From 194ea6bdf0d8a9cdec2e94de9f1f992b44f6f7d0 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Mon, 27 Jul 2026 18:03:21 +0800 Subject: [PATCH] docs(test): correct execa process-tree claims --- .../2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml | 6 +++--- .../2026-07-26-execa-for-test-subprocess-plumbing.md | 4 ++-- .../2026-07-26-execa-for-test-subprocess-plumbing.zh.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml b/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml index 606229b494..466071f552 100644 --- a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.i18n.yaml @@ -1,6 +1,6 @@ # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each # 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 -2026-07-26-execa-for-test-subprocess-plumbing.md: a25010b1cab7012cf9c659cfd8272d17e33618c5 -2026-07-26-execa-for-test-subprocess-plumbing.zh.md: 733c9f7e7f666052f030ed3b0f916e4832aaa120 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md +2026-07-26-execa-for-test-subprocess-plumbing.md: 958abc4aee94adb3e6206cc299595ad92bde4044 +2026-07-26-execa-for-test-subprocess-plumbing.zh.md: 7027a8bde51f81bfa7774743f84639cbd4b667d8 diff --git a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md b/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md index a25010b1ca..958abc4aee 100644 --- a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md +++ b/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.md @@ -25,13 +25,13 @@ Two related test-infra hand-rolls compounded the case: ## Alternatives considered - **`tinyexec` instead of execa.** Already in `node_modules` transitively via vitest, smaller API — but no kill-escalation, no rich error output embedding, and being transitive is not a contract; if the lighter package is preferred the swap shape is identical. -- **A repo-local shared spawn helper (no new dep).** Viable and cheaper on supply chain, but it keeps the maintenance of deadline/kill/settlement logic in-repo when a battle-tested package owns exactly this; contrary to the [dependency policy](../process/2026-07-26-dependencies-over-hand-rolling.md), it also has to re-earn Windows behavior (taskkill, exit codes) that execa already carries. +- **A repo-local shared spawn helper (no new dep).** Viable and cheaper on supply chain, but it keeps the maintenance of deadline/kill/settlement logic in-repo when a battle-tested package owns exactly this; contrary to the [dependency policy](../process/2026-07-26-dependencies-over-hand-rolling.md), it also has to re-earn cross-platform timeout, termination, and result-normalization behavior that execa already carries. - **`get-port`, `wait-on`, `tempy`, `tree-kill`.** Rejected individually: the repo's single port probe is break-even, the file waits are dominated by `vi.waitFor`, temp-dir handling already uses `mkdtemp` + `rm {recursive}` builtins everywhere, and acp-snapshot's `close()` is drain-ordering logic, not tree traversal. ## Consequences - The hand-rolled collect/timeout blocks are gone, including the two `/* v8 ignore */` un-inducible OS-error branches in `loader-smoke`: spawn and stream failures settle through execa's result fields, so the `src/` file carries no coverage exemptions and the per-file gate covers every remaining branch. - Captured output is bounded by execa's default 100 MB `maxBuffer` (overflow terminates the subprocess) where it was previously unbounded; the `loader-smoke` README's limitation entry reflects this. -- Windows termination behavior (taskkill, exit-code mapping) is owned by execa instead of per-site hand-rolls; each rewritten suite was re-run on POSIX in this change, and the Windows CI lanes own the other platform. +- Direct-child timeout termination and exit/signal result normalization are owned by execa across platforms instead of per-site hand-rolls; process-tree termination remains outside these helpers, as the `loader-smoke` README states. Each rewritten suite was re-run on POSIX in this change, and the Windows CI lanes own the other platform. - execa is a new root devDependency (previously absent from the lockfile); it is one of the most-depended-on packages on npm and actively maintained, and the exe/runtime closure is unaffected (tests only). - The mock-server CLI's tokenizer-level error texts are no longer this repo's to choose: unknown options, missing values, and stray positionals report `parseArgs`'s wording, pinned as such in `tests/cli.spec.ts`. diff --git a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md b/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md index 733c9f7e7f..7027a8bde5 100644 --- a/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md +++ b/.agents/notes/implemented/testing/2026-07-26-execa-for-test-subprocess-plumbing.zh.md @@ -25,13 +25,13 @@ Status: implemented ## 曾考虑的替代方案 - **用 `tinyexec` 代替 execa。**它已经作为 vitest 的传递依赖存在于 `node_modules` 中，API 也更小；但它没有终止信号逐级升级，不会把丰富的输出嵌入错误对象，而且传递依赖并不构成契约。如果最终更倾向这个更轻的包，替换的形态完全相同。 -- **仓库内共享的 spawn 辅助函数（不引入新依赖）。**可行，供应链成本也更低，但当一个久经实战的包恰好负责这件事时，它把截止时限、终止与结算逻辑的维护留在了仓库内；这与[依赖策略](../process/2026-07-26-dependencies-over-hand-rolling.md)背道而驰，它还得重新踩坑换来 execa 已经自带的 Windows 行为（taskkill、退出码）。 +- **仓库内共享的 spawn 辅助函数（不引入新依赖）。**可行，供应链成本也更低，但当一个久经实战的包恰好负责这件事时，它把截止时限、终止与结算逻辑的维护留在了仓库内；这与[依赖策略](../process/2026-07-26-dependencies-over-hand-rolling.md)背道而驰，它还得重新踩坑换来 execa 已经自带的跨平台超时、终止与结果规范化行为。 - **`get-port`、`wait-on`、`tempy`、`tree-kill`。**逐一不予采纳：仓库仅有的一处端口探测替换后收支相抵；文件等待场景已由 `vi.waitFor` 更优地覆盖；临时目录处理在各处已经使用内置的 `mkdtemp` + `rm {recursive}`；acp-snapshot 的 `close()` 是排空顺序逻辑，不是进程树遍历。 ## 后果 - 手写的收集/超时代码块全部移除，包括 `loader-smoke` 中两个标注 `/* v8 ignore */`、无法人为诱发的 OS 错误分支：spawn 与流故障如今经由 execa 的结果字段结算，这个 `src/` 文件不再携带任何覆盖率豁免，逐文件门禁覆盖其余全部分支。 - 捕获的输出如今受 execa 默认 100 MB `maxBuffer` 约束（溢出即终止子进程），此前是无界的；`loader-smoke` README 的局限条目反映了这一点。 -- Windows 终止行为（taskkill、退出码映射）由 execa 拥有，不再逐处手写；每个改写后的套件在本次变更中已在 POSIX 上重新运行，另一平台由 Windows CI 车道负责。 +- 直接子进程的超时终止以及退出/信号结果规范化均由 execa 跨平台负责，不再逐处手写；如 `loader-smoke` README 所述，这些辅助函数依然不负责终止进程树。每个改写后的套件在本次变更中已在 POSIX 上重新运行，另一平台由 Windows CI 车道负责。 - execa 是新增的根 devDependency（此前完全不存在于 lockfile 中）；它是 npm 上被依赖最多的包之一且维护活跃，exe/运行时闭包不受影响（仅测试使用）。 - mock-server CLI 切分器层面的错误文本不再由本仓库决定：未知选项、缺失取值与多余位置参数报告 `parseArgs` 的措辞，并在 `tests/cli.spec.ts` 中如此固定。