From 3222537e73a7e195063d0f1a8e2b047f0c063e81 Mon Sep 17 00:00:00 2001 From: cliffhall Date: Tue, 25 Aug 2026 01:37:40 -0400 Subject: [PATCH] =?UTF-8?q?docs(scripts):=20correct=20the=20deleted-source?= =?UTF-8?q?=20caveat=20=E2=80=94=20it=20is=20silent,=20not=20loud?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Round 3's suppressed finding, and it corrects a claim of mine that was simply wrong. The header said a deleted source file's stale `.js` produces "a loud failure rather than a silent one — an import of a removed module fails at the consumer". It does not: the stale file is still there, so the post-build existence checks pass against it and anything still importing that module keeps silently running the old code. That is the SAME failure class this PR exists to close, described as though it were the opposite. Rewritten in the helper header and AGENTS.md to say the unconditional build does not cover deletion, and to make `rm -rf test-servers/build` after a delete or rename an instruction rather than an aside — which is now a real clean, since the tsbuildinfo was pinned inside build/ in 8d19346. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01JTHVxSu8AUgHRLvo1ntZ8H Signed-off-by: cliffhall --- AGENTS.md | 11 ++++++++--- scripts/lib/ensure-test-servers.mjs | 19 +++++++++++-------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 13983ff9..b96bcff2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -266,9 +266,14 @@ v2/main/ │ # silently drove the previous fixture — reported not as │ # staleness but as a product failure in whatever the │ # smoke was checking. Unconditional emit is still not a -│ # clean: a DELETED src file leaves its stale `.js` -│ # behind, so `rm -rf test-servers/build` after one — -│ # #2111; +│ # clean, and that is the one hole it does NOT close: a +│ # DELETED src file leaves its stale `.js` behind, the +│ # existence checks pass against it, and anything still +│ # importing that module SILENTLY runs the old code — the +│ # same failure class. So `rm -rf test-servers/build` +│ # after deleting or renaming a source file; the +│ # `.tsbuildinfo` is pinned inside `build/` so that +│ # clean actually invalidates the cache — #2111; │ # resolve-node-bin.mjs resolves a │ # package's bin through its own package.json, so the │ # verify/smoke scripts spawn it with `process.execPath` diff --git a/scripts/lib/ensure-test-servers.mjs b/scripts/lib/ensure-test-servers.mjs index a273c7e8..d2bec471 100644 --- a/scripts/lib/ensure-test-servers.mjs +++ b/scripts/lib/ensure-test-servers.mjs @@ -21,14 +21,17 @@ * smokes that take tens of seconds and a `pack:verify` that does a real * `npm install` from the registry. * - * ⚠️ Unconditional emit is not a clean: `--noCheck` emit leaves the stale `.js` - * of a *deleted* `src` file behind, and no path here removes it. That is - * unchanged from before (the old early-return only skipped the build; it never - * cleaned either), and it is a loud failure rather than a silent one — an - * import of a removed module fails at the consumer. Fixing it properly means - * `tsc -b` with `composite`, which forces `declaration` on and drops - * `--noCheck`; not worth it for this. `rm -rf test-servers/build` if you have - * deleted a source file. + * ⚠️ Unconditional emit is not a clean, and this is the one hole it does NOT + * close. `--noCheck` emit leaves the stale `.js` of a *deleted* `src` file + * behind, and no path here removes it — the post-build existence checks pass + * against that stale file, so if anything still imports the deleted module it + * silently keeps running the old code. That is the same failure class as the + * one this helper fixes, so do not read the unconditional build as covering it. + * (It is unchanged from before: the old early return only skipped the build, it + * never cleaned either.) Fixing it properly means `tsc -b` with `composite`, + * which forces `declaration` on and drops `--noCheck`; not worth it for this. + * **`rm -rf test-servers/build` after deleting or renaming a source file** — + * the `.tsbuildinfo` lives inside `build/` precisely so that clean is real. * * The root-installed tsc is run via this Node — `npx` is a `.cmd` shim on * Windows that a shell-free spawnSync can't start (ENOENT — #1939). That is