跳转至

RTL 审计证据架构

{
  "scope": "global",
  "triggers": {
    "testing": [
      "INV1",
      "INV2",
      "INV3",
      "INV4",
      "INV6",
      "INV9",
      "INV10",
      "INV12",
      "INV13",
      "INV14",
      "INV16"
    ]
  }
}

合同速览

领域 合同
治理合同 design:bidirectionality 负责定义什么是正确的 RTL 行为;组件合同负责局部语义、例外与验证。不改变任何产品合同;本记录负责证据的准入与新鲜度。
系统行为 当前名单中的每个组件都有明确归属;可用的范围内 story 会以 LTR 和 RTL 两种方向渲染。结果区分已测量、已验证 N/A、覆盖缺口和行为失败。Lint 与渲染审计证明的是不同主张。
对最终用户的影响 阅读 RTL 界面的用户受到真实观测到的镜像、顺序、位置、几何与行为证据的保护,而不是一份未测量任何内容的绿色报告。
对构建者的影响 新增或变更的组件必须要么由适用的检查进行测量,要么带有明确的缺口;行为失败没有允许清单。已验证 N/A 与既有债务的准入等待所有者决策(OQ1、OQ2)。
兼容性/就绪度 INV12–INV16 规定了 D1 fixture 元数据与稳定选择,以及 D5 图表-绘图声明(rtlAudit.D5),并非已交付的强制措施。组件级 N/A 准入、历史债务与必需检查的逐步推出仍未解决;D7 强制每个已配置原生目标的最低要求。
审查检查 拒绝以 lint 代替渲染证据(INV1);拒绝将行为失败重新标记为允许清单(INV3);拒绝将全部 N/A 视为 RTL 就绪(INV4);拒绝组件因其 story 移动而退出名单(INV5);拒绝没有红/绿变更凭证的新维度(INV9);拒绝针对方向性控件/线索的 D1 排除,或缺少面向审查披露的 D1 排除或 D5 图表声明(INV12、INV13、INV16)。
治理规则 不存在决定性系统规范;适用 architecture:knowledge-contracts 的证据新鲜度规则与人工决策规则。

此表是审查投影;下文正文具有权威性。

目的

Astryx 需要能够区分三种主张的审查证据:

  1. 组件的方向敏感行为确实经过了测量;
  2. RTL 确实不适用于该组件;或
  3. RTL 适用性仍是未测量的债务。

绿色 lint 规则、全 N/A 浏览器报告或已入库存档的例外,都不能被当作超出了其实际观测范围的证明。引用 fixture 的维度级不适用性,与组件级已验证 N/A 声明不同。前者描述单个 story 的语义;后者需要覆盖整个组件的证据。

全局 testing 路由在 RTL 测试、证据主张或豁免与变更相关时,提供共享证据与排除审查主张。它不提供组件行为或视觉意图:design:bidirectionality 拥有这些关系,组件/模块合同拥有局部状态及其验证映射。匹配此路由既不需要每个组件都实现审计运行器,也不会将工作流拓扑、未解决的 N/A/债务准入或门禁推出决策作为通用组件规则引入。审查仅在其所述证据范围内应用被路由的主张;草稿路由仍不具备权威性。

系统模型

changed component or full-library sweep
  → discover the live component roster across every registered component package
  → render relevant stories LTR and RTL
  → run automatic relationship checks
  → run curated component checks
  → combine results per component
       measured
       verified N/A
       unexplained coverage gap
       optional known debt (unresolved proposal)
  → report behavior failures, stale evidence, and applicability state

Lint 与渲染后审计是互补的:

  • lint 拒绝那些仅凭声明本身即可证明存在方向性失败的源码模式;
  • 浏览器检查验证计算后的几何、可见性、顺序、命中目标、滚动/拖拽行为以及组合变换;
  • 如果采信 verified-N/A 证据,它只能证明所审查的源码与 stories 当前没有暴露任何方向敏感的关系。

