diffninja 0.3.1 → 0.4.0

package/dist/review/result-budget.js

@@ -0,0 +1,136 @@
+import { withVisibleControls } from "./hidden-characters.js";
+/**
+ * The most JSON one copy of a `review_diff` result may hold. The result travels
+ * twice, as text content and as structured content, and MCP clients built on the
+ * SDK drop the connection at 10 MiB per message: a 20,000-line pull request
+ * produced 12 MB, which made the tool unusable for an ordinary large change.
+ * The text copy is itself a JSON string inside the message, so it is measured
+ * escaped once more: a change full of escaped quotes nearly doubles in it.
+ *
+ * Only the copy sent to the agent is trimmed. The server keeps the whole report
+ * for the pages and for validating what the agent sends back, and every trim is
+ * named in the result's warnings so the agent knows what it was not shown.
+ */
+export const MAX_RESULT_BYTES = 4 * 1024 * 1024;
+/** Room left for the fields a result adds around the report (ids, next steps). */
+const RESERVED_BYTES = 64 * 1024;
+/** Author claims kept when the result is over budget: they are navigation aids, not the review. */
+const KEPT_CLAIMS = 20;
+/** Review agenda entries kept when the result is over budget: past the first few they point at hunks the items already list. */
+const KEPT_AGENDA = 20;
+/** Bytes of the value as the text copy carries it. Escaping is per character, so an item adds exactly its own escaped length to the whole. */
+const bytesOf = (value) => Buffer.byteLength(JSON.stringify(JSON.stringify(value)), "utf8");
+const sizeOf = (current) => bytesOf({ snapshot: current.snapshot, report: current.report });
+const stages = [
+    ({ snapshot, report }) => snapshot === undefined || snapshot.lines.length === 0 ? undefined : {
+        next: { snapshot: { ...snapshot, lines: [] }, report },
+        note: `snapshot.lines (a line-by-line copy of the diff, ${snapshot.lines.length} lines) was left out; the hunks in report.items carry every line`,
+    },
+    ({ snapshot, report }) => report.callFlow.length === 0 && report.callFlows.length === 0 ? undefined : {
+        next: { snapshot, report: { ...report, callFlow: [], callFlows: [] } },
+        note: "the call-flow trees (callFlow, callFlows) were left out",
+    },
+    ({ snapshot, report }) => {
+        const intent = report.evidence?.intent;
+        if (report.evidence === undefined || intent === undefined || intent.claims.length <= KEPT_CLAIMS)
+            return undefined;
+        return {
+            next: { snapshot, report: { ...report, evidence: { ...report.evidence, intent: { ...intent, claims: intent.claims.slice(0, KEPT_CLAIMS) } } } },
+            note: `only the first ${KEPT_CLAIMS} of ${intent.claims.length} statements from the pull request text were kept`,
+        };
+    },
+    ({ snapshot, report }) => {
+        const evidence = report.evidence;
+        if (evidence === undefined || evidence.agenda.length <= KEPT_AGENDA)
+            return undefined;
+        return {
+            next: { snapshot, report: { ...report, evidence: { ...evidence, agenda: evidence.agenda.slice(0, KEPT_AGENDA) } } },
+            note: `only the first ${KEPT_AGENDA} of ${evidence.agenda.length} review agenda entries were kept; report.items lists every hunk`,
+        };
+    },
+    ({ snapshot, report }) => {
+        if (!report.items.some((item) => item.callFlow !== undefined || item.contextNodes !== undefined))
+            return undefined;
+        const items = report.items.map(({ callFlow: _flow, contextNodes: _nodes, ...rest }) => rest);
+        return { next: { snapshot, report: { ...report, items } }, note: "the per-hunk call context (callFlow, contextNodes) was left out" };
+    },
+];
+function withoutDiff(item) {
+    const lines = item.diff.split("\n").length;
+    return { ...item, diff: `${item.header}\n[The ${lines} lines of this hunk were left out to keep this result under ${MAX_RESULT_BYTES / 1024 / 1024} MiB. Read them in the repository or on the review page.]` };
+}
+function withoutFacts({ facts: _facts, history: _history, ...rest }) {
+    return { ...rest, reasons: [] };
+}
+/**
+ * Replace items by a smaller form, from the last (lowest-ranked) up, until the
+ * result fits. Each item is measured once, and the size is kept by subtracting
+ * what each replacement saves, so a change of thousands of hunks is not
+ * serialized again per hunk. An item the smaller form would not shrink is kept.
+ */
+function trimItems(current, size, limit, smaller) {
+    const items = [...current.report.items];
+    let left = size;
+    let trimmed = 0;
+    for (let index = items.length - 1; index >= 0 && left > limit; index -= 1) {
+        const item = items[index];
+        if (item === undefined)
+            continue;
+        const replacement = smaller(item);
+        const saved = bytesOf(item) - bytesOf(replacement);
+        if (saved <= 0)
+            continue;
+        items[index] = replacement;
+        left -= saved;
+        trimmed += 1;
+    }
+    return { next: { snapshot: current.snapshot, report: { ...current.report, items } }, size: left, trimmed };
+}
+/**
+ * The report (and, for a connected review, its snapshot) as the agent is sent
+ * it: with hidden characters shown as markers, whole while it fits, otherwise
+ * trimmed in a fixed order, from the parts an agent needs least to the hunks
+ * ranked last, with each trim recorded in `warnings`. The markers come first
+ * because they are what is sent: a 3-byte zero-width space becomes a 12-byte
+ * marker, so a budget taken before them undercounts.
+ */
+export function boundedForAgent(snapshot, report, budget = MAX_RESULT_BYTES) {
+    const limit = budget - RESERVED_BYTES;
+    let current = withVisibleControls({ snapshot, report });
+    let size = sizeOf(current);
+    if (size <= limit)
+        return current;
+    const notes = [];
+    for (const stage of stages) {
+        const result = stage(current);
+        if (result === undefined)
+            continue;
+        current = result.next;
+        size = sizeOf(current);
+        notes.push(result.note);
+        if (size <= limit)
+            break;
+    }
+    if (size > limit) {
+        const diffs = trimItems(current, size, limit, withoutDiff);
+        current = diffs.next;
+        size = diffs.size;
+        if (diffs.trimmed > 0)
+            notes.push(`${diffs.trimmed} of the lowest-ranked hunks have their diff text left out`);
+    }
+    if (size > limit) {
+        const facts = trimItems(current, size, limit, withoutFacts);
+        current = facts.next;
+        size = facts.size;
+        if (facts.trimmed > 0)
+            notes.push(`${facts.trimmed} of the lowest-ranked hunks have their facts, reasons, and history left out`);
+    }
+    // Every hunk must stay listed for the agent to order it, so past this point a
+    // result only shrinks by losing hunks; saying so beats a dropped connection.
+    if (size > limit) {
+        const hunks = report.items.length === 1 ? "1 hunk" : `${report.items.length} hunks`;
+        throw new Error(`This result is too large to send: with every diff, fact, and reason left out, the review of this change's ${hunks} is still ${(size / 1024 / 1024).toFixed(1)} MiB, over the ${budget / 1024 / 1024} MiB a client accepts in one message. Review the change in parts, with a narrower git range or a diff of fewer files.`);
+    }
+    const warning = `This result was over ${budget / 1024 / 1024} MiB, and the message carries it twice, so it was trimmed to stay under what a client accepts: ${notes.join("; ")}. The review page has the complete report.`;
+    return { snapshot: current.snapshot, report: { ...current.report, warnings: [...current.report.warnings, warning] } };
+}

