diffninja 0.3.2 → 0.4.0

package/dist/review/github.js

@@ -19,6 +19,7 @@
  * - One review per session. An ambiguous write marks the session `unknown`,
  *   never retried; only an exact match found on GitHub resolves it.
  */
+import { resolveExecutable } from "../executables.js";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 /* ---------------------------------------------------------------- gh process */
@@ -42,9 +43,13 @@ export class GhCommandError extends Error {
         this.stderr = stderr;
     }
 }
-/** No prompt, no pager, no update notice, and never a host other than github.com. */
-function ghEnvironment() {
-    return { ...process.env, GH_HOST: GITHUB_HOST, GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", GH_PAGER: "cat", NO_COLOR: "1" };
+/**
+ * No prompt, no pager, no update notice, no usage telemetry (gh reports each
+ * command, its flag names, a device id and which agent runs it to GitHub unless
+ * told not to), and never a host other than github.com.
+ */
+export function ghEnvironment() {
+    return { ...process.env, GH_HOST: GITHUB_HOST, GH_PROMPT_DISABLED: "1", GH_NO_UPDATE_NOTIFIER: "1", GH_PAGER: "cat", NO_COLOR: "1", GH_TELEMETRY: "false", DO_NOT_TRACK: "1" };
 }
 /** Runs the real `gh` with an explicit argv (never a shell) and a hard deadline. */
 export function ghCliRunner() {
@@ -70,7 +75,15 @@ export function ghCliRunner() {
                 }
                 reject(new GhCommandError(firstLine(stderr) || firstLine(stdout) || "gh failed", stdout, stderr));
             };
-            const child = execFile("gh", [...invocation.args], {
+            let ghPath;
+            try {
+                ghPath = resolveExecutable("gh");
+            }
+            catch {
+                reject(new GhCommandError("gh was not found", "", ""));
+                return;
+            }
+            const child = execFile(ghPath, [...invocation.args], {
                 timeout: invocation.timeoutMs,
                 killSignal: "SIGKILL",
                 maxBuffer: GH_OUTPUT_LIMIT,
@@ -143,6 +156,39 @@ function githubBodyError(message) {
         return new Error(AUTHORIZATION_FAILURE);
     return new Error(`GitHub rejected the request: ${cleaned}`);
 }
+function failureKind(error) {
+    const detail = error.message;
+    const status = httpStatus(error);
+    if (status === 408 || /timed out|timeout/i.test(detail))
+        return "timeout";
+    if (/was not found/i.test(detail) && status === null)
+        return "gh-missing";
+    if (/unknown json field|unknown flag|unknown shorthand|unknown command/i.test(detail))
+        return "gh-outdated";
+    if (status === 401 || /bad credentials|not logged in|gh auth login|authentication required/i.test(detail))
+        return "signed-out";
+    if (status === 403 || /resource not accessible|forbidden|must have push|not authorized|insufficient/i.test(detail))
+        return "forbidden";
+    if (status === 404 || /could not resolve to a (?:node|pull ?request)|pull request was not found/i.test(detail))
+        return "not-found";
+    if (status !== null && status >= 400 && status < 500)
+        return "rejected";
+    // A GraphQL refusal is an HTTP 200 whose body carries `errors`, so gh names no status.
+    if (status === null && graphqlErrorsIn(error.stdout))
+        return "refused";
+    if (githubErrorText(error.stdout) !== null || (status !== null && status >= 500))
+        return "server";
+    if (/connection refused|no such host|name resolution|network is unreachable|unexpected EOF|TLS handshake|proxyconnect/i.test(detail))
+        return "unreachable";
+    return "other";
+}
+function graphqlErrorsIn(stdout) {
+    const decoded = tryParseJson(stdout);
+    if (!isGhObject(decoded))
+        return false;
+    const errors = decoded["errors"];
+    return Array.isArray(errors) && errors.length > 0;
+}
 /**
  * Map a raw `gh` failure to a safe, user-facing error. Read failures stay
  * neutral — no failure text claims the pull request was untouched, because when
@@ -153,37 +199,29 @@ function githubBodyError(message) {
 function classifyGhFailure(rawError, subject) {
     const error = asGhCommandError(rawError);
     const detail = error.message;
-    const status = httpStatus(error);
     const github = githubErrorText(error.stdout);
-    if (status === 408 || /timed out|timeout/i.test(detail)) {
-        return new Error("gh did not answer in time; the request did not complete. Check the network, then try again.");
-    }
-    if (/was not found/i.test(detail) && status === null)
-        return new Error(`The GitHub CLI (gh) was not found on PATH. Install gh ${MIN_GH_VERSION} or newer from https://cli.github.com, then run \`gh auth login --hostname github.com\` and try again.`);
-    if (/unknown json field|unknown flag|unknown shorthand|unknown command/i.test(detail)) {
-        return new Error(`The installed gh does not support the flags diffninja needs. Update gh to ${MIN_GH_VERSION} or newer.`);
-    }
-    if (status === 401 || /bad credentials|not logged in|gh auth login|authentication required/i.test(detail))
-        return new Error(AUTH_FAILURE);
-    if (status === 403 || /resource not accessible|forbidden|must have push|not authorized|insufficient/i.test(detail)) {
+    switch (failureKind(error)) {
+        case "timeout": return new Error("gh did not answer in time; the request did not complete. Check the network, then try again.");
+        case "gh-missing": return new Error(`The GitHub CLI (gh) was not found on PATH. Install gh ${MIN_GH_VERSION} or newer from https://cli.github.com, then run \`gh auth login --hostname github.com\` and try again.`);
+        case "gh-outdated": return new Error(`The installed gh does not support the flags diffninja needs. Update gh to ${MIN_GH_VERSION} or newer.`);
+        case "signed-out": return new Error(AUTH_FAILURE);
         // A 403 has many causes; GitHub's own text is what tells them apart.
-        return new Error(github === null ? AUTHORIZATION_FAILURE : `${AUTHORIZATION_FAILURE} GitHub said: ${github}.`);
-    }
-    if (status === 404 || /could not resolve to a pull ?request|pull request was not found/i.test(detail))
-        return new Error(NOT_FOUND_FAILURE);
-    if (status !== null && status >= 400 && status < 500) {
-        const what = subject === "review" ? "GitHub rejected the review" : "The request was rejected";
-        return new Error(github === null ? `${what}: ${sanitizeText(detail)}` : `${what}: ${github}`);
-    }
-    if (github !== null) {
-        return new Error(`GitHub returned a server error; the request did not complete: ${github}. Try again in a moment.`);
-    }
-    if (status !== null && status >= 500)
-        return new Error("GitHub returned a server error; the request did not complete. Try again in a moment.");
-    if (/connection refused|no such host|name resolution|network is unreachable|unexpected EOF|TLS handshake|proxyconnect/i.test(detail)) {
-        return new Error("diffninja could not reach GitHub; the request did not complete. Check the network and try again.");
+        case "forbidden": return new Error(github === null ? AUTHORIZATION_FAILURE : `${AUTHORIZATION_FAILURE} GitHub said: ${github}.`);
+        case "not-found": return new Error(NOT_FOUND_FAILURE);
+        case "rejected": {
+            const what = subject === "review" ? "GitHub rejected the review" : subject === "viewed" ? "GitHub rejected the Viewed mark" : "The request was rejected";
+            // The Viewed mark shows GitHub's named message or nothing of its own: never a line of gh's stderr.
+            if (github === null)
+                return new Error(subject === "viewed" ? `${what}.` : `${what}: ${sanitizeText(detail)}`);
+            return new Error(`${what}: ${github}`);
+        }
+        case "refused": return new Error(`GitHub refused the ${subject === "viewed" ? "Viewed mark" : "request"}: ${github ?? "no reason given"}.`);
+        case "server": return new Error(github === null
+            ? "GitHub returned a server error; the request did not complete. Try again in a moment."
+            : `GitHub returned a server error; the request did not complete: ${github}. Try again in a moment.`);
+        case "unreachable": return new Error("diffninja could not reach GitHub; the request did not complete. Check the network and try again.");
+        case "other": return new Error("The gh command failed; the request did not complete.");
     }
-    return new Error("The gh command failed; the request did not complete.");
 }
 function isGhObject(value) {
     // JSON.parse only produces plain objects, arrays, and primitives, so plain
@@ -647,6 +685,40 @@ const VIEW_FIELDS = [
     "url", "id", "number", "state", "title", "body", "baseRefOid", "headRefOid", "isCrossRepository",
     "headRepository", "headRepositoryOwner", "baseRefName", "headRefName",
 ].join(",");
+/**
+ * The only GraphQL documents diffninja sends, fixed text. A file path, a cursor
+ * and the pull request's node id travel as separate `-f` variables and are never
+ * placed in a document.
+ */
+export const VIEWED_FILES_QUERY = "query($pullRequestId: ID!, $after: String) { node(id: $pullRequestId) { ... on PullRequest { files(first: 100, after: $after) { nodes { path viewerViewedState } pageInfo { hasNextPage endCursor } } } } }";
+export const MARK_VIEWED_MUTATION = "mutation($pullRequestId: ID!, $path: String!) { markFileAsViewed(input: { pullRequestId: $pullRequestId, path: $path }) { clientMutationId } }";
+export const UNMARK_VIEWED_MUTATION = "mutation($pullRequestId: ID!, $path: String!) { unmarkFileAsViewed(input: { pullRequestId: $pullRequestId, path: $path }) { clientMutationId } }";
+const VIEWED_MUTATIONS = {
+    mark: { query: MARK_VIEWED_MUTATION, field: "markFileAsViewed" },
+    unmark: { query: UNMARK_VIEWED_MUTATION, field: "unmarkFileAsViewed" },
+};
+/** GitHub lists at most 3,000 files of a pull request; at 100 a page this is far past that. */
+const MAX_VIEWED_PAGES = 40;
+const UNFINISHED_MARK = "The Viewed mark did not finish, so GitHub may or may not have recorded it. Load the pull request again to read GitHub's marks.";
+/** A failure of these kinds means GitHub answered the write with a refusal, or gh never ran it. */
+const DEFINITE_FAILURES = new Set(["gh-missing", "gh-outdated", "signed-out", "forbidden", "not-found", "rejected", "refused"]);
+/** Fixed reasons a read of the Viewed marks failed. GitHub's own text is never among them. */
+const VIEWED_READ_REASON = {
+    "timeout": "gh did not answer in time",
+    "gh-missing": "the GitHub CLI was not found",
+    "gh-outdated": "the installed gh is too old",
+    "signed-out": "gh is not signed in to GitHub",
+    "forbidden": "the gh account may not read viewed marks",
+    "not-found": "GitHub did not find the pull request",
+    "rejected": "GitHub rejected the request",
+    "refused": "GitHub refused the request",
+    "server": "GitHub returned a server error",
+    "unreachable": "GitHub could not be reached",
+    "other": "gh failed",
+};
+/** A read of the Viewed marks that cannot be trusted; its message is a fixed sentence fragment. */
+class ViewedUnreadable extends Error {
+}
 const MAX_REVIEW_CHARS = 65_536;
 const MAX_COMMENT_CHARS = 65_536;
 const MAX_COMMENTS = 100;
@@ -691,6 +763,7 @@ export class ConnectedReview {
     /** Review ids that already existed before this session's write attempt. */
     preexistingReviewIds = new Set();
     queue = Promise.resolve();
+    viewedSync;
     constructor(deps = {}) {
         this.runner = deps.runner ?? ghCliRunner();
         this.timeoutMs = deps.timeoutMs ?? GH_TIMEOUT_MS;
@@ -702,6 +775,7 @@ export class ConnectedReview {
             status: this.status,
             receipt: this.receipt,
             message: this.message,
+            viewed: this.viewedState(),
         };
     }
     /** Canonical patch from the last successfully bound snapshot, for static export. */
@@ -722,6 +796,10 @@ export class ConnectedReview {
     async reconcile() {
         return this.serialize(() => this.runReconcile());
     }
+    /** Mark one changed file of the loaded snapshot Viewed, or not, on GitHub. */
+    async setViewed(input) {
+        return this.serialize(() => this.runSetViewed(input));
+    }
     /** Run `work` after everything already queued; failures never break the chain. */
     serialize(work) {
         const result = this.queue.then(work, work);
@@ -794,7 +872,9 @@ export class ConnectedReview {
         const canonical = parsePullUrl(url);
         if (canonical.number !== number)
             throw new Error("GitHub's pull request metadata is inconsistent; refusing to review it.");
+        const nodeId = textField(payload, "id");
         return {
+            nodeId: nodeId === null || nodeId === "" ? null : nodeId,
             url: canonical.url,
             owner: canonical.owner,
             repo: canonical.repo,
@@ -871,7 +951,8 @@ export class ConnectedReview {
         const reason = canonical.problem ?? reviewabilityProblem(meta);
         if (reason !== null)
             snapshot.unavailableReason = reason;
-        return { snapshot, diff: rawDiff, anchors: canonical.anchors, note: reason === null ? forkNote(meta) : null };
+        const filePaths = (listedFiles(listing) ?? []).map((file) => file.filename);
+        return { snapshot, diff: rawDiff, anchors: canonical.anchors, note: reason === null ? forkNote(meta) : null, nodeId: meta.nodeId, filePaths };
     }
     /**
      * One PR and one account per session: the first pull request that loads at all
@@ -900,10 +981,12 @@ export class ConnectedReview {
         await this.ensureGhVersion();
         const identity = await this.readIdentity();
         const read = await this.readSnapshot(target);
+        const viewed = read.snapshot.unavailableReason === undefined ? await this.readViewed(read) : undefined;
         this.identity = identity;
         this.snapshot = read.snapshot;
         this.diff = read.diff;
         this.anchors = read.anchors;
+        this.viewedSync = viewed;
         this.previewed = undefined;
         this.message = read.snapshot.unavailableReason ?? read.note ?? undefined;
         this.status = read.snapshot.unavailableReason === undefined ? "ready" : "empty";
@@ -950,6 +1033,89 @@ export class ConnectedReview {
         await this.postReview(snapshot, payload);
         return this.getState();
     }
+    /** One `gh api graphql` run: a fixed document plus its variables, each a separate raw `-f` argument. */
+    graphql(query, variables) {
+        const args = ["api", "--hostname", GITHUB_HOST, "graphql", "-f", `query=${query}`];
+        for (const [name, value] of Object.entries(variables))
+            args.push("-f", `${name}=${value}`);
+        return this.runner.run({ args, timeoutMs: this.timeoutMs });
+    }
+    /** The Viewed marks for the files of a fresh snapshot; a read that fails costs the sync, never the load. */
+    async readViewed(read) {
+        const pullRequestId = read.nodeId;
+        if (pullRequestId === null)
+            return { available: false, reason: "gh did not report the pull request's GitHub id" };
+        try {
+            const marks = await this.readViewedMarks(pullRequestId);
+            return { available: true, pullRequestId, files: new Map(read.filePaths.map((path) => [path, marks.get(path) === true])) };
+        }
+        catch (error) {
+            if (error instanceof ViewedUnreadable)
+                return { available: false, reason: error.message };
+            return { available: false, reason: VIEWED_READ_REASON[failureKind(asGhCommandError(error instanceof Error ? error : new Error("gh failed")))] };
+        }
+    }
+    /** Path to viewed, over every page of the pull request's files; VIEWED counts, UNVIEWED and DISMISSED do not. */
+    async readViewedMarks(pullRequestId) {
+        const marks = new Map();
+        let after;
+        for (let page = 0; page < MAX_VIEWED_PAGES; page++) {
+            const result = await this.graphql(VIEWED_FILES_QUERY, after === undefined ? { pullRequestId } : { pullRequestId, after });
+            const next = readViewedPage(result.stdout, marks);
+            if (next === null)
+                return marks;
+            after = next;
+        }
+        throw new ViewedUnreadable("the pull request has more files than diffninja reads");
+    }
+    async runSetViewed(input) {
+        const snapshot = this.snapshot;
+        if (snapshot === undefined)
+            throw new Error("Load a pull request before marking a file viewed.");
+        if (input.snapshotId !== snapshot.id) {
+            throw new Error("This mark belongs to a different version of the pull request. Reload it and try again.");
+        }
+        const sync = this.viewedSync;
+        if (sync === undefined || !sync.available) {
+            throw new Error(`Viewed marks are not synced with GitHub for this pull request${sync === undefined ? "" : ` (${sync.reason})`}.`);
+        }
+        if (!sync.files.has(input.path))
+            throw new Error("That file is not one of this pull request's changed files.");
+        // A mark has no commit of its own: GitHub applies it to the file as it is now. A push since the load
+        // would turn "every hunk I read" into "the file", so the head is read again first, as a submit does.
+        const meta = await this.readMetadata({ owner: snapshot.owner, repo: snapshot.repo, number: snapshot.number, url: snapshot.url });
+        if (meta.baseSha !== snapshot.baseSha || meta.headSha !== snapshot.headSha) {
+            throw new Error("The pull request changed since it was loaded. Load it again, then mark the file.");
+        }
+        const mutation = input.viewed ? VIEWED_MUTATIONS.mark : VIEWED_MUTATIONS.unmark;
+        let stdout;
+        try {
+            ({ stdout } = await this.graphql(mutation.query, { pullRequestId: sync.pullRequestId, path: input.path }));
+        }
+        catch (error) {
+            const failure = asGhCommandError(error instanceof Error ? error : new Error("gh failed"));
+            if (DEFINITE_FAILURES.has(failureKind(failure)))
+                throw classifyGhFailure(failure, "viewed");
+            throw this.unfinishedMark();
+        }
+        if (!confirmsMutation(stdout, mutation.field))
+            throw this.unfinishedMark();
+        sync.files.set(input.path, input.viewed);
+        return { path: input.path, viewed: input.viewed };
+    }
+    /** A write that may or may not have landed: the marks stay unread until the pull request is loaded again. */
+    unfinishedMark() {
+        this.viewedSync = { available: false, reason: "the last Viewed mark did not finish" };
+        return new Error(UNFINISHED_MARK);
+    }
+    viewedState() {
+        const sync = this.viewedSync;
+        if (sync === undefined)
+            return undefined;
+        if (!sync.available)
+            return { available: false, reason: sync.reason };
+        return { available: true, files: [...sync.files].map(([path, viewed]) => ({ path, viewed })) };
+    }
     async postReview(snapshot, payload) {
         this.status = "submitting";
         this.message = "Submitting the review to GitHub.";
@@ -1142,6 +1308,41 @@ export class ConnectedReview {
         throw new Error(`The comment on ${path}:${line} (${side}) does not match a line of this pull request's diff. Comment on an added line on the right, a deleted line on the left, or a context line.`);
     }
 }
+/**
+ * Add one page of `files { nodes { path viewerViewedState } }` to `marks` and
+ * return the cursor of the next page, or null after the last. Anything that is
+ * not that shape rejects the whole read: a mark cannot be guessed.
+ */
+function readViewedPage(stdout, marks) {
+    const unreadable = new ViewedUnreadable("GitHub's answer about viewed files was not readable");
+    const decoded = tryParseJson(stdout);
+    const files = objectField(objectField(objectField(isGhObject(decoded) ? decoded : null, "data"), "node"), "files");
+    const nodes = files === null ? null : files["nodes"];
+    const pageInfo = objectField(files, "pageInfo");
+    const more = booleanField(pageInfo, "hasNextPage");
+    if (!Array.isArray(nodes) || more === null)
+        throw unreadable;
+    for (const node of nodes) {
+        const path = isGhObject(node) ? textField(node, "path") : null;
+        const state = isGhObject(node) ? textField(node, "viewerViewedState") : null;
+        if (path === null || state === null)
+            throw unreadable;
+        marks.set(path, state === "VIEWED");
+    }
+    if (!more)
+        return null;
+    const cursor = textField(pageInfo, "endCursor");
+    if (cursor === null || cursor === "")
+        throw unreadable;
+    return cursor;
+}
+/** A mutation is confirmed only by its own field in `data` and no `errors`. */
+function confirmsMutation(stdout, field) {
+    const decoded = tryParseJson(stdout);
+    if (!isGhObject(decoded) || graphqlErrorsIn(stdout))
+        return false;
+    return objectField(objectField(decoded, "data"), field) !== null;
+}
 function compareVersions(left, right) {
     const a = left.split(".").map(Number);
     const b = right.split(".").map(Number);

package/dist/review/grammars-command.d.ts

@@ -0,0 +1,12 @@
+import { type GrammarStatus, type InstalledGrammars } from "../languages/grammars.js";
+export declare const grammarsHelp = "diffninja grammars. Downloads grammar code through npm, and only when you run it.\n\n  diffninja grammars install [--build] [--dry-run]\n      Install the tree-sitter grammars call flows need for languages other than\n      JavaScript and TypeScript (Python, Go, Java, Rust, C, C++, C#, Ruby, PHP,\n      Swift, Scala, Bash, Lua, Zig, Elixir, Haskell, OCaml, Solidity). Exact\n      versions, checked against the sha512 of every tarball in the lock that ships\n      with this diffninja, and no install script of any package is run.\n      --build also compiles the Kotlin and Perl grammars, which ship no prebuilt\n      binary: that runs their install script (node-gyp) and needs Python and a C/C++\n      compiler.\n  diffninja grammars status\n      Show what is installed and where.\n\nReviews never download or build anything: without these grammars, files in those\nlanguages are skipped by call flows and the review says so.\n";
+export interface GrammarsDependencies {
+    install: (options: {
+        cacheDir?: string;
+        build?: boolean;
+    }) => InstalledGrammars;
+    status: () => GrammarStatus;
+    log: (line: string) => void;
+}
+/** `diffninja grammars ...`; throws a message-only Error for bad usage. */
+export declare function runGrammars(args: readonly string[], deps?: GrammarsDependencies): void;

package/dist/review/grammars-command.js

@@ -0,0 +1,60 @@
+import { parseArgs } from "node:util";
+import { GRAMMAR_PINS } from "../languages/grammar-lock.js";
+import { grammarCacheDir, grammarStatus, installPinnedGrammars } from "../languages/grammars.js";
+export const grammarsHelp = `diffninja grammars. Downloads grammar code through npm, and only when you run it.
+
+  diffninja grammars install [--build] [--dry-run]
+      Install the tree-sitter grammars call flows need for languages other than
+      JavaScript and TypeScript (Python, Go, Java, Rust, C, C++, C#, Ruby, PHP,
+      Swift, Scala, Bash, Lua, Zig, Elixir, Haskell, OCaml, Solidity). Exact
+      versions, checked against the sha512 of every tarball in the lock that ships
+      with this diffninja, and no install script of any package is run.
+      --build also compiles the Kotlin and Perl grammars, which ship no prebuilt
+      binary: that runs their install script (node-gyp) and needs Python and a C/C++
+      compiler.
+  diffninja grammars status
+      Show what is installed and where.
+
+Reviews never download or build anything: without these grammars, files in those
+languages are skipped by call flows and the review says so.
+`;
+const real = { install: installPinnedGrammars, status: () => grammarStatus(), log: (line) => console.log(line) };
+/** `diffninja grammars ...`; throws a message-only Error for bad usage. */
+export function runGrammars(args, deps = real) {
+    const [action, ...rest] = args;
+    if (action === undefined || action === "--help" || action === "-h" || action === "help") {
+        deps.log(grammarsHelp);
+        return;
+    }
+    const { values, positionals } = parseArgs({ args: rest, options: { "dry-run": { type: "boolean" }, build: { type: "boolean" }, help: { type: "boolean" } }, strict: true, allowPositionals: true });
+    if (values.help) {
+        deps.log(grammarsHelp);
+        return;
+    }
+    if (positionals.length > 0)
+        throw new Error(`grammars ${action} takes no arguments. Use --help.`);
+    if (action === "status") {
+        const status = deps.status();
+        deps.log(`Cache: ${status.cacheDir}${status.trusted ? "" : " (nothing installed by this diffninja yet)"}`);
+        for (const entry of status.packages)
+            deps.log(`  ${entry.installed ? "installed" : "missing  "}  ${entry.name}@${entry.version}${entry.installed || !entry.needsBuild ? "" : "  (needs --build)"}`);
+        if (status.packages.some((entry) => !entry.installed))
+            deps.log("Run `diffninja grammars install` (add --build for the ones marked) to add the missing ones.");
+        return;
+    }
+    if (action !== "install")
+        throw new Error(`Unknown grammars command "${action}". Use install or status.`);
+    const names = Object.entries(GRAMMAR_PINS).map(([name, version]) => `${name}@${version}`);
+    const build = values.build === true;
+    if (values["dry-run"]) {
+        deps.log(`Would install into ${grammarCacheDir()} (npm ci from the lock shipped with diffninja, install scripts off${build ? ", then a source build of the Kotlin and Perl grammars" : ""}):`);
+        for (const name of names)
+            deps.log(`  ${name}`);
+        return;
+    }
+    deps.log(`Installing ${names.length} pinned grammars into ${grammarCacheDir()} (integrity-checked, install scripts off${build ? "; compiling Kotlin and Perl" : ""})...`);
+    const installed = deps.install({ build });
+    for (const entry of installed.packages)
+        deps.log(`  ${entry.name}@${entry.version}`);
+    deps.log("Done. The next review uses them; nothing needs restarting.");
+}

package/dist/review/hidden-characters.d.ts

@@ -0,0 +1,31 @@
+/** Matches one hidden character at a time, so each match is one code point to mark. */
+export declare const HIDDEN_CHARACTER_SOURCE = "[\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u206F\\u{E0000}-\\u{E0FFF}]|(?<!(?![\\x00-\\x7F\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u206F\\u{E0000}-\\u{E0FFF}\\u00AD\\u034F\\u115F\\u1160\\u17B4\\u17B5\\u180B-\\u180F\\u200B-\\u200D\\u2060-\\u2065\\u2800\\u3164\\uFE00-\\uFE0F\\uFFA0\\uFFF0-\\uFFF8\\u{1BCA0}-\\u{1BCA3}\\u{1D173}-\\u{1D17A}\\uFEFF]|\\p{Default_Ignorable_Code_Point})[\\p{L}\\p{M}\\p{N}\\p{S}\\p{P}])[\\u00AD\\u034F\\u115F\\u1160\\u17B4\\u17B5\\u180B-\\u180F\\u200B-\\u200D\\u2060-\\u2065\\u2800\\u3164\\uFE00-\\uFE0F\\uFFA0\\uFFF0-\\uFFF8\\u{1BCA0}-\\u{1BCA3}\\u{1D173}-\\u{1D17A}](?!(?![\\x00-\\x7F\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u206F\\u{E0000}-\\u{E0FFF}\\u00AD\\u034F\\u115F\\u1160\\u17B4\\u17B5\\u180B-\\u180F\\u200B-\\u200D\\u2060-\\u2065\\u2800\\u3164\\uFE00-\\uFE0F\\uFFA0\\uFFF0-\\uFFF8\\u{1BCA0}-\\u{1BCA3}\\u{1D173}-\\u{1D17A}\\uFEFF]|\\p{Default_Ignorable_Code_Point})[\\p{L}\\p{M}\\p{N}\\p{S}\\p{P}])|(?<!(?![\\x00-\\x7F\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u206F\\u{E0000}-\\u{E0FFF}\\u00AD\\u034F\\u115F\\u1160\\u17B4\\u17B5\\u180B-\\u180F\\u200B-\\u200D\\u2060-\\u2065\\u2800\\u3164\\uFE00-\\uFE0F\\uFFA0\\uFFF0-\\uFFF8\\u{1BCA0}-\\u{1BCA3}\\u{1D173}-\\u{1D17A}\\uFEFF]|\\p{Default_Ignorable_Code_Point})[\\p{L}\\p{M}\\p{N}\\p{S}\\p{P}]|(?:^|\\n)[+\\- ])\\uFEFF(?!(?![\\x00-\\x7F\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u206F\\u{E0000}-\\u{E0FFF}\\u00AD\\u034F\\u115F\\u1160\\u17B4\\u17B5\\u180B-\\u180F\\u200B-\\u200D\\u2060-\\u2065\\u2800\\u3164\\uFE00-\\uFE0F\\uFFA0\\uFFF0-\\uFFF8\\u{1BCA0}-\\u{1BCA3}\\u{1D173}-\\u{1D17A}\\uFEFF]|\\p{Default_Ignorable_Code_Point})[\\p{L}\\p{M}\\p{N}\\p{S}\\p{P}])";
+/**
+ * Every character of both tiers, with no lookaround, for a browser too old to compile
+ * {@link HIDDEN_CHARACTER_SOURCE} (lookbehind arrived in Safari 16.4). It marks the
+ * joiners of emoji and Persian text too, which reads worse but shows everything.
+ */
+export declare const HIDDEN_CHARACTER_FALLBACK_SOURCE = "[\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u206F\\u{E0000}-\\u{E0FFF}\\u00AD\\u034F\\u115F\\u1160\\u17B4\\u17B5\\u180B-\\u180F\\u200B-\\u200D\\u2060-\\u2065\\u2800\\u3164\\uFE00-\\uFE0F\\uFFA0\\uFFF0-\\uFFF8\\u{1BCA0}-\\u{1BCA3}\\u{1D173}-\\u{1D17A}\\uFEFF]";
+/** The text with each hidden character replaced by a visible `⟦U+XXXX⟧` marker. */
+export declare function visibleControls(text: string): string;
+/** The distinct hidden characters in the text, as sorted code points. */
+export declare function hiddenControlsIn(text: string): string[];
+/**
+ * A copy of a JSON value with every string in it, keys included, passed
+ * through {@link visibleControls}. Every review result goes through it on its
+ * way to the agent: the pull request's words are written by other people, and
+ * a hidden character would carry text or reorder it without the reader seeing
+ * it. Each string is marked on its own, not the JSON text as a whole, so the
+ * start of a string and its line breaks read the way they do in the string
+ * itself. The literals are found by scanning for quotes, not by a regular
+ * expression, which overflows its stack on a string of a few million
+ * characters.
+ */
+export declare function withVisibleControls<Payload>(payload: Payload): Payload;
+interface ChangedText {
+    readonly file: string;
+    readonly diff: string;
+}
+/** For each file, the distinct hidden characters on lines the change adds or removes (not on context it merely shows). */
+export declare function hiddenControlsByFile(units: readonly ChangedText[]): Map<string, string[]>;
+export {};

package/dist/review/hidden-characters.js

@@ -0,0 +1,113 @@
+/**
+ * Characters that change how text is drawn or that draw nothing at all. In code
+ * they let what a reviewer reads differ from what a compiler reads (Trojan
+ * Source, CVE-2021-42574), and in prose they hide instructions. A review tool
+ * shows them as visible markers instead of letting the browser act on them.
+ *
+ * Every Unicode bidirectional control (the left-to-right and right-to-left marks,
+ * embeddings, overrides and isolates, and the Arabic letter mark) and the whole
+ * plane-14 block (the tag characters, the supplementary variation selectors, and
+ * the unassigned code points between them) are always shown. The
+ * other invisible characters (joiners, zero-width spaces, fillers, variation
+ * selectors, marks) are also how emoji, Persian, Indic, Mongolian, and Hangul
+ * text is written, so one is shown only where no such script surrounds it:
+ * neither neighbour is a visible character of a script, so a run of them
+ * between ASCII letters is shown whole. A byte order mark right after a diff
+ * line's `+`, `-`, or space is left alone; anywhere else, a path or an id
+ * included, it is shown.
+ */
+const ALWAYS = "\\u061C\\u200E\\u200F\\u202A-\\u202E\\u2066-\\u206F\\u{E0000}-\\u{E0FFF}";
+const BESIDE_ASCII = "\\u00AD\\u034F\\u115F\\u1160\\u17B4\\u17B5\\u180B-\\u180F\\u200B-\\u200D\\u2060-\\u2065\\u2800\\u3164\\uFE00-\\uFE0F\\uFFA0\\uFFF0-\\uFFF8\\u{1BCA0}-\\u{1BCA3}\\u{1D173}-\\u{1D17A}";
+const BYTE_ORDER_MARK = "\\uFEFF";
+/**
+ * One visible character of a script: a non-ASCII letter, mark, digit, symbol,
+ * or punctuation that is not itself invisible. A space such as U+00A0 is not
+ * one, so it cannot shield a hidden character in ASCII code.
+ */
+const SCRIPT = `(?![\\x00-\\x7F${ALWAYS}${BESIDE_ASCII}${BYTE_ORDER_MARK}]|\\p{Default_Ignorable_Code_Point})[\\p{L}\\p{M}\\p{N}\\p{S}\\p{P}]`;
+/** Matches one hidden character at a time, so each match is one code point to mark. */
+export const HIDDEN_CHARACTER_SOURCE = `[${ALWAYS}]|(?<!${SCRIPT})[${BESIDE_ASCII}](?!${SCRIPT})|(?<!${SCRIPT}|(?:^|\\n)[+\\- ])${BYTE_ORDER_MARK}(?!${SCRIPT})`;
+/**
+ * Every character of both tiers, with no lookaround, for a browser too old to compile
+ * {@link HIDDEN_CHARACTER_SOURCE} (lookbehind arrived in Safari 16.4). It marks the
+ * joiners of emoji and Persian text too, which reads worse but shows everything.
+ */
+export const HIDDEN_CHARACTER_FALLBACK_SOURCE = `[${ALWAYS}${BESIDE_ASCII}${BYTE_ORDER_MARK}]`;
+const hidden = new RegExp(HIDDEN_CHARACTER_SOURCE, "gu");
+const anyHidden = new RegExp(HIDDEN_CHARACTER_SOURCE, "u");
+/** `U+202E`, at least four hex digits. */
+function codePoint(character) {
+    return `U+${(character.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, "0")}`;
+}
+/** The text with each hidden character replaced by a visible `⟦U+XXXX⟧` marker. */
+export function visibleControls(text) {
+    return text.replace(hidden, (character) => `⟦${codePoint(character)}⟧`);
+}
+/** Whether the text holds a character {@link visibleControls} would mark. */
+function hasHiddenControls(text) {
+    return anyHidden.test(text);
+}
+/** The distinct hidden characters in the text, as sorted code points. */
+export function hiddenControlsIn(text) {
+    const points = new Set();
+    for (const match of text.matchAll(hidden))
+        points.add(codePoint(match[0]));
+    return [...points].sort();
+}
+/** Whether the quote at `index` of a JSON text is escaped: an odd run of backslashes precedes it. */
+function escapedAt(json, index) {
+    let backslashes = 0;
+    while (json[index - 1 - backslashes] === "\\")
+        backslashes += 1;
+    return backslashes % 2 === 1;
+}
+/**
+ * A copy of a JSON value with every string in it, keys included, passed
+ * through {@link visibleControls}. Every review result goes through it on its
+ * way to the agent: the pull request's words are written by other people, and
+ * a hidden character would carry text or reorder it without the reader seeing
+ * it. Each string is marked on its own, not the JSON text as a whole, so the
+ * start of a string and its line breaks read the way they do in the string
+ * itself. The literals are found by scanning for quotes, not by a regular
+ * expression, which overflows its stack on a string of a few million
+ * characters.
+ */
+export function withVisibleControls(payload) {
+    const json = JSON.stringify(payload);
+    // Whatever one string of it would mark, the JSON text marks too: escapes are ASCII.
+    if (!hasHiddenControls(json))
+        return payload;
+    const parts = [];
+    let copied = 0;
+    for (let open = json.indexOf('"'); open >= 0;) {
+        let close = json.indexOf('"', open + 1);
+        while (escapedAt(json, close))
+            close = json.indexOf('"', close + 1);
+        const literal = json.slice(open, close + 1);
+        if (hasHiddenControls(literal)) {
+            // SAFETY: a JSON string literal parses to a string.
+            parts.push(json.slice(copied, open), JSON.stringify(visibleControls(JSON.parse(literal))));
+            copied = close + 1;
+        }
+        open = json.indexOf('"', close + 1);
+    }
+    parts.push(json.slice(copied));
+    // SAFETY: only the contents of JSON strings changed, so the text parses to the same shape.
+    return JSON.parse(parts.join(""));
+}
+/** For each file, the distinct hidden characters on lines the change adds or removes (not on context it merely shows). */
+export function hiddenControlsByFile(units) {
+    const found = new Map();
+    for (const unit of units) {
+        for (const line of unit.diff.split("\n")) {
+            if (!line.startsWith("+") && !line.startsWith("-"))
+                continue;
+            for (const point of hiddenControlsIn(line)) {
+                const points = found.get(unit.file) ?? new Set();
+                points.add(point);
+                found.set(unit.file, points);
+            }
+        }
+    }
+    return new Map([...found].map(([file, points]) => [file, [...points].sort()]));
+}

package/dist/review/history.js

@@ -13,6 +13,7 @@
  * context. A shallow clone cuts history, and lines whose origin lies past the cut
  * are counted as unknown rather than attributed to the boundary commit.
  */
+import { resolveExecutable } from "../executables.js";
 import { execFileSync } from "node:child_process";
 import { posix } from "node:path";
 import { testLikeFile } from "./file-role.js";
@@ -52,7 +53,7 @@ const STOP_WORDS = new Set([
     "before", "after", "while", "without", "because", "through", "over", "under", "about", "again", "back", "other",
 ]);
 function git(cwd, args, input) {
-    return execFileSync("git", ["--no-replace-objects", "--no-pager", ...args], {
+    return execFileSync(resolveExecutable("git"), ["--no-replace-objects", "--no-pager", ...args], {
         cwd, input, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: GIT_TIMEOUT_MS, stdio: ["pipe", "pipe", "pipe"],
     });
 }
@@ -130,7 +131,10 @@ function hunkHistories(cwd, base, units) {
         let blame;
         try {
             const args = ranges(hunks.flatMap((hunk) => hunk.lines)).flatMap(([a, b]) => ["-L", `${a},${b}`]);
-            blame = parseBlame(git(cwd, ["blame", "--porcelain", ...args, base, "--", file]));
+            // --no-textconv: like `git diff` in input.ts, blame would otherwise run a textconv helper
+            // that the repository's config or attributes select. A git too old to know the option
+            // fails here and the file simply has no line history.
+            blame = parseBlame(git(cwd, ["blame", "--no-textconv", "--porcelain", ...args, base, "--", file]));
         }
         catch {
             // A file absent at the base (renamed or copied) has no line history here.
@@ -284,7 +288,7 @@ function readBlobs(cwd, rev, paths) {
     const out = new Map();
     if (paths.length === 0)
         return out;
-    const raw = execFileSync("git", ["--no-replace-objects", "cat-file", "--batch"], {
+    const raw = execFileSync(resolveExecutable("git"), ["--no-replace-objects", "cat-file", "--batch"], {
         cwd, input: paths.map((path) => `${rev}:${path}`).join("\n") + "\n", maxBuffer: 256 * 1024 * 1024, timeout: GIT_TIMEOUT_MS,
     });
     let offset = 0;