@rigour-labs/core 6.4.4 → 6.5.1

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

@@ -0,0 +1,19 @@
+/**
+ * Agentic review of one changed file: the model reviews it and may look
+ * things up (read files, search the repository) before it answers.
+ *
+ * Used when a cloud review has no diff to read as a whole (`rigour check
+ * <paths> --deep`); a pull request is reviewed as one conversation instead
+ * (pr-review.ts). What the model read extends the grounding context, so a
+ * finding it supports with code it looked up is still verified against code
+ * it actually saw.
+ */
+import type { DeepFinding, InferenceOptions, InferenceProvider } from '../inference/types.js';
+import type { CodeContext } from './code-context.js';
+export interface AgentReviewResult {
+    findings: DeepFinding[];
+    /** The sent context, extended with what the model read in the reviewed file. */
+    context: CodeContext;
+    toolCalls: number;
+}
+export declare function reviewWithTools(provider: InferenceProvider, context: CodeContext, reference: string, cwd: string, inference: InferenceOptions): Promise<AgentReviewResult>;

package/dist/deep/agent-review.js

@@ -0,0 +1,19 @@
+import { buildCodeReviewPrompt } from './code-review-prompt.js';
+import { parseFindings } from './parse-findings.js';
+import { runToolLoop } from './tool-loop.js';
+const BUDGET = { maxToolCalls: 12, maxTurns: 8 };
+const TOOL_GUIDANCE = `TOOLS: you can call read_file and grep. Before you report a defect that depends on code you were not shown `
+    + `(a caller, a callee, a type, a constant, a config value), look it up. Drop a suspicion the code disproves. `
+    + `You have at most ${BUDGET.maxToolCalls} tool calls; when you are done, answer with the JSON findings only.`;
+export async function reviewWithTools(provider, context, reference, cwd, inference) {
+    const prompt = `${buildCodeReviewPrompt(context, reference)}\n\n${TOOL_GUIDANCE}`;
+    const loop = await runToolLoop(provider, prompt, cwd, inference, BUDGET);
+    return { findings: parseFindings(loop.text), context: grounded(context, loop.toolbox), toolCalls: loop.toolCalls };
+}
+/** Lines of the reviewed file the model read count as shown; so does any text it read, for cited identifiers. */
+function grounded(context, toolbox) {
+    const reads = toolbox.reads.get(context.file) ?? [];
+    if (reads.length === 0 && !toolbox.readText)
+        return context;
+    return { ...context, ranges: [...context.ranges, ...reads], source: `${context.source}\n${toolbox.readText}` };
+}

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

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

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

