test(scripts): 棘轮陈旧消息按实际成因分句,覆盖全部三条退休路径 (#3674)

[yinlianghui]

Fixes#3674

单文件、两个 commit,只动 the objectui#3647 baseline only shrinks 这一条断言的消息。stale 谓词与 expect(...).toEqual([]) 一字未动。

前提复核:成立,且比 issue 正文重一档 —— 是三条路径,不是两条

issue 点名的两条在 origin/main(切点 3e601773e,已含 PR #3687)上逐条命中:消息首行仍写死 A KNOWN_MISSING entry is stale — the path now resolves, so the defect is fixed.(:311),KNOWN_MISSING 已被 #3687 清空(:80)。

但复核 stale 的判据时量到第三条。stale = KNOWN_MISSING 的键不在 stillMissing 里,而 missing = declared.filter((d) => !d.onDisk && !isDeclaredBuildOutput(d)) —— 谓词里有两个过滤条件,issue 只追踪了 declared 那一侧:

#	一条基线条目离开 missing 的路径	路径 resolve 了吗	还在 files 里吗
1	文件被建出来(onDisk 转真)	✅ 是	是
2	声明被删,条目不再进入 declared	❌ 否	否
3	条目被 git-ignore 且其包有 build 脚本 → isDeclaredBuildOutput 转真	❌ 否	是

第 3 条是 issue 没有提到的:路径依然不存在、声明依然在,只是被豁免判据接管了。

这三条不是我编出来的分类 —— 同一个文件在 20 行之上已经把它们逐条列为「修复方向」了(存在性断言的消息,:290-294):

Fix it in whichever direction is true:
- the file should ship -> create it (that was the fix in PR #3662)
- the file is obsolete -> delete the entry from `files`
- it is build output -> git-ignore the path and give the package a `build` script,
which is how this guard recognises generated paths

三个被祝福的修法,一一对应三条退休路径。棘轮消息只描述了其中第一个。所以这不是「漏了一条」,是漏了三分之二,而正确答案本就写在同一个文件里。

取舍:成因可区分,故按实际成因分句(而非两因并列的中性表述)

派发单给了二选一:可区分则分句,不可区分则中性并列。实测可区分,且判据就在断言已经读的那份数据里 —— 对一条 stale 的 relPath,在 declared 里查一次即可:

• 查不到 → 第 2 条(没有任何 files 声明它)
• 查到且 onDisk → 第 1 条(路径存在了)
• 查到且不 onDisk → 只可能是第 3 条(被豁免判据接管)

因此选了分句。中性并列写法的代价是它把「读者本可以被直接告知的事实」降级成「读者需要自己去 ls 一遍才能确定的事实」—— 而读者去 ls 恰恰就是 #3674 记录的那个失败现场:路径不存在,于是怀疑门禁自己坏了。

新增的极小逻辑(派发单要求写明)

一个 causeOf(relPath) 纯函数,只在构造失败消息时调用:

constcauseOf=(relPath: string): string=>{constentry=declared.find((d)=>d.relPath===relPath);if(!entry)return'no `files` entry declares it: the declaration was deleted, its package left the workspace, or this baseline key never matched one';if(entry.onDisk)return'the path now exists on disk';return'still declared and still absent, but now excused as build output (git-ignored, untracked, package has a `build` script)';};

它从谓词读的同一份 declared / missing 数据里推导,不另建事实来源 —— 所以解释不可能与它所解释的判决漂移。这是刻意的:一份手写的成因说明会和谓词各走各的,正是本文件反对的形态(参见其对「白名单 vs 推导」的那段论证)。

第二个 commit:不宣称观察不到的历史

第 2 条最初写作「the files entry that declared it is gone」,自查时判为犯了本 PR 正要修的同一个错:谓词看到的事实只是「今天没有任何 files 条目声明它」,而这可能来自声明被删、包目录被删/改名/移出工作区,也可能来自这条基线键当初就拼错、从来没匹配过任何声明(键是手写字符串,完全可能)。说「is gone」是在断言一段它观察不到的历史。

故改为先陈述可观察事实(no \files` entry declares it`),再并列三种可能而不指定是哪一种。第 1、3 条本就是纯可观察表述,未动。

逆向验证:方向不是「红/绿翻转」,先说清楚

派发模板默认的「改前绿 / 改后红」在这里不成立,也不应该成立 —— 本 PR 不动谓词,红绿判决改前改后必须逐字节相同。若出现任何红绿差异,那才是缺陷(说明我不小心动了判断逻辑)。所以这里钉的是另一件事:同一组 fixture 下红绿不变,而归因从三分之一正确变为三分之三正确。

三条路径在 fixture 层各演一遍(共用起手式:给 plugin-tree 的 files 加一条 "NOTICE",并把 packages/plugin-tree/NOTICE 挂进 KNOWN_MISSING),外加一个 F0 对照组:

	扰动	预测(动手前写下)	实测
F0	只做起手式(条目已声明、缺席、已挂账)	5 绿 —— 条目在 missing 里,不 stale	Tests 5 passed (5) ✅
F1	建出 packages/plugin-tree/NOTICE	棘轮红;归因应为「路径存在了」	红 ✅
F2	从 files 删掉 "NOTICE"	棘轮红;归因应为「没有声明」	红 ✅
F3	把该路径写进 .gitignore(plugin-tree 有 vite build)	棘轮红;归因应为「被豁免为构建产物」。这条是 issue 未记载的第三路径,若它返绿则我的三路径主张被证伪	红 ✅,主张成立

四条预测全中,F0/F1/F2/F3 在改前改后红绿完全一致(F0 5 passed;F1/F2/F3 均 1 failed | 4 passed,失败的都是 the objectui#3647 baseline only shrinks)。

改前 —— 三条路径吐出逐字节相同的一句话

===== BEFORE F1 ===== / ===== BEFORE F2 ===== / ===== BEFORE F3 =====
AssertionError: A KNOWN_MISSING entry is stale — the path now resolves, so the defect is fixed.
Delete its line from KNOWN_MISSING in this file to bank the progress.
packages/plugin-tree/NOTICE (objectui#3674-fixture): expected [ 'packages/plugin-tree/NOTICE' ] to deeply equal []

F2 与 F3 下 packages/plugin-tree/NOTICE并没有 resolve —— 它依然不存在。F3 更刺眼:它连声明都还在。

改后 —— 同样三条路径,三句不同的归因

===== AFTER F1 =====
packages/plugin-tree/NOTICE (objectui#3674-fixture) — the path now exists on disk
===== AFTER F2 =====
packages/plugin-tree/NOTICE (objectui#3674-fixture) — no `files` entry declares it: the declaration was deleted, its package left the workspace, or this baseline key never matched one
===== AFTER F3 =====
packages/plugin-tree/NOTICE (objectui#3674-fixture) — still declared and still absent, but now excused as build output (git-ignored, untracked, package has a `build` script)

首行同时改为不再作因果宣称的 A KNOWN_MISSING entry no longer describes a live defect.,补救指令(删掉那一行)原样保留 —— 它在三条路径下都正确,这是 #3674 正文判定本条为观察类的依据,不应被改动。

fixture 全部还原(git checkout -- 定向还原 + rm 新建文件),git status 除本文件外干净。

门禁

pnpm exec vitest run scripts/__tests__/package-files-exist.test.ts → Test Files 1 passed / Tests 5 passed
pnpm exec vitest run scripts/__tests__/ --maxWorkers=2 → Test Files 18 passed (18) / Tests 339 passed (339)
pnpm type-check:scripts → exit 0
npx eslint scripts/__tests__/package-files-exist.test.ts → exit 0
node scripts/check-control-bytes.mjs → OK (scanned 3682 tracked text file(s); skipped 85 binary)
grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f]' 该文件 → 零命中
逐码点扫零宽/不可见字符(U+200B/U+FEFF/U+2028 等) → 0;全文件非 ASCII 字符仅一个破折号(本就在用)

scripts/__tests__/ 全量从 #3687 时的 17 文件 / 305 测试涨到 18 / 339,增量来自本 PR 之外的其它单,与本改动无关。

并行冲突面

与在途 #3696 同文件但文本无交叠:#3696 预计新增独立断言块,本 PR 只改 the objectui#3647 baseline only shrinks 内部的消息构造。本 PR 未新增/删除/重命名任何 it,KNOWN_MISSING(仍为空)与其上方文档注释一行未动 —— 那段注释是 #3687 写的历史记录,其「删声明与建文件同样使基线条目退休」一句在本 PR 之后依然为真,只是不再穷举全部路径;真正需要穷举的是失败消息,已就地解决,故不扩大文件面去改注释。

changeset:不加

纯测试文件、纯失败消息措辞,零生产代码、零发布产物、零运行时行为变化 —— 连 bug 修复都不是。与 #3667 / #3687 同判(AGENTS.md 第 151 行:功能改进需 changeset,本 PR 不属于)。

越界发现

无新开单。上文第 3 条路径不是独立缺陷,而是本单要修的那句消息所遗漏的成因之一,落在 #3674 的完成范围之内(该单主张「消息只覆盖了 stale 成因中的一条」,三条与两条只是同一主张的计数更正),故就地修完,未另立单。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 10:07pm