package/dist/review/service.js

@@ -1,6 +1,8 @@
+import { grammarsInstallCommand, takeMissingGrammars } from "../languages/grammars.js";
+import { hiddenControlsByFile } from "./hidden-characters.js";
 import { resolve } from "node:path";
 import { runDiff } from "../run.js";
-import { readSnapshotFile } from "../git.js";
+import { MAX_INDEXED_FILES, MAX_INDEXED_FILE_BYTES, readSnapshotFile, takeSkippedSources } 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";
@@ -95,6 +97,12 @@ export async function reviewDiff(input, options = {}) {
     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.");
     }
+    const hiddenControls = hiddenControlsByFile(units);
+    if (hiddenControls.size > 0) {
+        const files = [...hiddenControls.keys()];
+        const points = [...new Set([...hiddenControls.values()].flat())].sort();
+        warnings.push(`Lines this change adds or removes in ${files.slice(0, 5).join(", ")}${files.length > 5 ? ` and ${files.length - 5} more files` : ""} contain hidden or bidirectional control characters (${points.join(", ")}). They can make code read differently from how it compiles (Trojan Source, CVE-2021-42574); the pages show each as a ⟦U+XXXX⟧ marker. Read those lines with the markers before trusting them.`);
+    }
     let evidence = buildReviewEvidence(units);
     const callFlow = [];
     let trees = [];