边界与不变量

  • INV1 — 证据随主张而定。 源码 lint MUST NOT 替代计算后的几何或交互。渲染截图 MUST NOT 替代键盘、拖拽、滚动或命中测试行为。浏览器关系检查 MUST NOT 声称每个组件状态都已被覆盖,除非其 stories 确实渲染了这些状态。
  • INV2 — RTL 按关系评分。 方向性证据对比同一构建产物中来自相同源码的 LTR 与 RTL 结果。像素一致不是约定;语义镜像、顺序、侧边、几何与行为才是。
  • INV3 — 行为失败没有允许列表。 当适用的自动或人工策展维度显示出错误的镜像、顺序、放置、几何或行为时,结果就是一个 finding。已知历史不会把错误的 RTL 行为变成通过或 N/A。
  • INV4 — 全 N/A 不是实测。 所有维度均为 N/A 的组件没有正面的 RTL 证据。它要么在已采信的证据策略下被验证为不适用,要么仍属于覆盖缺口/债务。
  • INV5 — 活跃源码清单拥有覆盖范围。 该清单包含每个注册为组件包的包中的所有公共组件,而不仅仅是 Core 和 Lab。组件不能仅仅因为没有 story 或其 story 标题变更就从审查中消失。当组件在范围内时,缺失可渲染性本身就是一种覆盖缺口。
  • INV6 — 自动与人工策展覆盖相互组合。 通用检查覆盖可广泛发现的图标、装饰和位置关系。组件专用选择器仅用于通用发现无法推断的语义,例如顺序、滚动方向、浮层侧边或触摸目标归属。
  • INV7 — PR 范围与完整清单范围回答不同的问题。 RTL 审计在合并到 main 后(一次推送突发会在最新提交处检查一次)以及每次发布前,以完整范围运行;拉取请求只有在带有 ci:run-rtl 标签(spec:AST-030 FR12, DEC-7)时才在受影响范围内运行该审计;否则,在默认的 touched-components 检查中,仅审计变更所触及的组件。当拉取请求带标签运行时,它检查受变更影响的组件;它可以按包运行,但 PR 结果是每个包范围的并集,缺少任何一个范围都不能通过。完整范围运行检查活跃清单和共享回归。两者不会静默地相互替代。
  • INV8 — 适用证据使 N/A 失效。 一个新的适用的自动或人工策展维度 MUST 使已有的 verified N/A 声明失效。基于源码与 story 字节的失效是提议的附加闭合要求,而不是当前仅记录原因的注册表所具备的能力。
  • INV9 — 证据变异证明门禁有效。 新的审计规则或维度 MUST 证明:相关缺陷在没有该规则时会被漏过,在应用该规则后能被检测到。仅靠通过的正常路径不足以证明强制有效性。
  • INV10 — 触摸目标证据包含尺寸与对齐。 对于粗指针目标,仅证明目标中心与可见控件一致是不够的。浏览器证据 MUST 还将有效/原生目标与所属组件声明的最小尺寸进行对比。D7 使用每个目标配置的最小值,在检查居中和命中测试的同时强制执行两个原生尺寸维度;它不分配通用最小值。
  • INV11 — 审计状态不是产品意图。 本架构负责证据的采信与时效性。正确双向行为的人类语义属于 design:bidirectionality;组件契约负责局部语义、例外与验证。
  • INV12 — fixture 适用性依循语义角色。 D1 图标镜像适用于用作方向控件或方向提示的图形。如果参考 fixture 将调用方提供的左/右字形几何作为数据显示,则可以声明 D1 不适用。仅凭字形外观并不能使该样例成为方向控件,而排除声明 MUST NOT 掩盖适用的行为失败。INV16 中的人工审查与披露要求适用于显式排除。
  • INV13 — Story 排除是有类型的、会被解析的,并且失败即关闭。 被采信的 story 元数据是 rtlAudit.D1,其中 applicable: false 且 reason 非空并解释 INV12;以及 rtlAudit.D5,其中 physical: 'chart' 且 within 绘图区选择器非空,用于声明一个叠加层保持物理方向的绘图区(design:bidirectionality DR5),而不关闭 D5。审计读取解析后的 Storybook 参数,包括常规的 story 覆盖 meta 的优先级。缺少已渲染的元数据、参数格式错误、不支持的维度键,以及没有理由的排除,MUST 产生错误,而不是静默跳过检查。空的已解析 rtlAudit 对象表示没有排除;该理由不是对整个组件的批准。
  • INV14 — D1 排除只影响 D1。 D5 和 D6 MUST 仍然扫描范围内的每个 story,包括被 D1 排除的参考 fixture。组件的其他 stories 仍然是 D1 候选。如果所有 D1 候选都被排除,D1 会报告 N/A,并附上被排除的 stories 和理由;这不是实测证据,不能消除组件覆盖缺口,也不能授予 verified N/A。
  • INV15 — D1 选择与完成身份是稳定的。 审计按 story 源码路径、源码导出顺序,然后是 story id 对候选排序,并选择第一个未被 D1 显式排除的候选。生成的索引插入顺序 MUST NOT 选择代表项。当另一个候选运行或所有候选都被排除时,计划身份保持不变;选中的 story 会被单独保留,以便报告说明实际运行的是哪个 story。包/分片的合并 MUST 核对精确的计划/完成身份,而不仅仅是数量相等。
  • INV16 — 刻意的 D1 豁免需经过审查且保持可见。 新增或扩大显式 D1 排除,或改变被排除 story 的语义角色,MUST 通过正常的拉取请求审查获得人工复核。新增一个继承 meta 级排除的 story,视为扩大该排除。审查者检查每个受影响的 story,包括继承 meta 级参数的 stories,并拒绝其图形充当方向控件或方向提示的排除。非空的理由只能证明元数据有效,不能证明不适用性有效。面向审查的审计输出 MUST 列出审计范围内每条已声明的 D1 排除,包括其规范组件、story id、维度和理由,并包含未被选为 D1 代表的 stories。rtlAudit.D5 物理区域声明接受同样的审查与披露:新增或扩大此类声明需被审查,输出会列出每条声明的组件、story id、类型和绘图区选择器。报告 MUST NOT 将缺少 D1 测量结果称为方向行为正确的证明。因未发现方向图标而自动产生的 N/A 不需要额外的人工批准;未变更的豁免不会在每次审计运行时被重新批准。本规则不承认组件级的 verified N/A 或历史覆盖债务。

