ci-cd-pipeline.md 的 type-check 行漏了 `pnpm check:i18n-keys`,而 ci-cd-pipeline-doc.test.ts 的钉子按「作业」而非「步骤」判定,看不见这类漏项

[yinlianghui]

在实施 #3650(新增 i18n en 值漂移门禁)时发现,与该单验收项无关,单独立单。未在 PR 中修改 —— 越界。

现象

content/docs/guide/ci-cd-pipeline.md:69 的 type-check 作业行,「What it runs」一栏列的是:

scripts/check-type-check-coverage.mjs, then pnpm check:spec-symbols,
then pnpm type-check:scripts, then pnpm type-check, then pnpm type-check:vitest-setup

而 .github/workflows/ci.yml 的 type-check 作业实际还有一步,夹在 check:spec-symbols 与 type-check:scripts 之间:

# .github/workflows/ci.yml:103
- name: Verify t() call-site keys exist in the en locale pack
  run: pnpm check:i18n-keys

这一步是 #3530 / PR #3547 落的,当时没有同步该文档行。文档少报了一道会让构建失败的门禁。

为什么 pin 测试看不见

scripts/__tests__/ci-cd-pipeline-doc.test.ts 确实把这页钉在 ci.yml 上,而且钉得很细 —— 但判定粒度是「作业」:

• ciJobKeys() 解析 jobs: 下的作业键,双向比对文档的 job 表(缺一行、多一行都红);
• ciJobNames() 比对每个作业的 name:;
• 另有一组把 .github/workflows/*.yml 每个文件钉到文档的一个小节。

没有任何一条读「一个作业里跑了哪些步骤」。 所以往既有作业里加一个 run: 步骤,文档那一栏不跟改,全套钉子照绿 —— 这正是本条能潜伏至今的原因。

该测试头注自陈的立意是「a doc that advertises a guardrail the CI does not have is worse than no doc」(#3451,dev-server 行在作业删除后又活了三个月)。反方向(文档少报)它明确写了「annoying」而非危险,所以这条按 observation-class 记,不自评严重度,交分诊裁。

影响面

无用户可见影响,纯文档/贡献者体验:照该页判断「type-check 作业会跑什么」的人会漏掉一道真实门禁。

顺带说明:#3650 会让这一栏再少报一步

PR(#3650)在同一作业里紧邻 check:i18n-keys 之后新增一步:

- name: Verify changed en strings were followed by the nine translations
  run: pnpm check:i18n-drift

该 PR 有意未改这一栏 —— 派发口径的文件面不含 content/docs/,且要把这行改对必须连带补上 #3547 那一步(不是本单欠的账)。修本单时两步一起补即可。

修法建议(两选一,建议都做)

1. 最小事实订正:该行补上 pnpm check:i18n-keys 与 pnpm check:i18n-drift,顺序按 ci.yml 实际。
2. 把钉子下沉一级(可选,值不值得请分诊裁):在 ci-cd-pipeline-doc.test.ts 里增一条按步骤判定的断言 —— 从 ci.yml 每个作业抽出 run: 里的 pnpm <script> 名,要求文档对应行都提到。代价是文档行必须逐字跟 CI 走;收益是这一类漏项从「靠人看」变成机械可判。注意 run: 里也有非 pnpm 命令(node scripts/...、corepack enable),抽取规则要先量再定。

关联:#3530 / PR #3547(漏记的那一步的来源)、#3650(新增的那一步)、#3197 / #3451(这页与它的 pin 测试的立意与前情)。

---

Generated by Claude Code

[yinlianghui]

认领(PM 派发)。

• Session: session_01GTRjn8xBqp75dk7kFupVRt
• 分支:claude/issue-3653-cicd-doc-steps
• 文件面:content/docs/guide/ci-cd-pipeline.md(type-check 作业行补 check:i18n-keys 与 check:i18n-drift 两步 — feat(ci): assert every t() call-site key exists in the en locale pack #3547 与 i18n 门禁:en 文案变更时其余九包必须同批跟改(或显式挂账)——#3582/#3625 族缺陷缺的那道不变量 #3650/PR feat(scripts): en 文案改动必须由九个译文包同批跟改的门禁 (#3650) #3659 各欠一步,两账并清)+ scripts/__tests__/ci-cd-pipeline-doc.test.ts(粒度升级)。前置已落:PR feat(scripts): en 文案改动必须由九个译文包同批跟改的门禁 (#3650) #3659 已在 main(880e069)。
• 裁决:文档钉粒度从「作业级」升到步骤级(issue 点名的空档:往既有作业加 run: 步骤而不改文档,全套钉子照绿)— 实现形态由你测量该测试现有结构后定(最小正确形态即可:如逐作业断言其 run 步骤集合与文档表格一致);⚠️ 若步骤级钉需重写整个测试文件,停手报告,先只补文档两步 + 钉住这两步的存在。
• 措辞遵 docs(scripts): 按真实机制改写两处 Lychee 门禁描述,并删掉 judgeHref 重复注释 (#3587) (#3648) #3656 规矩(不复植失真特征词)。

---

Generated by Claude Code

[yinlianghui]

验收 ACCEPT → PR #3683(session_01GTRjn8xBqp75dk7kFupVRt)。

已核:CI 16 项全 success;六作业步骤全审计(漏报恰 type-check 两条,反方向全零);六条逆向验证方向全中,全部在 fixture 树上做(真 ci.yml 零改动)且 baseline 副本同数证明 harness 未被做手脚 — RV-3(旧钉对旧文档+今日 ci.yml 全绿)是 issue 前提的机械证明。

裁决记录:

1. 边界从 package.json 推导(第一方命令 = scripts/*.mjs + 根 script + turbo 任务,corepack/install/playwright 自动落面外无需豁免条目)— 与 test(scripts): 补门禁——package.json files 声明的条目必须在磁盘真实存在 (#3663) #3667 git 推导豁免同宗,记入方法库。
2. 不加冗余存在钉的取舍确认采纳:两个门禁测试已各自钉住存在性,本块只钉 YAML↔文档配对 — 一个缺陷一处报,分工写头注,对。
3. 内联 shell 块盲区写头注不当覆盖面,诚实。
4. 粒度升级零重写(docJobRows 加列 + 嵌套 describe),停手条款未触发。

#3547/#3650 两笔文档欠账并清,步骤级钉封死「加步不改文档照绿」空档。

---

Generated by Claude Code