diffninja 0.3.1 → 0.4.0

package/README.md

@@ -10,7 +10,7 @@ submit the review to GitHub yourself.
 
 - **Read the important changes first.** Big PRs are hard to follow file by
   file. diffninja numbers each change, most important first, and lets you step
-  through them with `j` and `k`.
+  through them with `j` and `k` and tick them off.
 - **See what the change does to the product, not just the code.** Your agent
   explains the change in business terms: the processes it touches as
   flowcharts, with new and changed steps highlighted, the business rules it
@@ -19,15 +19,29 @@ submit the review to GitHub yourself.
 - **Your agent does the first pass.** For each change, the agent answers simple
   questions: does it change behavior, is it tested, does it match the PR's
   goal. The answers sit above the code.
-- **Suggested comments, never posted for you.** The agent can suggest short
-  line comments. You add them with one click, edit them, or dismiss them.
-  Nothing reaches GitHub until you press Submit.
+- **Suggested comments are blockers only, never posted for you.** The agent
+  suggests a comment only for what blocks the merge, and shows its proof: the
+  case that fails, how it checked, and what would make it fine. No comment at
+  all is the normal result, and anything that does not block is dropped. You
+  add a comment with one click, edit it, or dismiss it.
+  None of diffninja's tools posts anything. The review reaches GitHub when
+  Submit is pressed on your review page, and your agent is told never to do
+  that itself.
 - **Facts you can check.** diffninja points at the exact lines that changed a
   comparison, a limit, an input check, or error handling. It also shows call
   flows: which functions call the changed code.
-- **Private.** The analysis runs on your machine. diffninja calls no AI model,
-  needs no API key, and sends your code nowhere. It uses your existing GitHub
-  CLI login to read the PR and post your review.
+- **The analysis runs on your machine.** diffninja calls no AI model, needs no
+  API key, has no telemetry of its own, and does not download or build code
+  during a review. It makes no request of its own while it reviews, except an
+  update notice that is off unless you turn it on. It uses your existing GitHub
+  CLI login to read the PR, to post your review when Submit is pressed, and to
+  mark a file Viewed on GitHub when you tick its changes.
+  Installing diffninja and adding language grammars use npm. Your agent sends
+  what diffninja returns, source text included, to its own model, as it does
+  with any tool result. It is not "local only" in every respect.
+  [docs/security.md](docs/security.md) lists what runs, what is downloaded, what
+  is written and what your agent can reach, including the parts that are not
+  local.
 
 ## What you need
 
