@rigour-labs/core 6.6.2 → 6.6.3

package/dist/review/orphan-files.js

@@ -0,0 +1,125 @@
+/**
+ * Orphaned file: a code file the change adds that nothing imports or runs.
+ *
+ * An agent that tries one approach, then another, leaves the first behind; type checkers and
+ * linters only look inside files, so a whole unused module passes them. A reference is a path
+ * named in code, package.json, CI or config (docs only mention), resolved to a file: relative
+ * paths against the naming file, `$lib/` to `src/lib/`, anything else from the repository root
+ * as npm scripts and CI write them. A common basename elsewhere never keeps a file alive, and a
+ * folder of new files that only import each other is reported as a whole. Files a framework or
+ * runner finds by itself (routes, hooks, tests, migrations, config) are never reported.
+ */
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import micromatch from 'micromatch';
+import { addedFiles } from './migration-order.js';
+import { sourceStem } from './package-layout.js';
+import { ownOutputs } from './unused-exports.js';
+const GIT_TIMEOUT_MS = 10_000;
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs|svelte)$/;
+const FOUND_BY_RUNNER = /(^|\/)\+[^/]+$|(^|\/)hooks(\.server|\.client)?\.(ts|js)$|^netlify\/functions\/|^src\/params\/|\.(test|spec|e2e)\.[a-z]+$|\.d\.ts$|^(tests?|e2e|__tests__|migrations|supabase)\/|\.config\.[a-z]+$|^\./;
+/** Files that can run or import another: code, package.json, CI and config. */
+const REFERRER = /\.(ts|tsx|js|jsx|mjs|cjs|svelte|json|ya?ml|toml|sh)$/;
+/** Lockfiles and generated bundles name no source file and can be megabytes. */
+const MAX_REFERRER_BYTES = 2 * 1024 * 1024;
+const SPECIFIER = /['"`\s]((?:\.{1,2}\/|\$lib\/|[\w@-]+\/)[^'"`\s]*)/g;
+/** A module as importers name it: `x.svelte.ts` is imported as `./x.svelte` or `./x.svelte.js`, `dir/index.ts` as `dir`. */
+const withoutExtension = (file) => file.replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '').replace(/\.svelte$/, '').replace(/\/index$/, '');
+/** Build output committed to the repository: bundles, not sources anyone imports. */
+const BUILD_OUTPUT = /(^|\/)(dist|build|out|coverage|\.next|[\w-]+-dist)\//;
+export function orphanFileFailures(cwd, diff, config) {
+    const settings = config.gates.orphan_files;
+    if (!settings?.enabled)
+        return [];
+    const added = addedFiles(diff).filter(file => CODE.test(file) && !FOUND_BY_RUNNER.test(file) && !BUILD_OUTPUT.test(file) && !micromatch.isMatch(file, settings.allow));
+    if (added.length === 0)
+        return [];
+    const excluded = ownOutputs(config);
+    const files = repositoryFiles(cwd)?.filter(file => !excluded.some(own => file === own || file.startsWith(`${own}/`)));
+    if (!files)
+        return []; // git could not answer: say nothing rather than guess
+    const referrers = referrersOf(cwd, added, files);
+    return [...unreferenced(added, referrers)].map(orphan);
+}
+/** Tracked and new (untracked, not ignored) files. */
+function repositoryFiles(cwd) {
+    const result = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+    return result.status === 0 ? [...new Set(result.stdout.split('\n').filter(Boolean))] : undefined;
+}
+/** For each added file, the files that name it. */
+function referrersOf(cwd, added, files) {
+    const targets = new Map(added.map(file => [withoutExtension(path.posix.normalize(file)), file]));
+    const underFolder = new Map();
+    for (const file of added) {
+        for (let dir = path.posix.dirname(file); dir !== '.' && dir !== '/'; dir = path.posix.dirname(dir)) {
+            underFolder.set(dir, [...(underFolder.get(dir) ?? []), file]);
+        }
+    }
+    const referrers = new Map(added.map(file => [file, new Set()]));
+    for (const referrer of files) {
+        if (!REFERRER.test(referrer))
+            continue;
+        let text;
+        try {
+            if (fs.statSync(path.join(cwd, referrer)).size > MAX_REFERRER_BYTES)
+                continue;
+            text = fs.readFileSync(path.join(cwd, referrer), 'utf8');
+        }
+        catch {
+            continue; // deleted in the working tree
+        }
+        for (const [, specifier] of text.matchAll(SPECIFIER)) {
+            for (const candidate of resolve(referrer, specifier)) {
+                const named = withoutExtension(path.posix.normalize(candidate)).replace(/\/+$/, '');
+                const target = targets.get(named);
+                if (target && target !== referrer)
+                    referrers.get(target).add(referrer);
+                // A folder named in code (a fixtures or plugins directory read at run time) reaches every file under it.
+                for (const file of underFolder.get(named) ?? [])
+                    if (file !== referrer)
+                        referrers.get(file).add(referrer);
+            }
+        }
+    }
+    return referrers;
+}
+/**
+ * The files a specifier can name: relative to the naming file; `$lib/` as `src/lib/`; any other
+ * path from the repository root (as npm scripts and CI write them) and from the naming file's
+ * folder (a package.json in a subfolder); a compiled path (`dist/bin.js`) as its source.
+ */
+function resolve(referrer, specifier) {
+    if (specifier.startsWith('.'))
+        return [path.posix.join(path.posix.dirname(referrer), specifier)];
+    if (specifier.startsWith('$lib/'))
+        return [`src/lib/${specifier.slice('$lib/'.length)}`];
+    const fromFolder = path.posix.join(path.posix.dirname(referrer), specifier);
+    return [specifier, fromFolder, sourceStem(specifier), path.posix.join(path.posix.dirname(referrer), sourceStem(specifier))];
+}
+/** Added files nothing outside the added set reaches, found by clearing suspects until nothing changes. */
+function unreferenced(added, referrers) {
+    const suspects = new Set(added);
+    for (let cleared = true; cleared;) {
+        cleared = false;
+        for (const file of suspects) {
+            if ([...referrers.get(file)].some(referrer => !suspects.has(referrer))) {
+                suspects.delete(file);
+                cleared = true;
+            }
+        }
+    }
+    return suspects;
+}
+function orphan(file) {
+    return {
+        id: 'orphan-file',
+        title: 'Orphaned file',
+        details: `\`${file}\` is new, but nothing outside the change's new files imports or runs it.`,
+        severity: 'medium',
+        provenance: 'traditional',
+        files: [file],
+        line: 1,
+        hint: 'Delete it, or wire it in where it is meant to run. If a tool loads it by path, add it to gates.orphan_files.allow.',
+    };
+}