@@ -127,6 +135,8 @@ export async function reviewDiff(input, options = {}) {
     // 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) {
+        takeMissingGrammars();
+        takeSkippedSources();
         try {
             const flow = runDiff({
                 cwd: cwd, from: snapshots.from, to: snapshots.to, maxDepth: CALL_FLOW_MAX_DEPTH, color: false, locs: true,
@@ -160,6 +170,20 @@ export async function reviewDiff(input, options = {}) {
             evidence = buildReviewEvidence(units);
             warnings.push("Call-flow analysis failed. Review is based on the diff only. Inspect repository context manually.");
         }
+        const left = takeSkippedSources();
+        if (left.oversized > 0 || left.beyondLimit > 0) {
+            const parts = [
+                left.oversized > 0 ? `${left.oversized} source ${left.oversized === 1 ? "file" : "files"} over ${MAX_INDEXED_FILE_BYTES / 1024 / 1024} MiB (generated or minified code)` : "",
+                left.beyondLimit > 0 ? `${left.beyondLimit} ${left.beyondLimit === 1 ? "file" : "files"} beyond the ${MAX_INDEXED_FILES.toLocaleString("en-US")} read per revision` : "",
+            ].filter((part) => part !== "");
+            warnings.push(`Call flows did not read ${parts.join(" and ")}. Flows through them are absent, which is not evidence of safety.`);
+            if (callFlowAvailability === "no-changes")
+                callFlowAvailability = "partial";
+        }
+        const missing = takeMissingGrammars();
+        if (missing.length > 0) {
+            warnings.push(`Call flows skip the files these grammars would read: ${missing.join(", ")}. diffninja does not download code while it reviews; run \`${grammarsInstallCommand(missing)}\` once and review again to include them. Flows through those files are absent, which is not evidence of safety.`);
+        }
     }
     if (options.referenceProject !== undefined) {
         if (!snapshots)
@@ -186,7 +210,7 @@ export async function reviewDiff(input, options = {}) {
     // 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)
+    if (callFlows.length > 0 && callFlowAvailability === "no-changes")
         callFlowAvailability = "available";
     const report = { title: options.pr?.title || "Focused PR review", source, createdAt: new Date().toISOString(),
         pr: options.pr,

package/dist/review/setup.d.ts

@@ -11,7 +11,7 @@
  * the `gh` session.
  */
 import { type Stats } from "node:fs";
-export declare const setupHelp = "diffninja setup. Register the diffninja MCP server on every detected agent CLI.\n\n  npx -y diffninja@latest setup [--cli claude,codex,omp,pi] [--dry-run]\n  diffninja setup --uninstall [--cli codex]\n\nDetects Claude Code, Codex, OMP, and pi from their config files or binaries\nand registers the diffninja MCP server in each user config, pointing at the\nglobally installed package. Installs the package globally first\n(`npm install -g diffninja@<this version>`) so the registration keeps\nworking, and updates a global install older than this setup, so running\n`npx -y diffninja@latest setup` again is how you update. When that install\nfails it registers an npx-based entry pinned to this version and says so.\n\nOptions:\n  --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.\n  --uninstall    Remove the diffninja server from every detected CLI.\n  --dry-run      Show what would change, without installing or writing.\n  --no-install   Skip installing or updating the global package; without one,\n                 register npx-based entries.\n  --help         Show this help.\n\nThe server needs no API key: static reviews run locally, and pull request\nreviews reuse your authenticated gh session.\n";
+export declare const setupHelp = "diffninja setup. Register the diffninja MCP server on every detected agent CLI.\n\n  npx -y diffninja@latest setup [--cli claude,codex,omp,pi] [--dry-run]\n  diffninja setup --uninstall [--cli codex]\n\nDetects Claude Code, Codex, OMP, and pi from their config files or binaries\nand registers the diffninja MCP server in each user config, pointing at the\nglobally installed package. Installs the package globally first\n(`npm install -g diffninja@<this version>`) so the registration keeps\nworking, and updates a global install older than this setup, so running\n`npx -y diffninja@latest setup` again is how you update. When that install\nfails it registers an npx-based entry pinned to this version and says so.\n\nEach JSON config it changes is rewritten in full, in standard formatting\n(indentation, string escapes and integers above 2^53 can change), and no\nbackup is kept. Copy ~/.claude.json before the first run.\n\nOptions:\n  --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.\n  --uninstall    Remove the diffninja server from every detected CLI.\n  --dry-run      Show what would change, without installing or writing.\n  --no-install   Skip installing or updating the global package; without one,\n                 register npx-based entries.\n  --help         Show this help.\n\nThe server needs no API key: static reviews run locally, and pull request\nreviews reuse your authenticated gh session.\n";
 export declare const CLI_NAMES: readonly ["claude", "codex", "omp", "pi"];
 export type CliName = (typeof CLI_NAMES)[number];
 export interface McpEntry {

package/dist/review/setup.js

@@ -18,6 +18,7 @@ import { lstat, mkdir, open, readFile, readlink, realpath, rename, rm, stat } fr
 import { homedir } from "node:os";
 import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { z } from "zod";
+import { npmEnvironment, windowsShell } from "../languages/child-env.js";
 import { npmCliPath, npmSpawnSpec } from "../languages/grammars.js";
 import { removeTomlTable, upsertTomlTable } from "./toml.js";
 import { compareVersions, packageVersion } from "./version.js";
@@ -34,6 +35,10 @@ working, and updates a global install older than this setup, so running
 \`npx -y diffninja@latest setup\` again is how you update. When that install
 fails it registers an npx-based entry pinned to this version and says so.
 
+Each JSON config it changes is rewritten in full, in standard formatting
+(indentation, string escapes and integers above 2^53 can change), and no
+backup is kept. Copy ~/.claude.json before the first run.
+
 Options:
   --cli NAMES    Only these CLIs, comma-separated: claude,codex,omp,pi.
   --uninstall    Remove the diffninja server from every detected CLI.
@@ -70,7 +75,7 @@ export function npxEntry(platform = process.platform, version = packageVersion()
 export function windowsCliEntry(name, args, cliPath = npmCliPath) {
     const npmCli = cliPath(`${name}-cli.js`);
     if (npmCli === undefined) {
-        return { command: process.env["ComSpec"] ?? "cmd.exe", args: ["/d", "/s", "/c", name, ...args] };
+        return { command: windowsShell(), args: ["/d", "/s", "/c", name, ...args] };
     }
     return { command: process.execPath, args: [npmCli, ...args] };
 }
@@ -108,7 +113,8 @@ export function globalIsOlder(installed, version) {
  */
 export function createNpm(overrides = {}) {
     const platform = overrides.platform ?? process.platform;
-    const env = overrides.env;
+    // Installing runs the install scripts of diffninja and its dependencies: they get what npm needs, not the shell's tokens.
+    const env = overrides.env ?? npmEnvironment();
     const run = (args, inherit) => {
         const spec = npmSpawnSpec(args, platform);
         return spawn(spec.file, spec.args, inherit ? { stdio: "inherit", env } : { env });
@@ -144,7 +150,6 @@ async function exitCode(child) {
         return -1;
     }
 }
-const realNpm = createNpm();
 /** `npm root -g`, or undefined when npm is unavailable or fails. */
 async function globalRoot(npm) {
     try {
@@ -557,7 +562,7 @@ export async function runSetup(options = {}, deps = {}) {
     let entry;
     let viaNpx = false;
     if (!uninstall) {
-        const resolved = await resolveEntry(options.noInstall === true, deps.npm ?? realNpm, quiet, dryRun, version);
+        const resolved = await resolveEntry(options.noInstall === true, deps.npm ?? createNpm(), quiet, dryRun, version);
         entry = resolved.entry;
         viaNpx = resolved.viaNpx;
     }

package/dist/review/types.d.ts

@@ -1,3 +1,4 @@
+import type { UpdateNotice } from "./update-check.js";
 import type { PullRequestIntent, ReviewEvidence } from "./evidence-types.js";
 import type { ChangeFacts } from "./change-facts.js";
 import type { ReviewQuestion } from "./questions.js";
@@ -62,10 +63,12 @@ export interface CallFlowFile {
  * Why structured call flows are present or absent. `available` means at least
  * one changed file has trees; `no-changes` means there was nothing structural to
  * attach (no changed file with text hunks, or no tree reaching one) and is not a
- * safety claim; `needs-git-range` means the input was a patch; `failed` means
- * the analysis threw.
+ * safety claim; `partial` means the analysis left source files out (over the
+ * size bound or past the file limit, named in the warnings), with or without
+ * trees, so paths through them are absent; `needs-git-range` means the input was
+ * a patch; `failed` means the analysis threw.
  */
-export type CallFlowAvailability = "available" | "needs-git-range" | "no-changes" | "failed";
+export type CallFlowAvailability = "available" | "needs-git-range" | "no-changes" | "partial" | "failed";
 /**
  * One keyed piece of structured review context for a hunk: a changed, caller, or
  * callee definition with its snapshot-bound source and the call/binding evidence
@@ -132,12 +135,21 @@ export interface AgentOrder {
     /** diffninja's own order of the same items, kept so the page can still offer it. */
     diffninjaIds: string[];
 }
-/** One line comment the reviewing agent suggests; the human adds it to their review or not. */
+/** How the agent came to believe a comment: it ran or reproduced the failure, or followed the code path by reading it. A guess is not a blocker. */
+export declare const COMMENT_EVIDENCE: readonly ["ran", "traced"];
+export type CommentEvidence = (typeof COMMENT_EVIDENCE)[number];
+/** One line comment the reviewing agent suggests. Every one claims to block the merge, so each carries its proof. */
 export interface SuggestedComment {
     path: string;
     line: number;
     side: "LEFT" | "RIGHT";
+    /** The reviewer's own words; the only field that joins the human's draft. */
     body: string;
+    /** A concrete input or state and the wrong result, or the written rule it breaks and where the rule is written. */
+    scenario: string;
+    evidence: CommentEvidence;
+    /** What would have to be true for this not to be a problem. */
+    unlessTrue: string;
 }
 export interface AgentComments {
     comments: SuggestedComment[];
@@ -176,7 +188,7 @@ export interface ReviewReport {
     questions: ReviewQuestion[];
     /** The reading order the reviewing agent recorded; once present, `items` follow it. */
     agentOrder?: AgentOrder;
-    /** Line comments the reviewing agent suggested; nothing is posted until the human submits them. */
+    /** Comments the reviewing agent says block the merge; nothing is posted until the human submits them. */
     agentComments?: AgentComments;
     /**
      * The reviewing agent's own paragraph on the pull request's goal, written
@@ -185,6 +197,8 @@ export interface ReviewReport {
      * agent's reading rather than a verified claim.
      */
     agentSummary?: AgentSummary;
+    /** A newer diffninja exists on npm; set only by the executable's opt-in version lookup. */
+    updateNotice?: UpdateNotice;
     /**
      * Every function a reader meets in this report (around the hunks and in the
      * call flows), each with a stable `<file>#<name>` id, for the reviewing agent

package/dist/review/types.js

@@ -1 +1,2 @@
-export {};
+/** How the agent came to believe a comment: it ran or reproduced the failure, or followed the code path by reading it. A guess is not a blocker. */
+export const COMMENT_EVIDENCE = ["ran", "traced"];

package/dist/review/update-check.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tells the user when a newer diffninja is on npm. It is OFF unless the person
+ * who starts the server turns it on with `DIFFNINJA_UPDATE_CHECK=1`: a review
+ * tool that reads company code should make no request of its own by default.
+ * When on, the lookup is one GET of the package's latest version, sent the
+ * first time a review is requested (never at process start), and any failure
+ * means "no notice", never an error. The server library never looks anything up
+ * unless it is handed a lookup; only `mcp-cli.ts` builds one, from the
+ * environment.
+ */
+/** How to update: re-running setup installs the newest package and re-points every agent. */
+export declare const UPDATE_COMMAND = "npx diffninja@latest setup";
+export interface UpdateNotice {
+    current: string;
+    latest: string;
+    command: string;
+}
+export type LatestVersion = () => Promise<string | undefined>;
+/** The newest published release, or undefined when the registry cannot be reached or answers oddly. */
+export declare function registryLatest(): Promise<string | undefined>;
+/**
+ * The lookup the executable uses: none unless `DIFFNINJA_UPDATE_CHECK=1`, and
+ * never in CI or when npm's own `NO_UPDATE_NOTIFIER` is set.
+ */
+export declare function updateLookupFromEnv(env?: NodeJS.ProcessEnv): LatestVersion | undefined;
+/** One lookup per connection, started by the first review that asks and never awaited longer than WAIT_MS. */
+export declare class UpdateNotifier {
+    private readonly lookup;
+    private readonly current;
+    private pending;
+    constructor(lookup: LatestVersion | undefined, current?: string);
+    notice(): Promise<UpdateNotice | undefined>;
+}
+/** The sentence for the agent: say it first, in its own words, and carry on with the review. */
+export declare function updateStep(notice: UpdateNotice): string;

package/dist/review/update-check.js

@@ -0,0 +1,76 @@
+/**
+ * Tells the user when a newer diffninja is on npm. It is OFF unless the person
+ * who starts the server turns it on with `DIFFNINJA_UPDATE_CHECK=1`: a review
+ * tool that reads company code should make no request of its own by default.
+ * When on, the lookup is one GET of the package's latest version, sent the
+ * first time a review is requested (never at process start), and any failure
+ * means "no notice", never an error. The server library never looks anything up
+ * unless it is handed a lookup; only `mcp-cli.ts` builds one, from the
+ * environment.
+ */
+import { z } from "zod";
+import { compareVersions, packageVersion } from "./version.js";
+/** How to update: re-running setup installs the newest package and re-points every agent. */
+export const UPDATE_COMMAND = "npx diffninja@latest setup";
+const REGISTRY_URL = "https://registry.npmjs.org/diffninja/latest";
+const LOOKUP_TIMEOUT_MS = 3000;
+/** The longest a review waits for the lookup; a slower answer shows up on the next review. */
+const WAIT_MS = 1500;
+/** The registry answers with the whole manifest of one release (tens of KB); anything near this is not it. */
+const MAX_RESPONSE_CHARS = 512 * 1024;
+/** Only a plain release counts: nothing else may reach the agent's instructions or a page. */
+const RELEASE = /^\d{1,6}\.\d{1,6}\.\d{1,6}$/;
+const latestSchema = z.object({ version: z.string().regex(RELEASE) });
+/** The newest published release, or undefined when the registry cannot be reached or answers oddly. */
+export async function registryLatest() {
+    try {
+        // A redirect would send the request somewhere the fixed URL above does not name.
+        const response = await fetch(REGISTRY_URL, { headers: { accept: "application/json" }, redirect: "error", signal: AbortSignal.timeout(LOOKUP_TIMEOUT_MS) });
+        if (!response.ok)
+            return undefined;
+        const text = await response.text();
+        if (text.length > MAX_RESPONSE_CHARS)
+            return undefined;
+        return latestSchema.parse(JSON.parse(text)).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The lookup the executable uses: none unless `DIFFNINJA_UPDATE_CHECK=1`, and
+ * never in CI or when npm's own `NO_UPDATE_NOTIFIER` is set.
+ */
+export function updateLookupFromEnv(env = process.env) {
+    if (env["DIFFNINJA_UPDATE_CHECK"] !== "1")
+        return undefined;
+    if (env["NO_UPDATE_NOTIFIER"] !== undefined || env["CI"] !== undefined)
+        return undefined;
+    return registryLatest;
+}
+/** One lookup per connection, started by the first review that asks and never awaited longer than WAIT_MS. */
+export class UpdateNotifier {
+    lookup;
+    current;
+    pending;
+    constructor(lookup, current = packageVersion()) {
+        this.lookup = lookup;
+        this.current = current;
+    }
+    async notice() {
+        if (this.lookup === undefined)
+            return undefined;
+        this.pending ??= this.lookup().catch(() => undefined);
+        // AbortSignal.timeout's timer never keeps the process alive, so nothing needs clearing.
+        const timer = new Promise(resolve => AbortSignal.timeout(WAIT_MS).addEventListener("abort", () => resolve(undefined), { once: true }));
+        const latest = await Promise.race([this.pending, timer]);
+        if (latest === undefined || !RELEASE.test(latest))
+            return undefined;
+        const newer = compareVersions(latest, this.current);
+        return newer !== undefined && newer > 0 ? { current: this.current, latest, command: UPDATE_COMMAND } : undefined;
+    }
+}
+/** The sentence for the agent: say it first, in its own words, and carry on with the review. */
+export function updateStep(notice) {
+    return `Before anything else, tell the user in one sentence that diffninja ${notice.latest} is available (this is ${notice.current}) and that they update by running \`${notice.command}\` in a terminal and restarting their agent; then continue this review.`;
+}

package/dist/run.js

@@ -1,18 +1,22 @@
+import { GrammarNotInstalledError } from "./languages/grammars.js";
 import { buildCallTreeFromInfo, exportsInFile, resolveEntry, resolveEntrypointFile, indexedFiles, } from "./calltree.js";
 import { buildIndex, extractCached } from "./extract.js";
-import { assertGitRepo, describeSnapshot, listSnapshotFiles, resolveDiffSnapshotsAndPaths, resolveSnapshotAndPaths, verifyCommit, visitCommitBlobs, visitWorktreeFiles, } from "./git.js";
+import { assertGitRepo, changedPaths, describeSnapshot, listSnapshotFiles, resolveDiffSnapshotsAndPaths, resolveSnapshotAndPaths, verifyCommit, visitCommitBlobs, visitWorktreeFiles, } from "./git.js";
 import { diffEntry, diffPinnedEntry, inferEntries, resolveExplicitDiffEntries, } from "./infer.js";
 import { collectPathsTo, findReachPaths } from "./reach.js";
 import { renderDiff, renderTree } from "./render.js";
 import { assignOptionalTreeFields } from "./types.js";
-function loadIndex(cwd, snapshot, pathFilters, cache = new Map()) {
-    const files = listSnapshotFiles(cwd, snapshot, pathFilters);
+function loadIndex(cwd, snapshot, pathFilters, cache = new Map(), changed = new Set()) {
+    const files = listSnapshotFiles(cwd, snapshot, pathFilters, changed);
     const extracted = new Map();
     const extract = (file, source) => {
         try {
             extracted.set(file.path, extractCached(file.path, source, cache));
         }
         catch (error) {
+            // A grammar that is not installed is reported once, by the review, not per file.
+            if (error instanceof GrammarNotInstalledError)
+                return;
             const message = error instanceof Error ? error.message : String(error);
             console.error(`warn: failed to parse ${file.path} @ ${snapshot.ref}: ${message}`);
         }
@@ -120,8 +124,10 @@ export function runDiff(options = {}) {
     if (to.kind === "commit")
         verifyCommit(cwd, to.ref);
     const extractionCache = new Map();
-    const before = loadIndex(cwd, from, resolvedPaths, extractionCache);
-    const after = loadIndex(cwd, to, resolvedPaths, extractionCache);
+    // A repository past the file limit still indexes the files this diff changes.
+    const changed = changedPaths(cwd, from, to);
+    const before = loadIndex(cwd, from, resolvedPaths, extractionCache, changed);
+    const after = loadIndex(cwd, to, resolvedPaths, extractionCache, changed);
     extractionCache.clear();
     options.onIndexes?.(before, after);
     const fromLabel = describeSnapshot(from);