diffninja 0.3.2 → 0.4.0

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,16 +135,21 @@ export interface AgentOrder {
     /** diffninja's own order of the same items, kept so the page can still offer it. */
     diffninjaIds: string[];
 }
-/** How much a suggested comment matters, most to least: what a reviewer triages by. */
-export declare const COMMENT_SEVERITIES: readonly ["critical", "major", "minor"];
-export type CommentSeverity = (typeof COMMENT_SEVERITIES)[number];
-/** 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;
-    severity: CommentSeverity;
+    /** 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[];
@@ -180,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
@@ -189,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,2 +1,2 @@
-/** How much a suggested comment matters, most to least: what a reviewer triages by. */
-export const COMMENT_SEVERITIES = ["critical", "major", "minor"];
+/** 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);