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
@@ -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);