fix(infra): assert alias coverage and harden the generator entry guard

Review found the CLI entry guard compared import.meta.url against a concatenated file:// URL. That fails whenever import.meta.url encodes something process.argv[1] does not — a repository path containing a space, or any Windows drive path — and it fails silently: the script exits 0 having done nothing, so verify-tsconfig-paths would pass without checking exactly where it is needed. Running a copy from a directory whose name contains a space reproduces it. The guard now uses the comparison the repository's seven other generators already use. Deleting the group wildcards also removed the fallback that resolved a package nobody had aliased, so the generator now asserts coverage: every workspace package with a src directory must be mapped, and --check names any that is not. That assertion immediately found four packages named dsh-<group>-<directory> whose siblings carry hand-written aliases while they did not, so they reached built lib/ output through the workspace symlink. They now carry aliases too, which takes the resolution differences in this branch from seven to eleven. Two comments in tsconfig.base.json still pointed at the deleted wildcards; they now state why those aliases stay hand-written. The package-inventory proposal recorded the wildcard collapse as current, so both notes are cross-linked as partial supersession.
2026-08-29 04:26:38 +00:00 · 2026-08-27 19:39:21 +08:00
parent 12c161e1a7
commit c4c3c32931
9 changed files with 139 additions and 21 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-27-explicit-workspace-path-aliases.md
-2026-08-27-explicit-workspace-path-aliases.md: 4cd97062fa56b5b8730101e81d20b33b206ea670
-2026-08-27-explicit-workspace-path-aliases.zh.md: 003f04077837b055a50996edb49cdc25ccd8f73a
+2026-08-27-explicit-workspace-path-aliases.md: 51d2dee7911d323637121f509e160ef92c352568
+2026-08-27-explicit-workspace-path-aliases.zh.md: 702d3d7a8cf91c8c307b1708fc30faad6cab009a
@@ -18,24 +18,32 @@ The cost fell hardest on the most-imported packages. `packages/util/*` sat at po

 The generator emits an alias only for a package whose declared name is exactly `@deepseek-ai/dsh-<directory>`, because that is the only shape a wildcard could ever have resolved: it substituted the specifier's suffix into `packages/<group>/<suffix>/src`. Packages named after something other than their directory — `@deepseek-ai/dsh-typert-protocol` at `packages/typert/protocol`, the `dsh-client-*` and `dsh-host-*` families — already carry hand-written aliases and are left alone. A specifier claimed by two package directories throws rather than picking one, because an explicit map cannot express the group-order tiebreak the wildcard used; no such collision exists today.

+Deleting the wildcards removed the fallback that used to resolve a package nobody had aliased, so the generator also asserts coverage: every workspace package carrying a `src` directory must be mapped by a generated or hand-written alias, and `--check` names any that is not. Without it a package whose name does not match its directory could be added, skipped by the generator, and left resolving through the workspace symlink to built `lib/` output — the same artifact-plane leak the explicit aliases exist to close.
+
 The region is written by text surgery between marker comments rather than by re-serializing the file. `tsconfig.base.json` is JSONC and its hand-written aliases carry comments that explain non-obvious mappings; re-serializing would drop them.

+This partly supersedes the [package-inventory discovery proposal](../../proposed/process/2026-06-20-discover-package-inventory.md), which records the collapse into one wildcard as current: the wildcard is gone, while that proposal's remaining subject — the aggregate configs' explicit `references` arrays — is untouched here.
+
 Four wildcards remain, each with a single candidate: `dsh-host-*/invariant`, `dsh-client-*/invariant`, `dsh-client-*/client`, and the five `dsh-host-<name>/*` subpath maps. One candidate costs one probe, so expanding them would trade file size for nothing.

 ## Resolution differences this change makes

-Every `@deepseek-ai/dsh-*` specifier appearing in repository sources — 1,022 distinct — resolves to the same target as before, with seven exceptions that now resolve where they previously did not:
+Every `@deepseek-ai/dsh-*` specifier appearing in repository sources — 1,023 distinct — resolves to the same target as before, with eleven exceptions that now resolve where they previously did not. All eleven previously reached built `lib/` output through the workspace symlink rather than source.

