@rigour-labs/core 6.4.3 → 6.5.0

package/dist/deep/pr-review.test.js

@@ -0,0 +1,80 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { verifyCodeFindings } from './code-verifier.js';
+import { diffSections } from './pr-diff.js';
+import { buildPrPrompt, reviewPullRequest } from './pr-review.js';
+const DIFF = [
+    'diff --git a/src/invoice.ts b/src/invoice.ts',
+    '--- a/src/invoice.ts',
+    '+++ b/src/invoice.ts',
+    '@@ -10,3 +10,3 @@ export function invoice(row) {',
+    '   const headers = {};',
+    "-  const cls = row.currency;",
+    "+  const cls = 'USD';",
+    '   return deliver(row, cls);',
+    'diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml',
+    '--- a/pnpm-lock.yaml',
+    '+++ b/pnpm-lock.yaml',
+    '@@ -1 +1 @@',
+    '-a',
+    '+b',
+    'diff --git a/src/price.ts b/src/price.ts',
+    '--- a/src/price.ts',
+    '+++ b/src/price.ts',
+    '@@ -1,1 +1,2 @@',
+    ' export function price(row) {',
+    '+  return row.currency;',
+].join('\n');
+describe('diffSections', () => {
+    it('numbers new-side lines, marks removals, and leaves lockfiles out', () => {
+        const sections = diffSections(DIFF);
+        expect(sections.map(s => s.file)).toEqual(['src/invoice.ts', 'src/price.ts']);
+        expect(sections[0].text).toContain("   11 +   const cls = 'USD';");
+        expect(sections[0].text).toContain("      -   const cls = row.currency;");
+        expect(sections[0].text).toContain('   12     return deliver(row, cls);');
+        expect(sections[1].addedLines).toBe(1);
+    });
+});
+describe('buildPrPrompt', () => {
+    it('puts the risky files first and points at the riskiest functions', () => {
+        const { prompt } = buildPrPrompt({ cwd: '.', diff: DIFF, focus: [{ file: 'src/price.ts', function: 'price', start: 1, questions: ['Do callers still get a currency?'] }], prBody: 'Read the currency live.' });
+        expect(prompt.indexOf('FILE src/price.ts')).toBeLessThan(prompt.indexOf('FILE src/invoice.ts'));
+        expect(prompt).toContain('- src/price.ts:1 `price`: Do callers still get a currency?');
+        expect(prompt).toContain('PR DESCRIPTION (what the author intended):\nRead the currency live.');
+        expect(prompt).not.toContain('pnpm-lock');
+    });
+});
+describe('reviewPullRequest', () => {
+    let repo;
+    beforeEach(() => {
+        repo = fs.mkdtempSync(path.join(os.tmpdir(), 'pr-review-'));
+        fs.mkdirSync(path.join(repo, 'src'));
+        fs.writeFileSync(path.join(repo, 'src/invoice.ts'), Array.from({ length: 20 }, (_, i) => i === 10 ? "  const cls = 'USD';" : `// ${i + 1}`).join('\n'));
+        fs.writeFileSync(path.join(repo, 'src/price.ts'), 'export function price(row) {\n  return row.currency;\n}\n');
+    });
+    afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+    it('reviews the PR in one conversation and grounds a cross-file finding in the files it names', async () => {
+        const replies = [
+            { text: '', toolCalls: [{ id: 'r', name: 'read_file', arguments: { path: 'src/price.ts' } }] },
+            { text: JSON.stringify({ findings: [
+                        { category: 'consistency', severity: 'high', file: 'src/invoice.ts', line: 11, description: '`cls` is hard-coded while `price` reads `currency` live.', suggestion: 's', confidence: 0.9 },
+                        { category: 'correctness', severity: 'high', file: 'src/invoice.ts', line: 11, description: '`invented_symbol` is never set.', suggestion: 's', confidence: 0.9 },
+                    ] }), toolCalls: [] },
+        ];
+        let conversations = 0;
+        const provider = {
+            name: 'fake', isAvailable: async () => true, setup: async () => { }, dispose: () => { }, analyze: async () => '',
+            chat: async (messages) => { if (messages.length === 1)
+                conversations++; return replies.shift(); },
+        };
+        const result = await reviewPullRequest(provider, { cwd: repo, diff: DIFF, focus: [] }, {});
+        expect(conversations).toBe(1);
+        expect(result.toolCalls).toBe(1);
+        const rejected = {};
+        const kept = verifyCodeFindings(result.findings, result.contexts, rejected);
+        expect(kept.map(f => f.description)).toEqual(['`cls` is hard-coded while `price` reads `currency` live.']);
+        expect(rejected).toEqual({ ungrounded_identifier: 1 });
+    });
+});

