@expo/code-review-cli 0.2.3 → 0.4.0

package/build/core/auth.js

@@ -1,12 +1,12 @@
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
 /** Env var each provider's SDK reads for an API key (x-api-key style). */
 const PROVIDER_KEY_ENV = {
-    anthropic: 'ANTHROPIC_API_KEY',
-    openai: 'OPENAI_API_KEY',
-    google: 'GOOGLE_GENERATIVE_AI_API_KEY',
-    openrouter: 'OPENROUTER_API_KEY',
+    anthropic: "ANTHROPIC_API_KEY",
+    openai: "OPENAI_API_KEY",
+    google: "GOOGLE_GENERATIVE_AI_API_KEY",
+    openrouter: "OPENROUTER_API_KEY",
 };
 /**
  * Env vars that must NEVER be forwarded to a model provider. `auth.tokenEnv` names
@@ -18,20 +18,84 @@ const PROVIDER_KEY_ENV = {
  * Defense-in-depth alongside loading config only from the trusted base ref.
  */
 const FORBIDDEN_TOKEN_ENVS = new Set([
-    'GITHUB_TOKEN',
-    'GH_TOKEN',
-    'ACTIONS_RUNTIME_TOKEN',
-    'ACTIONS_ID_TOKEN_REQUEST_TOKEN',
-    'AWS_ACCESS_KEY_ID',
-    'AWS_SECRET_ACCESS_KEY',
-    'AWS_SESSION_TOKEN',
-    'GOOGLE_APPLICATION_CREDENTIALS',
-    'GCP_SERVICE_ACCOUNT_KEY',
-    'NPM_TOKEN',
-    'NODE_AUTH_TOKEN',
-    'SSH_PRIVATE_KEY',
+    "GITHUB_TOKEN",
+    "GH_TOKEN",
+    "ACTIONS_RUNTIME_TOKEN",
+    "ACTIONS_ID_TOKEN_REQUEST_TOKEN",
+    "AWS_ACCESS_KEY_ID",
+    "AWS_SECRET_ACCESS_KEY",
+    "AWS_SESSION_TOKEN",
+    "GOOGLE_APPLICATION_CREDENTIALS",
+    "GCP_SERVICE_ACCOUNT_KEY",
+    "NPM_TOKEN",
+    "NODE_AUTH_TOKEN",
+    "SSH_PRIVATE_KEY",
 ]);
 const YEAR_MS = 365 * 24 * 60 * 60 * 1000;