-`dsh-invariants/invariant`, `dsh-lsp/invariant`, `dsh-lsp-stdio/invariant`, `dsh-tool-lsp/invariant`, `dsh-terminal/invariant`, `dsh-terminal-bash/invariant`, and `dsh-tool-terminal/invariant`.
+Seven are `/invariant` subpaths: `dsh-invariants/invariant`, `dsh-lsp/invariant`, `dsh-lsp-stdio/invariant`, `dsh-tool-lsp/invariant`, `dsh-terminal/invariant`, `dsh-terminal-bash/invariant`, and `dsh-tool-terminal/invariant`.

 The deleted `dsh-*/invariant` wildcard omitted the `lsp`, `terminal`, `client`, and `host` groups. The `client` and `host` omissions are deliberate and documented — those families have dedicated wildcards because their package names prefix the group directory. The `lsp` and `terminal` omissions have no such reason, and `packages/runtime-diagnostics/invariants` appeared in neither list. Those seven specifiers therefore resolved through the workspace symlink and the package's `./invariant` export to built `lib/types/*.d.ts` instead of to source, which contradicts the rule that static gates resolve workspace imports through `paths` to `src` and pass on a clean tree. Making the aliases uniform resolves them to source like every sibling.

+The other four are whole packages the coverage assertion surfaced: `dsh-client-ui-directory-picker-browse`, `dsh-client-ui-directory-picker-native`, `dsh-experimental-agent-team-profile`, and `dsh-experimental-agent-team-web-profile`. Each is named `dsh-<group>-<directory>`, which no wildcard could ever substitute, and each sits beside siblings that do carry hand-written aliases — they were simply missing. They now carry one too.
+
 ## Testing

-`scripts/gen-tsconfig-paths.spec.ts` pins that the collector maps a package to its own directory, skips packages carrying hand-written aliases, and returns a sorted list; that the renderer yields to a hand-written specifier and closes the region without a trailing comma; that the region writer replaces only the marked span and refuses a config without markers; and that neither group wildcard survives in the committed config.
+`scripts/gen-tsconfig-paths.spec.ts` pins that the collector maps a package to its own directory, skips packages carrying hand-written aliases, and returns a sorted list; that the renderer yields to a hand-written specifier and closes the region without a trailing comma; that the region writer replaces only the marked span and refuses a config without markers; and that neither group wildcard survives in the committed config. Two further cases pin the coverage assertion: it names an unmapped package, and it reports none against the committed config.

 The gate's rejection path is exercised directly: deleting one generated alias makes `verify-tsconfig-paths` exit non-zero, and restoring it makes the check pass.

+The CLI entry guard uses the repository's established comparison, `import.meta.filename === resolve(process.argv[1])`, rather than concatenating a `file://` URL. The concatenated form fails whenever `import.meta.url` percent-encodes something `process.argv[1]` does not — a repository path containing a space, or any Windows drive path — and the failure is silent: the script exits 0 having done nothing, which would make the gate a no-op exactly where it is needed. Running a copy from a directory whose name contains a space reproduces that: the concatenated guard evaluates false, the established one true.
+
 ## Alternatives considered

 **Reordering the wildcard's candidate globs so the hottest groups come first.** This needs no generator and no new gate, and recovers perhaps half the cost by moving `util`, `core`, `llm`, and `session` to the front. It was rejected because the win decays as packages are added, the ordering has no invariant a reader could check, and every group after the first still pays. It also leaves the worst property intact: adding a package group silently slows every boot.
@@ -50,4 +58,4 @@ A source-launch boot of the `headless` profile drops from a 2,157/2,182/2,153 ms

 The win is confined to the tsx source launch. Vitest resolves through `vite-tsconfig-paths`, which matches in-process and checks file existence without ever constructing a Node module error, so it never paid the decoration cost: an A/B over one package's suite measured 5,934/5,829/5,908 ms against 5,878/5,851/5,905 ms, which is noise. Repository gate scripts import few `@deepseek-ai/dsh-*` packages and likewise show no separable difference. Shipped users run built `lib/` under plain Node and were never affected.

