falsegreen-js 0.2.0 → 0.4.0

package/dist/cases.js

@@ -3,8 +3,18 @@
  * the same concept (shared C-codes, so cross-language paper comparison lines up),
  * plus JS/TS-specific codes (JS-prefix) for ecosystem-only patterns.
  *
- * confidence: "high" => blocks (exit 20); "low" => warns (exit 10); "off" => silent.
- * judgment: which semantic question (J1-J6, see falsegreen-skill) the code belongs to.
+ * Each code carries four independent axes (none derived from another or from the
+ * code prefix):
+ *   group       conceptual failure mode (RiskGroup, closed taxonomy).
+ *   severity    how serious the finding is when it fires ("high" | "low").
+ *   defaultOn   whether the default scan emits it (false for the opt-in
+ *               diagnostic group, surfaced only via --diagnostics).
+ *   judgment    which semantic question (J1-J6, see falsegreen-skill) it answers.
+ *
+ * The effective "confidence" used downstream (high/low/off) is derived from
+ * severity + defaultOn by baseConfidence(); the exit code is derived from the
+ * severity of the findings that are actually emitted. Keeping the axes apart is
+ * the point: a finding's taxonomy must not depend on whether it blocks.
  */
 export const JUDGMENTS = {
     J1: "does the assertion actually run?",
@@ -16,46 +26,143 @@ export const JUDGMENTS = {
 };
 export const CASES = {
     // --- shared concept with falsegreen (same code id) -----------------------
-    C2: { title: "test with no check at all (empty body)", confidence: "high", judgment: "J1" },
-    C2b: { title: "test calls things but checks nothing", confidence: "low", judgment: "J1" },
-    C5: { title: "always-true check (expect(true).toBe(true), assert(1))", confidence: "high", judgment: "J2" },
-    C7: { title: "compares a thing to itself (expect(x).toBe(x))", confidence: "high", judgment: "J2" },
-    C8: { title: "exact equality on a float (fails on rounding, not bugs)", confidence: "low", judgment: "J4" },
-    C16: { title: "result depends on time, randomness or a fixed timer", confidence: "low", judgment: "J1" },
-    C18: { title: "compares String()/JSON.stringify()/`${x}` of a value to a literal (checks formatting, not the value)", confidence: "low", judgment: "J2" },
-    C21: { title: "every assertion is conditional — none runs unconditionally", confidence: "low", judgment: "J1" },
-    C9: { title: "expect(...).toThrow() with no error type or message — accepts any error", confidence: "low", judgment: "J4" },
-    C37: { title: "duplicate case in it.each/test.each — the same scenario runs twice", confidence: "low", judgment: "J4" },
-    CC: { title: "commented-out assertion (check switched off)", confidence: "low", judgment: "J1" },
+    C2: { title: "test with no check at all (empty body)", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J1" },
+    C2b: { title: "test calls things but checks nothing", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J1" },
+    C5: { title: "always-true check (expect(true).toBe(true), assert(1))", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J2" },
+    C6: { title: "weak check — only verifies something came back (toBeTruthy/toBeDefined, length > 0)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    C7: { title: "compares a thing to itself (expect(x).toBe(x))", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J2" },
+    C44: { title: "numeric tautology — a length compared so the result is always true (length >= 0)", group: "effectiveness", severity: "high", defaultOn: true, judgment: "J2" },
+    C20: { title: "assertion in dead code after a return/throw — it never runs", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    C23: { title: "reads a real file at a literal path or hits a hard-coded URL (mystery guest)", group: "dependency", severity: "low", defaultOn: true, judgment: "J6" },
+    C8: { title: "exact equality on a float (fails on rounding, not bugs)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    C16: { title: "result depends on time, randomness or a fixed timer", group: "nondeterminism", severity: "low", defaultOn: true, judgment: "J1" },
+    C18: { title: "compares String()/JSON.stringify()/`${x}` of a value to a literal (checks formatting, not the value)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J2" },
+    C21: { title: "every assertion is conditional — none runs unconditionally", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    C9: { title: "expect(...).toThrow() with no error type or message — accepts any error", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    C37: { title: "duplicate case in it.each/test.each — the same scenario runs twice", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    CC: { title: "commented-out assertion (check switched off)", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    C48: { title: "dark patch — the test flips a test-mode flag (process.env.NODE_ENV=\"test\", process.env.TESTING, a TESTING flag) then asserts, exercising the product's test-only branch", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
     // --- JS/TS ecosystem-specific --------------------------------------------
-    JS1: { title: "focused test (it.only / fit / describe.only) silently skips the rest of the suite", confidence: "high", judgment: "J1" },
-    JS2: { title: "expect(x) with no matcher — the assertion is never executed", confidence: "high", judgment: "J1" },
-    JS3: { title: "snapshot is the only assertion (toMatchSnapshot generated from the output itself)", confidence: "low", judgment: "J2" },
-    JS4: { title: "skipped test (it.skip / xit / xdescribe / it.todo) never runs", confidence: "low", judgment: "J1" },
-    JS5: { title: "async query/event not awaited (findBy* / waitFor / user-event) — the assertion may never settle", confidence: "low", judgment: "J1" },
-    JS6: { title: "empty describe/suite block — the suite reports green but runs nothing", confidence: "high", judgment: "J1" },
-    JS7: { title: "assertion inside a non-awaited setTimeout/setInterval/then callback — it may run after the test ends", confidence: "low", judgment: "J1" },
-    JS9: { title: "assertion in a dead branch (if(false) / if(true){}else) — it never runs", confidence: "high", judgment: "J1" },
-    JS11: { title: "try/catch swallows the assertion — a failing expect is caught and the test stays green", confidence: "low", judgment: "J1" },
-    JS13: { title: "query (getBy*/queryBy*/wrapper.find) as a loose statement — its result is never asserted", confidence: "low", judgment: "J4" },
-    JS15: { title: "inappropriate assertion — the comparison is wrapped in a boolean (expect(a===b).toBe(true)), so the failure message is blind", confidence: "low", judgment: "J4" },
+    JS1: { title: "focused test (it.only / fit / describe.only) silently skips the rest of the suite", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS2: { title: "expect(x) with no matcher — the assertion is never executed", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS3: { title: "snapshot is the only assertion (toMatchSnapshot generated from the output itself)", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J2" },
+    JS4: { title: "skipped test (it.skip / xit / xdescribe / it.todo) never runs", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS5: { title: "async query/event not awaited (findBy* / waitFor / user-event) — the assertion may never settle", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS6: { title: "empty describe/suite block — the suite reports green but runs nothing", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS7: { title: "assertion inside a non-awaited setTimeout/setInterval/then callback — it may run after the test ends", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS8: { title: "mocks the unit under test (jest.mock/vi.mock of an imported module asserted directly) — tests the mock, not the code", group: "dependency", severity: "low", defaultOn: true, judgment: "J3" },
+    JS9: { title: "assertion in a dead branch (if(false) / if(true){}else) — it never runs", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS11: { title: "try/catch swallows the assertion — a failing expect is caught and the test stays green", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS13: { title: "query (getBy*/queryBy*/wrapper.find) as a loose statement — its result is never asserted", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    JS15: { title: "inappropriate assertion — the comparison is wrapped in a boolean (expect(a===b).toBe(true)), so the failure message is blind", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J4" },
+    JS17: { title: "commented-out test block (// it(...) / // test(...)) — a disabled test that no longer runs", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS18: { title: "test takes a done callback instead of async/await — a done called too early (or in a floating promise) passes before the assertions run", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
+    JS21: { title: "matcher referenced but never called (expect(x).toBe with no ()) — the assertion never executes", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
+    JS22: { title: "empty it.each/test.each table — the test is generated with zero cases and never runs", group: "execution", severity: "high", defaultOn: true, judgment: "J1" },
     // --- diagnostic group (maintainability; default off, opt-in via --diagnostics
     // or config severity). These are NOT false-green: the test still protects. They
     // are a "plus" for test-code health, mirroring falsegreen's D/M group. -------
-    D1: { title: "assertion roulette — many assertions in one test; a failure does not say which", confidence: "off", judgment: "J4" },
-    D3: { title: "duplicate assert — the same assertion appears more than once in a test", confidence: "off", judgment: "J4" },
-    D4: { title: "it.each/test.each without titled cases — a failing case is identified only by its index", confidence: "off", judgment: "J4" },
-    D6: { title: "console.* in a test body — a debug artifact that bypasses the oracle", confidence: "off", judgment: "J4" },
-    D7: { title: "anonymous test — empty or missing description", confidence: "off", judgment: "J4" },
-    D8: { title: "magic number in an assertion — a bare numeric literal instead of a named constant", confidence: "off", judgment: "J4" },
-    M2: { title: "test body exceeds the line-count threshold — hard to read and maintain", confidence: "off", judgment: "J5" },
+    D1: { title: "assertion roulette — many assertions in one test; a failure does not say which", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D3: { title: "duplicate assert — the same assertion appears more than once in a test", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D4: { title: "it.each/test.each without titled cases — a failing case is identified only by its index", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D6: { title: "console.* in a test body — a debug artifact that bypasses the oracle", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D7: { title: "anonymous test — empty or missing description", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    D8: { title: "magic number in an assertion — a bare numeric literal instead of a named constant", group: "diagnostic", severity: "low", defaultOn: false, judgment: "J4" },
+    M2: { title: "test body exceeds the line-count threshold — hard to read and maintain", group: "structure", severity: "low", defaultOn: false, judgment: "J5" },
+    // --- project layer (config-audit only; emitted by --config-audit, never by
+    // the per-file scan). The suite goes green by configuration, not by a smell
+    // inside any one test file. ------------------------------------------------
+    PL7: { title: "no coverage gate (coverageThreshold / coverage.thresholds) - coverage can fall to zero and the suite still passes", group: "effectiveness", severity: "low", defaultOn: true, judgment: "J5" },
+    PL8: { title: "bail stops the run early (bail) - the reported test count is incomplete", group: "execution", severity: "low", defaultOn: true, judgment: "J5" },
+    PL10: { title: "passWithNoTests lets an empty or fully-filtered suite report green", group: "execution", severity: "low", defaultOn: true, judgment: "J1" },
 };
 /** Default thresholds for the diagnostic group (overridable later via config). */
 export const DIAGNOSTIC_THRESHOLDS = { assertionRoulette: 5, longTest: 50 };
+/**
+ * Effective default state of a code as a single value: its severity when the
+ * default scan emits it, or "off" when it is opt-in. Derives the legacy
+ * three-valued "confidence" from the independent severity + defaultOn axes, so
+ * the rest of the pipeline (makeFinding, effectiveConf, exit code) keeps working
+ * unchanged while the taxonomy stays separate from the blocking decision.
+ */
+export function baseConfidence(code) {
+    const c = CASES[code];
+    if (!c)
+        throw new Error(`falsegreen-js: unknown code "${code}" — not in the case catalog`);
+    return c.defaultOn ? c.severity : "off";
+}
+/**
+ * Primary taxonomy: the conceptual failure mode, read from the closed per-code
+ * table. Rejects an unknown code instead of defaulting, so a typo or a code that
+ * was added to the rules but never classified fails loudly.
+ */
+export function riskGroupOf(code) {
+    const c = CASES[code];
+    if (!c)
+        throw new Error(`falsegreen-js: unknown code "${code}" — not in the case catalog`);
+    return c.group;
+}
+/**
+ * Legacy product grouping (false-positive / diagnostic / coupling / project),
+ * kept only as a transition-compat field in the JSON report. New consumers
+ * should read `riskGroup` (riskGroupOf). Prefix-based by design: it mirrors the
+ * pre-0.3 output exactly so downstream filters do not break across the upgrade.
+ */
 export function groupOf(code) {
+    if (code.startsWith("PL"))
+        return "project";
     if (code.startsWith("D"))
         return "diagnostic";
     if (code.startsWith("M"))
         return "coupling";
     return "false-positive";
 }
+/**
+ * One-line remediation per case: what to change so the test protects something.
+ * Short, imperative, no trailing period. Surfaced in the status report (text +
+ * JSON `fix` field). A code missing here renders no fix line, never throws.
+ */
+export const FIX_HINTS = {
+    C2: "add an assertion that checks the behaviour under test",
+    C2b: "assert the result of the call, not just that it ran",
+    C5: "assert the real behaviour, not a constant or tautology",
+    C6: "assert the actual value, not just that something came back",
+    C7: "compare against an independent expected value, not the subject itself",
+    C44: "assert the actual length, not that it is at least zero (always true)",
+    C20: "move the assertion before the return/throw so it runs",
+    C23: "use a fixture or temp file instead of a real path or hard-coded URL",
+    C8: "use toBeCloseTo() or a tolerance instead of exact float equality",
+    C16: "freeze time and seed randomness so the result is deterministic",
+    C18: "assert the value, not its String()/JSON.stringify() form",
+    C21: "add at least one assertion that runs unconditionally",
+    C9: "pass an error type or message to toThrow()",
+    C37: "remove the duplicate it.each/test.each case",
+    CC: "restore the commented-out assertion, or delete it",
+    C48: "assert the behaviour a real user hits; don't force the product's test-mode branch from the test",
+    JS1: "remove .only (it.only/fit/describe.only) so the whole suite runs",
+    JS2: "add a matcher (expect(x).toBe(...)) so the assertion runs",
+    JS3: "add a real assertion; don't rely only on a self-generated snapshot",
+    JS4: "remove .skip/xit/todo, or implement the test",
+    JS5: "await the async query/event before asserting",
+    JS6: "add tests to the describe block, or remove it",
+    JS7: "await the promise, or use/flush fake timers, or assert synchronously",
+    JS8: "unmock the unit under test; mock only its collaborators",
+    JS9: "remove the dead branch so the assertion runs",
+    JS11: "let the assertion error propagate; don't catch it",
+    JS13: "assert on the query result, not just query it",
+    JS15: "expect the value directly (expect(a).toBe(b)), not a boolean",
+    JS17: "restore the commented-out test, or delete it",
+    JS18: "use async/await instead of the done callback",
+    JS21: "call the matcher (add ()) so the assertion executes",
+    JS22: "add at least one row to the it.each/test.each table",
+    D1: "give each assertion a message, or split the test",
+    D3: "remove the duplicate assertion",
+    D4: "add titled cases to it.each/test.each",
+    D6: "remove console.* or replace it with an assertion",
+    D7: "give the test a description",
+    D8: "name the magic number with a constant",
+    M2: "split the long test into focused cases",
+    PL7: "set coverageThreshold (Jest) or coverage.thresholds (Vitest) to gate coverage",
+    PL8: "remove bail so the whole suite runs and the count is complete",
+    PL10: "drop passWithNoTests so an empty or filtered-to-nothing run fails",
+};

package/dist/cfg.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Intra-test structured reachability, backing C20 (dead code) and C21 (no
+ * unconditional assertion). JS test bodies are structured (no goto), so this is a
+ * recursive walk over the statement tree, not a full control-flow graph.
+ *
+ * Two questions, both FP-averse (a false positive is worse than a miss):
+ *   assertionsInDeadCode  - assertions at a position control can never reach.
+ *   hasUnconditionalAssertion - is at least one assertion guaranteed to run?
+ *
+ * The assertion predicate and literal-truthiness helper are passed in (they live in
+ * rules.ts) so this module imports nothing from there and there is no cycle.
+ */
+import ts from "typescript";
+type IsAssertion = (n: ts.Node) => boolean;
+type LitTruth = (e: ts.Expression | undefined) => boolean | null;
+/**
+ * Assertions sitting at a position control can never reach (C20). Walk each
+ * statement list keeping `reachable` (true at the head); once a statement does not
+ * fall through, the rest of the list is dead. Recurse into nested lists of a
+ * reachable statement with a fresh reachable=true. Stop at nested functions.
+ */
+export declare function assertionsInDeadCode(body: ts.Block, isAssertion: IsAssertion): ts.Node[];
+/**
+ * Is at least one assertion guaranteed to run (so C21 must NOT fire)? Walks the
+ * "spine" of always-executed positions: top-level statements, blocks on the spine,
+ * the taken branch of an if/?: with a literal-constant condition, finally blocks,
+ * and - conservatively - a try block. A non-const if, any loop, switch, catch, or
+ * short-circuit is not guaranteed. Anything unmodeled is treated as guaranteed
+ * (suppress C21) to stay false-positive-averse.
+ */
+export declare function hasUnconditionalAssertion(body: ts.Block, isAssertion: IsAssertion, litTruth: LitTruth, deadAsserts?: ReadonlySet<ts.Node>): boolean;
+export {};

package/dist/cfg.js

@@ -0,0 +1,237 @@
+/**
+ * Intra-test structured reachability, backing C20 (dead code) and C21 (no
+ * unconditional assertion). JS test bodies are structured (no goto), so this is a
+ * recursive walk over the statement tree, not a full control-flow graph.
+ *
+ * Two questions, both FP-averse (a false positive is worse than a miss):
+ *   assertionsInDeadCode  - assertions at a position control can never reach.
+ *   hasUnconditionalAssertion - is at least one assertion guaranteed to run?
+ *
+ * The assertion predicate and literal-truthiness helper are passed in (they live in
+ * rules.ts) so this module imports nothing from there and there is no cycle.
+ */
+import ts from "typescript";
+/** A call to process.exit(...) — control leaves the process, so it terminates. */
+function isProcessExit(e) {
+    return (ts.isCallExpression(e) &&
+        ts.isPropertyAccessExpression(e.expression) &&
+        e.expression.name.text === "exit" &&
+        ts.isIdentifier(e.expression.expression) &&
+        e.expression.expression.text === "process");
+}
+/**
+ * A statement does not fall through to the next statement in its list iff control
+ * cannot continue past it. `breakStops` controls whether break/continue count as
+ * not-falling-through: true within a normal statement list (the sibling after a
+ * break is unreachable), false when asking whether a switch escapes its own exit
+ * (a case ending in `break` continues after the switch, so it does fall through).
+ */
+function stmtNoFallThrough(stmt, breakStops) {
+    if (ts.isReturnStatement(stmt) || ts.isThrowStatement(stmt))
+        return true;
+    if (ts.isBreakStatement(stmt) || ts.isContinueStatement(stmt))
+        return breakStops;
+    if (ts.isExpressionStatement(stmt) && isProcessExit(stmt.expression))
+        return true;
+    if (ts.isBlock(stmt))
+        return listNoFallThrough(stmt.statements, breakStops);
+    if (ts.isLabeledStatement(stmt))
+        return stmtNoFallThrough(stmt.statement, breakStops);
+    if (ts.isIfStatement(stmt)) {
+        return (stmt.elseStatement !== undefined &&
+            stmtNoFallThrough(stmt.thenStatement, breakStops) &&
+            stmtNoFallThrough(stmt.elseStatement, breakStops));
+    }
+    if (ts.isTryStatement(stmt))
+        return tryNoFallThrough(stmt, breakStops);
+    if (ts.isSwitchStatement(stmt))
+        return switchNoFallThrough(stmt);
+    // loops may run zero times, so they always fall through; var/expr/etc fall through.
+    return false;
+}
+function listNoFallThrough(stmts, breakStops) {
+    return stmts.some((s) => stmtNoFallThrough(s, breakStops));
+}
+function tryNoFallThrough(t, breakStops) {
+    // finally always runs; if it escapes, the whole try escapes.
+    if (t.finallyBlock && listNoFallThrough(t.finallyBlock.statements, breakStops))
+        return true;
+    if (!listNoFallThrough(t.tryBlock.statements, breakStops))
+        return false;
+    // try-block escapes; if there is a catch, a caught throw escapes only if catch does too.
+    if (!t.catchClause)
+        return true;
+    return listNoFallThrough(t.catchClause.block.statements, breakStops);
+}
+function switchNoFallThrough(sw) {
+    // code after the switch is unreachable iff every clause escapes the function
+    // (return/throw/process.exit — a `break` exits to AFTER the switch, so it does
+    // NOT escape) and a default clause is present (else a no-match falls through).
+    let hasDefault = false;
+    for (const clause of sw.caseBlock.clauses) {
+        if (clause.kind === ts.SyntaxKind.DefaultClause)
+            hasDefault = true;
+        if (!listNoFallThrough(clause.statements, /* breakStops */ false))
+            return false;
+    }
+    return hasDefault;
+}
+/** Collect assertion nodes under `node`, never entering a nested function scope
+ *  (a return/assert inside a callback belongs to that callback, not this test). */
+function collectAssertionsNoNesting(node, isAssertion, out) {
+    const visit = (n) => {
+        if (isAssertion(n))
+            out.push(n);
+        if (!ts.isFunctionLike(n))
+            ts.forEachChild(n, visit);
+    };
+    ts.forEachChild(node, visit);
+    if (isAssertion(node))
+        out.push(node);
+}
+/**
+ * Assertions sitting at a position control can never reach (C20). Walk each
+ * statement list keeping `reachable` (true at the head); once a statement does not
+ * fall through, the rest of the list is dead. Recurse into nested lists of a
+ * reachable statement with a fresh reachable=true. Stop at nested functions.
+ */
+export function assertionsInDeadCode(body, isAssertion) {
+    const dead = [];
+    const walkList = (stmts) => {
+        let reachable = true;
+        for (const st of stmts) {
+            if (!reachable) {
+                collectAssertionsNoNesting(st, isAssertion, dead);
+            }
+            else {
+                recurse(st);
+                if (stmtNoFallThrough(st, /* breakStops */ true))
+                    reachable = false;
+            }
+        }
+    };
+    // Descend into the nested statement lists of a reachable statement, each a fresh
+    // list. Never enters a function body (its returns are its own).
+    const recurse = (st) => {
+        if (ts.isBlock(st))
+            return walkList(st.statements);
+        if (ts.isIfStatement(st)) {
+            recurse(st.thenStatement);
+            if (st.elseStatement)
+                recurse(st.elseStatement);
+            return;
+        }
+        if (ts.isForStatement(st) || ts.isForOfStatement(st) || ts.isForInStatement(st) ||
+            ts.isWhileStatement(st) || ts.isDoStatement(st)) {
+            return recurse(st.statement);
+        }
+        if (ts.isLabeledStatement(st))
+            return recurse(st.statement);
+        if (ts.isTryStatement(st)) {
+            walkList(st.tryBlock.statements);
+            if (st.catchClause)
+                walkList(st.catchClause.block.statements);
+            if (st.finallyBlock)
+                walkList(st.finallyBlock.statements);
+            return;
+        }
+        if (ts.isSwitchStatement(st)) {
+            for (const clause of st.caseBlock.clauses)
+                walkList(clause.statements);
+            return;
+        }
+        // expression/variable/etc: no nested statement list to walk (nested functions
+        // are skipped on purpose).
+    };
+    walkList(body.statements);
+    return dead;
+}
+/**
+ * Is at least one assertion guaranteed to run (so C21 must NOT fire)? Walks the
+ * "spine" of always-executed positions: top-level statements, blocks on the spine,
+ * the taken branch of an if/?: with a literal-constant condition, finally blocks,
+ * and - conservatively - a try block. A non-const if, any loop, switch, catch, or
+ * short-circuit is not guaranteed. Anything unmodeled is treated as guaranteed
+ * (suppress C21) to stay false-positive-averse.
+ */
+export function hasUnconditionalAssertion(body, isAssertion, litTruth, deadAsserts = new Set()) {
+    // An assertion already flagged C20 (dead code) is unreachable, so it is never the
+    // guaranteed-spine assertion. Walk a leaf statement's expression for a dead node so
+    // a dead top-level assertion does not mask a live conditional one (C21 must still
+    // fire). Scoped to the leaf expression only — a single ExpressionStatement/return
+    // has no sibling live asserts, so finding any dead node means this leaf is dead (#62).
+    const exprHasDeadAssertion = (e) => {
+        let dead = false;
+        const visit = (n) => {
+            if (deadAsserts.has(n)) {
+                dead = true;
+                return;
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(e);
+        return dead;
+    };
+    // An assertion that is itself the spine expression (not behind a short-circuit
+    // or ternary): expect(...).m(), await expect(...), (expect(...)).
+    const directAssertion = (e) => {
+        if (ts.isAwaitExpression(e) || ts.isParenthesizedExpression(e)) {
+            return directAssertion(e.expression);
+        }
+        if (isAssertion(e))
+            return true;
+        // chai/Cypress fluent call form: result.should.equal(1) / cy.get(x).should(...).
+        // isAssertion recognizes the `.should` property-access node, but on the spine the
+        // enclosing CallExpression is what we see, so scan its callee chain for `.should`.
+        // Only the property/call spine is walked, never `&&`/`?:` operands, so a
+        // short-circuited assertion still does not count as guaranteed.
+        if (ts.isCallExpression(e)) {
+            let base = e.expression;
+            while (ts.isPropertyAccessExpression(base) || ts.isCallExpression(base)) {
+                if (ts.isPropertyAccessExpression(base) && base.name.text === "should")
+                    return true;
+                base = base.expression;
+            }
+        }
+        return false;
+    };
+    const stmtGuaranteed = (st) => {
+        if (ts.isExpressionStatement(st)) {
+            if (exprHasDeadAssertion(st.expression))
+                return false;
+            return directAssertion(st.expression);
+        }
+        if (ts.isBlock(st))
+            return listGuaranteed(st.statements);
+        if (ts.isLabeledStatement(st))
+            return stmtGuaranteed(st.statement);
+        if (ts.isReturnStatement(st))
+            return st.expression !== undefined
+                && !exprHasDeadAssertion(st.expression) && directAssertion(st.expression);
+        if (ts.isIfStatement(st)) {
+            const t = litTruth(st.expression);
+            if (t === true)
+                return stmtGuaranteed(st.thenStatement);
+            if (t === false)
+                return st.elseStatement !== undefined && stmtGuaranteed(st.elseStatement);
+            return false; // non-const condition: neither branch is guaranteed
+        }
+        if (ts.isTryStatement(st)) {
+            // conservative: a try block on the spine counts as guaranteed (so
+            // try{expect}finally{...} is not flagged); finally always runs; catch does not.
+            if (listGuaranteed(st.tryBlock.statements))
+                return true;
+            if (st.finallyBlock && listGuaranteed(st.finallyBlock.statements))
+                return true;
+            return false;
+        }
+        // do/while is the one loop whose body always runs at least once, so an
+        // assertion in it IS unconditional (the condition only controls repetition).
+        if (ts.isDoStatement(st))
+            return stmtGuaranteed(st.statement);
+        // for/while/for-of/for-in/switch/catch: their body is not guaranteed to run.
+        return false;
+    };
+    const listGuaranteed = (stmts) => stmts.some(stmtGuaranteed);
+    return listGuaranteed(body.statements);
+}

package/dist/cli.d.ts

@@ -1,2 +1,39 @@
 #!/usr/bin/env node
-export {};
+import { Finding } from "./types.js";
+import { OutputFormat } from "./report.js";
+/** Turn --output into a concrete file path. A directory (existing dir, a
+ * trailing separator, or an extension-less name like ".falsegreen") receives
+ * "report.<ext>" for the chosen format; anything else is treated as a file.
+ * Missing parent directories are created either way. */
+export declare function resolveOutputPath(p: string, fmt: OutputFormat): string;
+/** The JSON report object. Each finding carries both the primary `riskGroup`
+ * (closed taxonomy) and the legacy `group` (transition-compat), plus its fix
+ * hint. The tool block records the oracle-registry version that classified it. */
+export declare function buildReport(findings: Finding[]): {
+    tool: string;
+    version: string;
+    oracleRegistryVersion: number;
+    judgments: Record<string, string>;
+    findings: {
+        riskGroup: import("./cases.js").RiskGroup;
+        group: "diagnostic" | "false-positive" | "coupling" | "project";
+        fix: string;
+        file: string;
+        line: number;
+        code: string;
+        detail: string;
+        confidence: import("./cases.js").Confidence;
+        title: string;
+        level: import("./cases.js").PyramidLevel;
+    }[];
+};
+/** Render findings in the chosen format. JSON keeps the full report object
+ * (riskGroup/group/fix/oracleRegistryVersion/judgments); SARIF/JUnit follow the
+ * Python sibling's contract. */
+export declare function render(findings: Finding[], fmt: OutputFormat): string;
+export declare function renderText(findings: Finding[]): string;
+/** True when this module is the process entry point. Package managers expose the
+ * `bin` through a symlink (node_modules/.bin/falsegreen-js), so process.argv[1]
+ * is the symlink while import.meta.url is the real dist/cli.js path; resolve the
+ * realpath before comparing, or `npx falsegreen-js` would exit without scanning. */
+export declare function isDirectRun(invokedPath: string | undefined, moduleUrl: string): boolean;