@@ -0,0 +1,53 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { reviewWithTools } from './agent-review.js';
+import { verifyCodeFindings } from './code-verifier.js';
+let repo;
+beforeEach(() => {
+    repo = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-review-'));
+    fs.writeFileSync(path.join(repo, 'limits.ts'), 'export const MAX_ROWS = 0;\n');
+    fs.writeFileSync(path.join(repo, 'page.ts'), Array.from({ length: 60 }, (_, i) => `// line ${i + 1}`).join('\n'));
+});
+afterEach(() => { fs.rmSync(repo, { recursive: true, force: true }); });
+const context = { file: 'page.ts', language: 'typescript', text: '1| export function page() {}', ranges: [[1, 5]], source: 'export function page() {}' };
+function scripted(replies) {
+    const seen = [];
+    const provider = {
+        name: 'fake', isAvailable: async () => true, setup: async () => { }, dispose: () => { }, analyze: async () => '',
+        chat: async (messages, tools, options) => {
+            seen.push({ messages: [...messages], tools: tools.length, toolChoice: options?.toolChoice });
+            return replies.shift() ?? { text: '{"findings": []}', toolCalls: [] };
+        },
+    };
+    return { provider, seen };
+}
+const findingJson = (line, description) => JSON.stringify({ findings: [{ category: 'correctness', severity: 'high', file: 'page.ts', line, description, suggestion: 's', confidence: 0.9 }] });
+describe('reviewWithTools', () => {
+    it('runs the tools the model asks for, then grounds its finding in what it read', async () => {
+        const { provider, seen } = scripted([
+            { text: '', toolCalls: [{ id: 't1', name: 'read_file', arguments: { path: 'limits.ts' } }, { id: 't2', name: 'read_file', arguments: { path: 'page.ts', start_line: 40, end_line: 45 } }] },
+            { text: findingJson(42, '`MAX_ROWS` is 0, so the page loop never runs.'), toolCalls: [] },
+        ]);
+        const result = await reviewWithTools(provider, context, '', repo, {});
+        expect(result.toolCalls).toBe(2);
+        const toolResults = seen[1].messages.filter(m => m.role === 'tool').map(m => m.content);
+        expect(toolResults[0]).toContain('export const MAX_ROWS = 0;');
+        // Line 42 was outside the sent source, but the model read it, and it read MAX_ROWS.
+        expect(verifyCodeFindings(result.findings, [result.context])).toHaveLength(1);
+        expect(verifyCodeFindings(result.findings, [context])).toHaveLength(0);
+    });
+    it('forbids tool calls after the budget, keeping the tools defined for the history, and asks for the answer', async () => {
+        const greedy = Array.from({ length: 20 }, (_, i) => ({ text: '', toolCalls: [{ id: `t${i}`, name: 'grep', arguments: { pattern: 'line' } }] }));
+        const { provider, seen } = scripted(greedy);
+        const result = await reviewWithTools(provider, context, '', repo, {});
+        expect(result.toolCalls).toBeLessThanOrEqual(12);
+        expect(seen.at(-1)).toMatchObject({ tools: 2, toolChoice: 'none' });
+        expect(result.findings).toEqual([]);
+    });
+    it('refuses a provider that cannot call tools', async () => {
+        const provider = { name: 'local', isAvailable: async () => true, setup: async () => { }, dispose: () => { }, analyze: async () => '' };
+        await expect(reviewWithTools(provider, context, '', repo, {})).rejects.toThrow('cannot call tools');
+    });
+});

package/dist/deep/code-pass.d.ts

@@ -18,6 +18,12 @@ export interface CodePassConfig extends PassConfig {
         removed?: Record<string, RemovedBlock[]>;
         prBody?: string;
     };