-`paths` grows from 188 keys to 519, and adding a package now requires running the generator. The `--check` gate makes that a named failure rather than a silent one, and the generated region keeps the diff of such a change to a single line.
+`paths` grows from 188 keys to 523, and adding a package now requires running the generator. The `--check` gate makes that a named failure rather than a silent one, and the generated region keeps the diff of such a change to a single line.
@@ -18,24 +18,32 @@ TypeScript 与 tsx 按顺序逐个尝试这些候选、取第一个存在的，

 生成器只为**声明名恰好等于 `@deepseek-ai/dsh-<目录名>`** 的包发别名，因为那是通配符唯一可能解析出的形态：它把说明符的后缀代入 `packages/<group>/<后缀>/src`。名字与目录不一致的包——`packages/typert/protocol` 上的 `@deepseek-ai/dsh-typert-protocol`、以及 `dsh-client-*` 与 `dsh-host-*` 两族——本来就有手写别名，保持不动。若某个说明符被两个包目录同时认领，生成器**抛错**而不是任选其一，因为显式映射无法表达通配符依赖的分组顺序裁决；当前不存在这种冲突。

+删除通配符也删掉了「没人写别名的包仍能解析」的兜底，因此生成器同时断言覆盖完备：每个含 `src` 的 workspace 包都必须被生成别名或手写别名映射，`--check` 会点名任何未被覆盖者。没有这条断言，一个名字与目录不一致的新包会被生成器跳过，继续经 workspace 软链解析到构建产物 `lib/`——正是显式别名要消除的产物层泄漏。
+
 该区域用标记注释之间的**定点文本改写**生成，而不是重新序列化整个文件。`tsconfig.base.json` 是 JSONC，其手写别名带有解释非显然映射的注释，重新序列化会把它们丢掉。

+本决策**部分取代**了[包清单自动发现提案](../../proposed/process/2026-06-20-discover-package-inventory.zh.md)——该提案把「合并为一个通配符」记为当前实现，而通配符已被删除；该提案剩余的主题（聚合配置里显式的 `references` 数组）不受本次改动影响。
+
 保留四条通配符，每条只有一个候选：`dsh-host-*/invariant`、`dsh-client-*/invariant`、`dsh-client-*/client`，以及五条 `dsh-host-<name>/*` 子路径映射。一个候选只花一次探测，展开它们只会换来文件变大而无收益。

 ## Resolution differences this change makes

-仓库源码中出现的每个 `@deepseek-ai/dsh-*` 说明符——共 1,022 个互不相同——解析目标与改动前完全一致，只有七个例外：它们现在能解析，而此前不能。
+仓库源码中出现的每个 `@deepseek-ai/dsh-*` 说明符——共 1,023 个互不相同——解析目标与改动前完全一致，只有十一个例外：它们现在能解析，而此前不能。这十一个此前都是经 workspace 软链解析到构建产物 `lib/`，而不是源码。

-`dsh-invariants/invariant`、`dsh-lsp/invariant`、`dsh-lsp-stdio/invariant`、`dsh-tool-lsp/invariant`、`dsh-terminal/invariant`、`dsh-terminal-bash/invariant`、`dsh-tool-terminal/invariant`。
+其中七个是 `/invariant` 子路径：`dsh-invariants/invariant`、`dsh-lsp/invariant`、`dsh-lsp-stdio/invariant`、`dsh-tool-lsp/invariant`、`dsh-terminal/invariant`、`dsh-terminal-bash/invariant`、`dsh-tool-terminal/invariant`。

 被删除的 `dsh-*/invariant` 通配符遗漏了 `lsp`、`terminal`、`client`、`host` 四个分组。其中 `client` 与 `host` 的遗漏是**刻意且有文档的**——这两族有专用通配符，因为它们的包名以分组目录名为前缀。而 `lsp` 与 `terminal` 的遗漏没有任何这类理由，`packages/runtime-diagnostics/invariants` 则两条列表都不在。于是这七个说明符此前是通过 workspace 软链与包的 `./invariant` 导出解析到构建产物 `lib/types/*.d.ts`，而不是解析到源码——这与「静态门禁通过 `paths` 把 workspace 导入解析到 `src`、并在干净树上通过」的规则相抵触。把别名统一之后，它们与所有同类一样解析到源码。

