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.
@@ -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. */
@@ -219,135 +227,480 @@ export interface WarnReturnPath {
219
227
  * allowed to be wrong in is toward NOT naming: an intervening `expect` at any
220
228
  * depth disqualifies a candidate, even one a branch could skip. A missed check
221
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`).
222
268
  */
223
- const WARN_CALL = /^console\s*\.\s*warn\s*\(/;
224
- const EXPECT_CALL = /^expect\s*(?:<[^>()]*>)?\s*\(/;
225
- const RETURN_KEYWORD = /^return\b/;
226
- const IF_KEYWORD = /^if\b/;
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
+
227
307
  /**
228
- * The keywords that open a branch excluding the one before it.
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)`.
229
310
  *
230
- * Brace depth alone only notices exclusivity when the branches are braced and
231
- * the depth dips between them. `if (a) expect(p); else console.warn(x);` puts
232
- * both at the same depth with nothing closing in between, and so does a
233
- * `switch`, so the assertion was credited to a path that can never run it.
234
- * PR #1539's review caught that.
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.
235
315
  */
236
- const BRANCH_SPLIT = /^(?:else|case|default)\b/;
237
-
238
- type PathToken = {
239
- kind: "expect" | "warn" | "return";
240
- at: number;
241
- depth: number;
242
- /**
243
- * The shallowest depth reached between the previous token and this one.
244
- *
245
- * Without it a forward scan can only compare each token's own depth against
246
- * the warn's, which cannot see a block closing and re-opening in between —
247
- * so a `return` inside a LATER, unrelated branch reads as the warn's own
248
- * path leaving the check. PR #1539's review caught exactly that.
249
- */
250
- minBefore: number;
251
- };
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
+ }
252
328
 
253
329
  /**
254
- * Bracket-depth-aware token scan over a check body, skipping strings and
255
- * comments the way `matchingParen` does.
330
+ * Does an `expect` appear anywhere under this node, INCLUDING inside nested
331
+ * functions?
256
332
  *
257
- * `assertDepth` is the shallowest depth at which an `expect` has been seen
258
- * whose enclosing block has not since closed — i.e. an assertion that runs on
259
- * every path reaching the current position. It resets when depth falls below
260
- * it, because that is the block closing.
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.
261
337
  */
262
- function pathTokens(body: string): { tokens: PathToken[]; assertDepthAt: Map<number, number | null> } {
263
- const tokens: PathToken[] = [];
264
- const assertDepthAt = new Map<number, number | null>();
265
- let depth = 0;
266
- let assertDepth: number | null = null;
267
- /** Where the assertion that set `assertDepth` sits, so an `else` can tell
268
- * whether it lives in the branch being superseded. */
269
- let assertAt = -1;
270
- /** The most recent `if`/`switch` head seen at each depth. */
271
- const branchHeadAt = new Map<number, number>();
272
- let minSinceToken = 0;
273
- const push = (kind: PathToken["kind"], at: number) => {
274
- tokens.push({ kind, at, depth, minBefore: Math.min(minSinceToken, depth) });
275
- minSinceToken = depth;
276
- };
277
- for (let i = 0; i < body.length; i++) {
278
- const c = body[i]!;
279
- const next = body[i + 1];
280
- if (c === "/" && next === "/") {
281
- const nl = body.indexOf("\n", i);
282
- i = nl === -1 ? body.length : nl;
283
- continue;
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
+ };
284
393
  }
285
- if (c === "/" && next === "*") {
286
- const close = body.indexOf("*/", i + 2);
287
- i = close === -1 ? body.length : close + 1;
288
- continue;
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
+ });
289
412
  }
290
- if (c === '"' || c === "'" || c === "`") {
291
- const quote = c;
292
- i++;
293
- for (; i < body.length; i++) {
294
- if (body[i] === "\\") { i++; continue; }
295
- if (body[i] === quote) break;
296
- if (quote === "`" && body[i] === "$" && body[i + 1] === "{") {
297
- let d = 1;
298
- i += 2;
299
- for (; i < body.length && d > 0; i++) {
300
- if (body[i] === "{") d++;
301
- else if (body[i] === "}") d--;
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;
302
531
  }
303
- i--;
304
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;
305
584
  }
306
- continue;
307
585
  }
308
- if (c === "(" || c === "[" || c === "{") { depth++; continue; }
309
- if (c === ")" || c === "]" || c === "}") {
310
- depth--;
311
- if (depth < minSinceToken) minSinceToken = depth;
312
- if (assertDepth !== null && depth < assertDepth) { assertDepth = null; assertAt = -1; }
313
- continue;
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;
314
618
  }
315
- // Only start a keyword match at an identifier boundary, so `s.expect(`
316
- // and `myreturn` are not read as the bare forms.
317
- if (!/[A-Za-z_$]/.test(c)) continue;
318
- if (i > 0 && /[\w$.]/.test(body[i - 1]!)) continue;
319
- const rest = body.slice(i, i + 200);
320
- if (IF_KEYWORD.test(rest) || /^switch\b/.test(rest)) {
321
- branchHeadAt.set(depth, i);
322
- continue;
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;
323
623
  }
324
- if (BRANCH_SPLIT.test(rest)) {
325
- // This opens a branch excluding the one before it. An assertion is
326
- // superseded only if it lives INSIDE that preceding branch — i.e. after
327
- // the `if`/`switch` head this pairs with. An `expect` written before the
328
- // head runs on every path, including this one, so it still counts.
329
- // An `else` sits at its `if`'s own depth; a `case` sits one level INSIDE
330
- // its `switch`'s braces. Take whichever head is nearer — that is the
331
- // construct this branch belongs to.
332
- const head = Math.max(branchHeadAt.get(depth) ?? -1, branchHeadAt.get(depth - 1) ?? -1);
333
- if (assertDepth !== null && head >= 0 && assertAt > head) {
334
- assertDepth = null;
335
- assertAt = -1;
336
- }
337
- continue;
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);
338
648
  }