+/**
+ * Decide whether the configured model provider has a usable credential, WITHOUT
+ * mutating the environment. Shared by `prepareAuth` (fail fast before spinning up
+ * the server and every pass) and `doctor` (report), so the two never drift.
+ *
+ * We only report `ok: false` when we're confident there is no credential — a
+ * missing OAuth token, a forbidden tokenEnv, or an api-key run with neither the
+ * configured tokenEnv nor the provider's own key env set. When nothing is
+ * configured and no known key env is present, we assume OpenCode's own login may
+ * cover it and don't hard-fail. `REVIEWER_MODEL` bypasses provider auth entirely.
+ */
+export function checkProviderAuth(config, env = process.env) {
+    const { mode, provider, tokenEnv } = config.auth;
+    if (env.REVIEWER_MODEL) {
+        return {
+            ok: true,
+            detail: `REVIEWER_MODEL override (${env.REVIEWER_MODEL}); using OpenCode's own login for that model`,
+        };
+    }
+    if (tokenEnv && FORBIDDEN_TOKEN_ENVS.has(tokenEnv)) {
+        return {
+            ok: false,
+            detail: `auth.tokenEnv is "${tokenEnv}", a well-known non-provider secret; refusing to ` +
+                `forward it to the model provider (that would leak it). Point auth.tokenEnv at a ` +
+                `token minted for the provider instead.`,
+        };
+    }
+    if (mode === "oauth") {
+        if (!tokenEnv) {
+            return {
+                ok: false,
+                detail: 'auth.mode "oauth" requires auth.tokenEnv to name the env var holding the OAuth token.',
+            };
+        }
+        if (!env[tokenEnv]) {
+            return {
+                ok: false,
+                detail: `auth is oauth for ${provider} but token env "${tokenEnv}" is not set.`,
+            };
+        }
+        return { ok: true, detail: `oauth for ${provider}; token env ${tokenEnv} is set` };
+    }
+    // api-key: usable if the configured tokenEnv is set, or the provider's own key
+    // env is already present in the environment.
+    const providerKeyEnv = PROVIDER_KEY_ENV[provider];
+    if (tokenEnv && env[tokenEnv]) {
+        return { ok: true, detail: `api-key for ${provider}; token env ${tokenEnv} is set` };
+    }
+    if (providerKeyEnv && env[providerKeyEnv]) {
+        return { ok: true, detail: `api-key for ${provider}; ${providerKeyEnv} is set` };
+    }
+    if (!tokenEnv && !providerKeyEnv) {
+        return {
+            ok: true,
+            detail: `api-key for ${provider}; no tokenEnv configured and no known key env — relying on OpenCode's own login`,
+        };
+    }
+    const names = [tokenEnv, providerKeyEnv].filter(Boolean).join(" or ");
+    return {
+        ok: false,
+        detail: `configured api-key for ${provider} but no credential is set — set ${names}, or set ` +
+            `REVIEWER_MODEL to a model you're already logged into.`,
+    };
+}
 /**
  * Prepare model credentials for the OpenCode server based on the repo's auth mode.
  * Must run before the server starts (it mutates env). Returns a cleanup handle.
@@ -53,17 +117,18 @@ export async function prepareAuth(config) {
     if (process.env.REVIEWER_MODEL) {
         return noop;
     }
-    // Refuse to forward a well-known unrelated secret as the provider credential,
-    // even if the (repo/PR-controlled) config names one — that would leak it.
-    if (tokenEnv && FORBIDDEN_TOKEN_ENVS.has(tokenEnv)) {
-        throw new Error(`auth.tokenEnv is set to "${tokenEnv}", a well-known non-provider secret. Refusing ` +
-            `to forward it to the model provider (that would leak the secret). Point auth.tokenEnv ` +
-            `at a token minted for the model provider instead.`);
+    // Fail fast, before starting the server and every pass, if the configured
+    // provider has no usable credential — otherwise it surfaces as N failed passes
+    // mid-run. This is the same readiness check `doctor` reports, and it also covers
+    // the forbidden-secret guard (refusing to forward a well-known unrelated secret).
+    const readiness = checkProviderAuth(config);
+    if (!readiness.ok) {
+        throw new Error(readiness.detail);
     }
-    if (mode === 'api-key') {
+    if (mode === "api-key") {
         if (tokenEnv) {
             const value = process.env[tokenEnv];
-            const target = PROVIDER_KEY_ENV[provider] ?? 'ANTHROPIC_API_KEY';
+            const target = PROVIDER_KEY_ENV[provider] ?? "ANTHROPIC_API_KEY";
             // The explicitly-configured tokenEnv is authoritative — set it even if the
             // provider env is already present, so config wins over ambient env.
             if (value) {
@@ -72,27 +137,25 @@ export async function prepareAuth(config) {
         }
         return noop;
     }
-    // oauth
-    if (!tokenEnv) {
-        throw new Error('auth.mode "oauth" requires auth.tokenEnv to name the env var holding the OAuth token.');
-    }
-    const token = process.env[tokenEnv];
+    // oauth — checkProviderAuth guarantees tokenEnv is set and present; read
+    // defensively so TypeScript narrows and this stays correct if called directly.
+    const token = tokenEnv ? process.env[tokenEnv] : undefined;
     if (!token) {
-        throw new Error(`OAuth token env "${tokenEnv}" is not set.`);
+        throw new Error('auth.mode "oauth" requires auth.tokenEnv to name a set OAuth token env.');
     }
-    const dir = await mkdtemp(path.join(tmpdir(), 'ecr-auth-'));
-    await mkdir(path.join(dir, 'opencode'), { recursive: true });
+    const dir = await mkdtemp(path.join(tmpdir(), "ecr-auth-"));
+    await mkdir(path.join(dir, "opencode"), { recursive: true });
     const authJson = {
         [provider]: {
-            type: 'oauth',
+            type: "oauth",
             access: token,
-            refresh: '',
+            refresh: "",
             // Far-future expiry so OpenCode uses the token as-is and does not try to
             // refresh it (setup-token tokens are long-lived and carry no refresh).
             expires: Date.now() + YEAR_MS,
         },
     };
-    await writeFile(path.join(dir, 'opencode', 'auth.json'), JSON.stringify(authJson), 'utf8');
+    await writeFile(path.join(dir, "opencode", "auth.json"), JSON.stringify(authJson), "utf8");
     process.env.XDG_DATA_HOME = dir;
     return {
         cleanup: async () => {

package/build/core/coordinator.js

@@ -1,6 +1,6 @@
-import { promptAndParse } from './opencode.js';
-import { buildCoordinatorSystem, buildCoordinatorTask } from './prompts.js';
-import { parseCoordinatorOutput } from './schema.js';
+import { promptAndParse } from "./opencode.js";
+import { buildCoordinatorSystem, buildCoordinatorTask } from "./prompts.js";
+import { parseCoordinatorOutput } from "./schema.js";
 /**
  * Single LLM call that dedupes, re-judges severity, and decides. Structured so it
  * could later own a spawn tool, but for now stays a plain consolidation pass.
@@ -13,10 +13,10 @@ export async function coordinate(handle, config, metadata, agentFindings, covera
     const system = buildCoordinatorSystem(config);
     const text = buildCoordinatorTask(metadata, agentFindings, coverageNotes);
     const { value, cost, tokens, truncated } = await promptAndParse(handle, {
-        agent: 'coordinator',
+        agent: "coordinator",
         system,
         text,
-        title: 'review-coordinator',
+        title: "review-coordinator",
         maxWaitMs: COORDINATOR_TIMEOUT_MS,
         finalizeOnTimeout: true,
     }, parseCoordinatorOutput);

package/build/core/diff.js

@@ -8,20 +8,20 @@ export function parseUnifiedDiff(diffText) {
         return [];
     }
     const entries = [];
-    const lines = diffText.split('\n');
+    const lines = diffText.split("\n");
     let current = null;
     const flush = () => {
         if (!current || current.length === 0) {
             return;
         }
-        const entry = patchToEntry(current.join('\n'));
+        const entry = patchToEntry(current.join("\n"));
         if (entry) {
             entries.push(entry);
         }
         current = null;
     };
     for (const line of lines) {
-        if (line.startsWith('diff --git ')) {
+        if (line.startsWith("diff --git ")) {
             flush();
             current = [line];
         }
@@ -33,49 +33,49 @@ export function parseUnifiedDiff(diffText) {
     return entries;
 }
 function patchToEntry(patch) {
-    const lines = patch.split('\n');
-    const header = lines[0] ?? '';
+    const lines = patch.split("\n");
+    const header = lines[0] ?? "";
     let newPath = null;
     let oldPath = null;
     let status;
     let binary = false;
     for (const line of lines) {
-        if (line.startsWith('+++ ')) {
+        if (line.startsWith("+++ ")) {
             newPath = stripDiffPathPrefix(line.slice(4));
         }
-        else if (line.startsWith('--- ')) {
+        else if (line.startsWith("--- ")) {
             oldPath = stripDiffPathPrefix(line.slice(4));
         }
-        else if (line.startsWith('new file mode')) {
-            status = 'A';
+        else if (line.startsWith("new file mode")) {
+            status = "A";
         }
-        else if (line.startsWith('deleted file mode')) {
-            status = 'D';
+        else if (line.startsWith("deleted file mode")) {
+            status = "D";
         }
-        else if (line.startsWith('rename ')) {
-            status = 'R';
+        else if (line.startsWith("rename ")) {
+            status = "R";
         }
-        else if (line.startsWith('Binary files ') || line === 'GIT binary patch') {
+        else if (line.startsWith("Binary files ") || line === "GIT binary patch") {
             // git emits one of these instead of +++/---/@@ hunks for a binary file.
             // There is no textual diff to review; flag it so noise filtering drops it.
             binary = true;
         }
     }
-    let path = newPath && newPath !== '/dev/null' ? newPath : oldPath;
-    if (!path || path === '/dev/null') {
+    let path = newPath && newPath !== "/dev/null" ? newPath : oldPath;
+    if (!path || path === "/dev/null") {
         path = pathFromHeader(header);
     }
     if (!path) {
         return null;
     }
-    return { path, patch, status: status ?? 'M', binary };
+    return { path, patch, status: status ?? "M", binary };
 }
 function stripDiffPathPrefix(raw) {
     const value = raw.trim();
-    if (value === '/dev/null') {
+    if (value === "/dev/null") {
         return value;
     }
-    return value.replace(/^[ab]\//, '');
+    return value.replace(/^[ab]\//, "");
 }
 function pathFromHeader(header) {
     const match = header.match(/^diff --git a\/(.+?) b\/(.+)$/);

package/build/core/exec.js

@@ -1,5 +1,5 @@
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 /**
  * Run a command capturing stdout/stderr. Never interpolates a shell, so
@@ -11,26 +11,26 @@ export async function run(command, args, options = {}) {
         const { stdout, stderr } = await execFileAsync(command, args, {
             cwd: options.cwd,
             maxBuffer: options.maxBuffer ?? 64 * 1024 * 1024,
-            encoding: 'utf8',
+            encoding: "utf8",
         });
         return { stdout, stderr, code: 0 };
     }
     catch (error) {
         const err = error;
         if (!check) {
-            return { stdout: err.stdout ?? '', stderr: err.stderr ?? '', code: err.code ?? 1 };
+            return { stdout: err.stdout ?? "", stderr: err.stderr ?? "", code: err.code ?? 1 };
         }
-        throw new Error(`Command failed: ${command} ${args.join(' ')}\n${err.stderr ?? err.message ?? ''}`.trim());
+        throw new Error(`Command failed: ${command} ${args.join(" ")}\n${err.stderr ?? err.message ?? ""}`.trim());
     }
 }
 export async function git(args, cwd) {
-    const { stdout } = await run('git', args, { cwd });
+    const { stdout } = await run("git", 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 { stdout } = await run("gh", ["repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"], {
             cwd,
         });
         const repo = stdout.trim();
@@ -41,12 +41,12 @@ export async function resolveRepo(cwd) {
     catch {
         // fall through to a clear error
     }
-    throw new Error('Could not determine the repository; pass --repo owner/repo.');
+    throw new Error("Could not determine the repository; pass --repo owner/repo.");
 }
 /** Absolute path of the git working-tree root, or null if not in a repo. */
 export async function repoRoot(cwd) {
     try {
-        return (await git(['rev-parse', '--show-toplevel'], cwd)).trim() || null;
+        return (await git(["rev-parse", "--show-toplevel"], cwd)).trim() || null;
     }
     catch {
         return null;
@@ -54,7 +54,7 @@ export async function repoRoot(cwd) {
 }
 /** Whether an executable is resolvable on PATH. */
 export async function onPath(command) {
-    const { code } = await run(process.platform === 'win32' ? 'where' : 'which', [command], {
+    const { code } = await run(process.platform === "win32" ? "where" : "which", [command], {
         check: false,
     });
     return code === 0;

package/build/core/log.js

@@ -1,10 +1,10 @@
-import { appendFile, mkdir } from 'node:fs/promises';
-import path from 'node:path';
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
 /**
  * Append one JSON line per review run. Keeps inputs, findings, decision, and
  * cost together so runs are auditable and cost/latency can be measured later.
  */
 export async function writeRunLog(logPath, record) {
     await mkdir(path.dirname(logPath), { recursive: true });
-    await appendFile(logPath, `${JSON.stringify(record)}\n`, 'utf8');
+    await appendFile(logPath, `${JSON.stringify(record)}\n`, "utf8");
 }

package/build/core/noise.js

@@ -1,16 +1,16 @@
-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']);
-const NOISE_EXTENSIONS = ['.min.js', '.min.css', '.bundle.js', '.map'];
+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"]);
+const NOISE_EXTENSIONS = [".min.js", ".min.css", ".bundle.js", ".map"];
 const DEFAULT_MARKERS = [
-    '@generated',
-    '@codegen',
-    'code generated by',
-    'this file was generated',
-    'this file is generated',
-    'auto-generated',
-    'autogenerated',
-    'do not edit',
+    "@generated",
+    "@codegen",
+    "code generated by",
+    "this file was generated",
+    "this file is generated",
+    "auto-generated",
+    "autogenerated",
+    "do not edit",
 ];
 /**
  * Strip files that add no signal (lockfiles, generated bundles/maps, snapshots,
@@ -34,37 +34,37 @@ export async function filterNoise(entries, options = {}, cwd = process.cwd()) {
 }
 async function noiseReason(entry, options, cwd) {
     if (entry.binary) {
-        return 'binary file (no textual diff)';
+        return "binary file (no textual diff)";
     }
     const base = path.basename(entry.path);
     if (LOCKFILES.has(base)) {
-        return 'lockfile';
+        return "lockfile";
     }
     for (const ext of NOISE_EXTENSIONS) {
         if (entry.path.endsWith(ext)) {
             return `generated asset (${ext})`;
         }
     }
-    if (entry.path.includes('__snapshots__/') && entry.path.endsWith('.snap')) {
-        return 'jest snapshot';
+    if (entry.path.includes("__snapshots__/") && entry.path.endsWith(".snap")) {
+        return "jest snapshot";
     }
     for (const pattern of options.additionalIgnores ?? []) {
         if (matchesIgnore(entry.path, pattern)) {
             return `repo-ignored (${pattern})`;
         }
     }
-    const markers = [...DEFAULT_MARKERS, ...(options.additionalMarkers ?? [])].map(marker => marker.toLowerCase());
+    const markers = [...DEFAULT_MARKERS, ...(options.additionalMarkers ?? [])].map((marker) => marker.toLowerCase());
     // A generation marker only counts as a HEADER — real generated files carry it
     // in their first few lines (e.g. `// @generated`, `# ... DO NOT EDIT.`). Only
     // checking the top avoids false positives on hand-written files that merely
     // mention these strings (e.g. this module lists them as DEFAULT_MARKERS, and a
     // config comment references "@generated"), which were being wrongly filtered.
     if (hasMarkerHeaderInPatch(entry.patch, markers)) {
-        return 'generated file header';
+        return "generated file header";
     }
     const head = await readFileHead(path.resolve(cwd, entry.path));
     if (head && hasMarkerInHead(head, markers)) {
-        return 'generated file header';
+        return "generated file header";
     }
     return null;
 }
@@ -76,20 +76,20 @@ export function matchesIgnore(filePath, pattern) {
     // inline. We deliberately use NO placeholder character: an earlier version
     // stashed a literal NUL byte as a sentinel, which made git classify this
     // source file as binary (so its diff was invisible to reviewers).
-    let out = '';
+    let out = "";
     for (let i = 0; i < pattern.length; i++) {
         const ch = pattern[i];
-        if (ch === '*') {
-            if (pattern[i + 1] === '*') {
-                out += '.*';
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                out += ".*";
                 i++;
             }
             else {
-                out += '[^/]*';
+                out += "[^/]*";
             }
         }
         else if (/[.+^${}()|[\]\\?]/.test(ch)) {
-            out += '\\' + ch;
+            out += "\\" + ch;
         }
         else {
             out += ch;
@@ -100,25 +100,25 @@ export function matchesIgnore(filePath, pattern) {
 /** A generation marker in the first few ADDED lines (i.e. the top of a new file). */
 function hasMarkerHeaderInPatch(patch, markers) {
     const topAddedLines = patch
-        .split('\n')
-        .filter(line => line.startsWith('+') && !line.startsWith('+++'))
+        .split("\n")
+        .filter((line) => line.startsWith("+") && !line.startsWith("+++"))
         .slice(0, HEADER_LINES)
-        .map(line => line.toLowerCase());
-    return topAddedLines.some(line => markers.some(marker => line.includes(marker)));
+        .map((line) => line.toLowerCase());
+    return topAddedLines.some((line) => markers.some((marker) => line.includes(marker)));
 }
 /** A generation marker in the first few lines of the on-disk file. */
 function hasMarkerInHead(head, markers) {
-    const topLines = head.split('\n').slice(0, HEADER_LINES).join('\n').toLowerCase();
-    return markers.some(marker => topLines.includes(marker));
+    const topLines = head.split("\n").slice(0, HEADER_LINES).join("\n").toLowerCase();
+    return markers.some((marker) => topLines.includes(marker));
 }
 /** Read the first `bytes` of a file (default 4 KB) without loading the whole thing. */
 async function readFileHead(absPath, bytes = 4096) {
     try {
-        const handle = await open(absPath, 'r');
+        const handle = await open(absPath, "r");
         try {
             const buffer = Buffer.alloc(bytes);
             const { bytesRead } = await handle.read(buffer, 0, bytes, 0);
-            return buffer.subarray(0, bytesRead).toString('utf8');
+            return buffer.subarray(0, bytesRead).toString("utf8");
         }
         finally {
             await handle.close();
@@ -131,11 +131,11 @@ async function readFileHead(absPath, bytes = 4096) {
 /** Count added + removed lines in a unified-diff patch (ignores +++/--- headers). */
 export function countChangedLines(patch) {
     let count = 0;
-    for (const line of patch.split('\n')) {
-        if (line.startsWith('+') && !line.startsWith('+++')) {
+    for (const line of patch.split("\n")) {
+        if (line.startsWith("+") && !line.startsWith("+++")) {
             count++;
         }
-        else if (line.startsWith('-') && !line.startsWith('---')) {
+        else if (line.startsWith("-") && !line.startsWith("---")) {
             count++;
         }
     }
@@ -147,14 +147,14 @@ export function countChangedLines(patch) {
  * paths instead of having the full diff inlined into every prompt.
  */
 export async function writePatchWorkspace(kept, metadata, rootDir) {
-    const patchDir = path.join(rootDir, 'patches');
+    const patchDir = path.join(rootDir, "patches");
     await mkdir(patchDir, { recursive: true });
     const files = [];
     for (let index = 0; index < kept.length; index++) {
         const entry = kept[index];
-        const safeName = `${String(index).padStart(4, '0')}-${entry.path.replace(/[^a-zA-Z0-9._-]/g, '__')}.patch`;
+        const safeName = `${String(index).padStart(4, "0")}-${entry.path.replace(/[^a-zA-Z0-9._-]/g, "__")}.patch`;
         const patchPath = path.join(patchDir, safeName);
-        await writeFile(patchPath, entry.patch, 'utf8');
+        await writeFile(patchPath, entry.patch, "utf8");
         files.push({
             path: entry.path,
             patchPath,
@@ -163,24 +163,24 @@ export async function writePatchWorkspace(kept, metadata, rootDir) {
             changedLines: countChangedLines(entry.patch),
         });
     }
-    const manifestPath = path.join(rootDir, 'context.md');
-    await writeFile(manifestPath, renderManifest(files, metadata), 'utf8');
+    const manifestPath = path.join(rootDir, "context.md");
+    await writeFile(manifestPath, renderManifest(files, metadata), "utf8");
     return { root: rootDir, manifestPath, files };
 }
 function renderManifest(files, metadata) {
     const lines = [
-        '# Changed files',
-        '',
-        `Base: ${metadata.baseRef || '(unknown)'}  Head: ${metadata.headRef || '(unknown)'}`,
-        '',
-        'Each entry lists the changed file (path relative to repo root) and a patch',
-        'file containing its unified diff. Read the patch to see what changed, then',
-        'read the surrounding source in the repo to confirm findings in context.',
-        '',
+        "# Changed files",
+        "",
+        `Base: ${metadata.baseRef || "(unknown)"}  Head: ${metadata.headRef || "(unknown)"}`,
+        "",
+        "Each entry lists the changed file (path relative to repo root) and a patch",
+        "file containing its unified diff. Read the patch to see what changed, then",
+        "read the surrounding source in the repo to confirm findings in context.",
+        "",
     ];
     for (const file of files) {
-        lines.push(`- \`${file.path}\` (${file.status ?? 'M'}) — patch: \`${file.patchPath}\``);
+        lines.push(`- \`${file.path}\` (${file.status ?? "M"}) — patch: \`${file.patchPath}\``);
     }
-    lines.push('');
-    return lines.join('\n');
+    lines.push("");
+    return lines.join("\n");
 }