rungate 0.8.3 → 0.8.5
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/ai-review-suppression.ts +295 -0
- package/lib/bun-test-paths.ts +253 -0
- package/lib/conformity.ts +9 -5
- package/lib/finding-jury.ts +20 -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 +485 -28
- package/lib/scaffold/ai-review-step.ts +384 -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/ai-review-findings.ts +45 -2
- 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,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
|
+
}
|