339
- if (EXPECT_CALL.test(rest)) {
340
- push("expect", i);
341
- if (assertDepth === null || depth < assertDepth) assertAt = i;
342
- assertDepth = assertDepth === null ? depth : Math.min(assertDepth, depth);
343
- } else if (WARN_CALL.test(rest)) {
344
- push("warn", i);
345
- assertDepthAt.set(i, assertDepth);
346
- } else if (RETURN_KEYWORD.test(rest)) {
347
- push("return", i);
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));
348
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 });
349
685
  }
350
- return { tokens, assertDepthAt };
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;
351
704
  }
352
705
 
353
706
  /**
@@ -355,55 +708,89 @@ function pathTokens(body: string): { tokens: PathToken[]; assertDepthAt: Map<num
355
708
  *
356
709
  * Two conditions, and both are about the PATH rather than the body:
357
710
  *
358
- * - nothing has asserted on the way to the warn — no `expect` whose enclosing
359
- * block still contains it;
360
- * - nothing asserts after it either — the path reaches a `return` at or above
361
- * the warn's own depth, or runs out of check, without meeting an `expect`.
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).
362
714
  *
363
- * Both halves of the second condition are implemented, and the second half is
364
- * the `else { console.warn(...) }` shape that gets past the body-level
365
- * predicate as well: the sibling branch's `expect` makes the body assert.
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.
366
717
  *
367
- * Falling out of an `if` into an assertion below is NOT a finding: once the
368
- * warn's own enclosing block closes, the path has merged back into the main
369
- * flow and reaches whatever that flow asserts. A `return` belonging to a
370
- * later, unrelated branch is that flow's, not this warn's.
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`.
371
723
  */
372
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
+
373
765
  const out: WarnReturnPath[] = [];
374
- for (const check of gateChecks(source)) {
766
+ for (let i = 0; i < checks.length; i++) {
767
+ const check = checks[i]!;
375
768
  if (check.name === STANDALONE_STUB_NAME) continue;
376
- const { tokens, assertDepthAt } = pathTokens(check.body);
377
- for (let t = 0; t < tokens.length; t++) {
378
- const warn = tokens[t]!;
379
- if (warn.kind !== "warn") continue;
380
- if (assertDepthAt.get(warn.at) !== null) continue;
381
- // The warn leaves the check only if it reaches a `return` while still
382
- // inside its OWN enclosing block. Once the running minimum drops below
383
- // the warn's depth that block has closed, the path has merged back into
384
- // the main flow, and every `return` and `expect` after that belongs to
385
- // the flow rather than to this warn.
386
- // Running out of tokens IS the path leaving: nothing asserts after the
387
- // warn, so it reaches the end of the check unasserted. That is the
388
- // `else { console.warn(...) }` shape, which gets past both halves of
389
- // the audit — the sibling branch's `expect` makes the body assert, and
390
- // there is no `return` for this scan to stop on.
391
- let leaves = true;
392
- let runningMin = warn.depth;
393
- for (let u = t + 1; u < tokens.length; u++) {
394
- const after = tokens[u]!;
395
- runningMin = Math.min(runningMin, after.minBefore);
396
- if (runningMin < warn.depth) { leaves = false; break; }
397
- if (after.kind === "expect") { leaves = false; break; }
398
- if (after.kind === "return" && after.depth <= warn.depth) break;
399
- }
400
- if (!leaves) 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;
401
787
  out.push({
402
788
  check: check.name,
403
789
  line: check.line,
404
790
  // The body starts partway through the `test(` line, so the warn's line
405
791
  // is the check's line plus the newlines before it inside the body.
406
- warnLine: check.line + (check.body.slice(0, warn.at).match(/\n/g) || []).length,
792
+ warnLine:
793
+ check.line + (check.body.slice(0, offsets[w]!).match(/\n/g) || []).length,
407
794
  });
408
795
  }
409
796
  }