scripts-type-check.test.ts 的 workspace-import 检查按文本 grep,注释里的 import 示例会被判成真 import 并给出错误的修复指引

[yinlianghui]

发现于 #3943 的实现(PR 见下),不在该 PR 处理 —— 那一单的面是 sideEffects 一致性门。这一条是另一个门的判定精度问题。

机制

scripts/__tests__/scripts-type-check.test.ts 的最后一条断言(does not need a workspace build, so it can stay in the cheap half of the job)这样判定「scripts 程序是否 import 了 workspace 包」:

const workspaceImports = parsedProject()
 .fileNames.flatMap((f) => [...fs.readFileSync(f, 'utf8').matchAll(/from\s+'(@object-ui\/[^']+)'/g)])
 .map((m) => m[1]);

读的是文件文本,不是 TS AST。于是任何位置只要出现 from + 空白 + 引号包住的 @object-ui/* 字面量就算命中 —— 包括注释、JSDoc @example、以及讲解用的代码片段。\s 匹配换行,所以跨行的散文也能凑出这个形状。

实测

在 scripts/__tests__/check-package-self-import.test.ts 里写下一行注释(内容是在解释「注释里的包名不是 import 边」这件事本身):

// rewrite of this gate breaks on a documented `import … from '@object-ui/core'`

该断言即变红:

- []
+ [ "@object-ui/core" ]
 ❯ scripts/__tests__/scripts-type-check.test.ts:213:7

为什么值得记一笔:失败信息把人指向不存在的东西

红的本身是「安全方向」(宁可误报不可漏报),真正的成本在诊断词:

tsconfig.scripts.json’s program now imports workspace packages, so it needs their built
declaration files. Move the ci.yml step below the build, or drop the import.

而现场根本没有 import,没有 import 可 drop,也没有任何 .d.ts 需求。读到这条的人会去找一条不存在的 import,或者更糟 —— 真的去动 ci.yml 的步骤顺序,把一个廉价步骤挪到 build 之后,而它的前提其实从未被破坏。误报本身廉价,误报 + 错误的修复指引才是这条的内容。

同一个仓里已经有过这个教训的反面:examples/console-starter/vite.config.ts:50 专门写了一段注释说明它故意不在注释里拼出带引号的 specifier,因为「那个诱饵已经骗过一次扫描」。

可能的处置(供分诊,未实施)

按代价从低到高:

1. 只改诊断词 —— 承认判据是文本匹配,让信息同时给出两个方向:「这是真 import → 移动 ci.yml 步骤 / 删掉它;这是注释或示例 → 改写措辞,别在 scripts/ 里拼出带引号的 specifier」。最小、不改判据,消除误导。
2. 剥掉注释再匹配 —— 与 vitest-config-alias-targets-3944.test.ts 的 withoutCommentLines() 同形状(该文件已因同类原因这么做)。能挡掉整行注释,挡不掉行尾注释与跨行散文。
3. 改用 AST —— parsedProject() 已经产出 fileNames,拿 ts.createSourceFile 遍历 ImportDeclaration/ExportDeclaration 的 moduleSpecifier 即精确判定,顺带覆盖 import type 与 export … from。判据从「像不像」变成「是不是」。

倾向 3(判据与被判定的事实对齐),但 1 单独就能消掉误导,且可独立落地。

退出条件

• 上述任一处置落地(诊断词至少要不再指向不存在的 import);或
• 判据改为 AST 后本条自动关闭。

参考位置:scripts/__tests__/scripts-type-check.test.ts:205-214、scripts/__tests__/vitest-config-alias-targets-3944.test.ts(withoutCommentLines() 先例)、examples/console-starter/vite.config.ts:50(同类诱饵的现场注释)。

[yinlianghui]

第二实例:column-identity.ratchet.test.ts 同样把注释当代码

本条的盲区不是单个门的判定精度问题,而是文本级门家族的共性 —— 今天在 #3951(PR #4909)上又撞了一次,机制完全同形,只是换了一个门。

现场

PR #4909 把 grid 列的键收敛到声明拼写 name(修 reader,不加容忍别名)。为了让下一个读代码的人别把别名加回来,我在 packages/fields/src/widgets/GridField.tsx 的 GridColumn.name 上写了一句注释,内容是声明「这里故意没有这个别名」。CI 20 个 job 里 19 绿,唯一红的是 Test (shard 2/4):

column-identity.ratchet.test.ts > finds no dual read in a file the inventory does not list
+ "fields/src/widgets/GridField.tsx:51 :: * There is deliberately NO `col.field ?? col.name` alias: one spelling, at"

也就是说:一句声明「不存在双读」的注释,被判成了新增双读。 棘轮读数 11 → 12。行为面零缺陷 —— 该文件里没有任何一处 alternation 读列身份,整个 PR 做的恰恰是把双拼写收敛成单拼写。

与本卡的同形之处

column-identity.ratchet.test.ts:194-215 的判据是逐行文本:

src.split('\n').forEach((line, i) => {
 if (!ALTERNATION.test(line)) return; // 行内有 || 或 ??
 const keys = [...line.matchAll(ACCESS)]; // 行内的 .field / .name / .fieldName 等属性访问
 if (distinct.size < 2) return; // 两个以上不同身份键 → 记为一处双读

collectSourceFiles() 已经排除了 node_modules / dist / __tests__ / *.test.tsx / *.d.ts,但没有剥注释,所以判据对「这一行是代码还是散文」完全不设防 —— 与本卡 scripts-type-check.test.ts 用 /from\s+'(@object-ui\/[^']+)'/ 扫文件文本是同一件事。

值得注意的是,这个门自己知道判据是启发式的(文件头写着「The scanner is a line-level heuristic, not a parser」),也正因如此它带了 verdict / why 的 inventory 来做人工分诊。但盲区在于:被误判的一方如果是注释,inventory 机制反而会把人引向错误修法 —— 把 GridField.tsx 加进 inventory 列表,等于在一份「双读清单」上登记一处根本不存在的双读,污染的正是这份清单的可信度。本卡记的「误报 + 错误的修复指引」在这里的具体形态是:正确修法(改注释措辞)和错误修法(加白名单)对读到失败信息的人来说难以区分,而错误修法留下的痕迹是永久的。

处置(#4909 内)

按 PM 指示只改措辞,不动 inventory:把该句改写成不含 alternation 形状的散文(「no tolerant alias bridging the retired spelling to this one」),并在注释里留了一行说明「不要把这条规则重新写成两个键名之间的 alternation 表达式,本仓的棘轮逐行扫描且分不清散文与代码」。本地复跑读数回到基线 11。

对本 finding 作用域的影响

原卡的三档处置(改诊断词 / 剥注释 / 换 AST)是针对 scripts-type-check.test.ts 一个门写的。有了第二实例,建议把作用域从「修这个门」提升为「盘点文本级门家族」:

• 本仓已知同族:scripts/__tests__/scripts-type-check.test.ts(本卡)、packages/core/src/utils/__tests__/column-identity.ratchet.test.ts(本评论)。
• 已知做对了的先例有两处,可作为处置模板:scripts/__tests__/vitest-config-alias-targets-3944.test.ts 的 withoutCommentLines(),以及 examples/console-starter/vite.config.ts:50 那段「故意不在注释里拼出诱饵」的现场说明。
• 两个实例都指向同一条结论:凡是「禁止某个代码形状」的文本级门,都会把讲解该形状的注释判成违例 —— 而讲解它的注释恰恰最可能出现在刚刚修掉它的那个 PR 里(fix(fields): grid columns 收敛到声明拼写 name,spec 合规元数据不再渲染空单元格 (#3951) #4909 就是这样:修掉双读的那次提交,因为写下「这里没有双读」而被双读门拦住)。这使得该家族的误报系统性地集中在正确修法上,不是随机噪声。

因此建议:处置 2/3 至少要覆盖这两个门;若采用 3(AST),column-identity.ratchet.test.ts 因为要判的是表达式形状而非 import 边,成本高于本卡的 import 判定,处置 2(先剥注释行)对它的性价比更高。

---

Generated by Claude Code

[os-support-ai]

Triage (concentrated finding round): promoted finding → pm:queue, with the widened scope the 2026-08-17 comment established: this is the text-level gate family, not one gate. Scope = both known members (scripts-type-check.test.ts workspace-import check; column-identity.ratchet.test.ts), using the two in-repo precedents as templates. Route suggestion per the evidence on this thread: AST for the import check (disposition 3 — parsedProject() already yields the file list), comment-line stripping for the column-identity ratchet (disposition 2 — expression-shape AST is poor value there), and in both cases fix the failure message so the wrong repair (whitelist/inventory pollution) stops being indistinguishable from the right one.

本评论来自分诊座位 Routine (session session_018euHiF12oV8iSfYdjVioUF).

---

Generated by Claude Code