@expo/code-review-cli 0.6.0 → 0.8.0

package/build/core/context-file.js

@@ -0,0 +1,42 @@
+import { open } from "node:fs/promises";
+// @ref LLP 0007#ecr-ci-the-trusted-root-run [constrained-by] — a missing/oversized context file WARNs and continues in ci; never fails checks
+/**
+ * Hard read ceiling for a `--context-file`. The file is read once in the command
+ * layer, byte-bounded here, then head/tail capped again for the prompt
+ * (CONTEXT_FILE_MAX_CHARS in prompts.ts). This ceiling bounds the read itself so a
+ * multi-gigabyte path can't exhaust memory before the prompt cap ever applies.
+ */
+export const MAX_CONTEXT_FILE_BYTES = 1_048_576; // 1 MiB
+const READ_CHUNK_BYTES = 65_536;
+/**
+ * Read an external context file as UTF-8 text. Throws on a missing/unreadable path
+ * or one over MAX_CONTEXT_FILE_BYTES — the command layer decides whether that is
+ * fatal (`ecr review`) or a warn-and-continue (`ecr ci`). The ceiling is enforced
+ * DURING the read, not by a stat beforehand: special files (`/dev/zero`, proc
+ * entries) report a small or zero size but read without end, and a regular file
+ * can grow between a stat and the read. Invalid UTF-8 decodes lossily
+ * (replacement chars); control chars are stripped later by sanitizeUntrusted.
+ */
+export async function readContextFile(filePath) {
+    const handle = await open(filePath, "r");
+    try {
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const chunk = Buffer.alloc(READ_CHUNK_BYTES);
+            const { bytesRead } = await handle.read(chunk, 0, READ_CHUNK_BYTES);
+            if (bytesRead === 0) {
+                break;
+            }
+            total += bytesRead;
+            if (total > MAX_CONTEXT_FILE_BYTES) {
+                throw new Error(`context file too large (> 1 MiB): ${filePath}`);
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    finally {
+        await handle.close();
+    }
+}

package/build/core/coordinator.js

@@ -9,9 +9,9 @@ import { parseCoordinatorOutput } from "./schema.js";
 // cap is a backstop. It runs AFTER all passes, so this adds to the worst-case
 // serial chain — keep it within the CI job timeout (see review.ts / workflows).
 const COORDINATOR_TIMEOUT_MS = 10 * 60 * 1000;
-export async function coordinate(handle, config, metadata, agentFindings, coverageNotes = []) {
+export async function coordinate(handle, config, metadata, agentFindings, coverageNotes = [], stackManifest) {
     const system = buildCoordinatorSystem(config);
-    const text = buildCoordinatorTask(metadata, agentFindings, coverageNotes);
+    const text = buildCoordinatorTask(metadata, agentFindings, coverageNotes, stackManifest);
     const { value, cost, tokens, truncated, model } = await promptAndParse(handle, {
         agent: "coordinator",
         system,

package/build/core/diff.js

@@ -32,6 +32,7 @@ export function parseUnifiedDiff(diffText) {
     flush();
     return entries;
 }
+// @ref LLP 0004#unified-diff-parsing [implements] — binary flagged, not dropped; noise filtering is the sole exclusion point
 function patchToEntry(patch) {
     const lines = patch.split("\n");
     const header = lines[0] ?? "";

package/build/core/exec.js

@@ -1,36 +1,274 @@
-import { execFile } from "node:child_process";
+// @ref LLP 0003#subprocess-spawning-rules [implements] — the only sanctioned child-process spawn path in the codebase
+import { execFile, spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import path from "node:path";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 /**
  * Run a command capturing stdout/stderr. Never interpolates a shell, so
  * arguments are passed verbatim and are not subject to shell injection.
+ *
+ * With `input`, the call routes through spawn so the text can be streamed to
+ * stdin; every other caller keeps the execFile path unchanged.
  */
 export async function run(command, args, options = {}) {
+    if (options.input !== undefined) {
+        return runWithInput(command, args, options, options.input);
+    }
     const check = options.check ?? true;
     try {
         const { stdout, stderr } = await execFileAsync(command, args, {
             cwd: options.cwd,
             maxBuffer: options.maxBuffer ?? 64 * 1024 * 1024,
             encoding: "utf8",
+            env: options.env,
+            timeout: options.timeout,
+            killSignal: options.killSignal,
         });
         return { stdout, stderr, code: 0 };
     }
     catch (error) {
         const err = error;
-        if (!check) {
-            return { stdout: err.stdout ?? "", stderr: err.stderr ?? "", code: err.code ?? 1 };
+        // Same timeout contract as runWithInput: a child our own `timeout` killed
+        // resolves with `timedOut: true` (even under check) instead of a generic
+        // throw, so callers see one shape regardless of which path ran.
+        const timedOut = options.timeout !== undefined && err.killed === true;
+        if (!check || timedOut) {
+            return {
+                stdout: err.stdout ?? "",
+                stderr: err.stderr ?? "",
+                code: err.code ?? 1,
+                signal: err.signal,
+                timedOut: timedOut || undefined,
+            };
         }
         throw new Error(`Command failed: ${command} ${args.join(" ")}\n${err.stderr ?? err.message ?? ""}`.trim());
     }
 }
+/**
+ * Kill callbacks for children still running, so an interrupt or exit never
+ * orphans them. Detached children live in their own process group (see
+ * runWithInput), so SIGINT from Ctrl-C reaches only this process — without this,
+ * an aborted review leaves a credential-bearing `claude` running unbounded.
+ */
+const liveChildKillers = new Set();
+let childCleanupInstalled = false;
+function installChildCleanup() {
+    if (childCleanupInstalled) {
+        return;
+    }
+    childCleanupInstalled = true;
+    const killAll = () => {
+        for (const kill of liveChildKillers) {
+            kill();
+        }
+    };
+    process.on("exit", killAll);
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        process.on(signal, () => {
+            killAll();
+            // Re-raise the conventional exit code; registering a handler suppressed
+            // Node's default termination.
+            process.exitCode = signal === "SIGINT" ? 130 : 143;
+            process.exit();
+        });
+    }
+}
+/**
+ * spawn-based variant that feeds `input` to the child's stdin. Collects
+ * stdout/stderr up to `maxBuffer`, enforces `timeout`/`killSignal` manually, and
+ * resolves the same RunResult shape (with `timedOut`/`overflowed` set).
+ *
+ * The deadline is enforced with our own timers rather than spawn's native
+ * `timeout`: spawn sends `killSignal` once, to the direct child only, with no
+ * SIGKILL escalation — a child that traps SIGTERM, or a shim wrapper
+ * (volta/mise/asdf) whose grandchild holds the work, would run unbounded. Here a
+ * child launched detached forms its own process group, we signal the whole group,
+ * and a grace timer escalates to SIGKILL.
+ */
+// @ref LLP 0003#subprocess-spawning-rules [implements] — own timeout/kill enforcement (process-group kill, SIGKILL escalation) instead of spawn's native timeout, which can't reach a grandchild
+function runWithInput(command, args, options, input) {
+    const check = options.check ?? true;
+    const maxBuffer = options.maxBuffer ?? 64 * 1024 * 1024;
+    return new Promise((resolve, reject) => {
+        const detached = process.platform !== "win32";
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            detached,
+        });
+        let stdout = "";
+        let stderr = "";
+        let overflowed = false;
+        let timedOut = false;
+        let killTimer;
+        let graceTimer;
+        const clearTimers = () => {
+            if (killTimer)
+                clearTimeout(killTimer);
+            if (graceTimer)
+                clearTimeout(graceTimer);
+        };
+        // Signal the whole process group when detached so a shim wrapper's grandchild
+        // is killed too. On Windows there are no process groups — kill the tree via
+        // taskkill instead, for the same reason.
+        const killChild = (sig) => {
+            try {
+                if (process.platform === "win32" && child.pid !== undefined) {
+                    // A no-op error handler is required: an async spawn failure (ENOENT/EPERM)
+                    // has no other listener here and would otherwise throw unhandled and
+                    // crash the parent, defeating the point of this cleanup path.
+                    spawn(taskkillPath(), ["/pid", String(child.pid), "/T", "/F"]).on("error", () => { });
+                }
+                else if (detached && child.pid !== undefined) {
+                    process.kill(-child.pid, sig);
+                }
+                else {
+                    child.kill(sig);
+                }
+            }
+            catch {
+                // Already exited, or the group is gone — nothing to kill.
+            }
+        };
+        const emergencyKill = () => killChild("SIGKILL");
+        installChildCleanup();
+        liveChildKillers.add(emergencyKill);
+        if (options.timeout && options.timeout > 0) {
+            killTimer = setTimeout(() => {
+                timedOut = true;
+                killChild(options.killSignal ?? "SIGTERM");
+                graceTimer = setTimeout(() => killChild("SIGKILL"), 5000);
+                graceTimer.unref?.();
+            }, options.timeout);
+            killTimer.unref?.();
+        }
+        const cap = (current, chunk) => {
+            if (current.length >= maxBuffer) {
+                overflowed = true;
+                return current;
+            }
+            const next = current + chunk;
+            // Check AFTER appending too — a single oversized chunk must both flag the
+            // overflow and stay capped, not sail through because the pre-append length
+            // was still under the limit.
+            if (next.length > maxBuffer) {
+                overflowed = true;
+                return next.slice(0, maxBuffer);
+            }
+            return next;
+        };
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout = cap(stdout, chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr = cap(stderr, chunk);
+        });
+        // A late I/O error on either stream (e.g. the process group getting
+        // SIGKILLed mid-read) would otherwise throw unhandled and crash the
+        // parent; the close handler reports the real outcome regardless.
+        child.stdout.on("error", () => { });
+        child.stderr.on("error", () => { });
+        child.on("error", (error) => {
+            clearTimers();
+            liveChildKillers.delete(emergencyKill);
+            if (!check) {
+                // A spawn error (ENOENT/EACCES) fires before any stderr can be
+                // captured, so fall back to error.message rather than resolving
+                // with an unexplained empty stderr.
+                resolve({ stdout, stderr: stderr || error.message, code: 1, timedOut, overflowed });
+                return;
+            }
+            reject(new Error(`Command failed: ${command} ${args.join(" ")}\n${error.message}`.trim()));
+        });
+        child.on("close", (code, signal) => {
+            clearTimers();
+            liveChildKillers.delete(emergencyKill);
+            const exitCode = code ?? 1;
+            if (overflowed && check) {
+                reject(new Error(`Command output exceeded ${maxBuffer} bytes: ${command}`));
+                return;
+            }
+            if (exitCode !== 0 && check && !timedOut) {
+                reject(new Error(`Command failed: ${command} ${args.join(" ")}\n${stderr}`.trim()));
+                return;
+            }
+            resolve({
+                stdout,
+                stderr,
+                code: exitCode,
+                signal: signal ?? undefined,
+                timedOut,
+                overflowed,
+            });
+        });
+        child.stdin.on("error", () => {
+            // A child that exits before reading stdin (e.g. bad args) closes the pipe;
+            // ignore EPIPE — the close handler reports the real outcome.
+        });
+        child.stdin.end(input);
+    });
+}
+/**
+ * Memoized trusted resolutions for the host `git`/`gh` binaries, keyed by name so
+ * git()'s many callers share ONE which/where lookup instead of each spawning their
+ * own. See resolveTrustedTool.
+ */
+const trustedToolResolutions = new Map();
+/**
+ * Resolve `git`/`gh` to a trusted ABSOLUTE path, refusing any binary that resolves
+ * INSIDE the reviewed tree. Every git/gh spawn goes through this, never a bare name.
+ *
+ * A review has chdir'd into the untrusted PR-head tree (and `ecr review` of a local
+ * branch, plus `ecr ci`/doctor, operate on an untrusted checkout). libuv on Windows
+ * searches the child's cwd BEFORE PATH when the command is a BARE NAME, so a
+ * PR-committed `git.bat`/`gh.exe` at the repo root would win the lookup and run with
+ * ambient secrets (GH_TOKEN, model creds) in its environment. Spawning a resolved
+ * absolute path does no cwd search at all — the same property that fixed `claude`
+ * and `opencode`. resolveOnPath itself does the which/where lookup from tmpdir(), so
+ * the in-tree shim is never even FOUND on POSIX or Windows; pathInside is the backstop.
+ *
+ * Memoized per name: resolveOnPath is cwd-INDEPENDENT (it looks up from tmpdir), so a
+ * first call can never cache a cwd-tainted value, and the host binary is stable for
+ * the process. The caller's cwd is NOT changed — only the binary is resolved, so
+ * git/gh keep operating on their target tree. Throws (not null) so callers that
+ * assume a working git/gh fail loudly rather than silently spawning nothing.
+ */
+// @ref LLP 0003#subprocess-spawning-rules [implements] — trusted absolute-path resolution plus in-tree refusal (pathInside) for git/gh, mirroring resolveClaudeCli/resolveOpencodeCli
+export function resolveTrustedTool(name) {
+    let resolution = trustedToolResolutions.get(name);
+    if (!resolution) {
+        resolution = (async () => {
+            const resolved = await resolveOnPath(name);
+            if (!resolved) {
+                throw new Error(`The \`${name}\` CLI is not installed or not on PATH.`);
+            }
+            if (pathInside(resolved, process.cwd())) {
+                throw new Error(`refusing to run a \`${name}\` binary found inside the reviewed tree (${resolved}) — ` +
+                    `install ${name} on the host and remove it from the repository.`);
+            }
+            return resolved;
+        })();
+        trustedToolResolutions.set(name, resolution);
+    }
+    return resolution;
+}
+/** Test-only: drop memoized git/gh resolutions so a test can re-resolve under a changed cwd/PATH. */
+export function resetTrustedToolCache() {
+    trustedToolResolutions.clear();
+}
 export async function git(args, cwd) {
-    const { stdout } = await run("git", args, { cwd });
+    const gitPath = await resolveTrustedTool("git");
+    const { stdout } = await run(gitPath, args, { cwd });
     return stdout;
 }
 /** Resolve owner/repo from the current checkout via gh (for PR-targeting commands). */
 export async function resolveRepo(cwd) {
     try {
-        const { stdout } = await run("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], {
+        const gh = await resolveTrustedTool("gh");
+        const { stdout } = await run(gh, ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], {
             cwd,
         });
         const repo = stdout.trim();
@@ -52,10 +290,45 @@ export async function repoRoot(cwd) {
         return null;
     }
 }
-/** Whether an executable is resolvable on PATH. */
-export async function onPath(command) {
-    const { code } = await run(process.platform === "win32" ? "where" : "which", [command], {
+// @ref LLP 0003#subprocess-spawning-rules [implements] — resolves from tmpdir(), never the process's own (possibly PR-tree) cwd, so a Windows cwd-search hijack can't find an in-tree shim
+/** Absolute path of an executable on PATH (first match), or null if unresolved. */
+export async function resolveOnPath(command) {
+    // SECURITY: run the lookup from a trusted directory, never the inherited cwd.
+    // During a review the process has chdir'd into the untrusted PR-head tree, and
+    // Windows `where` searches the CURRENT DIRECTORY before PATH — a committed
+    // `claude.exe` at the repo root would win the lookup and be executed with the
+    // engine's credentials in its environment. tmpdir() is host-controlled.
+    const { stdout, code } = await run(process.platform === "win32" ? "where" : "which", [command], {
         check: false,
+        cwd: tmpdir(),
     });
-    return code === 0;
+    if (code !== 0) {
+        return null;
+    }
+    return stdout.trim().split("\n")[0]?.trim() || null;
+}
+/**
+ * Whether `filePath` lies inside `dir` (after resolution). Used as the backstop
+ * that refuses to execute a binary resolved from inside the reviewed tree.
+ */
+export function pathInside(filePath, dir) {
+    const rel = path.relative(path.resolve(dir), path.resolve(filePath));
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/**
+ * Absolute path to Windows' `taskkill`, so a process-tree kill never spawns a BARE
+ * `taskkill` — during a review the cwd is the untrusted PR-head tree, and Windows
+ * resolves a bare name against the current directory before PATH, so a PR-committed
+ * `taskkill.exe`/`.bat` at the tree root could otherwise run in place of the real one
+ * (with ambient secrets in its env) on the timeout-kill path. An absolute path does no
+ * search at all. `taskkill` always lives in System32, and `SystemRoot` is set by
+ * Windows, never by the PR. Callers stay win32-guarded.
+ */
+export function taskkillPath() {
+    const root = process.env.SystemRoot || process.env.windir || "C:\\Windows";
+    return path.join(root, "System32", "taskkill.exe");
+}
+/** Whether an executable is resolvable on PATH. */
+export async function onPath(command) {
+    return (await resolveOnPath(command)) !== null;
 }

package/build/core/log.js

@@ -1,3 +1,4 @@
+// @ref LLP 0002#run-log-and-observability-sinks [implements] — one JSON line per run for cost/latency auditability
 import { appendFile, mkdir } from "node:fs/promises";
 import path from "node:path";
 /**

package/build/core/noise.js

@@ -1,3 +1,4 @@
+// @ref LLP 0004#noise-filtering [implements] — pre-agent signal gate; impure (reads cwd/disk), swallows read errors to null
 import { mkdir, open, writeFile } from "node:fs/promises";
 import path from "node:path";
 const LOCKFILES = new Set(["yarn.lock", "package-lock.json", "pnpm-lock.yaml", "bun.lock"]);
@@ -32,6 +33,7 @@ export async function filterNoise(entries, options = {}, cwd = process.cwd()) {
     }
     return { kept, filtered };
 }
+// @ref LLP 0004#noise-filtering [constrained-by] — marker checks are header-scoped only; whole-file scan self-filters this module
 async function noiseReason(entry, options, cwd) {
     if (entry.binary) {
         return "binary file (no textual diff)";
@@ -70,6 +72,7 @@ async function noiseReason(entry, options, cwd) {
 }
 /** How many leading lines of a file count as its (generation) header. */
 const HEADER_LINES = 5;
+// @ref LLP 0004#the-mini-glob-dialect [constrained-by] — no sentinel bytes: a NUL sentinel once made this file classify as binary to git
 /** Minimal glob: supports `**` (crosses `/`) and `*` (within a segment). */
 export function matchesIgnore(filePath, pattern) {
     // Translate the glob to a regex in a single pass, escaping metacharacters
@@ -128,6 +131,7 @@ async function readFileHead(absPath, bytes = 4096) {
         return null;
     }
 }
+// @ref LLP 0004#chunk-sizing-signal [implements] — sole size metric for chunk packing; the packing policy itself lives in review.ts
 /** Count added + removed lines in a unified-diff patch (ignores +++/--- headers). */
 export function countChangedLines(patch) {
     let count = 0;
@@ -141,6 +145,7 @@ export function countChangedLines(patch) {
     }
     return count;
 }
+// @ref LLP 0004#patch-workspace [implements] — filenames sanitized against traversal/collisions from untrusted diff paths
 /**
  * Write one patch file per changed file plus a shared manifest, all inside the
  * repo (so the OpenCode read tool can reach them). Agents are pointed at these