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.
- package/gates/.gate-salt +1 -1
- package/hooks/BunTestPathGuard.hook.ts +106 -0
- package/hooks/TopLevelCdGuard.hook.ts +38 -6
- package/lib/bun-test-paths.ts +253 -0
- package/lib/conformity.ts +9 -5
- package/lib/finding-jury.ts +13 -4
- package/lib/gate-check-audit.ts +535 -148
- package/lib/organize.ts +18 -8
- package/lib/release-preflight.ts +90 -1
- package/lib/report-provenance.ts +153 -0
- package/lib/scaffold/ai-review-findings.ts +219 -16
- package/lib/scaffold/ai-review-step.ts +263 -9
- package/lib/scaffold/steps.ts +26 -9
- package/lib/spec-updater.ts +11 -7
- package/lib/spec-write-ast.ts +728 -0
- package/lib/spec-write-sweep.ts +470 -0
- package/lib/test-suite-lock.ts +127 -13
- package/lib/ts-ast.ts +26 -0
- package/lib/validators/spec-validators.ts +15 -12
- package/lib/write-spec.ts +138 -0
- package/package.json +1 -1
- package/scripts/audit-specs.ts +8 -9
- package/scripts/convert-spec.ts +7 -2
- package/scripts/create-sc.ts +7 -6
- package/scripts/create-spec.ts +5 -2
- package/scripts/split-spec.ts +9 -8
- package/scripts/sync-sc-status.ts +7 -6
|
@@ -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
|
+
}
|
package/lib/test-suite-lock.ts
CHANGED
|
@@ -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
|
-
/**
|
|
408
|
-
|
|
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
|
-
|
|
479
|
-
|
|
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]).
|
|
497
|
-
|
|
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
|
|
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
|
|
518
|
-
// Either way the target is a
|
|
519
|
-
|
|
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
|
-
|
|
527
|
-
|
|
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
|
/**
|