rungate 0.8.3 → 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,470 @@
1
+ /**
2
+ * Every call site in this tree that can put bytes on disk, and which of them
3
+ * aim at a spec (#1552).
4
+ *
5
+ * ## What this replaces
6
+ *
7
+ * #1286's completeness sweep classified *files*: a file that reads and writes
8
+ * the same identifier had to appear on one of two declared lists. That check
9
+ * fails when a known writer is unclassified and **cannot** fail when somebody
10
+ * adds a new unguarded one, because list membership is not reachability. It is
11
+ * also blind below the file — a second unguarded write site inside an
12
+ * already-classified file is invisible to it (#1548).
13
+ *
14
+ * This sweep's unit is the **call site**, and its reading is the write's
15
+ * **target expression**, so both of those holes close at once. The question it
16
+ * answers is not "has somebody classified this file" but "does a raw write
17
+ * primitive aim at a spec path without going through `lib/write-spec.ts`".
18
+ *
19
+ * ## The detector's view, stated so it can be argued with
20
+ *
21
+ * For each call to a write primitive, the sweep reads the **written argument
22
+ * expression** and resolves the identifiers in it against the real scope
23
+ * chain. A site is spec-targeting when the resolved text matches `SPEC_TARGET`.
24
+ *
25
+ * The resolution lives in `lib/spec-write-ast.ts` and goes through `acorn` via
26
+ * `lib/ts-ast.ts`. It replaces a hand-rolled lexer whose `initialiserOf` was a
27
+ * file-global name scan (#1566): four AI-review rounds on #1557 found four
28
+ * separate edge cases in that lexer and a fifth was found by its own negative
29
+ * control. The question it was answering — "which binding does this identifier
30
+ * resolve to" — is scope and position, and no name scan answers it.
31
+ *
32
+ * Two deliberate properties:
33
+ *
34
+ * - **It over-reports.** `spec-compliance-auto.test.ts` is a test, not a
35
+ * spec, and it matches. An over-report costs one classified line in
36
+ * `NOT_A_SPEC_PATH`; an under-report is how three unguarded writers
37
+ * reached review across #1286 and #1549.
38
+ * - **It names what it cannot resolve.** A parameter, an import and a
39
+ * destructured binding carry no readable value, and each is reported as
40
+ * UNRESOLVED rather than resolving to something plausible. A site whose
41
+ * target shows no string literal AND has an unresolved identifier is
42
+ * `opaque`: the path is entirely invisible, so the sweep cannot claim it is
43
+ * not a spec.
44
+ *
45
+ * ## Which directories are in scope, decided rather than inherited
46
+ *
47
+ * The TypeScript half sweeps five directories — `lib scripts gates bin hooks`.
48
+ * `workflows/` and `.github/` are ALSO swept, for `.js`, and that is a
49
+ * deliberate inclusion rather than the default:
50
+ *
51
+ * - MEASURED 2026-10-24, `grep -rnE '(writeFileSync|writeFile|appendFileSync|
52
+ * appendFile|renameSync|copyFileSync|truncateSync|Bun\.write)\s*\(' workflows
53
+ * .github` → **2** call sites, **0** of them naming a spec or an ADR. So
54
+ * including them changes no reading today.
55
+ * - They are included anyway because **`workflows/*.js` cannot import**
56
+ * (#69). That makes them the one region where the chokepoint is not
57
+ * merely skipped but *unavailable*, so a future spec write there would be
58
+ * unguarded with no local remedy — it would have to call the CLI. A
59
+ * region a guard cannot reach is exactly the region worth watching.
60
+ *
61
+ * ## Shell is covered, and the population is zero
62
+ *
63
+ * `shellSpecWrites` scans `.github/workflows/*.yml`, `workflows/`, and `*.sh`
64
+ * for a redirect, a `tee`, or a `sed -i` whose target names `specs/`. Measured
65
+ * 2026-10-24: zero. A TypeScript-only chokepoint is therefore sufficient
66
+ * *today*, which is a fact about the tree and not a property of the design —
67
+ * so the shell reading is taken rather than assumed, and it has its own
68
+ * planted-violation case.
69
+ */
70
+ import { existsSync, readdirSync, readFileSync, statSync } from "fs";
71
+ import { join, relative, sep } from "path";
72
+ import {
73
+ resolveLines,
74
+ SIMPLE_PRIMITIVES,
75
+ specTargetingOf,
76
+ writeSitesIn,
77
+ } from "./spec-write-ast";
78
+
79
+ /** The module every spec write must route through. Excluded from the sweep. */
80
+ export const CHOKEPOINT = "lib/write-spec.ts";
81
+
82
+ /**
83
+ * Everything that can put bytes on disk, including the non-`fs` spellings.
84
+ *
85
+ * Derived from `SIMPLE_PRIMITIVES` rather than restated, so there is ONE list
86
+ * to extend. A second copy here would drift from the one the detector reads
87
+ * and the sweep would go green on a primitive it no longer looks for.
88
+ *
89
+ * ## This list is irreducible, and it fails toward UNDER-reporting
90
+ *
91
+ * #1566 replaced the sweep's resolution logic with a semantic invariant — a
92
+ * value set is complete only for a `const` with an initialiser, which is a
93
+ * guarantee the *language* makes — so no enumeration of assignment spellings
94
+ * can fall behind there. The obvious next question, raised by the AI review
95
+ * on #1569 (`bbaefb99`), is why this list is not given the same treatment.
96
+ *
97
+ * Because there is nothing to derive it from. Nothing in the language, the
98
+ * type system or the AST distinguishes `writeFileSync` from `readFileSync`;
99
+ * the knowledge lives in Node's documentation. A derivation like
100
+ * `/write|append|rename|copy|truncate/` over callee names would be a detector
101
+ * over spellings, which is the exact trade #1566 removed one layer down —
102
+ * and it would both miss a primitive named otherwise and flag
103
+ * `logger.writeLine`.
104
+ *
105
+ * So the bound stands, and the useful thing to know is its direction:
106
+ *
107
+ * - **A missed primitive is invisible, not wrong.** The sweep reports
108
+ * nothing at that call site rather than reporting it incorrectly, so the
109
+ * chokepoint's green reading silently excludes it. That is the costly
110
+ * direction, and it is why `Bun.write` is here — somebody hit it.
111
+ * - **A fix, if one is wanted, is a different instrument.** A capability
112
+ * check over the `fs` module surface belongs in
113
+ * `lib/fs-write-capabilities.ts`, not in a cleverer predicate here.
114
+ *
115
+ * Adding a spelling to `SIMPLE_PRIMITIVES` is therefore an ordinary and
116
+ * expected edit. Reaching for a pattern instead is the regression.
117
+ */
118
+ export const WRITE_PRIMITIVES = [...SIMPLE_PRIMITIVES, "Bun.write"] as const;
119
+
120
+ /** Directories whose TypeScript sources are swept. */
121
+ export const SWEPT_DIRS = ["lib", "scripts", "gates", "bin", "hooks"] as const;
122
+
123
+ /**
124
+ * Directories swept for `.js` instead. See the scope note in the module
125
+ * docblock: these are included because `workflows/*.js` cannot import (#69),
126
+ * so the chokepoint is unavailable rather than merely skipped there.
127
+ */
128
+ export const SWEPT_JS_DIRS = ["workflows", ".github"] as const;
129
+
130
+ export interface WriteSite {
131
+ /** Repo-relative path, forward-slashed. */
132
+ file: string;
133
+ /**
134
+ * 1-based line of the call, or `null` when it could not be established.
135
+ *
136
+ * AST node positions index the TRANSPILED text — `Bun.Transpiler` drops
137
+ * comments and blank lines — so the line is resolved by ordinal against the
138
+ * original and refused when the counts disagree. `NOT_A_SPEC_PATH` is keyed
139
+ * on the target expression and never on a line, so a null costs a reader
140
+ * some context and costs the check nothing.
141
+ */
142
+ line: number | null;
143
+ /** Which primitive was called. */
144
+ primitive: string;
145
+ /** The written argument's source text, whitespace-collapsed. */
146
+ target: string;
147
+ /** The text the detector actually read — target plus any expansion. */
148
+ view: string;
149
+ /** Whether `view` names a spec. */
150
+ specTargeting: boolean;
151
+ /** `name: reason` for each identifier in the target carrying no value. */
152
+ unresolved?: string[];
153
+ /** True when the sweep cannot determine this target's path. */
154
+ opaque?: boolean;
155
+ /** True when `view` is a lower bound rather than a reading. */
156
+ reassignable?: boolean;
157
+ }
158
+
159
+ /**
160
+ * Write sites whose resolved `view` is a LOWER BOUND rather than a reading,
161
+ * each with what it actually writes. Keyed `file::targetExpression`.
162
+ *
163
+ * This is the population that makes the strict reading honest. The sweep can
164
+ * see some of what these writes can aim at and cannot see all of it — so
165
+ * rather than let one read as "not a spec", every one is listed here and
166
+ * `undeterminedTargets` fails on one that is not.
167
+ *
168
+ * That is what stops the detector being defeated by an assignment spelling
169
+ * nobody enumerated. MEASURED: widening the tracker to destructuring patterns
170
+ * still missed 3 of 6 spellings (a default inside a pattern, `for ([p] of …)`,
171
+ * `for (p of …)`); under this reading all three come out undetermined instead
172
+ * of clean, and a fourth spelling nobody has thought of does too.
173
+ *
174
+ * Six entries on this tree, out of 131 write sites — unchanged when the
175
+ * reading widened from `let`/`var` to every incomplete value set (#1569 round
176
+ * 4), because no parameter, catch or destructured binding here is reassigned.
177
+ * The flag propagates through the expansion, so a locally-`const` target lands
178
+ * here when an identifier INSIDE it is not complete — `backupDir`, `outDir`
179
+ * and `SF` are why most of these are listed.
180
+ *
181
+ * This is the PROSE tier and it deliberately does not cover the wider class
182
+ * of targets that are `opaque` for some other reason. That class is now 96 of
183
+ * this tree's 130 non-chokepoint write sites, 85 of whose holes are a function
184
+ * parameter: a helper whose caller supplies the path. 96 hand-written
185
+ * justifications would be 96 lines of "the caller decides".
186
+ *
187
+ * It is no longer unguarded, which is the change #1584 made. `opaqueDrift`
188
+ * ratchets the whole 96 against `OPAQUE_RATCHET` in both directions, so the
189
+ * wider class moves only when somebody writes down that it moved. Six sites
190
+ * make the stronger claim and stay here, with what they write.
191
+ *
192
+ * The earlier number in this docblock was 38, measured before `unresolved`
193
+ * was recorded below depth 0 and before a visible literal stopped clearing an
194
+ * invisible directory. On this tree today the old predicate reads 37.
195
+ */
196
+ export const REASSIGNABLE_TARGETS: Record<string, string> = {
197
+ "lib/test-suite-lock.ts::tmp":
198
+ "a temp sibling of the lock file, `${path}.${pid}.${rand}`, renamed over it; `path` is the lock path",
199
+ "lib/test-suite-lock.ts::path":
200
+ "the suite lock file itself, as the destination of the atomic rename above",
201
+ "lib/worktree-collect.ts::slot":
202
+ "a numbered slot under the collect backup root, from `backupDir` which is a lazily-assigned let",
203
+ "scripts/suite-flake-run.ts::log":
204
+ "`run-NN.log` under the flake run's output directory",
205
+ "scripts/verify-merge-content.ts::out":
206
+ "the artefact path given by --out, written only when that flag was passed",
207
+ "gates/run-gate.ts::SF":
208
+ "the gate state file this script exists to maintain",
209
+ };
210
+
211
+ /**
212
+ * Write sites whose target matches `/spec/i` and is nonetheless not a path
213
+ * under `specs/`. Keyed `file::targetExpression` — a symbol, never a line
214
+ * number, so moving the call does not stale the entry.
215
+ *
216
+ * This is the negative control the check needs, not an exemption lane for
217
+ * spec writers: every entry names something that is demonstrably not a spec,
218
+ * and `test/spec-write-chokepoint.test.ts` refuses an entry whose site has
219
+ * disappeared from the population.
220
+ */
221
+ export const NOT_A_SPEC_PATH: Record<string, string> = {
222
+ // Empty, and that is the reading: all nineteen spec writes in this tree
223
+ // were MIGRATED to `writeSpec`, not exempted. An entry here is a claim that
224
+ // a `/spec/i` match is not a spec path, and it has to say what the site
225
+ // writes instead. Grandfathering a spec writer here would make the check
226
+ // decorative, which is the whole failure mode #1552 exists to end.
227
+ };
228
+
229
+ // ── The sweep ─────────────────────────────────────────────────────
230
+
231
+ /** TypeScript sources under the five swept directories. */
232
+ function sourceFiles(root: string, dir: string, out: string[], ext: RegExp): void {
233
+ const abs = join(root, dir);
234
+ if (!existsSync(abs)) return;
235
+ for (const e of readdirSync(abs, { withFileTypes: true }).sort((a, b) =>
236
+ a.name.localeCompare(b.name),
237
+ )) {
238
+ const rel = `${dir}/${e.name}`;
239
+ if (e.isDirectory()) {
240
+ if (e.name === "node_modules" || e.name === ".git") continue;
241
+ sourceFiles(root, rel, out, ext);
242
+ continue;
243
+ }
244
+ if (!ext.test(e.name) || e.name.endsWith(".test.ts")) continue;
245
+ out.push(rel);
246
+ }
247
+ }
248
+
249
+ /**
250
+ * Every write-primitive call site under the swept directories.
251
+ *
252
+ * Throws, naming the file, when a source cannot be parsed. A file the parser
253
+ * gave up on and a file with no writes produce the same empty list, and only
254
+ * one of those is a clean reading.
255
+ */
256
+ export function writeSites(root: string, dirs: readonly string[] = SWEPT_DIRS): WriteSite[] {
257
+ const files: string[] = [];
258
+ for (const d of dirs) sourceFiles(root, d, files, /\.ts$/);
259
+ for (const d of SWEPT_JS_DIRS) sourceFiles(root, d, files, /\.js$/);
260
+
261
+ const sites: WriteSite[] = [];
262
+ for (const file of files) {
263
+ const raw = readFileSync(join(root, file), "utf-8");
264
+ const loader = file.endsWith(".js") ? "js" : "ts";
265
+ let found;
266
+ try {
267
+ found = writeSitesIn(raw, { loader });
268
+ } catch (e) {
269
+ throw new Error(`spec-write sweep: UNMEASURED in ${file} — ${(e as Error).message}`);
270
+ }
271
+ const lines = resolveLines(raw, found, { positionsAreOriginal: loader === "js" });
272
+ found.forEach((s, i) => {
273
+ sites.push({
274
+ file,
275
+ line: lines[i],
276
+ primitive: s.primitive,
277
+ target: s.target,
278
+ view: s.view,
279
+ specTargeting: specTargetingOf(s),
280
+ unresolved: s.unresolved,
281
+ opaque: s.opaque,
282
+ reassignable: s.reassignable,
283
+ });
284
+ });
285
+ }
286
+ return sites;
287
+ }
288
+
289
+ /**
290
+ * Raw spec writes that bypass the chokepoint.
291
+ *
292
+ * Empty is the only acceptable reading. A site here is either migrated to
293
+ * `writeSpec` or — if its target is not a spec at all — classified in
294
+ * `NOT_A_SPEC_PATH` with what it writes instead.
295
+ */
296
+ export function specChokepointViolations(
297
+ root: string,
298
+ dirs: readonly string[] = SWEPT_DIRS,
299
+ classified: Record<string, string> = NOT_A_SPEC_PATH,
300
+ ): WriteSite[] {
301
+ return writeSites(root, dirs).filter(
302
+ (s) => s.specTargeting && s.file !== CHOKEPOINT && !(`${s.file}::${s.target}` in classified),
303
+ );
304
+ }
305
+
306
+ /**
307
+ * Write sites built from a reassignable binding that nobody has declared.
308
+ * Empty is the only acceptable reading.
309
+ *
310
+ * Separate from `specChokepointViolations` because it is a different claim: a
311
+ * violation says "this writes a spec and skips the chokepoint", while this
312
+ * says "the sweep cannot establish what this writes, and nobody has said why
313
+ * that is alright". Both must be empty for the chokepoint's green reading to
314
+ * mean anything — without this one, a target the resolver cannot follow reads
315
+ * exactly like a target it followed and cleared.
316
+ */
317
+ export function undeterminedTargets(
318
+ root: string,
319
+ dirs: readonly string[] = SWEPT_DIRS,
320
+ declared: Record<string, string> = REASSIGNABLE_TARGETS,
321
+ ): WriteSite[] {
322
+ return writeSites(root, dirs).filter(
323
+ (s) => s.reassignable && s.file !== CHOKEPOINT && !(`${s.file}::${s.target}` in declared),
324
+ );
325
+ }
326
+
327
+ // ── The opaque ratchet ────────────────────────────────────────────
328
+
329
+ /** Where the opaque population is recorded. Relative to the project root. */
330
+ export const OPAQUE_RATCHET = ".claude/spec-write-opaque-ratchet.json";
331
+
332
+ /** `file::target | reason, reason` — the fingerprint one opaque site records. */
333
+ export function opaqueFingerprint(s: WriteSite): string {
334
+ const holes =
335
+ s.unresolved && s.unresolved.length > 0
336
+ ? s.unresolved.join(", ")
337
+ : "reassignable, no readable hole";
338
+ return `${s.file}::${s.target} | ${holes}`;
339
+ }
340
+
341
+ /**
342
+ * The declared opaque population.
343
+ *
344
+ * Throws when the file is absent or does not carry a `sites` array. A store
345
+ * that could not be read is UNMEASURED, not an empty population — `{}` and
346
+ * `{"sites": []}` are different facts and `sites` is the control string that
347
+ * tells them apart (the same rule `lib/sc-reservations.ts` applies).
348
+ */
349
+ export function declaredOpaque(root: string): string[] {
350
+ const path = join(root, OPAQUE_RATCHET);
351
+ if (!existsSync(path)) {
352
+ throw new Error(`spec-write sweep: UNMEASURED — ${OPAQUE_RATCHET} is absent`);
353
+ }
354
+ const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
355
+ const sites = (parsed as { sites?: unknown }).sites;
356
+ if (!Array.isArray(sites) || sites.some((s) => typeof s !== "string")) {
357
+ throw new Error(`spec-write sweep: UNMEASURED — ${OPAQUE_RATCHET} has no \`sites\` string array`);
358
+ }
359
+ return sites as string[];
360
+ }
361
+
362
+ /**
363
+ * How the tree's opaque population differs from the declared one, in BOTH
364
+ * directions.
365
+ *
366
+ * `opaque` is the resolver's answer to "could I follow this target" and until
367
+ * #1584 nothing downstream read it — a fourth state no consumer distinguishes
368
+ * is the same as not having it. This is the consumer.
369
+ *
370
+ * It is a ratchet and not a justification list, and the difference is
371
+ * deliberate. The honest population is 96 of this tree's 130 non-chokepoint
372
+ * write sites, 85 of whose holes are a FUNCTION PARAMETER: a helper whose
373
+ * caller supplies the path. Asking for 96 hand-written justifications would
374
+ * produce 96 lines of "the caller decides", which is a list nobody reads
375
+ * guarding a property nobody can check. `REASSIGNABLE_TARGETS` keeps the
376
+ * prose tier for the six sites making the stronger claim.
377
+ *
378
+ * What this does buy, and what nothing bought before it: a NEW opaque site
379
+ * fails the suite, a site whose holes CHANGE fails, and a site that becomes
380
+ * readable fails until its entry is deleted in the same commit. The
381
+ * population can only move by somebody writing down that it moved.
382
+ */
383
+ export function opaqueDrift(
384
+ root: string,
385
+ dirs: readonly string[] = SWEPT_DIRS,
386
+ ): { added: string[]; removed: string[] } {
387
+ const found = writeSites(root, dirs)
388
+ .filter((s) => s.opaque && s.file !== CHOKEPOINT)
389
+ .map(opaqueFingerprint)
390
+ .sort();
391
+ const declared = [...declaredOpaque(root)].sort();
392
+
393
+ // Multiset difference: two sites can share a file, a target AND their holes
394
+ // — `lib/scaffold/steps.ts::filePath` is three of them — so a set would let
395
+ // a fourth copy arrive unnoticed.
396
+ const remaining = [...declared];
397
+ const added: string[] = [];
398
+ for (const f of found) {
399
+ const at = remaining.indexOf(f);
400
+ if (at === -1) added.push(f);
401
+ else remaining.splice(at, 1);
402
+ }
403
+ return { added, removed: remaining };
404
+ }
405
+
406
+ // ── Shell ─────────────────────────────────────────────────────────
407
+
408
+ /**
409
+ * A shell redirect, `tee` or `sed -i` whose target names `specs/`.
410
+ *
411
+ * Kept separate from the TypeScript sweep because the two have different
412
+ * remedies: a TypeScript site routes through `writeSpec`, and a shell site has
413
+ * no chokepoint to route through — it must call the CLI or not exist. Today it
414
+ * does not exist, and this is how that stays checkable.
415
+ */
416
+ export function shellSpecWrites(root: string, scanned?: string[]): WriteSite[] {
417
+ const files = scanned ?? shellCorpus(root);
418
+ const patterns: Array<[string, RegExp]> = [
419
+ ["redirect", /(?:^|[^>\w])>>?\s*(?:"|')?[^\s"'|;&]*\bspecs\//],
420
+ ["tee", /\btee\s+(?:-a\s+)?(?:"|')?[^\s"'|;&]*\bspecs\//],
421
+ ["sed-i", /\bsed\s+(?:-[a-zA-Z]*\s+)*-i[a-zA-Z]*\b[^\n]*\bspecs\//],
422
+ ];
423
+ const out: WriteSite[] = [];
424
+ for (const file of files) {
425
+ const raw = readFileSync(join(root, file), "utf-8");
426
+ raw.split("\n").forEach((text, idx) => {
427
+ if (/^\s*#/.test(text)) return;
428
+ for (const [primitive, re] of patterns) {
429
+ if (!re.test(text)) continue;
430
+ out.push({
431
+ file,
432
+ line: idx + 1,
433
+ primitive,
434
+ target: text.trim(),
435
+ view: text.trim(),
436
+ specTargeting: true,
437
+ });
438
+ break;
439
+ }
440
+ });
441
+ }
442
+ return out;
443
+ }
444
+
445
+ /** The shell-shaped files the redirect scan reads. Non-empty, or it is vacuous. */
446
+ export function shellCorpus(root: string): string[] {
447
+ const out: string[] = [];
448
+ const walk = (dir: string) => {
449
+ const abs = join(root, dir);
450
+ if (!existsSync(abs) || !statSync(abs).isDirectory()) return;
451
+ for (const e of readdirSync(abs, { withFileTypes: true }).sort((a, b) =>
452
+ a.name.localeCompare(b.name),
453
+ )) {
454
+ const rel = `${dir}/${e.name}`;
455
+ if (e.isDirectory()) {
456
+ if (e.name === "node_modules" || e.name === ".git") continue;
457
+ walk(rel);
458
+ continue;
459
+ }
460
+ if (/\.(sh|bash|zsh|ya?ml|js)$/.test(e.name)) out.push(rel);
461
+ }
462
+ };
463
+ for (const d of [".github", "workflows", "scripts", "hooks", "bin"]) walk(d);
464
+ return out.map((p) => p.split(sep).join("/"));
465
+ }
466
+
467
+ /** `relative`, forward-slashed — exported so callers need not import `path`. */
468
+ export function repoRelative(root: string, abs: string): string {
469
+ return relative(root, abs).split(sep).join("/");
470
+ }
@@ -404,8 +404,19 @@ const SHELL_DASH_C = /^(?:ba|z|k|)sh\s+-[a-z]*c\s+(['"])([\s\S]*)\1\s*$/;
404
404
  const SUITE_INVOCATION =
405
405
  /^(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?test(?![:\w-])/;
406
406
 
407
- /** A redirection operator, attached target or not: `>`, `2>`, `&>>`, `2>&1`, `2>/dev/null`. */
408
- const REDIRECT = /^(?:\d*|&)>>?(?:&\d+)?(.*)$/;
407
+ /**
408
+ * A redirection operator, attached target or not: `>`, `2>`, `&>>`, `2>&1`,
409
+ * `2>/dev/null`.
410
+ *
411
+ * Group 1 is a duplicate-fd suffix (`&1`), group 2 the attached target. Both
412
+ * are captured because only a redirect with NEITHER consumes the following
413
+ * token: `>` takes the next word as its target, while `2>&1` is complete in
414
+ * itself. Group 1 used to be non-capturing, so `2>&1` presented as a redirect
415
+ * with an empty target and swallowed the argument after it — a test path in
416
+ * that position was dropped from the extraction and never checked. Found by
417
+ * the AI review on PR #1562 (#1544).
418
+ */
419
+ const REDIRECT = /^(?:\d*|&)>>?(&\d+)?(.*)$/;
409
420
 
410
421
  /**
411
422
  * Split on command separators that are NOT inside quotes.
@@ -414,6 +425,32 @@ const REDIRECT = /^(?:\d*|&)>>?(?:&\d+)?(.*)$/;
414
425
  * because the `&&` inside the message split the command, and
415
426
  * `bash -c "bun test; echo done"` went unguarded because the `;` inside the body
416
427
  * split it before the shell-wrapper pattern could match a balanced quoted string.
428
+ *
429
+ * ## TWO GUARDS READ THIS. Loosening it for one breaks the other silently.
430
+ *
431
+ * 1. `isFullSuiteCommand` — the cross-session concurrency cap (DIR-L29, #67,
432
+ * SC-516). It fails CLOSED: a missed full suite is unlimited concurrency,
433
+ * which rebooted this machine on 2026-10-05.
434
+ * 2. `suitePathArguments` / `suitePathArgumentsBySegment` — the path-existence
435
+ * guard behind `lib/bun-test-paths.ts` and `hooks/BunTestPathGuard.hook.ts`
436
+ * (#1544). It fails OPEN, because a false refusal blocks the agent in
437
+ * front of it.
438
+ *
439
+ * The two want opposite error directions from the same reading, so a change
440
+ * here needs a case on both sides. `test/bun-test-path-guard.test.ts` AC-8e
441
+ * is the control that `&&` and a backgrounding `&` still end a segment —
442
+ * added when #1544 taught this splitter that an `&` adjacent to a `>` is part
443
+ * of a redirect, which is exactly the kind of loosening that could have
444
+ * quietly changed what the concurrency cap sees.
445
+ *
446
+ * ## This is NOT the same question `lib/top-level-cd.ts` answers
447
+ *
448
+ * `topLevelSegments` there splits only at parenthesis depth 0, returning a
449
+ * subshell as ONE opaque segment — correct for "did a `cd` move the SESSION",
450
+ * since a `cd` inside a subshell cannot. Adopting it here would hide every
451
+ * `bun test` inside a subshell from the anchored invocation pattern. One
452
+ * parser must treat a subshell as opaque and the other must see inside it, so
453
+ * they are not two deciders that agree (#1544, SC-2547).
417
454
  */
418
455
  function splitTopLevel(command: string): string[] {
419
456
  const out: string[] = [];
@@ -443,6 +480,17 @@ function splitTopLevel(command: string): string[] {
443
480
  i++;
444
481
  continue;
445
482
  }
483
+ // An `&` that belongs to a REDIRECT is not a separator: `2>&1` duplicates
484
+ // a descriptor and `&>log` redirects both streams. Splitting there ended
485
+ // the segment mid-operator and stranded everything after it in a segment
486
+ // with no suite invocation — so `bun test a.test.ts 2>&1 b.test.ts` lost
487
+ // `b.test.ts` from the extraction entirely and never checked it. Found by
488
+ // the AI review on PR #1562; the REDIRECT capture fix alone did not reach
489
+ // it, because the token never survived this splitter to be matched (#1544).
490
+ if (c === "&" && (command[i - 1] === ">" || command[i + 1] === ">")) {
491
+ cur += c;
492
+ continue;
493
+ }
446
494
  if (c === "\n" || c === ";" || c === "&" || c === "|") {
447
495
  if ((c === "&" && command[i + 1] === "&") || (c === "|" && command[i + 1] === "|")) i++;
448
496
  out.push(cur);
@@ -475,8 +523,36 @@ export function isFullSuiteCommand(command: string): boolean {
475
523
  return false;
476
524
  }
477
525
 
478
- function segmentIsFullSuite(segment: string, depth = 0): boolean {
479
- if (depth > 3) return false;
526
+ /**
527
+ * Is this argument demonstrably a PATH rather than a name filter? (#1544)
528
+ *
529
+ * Exported because two questions now read it and they are opposites: a
530
+ * path-shaped argument means a run is targeted rather than full
531
+ * (`isFullSuiteCommand`), and it means a path `lib/bun-test-paths.ts` must
532
+ * stat before bun turns it into a silent filter. A second copy of this
533
+ * predicate would survive any mutation of this one and both would read as
534
+ * covered (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
535
+ *
536
+ * Deliberately NOT every positional argument. Bun treats a bare word as a
537
+ * substring name filter and that is a legitimate thing to type, so refusing
538
+ * one because no file is named after it would fire on correct commands.
539
+ * The population this leaves uncovered is stated in `lib/bun-test-paths.ts`.
540
+ */
541
+ export function looksLikeTestPath(arg: string): boolean {
542
+ return arg.includes("/") || /\.(test\.)?(ts|tsx|js|jsx)$/.test(arg);
543
+ }
544
+
545
+ /**
546
+ * The positional arguments of every suite invocation in this segment — one
547
+ * array per invocation, empty for the outer list when the segment is not one.
548
+ *
549
+ * Per-invocation rather than flattened, because the two consumers need
550
+ * different granularity and flattening would change `isFullSuiteCommand`:
551
+ * `bash -c "bun test a/b.ts; bun test"` contains a full suite, and a single
552
+ * concatenated argument list would report a path and hide it.
553
+ */
554
+ function suiteInvocationArguments(segment: string, depth = 0): string[][] {
555
+ if (depth > 3) return [];
480
556
 
481
557
  let s = segment.trim();
482
558
 
@@ -493,13 +569,13 @@ function segmentIsFullSuite(segment: string, depth = 0): boolean {
493
569
  // `bash -c "bun test; echo done"` — recurse into the quoted body.
494
570
  const shellC = s.match(SHELL_DASH_C);
495
571
  if (shellC) {
496
- return splitTopLevel(shellC[2]).some((inner) =>
497
- segmentIsFullSuite(inner, depth + 1),
572
+ return splitTopLevel(shellC[2]).flatMap((inner) =>
573
+ suiteInvocationArguments(inner, depth + 1),
498
574
  );
499
575
  }
500
576
 
501
577
  const invocation = s.match(SUITE_INVOCATION);
502
- if (!invocation) return false;
578
+ if (!invocation) return [];
503
579
 
504
580
  const rest = s.slice(invocation[0].length).trim();
505
581
  // `npm test -- test/foo.ts` passes args through the runner.
@@ -514,19 +590,57 @@ function segmentIsFullSuite(segment: string, depth = 0): boolean {
514
590
 
515
591
  const redirect = t.match(REDIRECT);
516
592
  if (redirect) {
517
- // `2>/dev/null` carries its target; a bare `>` consumes the next token.
518
- // Either way the target is a sink, not a test path.
519
- if (!redirect[1]) i++;
593
+ // `2>/dev/null` carries its target and `2>&1` duplicates a descriptor;
594
+ // only a bare `>` consumes the next token. Either way the target is a
595
+ // sink, not a test path.
596
+ const [, duplicateFd, attachedTarget] = redirect;
597
+ if (!duplicateFd && !attachedTarget) i++;
520
598
  continue;
521
599
  }
522
600
 
523
601
  args.push(t);
524
602
  }
525
603
 
526
- const hasPath = args.some(
527
- (a) => a.includes("/") || /\.(test\.)?(ts|tsx|js|jsx)$/.test(a),
604
+ return [args];
605
+ }
606
+
607
+ /** One top-level segment and the path-shaped arguments its suite invocations carry. */
608
+ export interface SegmentPathArguments {
609
+ /** The segment text, so a caller can judge whether it is resolvable at all. */
610
+ segment: string;
611
+ paths: string[];
612
+ }
613
+
614
+ /**
615
+ * Every path-shaped `bun test` argument, grouped by the segment it came from.
616
+ *
617
+ * Grouped rather than flat because a caller that resolves these against the
618
+ * filesystem has to be able to skip a segment it cannot read — a command
619
+ * substitution spans several whitespace tokens, so `$(bun scripts/x.ts)`
620
+ * arrives as `$(bun` and `scripts/x.ts)` and a per-ARGUMENT check sees a
621
+ * perfectly ordinary-looking path in the second. That was a live false
622
+ * refusal, caught by this repo's own control case (#1544).
623
+ */
624
+ export function suitePathArgumentsBySegment(command: string): SegmentPathArguments[] {
625
+ return splitTopLevel(command).map((segment) => ({
626
+ segment,
627
+ paths: suiteInvocationArguments(segment).flat().filter(looksLikeTestPath),
628
+ }));
629
+ }
630
+
631
+ /**
632
+ * Every path-shaped argument handed to a `bun test` anywhere in this command.
633
+ *
634
+ * The flat reading, for a caller that does not need to resolve anything.
635
+ */
636
+ export function suitePathArguments(command: string): string[] {
637
+ return suitePathArgumentsBySegment(command).flatMap((s) => s.paths);
638
+ }
639
+
640
+ function segmentIsFullSuite(segment: string, depth = 0): boolean {
641
+ return suiteInvocationArguments(segment, depth).some(
642
+ (args) => !args.some(looksLikeTestPath),
528
643
  );
529
- return !hasPath;
530
644
  }
531
645
 
532
646
  /**