+另外四个是被覆盖断言揪出来的**整包**：`dsh-client-ui-directory-picker-browse`、`dsh-client-ui-directory-picker-native`、`dsh-experimental-agent-team-profile`、`dsh-experimental-agent-team-web-profile`。它们都叫 `dsh-<分组>-<目录>`，任何通配符都代不出这种形态；而它们身旁的同族包都有手写别名——这四个只是漏了。现在补上。
+
 ## Testing

-`scripts/gen-tsconfig-paths.spec.ts` 钉住：收集器把包映射到它自己的目录、跳过带手写别名的包、返回有序列表；渲染器让位于手写说明符，且区域收尾不带多余逗号；区域写入器只替换标记范围，并在缺少标记时拒绝；以及提交后的配置里两条分组通配符都不复存在。
+`scripts/gen-tsconfig-paths.spec.ts` 钉住：收集器把包映射到它自己的目录、跳过带手写别名的包、返回有序列表；渲染器让位于手写说明符，且区域收尾不带多余逗号；区域写入器只替换标记范围，并在缺少标记时拒绝；以及提交后的配置里两条分组通配符都不复存在。另有两条用例钉住覆盖断言：它会点名未被映射的包，且对提交后的配置报告为空。

 门禁的拒绝路径被直接验证过：删掉一条生成的别名会让 `verify-tsconfig-paths` 以非零码退出，恢复后检查通过。

+CLI 入口守卫采用仓库既有的比较方式 `import.meta.filename === resolve(process.argv[1])`，而不是拼接 `file://` URL。拼接形式在 `import.meta.url` 做了百分号编码而 `process.argv[1]` 没做时失效——仓库路径含空格、或任何 Windows 盘符路径——且失效是静默的：脚本什么也不做就以 0 退出，恰恰会让这道门在最需要它的环境里形同虚设。把脚本复制到一个名字含空格的目录下运行即可复现：拼接式守卫求值为 false，既有写法为 true。
+
 ## Alternatives considered

 **给通配符的候选 glob 重新排序，把最热的分组放前面。** 这不需要生成器也不需要新门禁，把 `util`、`core`、`llm`、`session` 挪到前面大约能拿回一半收益。否决理由：收益随着包的增加而衰减，这个顺序没有任何读者可核验的不变量，而且第一个分组之后的每一组仍然要付钱。它还保留了最糟的性质——新增一个包分组会悄悄拖慢所有人的启动。
@@ -50,4 +58,4 @@ TypeScript 与 tsx 按顺序逐个尝试这些候选、取第一个存在的，

 **收益仅限于 tsx 源码启动这一条路径。** Vitest 走 `vite-tsconfig-paths`，它在进程内做匹配与文件存在性检查，从不构造 Node 模块错误，因此从未付过那笔装饰代价：对某个包的整套用例做 A/B，实测 5,934 / 5,829 / 5,908 ms 对 5,878 / 5,851 / 5,905 ms，属于噪声。仓库的门禁脚本只 import 少数几个 `@deepseek-ai/dsh-*` 包，同样测不出可分离的差异。发布用户在裸 Node 下跑构建好的 `lib/`，本来就不受影响。

