falsegreen-js 0.3.0 → 0.4.0

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,10 +1,36 @@
 #!/usr/bin/env node
 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: "json" | "text"): string;
+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]

package/dist/cli.js

@@ -1,19 +1,36 @@
 #!/usr/bin/env node
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { pathToFileURL } from "node:url";
-import { JUDGMENTS, CASES, groupOf, FIX_HINTS } from "./cases.js";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { JUDGMENTS, CASES, groupOf, riskGroupOf, FIX_HINTS } from "./cases.js";
+import { ORACLE_REGISTRY_VERSION } from "./oracles.js";
 import { scanPaths, scanFile, stagedFiles, loadConfig, } from "./scan.js";
 import { auditConfig } from "./audit.js";
-const VERSION = "0.2.0";
+import { OUTPUT_EXT, renderSarif, renderJunit, loadBaseline, writeBaseline, applyBaseline, } from "./report.js";
+const DEFAULT_BASELINE = ".falsegreen-baseline.json";
+/** Single source of truth for the version: package.json, resolved at runtime so
+ * `--version` and the JSON report never drift from the published package. */
+function readVersion() {
+    try {
+        const pkg = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        return JSON.parse(fs.readFileSync(pkg, "utf-8")).version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+const VERSION = readVersion();
 const TOOL_URI = "https://github.com/vinicq/falsegreen-js";
 const HELP = `falsegreen-js ${VERSION} - find false-positive JS/TS tests (static AST scan)
 
 Usage:
   falsegreen-js [paths...]        files/dirs; no args = scan cwd
   falsegreen-js --staged          only test files staged in git
-  falsegreen-js --json            JSON output
+  falsegreen-js --format FMT      text | json | sarif | junit (default text)
+  falsegreen-js --json            alias for --format json
   falsegreen-js --output PATH     write to a file, or report.<ext> into a directory
+  falsegreen-js --baseline [PATH] suppress findings in PATH (default ${DEFAULT_BASELINE})
+  falsegreen-js --write-baseline [PATH]  record current findings as a baseline, exit 0
   falsegreen-js --config-audit    audit Jest/Vitest config (project-layer PL codes)
   falsegreen-js --diagnostics     also report the opt-in maintainability group (D*/M*)
   falsegreen-js --disable C7,JS3  turn off specific codes
@@ -25,12 +42,19 @@ and a one-line fix hint; the summary breaks findings down by level.
 Exit codes: 0 clean, 10 low-confidence only, 20 high-confidence present.
 Suppress inline:  expect(x).toBe(x); // falsegreen: ignore[C7]
 Covers: .js .jsx .ts .tsx .mjs .cjs .mts .cts`;
+const FORMATS = new Set(["text", "json", "sarif", "junit"]);
 function parseArgs(argv) {
     const paths = [];
     let json = false, staged = false, help = false, version = false, diagnostics = false;
     let configAudit = false;
+    let format;
     let output;
+    let baseline;
+    let writeBaselinePath;
     const disable = new Set();
+    // An optional-value flag (--baseline / --write-baseline) consumes the next
+    // token only when it is a value, not another flag.
+    const optionalValue = (next) => (next !== undefined && !next.startsWith("-")) ? next : undefined;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--json")
@@ -45,10 +69,44 @@ function parseArgs(argv) {
             help = true;
         else if (a === "--version" || a === "-V")
             version = true;
+        else if (a === "--format") {
+            const v = argv[++i] ?? "";
+            if (!FORMATS.has(v)) {
+                process.stderr.write(`falsegreen-js: invalid --format ${v} (text|json|sarif|junit)\n`);
+                process.exit(2);
+            }
+            format = v;
+        }
+        else if (a.startsWith("--format=")) {
+            const v = a.slice("--format=".length);
+            if (!FORMATS.has(v)) {
+                process.stderr.write(`falsegreen-js: invalid --format ${v} (text|json|sarif|junit)\n`);
+                process.exit(2);
+            }
+            format = v;
+        }
         else if (a === "--output")
             output = argv[++i] ?? "";
         else if (a.startsWith("--output="))
             output = a.slice("--output=".length);
+        else if (a === "--baseline") {
+            const v = optionalValue(argv[i + 1]);
+            if (v !== undefined)
+                i++;
+            baseline = v ?? DEFAULT_BASELINE;
+        }
+        else if (a.startsWith("--baseline=")) {
+            baseline = a.slice("--baseline=".length) || DEFAULT_BASELINE;
+        }
+        else if (a === "--write-baseline") {
+            const v = optionalValue(argv[i + 1]);
+            if (v !== undefined)
+                i++;
+            writeBaselinePath = v ?? DEFAULT_BASELINE;
+        }
+        else if (a.startsWith("--write-baseline=")) {
+            writeBaselinePath = a.slice("--write-baseline=".length) || DEFAULT_BASELINE;
+        }
         else if (a === "--disable") {
             const v = argv[++i] ?? "";
             v.split(",").map((s) => s.trim()).filter(Boolean).forEach((c) => disable.add(c));
@@ -64,14 +122,18 @@ function parseArgs(argv) {
         else
             paths.push(a);
     }
-    return { paths, json, staged, help, version, diagnostics, configAudit, disable, output };
+    const fmt = format ?? (json ? "json" : "text");
+    return {
+        paths, fmt, staged, help, version, diagnostics, configAudit, disable,
+        output, baseline, writeBaselinePath,
+    };
 }
 /** 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 function resolveOutputPath(p, fmt) {
-    const ext = fmt === "json" ? "json" : "txt";
+    const ext = OUTPUT_EXT[fmt];
     const trimmed = p.replace(/[/\\]+$/, "");
     const base = path.basename(trimmed);
     let isDir = /[/\\]$/.test(p) || path.extname(base) === "";
@@ -96,6 +158,35 @@ function exitCode(findings) {
         return 10;
     return 0;
 }
+/** 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 function buildReport(findings) {
+    return {
+        tool: "falsegreen-js",
+        version: VERSION,
+        oracleRegistryVersion: ORACLE_REGISTRY_VERSION,
+        judgments: JUDGMENTS,
+        findings: findings.map((f) => ({
+            ...f,
+            riskGroup: riskGroupOf(f.code),
+            group: groupOf(f.code),
+            fix: FIX_HINTS[f.code] ?? "",
+        })),
+    };
+}
+/** 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 function render(findings, fmt) {
+    if (fmt === "json")
+        return JSON.stringify(buildReport(findings), null, 2);
+    if (fmt === "sarif")
+        return renderSarif(findings, TOOL_URI, VERSION);
+    if (fmt === "junit")
+        return renderJunit(findings);
+    return renderText(findings);
+}
 export function renderText(findings) {
     if (findings.length === 0)
         return "falsegreen-js: no false-positive patterns found.";
@@ -141,6 +232,19 @@ export function renderText(findings) {
     }
     return lines.join("\n");
 }
+function scan(opt) {
+    const config = loadConfig();
+    const scanOpts = { config, cliDisable: opt.disable, diagnostics: opt.diagnostics };
+    if (opt.staged)
+        return stagedFiles().flatMap((f) => scanFile(f, scanOpts));
+    return scanPaths(opt.paths.length ? opt.paths : ["."], scanOpts);
+}
+function emit(rendered, opt) {
+    if (opt.output)
+        fs.writeFileSync(resolveOutputPath(opt.output, opt.fmt), rendered + "\n");
+    else
+        process.stdout.write(rendered + "\n");
+}
 function main() {
     const opt = parseArgs(process.argv.slice(2));
     if (opt.help) {
@@ -151,6 +255,13 @@ function main() {
         process.stdout.write(VERSION + "\n");
         process.exit(0);
     }
+    // --write-baseline records the current scan and exits clean, ahead of every
+    // other mode (mirrors the Python sibling: it ratchets the file scan only).
+    if (opt.writeBaselinePath !== undefined) {
+        const n = writeBaseline(opt.writeBaselinePath, scan(opt));
+        process.stderr.write(`falsegreen-js: wrote ${n} fingerprint(s) to ${opt.writeBaselinePath}\n`);
+        process.exit(0);
+    }
     if (opt.configAudit) {
         const base = opt.paths.find((p) => { try {
             return fs.statSync(p).isDirectory();
@@ -159,44 +270,16 @@ function main() {
             return false;
         } }) ?? ".";
         const findings = auditConfig(base);
-        const rendered = opt.json
-            ? JSON.stringify({
-                tool: "falsegreen-js", version: VERSION, judgments: JUDGMENTS,
-                findings: findings.map((f) => ({ ...f, group: groupOf(f.code), fix: FIX_HINTS[f.code] ?? "" })),
-            }, null, 2)
-            : renderText(findings);
-        if (opt.output)
-            fs.writeFileSync(resolveOutputPath(opt.output, opt.json ? "json" : "text"), rendered + "\n");
-        else
-            process.stdout.write(rendered + "\n");
+        emit(render(findings, opt.fmt), opt);
         process.exit(findings.length ? 10 : 0);
     }
-    const config = loadConfig();
-    const scanOpts = { config, cliDisable: opt.disable, diagnostics: opt.diagnostics };
-    let findings;
-    if (opt.staged) {
-        findings = stagedFiles().flatMap((f) => scanFile(f, scanOpts));
-    }
-    else {
-        findings = scanPaths(opt.paths.length ? opt.paths : ["."], scanOpts);
-    }
-    const rendered = opt.json
-        ? JSON.stringify({
-            tool: "falsegreen-js",
-            version: VERSION,
-            judgments: JUDGMENTS,
-            findings: findings.map((f) => ({
-                ...f, group: groupOf(f.code), fix: FIX_HINTS[f.code] ?? "",
-            })),
-        }, null, 2)
-        : renderText(findings);
-    if (opt.output) {
-        const dest = resolveOutputPath(opt.output, opt.json ? "json" : "text");
-        fs.writeFileSync(dest, rendered + "\n");
-    }
-    else {
-        process.stdout.write(rendered + "\n");
+    let findings = scan(opt);
+    // The baseline filter runs before the exit code, so CI fails only on findings
+    // that are not already recorded.
+    if (opt.baseline !== undefined) {
+        findings = applyBaseline(findings, loadBaseline(opt.baseline));
     }
+    emit(render(findings, opt.fmt), opt);
     process.exit(exitCode(findings));
 }
 /** True when this module is the process entry point. Package managers expose the

package/dist/oracles.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Oracle registry — the assertion-API vocabulary falsegreen-js understands, kept
+ * as a single versioned table instead of scattered Sets across the rules.
+ *
+ * Each family is classified by how its failure reaches the runner. That kind is
+ * what tells the async analysis whether a call settles synchronously, returns a
+ * promise that must be awaited, or only produces a value:
+ *
+ *   sync-fail          throws synchronously on mismatch — a bare statement is
+ *                      enough to fail the test (jest/vitest expect().matcher(),
+ *                      node:assert, chai assert, sinon.assert).
+ *   promise            returns a promise; the failure only surfaces if it is
+ *                      awaited or returned (expect().resolves/.rejects, supertest
+ *                      .expect() in its awaited form).
+ *   runner-registered  registered with the runner; the framework collects the
+ *                      result even from a fluent chain (AVA/node:test t.is,
+ *                      Cypress cy.should, chai .should).
+ *   value-only         produces a value but does not assert on its own; it must
+ *                      feed an assertion (Testing Library getBy* and findBy*).
+ *
+ * Bump ORACLE_REGISTRY_VERSION when the classification changes, so a JSON report
+ * records which vocabulary produced it.
+ */
+export declare const ORACLE_REGISTRY_VERSION = 2;
+export type OracleKind = "sync-fail" | "promise" | "runner-registered" | "value-only";
+/**
+ * Roots whose `<root>.<method>()` call counts as an assertion across runners:
+ * AVA / node:test / tap (t), Cypress (cy), chai assert, sinon.assert, QUnit.
+ * These are runner-registered: the framework records the outcome.
+ */
+export declare const ASSERT_ROOTS: Set<string>;
+/** Assertion method names used by AVA / tap / node:test / chai assert / QUnit. */
+export declare const ASSERT_METHODS: Set<string>;
+/** Matchers whose baseline is generated from the output itself (snapshot family). */
+export declare const SNAPSHOT_MATCHERS: Set<string>;
+/** Equality matchers (Jest/Vitest). */
+export declare const EQUALITY_MATCHERS: Set<string>;
+/**
+ * Testing Library async leaves that return a promise and must be awaited before
+ * the assertion can settle (value-only / promise: findBy* resolve to an element,
+ * waitFor* resolve when their callback stops throwing).
+ */
+export declare const ASYNC_AWAIT_LEAVES: Set<string>;
+/** Vue/Svelte async test helpers that return a promise and must be awaited. */
+export declare const VUE_SVELTE_ASYNC: Set<string>;
+/**
+ * Classify a call name (`root.leaf` or a bare identifier) by oracle kind. Returns
+ * null when the name is not a known oracle. Conservative: only the vocabulary
+ * above is classified; project-specific helpers are handled by naming convention
+ * in the rules, not here.
+ */
+export declare function oracleKind(name: string): OracleKind | null;

package/dist/oracles.js

@@ -0,0 +1,87 @@
+/**
+ * Oracle registry — the assertion-API vocabulary falsegreen-js understands, kept
+ * as a single versioned table instead of scattered Sets across the rules.
+ *
+ * Each family is classified by how its failure reaches the runner. That kind is
+ * what tells the async analysis whether a call settles synchronously, returns a
+ * promise that must be awaited, or only produces a value:
+ *
+ *   sync-fail          throws synchronously on mismatch — a bare statement is
+ *                      enough to fail the test (jest/vitest expect().matcher(),
+ *                      node:assert, chai assert, sinon.assert).
+ *   promise            returns a promise; the failure only surfaces if it is
+ *                      awaited or returned (expect().resolves/.rejects, supertest
+ *                      .expect() in its awaited form).
+ *   runner-registered  registered with the runner; the framework collects the
+ *                      result even from a fluent chain (AVA/node:test t.is,
+ *                      Cypress cy.should, chai .should).
+ *   value-only         produces a value but does not assert on its own; it must
+ *                      feed an assertion (Testing Library getBy* and findBy*).
+ *
+ * Bump ORACLE_REGISTRY_VERSION when the classification changes, so a JSON report
+ * records which vocabulary produced it.
+ */
+export const ORACLE_REGISTRY_VERSION = 2;
+/**
+ * Roots whose `<root>.<method>()` call counts as an assertion across runners:
+ * AVA / node:test / tap (t), Cypress (cy), chai assert, sinon.assert, QUnit.
+ * These are runner-registered: the framework records the outcome.
+ */
+export const ASSERT_ROOTS = new Set(["assert", "t", "cy", "tap", "qunit", "sinon", "chai", "should"]);
+/** Assertion method names used by AVA / tap / node:test / chai assert / QUnit. */
+export const ASSERT_METHODS = new Set([
+    "is", "not", "ok", "notOk", "true", "false", "truthy", "falsy",
+    "equal", "notEqual", "deepEqual", "notDeepEqual", "strictEqual",
+    "same", "notSame", "throws", "notThrows", "throwsAsync", "regex", "notRegex",
+    "pass", "fail", "assert", "expect", "include", "match",
+]);
+/** Matchers whose baseline is generated from the output itself (snapshot family). */
+export const SNAPSHOT_MATCHERS = new Set([
+    "toMatchSnapshot", "toMatchInlineSnapshot",
+    "toThrowErrorMatchingSnapshot", "toThrowErrorMatchingInlineSnapshot",
+    // visual snapshots (Playwright): the baseline is generated from the output too
+    "toHaveScreenshot", "toMatchScreenshot",
+]);
+/** Equality matchers (Jest/Vitest). */
+export const EQUALITY_MATCHERS = new Set(["toBe", "toEqual", "toStrictEqual"]);
+/**
+ * Testing Library async leaves that return a promise and must be awaited before
+ * the assertion can settle (value-only / promise: findBy* resolve to an element,
+ * waitFor* resolve when their callback stops throwing).
+ */
+export const ASYNC_AWAIT_LEAVES = new Set(["waitFor", "waitForElementToBeRemoved"]);
+/** Vue/Svelte async test helpers that return a promise and must be awaited. */
+export const VUE_SVELTE_ASYNC = new Set(["flushPromises", "nextTick", "$nextTick", "tick"]);
+/**
+ * Classify a call name (`root.leaf` or a bare identifier) by oracle kind. Returns
+ * null when the name is not a known oracle. Conservative: only the vocabulary
+ * above is classified; project-specific helpers are handled by naming convention
+ * in the rules, not here.
+ */
+export function oracleKind(name) {
+    const parts = name.split(".");
+    const root = parts[0];
+    const leaf = parts[parts.length - 1];
+    // expect(x).resolves/.rejects.matcher() — promise; plain expect().matcher() is sync-fail.
+    if (root === "expect")
+        return name.includes(".resolves") || name.includes(".rejects") ? "promise" : "sync-fail";
+    if (root === "assert")
+        return "sync-fail";
+    if (root === "sinon" && name.includes("assert"))
+        return "sync-fail";
+    if (ASSERT_ROOTS.has(root) && ASSERT_METHODS.has(leaf))
+        return "runner-registered";
+    if (leaf === "should")
+        return "runner-registered";
+    if (leaf.startsWith("findBy") || leaf.startsWith("findAllBy"))
+        return "value-only";
+    // @testing-library/user-event v14+: every action (click/type/keyboard/…) returns
+    // a promise that must be awaited before the resulting state can be asserted.
+    if (root === "userEvent")
+        return "promise";
+    if (ASYNC_AWAIT_LEAVES.has(leaf))
+        return "promise";
+    if (VUE_SVELTE_ASYNC.has(leaf))
+        return "promise";
+    return null;
+}