ci: validate decision document metadata - #309
Conversation
Signed-off-by: seekskyworld <djh1813553759@gmail.com>
tt-a1i
left a comment
tt-a1i
left a comment
There was a problem hiding this comment.
Review：Changes Requested
固定审查版本 bdcd6035ef346b9d090caa1a0d5946641df0bb24。
问题 / 价值 / 方法
在标准 check 中加入 Decision 元数据检查，让缺少状态、owner、关联信息的记录尽早失败。一个小脚本接入现有检查链的方向合理，不需要新治理框架。
Standards / Spec
规范轴没有发现需要额外抽象的设计问题。功能轴有 2 项 P2：Windows 下漏扫全部 Decision；逐行正则没有按 YAML 值语义判断必填字段。均见行内复现。
验证
本轮重新运行 bun run check：失败在新脚本第 51 行的 Biome 格式；线上 Node 22/24 CI 也为失败。请随修复一并格式化，并补上述校验器的回归测试。
只读内存探针执行实际脚本文本、注入 Node 的 path.win32/path.posix 与模拟文件系统：Windows 无 frontmatter 文档竟输出 docs contract (0 decision records) 且成功退出；POSIX 下 owner 为 ""、null、仅注释均成功退出；合法 related-issues YAML block list 被误报缺失。这是受控复现，不声称在原生 Windows 上运行过。
此前同一 exact head 的 lint/typecheck 通过；完整测试 Node 1065 通过、1 跳过，Vitest 30 通过。既有测试不覆盖上述新脚本缺口，全量绿色不能代替该功能验证。本轮未改代码、未合并。
| const files = markdownFiles(root); | ||
| const decisions = files.filter( | ||
| (file) => | ||
| file.includes(`${join("docs", "decisions")}${"/"}`) && |
There was a problem hiding this comment.
Windows 上 join("docs", "decisions") 返回反斜杠路径，这里又拼接 /，最终查找的是 docs\\decisions/；实际文件路径是 ...\\docs\\decisions\\0001-....md，不会匹配。使用实际脚本配合 path.win32 的只读探针，即使 Decision 完全没有 frontmatter，也成功输出 docs contract (0 decision records)。下一行 split("/") 同样是 POSIX 假设。
请从明确的 decisions 目录枚举，或统一使用原生路径组件和 basename；补一个 Windows 路径下必须发现记录并拒绝缺失元数据的测试，不能把零记录扫描当成验证成功。
| return new Map( | ||
| match[1] | ||
| .split("\n") | ||
| .map((line) => line.match(/^([\w-]+):\s*(.*)$/)) |
There was a problem hiding this comment.
当前 Map 保存的是未经解析的文本，所以 owner: ""、owner: null、owner: # no owner 都被第 51 行当成有值；反过来，合法的 related-issues:\n - "#198" 因首行值为空而被判缺失。对实际脚本的内存 fixture 复现了这四种情况。这会让必填信息遗漏漏过 gate，同时拒绝正常 YAML 写法。
请使用可靠的 YAML 解析并校验所需字段的非空值/允许类型，或者明确规定并严格校验受限格式；加上空字符串、null、注释和列表回归测试。保留当前小检查器即可，不必扩为通用文档框架。
Code Review SummaryChanges Requested：2 项 P2。 完整 review，固定版本
实际脚本文本的受控内存探针已复现；本轮 check 仍在新增脚本格式处失败，Node 22/24 CI 为红。建议修两个小边界、补回归并格式化，不增加框架。未改代码、未合并。 |
2 participants
Problem
Issue #198 established repository knowledge and evidence governance, but the standard check had no static guard for required Decision metadata. Missing fields would only be noticed during review.
Value
The check makes governed Decision records fail visibly when required status, ownership, review, and relationship metadata is absent, without treating prose or Benchmark claims as automatically validated.
Approach
scripts/check-docs-contract.mjswith data-driven recursive Decision discovery.check:docs-contractto the canonicalcheckscript.Validation
node scripts/check-docs-contract.mjs— passed (1 decision records).git diff --check— passed.npx --yes bun@1.3.14 run lint— passed.npx --yes bun@1.3.14 run typecheck— passed.Impact
Related to #198