package/dist/deep/related-changes.d.ts

@@ -0,0 +1,13 @@
+import type { FunctionRisk } from './risk.js';
+export interface RelatedChange {
+    /** The changed function, and where it is defined. */
+    callee: string;
+    calleeFile: string;
+    calleeLine: number;
+    /** Another changed file that calls it, and the first call line. */
+    callerFile: string;
+    callerLine: number;
+}
+export declare function relatedChanges(cwd: string, changedFiles: string[], changed: FunctionRisk[]): RelatedChange[];
+/** The caller imports `name` from the callee's module (relative or aliased path). */
+export declare function importsFrom(text: string, name: string, callerFile: string, calleeFile: string): boolean;

package/dist/deep/related-changes.js

@@ -0,0 +1,56 @@
+/**
+ * Related changes: a function the PR changed, called from another file the
+ * PR also changed. When both sides of a call move in one PR, the contract
+ * between them is the likeliest thing to break (one side reads a value live,
+ * the other still passes a constant), and a reviewer reading file by file,
+ * or running out of budget before the second file, misses it.
+ */
+import fs from 'fs';
+import path from 'path';
+const MAX_LINKS = 8;
+const TEST_FILE = /(\.(test|spec)\.[cm]?[jt]sx?$)|(^|\/)__tests__\//;
+export function relatedChanges(cwd, changedFiles, changed) {
+    const exported = changed.filter(f => f.signals.exported && /^[A-Za-z_$][\w$]*$/.test(f.name));
+    if (exported.length === 0)
+        return [];
+    const texts = new Map(changedFiles.map(file => [file, readLines(cwd, file)]));
+    const links = [];
+    for (const fn of exported) {
+        const call = new RegExp(`(^|[^\\w$.])${fn.name.replace(/\$/g, '\\$')}\\s*\\(`);
+        for (const [file, lines] of texts) {
+            if (file === fn.file || !lines || TEST_FILE.test(file) || !importsFrom(lines.join('\n'), fn.name, file, fn.file))
+                continue;
+            const index = lines.findIndex(line => call.test(line) && !/^\s*(import|export\s+\{)/.test(line));
+            if (index === -1)
+                continue;
+            links.push({ callee: fn.name, calleeFile: fn.file, calleeLine: fn.start, callerFile: file, callerLine: index + 1 });
+            if (links.length >= MAX_LINKS)
+                return links;
+        }
+    }
+    return links;
+}
+/** The caller imports `name` from the callee's module (relative or aliased path). */
+export function importsFrom(text, name, callerFile, calleeFile) {
+    const target = calleeFile.replace(/\.[cm]?[jt]sx?$/, '').replace(/\/index$/, '');
+    const imports = text.matchAll(/import\s+(?:type\s+)?\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/g);
+    for (const [, names, spec] of imports) {
+        if (!new RegExp(`(^|[\\s,])${name.replace(/\$/g, '\\$')}(\\s|,|$)`).test(names))
+            continue;
+        const module = spec.replace(/\.[cm]?[jt]sx?$/, '').replace(/\/index$/, '');
+        const resolved = module.startsWith('.')
+            ? path.posix.normalize(path.posix.join(path.posix.dirname(callerFile), module))
+            : module.replace(/^[@~]\//, '');
+        if (target === resolved || target.endsWith(`/${resolved}`))
+            return true;
+    }
+    return false;
+}
+function readLines(cwd, file) {
+    try {
+        return fs.readFileSync(path.join(cwd, file), 'utf-8').split('\n');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/deep/related-changes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deep/related-changes.test.js

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { importsFrom, relatedChanges } from './related-changes.js';
+import { rankChangedFunctions } from './risk.js';
+let dir;
+const write = (file, body) => {
+    fs.mkdirSync(path.dirname(path.join(dir, file)), { recursive: true });
+    fs.writeFileSync(path.join(dir, file), body);
+};
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'related-')); });
+afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+describe('relatedChanges', () => {
+    it('links a changed function to another changed file that imports and calls it, never tests or same-named functions', () => {
+        write('src/billing/price.ts', 'export function priceOf(row) {\n  return row.currency;\n}\n');
+        write('src/billing/invoice.ts', "import { priceOf } from './price';\n\nexport function invoice(row) {\n  return { cur: 'USD', price: priceOf(row) };\n}\n");
+        write('src/billing/price.test.ts', "import { priceOf } from './price';\npriceOf({});\n");
+        write('src/other/price.ts', 'export function priceOf(x) {\n  return 1;\n}\n');
+        write('src/other/use.ts', "import { priceOf } from './price';\nexport const y = () => priceOf(2);\n");
+        const focus = { 'src/billing/price.ts': [2], 'src/billing/invoice.ts': [4], 'src/billing/price.test.ts': [2], 'src/other/use.ts': [2] };
+        const links = relatedChanges(dir, Object.keys(focus), rankChangedFunctions(dir, focus));
+        expect(links).toEqual([{ callee: 'priceOf', calleeFile: 'src/billing/price.ts', calleeLine: 1, callerFile: 'src/billing/invoice.ts', callerLine: 4 }]);
+    });
+});
+describe('importsFrom', () => {
+    it('resolves relative and aliased module paths', () => {
+        expect(importsFrom("import { a, b } from '../lib/x';", 'b', 'src/app/y.ts', 'src/lib/x.ts')).toBe(true);
+        expect(importsFrom('import { b } from "@/lib/x";', 'b', 'src/app/y.ts', 'src/lib/x.ts')).toBe(true);
+        expect(importsFrom("import { bb } from '../lib/x';", 'b', 'src/app/y.ts', 'src/lib/x.ts')).toBe(false);
+        expect(importsFrom("import { b } from './x';", 'b', 'src/app/y.ts', 'src/lib/x.ts')).toBe(false);
+    });
+});

