fix(scripts): check-i18n-en-drift 的显式 base 提为权威,解析不出即失败 (#3766)

[yinlianghui]

Fixes #3766

问题

scripts/check-i18n-en-drift.mjs 的 resolveBaseRef 把显式指定的基准(--base、OS_I18N_DRIFT_BASE)仅当作候选链的第一环。解析不出时它不失败,而是继续往下猜,拿 merge-base with origin/main 之类的另一个提交当基准把比对做完,并打印一行自信的绿灯 —— 摘要行里的 (--base …) 也被换成了实际用的那一环,读日志的人看不出自己指的基准被忽略了。

「你指的 base 在这个 clone 里不存在」和「你没指 base」是两件不同的事,只有后者可以靠猜回答。

修法

显式来源提为权威:给出即只查它,解析不出直接返回 { ok: false, named: true },并给一条针对性提示(你指的 base 在这个 clone 里不存在),而不是原来那句会把人带偏的「去 fetch base 分支」。

形状是仓内先例 scripts/check-changeset-presence.mjs:209 的直移植 —— 同族缺陷先在那里被它自己的测试抓到(#3762),两个 resolveBaseRef 现在又是同一形状。该文件里那句「sibling 仍是跌落形状,另行开单」的注释随之更正。

resolveBaseRef 另补了 JSDoc @param:没有它,explicit 会被 TS 从默认值 null 推成 null | undefined,任何传显式 base 的测试都过不了 pnpm type-check:scripts(先例文件的测试从不传 explicit,所以那边没暴露)。这是在生产者声明契约,而不是在测试里加 cast。

修好前后 exit 对照(本仓真实实测)

缺陷版(= 改动前的形状),显式给一个本 clone 里不存在的 sha:

$ node scripts/check-i18n-en-drift.mjs --base 0123456789abcdef0123456789abcdef01234567
Compared the ten locale packs at 5147d9305 (merge-base with origin/main) with the working tree: 0 en value(s) changed ...
No en value changed in this range.
exit=0                     # 请求的 sha 被无声换掉,报绿

修好后,同一条命令:

$ node scripts/check-i18n-en-drift.mjs --base 0123456789abcdef0123456789abcdef01234567
Cannot resolve the commit to compare against, so there is nothing to diff.
  tried: --base 0123456789abcdef0123456789abcdef01234567 (unresolved)
  That base was named EXPLICITLY, so it is not guessed around: comparing the packs
  against some other commit instead would answer a question nobody asked, and
  answer it confidently. Name a commit that exists in this clone, or pass none and
  let the merge base with the target branch be found.
  This is a failure, not a skip: a diff gate with no diff would pass while
  checking nothing. See the header of scripts/check-i18n-en-drift.mjs.
exit=1

另一个显式入口 OS_I18N_DRIFT_BASE 同权威、同失败:

$ OS_I18N_DRIFT_BASE=0123456789abcdef0123456789abcdef01234567 node scripts/check-i18n-en-drift.mjs
  tried: OS_I18N_DRIFT_BASE=0123456789abcdef0123456789abcdef01234567 (unresolved)
  ... named EXPLICITLY ...
exit=1

候选链不变的证明

只有「你指了但解析不出」这一情形从猜测变失败;没指定显式 base 时的发现链完全不变。CI 的 pnpm check:i18n-drift 不传 --base,走的正是这条路径。

1. 无参实跑(= CI 走的路径),行为与改动前逐字一致:

$ node scripts/check-i18n-en-drift.mjs
Compared the ten locale packs at 5147d9305 (merge-base with origin/main) with the working tree: 0 en value(s) changed ...
exit=0

2. 显式给一个存在的 sha,正常比对,并且摘要行现在诚实地报 (--base …) 而不是替换成别的候选:

$ node scripts/check-i18n-en-drift.mjs --base 5147d9305c0275290f215abe35a6bbf4e80bbdc3
Compared the ten locale packs at 5147d9305 (--base 5147d9305c0275290f215abe35a6bbf4e80bbdc3) with the working tree: ...
exit=0

3. 新增用例直接钉链路完整(keeps guessing through the whole chain when NO base was named):无显式 base 时,GITHUB_BASE_REF 指向本 clone 没有的分支 -> 继续跌落到 merge-base with origin/main;在完全没有 origin 的 clone 里 -> 跌落到链尾的本地 main。链首链尾都测到,不是只测了链首。

4. 原有的 prefers the merge base with the PR base branch when CI names one 与 fails loudly rather than passing when there is no base to diff 两条未改动,仍绿。

5. 两个 workflow 里描述 base 解析的注释(ci.yml 的 fetch-depth: 0、changeset-presence.yml 关于 merge_group 跌落到 origin/main)描述的都是发现链,未受影响,无需改动 —— 已逐条核对。

反向验证(方向先判后跑)

预判:恢复跌落写法后,新用例应当红,且门禁 exit 0 并打印那句绿灯 —— 因为 fixture 仓里 merge-base with main 解析得到 HEAD,与工作树同内容,0 个 en 变更。跑出来正是如此:

❯ scripts/__tests__/check-i18n-en-drift.test.ts (37 tests | 2 failed | 30 skipped)
  × FAILS on an explicitly named --base that does not exist — it does NOT fall back
      Error: the gate exited 0 where a failure was expected
  × consults NOTHING but the named base — not even a candidate that would resolve
      AssertionError: expected true to be false   // outcome.ok

修好后同两条绿。这与 check-changeset-presence.test.ts 用例注释里记录的方向(exit 0 -> 1)一致。

新增用例

落在 scripts/__tests__/check-i18n-en-drift.test.ts 既有的 resolving the commit to compare against 块里,沿用本文件的形态(throwaway git 仓 + 真跑 CLI 钉 exit code):

• FAILS on an explicitly named --base that does not exist — it does NOT fall back —— 真跑 CLI,断言 exit 1、(unresolved)、named EXPLICITLY,并显式断言不含它过去产生的那句绿灯。
• FAILS the same way on an OS_I18N_DRIFT_BASE that does not exist —— 另一个显式入口。为此给 runGate 加了可选的 envOverrides(其余用例仍照旧清空这两个 env var)。
• consults NOTHING but the named base — not even a candidate that would resolve —— 直接钉机理:tried 只有一条。此仓同时备好了 GITHUB_BASE_REF=main 和真实的 origin/main,发现候选本来能解析出基准,所以单条 tried 就是「它根本没被问」的证据。
• still resolves a named base that DOES exist, and --base outranks the env var —— 权威不等于总是失败:好 sha 照常解析,--base 优先于 env var。
• keeps guessing through the whole chain when NO base was named —— 上面「候选链不变」的第 3 条。

验证

$ pnpm vitest run scripts/__tests__/check-i18n-en-drift.test.ts scripts/__tests__/check-changeset-presence.test.ts --maxWorkers=2
 Test Files  2 passed (2)
      Tests  68 passed (68)

$ pnpm vitest run scripts/__tests__/scripts-type-check.test.ts scripts/__tests__/ci-cd-pipeline-doc.test.ts scripts/__tests__/check-control-bytes.test.ts --maxWorkers=2
 Test Files  3 passed (3)
      Tests  62 passed (62)

$ pnpm type-check:scripts
exit=0

$ node scripts/check-control-bytes.mjs
✅  check-control-bytes: OK (scanned 3735 tracked text file(s); skipped 85 binary).

改动三个文件另跑了一次控制字节自查(grep -naP 覆盖闸门不扫的 0x01-0x1f),零命中。

Changeset

不带。node scripts/check-changeset-presence.mjs 实跑结论:3 file(s) changed, 0 of them under the src/ of a package the release covers -> No source of a released package changed in this range, so no changeset is owed. —— scripts/** 在发版包守卫面外,与 #3273 / #3784 先例一致。门禁本身也不是用户可见的运行时行为。

影响面

今天的 CI 路径不受影响(不传 --base,走 GITHUB_BASE_REF 那一环)。受影响的是该脚本对外声明支持的两个显式入口 —— 复现历史提交、跨 worktree 比对、以及该门禁自身测试所用的入口:它们从「静默拿错基准报绿」变成「明确失败并说清原因」。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 8, 2026 5:46pm

[yinlianghui]

✅ 验收通过(objectui 分片 PM,session_01GTRjn8xBqp75dk7kFupVRt)—— undraft + auto-merge。

核验:净 diff 3 文件;named base 权威形状按 check-changeset-presence.mjs:209 先例移植({ok:false, named:true} + 针对性提示),发现链(GITHUB_BASE_REF → origin/main → main)逐字不变且链首链尾各有钉子防「只测链首、链尾静默失效」的空绿;CLI 矩阵含缺陷版同命令对照(静默换基准报绿被复现成证据);反向验证 2 红命中预判。超出正文的必要发现处置正确:先例移植后 type-check:scripts 红 3 处 TS2322(先例文件测试从不传 explicit 故从未暴露)—— 按契约优先在生产者补 JSDoc @param 而非测试侧 cast,顺带更正了 sibling 注释里因本单而失效的一句。17 项 CI 全部完成 0 失败;changeset 按实跑判定不带,同 #3273/#3784 先例;trailer 自查零命中(新硬规首单执行)。

---

Generated by Claude Code