diffninja 0.1.0

package/dist/review/report-pages.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Loopback pages for static review reports, owned by one MCP connection.
+ *
+ * A static review returns its report to the agent as data; this serves the same
+ * report as the self-contained HTML page for the human reviewer. The page is
+ * read-only: there is no API, nothing is written to disk, and the only route is
+ * `GET /report/<token>`, where the token is 256 random bits per report. Reports
+ * embed source code, so the listener binds 127.0.0.1 only, rejects any request
+ * whose Host is not this exact origin, and forbids caching, framing, and every
+ * resource the page does not carry inline. The inline script and stylesheet are
+ * allowed by their SHA-256 hashes, so the report HTML is served byte for byte.
+ */
+import type { ReviewReport, SuggestedComment } from "./types.js";
+/** Most reports one connection keeps; the oldest page closes first. */
+export declare const MAX_REPORT_PAGES = 20;
+/** Most comments one review may carry from the agent: a reviewer's handful, not a lint dump. */
+export declare const MAX_SUGGESTED_COMMENTS = 30;
+/** Longest suggested comment: a sentence or two, the way a reviewer writes one. */
+export declare const MAX_SUGGESTED_CHARS = 280;
+/** CSP naming exactly the inline script and style blocks of one page. */
+export declare function reportPolicy(html: string): string;
+/** A static review published on this connection. */
+export interface PublishedReview {
+    readonly reviewId: string;
+    readonly url: string;
+}
+/** One answer as the agent sent it; validated against the question before it is kept. */
+export interface AnswerInput {
+    readonly questionId: string;
+    readonly choice: string;
+}
+export interface RecordedAnswers {
+    readonly reviewId: string;
+    readonly recorded: number;
+    readonly answered: number;
+    readonly unanswered: number;
+}
+export interface RecordedOrder {
+    readonly reviewId: string;
+    readonly ordered: number;
+}
+export interface RecordedComments {
+    readonly reviewId: string;
+    readonly suggested: number;
+}
+/** Everything the reviewing agent owes a review before its pages are handed out. */
+export interface FinishInput {
+    readonly answers: readonly AnswerInput[];
+    readonly order: readonly string[];
+    readonly comments: readonly SuggestedComment[];
+}
+export interface FinishedReview {
+    readonly reviewId: string;
+    readonly answered: number;
+    readonly ordered: number;
+    readonly suggested: number;
+    readonly reportUrl: string;
+}
+export declare class ReportPages {
+    private readonly render;
+    private readonly pages;
+    private readonly tokens;
+    constructor(render?: (report: ReviewReport) => string);
+    private listening;
+    private closed;
+    /** Serve one report page and return its URL. */
+    add(html: string): Promise<string>;
+    /** Serve a static review's page, keeping the report so answers can be recorded. */
+    publish(report: ReviewReport): Promise<PublishedReview>;
+    /**
+     * Accept the reviewing agent's whole reading of a review at once: an answer
+     * to every question, the reading order of every hunk, and the line comments
+     * it suggests (an empty list says it has none). Everything is checked before
+     * anything is kept, so one gap or bad entry refuses the call and changes
+     * nothing. Only a finished review's page addresses are handed out: an agent
+     * cannot give the human a page it has not finished reading.
+     */
+    finish(reviewId: string, input: FinishInput, by: string): FinishedReview;
+    /** Whether finish_review accepted this review, so its addresses may be handed out again. */
+    isFinished(reviewId: string): boolean;
+    /**
+     * Update the answers of a review. Every answer is checked before any is kept
+     * — a question this review asked, one of that question's options, each
+     * question at most once per call — so a call with one bad answer changes
+     * nothing. A later answer replaces an earlier one.
+     */
+    record(reviewId: string, answers: readonly AnswerInput[], answeredBy: string): RecordedAnswers;
+    /**
+     * Update the reading order the reviewing agent recommends: the report's items
+     * are reordered to it, so every page and the connected analysis list hunks in
+     * the agent's order. diffninja's own order is kept beside it; statuses and
+     * priorities never change. The order must name every hunk exactly once;
+     * anything else refuses the call and keeps the previous order.
+     */
+    recordOrder(reviewId: string, itemIds: readonly string[], orderedBy: string): RecordedOrder;
+    /**
+     * Update the line comments the reviewing agent suggests. The human sees them
+     * under their lines on the pull request page and adds each to their own
+     * review, or not; nothing here posts anything. Any bad comment refuses the
+     * call and keeps the previous set; an empty list clears it.
+     */
+    suggestComments(reviewId: string, comments: readonly SuggestedComment[], suggestedBy: string): RecordedComments;
+    private review;
+    private rerender;
+    private origin;
+    /** Stop serving every page. Repeated calls are harmless. */
+    close(): Promise<void>;
+    private listen;
+}

