ci-cd-pipeline.md 的 ci.yml job 表格漂移:写「Seven jobs」并列了一个不存在的 dev-server job(实际 6 个) #3451

现象

content/docs/guide/ci-cd-pipeline.md 描述 ci.yml 的那一节写道:

Seven jobs, all parallel — there are no needs: edges between them:

表格里第七行是:

| dev-server | Dev-server fixture build | pnpm --filter @object-ui/dev-server build — guards apps/dev-server's objectstack.config.ts against fixture / @objectstack/spec drift. | Every run |

但 ci.yml 里没有 dev-server 这个 job,实际只有 6 个:

$ python3 -c "import yaml; print(list(yaml.safe_load(open('.github/workflows/ci.yml'))['jobs'].keys()))"
['changeset-check', 'type-check', 'test', 'test-coverage', 'e2e', 'docs']

PR #3450 上跑出来的 checks 也印证了这一点(ci.yml 贡献的是 Changeset Fixed Group Check / Type Check / Test shard 1-4 / Test (coverage) / Build & E2E / Build Docs,没有任何 dev-server 条目)。

为什么值得记

这正是 #3197 / #3212 反复处理过的那类漂移 —— 「散文与 YAML 不同步」。而且方向是更危险的那一种:页面宣称存在一个并不存在的守卫。#3197 的测试注释本身就写过这个判断:

A doc that understates a gate is annoying; a doc that advertises a guardrail the CI does not have is worse than no doc, because people make size decisions believing something will stop them.

按这一页读,贡献者会以为 apps/dev-server 的 objectstack.config.ts 每次 CI 都有 fixture / spec 漂移守卫;实际没有。(是否应该有这个 job 是另一个问题 —— 可能是 job 被删了而文档没跟,也可能是文档先写了而 job 从未落地;需要查一下历史再决定是补文档还是补 job。)

现有测试为什么没拦住

scripts/__tests__/ci-cd-pipeline-doc.test.ts 钉的是:

• performance-budget.yml 的 MAX_ENTRY_GZIP_KB 与三档 advisory tiers;
• workflow 文件清单(每个 .github/workflows/*.yml 必须有对应标题,且页面提到的 *.yml 必须真实存在)。

它不校验 ci.yml 的 job 表格。所以 job 数量和 job 名称的漂移是这套 pin 的盲区。

建议

1. 先查清 dev-server job 是被删了还是从未存在,据此决定「删表格行」还是「补 job」。
2. 顺手把 Seven jobs 的字面数字改对(或改成不写死数字的表述)。
3. 可选、也是真正止血的一步:给 ci-cd-pipeline-doc.test.ts 加一条 job 表格的双向 pin —— 从 ci.yml 解析 jobs 的 key,与页面表格首列互相断言。这条如果早存在,本 issue 就不会发生;与该文件已有的「反向 pin」思路一致。

相关

• 由 pnpm docs:check-links 在 main 上就退出 1,但没有任何工作流跑它(两个链接检查器都不拦 PR) #3213 / docs: content/docs/core/enhanced-actions.mdx 指向不存在的 /docs/components/form #3292 的修复 PR(ci(docs): 把 check-doc-links 接进 CI,并修好它一直在报的那条坏链 (#3213, #3292) #3450)顺带发现;该 PR 只同步了自己改动涉及的 docs 行,未触碰这处既存漂移。
• 同源先例:Docs:ci-cd-pipeline.md 的 Performance Budget / Size Check 两节与实际工作流不符(预算数字差 5.8 倍、记录了一个不存在的工作流) #3197、Docs:ci-cd-pipeline.md 的工作流清单与 ci.yml 一节仍与实际不符(11 vs 12、两个工作流没被记录、五个任务名里三个不存在) #3212