变更耦合

对审计维度、组件发现、精选目标、适用性注册表、提议的证据哈希、工作流范围、摘要或 RTL lint 的变更都必须审查本记录。

新的方向敏感组件契约必须将其需求映射到可执行证据,否则保持为显式缺口。如果所有者承认已核实的 N/A 或具有字节边界闭合的已知技术债,实现 MUST 将该证据绑定到规范来源、直接拥有的辅助函数/样式以及自有 stories,从而使相关变更在过期时失败,而不是静默保留其旧分类。

组件级的 verified-N/A 准入、历史覆盖债务基线和必选检查推广,在所有者决定这些边界之前,仍不属于已敲定的主张范围。它们不阻止对维度级 fixture 策略进行主张范围内的批准。D1 排除项不暗示对这些更广泛状态作出任何决定。

审计维度

审计的 D 标识符命名的是仓库特定的检查项,而非外部国际化标准。自动发现覆盖 D1、D5 和 D6;其余维度由精选的 story 目标提供。

ID 观察到的关系
D1 方向性图标仅镜像或交换一次。
D2 上一个/下一个控件交换水平顺序。
D3 方向性交互或滚动行为跟随当前激活的方向。
D4 覆盖层或定位式功能提示跟随其逻辑侧。
D5 定位元素相对于其父元素镜像;在 story 声明的图表绘图区(rtlAudit.D5)内,它们保持物理位置(design:bidirectionality DR5)。
D6 上下文相关的方向性装饰恰好接受一次 bidi 处理。
D7 粗指针原生输入的尺寸、中心和命中测试满足所属目标契约。
D8 逻辑内联内边距解析为镜像后的物理边缘。
D9 分组的圆角跟随声明的逻辑内联侧。