package/dist/review/package-layout.d.ts

@@ -0,0 +1,9 @@
+/** A path a package or script names, as the source file it was compiled from: `dist/bin.js` → `src/bin`. */
+export declare function sourceStem(relative: string): string;
+/**
+ * Whether `file` is part of a package's public surface: an entry point a package.json on its path
+ * names, or a module an entry re-exports whole (`export * from './hooks/index.js'`), followed down.
+ */
+export declare function isPackageEntry(cwd: string, file: string): boolean;
+/** Whether the TypeScript project around `file` emits declarations (declaration or composite, following extends). */
+export declare function emitsDeclarations(cwd: string, file: string): boolean;

package/dist/review/package-layout.js

@@ -0,0 +1,108 @@
+/**
+ * What a package's own files say about a source file: whether it is the package's entry point
+ * (its exports are the public API, used outside the repository), and whether its project emits
+ * declarations (an exported type named in another export's signature must stay exported).
+ * Compiled paths in package.json (dist/, lib/, build/, out/) are mapped back to sources.
+ */
+import fs from 'fs';
+import path from 'path';
+const COMPILED_DIR = /^(dist|lib|build|out)\//;
+const COMPILED_EXT = /\.(d\.ts|d\.mts|js|mjs|cjs)$/;
+/** A path a package or script names, as the source file it was compiled from: `dist/bin.js` → `src/bin`. */
+export function sourceStem(relative) {
+    return relative.replace(/^\.\//, '').replace(COMPILED_DIR, 'src/').replace(COMPILED_EXT, '').replace(/\.(ts|tsx|mts|cts)$/, '');
+}
+/** The source files a package.json points at (main, module, types, bin, exports), as repository-relative stems. */
+function packageEntryStems(cwd, packageJson) {
+    let pkg;
+    try {
+        pkg = JSON.parse(fs.readFileSync(path.join(cwd, packageJson), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    const dir = path.posix.dirname(packageJson);
+    const targets = [];
+    const collect = (value) => {
+        if (typeof value === 'string')
+            targets.push(value);
+        else if (value && typeof value === 'object')
+            Object.values(value).forEach(collect);
+    };
+    [pkg.main, pkg.module, pkg.types, pkg.typings, pkg.exports, pkg.bin].forEach(collect);
+    return targets.filter(t => t.startsWith('./') || !t.startsWith('.')).map(t => path.posix.normalize(path.posix.join(dir, sourceStem(t))));
+}
+/**
+ * Whether `file` is part of a package's public surface: an entry point a package.json on its path
+ * names, or a module an entry re-exports whole (`export * from './hooks/index.js'`), followed down.
+ */
+export function isPackageEntry(cwd, file) {
+    const stem = file.replace(/\.(ts|tsx|mts|cts|js|jsx|mjs|svelte)$/, '');
+    for (let dir = path.posix.dirname(file);; dir = path.posix.dirname(dir)) {
+        const candidate = dir === '.' ? 'package.json' : `${dir}/package.json`;
+        if (fs.existsSync(path.join(cwd, candidate)) && publicStems(cwd, candidate).has(stem))
+            return true;
+        if (dir === '.' || dir === '/')
+            return false;
+    }
+}
+const publicCache = new Map();
+/** Entry stems plus every module they re-export whole, transitively. */
+function publicStems(cwd, packageJson) {
+    const key = `${cwd}\0${packageJson}`;
+    const cached = publicCache.get(key);
+    if (cached)
+        return cached;
+    const stems = new Set();
+    const queue = packageEntryStems(cwd, packageJson);
+    while (queue.length) {
+        const stem = queue.shift();
+        if (stems.has(stem))
+            continue;
+        stems.add(stem);
+        const text = readSource(cwd, stem);
+        for (const match of text.matchAll(/export\s+\*\s+(?:as\s+\w+\s+)?from\s+['"](\.[^'"]+)['"]/g)) {
+            queue.push(path.posix.normalize(path.posix.join(path.posix.dirname(stem), match[1].replace(COMPILED_EXT, '').replace(/\.(ts|tsx|mts|cts)$/, ''))));
+        }
+    }
+    publicCache.set(key, stems);
+    return stems;
+}
+function readSource(cwd, stem) {
+    for (const ext of ['.ts', '.tsx', '.mts', '.js', '.mjs']) {
+        try {
+            return fs.readFileSync(path.join(cwd, stem + ext), 'utf8');
+        }
+        catch {
+            // try the next extension
+        }
+    }
+    return '';
+}
+/** Whether the TypeScript project around `file` emits declarations (declaration or composite, following extends). */
+export function emitsDeclarations(cwd, file) {
+    for (let dir = path.posix.dirname(file);; dir = path.posix.dirname(dir)) {
+        const tsconfig = path.join(cwd, dir === '.' ? 'tsconfig.json' : `${dir}/tsconfig.json`);
+        if (fs.existsSync(tsconfig))
+            return declarationsIn(tsconfig, 0);
+        if (dir === '.' || dir === '/')
+            return false;
+    }
+}
+function declarationsIn(tsconfig, depth) {
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(tsconfig, 'utf8').replace(/^\s*\/\/.*$/gm, '').replace(/,(\s*[}\]])/g, '$1'));
+    }
+    catch {
+        return false;
+    }
+    const options = config?.compilerOptions ?? {};
+    if (typeof options.declaration === 'boolean' || typeof options.composite === 'boolean')
+        return options.declaration === true || options.composite === true;
+    if (typeof config?.extends === 'string' && config.extends.startsWith('.') && depth < 5) {
+        const parent = path.resolve(path.dirname(tsconfig), config.extends.endsWith('.json') ? config.extends : `${config.extends}.json`);
+        return declarationsIn(parent, depth + 1);
+    }
+    return false;
+}