@@ -45,8 +59,23 @@ Run this once:
 npx -y diffninja@latest setup
 ```
 
-It installs diffninja and adds it to every agent CLI it finds on your machine.
-Then restart your agent CLI.
+It installs diffninja globally with `npm install -g` (if that fails, it registers
+an `npx` entry instead), and adds diffninja to every agent CLI it finds on your
+machine by editing that CLI's config file. Then restart your agent CLI.
+
+Setup rewrites a JSON config file in full, in standard formatting, and keeps no
+backup. Indentation, string escapes and integers above 2^53 in it can change.
+`~/.claude.json` is Claude Code's main state file, so copy it before the first
+run (`cp ~/.claude.json ~/.claude.json.bak`).
+
+[docs/security.md](docs/security.md) and this README describe diffninja 0.4.0
+and later. Version 0.3.2 and earlier behave as two security audits found. The
+review page's submit API had no secret in its path, so any local process could
+use it. Reviews installed grammars with npm at review time. Hidden characters
+were not marked, and the package had no pinned dependency tree.
+`npx -y diffninja@latest setup` installs the newest published version. Check
+that it is 0.4.0 or later with `npm ls -g diffninja`, or read the version in the
+entry setup wrote to your agent's config.
 
 To update later, run the same command again: setup brings an older global
 install up to its own version, then restart your agent CLI. (Setup from
@@ -76,6 +105,12 @@ your machine at `127.0.0.1`). On the page:
    `j` and `k` move to the next and previous change, and the list on the left
    shows where you are. The agent sets the reading order; the connected page
    does not label changes “Attention”.
+   Tick a change in that list when you have read it. Scrolling ticks nothing.
+   GitHub's **Viewed** mark belongs to a file, so a file is marked Viewed on
+   GitHub once every change of it is ticked, and unticking one clears the mark.
+   A file already marked Viewed on GitHub starts ticked. If diffninja cannot
+   read or write the marks, the page says "not synced with GitHub" and keeps
+   your ticks in the tab.
 2. Hover a line and press **+** to write a comment, or add the agent's
    suggestions.
 3. Write a summary, choose **Comment**, **Approve**, or **Request changes**.
@@ -84,7 +119,21 @@ your machine at `127.0.0.1`). On the page:
 
 Tip: if your agent is running inside a local clone of the repository, it can
 pass the clone to diffninja. You then also get call-flow diagrams for the
-changed files.
+changed files. Call flows read JavaScript and TypeScript out of the box. For
+other languages (Python, Go, Java, Rust, C#, Ruby, and more), install their
+grammars once. This step downloads grammar code through npm at exact versions,
+checked against hashes shipped with diffninja, and runs no install script. Use
+the version of diffninja your agent runs, because diffninja may not read
+grammars that another version installed. A review that needs them says which
+files its call flows skipped and prints the exact command, which has the form
+`npx -y diffninja@<version> grammars install`. Kotlin and Perl also need
+`--build`, which compiles them on your machine and runs their install scripts.
+A review never installs anything itself.
+
+If the local clone is a partial clone (for example made with
+`git clone --filter=blob:none`), git may fetch missing objects from that clone's
+own remote while diffninja reads it, as `git log -p` would. diffninja itself
+never runs a fetch or a checkout.
 
 You can also review changes that aren't a PR yet:
 
@@ -100,7 +149,12 @@ and gives you a link to read the same report in your browser.
 - The review page closes when you exit your agent CLI.
 - The page and the agent's session contain source code. Treat them like the
   code itself.
-- diffninja never approves, blocks, or merges anything on its own.
+- No diffninja tool approves, blocks, merges or posts anything. A review is
+  submitted when Submit is pressed on the review page. The page's one other
+  write to GitHub is a file's Viewed mark, which follows your ticks. Anyone
+  holding that page's link can do both through the page's API, and your agent
+  holds the link. diffninja tells the agent never to submit. It cannot enforce
+  that.
 
 ## More
 

package/dist/executables.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where a command the review runs (`git`, `gh`) really is.
+ *
+ * On Windows the runtime looks for a bare command name in the child's working
+ * directory before it looks at PATH. Every git call runs with the repository under
+ * review as its working directory, so a `git.exe` committed in that repository, or
+ * a `gh.exe` in the directory the agent was started in, would run instead of the
+ * real tool as soon as its branch is checked out. Here the name is resolved once
+ * against PATH's absolute entries only, to a full path, and that path is what runs.
+ * Elsewhere the name is returned as it is: PATH lookup does not search the
+ * working directory.
+ */
+export interface ExecutableLookup {
+    readonly platform?: NodeJS.Platform;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly exists?: (path: string) => boolean;
+}
+export declare function resolveExecutable(name: string, lookup?: ExecutableLookup): string;

package/dist/executables.js

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { win32 } from "node:path";
+/** Only real executables: a `.cmd` or `.bat` cannot be started without a shell. */
+const EXTENSIONS = [".exe", ".com"];
+const resolved = new Map();
+export function resolveExecutable(name, lookup = {}) {
+    const platform = lookup.platform ?? process.platform;
+    if (platform !== "win32")
+        return name;
+    const env = lookup.env ?? process.env;
+    const cacheable = lookup.env === undefined && lookup.exists === undefined;
+    const known = cacheable ? resolved.get(name) : undefined;
+    if (known !== undefined)
+        return known;
+    const exists = lookup.exists ?? existsSync;
+    const path = env["PATH"] ?? env["Path"] ?? "";
+    for (const raw of path.split(";")) {
+        const directory = raw.trim().replace(/^"|"$/g, "");
+        // A relative or empty entry means "here": never a place to find a tool.
+        if (directory === "" || !win32.isAbsolute(directory))
+            continue;
+        for (const extension of EXTENSIONS) {
+            const candidate = win32.join(directory, name + extension);
+            if (!exists(candidate))
+                continue;
+            if (cacheable)
+                resolved.set(name, candidate);
+            return candidate;
+        }
+    }
+    throw new Error(`${name} was not found on PATH. Only absolute PATH entries are searched, never the repository or the current directory.`);
+}

package/dist/git.d.ts

@@ -26,7 +26,32 @@ export interface SnapshotFile {
     oid?: string;
     size?: number;
 }
-export declare function listSnapshotFiles(cwd: string, snapshot: Snapshot, pathFilters?: string[]): SnapshotFile[];
+/**
+ * Bounds on what call-flow analysis parses from one revision: a source file over
+ * this size is generated or minified code, not something a person reads. Past
+ * the file limit, the files the diff changes are read first, then the rest of
+ * their directories, then everything else in code-point order, so the same range
+ * leaves out the same files on every machine. The review names what was skipped.
+ */
+export declare const MAX_INDEXED_FILE_BYTES: number;
+export declare const MAX_INDEXED_FILES = 15000;
+export interface SkippedSources {
+    /** Source files over the size bound. */
+    oversized: number;
+    /** Files past the count bound. */
+    beyondLimit: number;
+}
+/** What was left out of call-flow analysis since the last call; clears the count. */
+export declare function takeSkippedSources(): SkippedSources;
+/**
+ * Paths that differ between two snapshots, both sides of a rename included,
+ * relative to `cwd` as the snapshot listings are.
+ */
+export declare function changedPaths(cwd: string, from: Snapshot, to: Snapshot): Set<string>;
+export declare function listSnapshotFiles(cwd: string, snapshot: Snapshot, pathFilters?: string[], changed?: ReadonlySet<string>, limits?: {
+    readonly maxFiles: number;
+    readonly maxFileBytes: number;
+}): SnapshotFile[];
 export declare function visitCommitBlobs(cwd: string, files: SnapshotFile[], visit: (oid: string, source: string) => void): void;
 export declare function visitWorktreeFiles(cwd: string, files: SnapshotFile[], visit: (file: SnapshotFile, source: string) => void): void;
 export declare function describeSnapshot(snapshot: Snapshot): string;

package/dist/git.js

@@ -1,12 +1,16 @@
+import { resolveExecutable } from "./executables.js";
 import { execFileSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { listSupportedExtensions } from "./languages/registry.js";
+/** A git command that has not answered in this long (a dead network share) is stopped, not waited for forever. */
+const GIT_TIMEOUT_MS = 120_000;
 function gitBuffer(cwd, args, input, maxBuffer = 64 * 1024 * 1024) {
-    return execFileSync("git", ["--no-replace-objects", ...args], {
+    return execFileSync(resolveExecutable("git"), ["--no-replace-objects", ...args], {
         cwd,
         input,
         maxBuffer,
+        timeout: GIT_TIMEOUT_MS,
         stdio: ["pipe", "pipe", "pipe"],
     });
 }
@@ -183,13 +187,61 @@ function pathAllowed(file, pathFilters) {
             file.endsWith(normalized));
     });
 }
-export function listSnapshotFiles(cwd, snapshot, pathFilters = []) {
+/**
+ * Bounds on what call-flow analysis parses from one revision: a source file over
+ * this size is generated or minified code, not something a person reads. Past
+ * the file limit, the files the diff changes are read first, then the rest of
+ * their directories, then everything else in code-point order, so the same range
+ * leaves out the same files on every machine. The review names what was skipped.
+ */
+export const MAX_INDEXED_FILE_BYTES = 1024 * 1024;
+export const MAX_INDEXED_FILES = 15_000;
+/** Paths, so a file left out of both revisions of a diff counts once. */
+const skipped = { oversized: new Set(), beyondLimit: new Set() };
+/** What was left out of call-flow analysis since the last call; clears the count. */
+export function takeSkippedSources() {
+    const counts = { oversized: skipped.oversized.size, beyondLimit: skipped.beyondLimit.size };
+    skipped.oversized.clear();
+    skipped.beyondLimit.clear();
+    return counts;
+}
+/**
+ * Paths that differ between two snapshots, both sides of a rename included,
+ * relative to `cwd` as the snapshot listings are.
+ */
+export function changedPaths(cwd, from, to) {
+    const refs = [from, to].filter((snapshot) => snapshot.kind === "commit").map((snapshot) => snapshot.ref);
+    return new Set(git(cwd, ["diff", "--relative", "--name-only", "-z", "--no-renames", ...refs, "--"]).split("\0").filter(Boolean));
+}
+function directoryOf(path) {
+    return path.slice(0, path.lastIndexOf("/") + 1);
+}
+export function listSnapshotFiles(cwd, snapshot, pathFilters = [], changed = new Set(), limits = { maxFiles: MAX_INDEXED_FILES, maxFileBytes: MAX_INDEXED_FILE_BYTES }) {
     const files = snapshot.kind === "worktree"
         ? listWorktreeFiles(cwd)
         : listCommitFiles(cwd, snapshot.ref);
-    return files
+    const wanted = files
         .filter((file) => pathAllowed(file.path, pathFilters))
-        .sort((a, b) => a.path.localeCompare(b.path));
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const small = [];
+    for (const file of wanted) {
+        if (file.size !== undefined && file.size > limits.maxFileBytes)
+            skipped.oversized.add(file.path);
+        else
+            small.push(file);
+    }
+    if (small.length <= limits.maxFiles)
+        return small;
+    const directories = new Set([...changed].map(directoryOf));
+    const first = [], neighbours = [], rest = [];
+    for (const file of small) {
+        (changed.has(file.path) ? first : directories.has(directoryOf(file.path)) ? neighbours : rest).push(file);
+    }
+    const kept = new Set([...first, ...neighbours, ...rest].slice(0, limits.maxFiles));
+    for (const file of small)
+        if (!kept.has(file))
+            skipped.beyondLimit.add(file.path);
+    return small.filter((file) => kept.has(file));
 }
 const BATCH_BYTES = 32 * 1024 * 1024;
 function chunkBlobs(files) {

package/dist/languages/child-env.d.ts

@@ -0,0 +1,11 @@
+/** Compared without regard to case: Windows spells `Path`, `ComSpec` and `SystemRoot` its own way. */
+export declare function npmEnvironment(env?: NodeJS.ProcessEnv, extra?: Readonly<Record<string, string>>, options?: {
+    readonly build?: boolean;
+}): NodeJS.ProcessEnv;
+/**
+ * The shell Windows runs a `.cmd` shim with, when no npm JS entry point can be
+ * found. ComSpec is used only when it is an absolute path to `cmd.exe`; anything
+ * else in that variable would otherwise be written into an agent's config and run
+ * every time the agent starts.
+ */
+export declare function windowsShell(env?: NodeJS.ProcessEnv): string;

package/dist/languages/child-env.js

@@ -0,0 +1,60 @@
+import { isAbsolute } from "node:path";
+/**
+ * The environment npm gets when diffninja runs it. npm and the install scripts
+ * of the packages it fetches inherit their parent's environment, and an engineer's
+ * shell carries tokens (GitHub, cloud providers, package registries) that no
+ * install has any business seeing. Only what npm and node-gyp need to find their
+ * tools, cache, proxy and certificates is passed on; npm's own `npm_config_*`
+ * variables are the user's npm configuration and pass too.
+ */
+const KEPT = new Set([
+    "PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_ALL", "LC_CTYPE", "TERM", "TZ",
+    "TMPDIR", "TMP", "TEMP",
+    "XDG_CACHE_HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME",
+    "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "ALL_PROXY",
+    "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR",
+    // Windows: without these npm cannot find its own files, Python or the compiler.
+    "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA", "PROGRAMDATA",
+    "PROGRAMFILES", "PROGRAMFILES(X86)", "PROGRAMW6432", "COMMONPROGRAMFILES", "COMMONPROGRAMFILES(X86)",
+    "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT", "OS", "PROCESSOR_ARCHITECTURE", "NUMBER_OF_PROCESSORS",
+]);
+/** What a source build (node-gyp) also looks for: compiler, Python and SDK locations. Only when the person asked for a build. */
+const BUILD_KEPT = new Set(["CC", "CXX", "CFLAGS", "CXXFLAGS", "CPPFLAGS", "LDFLAGS", "PYTHON", "SDKROOT", "DEVELOPER_DIR", "MACOSX_DEPLOYMENT_TARGET", "INCLUDE", "LIB", "LIBPATH"]);
+const BUILD_PREFIXES = ["GYP_", "VSINSTALLDIR", "VCINSTALLDIR", "VCTOOLS", "VSCMD_", "VS1", "VISUALSTUDIO", "WINDOWSSDK", "UNIVERSALCRT", "UCRT"];
+/**
+ * The variables the person running diffninja chose to pass to npm as well, named in
+ * DIFFNINJA_NPM_ENV (for example `NPM_TOKEN,NODE_AUTH_TOKEN`). A private registry whose
+ * `.npmrc` reads its token from the environment answers 401 without it. Names only. Anything
+ * else is refused without being echoed, because what was written there may be the secret itself.
+ */
+function chosenNames(env) {
+    const names = (env["DIFFNINJA_NPM_ENV"] ?? "").split(",").map((name) => name.trim()).filter((name) => name !== "");
+    if (names.some((name) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))) {
+        throw new Error("DIFFNINJA_NPM_ENV must list only environment variable names separated by commas, such as NPM_TOKEN,NODE_AUTH_TOKEN.");
+    }
+    return new Set(names.map((name) => name.toUpperCase()));
+}
+/** Compared without regard to case: Windows spells `Path`, `ComSpec` and `SystemRoot` its own way. */
+export function npmEnvironment(env = process.env, extra = {}, options = {}) {
+    const chosen = chosenNames(env);
+    const out = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        const upper = name.toUpperCase();
+        const forBuild = options.build === true && (BUILD_KEPT.has(upper) || BUILD_PREFIXES.some((prefix) => upper.startsWith(prefix)));
+        if (KEPT.has(upper) || upper.startsWith("NPM_CONFIG_") || upper.startsWith("LC_") || forBuild || chosen.has(upper))
+            out[name] = value;
+    }
+    return { ...out, ...extra };
+}
+/**
+ * The shell Windows runs a `.cmd` shim with, when no npm JS entry point can be
+ * found. ComSpec is used only when it is an absolute path to `cmd.exe`; anything
+ * else in that variable would otherwise be written into an agent's config and run
+ * every time the agent starts.
+ */
+export function windowsShell(env = process.env) {
+    const candidate = env["ComSpec"] ?? env["COMSPEC"];
+    return candidate !== undefined && /[\\/]cmd\.exe$/i.test(candidate) && (isAbsolute(candidate) || /^[A-Za-z]:[\\/]/.test(candidate)) ? candidate : "cmd.exe";
+}