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

在实施 #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