-`paths` 从 188 个 key 增长到 519 个，新增包时必须运行生成器。`--check` 门禁把这件事变成一次具名失败而非静默失败，而生成区域让这类改动的 diff 只有一行。
+`paths` 从 188 个 key 增长到 523 个，新增包时必须运行生成器。`--check` 门禁把这件事变成一次具名失败而非静默失败，而生成区域让这类改动的 diff 只有一行。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/proposed/process/2026-06-20-discover-package-inventory.md
-2026-06-20-discover-package-inventory.md: 7de865e43f87f0e41fad43b3786b9825509e9d50
-2026-06-20-discover-package-inventory.zh.md: fed3d9dd8740b2dc22434f8af7e1e8c025502f61
+2026-06-20-discover-package-inventory.md: 90ad595312431b942f3aac562e4ce8843fb6cc83
+2026-06-20-discover-package-inventory.zh.md: 4c5312f17ddeab1d6457a1a904f921f44e7d0b9d
@@ -8,7 +8,7 @@ English | [中文](2026-06-20-discover-package-inventory.zh.md)

 Package and gate inventories are repeated across TypeScript project references, package docs, CI prose, and Knip overrides. Most restate package layout, manifest data, or aggregate command contents. Each new package therefore creates avoidable synchronization points.

-The [package hierarchy](../../archived/architecture/2026-06-20-package-hierarchy.md) already removed several of these by hand: `scripts/publint-all.ts` now derives its list from the `packages/<group>/<pkg>` layout, and the two `tsconfig` `paths` maps collapsed to one `@deepseek-ai/dsh-*` wildcard. What remains is the inventory that cannot be globbed away — chiefly the aggregate configs' (`tsconfig.host.json`, `tsconfig.client.json`) project `references`, which TypeScript requires as explicit arrays (no wildcard form).
+The [package hierarchy](../../archived/architecture/2026-06-20-package-hierarchy.md) already removed several of these by hand: `scripts/publint-all.ts` now derives its list from the `packages/<group>/<pkg>` layout, and the two `tsconfig` `paths` maps collapsed to one `@deepseek-ai/dsh-*` wildcard — since reverted to one explicit alias per package, generated and gated, because resolving a wildcard's candidates in order dominated source-launch boot ([explicit workspace path aliases](../../implemented/process/2026-08-27-explicit-workspace-path-aliases.md)). What remains is the inventory that cannot be globbed away — chiefly the aggregate configs' (`tsconfig.host.json`, `tsconfig.client.json`) project `references`, which TypeScript requires as explicit arrays (no wildcard form).

 Static lists are appropriate when they encode policy; they are needless friction when they duplicate manifest data or layout facts that already exist in `package.json`, workspace globs, or the package hierarchy.

@@ -8,7 +8,7 @@ Status: proposed

 包与门禁清单在 TypeScript project references、包文档、CI 描述和 Knip 覆盖项中反复出现。大多数只是重述包布局、manifest（元数据清单）数据或聚合命令内容。因此每新增一个包都会产生本可避免的同步点。

-[包层级结构](../../archived/architecture/2026-06-20-package-hierarchy.md)已经手动消除了其中若干：`scripts/publint-all.ts` 现在从 `packages/<group>/<pkg>` 布局推导列表，两份 `tsconfig` 的 `paths` 映射也合并为一个 `@deepseek-ai/dsh-*` 通配符。剩下的是无法用 glob 消除的清单，主要是聚合配置（`tsconfig.host.json`、`tsconfig.client.json`）中的项目引用（`references`）——TypeScript 要求它们是显式数组（没有通配符形式）。
+[包层级结构](../../archived/architecture/2026-06-20-package-hierarchy.md)已经手动消除了其中若干：`scripts/publint-all.ts` 现在从 `packages/<group>/<pkg>` 布局推导列表，两份 `tsconfig` 的 `paths` 映射也合并为一个 `@deepseek-ai/dsh-*` 通配符——该合并此后已被回退为「每包一条、由生成器托管并有门禁把关」的显式别名，因为按顺序试候选的解析开销主导了源码启动时间（[显式 workspace 路径别名](../../implemented/process/2026-08-27-explicit-workspace-path-aliases.zh.md)）。剩下的是无法用 glob 消除的清单，主要是聚合配置（`tsconfig.host.json`、`tsconfig.client.json`）中的项目引用（`references`）——TypeScript 要求它们是显式数组（没有通配符形式）。

 当静态列表编码的是策略时，它们是合理的；当它们只是重复 `package.json`、workspace glob 或包层级结构中已有的 manifest 数据或布局事实时，就是不必要的摩擦。