package/dist/review/report-pages.js

@@ -0,0 +1,328 @@
+/**
+ * Loopback pages for static review reports, owned by one MCP connection.
+ *
+ * A static review returns its report to the agent as data; this serves the same
+ * report as the self-contained HTML page for the human reviewer. The page is
+ * read-only: there is no API, nothing is written to disk, and the only route is
+ * `GET /report/<token>`, where the token is 256 random bits per report. Reports
+ * embed source code, so the listener binds 127.0.0.1 only, rejects any request
+ * whose Host is not this exact origin, and forbids caching, framing, and every
+ * resource the page does not carry inline. The inline script and stylesheet are
+ * allowed by their SHA-256 hashes, so the report HTML is served byte for byte.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { z } from "zod";
+/** Most reports one connection keeps; the oldest page closes first. */
+export const MAX_REPORT_PAGES = 20;
+/** Most comments one review may carry from the agent: a reviewer's handful, not a lint dump. */
+export const MAX_SUGGESTED_COMMENTS = 30;
+/** Longest suggested comment: a sentence or two, the way a reviewer writes one. */
+export const MAX_SUGGESTED_CHARS = 280;
+const CONTROL_CHARACTERS = /[^\P{Cc}]/u;
+/** Report scaffolding a person would not write in a review comment: "Finding 1:", "Attention -", "**Error**", "## Bug". */
+const REPORT_LABEL = /^\s*(?:#|>|[-*+]\s|\d+[.)]\s|\*\*|\[)|^\s*(?:findings?|issues?|attention|errors?|warnings?|bugs?|problems?|severity|critical|major|minor|high|medium|low|concerns?|risks?|suggestions?|observations?|summary)\b\s*#?\d*\s*[:\-\u2013\u2014.]|\*\*/i;
+const INLINE_BLOCK = /<(script|style)>([\s\S]*?)<\/\1>/g;
+/** CSP naming exactly the inline script and style blocks of one page. */
+export function reportPolicy(html) {
+    const hashes = { script: new Set(), style: new Set() };
+    for (const match of html.matchAll(INLINE_BLOCK)) {
+        const kind = match[1] === "script" ? "script" : "style";
+        hashes[kind].add(`'sha256-${createHash("sha256").update(match[2]).digest("base64")}'`);
+    }
+    const sources = (set) => (set.size === 0 ? "'none'" : [...set].join(" "));
+    return [
+        "default-src 'none'",
+        `script-src ${sources(hashes.script)}`,
+        `style-src ${sources(hashes.style)}`,
+        "img-src data:",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join("; ");
+}
+/** Every answer names a question this review asked, once, with one of its options. */
+function checkAnswers(report, answers) {
+    const questions = new Map(report.questions.map((question) => [question.id, question]));
+    const seen = new Set();
+    answers.forEach((answer, index) => {
+        const question = questions.get(answer.questionId);
+        if (question === undefined)
+            throw new Error(`answers[${index}] names a question this review did not ask.`);
+        if (seen.has(answer.questionId))
+            throw new Error(`answers[${index}] answers the same question twice in one call.`);
+        if (!question.options.includes(answer.choice)) {
+            throw new Error(`answers[${index}] is not one of that question's options: ${question.options.join(", ")}.`);
+        }
+        seen.add(answer.questionId);
+    });
+}
+function applyAnswers(report, answers, answeredBy) {
+    const questions = new Map(report.questions.map((question) => [question.id, question]));
+    const answeredAt = new Date().toISOString();
+    for (const answer of answers)
+        questions.get(answer.questionId).answer = { choice: answer.choice, answeredBy, answeredAt };
+}
+/** The order names every hunk of the review exactly once. */
+function checkOrder(report, itemIds) {
+    const known = new Set(report.items.map((item) => item.id));
+    const seen = new Set();
+    itemIds.forEach((id, index) => {
+        if (!known.has(id))
+            throw new Error(`order[${index}] names a hunk this review does not have.`);
+        if (seen.has(id))
+            throw new Error(`order[${index}] repeats a hunk; name each hunk once.`);
+        seen.add(id);
+    });
+    const missing = report.items.filter((item) => !seen.has(item.id)).map((item) => item.id);
+    if (missing.length > 0)
+        throw new Error(`order leaves out ${missing.length} of ${known.size} hunks, starting with ${missing[0]}; name every hunk once.`);
+}
+function applyOrder(report, itemIds, orderedBy) {
+    const diffninjaIds = report.agentOrder?.diffninjaIds ?? report.items.map((item) => item.id);
+    const position = new Map(itemIds.map((id, index) => [id, index]));
+    report.items.sort((a, b) => position.get(a.id) - position.get(b.id));
+    report.agentOrder = { itemIds: [...itemIds], orderedBy, orderedAt: new Date().toISOString(), diffninjaIds };
+}
+/** Every comment names a line of the diff, one per line, and reads like the reviewer's own. */
+function checkComments(report, comments) {
+    const anchors = new Set();
+    for (const item of report.items)
+        anchorsOf(item, anchors);
+    const seen = new Set();
+    comments.forEach((comment, index) => {
+        const key = anchorKey(comment.path, comment.side, comment.line);
+        if (!anchors.has(key))
+            throw new Error(`comments[${index}] names ${comment.path}:${comment.line} (${comment.side}), which is not a line of this review's diff.`);
+        if (seen.has(key))
+            throw new Error(`comments[${index}] is a second comment on the same line; combine them into one.`);
+        const problem = commentProblem(comment.body);
+        if (problem !== undefined)
+            throw new Error(`comments[${index}] ${problem}.`);
+        seen.add(key);
+    });
+}
+function applyComments(report, comments, suggestedBy) {
+    report.agentComments = {
+        comments: comments.map(({ path, line, side, body }) => ({ path, line, side, body: body.trim() })),
+        suggestedBy,
+        suggestedAt: new Date().toISOString(),
+    };
+}
+/** Map key of one commentable line. */
+function anchorKey(path, side, line) {
+    return JSON.stringify([path, side, line]);
+}
+/** Every line a comment may anchor to in one hunk: added lines on the new side, removed on the old, context on both. */
+function anchorsOf(item, into) {
+    let oldLine = item.oldStart;
+    let newLine = item.newStart;
+    for (const text of item.diff.split("\n").slice(1)) {
+        if (text.startsWith("+"))
+            into.add(anchorKey(item.file, "RIGHT", newLine++));
+        else if (text.startsWith("-"))
+            into.add(anchorKey(item.file, "LEFT", oldLine++));
+        else if (text.startsWith(" ")) {
+            into.add(anchorKey(item.file, "RIGHT", newLine++));
+            into.add(anchorKey(item.file, "LEFT", oldLine++));
+        }
+    }
+}
+/** Why a suggested comment cannot be offered as the reviewer's own words, or undefined when it can. */
+function commentProblem(body) {
+    if (body.trim() === "")
+        return "is empty";
+    if (/[\r\n]/.test(body))
+        return "must be one line of text";
+    if (CONTROL_CHARACTERS.test(body))
+        return "contains control characters";
+    if (body.length > MAX_SUGGESTED_CHARS)
+        return `is longer than ${MAX_SUGGESTED_CHARS} characters; say it the way a reviewer would, in a sentence or two`;
+    if (REPORT_LABEL.test(body))
+        return "reads like a report (a heading, list marker, bold, or a label such as \"Finding 1:\"); write it the way the reviewer would say it";
+    return undefined;
+}
+export class ReportPages {
+    render;
+    pages = new Map();
+    tokens = new Map();
+    constructor(render = () => "") {
+        this.render = render;
+    }
+    listening;
+    closed = false;
+    /** Serve one report page and return its URL. */
+    async add(html) {
+        if (this.closed)
+            throw new Error("This MCP connection is shutting down; the report page was not served.");
+        const { origin } = await (this.listening ??= this.listen());
+        const token = randomBytes(32).toString("hex");
+        this.pages.set(token, { html, policy: reportPolicy(html) });
+        for (const [oldest, page] of this.pages) {
+            if (this.pages.size <= MAX_REPORT_PAGES)
+                break;
+            this.pages.delete(oldest);
+            if (page.reviewId !== undefined)
+                this.tokens.delete(page.reviewId);
+        }
+        return `${origin}/report/${token}`;
+    }
+    /** Serve a static review's page, keeping the report so answers can be recorded. */
+    async publish(report) {
+        const url = await this.add(this.render(report));
+        const token = url.slice(url.lastIndexOf("/") + 1);
+        const reviewId = randomBytes(16).toString("hex");
+        const page = this.pages.get(token);
+        this.pages.set(token, { ...page, report, reviewId });
+        this.tokens.set(reviewId, token);
+        return { reviewId, url };
+    }
+    /**
+     * Accept the reviewing agent's whole reading of a review at once: an answer
+     * to every question, the reading order of every hunk, and the line comments
+     * it suggests (an empty list says it has none). Everything is checked before
+     * anything is kept, so one gap or bad entry refuses the call and changes
+     * nothing. Only a finished review's page addresses are handed out: an agent
+     * cannot give the human a page it has not finished reading.
+     */
+    finish(reviewId, input, by) {
+        const { token, page, report } = this.review(reviewId);
+        checkAnswers(report, input.answers);
+        const answeredIds = new Set(input.answers.map((answer) => answer.questionId));
+        const unanswered = report.questions.filter((question) => !answeredIds.has(question.id));
+        if (unanswered.length > 0) {
+            throw new Error(`answers leave out ${unanswered.length} of ${report.questions.length} questions, starting with ${unanswered[0].id}; answer every question, cannot-tell when the code does not settle it.`);
+        }
+        checkOrder(report, input.order);
+        checkComments(report, input.comments);
+        applyAnswers(report, input.answers, by);
+        applyOrder(report, input.order, by);
+        applyComments(report, input.comments, by);
+        page.finished = true;
+        this.rerender(page, report);
+        return {
+            reviewId,
+            answered: input.answers.length,
+            ordered: input.order.length,
+            suggested: input.comments.length,
+            reportUrl: `${this.origin}/report/${token}`,
+        };
+    }
+    /** Whether finish_review accepted this review, so its addresses may be handed out again. */
+    isFinished(reviewId) {
+        return this.review(reviewId).page.finished === true;
+    }
+    /**
+     * Update the answers of a review. Every answer is checked before any is kept
+     * — a question this review asked, one of that question's options, each
+     * question at most once per call — so a call with one bad answer changes
+     * nothing. A later answer replaces an earlier one.
+     */
+    record(reviewId, answers, answeredBy) {
+        const { page, report } = this.review(reviewId);
+        checkAnswers(report, answers);
+        applyAnswers(report, answers, answeredBy);
+        this.rerender(page, report);
+        const answered = report.questions.filter((question) => question.answer !== undefined).length;
+        return { reviewId, recorded: answers.length, answered, unanswered: report.questions.length - answered };
+    }
+    /**
+     * Update the reading order the reviewing agent recommends: the report's items
+     * are reordered to it, so every page and the connected analysis list hunks in
+     * the agent's order. diffninja's own order is kept beside it; statuses and
+     * priorities never change. The order must name every hunk exactly once;
+     * anything else refuses the call and keeps the previous order.
+     */
+    recordOrder(reviewId, itemIds, orderedBy) {
+        const { page, report } = this.review(reviewId);
+        checkOrder(report, itemIds);
+        applyOrder(report, itemIds, orderedBy);
+        this.rerender(page, report);
+        return { reviewId, ordered: itemIds.length };
+    }
+    /**
+     * Update the line comments the reviewing agent suggests. The human sees them
+     * under their lines on the pull request page and adds each to their own
+     * review, or not; nothing here posts anything. Any bad comment refuses the
+     * call and keeps the previous set; an empty list clears it.
+     */
+    suggestComments(reviewId, comments, suggestedBy) {
+        const { page, report } = this.review(reviewId);
+        checkComments(report, comments);
+        applyComments(report, comments, suggestedBy);
+        this.rerender(page, report);
+        return { reviewId, suggested: comments.length };
+    }
+    review(reviewId) {
+        const token = this.tokens.get(reviewId);
+        const page = token === undefined ? undefined : this.pages.get(token);
+        if (token === undefined || page?.report === undefined) {
+            throw new Error("No review with that reviewId on this MCP connection. Reviews last as long as the connection, at most the latest 20.");
+        }
+        return { token, page, report: page.report };
+    }
+    rerender(page, report) {
+        page.html = this.render(report);
+        page.policy = reportPolicy(page.html);
+    }
+    origin = "";
+    /** Stop serving every page. Repeated calls are harmless. */
+    async close() {
+        this.closed = true;
+        this.pages.clear();
+        this.tokens.clear();
+        const listening = this.listening;
+        if (listening === undefined)
+            return;
+        const { server } = await listening.catch(() => ({ server: undefined }));
+        if (server === undefined)
+            return;
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        });
+    }
+    async listen() {
+        let origin = "";
+        const server = createServer((req, res) => {
+            res.setHeader("Cache-Control", "no-store");
+            res.setHeader("X-Content-Type-Options", "nosniff");
+            res.setHeader("X-Frame-Options", "DENY");
+            res.setHeader("Referrer-Policy", "no-referrer");
+            const refuse = (code, message) => {
+                res.setHeader("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'");
+                res.writeHead(code, { "Content-Type": "text/plain; charset=utf-8" });
+                res.end(message);
+            };
+            if (req.headers.host !== new URL(origin).host)
+                return refuse(403, "Untrusted Host.");
+            if (req.method !== "GET")
+                return refuse(405, "Read-only report.");
+            const token = /^\/report\/([a-f0-9]{64})$/.exec(req.url ?? "")?.[1];
+            const page = token === undefined ? undefined : this.pages.get(token);
+            if (page === undefined)
+                return refuse(404, "No such report on this connection.");
+            res.setHeader("Content-Security-Policy", page.policy);
+            res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(page.html);
+        });
+        server.requestTimeout = 15_000;
+        server.headersTimeout = 10_000;
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", () => {
+                server.removeListener("error", reject);
+                resolve();
+            });
+        });
+        const address = z.object({ port: z.number().int().positive() }).parse(server.address());
+        origin = `http://127.0.0.1:${address.port}`;
+        this.origin = origin;
+        // A close that raced this listen still owns the teardown.
+        if (this.closed) {
+            await new Promise((resolve) => server.close(() => resolve()));
+            throw new Error("This MCP connection is shutting down; the report page was not served.");
+        }
+        return { server, origin };
+    }
+}

