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.
- package/bin/rungate.ts +11 -6
- package/config/prove-evidence.schema.json +21 -3
- package/gates/.gate-salt +1 -1
- package/gates/gate-executor.ts +153 -1
- package/gates/prove.test.ts +12 -6
- package/gates/schema.ts +69 -6
- package/gates/workflow.test.ts +12 -5
- package/hooks/BunTestPathGuard.hook.ts +106 -0
- package/hooks/DocHygiene.hook.ts +2 -1
- package/hooks/GateResultProtection.hook.ts +28 -7
- package/hooks/HookCurrency.hook.ts +48 -1
- package/hooks/TopLevelCdGuard.hook.ts +38 -6
- package/hooks/VerifyPhaseLock.hook.ts +25 -8
- package/hooks/WorkflowStateGuard.hook.ts +24 -7
- package/lib/ai-review-jury.ts +725 -0
- package/lib/ai-review-rounds.ts +791 -4
- package/lib/ai-review-unmeasured.ts +361 -0
- package/lib/bash-write-guard.ts +1235 -102
- package/lib/bun-test-paths.ts +253 -0
- package/lib/cli-commands.ts +252 -11
- package/lib/closing-reference-audit.ts +163 -0
- package/lib/conformity.ts +17 -1
- package/lib/create-sc.ts +45 -12
- package/lib/derived-spec.ts +206 -0
- package/lib/file-claims.ts +335 -0
- package/lib/finding-arbiter.ts +502 -28
- package/lib/finding-jury.ts +61 -5
- package/lib/finding-pr-routing.ts +333 -0
- package/lib/frontmatter.ts +16 -0
- package/lib/gate-check-audit.ts +646 -0
- package/lib/generators/agents-md.ts +29 -0
- package/lib/github.ts +112 -7
- package/lib/hook-tree-currency.ts +494 -0
- package/lib/issue-closure-audit.ts +161 -14
- package/lib/issue-create-override.ts +53 -3
- package/lib/issue-filing-gate.ts +1073 -76
- package/lib/local-review-rounds.ts +523 -0
- package/lib/organize.ts +21 -1
- package/lib/project-state-shape.ts +56 -5
- package/lib/release-preflight.ts +90 -1
- package/lib/repo-path.ts +94 -0
- package/lib/report-provenance.ts +218 -3
- package/lib/risk-tier.ts +302 -0
- package/lib/rounds-to-pass.ts +274 -0
- package/lib/rule-row-drift.ts +199 -0
- package/lib/sc-claim-forms.ts +33 -5
- package/lib/sc-guard.ts +11 -1
- package/lib/sc-id-cross-tree.ts +17 -2
- package/lib/sc-ids.ts +71 -6
- package/lib/sc-reservations.ts +158 -14
- package/lib/scaffold/ai-review-findings.ts +1369 -27
- package/lib/scaffold/ai-review-step.ts +4095 -119
- package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
- package/lib/scaffold/owned-files.ts +14 -0
- package/lib/scaffold/steps.ts +100 -9
- package/lib/scratch-roots.ts +93 -3
- package/lib/spec-updater.ts +22 -2
- 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 +36 -7
- package/lib/write-spec.ts +138 -0
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +41 -1
- package/scripts/arbitrate-finding.ts +330 -12
- package/scripts/audit-specs.ts +225 -24
- package/scripts/convert-spec.ts +7 -2
- package/scripts/create-sc.ts +14 -2
- package/scripts/create-spec.ts +5 -2
- package/scripts/detect-sc-drift.ts +10 -2
- package/scripts/record-ai-review-unmeasured.ts +370 -0
- package/scripts/split-spec.ts +17 -4
- package/scripts/sync-sc-status.ts +14 -2
package/lib/gate-check-audit.ts
CHANGED
|
@@ -20,6 +20,14 @@
|
|
|
20
20
|
* assertion.
|
|
21
21
|
*/
|
|
22
22
|
|
|
23
|
+
import {
|
|
24
|
+
parseTsModule,
|
|
25
|
+
walkNodes,
|
|
26
|
+
calleeRoot,
|
|
27
|
+
rootProperty,
|
|
28
|
+
type AstNode,
|
|
29
|
+
} from "./ts-ast";
|
|
30
|
+
|
|
23
31
|
/** One `test(...)` in a gate suite, with the body a brace matcher found. */
|
|
24
32
|
export interface GateCheck {
|
|
25
33
|
/** The first argument to `test(...)`, as written. */
|
|
@@ -56,6 +64,31 @@ export const WARN_TIER_CHECKS: Readonly<Record<string, string>> = Object.freeze(
|
|
|
56
64
|
"gate. Same basis #409 Decision #9 rejected for spec-decision-compliance: a match over " +
|
|
57
65
|
"prose is not grounds for refusing a run. The reading is lib/ac-quality.ts's " +
|
|
58
66
|
"goalKeywordCoverage so the threshold is drivable from both sides by a test.",
|
|
67
|
+
"before-state-captured: STANDARD+ must have beforeState in workflow-state":
|
|
68
|
+
"#1411 wrote the check and #1384 found it could not fail on the condition it is named " +
|
|
69
|
+
"for. Measured before deciding, over the 155 workflow-state.json files under ~/.rungate " +
|
|
70
|
+
"on 2026-10-24: 30 are STANDARD or THOROUGH, and 30 of those 30 — 100% — have no " +
|
|
71
|
+
"beforeState at all. Not one run in the corpus has ever carried one. The reason is the " +
|
|
72
|
+
"producer, not the runs: nothing in the shipped tree WRITES beforeState. gates/schema.ts " +
|
|
73
|
+
"declares its shape, gates/gate-executor.ts reads it with a `|| null` fallback and " +
|
|
74
|
+
"workflows/prove.js reads it if present; the only thing that describes writing one is " +
|
|
75
|
+
"reference/prompts/goal-skill.md, and this project has been in direct-ship mode since " +
|
|
76
|
+
"2026-10-19, so no goal skill runs. Making this refuse would fail every STANDARD+ run " +
|
|
77
|
+
"immediately — the #423 basis exactly, where 71% was already judged an outage rather " +
|
|
78
|
+
"than a gate. The missing producer is the fixable half and is filed separately; this " +
|
|
79
|
+
"entry is the honest reading until something writes the field.",
|
|
80
|
+
"brief-ac-alignment: brief covers all ACs":
|
|
81
|
+
"#1384 named this through the widened path-level predicate, and the warn-return is a " +
|
|
82
|
+
"deliberate scope-out rather than a swallowed refusal. The condition the check is named " +
|
|
83
|
+
"for DOES refuse: lib/brief-ac-alignment.ts returns BRIEF_ABSENT with a refusal when " +
|
|
84
|
+
"Marcus was spawned and no brief exists, and IDS_MISSING when the brief omits an AC, " +
|
|
85
|
+
"and gates/workflow.test.ts asserts `reading.refusal` is null. The warned path is the " +
|
|
86
|
+
"fourth reading, NOT_APPLICABLE, which fires only when Marcus was never spawned — so " +
|
|
87
|
+
"nothing was expected to write a brief. That reading exists because the inline version " +
|
|
88
|
+
"returned bare in two places and made 'decided nothing was wrong' and 'declined to " +
|
|
89
|
+
"look' the same observation; per .claude/rules/config-access.md that is UNMEASURED, not " +
|
|
90
|
+
"a pass, and it is reported with the resolved path rather than silently. Turning a " +
|
|
91
|
+
"scope-out into a refusal would fail every run that does not spawn Marcus.",
|
|
59
92
|
});
|
|
60
93
|
|
|
61
94
|
/**
|
|
@@ -166,6 +199,619 @@ export function checksWithoutAssertions(source: string): GateCheck[] {
|
|
|
166
199
|
return gateChecks(source).filter(c => !c.hasAssertion && c.name !== STANDALONE_STUB_NAME);
|
|
167
200
|
}
|
|
168
201
|
|
|
202
|
+
/** One `console.warn` that leads out of a check with nothing asserted (#1384). */
|
|
203
|
+
export interface WarnReturnPath {
|
|
204
|
+
/** The check's name, as written. */
|
|
205
|
+
check: string;
|
|
206
|
+
/** 1-indexed line of the `test(` call. */
|
|
207
|
+
line: number;
|
|
208
|
+
/** 1-indexed line of the `console.warn` that leads the path. */
|
|
209
|
+
warnLine: number;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* The view this detector takes, stated rather than left to be inferred.
|
|
214
|
+
*
|
|
215
|
+
* It is anchored on `console.warn`, and that is a deliberate narrowing. The
|
|
216
|
+
* general property — "a path through the check executes no assertion" — holds
|
|
217
|
+
* for `if (tier === "LIGHT") return;`, which opens most checks in the suite
|
|
218
|
+
* and is legitimate scoping rather than a swallowed refusal. A predicate that
|
|
219
|
+
* named those would report the whole file and be switched off within a day.
|
|
220
|
+
*
|
|
221
|
+
* A `console.warn` is the author writing down that something is wrong. A warn
|
|
222
|
+
* followed by a path that leaves the check without asserting is that author
|
|
223
|
+
* declining to refuse — which is the thing `WARN_TIER_CHECKS` exists to make
|
|
224
|
+
* someone decide about, in the one place the body-level predicate cannot see.
|
|
225
|
+
*
|
|
226
|
+
* Per `.claude/rules/checks-must-be-able-to-fail.md`, the direction this is
|
|
227
|
+
* allowed to be wrong in is toward NOT naming: an intervening `expect` at any
|
|
228
|
+
* depth disqualifies a candidate, even one a branch could skip. A missed check
|
|
229
|
+
* costs an entry nobody wrote; a false one costs the list its credibility.
|
|
230
|
+
*
|
|
231
|
+
* ## Why this is an AST and not a token scan (#1555)
|
|
232
|
+
*
|
|
233
|
+
* The question "does a path out of this `console.warn` leave the check without
|
|
234
|
+
* asserting" is a **reachability analysis**. Until #1555 it was a forward token
|
|
235
|
+
* scan over the check body that tracked brace depth, paired `else` to `if` by
|
|
236
|
+
* remembering head positions per depth, and carried a running minimum depth
|
|
237
|
+
* between tokens to notice a block closing. That is a parser, written badly,
|
|
238
|
+
* and it was wrong five times across four revisions of #1539 — three of them
|
|
239
|
+
* found one at a time by an AI reviewer handing back one side of the shape per
|
|
240
|
+
* round, and one of those three a regression a previous round's own fix had
|
|
241
|
+
* introduced.
|
|
242
|
+
*
|
|
243
|
+
* #1555 enumerated every way a path out of a warn can terminate — twelve
|
|
244
|
+
* shapes — and measured the merged scan against all of them. **Three were
|
|
245
|
+
* wrong**, not the two the issue predicted: `try { warn; return } finally
|
|
246
|
+
* { expect }`, a warn inside a callback with an `expect` after it, and a
|
|
247
|
+
* `throw` after the warn. Each is a direct question about the tree:
|
|
248
|
+
* `ThrowStatement`, `TryStatement.finalizer`, a closure as a node boundary,
|
|
249
|
+
* `IfStatement.alternate`, `SwitchCase`. The scan had to approximate all of
|
|
250
|
+
* them from brace depth, and shape 7 (warn OUTSIDE a closure, right) beside
|
|
251
|
+
* shape 12 (warn INSIDE one, wrong) is what that looks like: brace depth
|
|
252
|
+
* getting the right answer for the wrong reason.
|
|
253
|
+
*
|
|
254
|
+
* The parser is `acorn`, through `lib/ts-ast.ts`, which is this repository's
|
|
255
|
+
* existing binding for "a detector that must not be fooled by its own
|
|
256
|
+
* fixtures" (#968) and the one five other `lib/` modules already use. #1555
|
|
257
|
+
* recommended TypeScript's own parser on the grounds that it is a declared
|
|
258
|
+
* dependency; it is declared as a **devDependency**, and `lib/` is published
|
|
259
|
+
* (`files[]` in package.json), so a published module importing it would be
|
|
260
|
+
* broken in every consumer's install. `acorn` is a runtime dependency.
|
|
261
|
+
*
|
|
262
|
+
* The consequence of that choice, which the code below has to carry:
|
|
263
|
+
* `parseTsModule` transpiles the types off before parsing, and
|
|
264
|
+
* `Bun.Transpiler` drops comments and blank lines — so **node positions index
|
|
265
|
+
* the transpiled text and cannot be converted to a line in the original**.
|
|
266
|
+
* `warnLine` is therefore resolved by ordinal against the original body, and
|
|
267
|
+
* the counts are required to agree rather than assumed to (`warnOffsets`).
|
|
268
|
+
*/
|
|
269
|
+
|
|
270
|
+
/** The decision for one path out of a warn, and what it is allowed to be. */
|
|
271
|
+
interface PathFlow {
|
|
272
|
+
/** An `expect` MAY execute along this path. Disqualifies the candidate. */
|
|
273
|
+
expect: boolean;
|
|
274
|
+
/** Control may reach the end of the construct normally. */
|
|
275
|
+
fall: boolean;
|
|
276
|
+
/** Control may execute a `return` — a normal exit from the function. */
|
|
277
|
+
ret: boolean;
|
|
278
|
+
/** Control may `break` out of the enclosing loop or switch. */
|
|
279
|
+
brk: boolean;
|
|
280
|
+
/** Control may `continue` the enclosing loop. */
|
|
281
|
+
cont: boolean;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
const LOOPS = new Set([
|
|
285
|
+
"ForStatement",
|
|
286
|
+
"ForInStatement",
|
|
287
|
+
"ForOfStatement",
|
|
288
|
+
"WhileStatement",
|
|
289
|
+
"DoWhileStatement",
|
|
290
|
+
]);
|
|
291
|
+
|
|
292
|
+
const FUNCTIONS = new Set([
|
|
293
|
+
"ArrowFunctionExpression",
|
|
294
|
+
"FunctionExpression",
|
|
295
|
+
"FunctionDeclaration",
|
|
296
|
+
]);
|
|
297
|
+
|
|
298
|
+
function isNodeLike(value: unknown): value is AstNode {
|
|
299
|
+
return (
|
|
300
|
+
typeof value === "object" &&
|
|
301
|
+
value !== null &&
|
|
302
|
+
typeof (value as AstNode).type === "string" &&
|
|
303
|
+
typeof (value as AstNode).start === "number"
|
|
304
|
+
);
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/**
|
|
308
|
+
* `expect(...)` in any spelling, including `expect<T>(...)` (the type argument
|
|
309
|
+
* is gone by the time acorn sees it) and `expect(x).toBe(y)`.
|
|
310
|
+
*
|
|
311
|
+
* `calleeRoot` is what makes this one question rather than a list of
|
|
312
|
+
* spellings: it follows member and call chains to the identifier at the root,
|
|
313
|
+
* so `s.expect(...)` resolves to `s` and is correctly NOT an assertion — the
|
|
314
|
+
* boundary the old regex had to hand-check with a character class.
|
|
315
|
+
*/
|
|
316
|
+
function isExpectCall(node: AstNode): boolean {
|
|
317
|
+
return node.type === "CallExpression" && calleeRoot(node.callee) === "expect";
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
/** `console.warn(...)`. */
|
|
321
|
+
function isWarnCall(node: AstNode): boolean {
|
|
322
|
+
return (
|
|
323
|
+
node.type === "CallExpression" &&
|
|
324
|
+
calleeRoot(node.callee) === "console" &&
|
|
325
|
+
rootProperty(node.callee) === "warn"
|
|
326
|
+
);
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* Does an `expect` appear anywhere under this node, INCLUDING inside nested
|
|
331
|
+
* functions?
|
|
332
|
+
*
|
|
333
|
+
* Including them is deliberate and is the allowed direction. A callback passed
|
|
334
|
+
* to `forEach` runs synchronously and its assertion does execute; a callback
|
|
335
|
+
* stored and never called does not, and counting it costs a check nobody
|
|
336
|
+
* names. Per the rule above, that is the direction to be wrong in.
|
|
337
|
+
*/
|
|
338
|
+
function hasExpectIn(node: unknown): boolean {
|
|
339
|
+
if (!isNodeLike(node)) return false;
|
|
340
|
+
for (const n of walkNodes(node)) if (isExpectCall(n)) return true;
|
|
341
|
+
return false;
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/** Execute `statements` from `from` to the end of the list. */
|
|
345
|
+
function seqFlow(statements: AstNode[], from: number): PathFlow {
|
|
346
|
+
const flow: PathFlow = { expect: false, fall: true, ret: false, brk: false, cont: false };
|
|
347
|
+
for (let i = from; i < statements.length; i++) {
|
|
348
|
+
if (!flow.fall) break;
|
|
349
|
+
const s = stmtFlow(statements[i]!);
|
|
350
|
+
flow.expect ||= s.expect;
|
|
351
|
+
flow.ret ||= s.ret;
|
|
352
|
+
flow.brk ||= s.brk;
|
|
353
|
+
flow.cont ||= s.cont;
|
|
354
|
+
flow.fall = s.fall;
|
|
355
|
+
}
|
|
356
|
+
return flow;
|
|
357
|
+
}
|
|
358
|
+
|
|
359
|
+
/** Enter one statement. */
|
|
360
|
+
function stmtFlow(node: AstNode): PathFlow {
|
|
361
|
+
const base = (over: Partial<PathFlow>): PathFlow => ({
|
|
362
|
+
expect: false,
|
|
363
|
+
fall: true,
|
|
364
|
+
ret: false,
|
|
365
|
+
brk: false,
|
|
366
|
+
cont: false,
|
|
367
|
+
...over,
|
|
368
|
+
});
|
|
369
|
+
switch (node.type) {
|
|
370
|
+
case "ReturnStatement":
|
|
371
|
+
return base({ expect: hasExpectIn(node.argument), fall: false, ret: true });
|
|
372
|
+
// A `throw` is not an exit this detector cares about: the check FAILS on
|
|
373
|
+
// that path, so it is not a swallowed refusal. `ret` stays false, which is
|
|
374
|
+
// the whole of shape 3.
|
|
375
|
+
case "ThrowStatement":
|
|
376
|
+
return base({ expect: hasExpectIn(node.argument), fall: false });
|
|
377
|
+
case "BreakStatement":
|
|
378
|
+
return base({ fall: false, brk: true });
|
|
379
|
+
case "ContinueStatement":
|
|
380
|
+
return base({ fall: false, cont: true });
|
|
381
|
+
case "BlockStatement":
|
|
382
|
+
return seqFlow((node.body ?? []) as AstNode[], 0);
|
|
383
|
+
case "IfStatement": {
|
|
384
|
+
const c = stmtFlow(node.consequent as AstNode);
|
|
385
|
+
const a = isNodeLike(node.alternate) ? stmtFlow(node.alternate) : base({});
|
|
386
|
+
return {
|
|
387
|
+
expect: hasExpectIn(node.test) || c.expect || a.expect,
|
|
388
|
+
fall: c.fall || a.fall,
|
|
389
|
+
ret: c.ret || a.ret,
|
|
390
|
+
brk: c.brk || a.brk,
|
|
391
|
+
cont: c.cont || a.cont,
|
|
392
|
+
};
|
|
393
|
+
}
|
|
394
|
+
case "ForStatement":
|
|
395
|
+
case "ForInStatement":
|
|
396
|
+
case "ForOfStatement":
|
|
397
|
+
case "WhileStatement":
|
|
398
|
+
case "DoWhileStatement": {
|
|
399
|
+
const b = stmtFlow(node.body as AstNode);
|
|
400
|
+
// `break` and `continue` are absorbed by the loop rather than leaving
|
|
401
|
+
// the check — shapes 4 and 5. The loop may also run zero times, so it
|
|
402
|
+
// always falls through.
|
|
403
|
+
return base({
|
|
404
|
+
expect:
|
|
405
|
+
b.expect ||
|
|
406
|
+
hasExpectIn(node.test) ||
|
|
407
|
+
hasExpectIn(node.init) ||
|
|
408
|
+
hasExpectIn(node.update) ||
|
|
409
|
+
hasExpectIn(node.right),
|
|
410
|
+
ret: b.ret,
|
|
411
|
+
});
|
|
412
|
+
}
|
|
413
|
+
case "SwitchStatement": {
|
|
414
|
+
const flow = base({ expect: hasExpectIn(node.discriminant) });
|
|
415
|
+
for (const c of (node.cases ?? []) as AstNode[]) {
|
|
416
|
+
const cf = seqFlow((c.consequent ?? []) as AstNode[], 0);
|
|
417
|
+
flow.expect ||= cf.expect;
|
|
418
|
+
flow.ret ||= cf.ret;
|
|
419
|
+
flow.cont ||= cf.cont;
|
|
420
|
+
}
|
|
421
|
+
return flow;
|
|
422
|
+
}
|
|
423
|
+
case "TryStatement": {
|
|
424
|
+
const t = stmtFlow(node.block as AstNode);
|
|
425
|
+
const handler = node.handler as AstNode | undefined;
|
|
426
|
+
const h = isNodeLike(handler?.body) ? stmtFlow(handler.body as AstNode) : null;
|
|
427
|
+
const fin = isNodeLike(node.finalizer) ? stmtFlow(node.finalizer) : null;
|
|
428
|
+
const flow: PathFlow = {
|
|
429
|
+
expect: t.expect || !!h?.expect || !!fin?.expect,
|
|
430
|
+
fall: t.fall || !!h?.fall,
|
|
431
|
+
ret: t.ret || !!h?.ret,
|
|
432
|
+
brk: t.brk || !!h?.brk,
|
|
433
|
+
cont: t.cont || !!h?.cont,
|
|
434
|
+
};
|
|
435
|
+
// A finalizer that does not fall through replaces every completion of
|
|
436
|
+
// the block it guards.
|
|
437
|
+
if (fin && !fin.fall) {
|
|
438
|
+
flow.fall = false;
|
|
439
|
+
flow.ret = fin.ret;
|
|
440
|
+
flow.brk = fin.brk;
|
|
441
|
+
flow.cont = fin.cont;
|
|
442
|
+
}
|
|
443
|
+
return flow;
|
|
444
|
+
}
|
|
445
|
+
case "LabeledStatement": {
|
|
446
|
+
const b = stmtFlow(node.body as AstNode);
|
|
447
|
+
return { ...b, fall: b.fall || b.brk, brk: false };
|
|
448
|
+
}
|
|
449
|
+
// A function DECLARATION is not executed where it is written.
|
|
450
|
+
case "FunctionDeclaration":
|
|
451
|
+
case "ClassDeclaration":
|
|
452
|
+
case "EmptyStatement":
|
|
453
|
+
return base({});
|
|
454
|
+
default:
|
|
455
|
+
return base({ expect: hasExpectIn(node) });
|
|
456
|
+
}
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
/** `acc`, then `rest` — `rest` only runs if `acc` can fall into it. */
|
|
460
|
+
function chain(acc: PathFlow, rest: PathFlow): PathFlow {
|
|
461
|
+
if (!acc.fall) return acc;
|
|
462
|
+
return {
|
|
463
|
+
expect: acc.expect || rest.expect,
|
|
464
|
+
fall: rest.fall,
|
|
465
|
+
ret: acc.ret || rest.ret,
|
|
466
|
+
brk: acc.brk || rest.brk,
|
|
467
|
+
cont: acc.cont || rest.cont,
|
|
468
|
+
};
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
/**
|
|
472
|
+
* Walk OUT from the warn to the check's own boundary, accumulating what the
|
|
473
|
+
* path meets on the way.
|
|
474
|
+
*
|
|
475
|
+
* Returns whether an `expect` is reachable, and whether a NORMAL exit from the
|
|
476
|
+
* check is reachable. A `throw` is neither — it reaches no `expect` and no
|
|
477
|
+
* normal exit, so it is not a finding.
|
|
478
|
+
*/
|
|
479
|
+
function forwardFromWarn(
|
|
480
|
+
warn: AstNode,
|
|
481
|
+
callback: AstNode,
|
|
482
|
+
parentOf: Map<AstNode, AstNode>,
|
|
483
|
+
): { expect: boolean; normalExit: boolean } {
|
|
484
|
+
// An `expect` sharing the warn's own STATEMENT — `a ? console.warn(x) :
|
|
485
|
+
// expect(y)`, or an `expect` further along a comma or logical chain. The
|
|
486
|
+
// walk below starts at statement granularity and would step straight past
|
|
487
|
+
// it, so it is taken first. Counting an assertion that a branch could skip
|
|
488
|
+
// is the direction this is allowed to be wrong in.
|
|
489
|
+
let stmt: AstNode = warn;
|
|
490
|
+
for (;;) {
|
|
491
|
+
const up = parentOf.get(stmt);
|
|
492
|
+
if (!up || /Statement$|Declaration$/.test(stmt.type)) break;
|
|
493
|
+
stmt = up;
|
|
494
|
+
}
|
|
495
|
+
|
|
496
|
+
let acc: PathFlow = {
|
|
497
|
+
expect: hasExpectIn(stmt),
|
|
498
|
+
fall: true,
|
|
499
|
+
ret: false,
|
|
500
|
+
brk: false,
|
|
501
|
+
cont: false,
|
|
502
|
+
};
|
|
503
|
+
let child: AstNode = warn;
|
|
504
|
+
let parent = parentOf.get(child);
|
|
505
|
+
while (parent) {
|
|
506
|
+
if (parent === callback) break;
|
|
507
|
+
switch (parent.type) {
|
|
508
|
+
case "BlockStatement":
|
|
509
|
+
case "Program": {
|
|
510
|
+
const body = (parent.body ?? []) as AstNode[];
|
|
511
|
+
const idx = body.indexOf(child);
|
|
512
|
+
if (idx >= 0) acc = chain(acc, seqFlow(body, idx + 1));
|
|
513
|
+
break;
|
|
514
|
+
}
|
|
515
|
+
case "SwitchCase": {
|
|
516
|
+
const body = (parent.consequent ?? []) as AstNode[];
|
|
517
|
+
const idx = body.indexOf(child);
|
|
518
|
+
if (idx >= 0) acc = chain(acc, seqFlow(body, idx + 1));
|
|
519
|
+
break;
|
|
520
|
+
}
|
|
521
|
+
case "SwitchStatement": {
|
|
522
|
+
// Falling out of a case runs the cases below it; `break` leaves the
|
|
523
|
+
// switch. Either way the path continues after the switch.
|
|
524
|
+
const cases = (parent.cases ?? []) as AstNode[];
|
|
525
|
+
const idx = cases.indexOf(child);
|
|
526
|
+
if (idx >= 0 && acc.fall) {
|
|
527
|
+
for (let i = idx + 1; i < cases.length; i++) {
|
|
528
|
+
const cf = seqFlow((cases[i]!.consequent ?? []) as AstNode[], 0);
|
|
529
|
+
acc.expect ||= cf.expect;
|
|
530
|
+
acc.ret ||= cf.ret;
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
acc.fall = acc.fall || acc.brk;
|
|
534
|
+
acc.brk = false;
|
|
535
|
+
break;
|
|
536
|
+
}
|
|
537
|
+
case "TryStatement": {
|
|
538
|
+
// The finalizer runs on EVERY exit from the block it guards —
|
|
539
|
+
// including the `return`. Shape 11.
|
|
540
|
+
if (child === parent.block || child === parent.handler) {
|
|
541
|
+
const finalizer = asNode(parent.finalizer);
|
|
542
|
+
if (finalizer) {
|
|
543
|
+
const f = stmtFlow(finalizer);
|
|
544
|
+
if (acc.fall || acc.ret || acc.brk || acc.cont) acc.expect ||= f.expect;
|
|
545
|
+
if (!f.fall) {
|
|
546
|
+
acc.fall = false;
|
|
547
|
+
acc.ret = f.ret;
|
|
548
|
+
acc.brk = f.brk;
|
|
549
|
+
acc.cont = f.cont;
|
|
550
|
+
}
|
|
551
|
+
}
|
|
552
|
+
}
|
|
553
|
+
break;
|
|
554
|
+
}
|
|
555
|
+
case "LabeledStatement":
|
|
556
|
+
acc.fall = acc.fall || acc.brk;
|
|
557
|
+
acc.brk = false;
|
|
558
|
+
break;
|
|
559
|
+
default: {
|
|
560
|
+
if (LOOPS.has(parent.type) && child === parent.body) {
|
|
561
|
+
// Both `continue` and falling off the end of the body re-enter it,
|
|
562
|
+
// so anything the body asserts is reachable; `break` and the loop
|
|
563
|
+
// finishing both continue after it. Shapes 4 and 5.
|
|
564
|
+
if (acc.fall || acc.cont) {
|
|
565
|
+
acc.expect ||=
|
|
566
|
+
hasExpectIn(parent.body) ||
|
|
567
|
+
hasExpectIn(parent.test) ||
|
|
568
|
+
hasExpectIn(parent.update);
|
|
569
|
+
}
|
|
570
|
+
acc.fall = acc.fall || acc.cont || acc.brk;
|
|
571
|
+
acc.brk = false;
|
|
572
|
+
acc.cont = false;
|
|
573
|
+
} else if (FUNCTIONS.has(parent.type)) {
|
|
574
|
+
// A nested closure is a node boundary, not a brace depth. Its
|
|
575
|
+
// `return` exits the CLOSURE and resumes the caller, so the path
|
|
576
|
+
// carries on at the call site rather than leaving the check.
|
|
577
|
+
// Shape 12 — and shape 7 is the same rule seen from outside.
|
|
578
|
+
acc.fall = acc.fall || acc.ret;
|
|
579
|
+
acc.ret = false;
|
|
580
|
+
acc.brk = false;
|
|
581
|
+
acc.cont = false;
|
|
582
|
+
}
|
|
583
|
+
break;
|
|
584
|
+
}
|
|
585
|
+
}
|
|
586
|
+
child = parent;
|
|
587
|
+
parent = parentOf.get(parent);
|
|
588
|
+
}
|
|
589
|
+
return { expect: acc.expect, normalExit: acc.fall || acc.ret };
|
|
590
|
+
}
|
|
591
|
+
|
|
592
|
+
function asNode(value: unknown): AstNode | null {
|
|
593
|
+
return isNodeLike(value) ? value : null;
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
/**
|
|
597
|
+
* Does an assertion run on EVERY path that reaches this warn?
|
|
598
|
+
*
|
|
599
|
+
* Dominance, not "an `expect` appears earlier in the text". The two differ on
|
|
600
|
+
* exactly the shape PR #1539's third review round was about: in
|
|
601
|
+
* `if (a) expect(p); else console.warn(x);` the assertion is earlier and can
|
|
602
|
+
* never have run on the path that reaches the warn. The AST answers it by
|
|
603
|
+
* construction — only a PRECEDING SIBLING in an enclosing statement list can
|
|
604
|
+
* dominate, and `IfStatement.alternate` is not a sibling of its consequent.
|
|
605
|
+
*/
|
|
606
|
+
function assertionDominates(
|
|
607
|
+
warn: AstNode,
|
|
608
|
+
callback: AstNode,
|
|
609
|
+
parentOf: Map<AstNode, AstNode>,
|
|
610
|
+
): boolean {
|
|
611
|
+
let child: AstNode = warn;
|
|
612
|
+
let parent = parentOf.get(child);
|
|
613
|
+
while (parent) {
|
|
614
|
+
if (parent.type === "BlockStatement" || parent.type === "Program") {
|
|
615
|
+
const body = (parent.body ?? []) as AstNode[];
|
|
616
|
+
const idx = body.indexOf(child);
|
|
617
|
+
for (let i = 0; i < idx; i++) if (alwaysAsserts(body[i]!)) return true;
|
|
618
|
+
}
|
|
619
|
+
if (parent.type === "SwitchCase") {
|
|
620
|
+
const body = (parent.consequent ?? []) as AstNode[];
|
|
621
|
+
const idx = body.indexOf(child);
|
|
622
|
+
for (let i = 0; i < idx; i++) if (alwaysAsserts(body[i]!)) return true;
|
|
623
|
+
}
|
|
624
|
+
if (parent === callback) break;
|
|
625
|
+
child = parent;
|
|
626
|
+
parent = parentOf.get(parent);
|
|
627
|
+
}
|
|
628
|
+
return false;
|
|
629
|
+
}
|
|
630
|
+
|
|
631
|
+
/** Does entering this statement guarantee an `expect` runs? */
|
|
632
|
+
function alwaysAsserts(node: AstNode): boolean {
|
|
633
|
+
switch (node.type) {
|
|
634
|
+
case "BlockStatement":
|
|
635
|
+
return ((node.body ?? []) as AstNode[]).some(alwaysAsserts);
|
|
636
|
+
case "IfStatement":
|
|
637
|
+
return (
|
|
638
|
+
isNodeLike(node.alternate) &&
|
|
639
|
+
alwaysAsserts(node.consequent as AstNode) &&
|
|
640
|
+
alwaysAsserts(node.alternate)
|
|
641
|
+
);
|
|
642
|
+
case "TryStatement": {
|
|
643
|
+
if (isNodeLike(node.finalizer) && alwaysAsserts(node.finalizer)) return true;
|
|
644
|
+
const handler = node.handler as AstNode | undefined;
|
|
645
|
+
const blockAsserts = alwaysAsserts(node.block as AstNode);
|
|
646
|
+
if (!blockAsserts) return false;
|
|
647
|
+
return !handler || alwaysAsserts(handler.body as AstNode);
|
|
648
|
+
}
|
|
649
|
+
case "LabeledStatement":
|
|
650
|
+
case "DoWhileStatement":
|
|
651
|
+
return alwaysAsserts(node.body as AstNode);
|
|
652
|
+
case "SwitchStatement": {
|
|
653
|
+
const cases = (node.cases ?? []) as AstNode[];
|
|
654
|
+
if (!cases.some(c => !isNodeLike(c.test))) return false;
|
|
655
|
+
return cases.every(c => ((c.consequent ?? []) as AstNode[]).some(alwaysAsserts));
|
|
656
|
+
}
|
|
657
|
+
// A loop may run zero times, and a declaration is not executed here.
|
|
658
|
+
case "ForStatement":
|
|
659
|
+
case "ForInStatement":
|
|
660
|
+
case "ForOfStatement":
|
|
661
|
+
case "WhileStatement":
|
|
662
|
+
case "FunctionDeclaration":
|
|
663
|
+
case "ClassDeclaration":
|
|
664
|
+
return false;
|
|
665
|
+
default:
|
|
666
|
+
return hasExpectIn(node);
|
|
667
|
+
}
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
/** Every `test(...)` callback in a parsed module, in source order. */
|
|
671
|
+
function testCallbacks(tree: AstNode): { name: string; callback: AstNode }[] {
|
|
672
|
+
const out: { name: string; callback: AstNode; at: number }[] = [];
|
|
673
|
+
for (const node of walkNodes(tree)) {
|
|
674
|
+
if (node.type !== "CallExpression") continue;
|
|
675
|
+
const callee = node.callee as AstNode | undefined;
|
|
676
|
+
// `test(...)` exactly, matching what `gateChecks` enumerates — not
|
|
677
|
+
// `test.each`, not `describe`.
|
|
678
|
+
if (callee?.type !== "Identifier" || callee.name !== "test") continue;
|
|
679
|
+
const args = (node.arguments ?? []) as AstNode[];
|
|
680
|
+
const first = args[0];
|
|
681
|
+
if (first?.type !== "Literal" || typeof first.value !== "string") continue;
|
|
682
|
+
const callback = args.find(a => FUNCTIONS.has(a.type));
|
|
683
|
+
if (!callback) continue;
|
|
684
|
+
out.push({ name: first.value, callback, at: node.start });
|
|
685
|
+
}
|
|
686
|
+
out.sort((a, b) => a.at - b.at);
|
|
687
|
+
return out.map(({ name, callback }) => ({ name, callback }));
|
|
688
|
+
}
|
|
689
|
+
|
|
690
|
+
/**
|
|
691
|
+
* The offsets of each real `console.warn(` in an original check body.
|
|
692
|
+
*
|
|
693
|
+
* Node positions index the TRANSPILED text (see the module note above), so a
|
|
694
|
+
* warn's line in the original file cannot be read off its node. It is resolved
|
|
695
|
+
* by ordinal instead — and the two counts are REQUIRED to agree rather than
|
|
696
|
+
* assumed to. A `console.warn(` inside a comment or a string literal would
|
|
697
|
+
* make the text count exceed the AST count, and silently reporting the wrong
|
|
698
|
+
* line is the kind of quiet wrongness this whole module exists to stop.
|
|
699
|
+
*/
|
|
700
|
+
function warnOffsets(body: string): number[] {
|
|
701
|
+
const out: number[] = [];
|
|
702
|
+
for (const m of body.matchAll(/console\s*\.\s*warn\s*\(/g)) out.push(m.index);
|
|
703
|
+
return out;
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
/**
|
|
707
|
+
* Every `console.warn` whose path leaves the check with nothing asserted.
|
|
708
|
+
*
|
|
709
|
+
* Two conditions, and both are about the PATH rather than the body:
|
|
710
|
+
*
|
|
711
|
+
* - no assertion DOMINATES the warn — nothing that runs on every path to it;
|
|
712
|
+
* - from the warn, no `expect` is reachable before the check is left by a
|
|
713
|
+
* normal exit (a `return`, or running off the end of the body).
|
|
714
|
+
*
|
|
715
|
+
* A path that can only leave by `throw` is not a finding: the check fails on
|
|
716
|
+
* it, so it is not a swallowed refusal.
|
|
717
|
+
*
|
|
718
|
+
* Throws rather than returning `[]` when the source cannot be parsed, or when
|
|
719
|
+
* the tree disagrees with `gateChecks` about what the checks are. A parser
|
|
720
|
+
* that stopped parsing and a file that is clean otherwise produce the same
|
|
721
|
+
* empty list, which is the first shape in
|
|
722
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
723
|
+
*/
|
|
724
|
+
export function unassertedWarnPaths(source: string): WarnReturnPath[] {
|
|
725
|
+
const checks = gateChecks(source);
|
|
726
|
+
// No early return on an empty check list. A source that failed to parse
|
|
727
|
+
// yields no checks for the brace matcher either, so short-circuiting here
|
|
728
|
+
// would convert every unparseable file into a clean one — the fail-open in
|
|
729
|
+
// `.claude/rules/checks-must-be-able-to-fail.md`. An empty source parses,
|
|
730
|
+
// agrees with the tree at zero, and returns [] through the normal path.
|
|
731
|
+
const parsed = parseTsModule(source);
|
|
732
|
+
if (!parsed) {
|
|
733
|
+
throw new Error(
|
|
734
|
+
"unassertedWarnPaths: UNMEASURED — the source did not transpile or did not parse, so " +
|
|
735
|
+
"no reachability reading was taken. This is not an empty list of findings.",
|
|
736
|
+
);
|
|
737
|
+
}
|
|
738
|
+
|
|
739
|
+
// `gateChecks` stays the single enumerator of what a check IS, and the tree
|
|
740
|
+
// is a lookup rather than a second opinion. Two enumerators that disagreed
|
|
741
|
+
// would silently drop a check from the join — so they are required to agree
|
|
742
|
+
// here instead, by name and in order.
|
|
743
|
+
const fromTree = testCallbacks(parsed.tree);
|
|
744
|
+
const treeNames = fromTree.map(c => c.name).join("\n");
|
|
745
|
+
const checkNames = checks.map(c => c.name).join("\n");
|
|
746
|
+
if (treeNames !== checkNames) {
|
|
747
|
+
throw new Error(
|
|
748
|
+
`unassertedWarnPaths: UNMEASURED — the parsed tree sees ${fromTree.length} checks and ` +
|
|
749
|
+
`gateChecks sees ${checks.length}, or they are in a different order. One of the two is ` +
|
|
750
|
+
"reading less than the file.",
|
|
751
|
+
);
|
|
752
|
+
}
|
|
753
|
+
|
|
754
|
+
const parentOf = new Map<AstNode, AstNode>();
|
|
755
|
+
for (const node of walkNodes(parsed.tree)) {
|
|
756
|
+
for (const value of Object.values(node)) {
|
|
757
|
+
if (Array.isArray(value)) {
|
|
758
|
+
for (const child of value) if (isNodeLike(child)) parentOf.set(child, node);
|
|
759
|
+
} else if (isNodeLike(value)) {
|
|
760
|
+
parentOf.set(value, node);
|
|
761
|
+
}
|
|
762
|
+
}
|
|
763
|
+
}
|
|
764
|
+
|
|
765
|
+
const out: WarnReturnPath[] = [];
|
|
766
|
+
for (let i = 0; i < checks.length; i++) {
|
|
767
|
+
const check = checks[i]!;
|
|
768
|
+
if (check.name === STANDALONE_STUB_NAME) continue;
|
|
769
|
+
const { callback } = fromTree[i]!;
|
|
770
|
+
|
|
771
|
+
const warns = [...walkNodes(callback)].filter(isWarnCall).sort((a, b) => a.start - b.start);
|
|
772
|
+
const offsets = warnOffsets(check.body);
|
|
773
|
+
if (warns.length !== offsets.length) {
|
|
774
|
+
throw new Error(
|
|
775
|
+
`unassertedWarnPaths: UNMEASURED — "${check.name}" has ${warns.length} console.warn ` +
|
|
776
|
+
`calls in the tree and ${offsets.length} in its source text, so a finding's line ` +
|
|
777
|
+
"cannot be resolved by ordinal. A `console.warn(` in a comment or a string would do " +
|
|
778
|
+
"this; reporting the wrong line silently would be worse.",
|
|
779
|
+
);
|
|
780
|
+
}
|
|
781
|
+
|
|
782
|
+
for (let w = 0; w < warns.length; w++) {
|
|
783
|
+
const warn = warns[w]!;
|
|
784
|
+
if (assertionDominates(warn, callback, parentOf)) continue;
|
|
785
|
+
const after = forwardFromWarn(warn, callback, parentOf);
|
|
786
|
+
if (after.expect || !after.normalExit) continue;
|
|
787
|
+
out.push({
|
|
788
|
+
check: check.name,
|
|
789
|
+
line: check.line,
|
|
790
|
+
// The body starts partway through the `test(` line, so the warn's line
|
|
791
|
+
// is the check's line plus the newlines before it inside the body.
|
|
792
|
+
warnLine:
|
|
793
|
+
check.line + (check.body.slice(0, offsets[w]!).match(/\n/g) || []).length,
|
|
794
|
+
});
|
|
795
|
+
}
|
|
796
|
+
}
|
|
797
|
+
return out;
|
|
798
|
+
}
|
|
799
|
+
|
|
800
|
+
/**
|
|
801
|
+
* Every check that cannot fail on the condition it is named for — the union of
|
|
802
|
+
* the body-level and path-level readings, in source order.
|
|
803
|
+
*
|
|
804
|
+
* This is the one binding the audit reads. `checksWithoutAssertions` stays
|
|
805
|
+
* exported because it is the narrower of the two and the tests use it as the
|
|
806
|
+
* recorded baseline: it is what the audit could see before #1384.
|
|
807
|
+
*/
|
|
808
|
+
export function checksThatCannotFail(source: string): GateCheck[] {
|
|
809
|
+
const warned = new Set(unassertedWarnPaths(source).map(p => p.check));
|
|
810
|
+
return gateChecks(source).filter(
|
|
811
|
+
c => c.name !== STANDALONE_STUB_NAME && (!c.hasAssertion || warned.has(c.name)),
|
|
812
|
+
);
|
|
813
|
+
}
|
|
814
|
+
|
|
169
815
|
/** The standalone placeholders, so their emptiness can be asserted. */
|
|
170
816
|
export function standaloneStubs(source: string): GateCheck[] {
|
|
171
817
|
return gateChecks(source).filter(c => c.name === STANDALONE_STUB_NAME);
|