package/dist/review/query-patterns.d.ts

@@ -0,0 +1,2 @@
+import type { Config, Failure } from '../types/index.js';
+export declare function queryPatternFailures(cwd: string, changedLines: Record<string, Set<number>>, config: Config): Failure[];

package/dist/review/query-patterns.js

@@ -0,0 +1,153 @@
+/**
+ * Query shapes that cost production, on lines a change adds (query-builder chains such as
+ * PostgREST/Supabase, Knex, Drizzle):
+ *
+ * - offset-paging: `.range(from, to)` or `.offset(n)` inside a loop, or in a callback handed to a
+ *   pager (the bounds are the callback's own parameters, so something calls it page after page). Each page re-reads and skips
+ *   every row before it, so a sweep over N rows reads O(N²); rows inserted mid-sweep shift pages,
+ *   so rows are skipped or read twice. Keyset paging (`.gt(id, last)` + order + limit) does not.
+ * - unbounded-window: a lower bound on a time column (`.gt`/`.gte`) taken from a window object
+ *   (`window.from`, `range.start`) with no upper bound on the same column in the same query: the
+ *   code has a window with an end and reads only half of it, so every run reads up to "now" and
+ *   rows written while it runs land in two windows. A bare "since" (everything after an event) is
+ *   a legitimate query and is not reported.
+ *
+ * Read from the syntax tree, so a comment or string never matches.
+ */
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+const CODE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+const SKIPPED = /\.(test|spec)\.|\.d\.ts$|(^|\/)(__tests__|tests?|e2e)\//;
+const TIME_COLUMN = /(_at|_on|At|On|date|Date|time|Time|timestamp|Timestamp)$|^(at|since|until|created|updated)$/;
+const LOWER = new Set(['gt', 'gte']);
+const UPPER = new Set(['lt', 'lte']);
+export function queryPatternFailures(cwd, changedLines, config) {
+    if (!config.gates.query_patterns?.enabled)
+        return [];
+    const failures = [];
+    for (const [file, lines] of Object.entries(changedLines)) {
+        if (!CODE.test(file) || SKIPPED.test(file) || lines.size === 0)
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(cwd, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (!/\.(range|offset|gte?)\(/.test(text))
+            continue;
+        const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+        const lineOf = (node) => source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+        const visit = (node) => {
+            if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+                const method = node.expression.name.text;
+                const line = lineOf(node.expression.name);
+                if (lines.has(line)) {
+                    if (isOffsetPage(method, node) && (insideLoop(node) || pagerCallback(node)))
+                        failures.push(offsetPaging(file, line, method));
+                    if (LOWER.has(method)) {
+                        const column = columnOf(node, source);
+                        if (column && TIME_COLUMN.test(column.replace(/['"`]/g, '').split('.').pop() ?? '') && fromWindow(node) && !hasUpperBound(node, column, source)) {
+                            failures.push(unboundedWindow(file, line, column));
+                        }
+                    }
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    return failures;
+}
+function isOffsetPage(method, call) {
+    return (method === 'range' && call.arguments.length === 2) || (method === 'offset' && call.arguments.length === 1);
+}
+/** A loop between the call and the function it is in. */
+function insideLoop(node) {
+    for (let current = node.parent; current; current = current.parent) {
+        if (ts.isForStatement(current) || ts.isForOfStatement(current) || ts.isForInStatement(current) || ts.isWhileStatement(current) || ts.isDoStatement(current))
+            return true;
+        if (ts.isFunctionLike(current))
+            return false;
+    }
+    return false;
+}
+/**
+ * The offset comes from a parameter of a function passed as an argument (`readAllPages((from, to) =>
+ * q.range(from, to))`): a pager calls it once per page. A named function taking bounds from a
+ * request (UI pagination, one page per call) is not this.
+ */
+function pagerCallback(call) {
+    let fn = call.parent;
+    while (fn && !ts.isFunctionLike(fn))
+        fn = fn.parent;
+    if (!fn || !(ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) || !ts.isCallExpression(fn.parent) || !fn.parent.arguments.includes(fn))
+        return false;
+    const params = new Set(fn.parameters.map(p => (ts.isIdentifier(p.name) ? p.name.text : '')).filter(Boolean));
+    const offset = call.arguments[0];
+    return !!offset && ts.isIdentifier(offset) && params.has(offset.text);
+}
+/** The lower bound is one end of a window object: `window.from`, `range.start`, `span.begin`. */
+function fromWindow(call) {
+    const bound = call.arguments[1];
+    return !!bound && ts.isPropertyAccessExpression(bound) && /^(from|start|begin|after|lower)$/.test(bound.name.text);
+}
+function columnOf(call, source) {
+    const first = call.arguments[0];
+    return first ? first.getText(source) : undefined;
+}
+/** The whole builder chain this call belongs to: every `.method(args)` from its root to its outermost call. */
+function chainCalls(call) {
+    let top = call;
+    while (top.parent && (ts.isPropertyAccessExpression(top.parent) || (ts.isCallExpression(top.parent) && top.parent.expression === top) || ts.isAwaitExpression(top.parent) || ts.isNonNullExpression(top.parent))) {
+        top = top.parent;
+    }
+    const calls = [];
+    const walk = (node) => {
+        if (ts.isCallExpression(node))
+            calls.push(node);
+        if (ts.isCallExpression(node) || ts.isPropertyAccessExpression(node) || ts.isAwaitExpression(node) || ts.isNonNullExpression(node)) {
+            walk(ts.isCallExpression(node) ? node.expression : node.expression);
+        }
+    };
+    walk(top);
+    return calls;
+}
+/**
+ * An upper bound on the same column in the same query. A chain built in steps (`let q = …; q = q.lte(…)`)
+ * or a bound added through a variable cannot be followed, so a query assembled outside one
+ * expression is given the benefit of the doubt: only a single self-contained chain is reported.
+ */
+function hasUpperBound(call, column, source) {
+    const calls = chainCalls(call);
+    const rooted = calls.some(c => ts.isPropertyAccessExpression(c.expression) && /^(from|select|table|selectFrom)$/.test(c.expression.name.text));
+    if (!rooted)
+        return true;
+    return calls.some(c => ts.isPropertyAccessExpression(c.expression) && UPPER.has(c.expression.name.text) && c.arguments[0]?.getText(source) === column);
+}
+function offsetPaging(file, line, method) {
+    return {
+        id: 'offset-paging',
+        title: 'Offset paging in a loop',
+        details: `\`.${method}()\` pages by offset inside a loop: every page re-reads the rows before it, and rows written during the sweep shift the pages, so some are skipped or read twice.`,
+        severity: 'medium',
+        provenance: 'traditional',
+        files: [file],
+        line,
+        hint: 'Page by key instead: order by a unique column and read the next page with `.gt(column, lastSeen)` and a limit.',
+    };
+}
+function unboundedWindow(file, line, column) {
+    return {
+        id: 'unbounded-window',
+        title: 'Time window with no upper bound',
+        details: `The query reads ${column} from a lower bound with no upper bound: each run reads up to "now", and rows written while it runs fall into two windows.`,
+        severity: 'medium',
+        provenance: 'traditional',
+        files: [file],
+        line,
+        hint: `Bound both ends: add \`.lte(${column}, until)\` with the run's own "until".`,
+    };
+}

package/dist/review/quiet.js

@@ -20,7 +20,7 @@ import fs from 'fs';
 import path from 'path';
 import { checkId, isMuted, readOutcomes, recordOutcome, reportedCheck } from './check-outcomes.js';
 import { readStateFile } from './trusted-state.js';
-const PROVEN_GATES = new Set(['semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests']);
+const PROVEN_GATES = new Set(['semantic-bugs', 'hallucinated-imports', 'security-patterns', 'deep-analysis', 'diff-tests', 'unused-export', 'orphan-file', 'offset-paging', 'unbounded-window', 'duplicate-function']);
 export const DISMISSED_FILE = path.join('.rigour', 'dismissed.json');
 export function isProven(failure) {
     return PROVEN_GATES.has(failure.id);

package/dist/review/review.d.ts

@@ -30,6 +30,8 @@ export interface ReviewResult {
     dismissedByGate: Record<string, number>;
     unlocated: number;
     excludedOutsideChangedLines: number;
+    /** Findings the base already had: counted, not reported (baseline.ts). */
+    preexisting: number;
     changedLines: Record<string, Set<number>>;
     report: Report | null;
     deepError?: string;

package/dist/review/review.js

@@ -19,19 +19,28 @@ import { checkId, rememberReported } from './check-outcomes.js';
 import { diffFromGit } from './git-diff.js';
 import { diffTestFailures } from './diff-test-findings.js';
 import { migrationOrderFailures } from './migration-order.js';
+import { orphanFileFailures } from './orphan-files.js';
+import { unusedExportFailures } from './unused-exports.js';
+import { queryPatternFailures } from './query-patterns.js';
+import { optionalParamFailures } from './optional-params.js';
+import { duplicateFunctionFailures } from './duplicate-functions.js';
 import { isControlFile } from './trusted-state.js';
+import { baseCommit, baseFindings, splitIntroduced } from './baseline.js';
 export async function reviewChange(input) {
     const diff = input.diff ?? diffFromGit(input.cwd, input.source);
     const changedLines = withoutGenerated(input.cwd, parseDiff(diff));
     const targets = input.files?.length ? input.files : Object.keys(changedLines);
     if (targets.length === 0) {
-        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff) };
+        return { status: 'PASS', findings: [], fileFindings: [], contextFindings: [], advisory: [], muted: 0, dismissed: 0, dismissedByGate: {}, unlocated: 0, excludedOutsideChangedLines: 0, preexisting: 0, changedLines, report: null, gateErrors: [], controlFilesChanged: controlFiles(diff) };
     }
     const deep = input.deep ? { ...input.deep, focusLines: changedLinesByFile(changedLines), removedLines: removedByFile(diff), diff } : undefined;
     const report = await new GateRunner(input.config).run(input.cwd, await normalizeScopePatterns(input.cwd, targets), deep);
+    const preexisting = await dropPreexisting(input, report, targets);
     if (input.diffTests && deep)
         report.failures.push(...await diffTestFailures(input.cwd, input.source, deep));
     report.failures.push(...migrationOrderFailures(input.cwd, diff, input.source, input.config));
+    report.failures.push(...unusedExportFailures(input.cwd, diff, input.config), ...orphanFileFailures(input.cwd, diff, input.config));
+    report.failures.push(...queryPatternFailures(input.cwd, changedLines, input.config), ...optionalParamFailures(input.cwd, changedLines, input.config), ...duplicateFunctionFailures(input.cwd, changedLines, input.config));
     const split = splitByChangedLines(report.failures, changedLines, deep ? changedFunctionSpans(input.cwd, changedLines) : {}, removedByFile(diff));
     const deepError = deepAnalysisError(report);
     const quiet = quietSplit(input.cwd, split.findings, input.config.review?.include_heuristics, input.trustedRef);
@@ -49,6 +58,7 @@ export async function reviewChange(input) {
         contextFindings: split.contextFindings,
         unlocated: split.unlocated,
         excludedOutsideChangedLines: split.outside,
+        preexisting,
         changedLines,
         report,
         gateErrors,
@@ -56,6 +66,24 @@ export async function reviewChange(input) {
         ...(deepError ? { deepError } : {}),
     };
 }
+/** Drop the rules' findings the base already had; returns how many. Model findings stay: the model reviews only the change. */
+async function dropPreexisting(input, report, targets) {
+    if (input.config.review?.show_preexisting)
+        return 0;
+    const commit = baseCommit(input.cwd, input.source ?? (input.diff ? undefined : { mode: 'working' }));
+    const rules = report.failures.filter(f => f.provenance !== 'deep-analysis');
+    if (!commit || rules.length === 0)
+        return 0;
+    try {
+        const { preexisting } = splitIntroduced(rules, await baseFindings(input.cwd, input.config, commit, targets));
+        const old = new Set(preexisting);
+        report.failures = report.failures.filter(f => !old.has(f));
+        return old.size;
+    }
+    catch {
+        return 0; // the comparison is a courtesy; it never fails a review
+    }
+}
 /** Every path the diff touches (including deletions, which parseDiff drops) that steers Rigour itself. */
 function controlFiles(diff) {
     const files = new Set();

package/dist/review/review.test.js

@@ -11,6 +11,8 @@ import { anchorInChangedFunction, changedFunctionSpans } from './changed-functio
 import { diffFromGit } from './git-diff.js';
 import { reviewChange, toReviewFinding } from './review.js';
 import { findingKey } from './quiet.js';
+/** These tests are about other checks; a new unreferenced fixture file is not their subject. */
+const NO_DEAD_CODE = { unused_exports: { enabled: false }, orphan_files: { enabled: false } };
 const LEAKY = [
     'export async function notify(endpoint: string, signature: string) {',
     "  return fetch(endpoint, { method: 'POST', headers: { 'x-hook-signature': signature } });",
@@ -115,6 +117,30 @@ describe('git-backed review', () => {
         expect(semantic.map(f => [f.files?.[0], f.line])).toEqual([['src/notify.ts', 2]]);
         expect(toReviewFinding(semantic[0])).toMatchObject({ id: 'semantic-bugs', file: 'src/notify.ts', line: 2, severity: 'high' });
     });
+    it('reports what the change introduced, not what the touched code already had', async () => {
+        const branchy = (name, extra = '') => [
+            `export function ${name}(x: number) {`,
+            ...Array.from({ length: 12 }, (_, i) => `  if (x === ${i}) return ${i};`),
+            extra,
+            '  return -1;',
+            '}',
+            '',
+        ].join('\n');
+        write('src/old.ts', branchy('legacy'));
+        git('add', '-A');
+        git('commit', '-qm', 'init');
+        write('src/old.ts', branchy('legacy', '  if (x === 99) return 99;'));
+        write('src/fresh.ts', branchy('fresh'));
+        const config = ConfigSchema.parse({ version: 1 });
+        const result = await reviewChange({ cwd: repo, config });
+        const complexity = [...result.findings, ...result.fileFindings, ...result.advisory].filter(f => f.id === 'AST_COMPLEXITY');
+        expect(complexity.map(f => f.files?.[0])).toEqual(['src/fresh.ts']);
+        expect(result.preexisting).toBeGreaterThanOrEqual(1);
+        const all = await reviewChange({ cwd: repo, config: ConfigSchema.parse({ version: 1, review: { show_preexisting: true } }) });
+        const shown = [...all.findings, ...all.fileFindings, ...all.advisory].filter(f => f.id === 'AST_COMPLEXITY');
+        expect(shown.map(f => f.files?.[0]).sort()).toEqual(['src/fresh.ts', 'src/old.ts']);
+        expect(all.preexisting).toBe(0);
+    });
     it('lets a change dismiss its own finding only when the review trusts the working tree', async () => {
         write('src/old.ts', 'export const a = 1;\n');
         write('.gitignore', '.rigour/*\n!.rigour/dismissed.json\n');
@@ -122,7 +148,7 @@ describe('git-backed review', () => {
         git('commit', '-qm', 'init');
         git('checkout', '-q', '-b', 'pr');
         write('src/notify.ts', LEAKY);
-        const config = ConfigSchema.parse({ version: 1, gates: { semantic_bugs: { enabled: true } } });
+        const config = ConfigSchema.parse({ version: 1, gates: { semantic_bugs: { enabled: true }, ...NO_DEAD_CODE } });
         const key = findingKey((await reviewChange({ cwd: repo, config })).findings[0]);
         write('.rigour/dismissed.json', JSON.stringify({ version: 1, entries: [{ key, reason: 'trust me', at: 'now' }] }));
         git('add', '-A');
@@ -147,7 +173,7 @@ describe('git-backed review', () => {
     });
     it('is ERROR when a proven gate crashed, and only lists a crashed heuristic gate', async () => {
         write('src/a.ts', 'export const a = 1;\n');
-        const config = ConfigSchema.parse({ version: 1 });
+        const config = ConfigSchema.parse({ version: 1, gates: NO_DEAD_CODE });
         const crash = (summary) => vi.spyOn(GateRunner.prototype, 'run').mockResolvedValueOnce({ status: 'FAIL', summary, failures: [], stats: { duration_ms: 0 } });
         crash({ 'hallucinated-imports': 'ERROR' });
         const proven = await reviewChange({ cwd: repo, config });

package/dist/review/reviewer.d.ts

@@ -0,0 +1,55 @@
+import type { Config } from '../types/index.js';
+export interface PriorPoint {
+    point: string;
+    resolved: boolean;
+    evidence?: string;
+    /** As the human marked it: false for a nit, a question, or a point they said was optional. Open non-blocking points are listed for the reply, not held against the push. */
+    blocking?: boolean;
+}
+export interface BlockingIssue {
+    file: string;
+    line?: number;
+    issue: string;
+    why?: string;
+}
+export interface ReviewerVerdict {
+    prior_points: PriorPoint[];
+    blocking: BlockingIssue[];
+    non_blocking: Array<{
+        file: string;
+        issue: string;
+    }>;
+}
+export interface ReviewerResult {
+    verdict?: ReviewerVerdict;
+    /** Why there is no verdict: the reviewer could not run or answered badly. Never a pass. */
+    error?: string;
+    /** The human review it worked from, if any (`Reviewer: <login>, <date>`). */
+    previousReview?: string;
+    cached: boolean;
+}
+/** How commands are run; tests replace it. */
+export type Exec = (command: string, args: string[], options: {
+    cwd: string;
+    timeoutMs: number;
+    env?: Record<string, string>;
+}) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** Called while the reviewer works, so a slow run and a stuck one look different. */
+export type Progress = (message: string) => void;
+export declare function runReviewer(cwd: string, base: string, config: Config, exec?: Exec, progress?: Progress): Promise<ReviewerResult>;
+/** Open blocking points and new blocking issues: what stops a push. An open non-blocking point is answered in the reply, not held against the push. */
+export declare function reviewerBlocks(result: ReviewerResult): boolean;
+/** The reviewer's answer as a verdict, or why it is not one. */
+export declare function parseVerdict(answer: {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}, hadReview: boolean): {
+    verdict: ReviewerVerdict;
+} | {
+    error: string;
+};