D7 同时保留原生输入框和可见的包装框。其 minimumTargetSize 宽度和高度来自精选目标所属的组件/组合契约;缺失或无效的尺寸会产生错误。

所属代码

  • apps/storybook/rtl-audit/rtl-audit.mjs — 渲染并比较 LTR/RTL 行为。
  • apps/storybook/rtl-audit/rtl-audit-coverage.mjs — 发现实时名册,并合并已测量、N/A 和缺口状态。
  • scripts/component-packages.cjs — 组件包注册表,其公开组件构成该名册。
  • apps/storybook/rtl-audit/targets.json — 精选的 D2/D3/D4/D7/D8/D9 目标。
  • apps/storybook/rtl-audit/story-parameters.ts — 规划中的带类型 D1 fixture 适用性表面;基础实现中尚不存在。
  • apps/storybook/.storybook/preview.tsx — 规划中的已解析 story 元数据,位于现有 Storybook 根上;渲染的 story 周围没有包装器或兄弟元素。
  • apps/storybook/stories/SVGIconRegistry.stories.tsx — 参考字形数据;与 SVGIcon 所有者的关联及 D1 元数据有待 fixture 策略实现。
  • apps/storybook/rtl-audit/verified-not-applicable.json — 候选的 verified-N/A 注册表;其准入策略尚未解决(OQ1)。
  • 历史覆盖债务的准入问题尚未解决。本契约不包含任何额外的债务基线文件;缺失的测量结果仍是可见缺口。
  • .github/workflows/ci.yml — 受影响组件的 PR 审计,按组件包分片并合并为单个结果。
  • .github/scripts/rtl-join.mjs、rtl-report-completion.mjs 和 rtl-shard-scope.mjs — 精确的包/分片范围与完成度对账。
  • .github/scripts/rtl-scorecard-summary.mjs — 面向审查的记分卡投影;报告完整性和排除可见性仍然是要求,而非压制问题的权限。
  • .github/workflows/ci.yml 发布检查 — 每三小时以及每个工作日发布剪切之前,对 main 的最新提交执行全名册审计(spec:AST-030 DEC-19)。
  • internal/eslint-plugin-astryx/no-physical-properties.js — 可由源码证明的物理/逻辑声明约束。
  • design:bidirectionality — 人工产品意图,单独拥有。

已发布的 RTL 机制本身仍然缺少一个规范的架构所有者。后续的 architecture:bidirectional-layout 记录应负责 CSS 逻辑属性、rtlStyles、惰性 DOM 方向读取、居中辅助函数以及首帧绘制/水合不变量。本证据记录 MUST NOT 被视为那份缺失的实现契约。

决策规范

当前没有任何系统规范能够确定 verified-N/A 或已知技术债的准入。当前的知识架构要求证据保持新鲜并需要明确的人工决策;本记录将剩余的决策缩小为以下选项。

验证

| 不变量 | 证据 | 失败信号 | | INV1、INV2、INV6 | 聚焦的审计夹具,加上真实构建的 Storybook 变更 | 仅基于源码的规则声称渲染结果正确,或某个关系缺陷依然保持绿色 | | INV3 | 自动/人工筛选的失败测试以及 RTL 记分卡测试 | 某个已知的错误 RTL 结果被当作预期或 N/A 而不予报错 | | INV4、INV5 | 覆盖范围夹具,包含缺失/不适用(no-applicable)的 stories | 某个组件消失,或全部 N/A 被报告为 RTL 就绪 | | INV7 | PR 工作流范围测试和发布检查工作流测试 | 某个变更的组件被跳过,或全量清单债务被误认为仅限 PR 的证据 | | INV8 | 自动/人工筛选的适用性测试 | 某个新适用的维度使现有的已核实-N/A 声明仍然保持现状 | | INV9 | 每个新维度的红/绿变更(mutation)凭证 | 某个新维度只有通过的自证测试 | | INV10 | 原生宽度/高度变更夹具,以及 LTR/RTL、sm/md 下的 D7 中心/命中检查 | 尺寸过小的原生目标尽管包装容器几何结构符合要求,却依然保持绿色 | | INV12–INV16 | 候选夹具策略测试和构建后的 Storybook 变更;不由基础实现强制执行 | 对生成的 story 索引重新排序会改变 D1;格式错误/缺失的元数据被静默跳过;夹具选择退出会跳过 D5/D6 或关闭组件缺口;对方向性控件/提示的排除在语义审查中幸存,或从摘要中遗漏 | | D5 (DR5) | 定位配对评分以及 rtlAudit.D5 验证测试,加上真实构建的 Storybook 中已声明的 Recharts 主题 stories | 镜像的图表工具提示通过,未声明的浮层被评定为物理(physical)属性,或格式错误的 rtlAudit.D5 声明被接受 |