package/dist/deep/review-tools.d.ts

@@ -0,0 +1,16 @@
+import type { ChatTool, ToolCall } from '../inference/types.js';
+export declare const REVIEW_TOOLS: ChatTool[];
+/** Tools bound to one repository, remembering what was read. */
+export declare class ReviewToolbox {
+    private readonly cwd;
+    /** Repository-relative path → [start, end] line ranges the model read. */
+    readonly reads: Map<string, [number, number][]>;
+    /** Text the model read, for checking identifiers it cites. */
+    readText: string;
+    constructor(cwd: string);
+    run(call: ToolCall): string;
+    private readFile;
+    private grep;
+    /** A repository-relative path that stays inside the repository and is not a secrets file. */
+    private inside;
+}

package/dist/deep/review-tools.js

@@ -0,0 +1,111 @@
+/**
+ * Read-only repository tools for an agentic review.
+ *
+ * A reviewer that can only see the chunk it was sent guesses about callers,
+ * callees and types; one that can look them up checks its suspicion first.
+ * These tools only read, only inside the repository, never secrets files,
+ * and record which lines of which files the model actually read so its
+ * findings can still be grounded (code-verifier.ts).
+ */
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+const MAX_READ_LINES = 200;
+const MAX_GREP_LINES = 40;
+const MAX_LINE_CHARS = 240;
+/** Never sent to a model provider: environment files, keys, credentials. */
+const SECRET_FILE = /(^|\/)(\.env(\..*)?|.*\.(pem|key|p12|pfx)|id_[a-z0-9]+|\.npmrc|\.netrc|credentials(\.json)?)$/i;
+export const REVIEW_TOOLS = [
+    {
+        name: 'read_file',
+        description: 'Read lines of a repository file, numbered. Use it to check callers, callees, types and constants before claiming a defect.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Repository-relative path.' },
+                start_line: { type: 'integer', description: 'First line, 1-based (default 1).' },
+                end_line: { type: 'integer', description: `Last line (at most ${MAX_READ_LINES} lines per call).` },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'grep',
+        description: 'Search tracked files with an extended regular expression. Returns path:line:text matches.',
+        parameters: {
+            type: 'object',
+            properties: {
+                pattern: { type: 'string' },
+                path_glob: { type: 'string', description: 'Optional pathspec, e.g. "src/**/*.ts".' },
+            },
+            required: ['pattern'],
+        },
+    },
+];
+/** Tools bound to one repository, remembering what was read. */
+export class ReviewToolbox {
+    cwd;
+    /** Repository-relative path → [start, end] line ranges the model read. */
+    reads = new Map();
+    /** Text the model read, for checking identifiers it cites. */
+    readText = '';
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    run(call) {
+        try {
+            if (call.name === 'read_file')
+                return this.readFile(call.arguments);
+            if (call.name === 'grep')
+                return this.grep(call.arguments);
+            return `Unknown tool "${call.name}".`;
+        }
+        catch (error) {
+            return `Error: ${error?.message ?? String(error)}`;
+        }
+    }
+    readFile(args) {
+        const file = this.inside(String(args.path ?? ''));
+        const lines = fs.readFileSync(path.join(this.cwd, file), 'utf-8').split('\n');
+        const start = clamp(Number(args.start_line) || 1, 1, lines.length);
+        const end = clamp(Number(args.end_line) || start + MAX_READ_LINES - 1, start, Math.min(lines.length, start + MAX_READ_LINES - 1));
+        const text = lines.slice(start - 1, end).map((line, i) => `${String(start + i).padStart(5)}| ${line}`).join('\n');
+        this.reads.set(file, [...(this.reads.get(file) ?? []), [start, end]]);
+        this.readText += `\n${lines.slice(start - 1, end).join('\n')}`;
+        return `${file} lines ${start}-${end} of ${lines.length}:\n${text}`;
+    }
+    grep(args) {
+        const pattern = String(args.pattern ?? '');
+        if (!pattern || pattern.length > 200)
+            return 'Error: pattern must be 1-200 characters.';
+        const spec = typeof args.path_glob === 'string' && args.path_glob ? [args.path_glob] : [];
+        let out = '';
+        try {
+            out = execFileSync('git', ['grep', '-n', '-I', '-E', '-e', pattern, '--', ...spec], {
+                cwd: this.cwd, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'], timeout: 15_000,
+            });
+        }
+        catch {
+            return 'No matches.';
+        }
+        const matches = out.split('\n').filter(line => line && !SECRET_FILE.test(line.split(':')[0]));
+        const shown = matches.slice(0, MAX_GREP_LINES).map(line => line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}…` : line);
+        this.readText += `\n${shown.join('\n')}`;
+        return shown.length ? shown.join('\n') + (matches.length > shown.length ? `\n… ${matches.length - shown.length} more` : '') : 'No matches.';
+    }
+    /** A repository-relative path that stays inside the repository and is not a secrets file. */
+    inside(requested) {
+        const root = fs.realpathSync(this.cwd);
+        const resolved = fs.realpathSync(path.resolve(root, requested));
+        const relative = path.relative(root, resolved);
+        if (!relative || relative.startsWith('..') || path.isAbsolute(relative))
+            throw new Error('path is outside the repository');
+        const posix = relative.split(path.sep).join('/');
+        if (posix.startsWith('.git/') || SECRET_FILE.test(posix))
+            throw new Error('this file is not readable by the reviewer');
+        return posix;
+    }
+}
+function clamp(value, low, high) {
+    return Math.max(low, Math.min(high, Math.floor(value)));
+}

package/dist/deep/review-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deep/review-tools.test.js

@@ -0,0 +1,39 @@
+import { execFileSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ReviewToolbox } from './review-tools.js';
+let repo;
+const call = (name, args) => ({ id: 'c1', name, arguments: args });
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'review-tools-'));
+    fs.mkdirSync(path.join(repo, 'src'));
+    fs.writeFileSync(path.join(repo, 'src/a.ts'), Array.from({ length: 300 }, (_, i) => `const v${i + 1} = ${i + 1};`).join('\n'));
+    fs.writeFileSync(path.join(repo, '.env'), 'API_KEY=secret');
+    execFileSync('git', ['init', '-q'], { cwd: repo });
+    execFileSync('git', ['add', '-A'], { cwd: repo });
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+describe('ReviewToolbox', () => {
+    it('reads numbered lines, caps a call at 200 lines, and records what was read', () => {
+        const tools = new ReviewToolbox(repo);
+        const out = tools.run(call('read_file', { path: 'src/a.ts', start_line: 10, end_line: 900 }));
+        expect(out).toContain('src/a.ts lines 10-209 of 300');
+        expect(out).toContain('   10| const v10 = 10;');
+        expect(tools.reads.get('src/a.ts')).toEqual([[10, 209]]);
+        expect(tools.readText).toContain('const v209');
+    });
+    it('refuses paths outside the repository and secrets files, without throwing', () => {
+        const tools = new ReviewToolbox(repo);
+        expect(tools.run(call('read_file', { path: '../../etc/passwd' }))).toMatch(/^Error:/);
+        expect(tools.run(call('read_file', { path: '.env' }))).toBe('Error: this file is not readable by the reviewer');
+        expect(tools.reads.size).toBe(0);
+    });
+    it('greps tracked files but never shows a secrets file', () => {
+        const tools = new ReviewToolbox(repo);
+        expect(tools.run(call('grep', { pattern: 'v12 =' }))).toBe('src/a.ts:12:const v12 = 12;');
+        expect(tools.run(call('grep', { pattern: 'API_KEY' }))).toBe('No matches.');
+        expect(tools.run(call('shell', {}))).toBe('Unknown tool "shell".');
+    });
+});

package/dist/deep/risk.d.ts

@@ -0,0 +1,41 @@
+import type { RemovedBlock } from '../utils/diff.js';
+/** Kinds of operation where a wrong line costs the most; matched on the function's text. */
+export declare const SENSITIVE: ReadonlyArray<{
+    kind: string;
+    pattern: RegExp;
+}>;
+export interface RiskSignals {
+    exported: boolean;
+    async: boolean;
+    /** Deepest nesting of branches and loops. */
+    nesting: number;
+    lines: number;
+    /** The change removed more conditions, early returns or throws from this function than it added. */
+    removedGuard: boolean;
+    /** SENSITIVE kinds this function touches. */
+    sensitive: string[];
+}
+export interface FunctionRisk {
+    file: string;
+    name: string;
+    start: number;
+    end: number;
+    signals: RiskSignals;
+    score: number;
+    /** sha256 of the function's text with whitespace collapsed: any edit to it changes this. */
+    hash: string;
+}
+/**
+ * Score one changed function from its signals; higher is riskier, 0 means
+ * "rules only". The router reviews functions at or above `min_score`.
+ */
+export declare function scoreRisk(signals: RiskSignals): number;
+/** Changed functions across the change, riskiest first. */
+export declare function rankChangedFunctions(cwd: string, focusLines: Record<string, number[]>, removed?: Record<string, RemovedBlock[]>): FunctionRisk[];
+/** The current text hash and span of a named function in a file, if the file parses and has it. */
+export declare function findFunction(cwd: string, file: string, name: string): {
+    hash: string;
+    start: number;
+    end: number;
+} | undefined;
+export declare function functionHash(text: string): string;

package/dist/deep/risk.js

@@ -0,0 +1,135 @@
+/**
+ * Risk of each changed function: which code is worth a paid model's review.
+ *
+ * Sending every changed file to a frontier model cost $0.75 per PR on real
+ * PRs; most changed functions are glue, rename or plumbing that never carries
+ * a defect a reviewer acts on. The router reviews the riskiest functions and
+ * leaves the rest to the deterministic gates. Signals are syntactic and cheap
+ * (no type checker), so ranking a large PR takes milliseconds.
+ */
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+import { changedFunctions, isExported } from './changed-functions.js';
+const PARSEABLE = /\.(?:[cm]?[jt]sx?)$/i;
+/** Kinds of operation where a wrong line costs the most; matched on the function's text. */
+export const SENSITIVE = [
+    { kind: 'data-write', pattern: /\.(?:insert|update|upsert|delete|rpc)\s*\(|\b(?:INSERT|UPDATE|DELETE)\s+(?:INTO\s+)?\w|\bON CONFLICT\b/ },
+    { kind: 'paging', pattern: /\b(?:cursor|offset|nextPage|pageToken|hasMore|limit)\b/i },
+    { kind: 'auth', pattern: /\b(?:token|session|password|secret|jwt|permission|role|authori[sz]e)\w*/i },
+    { kind: 'money-or-time', pattern: /\b(?:amount|price|cents|currency|refund|timezone|Date\.now|new Date|setTimeout|toISOString)\b/ },
+    { kind: 'concurrency', pattern: /\bPromise\.(?:all|race|allSettled)\b|\b(?:mutex|lock|semaphore|retry|backoff)\b/i },
+    { kind: 'network', pattern: /\bfetch\w*\s*\(|\bnew Request\s*\(|\bAbort(?:Controller|Signal)\b|\baxios\b|\bhttps?\.request\b/ },
+];
+/**
+ * Score one changed function from its signals; higher is riskier, 0 means
+ * "rules only". The router reviews functions at or above `min_score`.
+ */
+export function scoreRisk(signals) {
+    // Strong signals clear the default bar (1) on their own; shape alone (size, nesting) never does.
+    let score = signals.removedGuard ? 2 : 0;
+    score += signals.sensitive.includes('data-write') ? 2 : 0;
+    // Other sensitive kinds add, capped so a function that mentions everything does not drown the rest.
+    score += Math.min(2, signals.sensitive.filter(kind => kind !== 'data-write').length);
+    // Weak proxies only add to something already risky, or push a big, branchy public function over.
+    score += (signals.nesting >= 3 ? 0.5 : 0) + (signals.lines >= 40 ? 0.5 : 0);
+    score += signals.exported && signals.async ? 0.5 : 0;
+    return score;
+}
+/** Changed functions across the change, riskiest first. */
+export function rankChangedFunctions(cwd, focusLines, removed = {}) {
+    const ranked = [];
+    for (const [file, lines] of Object.entries(focusLines)) {
+        if (!PARSEABLE.test(file) || lines.length === 0)
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(cwd, file), 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+        const textLines = text.split('\n');
+        for (const fn of changedFunctions(sourceFile, lines)) {
+            const start = sourceFile.getLineAndCharacterOfPosition(fn.getStart(sourceFile)).line + 1;
+            const end = sourceFile.getLineAndCharacterOfPosition(fn.getEnd()).line + 1;
+            const added = lines.filter(l => l >= start && l <= end).map(l => textLines[l - 1] ?? '');
+            const signals = signalsOf(fn, sourceFile, start, end, removed[file] ?? [], added);
+            ranked.push({ file, name: nameOf(fn, sourceFile), start, end, signals, score: scoreRisk(signals), hash: functionHash(fn.getText(sourceFile)) });
+        }
+    }
+    return ranked.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file) || a.start - b.start);
+}
+/** The current text hash and span of a named function in a file, if the file parses and has it. */
+export function findFunction(cwd, file, name) {
+    if (!PARSEABLE.test(file))
+        return undefined;
+    let text;
+    try {
+        text = fs.readFileSync(path.join(cwd, file), 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+    const sourceFile = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+    let found;
+    const visit = (node) => {
+        if (found)
+            return;
+        if ((ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node))
+            && node.body && nameOf(node, sourceFile) === name) {
+            found = {
+                hash: functionHash(node.getText(sourceFile)),
+                start: sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1,
+                end: sourceFile.getLineAndCharacterOfPosition(node.getEnd()).line + 1,
+            };
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+export function functionHash(text) {
+    return crypto.createHash('sha256').update(text.replace(/\s+/g, ' ').trim()).digest('hex');
+}
+const GUARD = /\b(?:if|else|return|throw|break|continue|catch)\b|\?\?|\?\./g;
+function guards(lines) {
+    return lines.reduce((count, line) => count + (line.match(GUARD)?.length ?? 0), 0);
+}
+function signalsOf(fn, sourceFile, start, end, removed, added) {
+    const body = fn.getText(sourceFile);
+    const removedLines = removed.filter(block => block.line >= start && block.line <= end + 1).flatMap(block => block.text);
+    return {
+        exported: isExported(fn),
+        async: !!ts.getModifiers(fn)?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword),
+        nesting: maxNesting(fn),
+        lines: end - start + 1,
+        removedGuard: guards(removedLines) > guards(added),
+        sensitive: SENSITIVE.filter(s => s.pattern.test(body)).map(s => s.kind),
+    };
+}
+function maxNesting(fn) {
+    let deepest = 0;
+    const walk = (node, depth) => {
+        const nests = ts.isIfStatement(node) || ts.isIterationStatement(node, false) || ts.isSwitchStatement(node)
+            || ts.isTryStatement(node) || ts.isConditionalExpression(node);
+        const next = nests ? depth + 1 : depth;
+        deepest = Math.max(deepest, next);
+        if (node !== fn && (ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node)))
+            return;
+        ts.forEachChild(node, child => walk(child, next));
+    };
+    ts.forEachChild(fn, child => walk(child, 0));
+    return deepest;
+}
+function nameOf(fn, sourceFile) {
+    if (fn.name)
+        return fn.name.getText(sourceFile);
+    const parent = fn.parent;
+    if (parent && (ts.isVariableDeclaration(parent) || ts.isPropertyAssignment(parent)) && parent.name)
+        return parent.name.getText(sourceFile);
+    return `<anonymous>@${sourceFile.getLineAndCharacterOfPosition(fn.getStart(sourceFile)).line + 1}`;
+}

package/dist/deep/risk.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/deep/risk.test.js

@@ -0,0 +1,63 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { rankChangedFunctions, scoreRisk } from './risk.js';
+import { routeFiles } from './router.js';
+let dir;
+beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'risk-')); });
+afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+const SYNC = [
+    'export async function syncOrders(db, cursor) {', // 1
+    '  for (const page of pages(cursor)) {', // 2
+    '    if (page.rows.length) {', // 3
+    "      await db.from('orders').upsert(page.rows);", // 4
+    '    }', // 5
+    '  }', // 6
+    '}', // 7
+    'function label(name) {', // 8
+    '  return name.trim();', // 9
+    '}', // 10
+].join('\n');
+const plain = { exported: false, async: false, nesting: 0, lines: 3, removedGuard: false, sensitive: [] };
+describe('rankChangedFunctions', () => {
+    it('reads the signals of each changed function', () => {
+        fs.writeFileSync(path.join(dir, 'sync.ts'), SYNC);
+        const ranked = rankChangedFunctions(dir, { 'sync.ts': [4, 9] }, { 'sync.ts': [{ line: 4, text: ['    if (!page.ok) return;'] }] });
+        const byName = Object.fromEntries(ranked.map(f => [f.name, f]));
+        expect(byName.syncOrders.signals).toEqual({
+            exported: true, async: true, nesting: 2, lines: 7, removedGuard: true, sensitive: ['data-write', 'paging'],
+        });
+        expect(byName.label.signals).toMatchObject({ exported: false, async: false, nesting: 0, removedGuard: false, sensitive: [] });
+        expect([byName.label.start, byName.label.end]).toEqual([8, 10]);
+    });
+});
+describe('scoreRisk', () => {
+    it('ranks a data write behind a removed guard above a plain helper', () => {
+        const risky = { exported: true, async: true, nesting: 2, lines: 30, removedGuard: true, sensitive: ['data-write', 'paging'] };
+        expect(scoreRisk(risky)).toBeGreaterThan(scoreRisk(plain));
+    });
+    it('gives a short, flat, private, non-sensitive function no model review', () => {
+        expect(scoreRisk(plain)).toBe(0);
+    });
+    it('never scores below zero', () => {
+        expect(scoreRisk({ ...plain, lines: 1 })).toBeGreaterThanOrEqual(0);
+    });
+});
+describe('routeFiles', () => {
+    it('always keeps files it cannot rank, and reports what it left to the gates', () => {
+        fs.writeFileSync(path.join(dir, 'helper.ts'), 'function label(name) {\n  return name.trim();\n}\n');
+        fs.writeFileSync(path.join(dir, 'query.py'), 'def f():\n    return 1\n');
+        const routed = routeFiles(dir, ['helper.ts', 'query.py'], { 'helper.ts': [2], 'query.py': [2] }, {}, { min_score: 1 });
+        expect([...routed.files]).toEqual(['query.py']);
+        expect(routed.stats).toEqual({ functions: 1, routed: 0, files_skipped: 1, already_reviewed: 0 });
+    });
+    it('skips a risky function reviewed before at exactly this code, and only that code', () => {
+        fs.writeFileSync(path.join(dir, 'sync.ts'), SYNC);
+        const [risky] = rankChangedFunctions(dir, { 'sync.ts': [4] });
+        const cleared = routeFiles(dir, ['sync.ts'], { 'sync.ts': [4] }, {}, {}, [{ file: 'sync.ts', function: 'syncOrders', hash: risky.hash }]);
+        expect(cleared.stats).toMatchObject({ routed: 0, already_reviewed: 1, files_skipped: 1 });
+        const stale = routeFiles(dir, ['sync.ts'], { 'sync.ts': [4] }, {}, {}, [{ file: 'sync.ts', function: 'syncOrders', hash: 'old' }]);
+        expect(stale.stats).toMatchObject({ routed: 1, already_reviewed: 0 });
+    });
+});

package/dist/deep/router.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Router: which changed files a paid model reviews.
+ *
+ * Files are chosen through their riskiest changed function (risk.ts). A file
+ * the ranking cannot see into (another language, or a change outside any
+ * function) is always reviewed: the router only cuts what it understands.
+ */
+import type { RemovedBlock } from '../utils/diff.js';
+import { type ReviewedKey } from '../review/ledger.js';
+export interface RouterPolicy {
+    enabled?: boolean;
+    min_score?: number;
+    max_functions?: number;
+}
+export interface RouterStats {
+    functions: number;
+    routed: number;
+    files_skipped: number;
+    /** Risky functions skipped because this exact code was reviewed before (ledger or reviewed.json). */
+    already_reviewed: number;
+}
+export declare const DEFAULT_MIN_SCORE = 1;
+export declare const DEFAULT_MAX_FUNCTIONS = 12;
+export declare function routeFiles(cwd: string, files: string[], focusLines: Record<string, number[]>, removed?: Record<string, RemovedBlock[]>, policy?: RouterPolicy, reviewed?: ReviewedKey[]): {
+    files: Set<string>;
+    stats: RouterStats;
+};

package/dist/deep/router.js

@@ -0,0 +1,15 @@
+import { rankChangedFunctions } from './risk.js';
+import { isReviewed } from '../review/ledger.js';
+export const DEFAULT_MIN_SCORE = 1;
+export const DEFAULT_MAX_FUNCTIONS = 12;
+export function routeFiles(cwd, files, focusLines, removed = {}, policy = {}, reviewed = []) {
+    const inScope = Object.fromEntries(files.filter(f => focusLines[f]?.length).map(f => [f, focusLines[f]]));
+    const ranked = rankChangedFunctions(cwd, inScope, removed);
+    const minScore = policy.min_score ?? DEFAULT_MIN_SCORE;
+    const risky = ranked.filter(f => f.score >= minScore);
+    const unreviewed = risky.filter(f => !isReviewed(reviewed, { file: f.file, function: f.name, hash: f.hash }));
+    const routed = unreviewed.slice(0, policy.max_functions ?? DEFAULT_MAX_FUNCTIONS);
+    const ranks = new Set(ranked.map(f => f.file));
+    const chosen = new Set([...routed.map(f => f.file), ...files.filter(f => !ranks.has(f))]);
+    return { files: chosen, stats: { functions: ranked.length, routed: routed.length, files_skipped: files.length - chosen.size, already_reviewed: risky.length - unreviewed.length } };
+}