rungate 0.8.2 → 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.
Files changed (74) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/BunTestPathGuard.hook.ts +106 -0
  9. package/hooks/DocHygiene.hook.ts +2 -1
  10. package/hooks/GateResultProtection.hook.ts +28 -7
  11. package/hooks/HookCurrency.hook.ts +48 -1
  12. package/hooks/TopLevelCdGuard.hook.ts +38 -6
  13. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  14. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  15. package/lib/ai-review-jury.ts +725 -0
  16. package/lib/ai-review-rounds.ts +791 -4
  17. package/lib/ai-review-unmeasured.ts +361 -0
  18. package/lib/bash-write-guard.ts +1235 -102
  19. package/lib/bun-test-paths.ts +253 -0
  20. package/lib/cli-commands.ts +252 -11
  21. package/lib/closing-reference-audit.ts +163 -0
  22. package/lib/conformity.ts +17 -1
  23. package/lib/create-sc.ts +45 -12
  24. package/lib/derived-spec.ts +206 -0
  25. package/lib/file-claims.ts +335 -0
  26. package/lib/finding-arbiter.ts +502 -28
  27. package/lib/finding-jury.ts +61 -5
  28. package/lib/finding-pr-routing.ts +333 -0
  29. package/lib/frontmatter.ts +16 -0
  30. package/lib/gate-check-audit.ts +646 -0
  31. package/lib/generators/agents-md.ts +29 -0
  32. package/lib/github.ts +112 -7
  33. package/lib/hook-tree-currency.ts +494 -0
  34. package/lib/issue-closure-audit.ts +161 -14
  35. package/lib/issue-create-override.ts +53 -3
  36. package/lib/issue-filing-gate.ts +1073 -76
  37. package/lib/local-review-rounds.ts +523 -0
  38. package/lib/organize.ts +21 -1
  39. package/lib/project-state-shape.ts +56 -5
  40. package/lib/release-preflight.ts +90 -1
  41. package/lib/repo-path.ts +94 -0
  42. package/lib/report-provenance.ts +218 -3
  43. package/lib/risk-tier.ts +302 -0
  44. package/lib/rounds-to-pass.ts +274 -0
  45. package/lib/rule-row-drift.ts +199 -0
  46. package/lib/sc-claim-forms.ts +33 -5
  47. package/lib/sc-guard.ts +11 -1
  48. package/lib/sc-id-cross-tree.ts +17 -2
  49. package/lib/sc-ids.ts +71 -6
  50. package/lib/sc-reservations.ts +158 -14
  51. package/lib/scaffold/ai-review-findings.ts +1369 -27
  52. package/lib/scaffold/ai-review-step.ts +4095 -119
  53. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  54. package/lib/scaffold/owned-files.ts +14 -0
  55. package/lib/scaffold/steps.ts +100 -9
  56. package/lib/scratch-roots.ts +93 -3
  57. package/lib/spec-updater.ts +22 -2
  58. package/lib/spec-write-ast.ts +728 -0
  59. package/lib/spec-write-sweep.ts +470 -0
  60. package/lib/test-suite-lock.ts +127 -13
  61. package/lib/ts-ast.ts +26 -0
  62. package/lib/validators/spec-validators.ts +36 -7
  63. package/lib/write-spec.ts +138 -0
  64. package/package.json +2 -1
  65. package/scripts/ai-review-findings.ts +41 -1
  66. package/scripts/arbitrate-finding.ts +330 -12
  67. package/scripts/audit-specs.ts +225 -24
  68. package/scripts/convert-spec.ts +7 -2
  69. package/scripts/create-sc.ts +14 -2
  70. package/scripts/create-spec.ts +5 -2
  71. package/scripts/detect-sc-drift.ts +10 -2
  72. package/scripts/record-ai-review-unmeasured.ts +370 -0
  73. package/scripts/split-spec.ts +17 -4
  74. package/scripts/sync-sc-status.ts +14 -2