实现状态

基础审计实现了现有的自动/人工筛选检查以及组件 覆盖率汇总。INV12–INV16 定义了维度级夹具策略和稳定的 选择契约;其元数据传递和聚焦变更测试不属于 基础实现的一部分。它们需要单独的实现验证。 所有者可以在实现之前批准该预期契约,而不必 将其新检查视为已发布或已强制执行。根据 INV16 完善排除项摘要覆盖率仍然属于实现工作;仅靠一次通过的审计并不是 对新增或变更豁免项所需的人工审查。

候选证据状态

状态 最低证据 是否可为新组件/变更组件放行? 当前决策状态
已测量(Measured) 至少一个适用的关系或行为检查通过;所有适用的检查均通过 是 由当前审计行为决定
Verified N/A 今日:人工审核的理由;提议:source/helper/story 证据,并带 fail-closed 失效机制 未解决 需要所有者决策
Coverage gap 没有适用的测量,也没有被接纳的当前 N/A 证据 否 已解决
Known pre-existing debt 提议的仅移除基线条目,在未变更时保持可见且不失败 未解决 需要所有者决策
Behavior failure 适用的维度失败 否 已解决;无抑制
Stale evidence 今日:适用的维度出现;提议:记录的证据字节发生变化 否 部分实施

当前的强制执行缺口

  • 仅包含理由的 verified-N/A 注册表在自动化/人工维护的维度开始适用时会变得陈旧,但它尚未将证据绑定到 source/helper/story 字节。
  • CI 摘要代码中仍包含一个未使用的 knownNotRtl 标签路径,尽管报告不会输出此类允许列表。请移除它,以免实现被解读为允许已知的行为失败。
  • 组件/组合记录以及 AST-020 各自规定了 coarse-pointer 的最小目标尺寸。本审计记录不设定通用的像素最小值。

未决决策

OQ1 —— verified N/A 是否是被认可的完结状态?

  • 选项 A: 当一条声明带有特定理由时,接受 verified N/A。在该选项成为现行状态之前,需要在规范源代码、直接拥有的 helper/样式和拥有的 story 上补充证据,并加入 fail-closed 失效机制。这能识别真正与方向无关的组件,而无需制造无意义的浏览器测试。
  • 选项 B: 要求每个组件都有可执行的渲染测量。这取消了基于判断的 N/A,但会对没有方向性关系的组件强行加入人为检查。

OQ2 —— 既有且无法解释的全 N/A 是否可以进入仅移除的已知债务?

  • 选项 A: 将现有缺口快照为可见且不失败的债务,同时新的缺口、过期条目、行为失败,以及未变为已测量/N/A 的移除项继续失败。这样可以在不隐藏清单的情况下逐步推出。
  • 选项 B: 让每个无法解释的缺口都保持失败。这样更简单也更严格,但会使审计永久保持红色,直到完整的历史名单被测量或审查完毕。

OQ3 —— RTL 何时成为必需的合并检查?

当前的 PR 审计是软门控(soft-gated)的。在将其设为必需之前,所有者必须选择前置的干净状态和稳定性窗口。无论门控状态如何,报告必须保持真实,行为失败不得被重新标记。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx