diffninja 0.1.0

package/dist/review/pipeline.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Hunk routing and ranking for a diffninja review run.
+ *
+ * Everything here is local and deterministic: no model is called, nothing leaves
+ * the machine, and the same input always produces the same report. Every input
+ * unit comes back as exactly one ReviewItem:
+ *
+ *   - a unit the input parser marked special (binary, rename, mode, symbolic
+ *     link, submodule) and a unit with no diff text go to manual review;
+ *   - an exact no-op hunk and a blank-only change to a .md/.txt document pass;
+ *   - every other hunk gets its local change facts ({@link changeFactsOf}): a
+ *     formatting- or comment-only change passes, a file type diffninja cannot
+ *     read is `uncertain` for a human to read, a code or configuration change
+ *     outside a test file is `attention`, documentation is `attention` when it
+ *     changes an instruction, a link, or a limit and `low` otherwise, and a
+ *     test-file change is `attention` only when it changes a limit, discards a
+ *     failure, or weakens a gate, `low` otherwise.
+ *
+ * Priority orders hunks within the report: a fixed base, a weight for a change
+ * that is not inert, and the heaviest fact of the boundary group (what the
+ * change says or bounds), of the failure group (failures, gates,
+ * permissions), and of the surface group (public declarations, schema, stored
+ * data). Each group contributes its maximum, never a sum.
+ *
+ * The report order puts manual work first, then the read hunks by priority —
+ * those outside test files before those in test files — and the passes last;
+ * input order breaks ties. Status is a label to filter on and never reorders it.
+ */
+import type { ReviewItem, ReviewUnit } from "./types.js";
+/** Priority every read hunk starts from. */
+export declare const BASE_PRIORITY = 5;
+/** Weight of a change that is not inert: the code, or the text, really differs. */
+export declare const CHANGED_PRIORITY = 10;
+/** Weight of each fact when it is `yes`; `no` adds nothing. */
+export declare const FACT_PRIORITY: {
+    comparisonChanged: number;
+    limitChanged: number;
+    validationChanged: number;
+    failurePropagated: number;
+    failureDeferred: number;
+    failureDiscarded: number;
+    contractChanged: number;
+    dataChanged: number;
+    queryChanged: number;
+    instructionChanged: number;
+    referenceChanged: number;
+    gateWeakened: number;
+    permissionChanged: number;
+    pinChanged: number;
+};
+/** Fixed priorities for hunks the facts do not rank. */
+export declare const MANUAL_REVIEW_PRIORITY = 70;
+export declare const TRIVIAL_PRIORITY = 5;
+/**
+ * Report position of one item: manual work, then read hunks outside test files,
+ * then hunks in test files (read or not), then passes; within a position, higher
+ * priority first and, among equal priorities, more changed lines first. Test files come after the code they
+ * exercise because a regression test changes as much as its fix does; which file
+ * is a test is a path fact. Documentation is not demoted: prose can be normative.
+ */
+export declare const REPORT_PLACEMENT: {
+    manual: number;
+    read: number;
+    readTest: number;
+    passed: number;
+};
+/** Reason attached to a read hunk the report lists after the non-test hunks. */
+export declare const TEST_FILE_ORDER_REASON: string;
+export interface ReviewPipelineResult {
+    readonly items: ReviewItem[];
+    /** Run-level notices for the report; per-hunk detail stays in `reasons`. */
+    readonly warnings: string[];
+}
+/** Where an item belongs in the report; see {@link REPORT_PLACEMENT}. */
+export declare function placementOf(item: ReviewItem): number;
+/** Route, read, and order every unit. Deterministic: no network, no model, no randomness. */
+export declare function reviewUnits(units: readonly ReviewUnit[]): ReviewPipelineResult;

package/dist/review/pipeline.js

@@ -0,0 +1,227 @@
+/**
+ * Hunk routing and ranking for a diffninja review run.
+ *
+ * Everything here is local and deterministic: no model is called, nothing leaves
+ * the machine, and the same input always produces the same report. Every input
+ * unit comes back as exactly one ReviewItem:
+ *
+ *   - a unit the input parser marked special (binary, rename, mode, symbolic
+ *     link, submodule) and a unit with no diff text go to manual review;
+ *   - an exact no-op hunk and a blank-only change to a .md/.txt document pass;
+ *   - every other hunk gets its local change facts ({@link changeFactsOf}): a
+ *     formatting- or comment-only change passes, a file type diffninja cannot
+ *     read is `uncertain` for a human to read, a code or configuration change
+ *     outside a test file is `attention`, documentation is `attention` when it
+ *     changes an instruction, a link, or a limit and `low` otherwise, and a
+ *     test-file change is `attention` only when it changes a limit, discards a
+ *     failure, or weakens a gate, `low` otherwise.
+ *
+ * Priority orders hunks within the report: a fixed base, a weight for a change
+ * that is not inert, and the heaviest fact of the boundary group (what the
+ * change says or bounds), of the failure group (failures, gates,
+ * permissions), and of the surface group (public declarations, schema, stored
+ * data). Each group contributes its maximum, never a sum.
+ *
+ * The report order puts manual work first, then the read hunks by priority —
+ * those outside test files before those in test files — and the passes last;
+ * input order breaks ties. Status is a label to filter on and never reorders it.
+ */
+import { CHANGE_FACT_QUESTIONS, changeFactsOf, factQuestionsFor, } from "./change-facts.js";
+import { testLikeFile } from "./file-role.js";
+/** Priority every read hunk starts from. */
+export const BASE_PRIORITY = 5;
+/** Weight of a change that is not inert: the code, or the text, really differs. */
+export const CHANGED_PRIORITY = 10;
+/** Weight of each fact when it is `yes`; `no` adds nothing. */
+export const FACT_PRIORITY = {
+    comparisonChanged: 6,
+    limitChanged: 15,
+    validationChanged: 6,
+    failurePropagated: 3,
+    failureDeferred: 6,
+    failureDiscarded: 15,
+    contractChanged: 10,
+    dataChanged: 15,
+    queryChanged: 10,
+    instructionChanged: 10,
+    referenceChanged: 6,
+    gateWeakened: 15,
+    permissionChanged: 15,
+    pinChanged: 6,
+};
+/** What the change says or bounds: conditions, limits, checks, instructions, links, pins. */
+const BOUNDARY_FACTS = [
+    "comparisonChanged", "limitChanged", "validationChanged", "instructionChanged", "referenceChanged", "pinChanged",
+];
+/** What happens when things fail, or who may do what: failures, CI gates, permissions. */
+const FAILURE_FACTS = [
+    "failurePropagated", "failureDeferred", "failureDiscarded", "gateWeakened", "permissionChanged",
+];
+/** What others build on or what is stored: public declarations, schema, and data. */
+const SURFACE_FACTS = ["contractChanged", "dataChanged", "queryChanged"];
+/** Facts strong enough to raise a test-file hunk to attention on their own. */
+const TEST_FILE_ATTENTION_FACTS = ["limitChanged", "failureDiscarded", "gateWeakened"];
+/** Fixed priorities for hunks the facts do not rank. */
+export const MANUAL_REVIEW_PRIORITY = 70;
+export const TRIVIAL_PRIORITY = 5;
+/**
+ * Report position of one item: manual work, then read hunks outside test files,
+ * then hunks in test files (read or not), then passes; within a position, higher
+ * priority first and, among equal priorities, more changed lines first. Test files come after the code they
+ * exercise because a regression test changes as much as its fix does; which file
+ * is a test is a path fact. Documentation is not demoted: prose can be normative.
+ */
+export const REPORT_PLACEMENT = {
+    manual: 0,
+    read: 1,
+    readTest: 2,
+    passed: 3,
+};
+/** Reason attached to a read hunk the report lists after the non-test hunks. */
+export const TEST_FILE_ORDER_REASON = "read after the hunks outside test files: the path looks like a test file (a path convention, " +
+    "not coverage), and its priority orders it among the other test hunks";
+const FACT_LABEL = {
+    comparisonChanged: "comparison changed",
+    limitChanged: "limit changed",
+    validationChanged: "input check changed",
+    failurePropagated: "failure handed to the caller",
+    failureDeferred: "failure deferred or retried",
+    failureDiscarded: "failure discarded",
+    contractChanged: "public contract or declaration changed",
+    dataChanged: "schema or stored data changed",
+    queryChanged: "database query changed",
+    instructionChanged: "instruction to readers changed",
+    referenceChanged: "link or reference changed",
+    gateWeakened: "CI gate weakened",
+    permissionChanged: "permission or secret access changed",
+    pinChanged: "version pin changed",
+};
+const STATUS_REASON = {
+    attention: "attention: code or configuration outside a test file changed, documentation changed an instruction, link, or limit, or a test changed a limit, discarded a failure, or weakened a gate",
+    uncertain: "uncertain: diffninja does not read this file type, so no facts were established and a person reads it",
+    low: "low: a test-file change, an import-only change (read where the names are used), or a documentation change with no instruction, link, or limit change",
+    passed: "passed: the text is identical once comments and layout are ignored",
+};
+function clampPriority(priority) {
+    return Math.max(0, Math.min(100, Math.round(priority)));
+}
+/** Added and removed lines, and how many of them are not blank. */
+function countChangedLines(diff) {
+    let added = 0;
+    let removed = 0;
+    let nonBlank = 0;
+    for (const line of diff.split("\n")) {
+        if (line.startsWith("+")) {
+            added += 1;
+            if (line.slice(1).trim() !== "")
+                nonBlank += 1;
+        }
+        else if (line.startsWith("-")) {
+            removed += 1;
+            if (line.slice(1).trim() !== "")
+                nonBlank += 1;
+        }
+    }
+    return { added, removed, nonBlank };
+}
+/**
+ * Pass rules that need no facts: a hunk with no added or removed lines, and a
+ * blank-only change to a text document (.md/.txt).
+ */
+function deterministicPassReason(unit) {
+    const changed = countChangedLines(unit.diff);
+    if (changed.added === 0 && changed.removed === 0) {
+        return "exact no-op: the hunk adds and removes no lines";
+    }
+    if (changed.nonBlank > 0)
+        return null;
+    const path = unit.file.toLowerCase();
+    if (path.endsWith(".md") || path.endsWith(".txt")) {
+        return `blank-only change to a text document (${changed.added} added, ${changed.removed} removed blank line(s))`;
+    }
+    return null;
+}
+function manualReason(unit) {
+    if (unit.special !== undefined && unit.special !== "") {
+        return `special unit (${unit.special}): the diff carries no reviewable text, so a person reviews it`;
+    }
+    if (unit.diff.trim() === "")
+        return "no diff text was supplied for this hunk; a person reviews it";
+    return null;
+}
+function statusOf(unit, facts) {
+    if (facts.language === null)
+        return "uncertain";
+    if (facts.inert)
+        return "passed";
+    const yes = (question) => facts.answers[question] === "yes";
+    if (testLikeFile(unit.file))
+        return TEST_FILE_ATTENTION_FACTS.some(yes) ? "attention" : "low";
+    // Prose matters when it tells a reader something new to do, follow, or rely on.
+    if (facts.language === "prose")
+        return factQuestionsFor("prose").some(yes) ? "attention" : "low";
+    // Import wiring is read where the imported names are used.
+    if (facts.importsOnly === true)
+        return "low";
+    return "attention";
+}
+function priorityOf(facts) {
+    if (facts.inert || facts.importsOnly === true)
+        return TRIVIAL_PRIORITY;
+    const heaviest = (group) => Math.max(0, ...group.filter((question) => facts.answers[question] === "yes").map((question) => FACT_PRIORITY[question]));
+    return clampPriority(BASE_PRIORITY + CHANGED_PRIORITY + heaviest(BOUNDARY_FACTS) + heaviest(FAILURE_FACTS) + heaviest(SURFACE_FACTS));
+}
+/** One sentence per established fact, citing the changed line it rests on. */
+function reasonsOf(unit, facts, status) {
+    const reasons = [];
+    for (const question of CHANGE_FACT_QUESTIONS) {
+        const evidence = facts.evidence[question];
+        if (facts.answers[question] === "yes" && evidence !== undefined) {
+            reasons.push(`${FACT_LABEL[question]} — ${evidence.side} line: ${evidence.text}`);
+        }
+    }
+    reasons.push(STATUS_REASON[status]);
+    if (status !== "passed" && facts.language !== null && testLikeFile(unit.file))
+        reasons.push(TEST_FILE_ORDER_REASON);
+    return reasons;
+}
+function readItem(unit) {
+    const facts = changeFactsOf(unit);
+    const status = statusOf(unit, facts);
+    return { ...unit, status, priority: priorityOf(facts), reasons: reasonsOf(unit, facts, status), facts };
+}
+/** Where an item belongs in the report; see {@link REPORT_PLACEMENT}. */
+export function placementOf(item) {
+    if (item.status === "passed")
+        return REPORT_PLACEMENT.passed;
+    if (item.facts === undefined)
+        return REPORT_PLACEMENT.manual;
+    // A test file diffninja cannot read (a snapshot, expected compiler output) is
+    // still a test file: it belongs with the tests, not ahead of the code.
+    return testLikeFile(item.file) ? REPORT_PLACEMENT.readTest : REPORT_PLACEMENT.read;
+}
+function changedLines(item) {
+    return item.added + item.removed;
+}
+/** Route, read, and order every unit. Deterministic: no network, no model, no randomness. */
+export function reviewUnits(units) {
+    const items = units.map((unit, index) => {
+        const manual = manualReason(unit);
+        if (manual !== null) {
+            return { index, item: { ...unit, status: "uncertain", priority: MANUAL_REVIEW_PRIORITY, reasons: [manual] } };
+        }
+        const pass = deterministicPassReason(unit);
+        if (pass !== null) {
+            return { index, item: { ...unit, status: "passed", priority: TRIVIAL_PRIORITY, reasons: [pass] } };
+        }
+        return { index, item: readItem(unit) };
+    });
+    items.sort((left, right) => placementOf(left.item) - placementOf(right.item) ||
+        right.item.priority - left.item.priority ||
+        // Equal priority: the larger change first. On maintainer-reviewed pull
+        // requests the hunk they commented on was, among equals, usually the one
+        // that changed the most lines, not the first one in path order.
+        changedLines(right.item) - changedLines(left.item) ||
+        left.index - right.index);
+    return { items: items.map((entry) => entry.item), warnings: [] };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Pull request detection shared by the CLI and the MCP server.
+ *
+ * Inputs are arbitrary text: a bare URL, a sentence with a link in it, or the
+ * value half of `--flag=value`. Detection is content based, so no caller has to
+ * know which argument carried the link. Only github.com pull requests count,
+ * and free text that never claims one is ignored rather than rejected. Text
+ * that does claim a github.com pull request and cannot be read is refused
+ * loudly: a mistyped target must never silently become a review of something
+ * else. The canonical URL returned always passes the strict parser the
+ * connected session itself uses.
+ */
+/**
+ * The one pull request named by any of the given strings, as
+ * `https://github.com/owner/repo/pull/123`. Empty strings are ignored. An
+ * unreadable github.com pull request URL, or two different pull requests, is an
+ * error: neither may be resolved by guessing which one was meant.
+ */
+export declare function detectPullRequest(inputs: readonly string[]): string | undefined;

package/dist/review/pr-input.js

@@ -0,0 +1,130 @@
+/**
+ * Pull request detection shared by the CLI and the MCP server.
+ *
+ * Inputs are arbitrary text: a bare URL, a sentence with a link in it, or the
+ * value half of `--flag=value`. Detection is content based, so no caller has to
+ * know which argument carried the link. Only github.com pull requests count,
+ * and free text that never claims one is ignored rather than rejected. Text
+ * that does claim a github.com pull request and cannot be read is refused
+ * loudly: a mistyped target must never silently become a review of something
+ * else. The canonical URL returned always passes the strict parser the
+ * connected session itself uses.
+ */
+const GITHUB_HOST = "github.com";
+const GITHUB_WWW_HOST = `www.${GITHUB_HOST}`;
+const PR_MARKER = "/pull/";
+const SCHEME = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//;
+/** Owner and repository segments GitHub accepts; also excludes `.` and `..`. */
+const NAME = /^[A-Za-z0-9._-]+$/;
+/** `/owner/repo/pull/123`, then an optional path, query, or fragment. */
+const PR_PATH = /^\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:\.(?:diff|patch))?(?=\/|$)/;
+/**
+ * Characters that end the argument-shaped token around a URL: whitespace,
+ * quotes — including the typographic ones a paste carries — brackets, markdown
+ * and shell punctuation, and the zero-width formatting characters that ride
+ * along with copied links. `#` ends a token too: it can only follow a URL,
+ * never sit inside the part that names a pull request. `&` ends one because a
+ * glued `&x=1` or `&` is not part of the address a reviewer copied.
+ */
+const TOKEN_BREAK = /[\s"'`“”‘’«»<>,;|\\=*()[\]{}【】&…–—#\u200b-\u200f\u2060\ufeff]/u;
+/** Trailing sentence punctuation, which is never part of the URL. */
+const TRAILING = /[\s.,;:!?]+$/u;
+const UNSUPPORTED_PROBLEM = "Only https://github.com pull request URLs are supported.";
+const CREDENTIALS_PROBLEM = "Remove the username or token from the pull request URL.";
+const FORM_PROBLEM = "Enter a pull request URL of the form https://github.com/owner/repo/pull/123.";
+const RANGE_PROBLEM = "That pull request number is out of range.";
+/** Where the last `scheme://` in `head` starts; 0 when it holds no scheme. */
+function schemeStart(head) {
+    const scheme = /[A-Za-z][A-Za-z0-9+.-]*:\/\//gu;
+    let start = 0;
+    for (let match = scheme.exec(head); match !== null; match = scheme.exec(head))
+        start = match.index;
+    return start;
+}
+/** Every `/pull/`-shaped token in one string; a bare host or repo is not one. */
+function pullTokens(text) {
+    const tokens = [];
+    for (let index = text.indexOf(PR_MARKER); index !== -1; index = text.indexOf(PR_MARKER, index + PR_MARKER.length)) {
+        let start = index;
+        while (start > 0 && !TOKEN_BREAK.test(text[start - 1]))
+            start--;
+        let end = index + PR_MARKER.length;
+        while (end < text.length && !TOKEN_BREAK.test(text[end]))
+            end++;
+        // Text glued to a link keeps its own words in the token (`PR:https://…`,
+        // a page whose path holds the link); the link itself starts at the last
+        // scheme before the marker, so glue can never hide a real link.
+        start += schemeStart(text.slice(start, index + PR_MARKER.length));
+        const token = text.slice(start, end).replace(TRAILING, "");
+        if (token !== "")
+            tokens.push(token);
+    }
+    return tokens;
+}
+/**
+ * The canonical pull request URL one token names, or null when the token is not
+ * about github.com at all. A token that is about github.com and is unreadable
+ * throws instead, so a mistyped URL is never silently ignored.
+ */
+function canonicalPullUrl(token) {
+    let rest = token;
+    const scheme = SCHEME.exec(rest);
+    if (scheme !== null) {
+        if (!/^https?$/iu.test(scheme[1])) {
+            if (rest.toLowerCase().includes(GITHUB_HOST))
+                throw new Error(UNSUPPORTED_PROBLEM);
+            return null;
+        }
+        rest = rest.slice(scheme[0].length);
+    }
+    else if (rest.startsWith("//")) {
+        rest = rest.slice(2);
+    }
+    const boundary = rest.search(/[/?#]/u);
+    const authority = (boundary === -1 ? rest : rest.slice(0, boundary)).toLowerCase();
+    const path = boundary === -1 ? "" : rest.slice(boundary);
+    const host = authority.slice(authority.lastIndexOf("@") + 1);
+    // Another host entirely: free text, not a claim about a pull request. A host
+    // that merely contains github.com (github.com.evil.com, notgithub.com, a
+    // port) is a claim that cannot be honored, so it is refused.
+    if (!host.includes(GITHUB_HOST))
+        return null;
+    if (host !== GITHUB_HOST && host !== GITHUB_WWW_HOST)
+        throw new Error(UNSUPPORTED_PROBLEM);
+    if (authority !== host)
+        throw new Error(CREDENTIALS_PROBLEM);
+    const match = PR_PATH.exec(path.split(/[?#]/u)[0]);
+    if (match === null)
+        throw new Error(FORM_PROBLEM);
+    const [, owner, repo, digits] = match;
+    if (!NAME.test(owner) || !NAME.test(repo) || owner === "." || owner === ".." || repo === "." || repo === "..")
+        throw new Error(FORM_PROBLEM);
+    const number = Number(digits);
+    if (!Number.isSafeInteger(number) || number < 1)
+        throw new Error(RANGE_PROBLEM);
+    return `https://${GITHUB_HOST}/${owner}/${repo}/pull/${number}`;
+}
+/**
+ * The one pull request named by any of the given strings, as
+ * `https://github.com/owner/repo/pull/123`. Empty strings are ignored. An
+ * unreadable github.com pull request URL, or two different pull requests, is an
+ * error: neither may be resolved by guessing which one was meant.
+ */
+export function detectPullRequest(inputs) {
+    const found = [];
+    for (const input of inputs) {
+        for (const token of pullTokens(input)) {
+            const url = canonicalPullUrl(token);
+            if (url !== null && !found.some(existing => existing.toLowerCase() === url.toLowerCase()))
+                found.push(url);
+        }
+    }
+    if (found.length === 0)
+        return undefined;
+    if (found.length > 1) {
+        const shown = found.slice(0, 3).join(", ");
+        const extra = found.length > 3 ? `, and ${found.length - 3} more` : "";
+        throw new Error(`Found ${found.length} different pull requests (${shown}${extra}). Pass exactly one.`);
+    }
+    return found[0];
+}

package/dist/review/questions.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Questions for the reviewing agent's own model.
+ *
+ * diffninja calls no model. Where a judgment needs meaning rather than syntax —
+ * does this change what callers observe, does a test exercise it, does a test
+ * change weaken it, does the documentation match the code, does the hunk serve
+ * the stated goal — the report asks the agent that requested it. Questions are
+ * fixed templates bound to specific hunks, generated deterministically from the
+ * facts, each with a closed set of options that always includes `cannot-tell`.
+ *
+ * Answers are recorded through the `record_answers` tool, validated against
+ * these options, attributed to the answering MCP client, and shown beside the
+ * hunk. They never change a status, a priority, or the report order: an answer
+ * is another reader's view, not a verdict.
+ */
+import type { PullRequestIntent } from "./evidence-types.js";
+import type { ProjectContext } from "./history.js";
+import type { ReviewItem } from "./types.js";
+/** Most questions one report asks; hunks earlier in the report are asked first. */
+export declare const MAX_REVIEW_QUESTIONS = 36;
+/** Most revert and removed-fix questions one report asks; the rest stay in the project context. */
+export declare const MAX_HISTORY_QUESTIONS = 3;
+export declare const QUESTION_OPTIONS: {
+    readonly behaviorChange: readonly ["changes-behavior", "no-behavior-change", "cannot-tell"];
+    readonly testCoverage: readonly ["exercised", "not-exercised", "cannot-tell"];
+    readonly testWeakened: readonly ["weakens", "does-not-weaken", "cannot-tell"];
+    readonly docMatchesCode: readonly ["matches", "contradicts", "cannot-tell"];
+    readonly intentFit: readonly ["serves", "supports", "unrelated", "contradicts", "cannot-tell"];
+    readonly undoesFix: readonly ["keeps-its-purpose", "undoes-it", "cannot-tell"];
+    readonly repeatsRevert: readonly ["reintroduces-it", "different-change", "cannot-tell"];
+    readonly followsGuidelines: readonly ["follows", "breaks-a-rule", "not-covered", "cannot-tell"];
+    readonly followsConvention: readonly ["should-follow", "differs-for-a-reason", "cannot-tell"];
+};
+export type QuestionKind = keyof typeof QUESTION_OPTIONS;
+/** How a recorded answer reads to the human: `watch` asks for a closer look, `unsure` means the agent could not tell. */
+export type VerdictTone = "ok" | "watch" | "unsure" | "quiet";
+export interface Verdict {
+    readonly label: string;
+    readonly tone: VerdictTone;
+}
+/** The short label a page shows for each answer, so the question's full wording stays with the agent. */
+export declare const ANSWER_VERDICTS: {
+    behaviorChange: {
+        "changes-behavior": {
+            label: string;
+            tone: "quiet";
+        };
+        "no-behavior-change": {
+            label: string;
+            tone: "quiet";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    testCoverage: {
+        exercised: {
+            label: string;
+            tone: "ok";
+        };
+        "not-exercised": {
+            label: string;
+            tone: "watch";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    testWeakened: {
+        weakens: {
+            label: string;
+            tone: "watch";
+        };
+        "does-not-weaken": {
+            label: string;
+            tone: "ok";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    docMatchesCode: {
+        matches: {
+            label: string;
+            tone: "ok";
+        };
+        contradicts: {
+            label: string;
+            tone: "watch";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    intentFit: {
+        serves: {
+            label: string;
+            tone: "ok";
+        };
+        supports: {
+            label: string;
+            tone: "quiet";
+        };
+        unrelated: {
+            label: string;
+            tone: "watch";
+        };
+        contradicts: {
+            label: string;
+            tone: "watch";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    undoesFix: {
+        "keeps-its-purpose": {
+            label: string;
+            tone: "ok";
+        };
+        "undoes-it": {
+            label: string;
+            tone: "watch";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    repeatsRevert: {
+        "reintroduces-it": {
+            label: string;
+            tone: "watch";
+        };
+        "different-change": {
+            label: string;
+            tone: "ok";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    followsGuidelines: {
+        follows: {
+            label: string;
+            tone: "ok";
+        };
+        "breaks-a-rule": {
+            label: string;
+            tone: "watch";
+        };
+        "not-covered": {
+            label: string;
+            tone: "quiet";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+    followsConvention: {
+        "should-follow": {
+            label: string;
+            tone: "watch";
+        };
+        "differs-for-a-reason": {
+            label: string;
+            tone: "quiet";
+        };
+        "cannot-tell": {
+            label: string;
+            tone: "unsure";
+        };
+    };
+};
+/** The verdict for a recorded answer, or undefined for an answer the question does not list. */
+export declare function verdictOf(kind: QuestionKind, choice: string): Verdict | undefined;
+export interface QuestionAnswer {
+    readonly choice: string;
+    /** The MCP client that recorded it, as it named itself; never a model identity claim. */
+    readonly answeredBy: string;
+    readonly answeredAt: string;
+}
+export interface ReviewQuestion {
+    /** Stable within one report: `q1`, `q2`, … in report order. */
+    readonly id: string;
+    readonly kind: QuestionKind;
+    /** The hunks the question is about; the first is the one it is asked beside. */
+    readonly unitIds: readonly string[];
+    readonly text: string;
+    readonly options: readonly string[];
+    answer?: QuestionAnswer;
+}
+/** The questions for one report, in report order, at most {@link MAX_REVIEW_QUESTIONS}. */
+export declare function reviewQuestions(items: readonly ReviewItem[], intent?: PullRequestIntent, project?: ProjectContext): ReviewQuestion[];