@@ -0,0 +1,728 @@
1
+ /**
2
+ * Which binding does the identifier at a write site resolve to? (#1566)
3
+ *
4
+ * ## Why this module exists
5
+ *
6
+ * #1552 shipped a spec-write sweep whose target resolution was a file-global
7
+ * name scan (`initialiserOf`). The AI review on #1557 found it reading the
8
+ * FIRST same-named declaration in the file; the fix taken there was a UNION
9
+ * over all same-named declarations. Both are name scans, and the question is
10
+ * not a name question — it is "which binding does this identifier resolve to",
11
+ * which is scope and position. A name scan answers it correctly only when the
12
+ * file happens to contain one binding of that name.
13
+ *
14
+ * The direction of the error matters more than its size. The first-match scan
15
+ * was wrong in the PERMISSIVE direction: a file with `const filePath =
16
+ * join(outDir, "report.json")` in one function and `const filePath =
17
+ * join(specsDir, "NEW-SPEC.md")` in another reads the real spec write through
18
+ * the report path, matches nothing, and reports CLEAN. That is the exact miss
19
+ * #1552 exists to end, rebuilt inside the detector meant to catch it.
20
+ *
21
+ * This repository has paid for this lesson twice already — #968 (a regex
22
+ * narrower than its own subject) and #1555 (a brace-depth token scan wrong
23
+ * five times across four revisions, with two shapes still wrong in merged
24
+ * code). Both ended at an AST. This is the same ending, reached one patch
25
+ * earlier.
26
+ *
27
+ * ## The parser, and why not TypeScript's
28
+ *
29
+ * `acorn`, through `lib/ts-ast.ts` — this repository's existing binding for
30
+ * "a detector that must not be fooled by its own fixtures". `typescript` is a
31
+ * **devDependency** and `lib/` is published (`files[]` in package.json), so a
32
+ * published module importing it resolves here and breaks at
33
+ * `bunx rungate@<version>` on a consumer's CI runner, where nothing in this
34
+ * suite would see it. `test/package-closure.test.ts` is the check for that
35
+ * class. `acorn` is a runtime dependency.
36
+ *
37
+ * ## The consequence that this module has to carry
38
+ *
39
+ * `parseTsModule` transpiles the types off before parsing, and
40
+ * `Bun.Transpiler` drops comments and blank lines. MEASURED on bun 1.3.14: an
41
+ * 11-line fixture transpiles to 6 lines, and the offset of the same call moves
42
+ * from 152 to 93. **Node positions index the transpiled text and cannot be
43
+ * converted to a line in the original.** `resolveLines` therefore maps them by
44
+ * ordinal against the original text and REFUSES — reporting `line: null`
45
+ * rather than a number — when the two counts disagree. A wrong line in a
46
+ * violation message sends the next reader to the wrong place, which is worse
47
+ * than no line.
48
+ *
49
+ * ## WHAT THIS DOES NOT RESOLVE
50
+ *
51
+ * Stated because an unstated boundary reads as coverage, and a clean report
52
+ * from an incomplete detector is worse than no detector (#968's own thesis).
53
+ * Each of these is reported as UNRESOLVED with its reason rather than
54
+ * silently resolving to something plausible:
55
+ *
56
+ * - **A parameter.** The value comes from callers; this reading is per-module.
57
+ * - **An import.** The value is in another module. Not followed, by design —
58
+ * the alternative is an import graph, which this is not.
59
+ * - **A destructured binding.** `const { p } = cfg` binds a property of a
60
+ * value this module does not evaluate.
61
+ * - **A declaration with no initialiser** that is never assigned.
62
+ * - **A loop binding that reassigns an existing identifier** — `for (p of
63
+ * paths) writeFileSync(p, …)`, where `p` is declared elsewhere. The write
64
+ * is still found; only the VALUE is unread, so the site reads as
65
+ * unresolved rather than as clean. `for (const p of …)` is a declaration
66
+ * and is resolved normally.
67
+ *
68
+
69
+ * And one case is deliberately OVER-approximated rather than refused: a
70
+ * binding that is REASSIGNED is read as the union of its initialiser and every
71
+ * assigned expression. Over-reporting costs one classified line; under-
72
+ * reporting costs an unguarded writer nobody can see.
73
+ */
74
+ import {
75
+ type AstNode,
76
+ calleeRoot,
77
+ importBindings,
78
+ parseJsModule,
79
+ parseTsModule,
80
+ rootProperty,
81
+ walkNodes,
82
+ } from "./ts-ast";
83
+
84
+ /**
85
+ * Everything that can put bytes on disk, excluding the `Bun.write` spelling,
86
+ * which is a member expression and is matched separately.
87
+ */
88
+ export const SIMPLE_PRIMITIVES = [
89
+ "writeFileSync",
90
+ "writeFile",
91
+ "appendFileSync",
92
+ "appendFile",
93
+ "renameSync",
94
+ "copyFileSync",
95
+ "truncateSync",
96
+ ] as const;
97
+
98
+ /** Primitives that write their SECOND argument rather than their first. */
99
+ const WRITTEN_ARGUMENT: Record<string, number> = { renameSync: 1, copyFileSync: 1 };
100
+
101
+ /**
102
+ * What counts as a target naming a derived document.
103
+ *
104
+ * Anchored at a token boundary rather than matched as a bare substring, so
105
+ * `quadrant` and `inspectPath` are not derived documents while `adrDir` and
106
+ * `specsDir` are. `adr` is in deliberately — see #1548.
107
+ */
108
+ export const SPEC_TARGET = /(?:^|[^A-Za-z0-9])(spec|adr)/i;
109
+
110
+ /** Maximum links of a `const a = f(b); const b = f(c)` chain the view follows. */
111
+ export const EXPANSION_DEPTH = 3;
112
+
113
+ /**
114
+ * Identifiers that are ambient rather than bound in the module. Not reported
115
+ * as unresolved: "I could not find a binding for `process`" is noise, and a
116
+ * noisy unresolved list is one nobody reads.
117
+ */
118
+ const AMBIENT = new Set([
119
+ "Bun", "process", "JSON", "Math", "String", "Number", "Boolean", "Array",
120
+ "Object", "Date", "RegExp", "Error", "console", "require", "globalThis",
121
+ "__dirname", "__filename", "undefined", "NaN", "Infinity",
122
+ ]);
123
+
124
+ type BindingKind =
125
+ | "const" | "let" | "var" | "param" | "import"
126
+ | "destructured" | "function" | "class" | "catch";
127
+
128
+ /** Why an identifier carries no readable value. */
129
+ type UnresolvedReason = "parameter" | "import" | "destructured" | "no-initialiser" | "not-found";
130
+
131
+ interface Binding {
132
+ kind: BindingKind;
133
+ /** Initialiser source text, or `null` when there is none to read. */
134
+ init: string | null;
135
+ /**
136
+ * Expressions assigned to this binding after declaration, as NODES.
137
+ *
138
+ * Stored as nodes rather than as source text so the expansion can follow
139
+ * through them the way it follows an initialiser. Holding the text alone
140
+ * meant `p = q` appended the characters `q` to `view` and never resolved
141
+ * `q` — one of two symmetric inputs reaching the frontier (#1582). The
142
+ * text is derived at the read site, so there is no second copy to desync.
143
+ */
144
+ assigned: AstNode[];
145
+ /** Position of the declaration in the TRANSPILED text. */
146
+ declStart: number;
147
+ }
148
+
149
+ interface Scope {
150
+ parent: Scope | null;
151
+ isFunction: boolean;
152
+ start: number;
153
+ end: number;
154
+ bindings: Map<string, Binding>;
155
+ }
156
+
157
+ const FUNCTION_TYPES = new Set([
158
+ "FunctionDeclaration",
159
+ "FunctionExpression",
160
+ "ArrowFunctionExpression",
161
+ ]);
162
+
163
+ const BLOCK_TYPES = new Set([
164
+ "BlockStatement",
165
+ "ForStatement",
166
+ "ForInStatement",
167
+ "ForOfStatement",
168
+ "CatchClause",
169
+ "SwitchStatement",
170
+ ]);
171
+
172
+ function isNodeLike(value: unknown): value is AstNode {
173
+ return (
174
+ typeof value === "object" &&
175
+ value !== null &&
176
+ typeof (value as AstNode).type === "string" &&
177
+ typeof (value as AstNode).start === "number"
178
+ );
179
+ }
180
+
181
+ /** Child nodes of `node`, in document order. */
182
+ function children(node: AstNode): AstNode[] {
183
+ const out: AstNode[] = [];
184
+ for (const value of Object.values(node)) {
185
+ if (Array.isArray(value)) {
186
+ for (const c of value) if (isNodeLike(c)) out.push(c);
187
+ } else if (isNodeLike(value)) {
188
+ out.push(value);
189
+ }
190
+ }
191
+ return out;
192
+ }
193
+
194
+ /** Every name a binding pattern introduces, with whether it was destructured. */
195
+ function patternNames(node: AstNode | undefined, destructured: boolean): [string, boolean][] {
196
+ if (!node) return [];
197
+ switch (node.type) {
198
+ case "Identifier":
199
+ return [[String(node.name), destructured]];
200
+ case "ObjectPattern":
201
+ return ((node.properties ?? []) as AstNode[]).flatMap((p) =>
202
+ p.type === "RestElement"
203
+ ? patternNames(p.argument as AstNode, true)
204
+ : patternNames(p.value as AstNode, true),
205
+ );
206
+ case "ArrayPattern":
207
+ return ((node.elements ?? []) as (AstNode | null)[]).flatMap((e) =>
208
+ e ? patternNames(e, true) : [],
209
+ );
210
+ case "AssignmentPattern":
211
+ return patternNames(node.left as AstNode, destructured);
212
+ case "RestElement":
213
+ return patternNames(node.argument as AstNode, destructured);
214
+ default:
215
+ return [];
216
+ }
217
+ }
218
+
219
+ /**
220
+ * Build the scope tree, with every declaration attached to the scope that
221
+ * actually holds it: `var` and parameters to the nearest FUNCTION scope,
222
+ * `let`/`const`/`class` to the nearest block, imports to the module scope.
223
+ */
224
+ function buildScopes(tree: AstNode, js: string): { root: Scope; scopeOf: Map<AstNode, Scope> } {
225
+ const root: Scope = {
226
+ parent: null,
227
+ isFunction: true,
228
+ start: tree.start,
229
+ end: tree.end,
230
+ bindings: new Map(),
231
+ };
232
+ const scopeOf = new Map<AstNode, Scope>();
233
+
234
+ const text = (n: AstNode | undefined | null): string | null =>
235
+ n ? js.slice(n.start, n.end) : null;
236
+
237
+ const functionScope = (s: Scope): Scope => {
238
+ let cur: Scope = s;
239
+ while (!cur.isFunction && cur.parent) cur = cur.parent;
240
+ return cur;
241
+ };
242
+
243
+ const bindName = (scope: Scope, name: string, binding: Binding) => {
244
+ // First declaration wins within a scope. A redeclaration of the same name
245
+ // in the same scope is either a `var` repeat or invalid code; either way
246
+ // the later one does not create a second resolution target.
247
+ if (!scope.bindings.has(name)) scope.bindings.set(name, binding);
248
+ };
249
+
250
+ const visit = (node: AstNode, scope: Scope): void => {
251
+ let current = scope;
252
+
253
+ if (FUNCTION_TYPES.has(node.type)) {
254
+ current = {
255
+ parent: scope,
256
+ isFunction: true,
257
+ start: node.start,
258
+ end: node.end,
259
+ bindings: new Map(),
260
+ };
261
+ for (const p of (node.params ?? []) as AstNode[]) {
262
+ for (const [name] of patternNames(p, false)) {
263
+ bindName(current, name, { kind: "param", init: null, assigned: [], declStart: node.start });
264
+ }
265
+ }
266
+ } else if (BLOCK_TYPES.has(node.type)) {
267
+ current = {
268
+ parent: scope,
269
+ isFunction: false,
270
+ start: node.start,
271
+ end: node.end,
272
+ bindings: new Map(),
273
+ };
274
+ if (node.type === "CatchClause" && node.param) {
275
+ for (const [name] of patternNames(node.param as AstNode, false)) {
276
+ bindName(current, name, { kind: "catch", init: null, assigned: [], declStart: node.start });
277
+ }
278
+ }
279
+ }
280
+ scopeOf.set(node, current);
281
+
282
+ if (node.type === "VariableDeclaration") {
283
+ const kind = String(node.kind) as "const" | "let" | "var";
284
+ const target = kind === "var" ? functionScope(current) : current;
285
+ for (const d of (node.declarations ?? []) as AstNode[]) {
286
+ const init = text(d.init as AstNode | undefined);
287
+ for (const [name, destructured] of patternNames(d.id as AstNode, false)) {
288
+ bindName(target, name, {
289
+ kind: destructured ? "destructured" : kind,
290
+ init: destructured ? null : init,
291
+ assigned: [],
292
+ declStart: d.start,
293
+ });
294
+ }
295
+ }
296
+ } else if (node.type === "FunctionDeclaration" && node.id) {
297
+ bindName(scope, String((node.id as AstNode).name), {
298
+ kind: "function", init: null, assigned: [], declStart: node.start,
299
+ });
300
+ } else if (node.type === "ClassDeclaration" && node.id) {
301
+ bindName(scope, String((node.id as AstNode).name), {
302
+ kind: "class", init: null, assigned: [], declStart: node.start,
303
+ });
304
+ } else if (node.type === "ImportDeclaration") {
305
+ for (const s of (node.specifiers ?? []) as AstNode[]) {
306
+ const local = (s.local as AstNode | undefined)?.name;
307
+ if (typeof local === "string") {
308
+ bindName(root, local, { kind: "import", init: null, assigned: [], declStart: node.start });
309
+ }
310
+ }
311
+ }
312
+
313
+ for (const c of children(node)) visit(c, current);
314
+ };
315
+
316
+ visit(tree, root);
317
+ return { root, scopeOf };
318
+ }
319
+
320
+ /**
321
+ * Resolve `name` as seen from `pos`.
322
+ *
323
+ * Walks the scope chain outward from the use site. Declaration position is
324
+ * respected for `let`/`const`, but ONLY while no function boundary has been
325
+ * crossed: `function f() { return p } const p = 1` is legal and `p` does
326
+ * resolve, because `f` runs after the declaration is evaluated. Applying the
327
+ * positional rule across a function boundary would wrongly refuse it.
328
+ */
329
+ function lookup(from: Scope, name: string, pos: number): Binding | null {
330
+ let scope: Scope | null = from;
331
+ let crossedFunction = false;
332
+ /**
333
+ * A binding the positional rule skipped. Position is used to PREFER one
334
+ * binding over another, never to refuse resolution outright: a reference
335
+ * that precedes its own `const` is broken code, and reading it anyway
336
+ * over-reports, while refusing it reads as clean. The sweep's allowed
337
+ * direction is over-reporting — MEASURED, this is what the round-3
338
+ * `const outPath = mask + tail` fixture needs, where every link of the
339
+ * chain is declared after its use.
340
+ */
341
+ let deferred: Binding | null = null;
342
+ while (scope) {
343
+ const b = scope.bindings.get(name);
344
+ if (b) {
345
+ const temporalDeadZone =
346
+ !crossedFunction && (b.kind === "const" || b.kind === "let") && b.declStart > pos;
347
+ if (!temporalDeadZone) return b;
348
+ deferred ??= b;
349
+ }
350
+ if (scope.isFunction) crossedFunction = true;
351
+ scope = scope.parent;
352
+ }
353
+ return deferred;
354
+ }
355
+
356
+ /** Every value-reference identifier under `node` — not property names or callees. */
357
+ function valueIdentifiers(node: AstNode): AstNode[] {
358
+ const out: AstNode[] = [];
359
+ const skip = new Set<AstNode>();
360
+ for (const n of walkNodes(node)) {
361
+ if (n.type === "MemberExpression" && !n.computed) skip.add(n.property as AstNode);
362
+ if (n.type === "CallExpression" || n.type === "NewExpression") skip.add(n.callee as AstNode);
363
+ if (n.type === "Property" && !n.computed) skip.add(n.key as AstNode);
364
+ // `import.meta` is a MetaProperty: two Identifier nodes that reference no
365
+ // binding at all. Without this they resolve to nothing and are reported as
366
+ // `import: not-found` / `meta: not-found` — a hole invented by the walker,
367
+ // in the one construct every script in this repo uses to find its own
368
+ // directory. `__dirname`, its CJS equivalent, is already in AMBIENT.
369
+ if (n.type === "MetaProperty") {
370
+ skip.add(n.meta as AstNode);
371
+ skip.add(n.property as AstNode);
372
+ }
373
+ }
374
+ for (const n of walkNodes(node)) {
375
+ if (n.type === "Identifier" && !skip.has(n)) out.push(n);
376
+ }
377
+ return out;
378
+ }
379
+
380
+ /** One write-primitive call site, as the tree sees it. */
381
+ export interface AstWriteSite {
382
+ /** Canonical primitive name, e.g. `writeFileSync` or `Bun.write`. */
383
+ primitive: string;
384
+ /** The callee's source text as written, e.g. `fs.writeFileSync` or `wfs`. */
385
+ callee: string;
386
+ /** The written argument's source text, whitespace-collapsed. */
387
+ target: string;
388
+ /** `target` plus every initialiser the resolver could reach from it. */
389
+ view: string;
390
+ /** `name: reason` for each identifier in the target carrying no value. */
391
+ unresolved: string[];
392
+ /**
393
+ * True when the sweep cannot determine this target's path, so it must not
394
+ * claim the site is not a spec write. Two causes:
395
+ *
396
+ * - the target has an unresolved identifier at ANY depth — some component
397
+ * of the path is invisible. A partial reading like
398
+ * `join(root, "report.json")` IS one of these: the filename is readable
399
+ * and the directory is not, and the directory is the half that decides
400
+ * whether the write lands under `specs/`. An earlier predicate cleared
401
+ * those on the strength of the visible literal (#1584);
402
+ * - the target depends on a binding whose value set is not closed, so the
403
+ * value at the write is not what its initialiser says. See `reassignable`.
404
+ */
405
+ opaque: boolean;
406
+ /**
407
+ * True when `view` is a LOWER BOUND: some identifier in the target
408
+ * contributed a value while its complete set of values is not knowable here.
409
+ * The sweep can see some of what this write can aim at and cannot see all of
410
+ * it, so a reading of "not a spec" is not available.
411
+ *
412
+ * This is the property that replaced enumerating assignment spellings. The
413
+ * first fix for the #1569 review finding widened the tracker from `x = …` to
414
+ * destructuring patterns; MEASURED against six spellings, three were still
415
+ * missed — a default inside a pattern, `for ([p] of …)` and `for (p of …)`.
416
+ * Widening again just moves the boundary.
417
+ *
418
+ * A value set is complete only when the declaration established it and
419
+ * nothing can change it afterwards: a `const` with an initialiser. That is
420
+ * the language's own guarantee rather than a list this file has to keep
421
+ * current, so a new assignment spelling nobody enumerated changes no answer.
422
+ *
423
+ * It has been wrong in both directions and both are recorded here, because
424
+ * the shape of the error is the point:
425
+ *
426
+ * - It first asked `kind === "let" || kind === "var"`, which is a statement
427
+ * about how the name was INTRODUCED and not about what can be seen. A
428
+ * `param`, a `catch` binding and a destructured one are assignable too,
429
+ * and one conditional assignment to any of them read as a complete
430
+ * resolution (#1569 round 4).
431
+ * - An earlier draft of this comment put the cost at 3 sites. That came
432
+ * from a probe which only inspected module-level declarations, so it
433
+ * could not see a parameter or a function-local — the instrument's scope
434
+ * was narrower than the question it was quoted as answering.
435
+ *
436
+ * MEASURED on this tree: 6 of 131 write sites, unchanged across both
437
+ * corrections — no parameter or destructured binding here is reassigned, so
438
+ * the widened reading costs nothing and closes a reachable hole. The flag
439
+ * propagates through the expansion, so a locally-`const` target counts when
440
+ * an identifier inside it is not complete. Those 6 are declared in
441
+ * `REASSIGNABLE_TARGETS` rather than silently cleared.
442
+ */
443
+ reassignable: boolean;
444
+ /** Offset of the call in the TRANSPILED text. Never an original-file offset. */
445
+ start: number;
446
+ }
447
+
448
+ /** Does this site's resolved view name a derived document? */
449
+ export function specTargetingOf(site: AstWriteSite): boolean {
450
+ return SPEC_TARGET.test(site.view);
451
+ }
452
+
453
+ /**
454
+ * Every write-primitive call site in `source`.
455
+ *
456
+ * Throws rather than returning `[]` when the source does not parse. A parser
457
+ * that stopped parsing and a file that is clean produce the same empty list,
458
+ * which is the first shape in `.claude/rules/checks-must-be-able-to-fail.md`.
459
+ */
460
+ export function writeSitesIn(
461
+ source: string,
462
+ opts: { loader?: "ts" | "js" } = {},
463
+ ): AstWriteSite[] {
464
+ // `.js` is parsed directly: it has no types to strip, `Bun.Transpiler`
465
+ // refuses every `workflows/*.js` in this tree on all four loaders, and
466
+ // skipping the rewrite makes node positions index the original text.
467
+ const parsed = opts.loader === "js" ? parseJsModule(source) : parseTsModule(source);
468
+ if (!parsed) {
469
+ throw new Error(
470
+ "writeSitesIn: UNMEASURED — the source did not transpile or did not parse, so no write " +
471
+ "sites were read. This is not an empty list of findings.",
472
+ );
473
+ }
474
+ const { tree, js } = parsed;
475
+ const { root, scopeOf } = buildScopes(tree, js);
476
+ const imports = importBindings(tree);
477
+
478
+ // Attach assignments to the binding they actually target, so a reassignment
479
+ // is read as a union rather than ignored.
480
+ for (const node of walkNodes(tree)) {
481
+ if (node.type !== "AssignmentExpression") continue;
482
+ const left = node.left as AstNode | undefined;
483
+ const right = node.right as AstNode | undefined;
484
+ if (!left || !right) continue;
485
+ // Every name the left-hand side binds, not just a bare `x = …`. A
486
+ // destructuring reassignment — `[p] = […]` or `({ p } = …)` — targets an
487
+ // already-declared identifier, and reading only `Identifier` dropped it
488
+ // silently, so the binding resolved to its initialiser alone. That is the
489
+ // permissive direction, inside the mechanism added to stop it (#1569).
490
+ //
491
+ // The whole right-hand side is attributed to each name rather than the
492
+ // element that actually reaches it: which property lands where needs
493
+ // evaluation, and over-attributing is the allowed direction.
494
+ for (const [name] of patternNames(left, false)) {
495
+ const binding = lookup(scopeOf.get(node) ?? root, name, node.start);
496
+ if (binding) binding.assigned.push(right);
497
+ }
498
+ }
499
+
500
+ /** The primitive this callee denotes, or null. */
501
+ const primitiveOf = (callee: AstNode, scope: Scope, pos: number): string | null => {
502
+ if (callee.type === "Identifier") {
503
+ const name = String(callee.name);
504
+ if ((SIMPLE_PRIMITIVES as readonly string[]).includes(name)) return name;
505
+ // An aliased import: `import { writeFileSync as wfs } from "fs"`.
506
+ const imported = imports.get(name)?.imported;
507
+ if (imported && (SIMPLE_PRIMITIVES as readonly string[]).includes(imported)) return imported;
508
+ // A local alias: `const w = writeFileSync`.
509
+ const binding = lookup(scope, name, pos);
510
+ const init = binding?.init?.trim();
511
+ if (init && (SIMPLE_PRIMITIVES as readonly string[]).includes(init)) return init;
512
+ return null;
513
+ }
514
+ if (callee.type === "MemberExpression" && !callee.computed) {
515
+ const prop = callee.property as AstNode | undefined;
516
+ if (prop?.type !== "Identifier") return null;
517
+ const name = String(prop.name);
518
+ if (calleeRoot(callee) === "Bun" && rootProperty(callee) === "write") return "Bun.write";
519
+ if ((SIMPLE_PRIMITIVES as readonly string[]).includes(name)) return name;
520
+ return null;
521
+ }
522
+ return null;
523
+ };
524
+
525
+ const sites: AstWriteSite[] = [];
526
+ for (const node of walkNodes(tree)) {
527
+ if (node.type !== "CallExpression") continue;
528
+ const callee = node.callee as AstNode | undefined;
529
+ if (!callee) continue;
530
+ const scope = scopeOf.get(node) ?? root;
531
+ const primitive = primitiveOf(callee, scope, node.start);
532
+ if (!primitive) continue;
533
+
534
+ const args = (node.arguments ?? []) as AstNode[];
535
+ const index = WRITTEN_ARGUMENT[primitive] ?? 0;
536
+ const arg = args[index];
537
+ const target = arg ? js.slice(arg.start, arg.end).replace(/\s+/g, " ") : "";
538
+
539
+ const unresolved: string[] = [];
540
+ let view = target;
541
+ let reassignable = false;
542
+
543
+ if (arg) {
544
+ // Expand identifiers transitively, resolving each from ITS OWN scope.
545
+ //
546
+ // The dedup is keyed on the BINDING, not on the name. Keying it on the
547
+ // name is the same defect as `initialiserOf`, one level further in: two
548
+ // distinct bindings sharing a name on one chain — a local reached first,
549
+ // the module-level one holding the path reached later — and the second
550
+ // is marked done by the first and never expanded. Found by the AI review
551
+ // on #1569 and reproduced as shape 9. An unresolvable identifier has no
552
+ // binding to key on, so those are deduped by name separately.
553
+ const seen = new Set<Binding>();
554
+ const noted = new Set<string>();
555
+
556
+ // Record an identifier the resolver could not read a value for, AT ANY
557
+ // DEPTH. The push used to be gated on `depth === 0`, so a hole reached
558
+ // by FOLLOWING the chain — `const p = join(z, "report.json")` with `z` a
559
+ // parameter — left no trace: the site reported an EMPTY unresolved list,
560
+ // byte-identical to a fully resolved reading. A target the resolver
561
+ // could not follow must never read like one it followed and cleared.
562
+ //
563
+ // The depth gate's intent was readability, and the suffix keeps it: a
564
+ // nested hole is still tellable from a top-level one, which is what the
565
+ // depth gate bought at the price of dropping it entirely (#1584).
566
+ const note = (name: string, reason: UnresolvedReason, depth: number): void => {
567
+ const entry = depth === 0 ? `${name}: ${reason}` : `${name}: ${reason} (nested)`;
568
+ if (noted.has(entry)) return;
569
+ noted.add(entry);
570
+ unresolved.push(entry);
571
+ };
572
+
573
+ let frontier = valueIdentifiers(arg);
574
+ for (let depth = 0; depth < EXPANSION_DEPTH && frontier.length > 0; depth++) {
575
+ const next: AstNode[] = [];
576
+ for (const id of frontier) {
577
+ const name = String(id.name);
578
+ if (AMBIENT.has(name)) continue;
579
+ const idScope = scopeOf.get(id) ?? scope;
580
+ const binding = lookup(idScope, name, id.start);
581
+
582
+ if (!binding) {
583
+ note(name, "not-found", depth);
584
+ continue;
585
+ }
586
+ if (seen.has(binding)) continue;
587
+ seen.add(binding);
588
+
589
+ // A value set is COMPLETE only when the declaration established it
590
+ // and nothing can change it afterwards: a `const` with an
591
+ // initialiser. That is the language's own guarantee, so it needs no
592
+ // list of binding kinds and no list of assignment spellings.
593
+ //
594
+ // An earlier draft asked `kind === "let" || kind === "var"`, which
595
+ // is a statement about how the name was INTRODUCED rather than about
596
+ // what the sweep can see. A `param`, a `catch` binding and a
597
+ // destructured one are assignable too (#1569 round 4).
598
+ const complete = binding.kind === "const" && binding.init !== null;
599
+
600
+ // The declaration gave no value: say so, and say so whether or not
601
+ // an assignment later supplied one. Recording the reason only on an
602
+ // empty value list meant ONE conditional assignment erased it, and a
603
+ // parameter whose incoming value is unknowable read as fully
604
+ // resolved from the one branch that happened to be visible.
605
+ if (binding.init === null) {
606
+ const reason: UnresolvedReason =
607
+ binding.kind === "param" || binding.kind === "catch"
608
+ ? "parameter"
609
+ : binding.kind === "import"
610
+ ? "import"
611
+ : binding.kind === "destructured"
612
+ ? "destructured"
613
+ : "no-initialiser";
614
+ note(name, reason, depth);
615
+ }
616
+
617
+ const values = [
618
+ binding.init,
619
+ ...binding.assigned.map((n) => js.slice(n.start, n.end)),
620
+ ].filter((v): v is string => typeof v === "string" && v.length > 0);
621
+ // Nothing readable at all. The reason is already recorded above; the
622
+ // site makes no claim about this identifier, so there is no lower
623
+ // bound to flag.
624
+ if (values.length === 0) continue;
625
+
626
+ // Values exist and the set is not closed, so `view` is a LOWER
627
+ // BOUND — the sweep can see some of what this write can aim at and
628
+ // cannot see all of it. That is the state the chokepoint's green
629
+ // reading must not absorb.
630
+ if (!complete) reassignable = true;
631
+
632
+ for (const v of values) {
633
+ view += ` ${v}`;
634
+ }
635
+ // Follow the chain: re-parse each value's identifiers from the
636
+ // position they were written at, not the write site's.
637
+ //
638
+ // BOTH edges, which is the whole of #1582. The frontier was fed from
639
+ // the initialiser alone, so `p = q` appended the text `q` to `view`
640
+ // and stopped — a target reassigned to an identifier holding a spec
641
+ // path did not resolve. An initialiser and an assignment are
642
+ // symmetric inputs to the same question, and only one of them was
643
+ // being asked. The per-binding dedup (#1569 round 3) is what keeps
644
+ // the extra edges from walking forever.
645
+ const declNode = binding.init
646
+ ? [...walkNodes(tree)].find(
647
+ (n) => n.start === binding.declStart && n.type === "VariableDeclarator",
648
+ )
649
+ : undefined;
650
+ if (declNode?.init) next.push(...valueIdentifiers(declNode.init as AstNode));
651
+ for (const assignedNode of binding.assigned) {
652
+ next.push(...valueIdentifiers(assignedNode));
653
+ }
654
+ }
655
+ frontier = next;
656
+ }
657
+ }
658
+
659
+ sites.push({
660
+ primitive,
661
+ callee: js.slice(callee.start, callee.end).replace(/\s+/g, ""),
662
+ target,
663
+ view: view.replace(/\s+/g, " ").trim(),
664
+ unresolved,
665
+ // A reassignable binding makes the target opaque even when a literal IS
666
+ // visible: the literal may be the initialiser while the value at the
667
+ // write came from an assignment in a form nobody enumerated.
668
+ //
669
+ // And a visible literal does not clear an invisible component. The
670
+ // predicate used to be `!sawLiteral && unresolved.length > 0`, so ONE
671
+ // readable filename cleared a target whose DIRECTORY nobody can see:
672
+ // `join(<unknown>, "report.json")` read as transparent. That is not a
673
+ // path the sweep has read, it is a filename plus a hole, and the hole is
674
+ // the half that decides whether the write lands under `specs/` (#1584).
675
+ opaque: reassignable || unresolved.length > 0,
676
+ reassignable,
677
+ start: node.start,
678
+ });
679
+ }
680
+
681
+ return sites.sort((a, b) => a.start - b.start);
682
+ }
683
+
684
+ /**
685
+ * The 1-based line of each site in the ORIGINAL source, or `null` where it
686
+ * cannot be established.
687
+ *
688
+ * Node positions index the transpiled text, so the line is resolved by ordinal
689
+ * against the original: the Nth call of a given callee name in the tree is the
690
+ * Nth textual occurrence of that name followed by `(`. The two counts are
691
+ * REQUIRED to agree — a `writeFileSync(` inside a comment or a string inflates
692
+ * the text count, and reporting the wrong line silently is worse than
693
+ * reporting none.
694
+ */
695
+ export function resolveLines(
696
+ original: string,
697
+ sites: AstWriteSite[],
698
+ opts: { positionsAreOriginal?: boolean } = {},
699
+ ): (number | null)[] {
700
+ // When nothing was rewritten (a `.js` parse), the offset IS an offset into
701
+ // the text being reported on, so the line is exact and needs no ordinal.
702
+ if (opts.positionsAreOriginal) {
703
+ return sites.map((s) => original.slice(0, s.start).split("\n").length);
704
+ }
705
+
706
+ const trailing = (callee: string): string => callee.slice(callee.lastIndexOf(".") + 1);
707
+
708
+ const byName = new Map<string, number[]>();
709
+ for (const site of sites) {
710
+ const name = trailing(site.callee);
711
+ if (byName.has(name)) continue;
712
+ const offsets: number[] = [];
713
+ const re = new RegExp(`(?<![A-Za-z0-9_$])${name}\\s*\\(`, "g");
714
+ for (const m of original.matchAll(re)) offsets.push(m.index);
715
+ byName.set(name, offsets);
716
+ }
717
+
718
+ const ordinal = new Map<string, number>();
719
+ return sites.map((site) => {
720
+ const name = trailing(site.callee);
721
+ const offsets = byName.get(name)!;
722
+ const n = ordinal.get(name) ?? 0;
723
+ ordinal.set(name, n + 1);
724
+ const total = sites.filter((s) => trailing(s.callee) === name).length;
725
+ if (offsets.length !== total) return null;
726
+ return original.slice(0, offsets[n]!).split("\n").length;
727
+ });
728
+ }