+    /** Epoch ms after which no new file is started (the run budget). */
+    deadline?: number;
+    /** Files reviewed at once. */
+    concurrency?: number;
+    /** Let a tool-capable provider read the repository while it reviews (agent-review.ts). */
+    agentic?: boolean;
 }
 export interface CodePassResult extends PassResult {
     contexts: CodeContext[];
@@ -25,5 +31,9 @@ export interface CodePassResult extends PassResult {
     proposed: number;
     /** Of those, withdrawn by the self-check. */
     withdrawn: number;
+    /** Files not started before the deadline. */
+    skipped: number;
+    /** Repository lookups the model made (agentic review). */
+    toolCalls: number;
 }
 export declare function runCodePass(provider: InferenceProvider, facts: FileFacts[], config: CodePassConfig): Promise<CodePassResult>;

package/dist/deep/code-pass.js

@@ -9,47 +9,78 @@ import { buildCodeReviewPrompt } from './code-review-prompt.js';
 import { parseFindings } from './parse-findings.js';
 import { buildReferencePack } from './reference-pack.js';
 import { selfCheck } from './self-check.js';
+import { reviewWithTools } from './agent-review.js';
 import { Logger } from '../utils/logger.js';
 export async function runCodePass(provider, facts, config) {
-    const result = { findings: [], chunksTotal: facts.length, chunksFailed: 0, contexts: [], proposed: 0, withdrawn: 0 };
-    for (let i = 0; i < facts.length; i++) {
-        const file = facts[i];
-        config.onProgress?.(`  Reviewing ${file.path} (${i + 1}/${facts.length})...`);
-        let context;
-        try {
-            const content = await fs.readFile(path.join(config.cwd, file.path), 'utf-8');
-            context = buildCodeContext(file, content, {
-                maxChars: config.maxSourceChars,
-                focusLines: config.focusLines?.[file.path],
-            });
+    const result = { findings: [], chunksTotal: facts.length, chunksFailed: 0, contexts: [], proposed: 0, withdrawn: 0, skipped: 0, toolCalls: 0 };
+    const reviews = new Array(facts.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < facts.length) {
+            const index = next++;
+            if (config.deadline !== undefined && Date.now() >= config.deadline)
+                continue;
+            config.onProgress?.(`  Reviewing ${facts[index].path} (${index + 1}/${facts.length})...`);
+            reviews[index] = await reviewFile(provider, facts[index], config);
         }
-        catch (error) {
-            recordFailure(result, `${file.path}: ${error.message}`, config);
+    };
+    const workers = Math.max(1, Math.min(config.concurrency ?? 1, facts.length));
+    await Promise.all(Array.from({ length: workers }, worker));
+    // Merge in file order, so the result does not depend on which call finished first.
+    for (const review of reviews) {
+        if (!review) {
+            result.skipped++;
             continue;
         }
-        const pack = config.reference ? packFor(file.path, config) : undefined;
-        if (pack)
-            context = { ...context, source: `${context.source}\n${pack.source}` };
-        result.contexts.push(context);
-        try {
-            if (pack) {
-                const checked = await reviewTwiceAndCheck(provider, context, pack, config);
-                result.findings.push(...checked.kept);
-                result.proposed += checked.proposed;
-                result.withdrawn += checked.withdrawn;
-            }
-            else {
-                const found = await reviewOnce(provider, context, '', config);
-                result.findings.push(...found);
-                result.proposed += found.length;
-            }
-        }
-        catch (error) {
-            recordFailure(result, `${file.path}: ${error.message}`, config);
-        }
+        if (review.context)
+            result.contexts.push(review.context);
+        if (review.error)
+            recordFailure(result, review.error, config);
+        result.findings.push(...review.findings);
+        result.proposed += review.proposed;
+        result.withdrawn += review.withdrawn;
+        result.toolCalls += review.toolCalls ?? 0;
     }
     return result;
 }
+async function reviewFile(provider, file, config) {
+    const empty = { findings: [], proposed: 0, withdrawn: 0 };
+    let context;
+    try {
+        const content = await fs.readFile(path.join(config.cwd, file.path), 'utf-8');
+        context = buildCodeContext(file, content, {
+            maxChars: config.maxSourceChars,
+            focusLines: config.focusLines?.[file.path],
+        });
+    }
+    catch (error) {
+        return { ...empty, error: `${file.path}: ${error.message}` };
+    }
+    const pack = config.reference ? packFor(file.path, config) : undefined;
+    if (pack)
+        context = { ...context, source: `${context.source}\n${pack.source}` };
+    try {
+        if (pack && config.agentic && provider.chat)
+            return await reviewAgentically(provider, context, pack, config);
+        if (pack) {
+            const checked = await reviewTwiceAndCheck(provider, context, pack, config);
+            return { context, findings: checked.kept, proposed: checked.proposed, withdrawn: checked.withdrawn };
+        }
+        const found = await reviewOnce(provider, context, '', config);
+        return { context, findings: found, proposed: found.length, withdrawn: 0 };
+    }
+    catch (error) {
+        return { ...empty, context, error: `${file.path}: ${error.message}` };
+    }
+}
+async function reviewAgentically(provider, context, pack, config) {
+    const review = await reviewWithTools(provider, context, pack.text, config.cwd, config.inference);
+    const found = dedupe(review.findings);
+    if (found.length === 0)
+        return { context: review.context, findings: [], proposed: 0, withdrawn: 0, toolCalls: review.toolCalls };
+    const checked = await selfCheck(provider, review.context, pack.text, found, config.inference);
+    return { context: review.context, findings: checked.kept, proposed: found.length, withdrawn: checked.withdrawn, toolCalls: review.toolCalls };
+}
 async function reviewOnce(provider, context, reference, config) {
     return parseFindings(await provider.analyze(buildCodeReviewPrompt(context, reference), config.inference));
 }

package/dist/deep/code-pass.test.js

@@ -3,7 +3,7 @@ import os from 'os';
 import path from 'path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { runCodePass } from './code-pass.js';
-import { parseVerdict } from './self-check.js';
+import { parseVerdicts } from './self-check.js';
 let dir;
 afterEach(() => { if (dir)
     fs.rmSync(dir, { recursive: true, force: true }); dir = undefined; });
@@ -12,16 +12,17 @@ const facts = { path: 'total.ts', language: 'typescript', classes: [], functions
 function finding(line, category, description) {
     return { category, severity: 'high', file: 'total.ts', line, description, suggestion: 's', confidence: 0.9 };
 }
-/** Review passes answer from `reviews` in turn; self-checks withdraw findings whose line is in `withdraw`. */
+const isCheck = (prompt) => /^You reported \d+ defect/.test(prompt);
+/** Review passes answer from `reviews` in turn; the self-check withdraws findings whose line is in `withdraw`. */
 function fakeProvider(reviews, withdraw) {
     const prompts = [];
     const provider = {
         name: 'fake', isAvailable: async () => true, setup: async () => { }, dispose: () => { },
         analyze: async (prompt) => {
             prompts.push(prompt);
-            if (prompt.startsWith('You reported a defect')) {
-                const line = Number(prompt.match(/REPORTED at total\.ts:(\d+)/)?.[1]);
-                return JSON.stringify({ real: !withdraw.includes(line) });
+            if (isCheck(prompt)) {
+                const listed = [...prompt.matchAll(/^(\d+)\. total\.ts:(\d+):/gm)];
+                return JSON.stringify({ verdicts: listed.map(m => ({ n: Number(m[1]), real: !withdraw.includes(Number(m[2])) })) });
             }
             return JSON.stringify({ findings: reviews.shift() ?? [] });
         },
@@ -46,7 +47,7 @@ describe('runCodePass', () => {
         await run(provider, { maxChars: 4000, prBody: 'Sum the basket.' });
         expect(prompts).toHaveLength(1);
     });
-    it('with reference material, reviews twice in opposite orders, merges, and keeps what the self-check confirms', async () => {
+    it('with reference material, reviews twice in opposite orders, merges, and keeps what one self-check call confirms', async () => {
         const { provider, prompts } = fakeProvider([
             [finding(3, 'correctness', 'reads past the end of `items`')],
             [finding(3, 'correctness', 'same bug seen again'), finding(2, 'consistency', 'style-ish claim about `sum`')],
@@ -55,17 +56,57 @@ describe('runCodePass', () => {
             maxChars: 4000, prBody: 'Sum the basket.',
             removed: { 'total.ts': [{ line: 3, text: ['  for (let i = 0; i < items.length; i++) sum += items[i];'] }] },
         });
-        const reviews = prompts.filter(p => !p.startsWith('You reported a defect'));
+        const reviews = prompts.filter(p => !isCheck(p));
         expect(reviews).toHaveLength(2);
         expect(reviews[0].indexOf('PR DESCRIPTION')).toBeLessThan(reviews[0].indexOf('REMOVED by this change'));
         expect(reviews[1].indexOf('REMOVED by this change')).toBeLessThan(reviews[1].indexOf('PR DESCRIPTION'));
-        expect(prompts.filter(p => p.startsWith('You reported a defect'))).toHaveLength(2);
+        expect(prompts.filter(isCheck)).toHaveLength(1);
         expect(result.findings.map(f => [f.line, f.category])).toEqual([[3, 'correctness']]);
         expect([result.proposed, result.withdrawn]).toEqual([2, 1]); // two distinct findings, one withdrawn
     });
-    it('reads a self-check reply only when it is a verdict', () => {
-        expect(parseVerdict('{"real": false, "reason": "handled"}')).toBe(false);
-        expect(parseVerdict('Sure! {"real": true}')).toBe(true);
-        expect(parseVerdict('I am not sure')).toBeUndefined();
+    it('reads only well-formed verdicts from a self-check reply', () => {
+        expect([...parseVerdicts('Sure! {"verdicts": [{"n": 1, "real": false}, {"n": 2, "real": true}, {"n": "3", "real": false}]}')])
+            .toEqual([[1, false], [2, true]]);
+        expect(parseVerdicts('I am not sure').size).toBe(0);
+    });
+    it('keeps every finding when the self-check call fails', async () => {
+        const { provider } = fakeProvider([[finding(3, 'correctness', 'reads past the end of `items`')], []], []);
+        const analyze = provider.analyze;
+        provider.analyze = async (prompt, options) => isCheck(prompt) ? Promise.reject(new Error('timeout')) : analyze(prompt, options);
+        const result = await run(provider, { maxChars: 4000, prBody: 'Sum the basket.', removed: { 'total.ts': [{ line: 3, text: ['x'] }] } });
+        expect(result.findings.map(f => f.line)).toEqual([3]);
+        expect(result.withdrawn).toBe(0);
+    });
+    it('starts no file after the deadline, and counts what it skipped', async () => {
+        const { provider, prompts } = fakeProvider([[]], []);
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), 'code-pass-'));
+        fs.writeFileSync(path.join(dir, 'total.ts'), SOURCE);
+        const result = await runCodePass(provider, [facts, facts], { cwd: dir, inference: {}, maxSourceChars: 10_000, deadline: Date.now() - 1 });
+        expect(prompts).toHaveLength(0);
+        expect(result.skipped).toBe(2);
+    });
+    it('reviews files concurrently but reports them in file order', async () => {
+        dir = fs.mkdtempSync(path.join(os.tmpdir(), 'code-pass-'));
+        const names = ['a.ts', 'b.ts', 'c.ts'];
+        for (const name of names)
+            fs.writeFileSync(path.join(dir, name), SOURCE);
+        let inFlight = 0;
+        let peak = 0;
+        const provider = {
+            name: 'fake', isAvailable: async () => true, setup: async () => { }, dispose: () => { },
+            analyze: async (prompt) => {
+                inFlight++;
+                peak = Math.max(peak, inFlight);
+                const file = names.find(n => prompt.includes(n));
+                await new Promise(resolve => setTimeout(resolve, file === 'a.ts' ? 30 : 5));
+                inFlight--;
+                return JSON.stringify({ findings: [{ ...finding(3, 'correctness', 'off by one'), file }] });
+            },
+        };
+        const many = names.map(name => ({ ...facts, path: name }));
+        const result = await runCodePass(provider, many, { cwd: dir, inference: {}, maxSourceChars: 10_000, concurrency: 2 });
+        expect(peak).toBe(2);
+        expect(result.findings.map(f => f.file)).toEqual(names);
+        expect(result.contexts.map(c => c.file)).toEqual(names);
     });
 });

package/dist/deep/code-verifier.d.ts

@@ -14,6 +14,8 @@
 import type { DeepFinding } from '../inference/types.js';
 import type { CodeContext } from './code-context.js';
 import type { VerifiedFinding } from './verifier.js';
-export declare function verifyCodeFindings(findings: DeepFinding[], contexts: CodeContext[]): VerifiedFinding[];
+export type RejectionReason = 'no_context' | 'low_confidence' | 'no_line' | 'out_of_range' | 'ungrounded_identifier';
+/** Grounded findings, and how many were dropped for each reason (so a drop is never silent). */
+export declare function verifyCodeFindings(findings: DeepFinding[], contexts: CodeContext[], rejected?: Partial<Record<RejectionReason, number>>): VerifiedFinding[];
 /** Backticked, identifier-like tokens (skips quoted prose and code fragments). */
 export declare function quotedIdentifiers(text: string): string[];

package/dist/deep/code-verifier.js

@@ -1,28 +1,28 @@
 const MIN_CONFIDENCE = 0.3;
-export function verifyCodeFindings(findings, contexts) {
+/** Grounded findings, and how many were dropped for each reason (so a drop is never silent). */
+export function verifyCodeFindings(findings, contexts, rejected = {}) {
     const verified = [];
     for (const finding of findings) {
         const context = findContext(finding.file, contexts);
-        if (!context)
-            continue;
-        const note = rejectionReason(finding, context);
-        if (note)
+        const reason = context ? rejectionReason(finding, context) : 'no_context';
+        if (reason) {
+            rejected[reason] = (rejected[reason] ?? 0) + 1;
             continue;
+        }
         verified.push({ ...finding, file: context.file, verified: true, verificationNotes: 'grounded in sent source' });
     }
     return verified;
 }
 function rejectionReason(finding, context) {
     if (finding.confidence < MIN_CONFIDENCE)
-        return 'low confidence';
+        return 'low_confidence';
     const line = typeof finding.line === 'number' && finding.line > 0 ? finding.line : null;
     if (line === null)
-        return 'no line';
+        return 'no_line';
     if (!context.ranges.some(([s, e]) => line >= s && line <= e))
-        return 'line outside sent source';
-    const missing = quotedIdentifiers(finding.description).find(id => !context.source.includes(id));
-    if (missing)
-        return `identifier \`${missing}\` not in sent source`;
+        return 'out_of_range';
+    if (quotedIdentifiers(finding.description).some(id => !context.source.includes(id)))
+        return 'ungrounded_identifier';
     return null;
 }
 /** Backticked, identifier-like tokens (skips quoted prose and code fragments). */

package/dist/deep/code-verifier.test.js

@@ -15,6 +15,14 @@ function finding(overrides) {
     };
 }
 describe('verifyCodeFindings', () => {
+    it('counts every dropped finding by reason, so a drop is never silent', () => {
+        const rejected = {};
+        verifyCodeFindings([
+            finding({}), finding({ file: 'src/other.ts' }), finding({ line: 80 }), finding({ line: undefined }),
+            finding({ confidence: 0.1 }), finding({ description: '`fetchEverything` has no limit.' }),
+        ], [context], rejected);
+        expect(rejected).toEqual({ no_context: 1, out_of_range: 1, no_line: 1, low_confidence: 1, ungrounded_identifier: 1 });
+    });
     it('keeps a finding grounded in the sent source', () => {
         const [kept] = verifyCodeFindings([finding({})], [context]);
         expect(kept).toMatchObject({ file: 'src/api/report.ts', verified: true });

package/dist/deep/pr-diff.d.ts

@@ -0,0 +1,7 @@
+export interface DiffSection {
+    file: string;
+    /** The section with new-side line numbers. */
+    text: string;
+    addedLines: number;
+}
+export declare function diffSections(diff: string): DiffSection[];

package/dist/deep/pr-diff.js

@@ -0,0 +1,47 @@
+/**
+ * A diff as a reviewer reads it: one section per file, every new-side line
+ * carrying its line number, so a finding can name the exact line to fix.
+ * Lockfiles, build output and minified files carry no reviewable logic and
+ * are left out.
+ */
+const GENERATED = /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb|Cargo\.lock|poetry\.lock|go\.sum)$|(^|\/)(dist|build|out|coverage|\.next|node_modules)\/|\.min\.(js|css)$|\.(snap|map)$|(\.|-|_)(gen|generated|pb)\.[cm]?[jt]sx?$|(^|\/)__generated__\//;
+export function diffSections(diff) {
+    const sections = [];
+    let current = null;
+    let newLine = 0;
+    let out = [];
+    const flush = () => {
+        if (current && !GENERATED.test(current.file))
+            sections.push({ ...current, text: out.join('\n') });
+    };
+    for (const line of diff.split('\n')) {
+        if (line.startsWith('diff --git ')) {
+            flush();
+            current = { file: '', text: '', addedLines: 0 };
+            out = [];
+        }
+        else if (!current) {
+            continue;
+        }
+        else if (line.startsWith('+++ ')) {
+            current.file = line.startsWith('+++ b/') ? line.slice(6).trim() : '';
+            out.push(`FILE ${current.file || '(deleted)'}`);
+        }
+        else if (line.startsWith('@@')) {
+            newLine = Number(/\+(\d+)/.exec(line)?.[1] ?? 1);
+            out.push(line);
+        }
+        else if (line.startsWith('+')) {
+            out.push(`${String(newLine++).padStart(5)} + ${line.slice(1)}`);
+            current.addedLines++;
+        }
+        else if (line.startsWith('-') && !line.startsWith('--- ')) {
+            out.push(`      - ${line.slice(1)}`);
+        }
+        else if (line.startsWith(' ')) {
+            out.push(`${String(newLine++).padStart(5)}   ${line.slice(1)}`);
+        }
+    }
+    flush();
+    return sections.filter(s => s.file);
+}

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

@@ -0,0 +1,33 @@
+import type { DeepFinding, InferenceOptions, InferenceProvider } from '../inference/types.js';
+import type { CodeContext } from './code-context.js';
+import type { RelatedChange } from './related-changes.js';
+export interface FocusItem {
+    file: string;
+    function: string;
+    start: number;
+    questions: string[];
+}
+export interface PrReviewInput {
+    cwd: string;
+    diff: string;
+    /** Risk-ranked changed functions to look at first, with what to check. */
+    focus: FocusItem[];
+    /** Changed functions called from other changed files: both sides of a contract moved. */
+    related?: RelatedChange[];
+    /** The team's past review lessons that apply to this change, already rendered. */
+    lessons?: string;
+    /** The repository's own rules that apply to this change, already rendered. */
+    rules?: string;
+    prBody?: string;
+}
+export interface PrReviewResult {
+    findings: DeepFinding[];
+    /** Changed files and files the model read, whole, plus what it read: what findings are grounded against. */
+    contexts: CodeContext[];
+    toolCalls: number;
+}
+export declare function reviewPullRequest(provider: InferenceProvider, input: PrReviewInput, inference: InferenceOptions): Promise<PrReviewResult>;
+export declare function buildPrPrompt(input: PrReviewInput): {
+    prompt: string;
+    sentDiff: string;
+};

package/dist/deep/pr-review.js

@@ -0,0 +1,81 @@
+/**
+ * Review a pull request as one conversation, the way a senior reviewer does:
+ * read the whole diff, start with the riskiest changed functions, and look up
+ * whatever a suspicion depends on before reporting it.
+ *
+ * Reviewing file by file, a model never sees that one file now reads a value
+ * live while another still hard-codes it; on real PRs, the same model family
+ * pre-empted 1 of 10 acted-on review comments file by file, and 4 of 10
+ * reading the PR whole with repository tools, with fewer findings per PR.
+ */
+import fs from 'fs';
+import path from 'path';
+import { REVIEW_CATEGORIES } from './code-review-prompt.js';
+import { parseFindings } from './parse-findings.js';
+import { diffSections } from './pr-diff.js';
+import { runToolLoop } from './tool-loop.js';
+const BUDGET = { maxToolCalls: 24, maxTurns: 14 };
+const MAX_DIFF_CHARS = 80_000;
+const MAX_FINDINGS = 5;
+const PR_BODY_CHARS = 1500;
+export async function reviewPullRequest(provider, input, inference) {
+    const { prompt, sentDiff } = buildPrPrompt(input);
+    const loop = await runToolLoop(provider, prompt, input.cwd, inference, BUDGET);
+    const findings = parseFindings(loop.text).slice(0, MAX_FINDINGS);
+    const files = new Set([...diffSections(input.diff).map(s => s.file), ...loop.toolbox.reads.keys(), ...findings.map(f => f.file)]);
+    const shown = `${sentDiff}\n${loop.toolbox.readText}`;
+    return { findings, contexts: [...files].flatMap(file => wholeFile(input.cwd, file, shown)), toolCalls: loop.toolCalls };
+}
+export function buildPrPrompt(input) {
+    const related = input.related ?? [];
+    const relatedFiles = new Set(related.flatMap(r => [r.calleeFile, r.callerFile]));
+    const focusFiles = new Set(input.focus.map(f => f.file));
+    const rank = (file) => (relatedFiles.has(file) ? 2 : 0) + (focusFiles.has(file) ? 1 : 0);
+    const sections = diffSections(input.diff).sort((a, b) => rank(b.file) - rank(a.file));
+    const sent = [];
+    const omitted = [];
+    let used = 0;
+    for (const section of sections) {
+        if (used + section.text.length <= MAX_DIFF_CHARS) {
+            sent.push(section.text);
+            used += section.text.length;
+        }
+        else {
+            omitted.push(`- ${section.file} (+${section.addedLines} lines): use read_file`);
+        }
+    }
+    const sentDiff = sent.join('\n\n');
+    const categories = REVIEW_CATEGORIES.map(c => `- ${c.key}: ${c.focus}`).join('\n');
+    const focus = input.focus.map(f => `- ${f.file}:${f.start} \`${f.function}\`: ${f.questions.join(' ')}`).join('\n');
+    const contracts = related.map(r => `- \`${r.callee}\` changed at ${r.calleeFile}:${r.calleeLine}; called from ${r.callerFile}:${r.callerLine}, a file this PR also changes. Does the caller still match what the function now expects and returns?`).join('\n');
+    const prompt = [
+        'You are a senior engineer reviewing a pull request before it merges. Find defects this change introduces that would make the code behave wrongly, unsafely, or fail in production.',
+        `CATEGORIES:\n${categories}`,
+        `RULES:
+1. Report only defects the change introduces, anchored on a line it added or changed: use the new-side line numbers shown in the diff, and the file path after FILE.
+2. Before reporting anything that depends on code not in the diff (a caller, a callee, a type, a constant, a config value, another changed file), look it up with read_file or grep. Drop a suspicion the code disproves.
+3. Do not report style, naming, formatting, tests, documentation, or speculation about code you have not read.
+4. Put identifiers in backticks, spelled exactly as in the code.
+5. At most ${MAX_FINDINGS} findings, only ones you are confident are real. An empty list is a good answer.
+6. You have at most ${BUDGET.maxToolCalls} tool calls. Finish with ONLY JSON: {"findings":[{"category","severity","file","line","description","suggestion","confidence"}]}.`,
+        input.prBody ? `PR DESCRIPTION (what the author intended):\n${input.prBody.slice(0, PR_BODY_CHARS)}` : '',
+        input.rules ?? '',
+        input.lessons ?? '',
+        contracts ? `BOTH SIDES OF A CALL CHANGED (check these contracts first):\n${contracts}` : '',
+        focus ? `LOOK FIRST (riskiest changed functions, and what to check):\n${focus}` : '',
+        `PR DIFF (new-side line numbers on the left; "-" lines were removed):\n${sentDiff}`,
+        omitted.length ? `NOT SHOWN (diff too large):\n${omitted.join('\n')}` : '',
+    ].filter(Boolean).join('\n\n');
+    return { prompt, sentDiff };
+}
+/** A file the review may cite anywhere in, with what the model was shown for identifier checks. */
+function wholeFile(cwd, file, shown) {
+    try {
+        const content = fs.readFileSync(path.join(cwd, file), 'utf-8');
+        const lines = content.split('\n').length;
+        return [{ file, language: '', text: '', ranges: [[1, lines]], source: `${shown}\n${content}` }];
+    }
+    catch {
+        return [];
+    }
+}

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

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