package/dist/review/service.d.ts

@@ -0,0 +1,23 @@
+import type { ReviewOptions, ReviewReport, ReviewUnit } from "./types.js";
+export type ReviewInput = {
+    diff: string;
+    source: string;
+} | {
+    repo: string;
+    from: string;
+    to: string;
+    diff?: string;
+    source?: string;
+};
+/** Most whole context nodes one hunk carries in the report. */
+export declare const REPORT_CONTEXT_NODES = 8;
+/** Most call-flow block characters one hunk carries in the report. */
+export declare const REPORT_CALL_FLOW_CHARS = 24000;
+/** Most characters of whole-diff call-flow trees the report carries. */
+export declare const REPORT_CALL_FLOW_TREE_CHARS = 64000;
+/** Keep the highest-priority context of one hunk, whole, and say what was left out. */
+export declare function boundReportContext(unit: ReviewUnit): void;
+/** The whole-diff call-flow trees in engine order, whole, within the report bound. */
+export declare function boundCallFlowTrees(trees: readonly string[]): string[];
+/** Shared report orchestration; transports own input reading and output persistence. */
+export declare function reviewDiff(input: ReviewInput, options?: ReviewOptions): Promise<ReviewReport>;

package/dist/review/service.js

@@ -0,0 +1,198 @@
+import { resolve } from "node:path";
+import { runDiff } from "../run.js";
+import { readSnapshotFile } from "../git.js";
+import { parseDiff, gitDiff } from "./input.js";
+import { reviewUnits } from "./pipeline.js";
+import { buildCallFlows, reportOrderedTextHunkFiles, CALL_FLOW_MAX_DEPTH } from "./call-flow.js";
+import { buildCallContext } from "./call-context.js";
+import { definitionReader } from "./source.js";
+import { buildReviewEvidence } from "./evidence.js";
+import { crossCheckIntent } from "./intent.js";
+import { checkReferences } from "./reference-check.js";
+import { moduleResolver } from "./module-resolution.js";
+import { reviewQuestions } from "./questions.js";
+import { readProjectContext } from "./history.js";
+/** Context width may differ, but source-enriched patches must describe the same changed lines. */
+function changedLineIdentity(units) {
+    const changes = [];
+    for (const unit of units) {
+        if (unit.special)
+            continue;
+        let oldLine = unit.oldStart, newLine = unit.newStart;
+        for (const line of unit.diff.split("\n").slice(1)) {
+            if (line.startsWith("+"))
+                changes.push(JSON.stringify([unit.file, "+", newLine++, line.slice(1)]));
+            else if (line.startsWith("-"))
+                changes.push(JSON.stringify([unit.file, "-", oldLine++, line.slice(1)]));
+            else if (line.startsWith(" ")) {
+                oldLine++;
+                newLine++;
+            }
+        }
+    }
+    return changes.sort().join("\n");
+}
+/** Most whole context nodes one hunk carries in the report. */
+export const REPORT_CONTEXT_NODES = 8;
+/** Most call-flow block characters one hunk carries in the report. */
+export const REPORT_CALL_FLOW_CHARS = 24_000;
+/** Most characters of whole-diff call-flow trees the report carries. */
+export const REPORT_CALL_FLOW_TREE_CHARS = 64_000;
+/** Leading blocks, whole, within `limit` characters; always at least the first. */
+function keepWithin(blocks, limit) {
+    const kept = [];
+    let used = 0;
+    for (const block of blocks) {
+        if (used + block.length > limit && kept.length > 0)
+            break;
+        kept.push(block);
+        used += block.length;
+    }
+    return { kept, omitted: blocks.length - kept.length };
+}
+/** Keep the highest-priority context of one hunk, whole, and say what was left out. */
+export function boundReportContext(unit) {
+    if (unit.contextNodes !== undefined && unit.contextNodes.length > REPORT_CONTEXT_NODES) {
+        unit.contextNodes = unit.contextNodes.slice(0, REPORT_CONTEXT_NODES);
+    }
+    if (unit.callFlow === undefined)
+        return;
+    const { kept, omitted } = keepWithin(unit.callFlow, REPORT_CALL_FLOW_CHARS);
+    if (omitted > 0)
+        kept.push(`omitted call-flow blocks=${omitted} reason=report-size-limit chars=${REPORT_CALL_FLOW_CHARS}`);
+    unit.callFlow = kept;
+}
+/** The whole-diff call-flow trees in engine order, whole, within the report bound. */
+export function boundCallFlowTrees(trees) {
+    const { kept, omitted } = keepWithin(trees, REPORT_CALL_FLOW_TREE_CHARS);
+    // A single tree over the bound keeps its leading lines: the root and nearest calls.
+    const first = kept[0];
+    if (first !== undefined && first.length > REPORT_CALL_FLOW_TREE_CHARS) {
+        const lines = first.split("\n");
+        const head = keepWithin(lines.map((line) => `${line}\n`), REPORT_CALL_FLOW_TREE_CHARS);
+        kept[0] = `${head.kept.join("")}omitted tree lines=${head.omitted} reason=report-size-limit chars=${REPORT_CALL_FLOW_TREE_CHARS}`;
+    }
+    if (omitted > 0)
+        kept.push(`omitted call-flow trees=${omitted} reason=report-size-limit chars=${REPORT_CALL_FLOW_TREE_CHARS}`);
+    return kept;
+}
+/** Shared report orchestration; transports own input reading and output persistence. */
+export async function reviewDiff(input, options = {}) {
+    const warnings = [];
+    const cwd = "repo" in input ? resolve(input.repo) : undefined;
+    const snapshots = "repo" in input ? gitDiff(cwd, input.from, input.to) : undefined;
+    const text = input.diff ?? snapshots.diff;
+    const source = input.source ?? ("repo" in input
+        ? `${input.from} → ${input.to} (${snapshots.from.slice(0, 8)} → ${snapshots.to.slice(0, 8)})`
+        : "Patch");
+    if (!snapshots)
+        warnings.push("Patch-only review. Full files and repository call flows are unavailable.");
+    const units = parseDiff(text);
+    if (snapshots && input.diff !== undefined && changedLineIdentity(units) !== changedLineIdentity(parseDiff(snapshots.diff))) {
+        throw new Error("The supplied patch does not match the immutable repository range; refusing mismatched source evidence.");
+    }
+    if (snapshots && options.pr?.headRef !== undefined && options.pr.headRef !== snapshots.to) {
+        throw new Error("The PR head does not match the source snapshot; refusing mismatched intent evidence.");
+    }
+    let evidence = buildReviewEvidence(units);
+    const callFlow = [];
+    let trees = [];
+    // Definition source comes from the snapshot the definition resolved in: the
+    // `to` revision, except for a removed call, whose only definition is the
+    // `from` one. Definitions outside the diff, callers and callees alike, are
+    // read the same way. Unreadable definitions stay absent rather than guessed.
+    // One reader serves the structured call flows and the keyed node context, so
+    // each snapshot file is read once per revision.
+    let nodeDetail;
+    let contextSources = {};
+    if (snapshots) {
+        const readDefinition = definitionReader(cwd);
+        const from = { kind: "commit", ref: snapshots.from };
+        const to = { kind: "commit", ref: snapshots.to };
+        nodeDetail = (node) => {
+            const definition = node.definition;
+            if (!definition)
+                return {};
+            return readDefinition(definition, node.status === "removed" ? from : to);
+        };
+        // A node carries its definition whole or not at all, so an unreadable
+        // span yields no source rather than a shorter one.
+        contextSources = {
+            before: definition => readDefinition(definition, from).source?.text ?? null,
+            after: definition => readDefinition(definition, to).source?.text ?? null,
+        };
+    }
+    // A patch carries no repository, so the only honest answer is that call flows
+    // need a git range. Every other value is decided by what analysis returned.
+    let callFlowAvailability = snapshots ? "no-changes" : "needs-git-range";
+    if (snapshots && units.length) {
+        try {
+            const flow = runDiff({
+                cwd: cwd, from: snapshots.from, to: snapshots.to, maxDepth: CALL_FLOW_MAX_DEPTH, color: false, locs: true,
+                onIndexes(before, after) {
+                    const context = buildCallContext(units, before, after, contextSources);
+                    for (const unit of units) {
+                        const entry = context.get(unit.id);
+                        // Absent, not empty: a hunk with no context carries neither field,
+                        // exactly as the report treated a hunk with no blocks before.
+                        unit.callFlow = entry === undefined || entry.entries.length === 0 ? undefined : entry.entries;
+                        unit.contextNodes = entry === undefined || entry.nodes.length === 0 ? undefined : entry.nodes;
+                    }
+                    evidence = buildReviewEvidence(units, {
+                        before, after, sources: contextSources, baseRef: snapshots.from, headRef: snapshots.to,
+                        resolveImport: moduleResolver(file => readSnapshotFile(cwd, { kind: "commit", ref: snapshots.to }, file)),
+                    });
+                },
+            });
+            trees = flow.trees;
+            // One tree can reach thousands of callers (a neovim hunk made 5.7 MB); the
+            // agent gets the leading trees whole, the structured flows stay bounded.
+            callFlow.push(...boundCallFlowTrees(trees.map(tree => tree.ascii)));
+            warnings.push("Call flows are syntactic, not a type checker. Dynamic calls and parse failures may be absent. An empty flow is not evidence of safety.");
+        }
+        catch {
+            for (const unit of units) {
+                delete unit.callFlow;
+                delete unit.contextNodes;
+            }
+            callFlowAvailability = "failed";
+            evidence = buildReviewEvidence(units);
+            warnings.push("Call-flow analysis failed. Review is based on the diff only. Inspect repository context manually.");
+        }
+    }
+    if (options.referenceProject !== undefined) {
+        if (!snapshots)
+            throw new Error("Reference checking requires a repository and immutable git range.");
+        const references = await checkReferences(cwd, snapshots.from, snapshots.to, units, options.referenceProject);
+        evidence.findings.push(...references.findings);
+        evidence.agenda.unshift(...references.findings.map(finding => ({
+            id: `agenda-${finding.id}`, title: "Check the newly unresolved reference",
+            reason: finding.title, priority: 100, unitIds: finding.unitIds,
+            findingIds: [finding.id], evidence: finding.evidence, context: [],
+        })));
+        evidence.checks = evidence.checks.map(check => check.kind === "broken-reference" ? references.check : check);
+    }
+    // Analysis above used every context node; the report carries a bounded share of
+    // it per hunk, so a change to a widely used type cannot produce a report of tens
+    // of megabytes (one real hunk had thousands of callers).
+    for (const unit of units)
+        boundReportContext(unit);
+    // History, guidelines, and conventions come from the local repository only.
+    const project = snapshots
+        ? readProjectContext(cwd, snapshots.from, snapshots.to, units, options.pr?.title ?? "")
+        : undefined;
+    const result = reviewUnits(units);
+    // Structured flows are grouped per changed file in report order, after
+    // ranking, so the HTML can order files by the severity of their worst hunk.
+    const callFlows = buildCallFlows(reportOrderedTextHunkFiles(result.items, units), trees, nodeDetail);
+    if (callFlows.length > 0)
+        callFlowAvailability = "available";
+    const report = { title: options.pr?.title || "Focused PR review", source, createdAt: new Date().toISOString(),
+        pr: options.pr,
+        evidence: { ...evidence, intent: crossCheckIntent(options.pr, units, evidence.agenda, evidence.findings) },
+        ...result, callFlow, callFlows, callFlowAvailability, warnings: [...warnings, ...result.warnings],
+        questions: reviewQuestions(result.items, options.pr, project) };
+    if (project !== undefined)
+        report.project = project;
+    return report;
+}