@jpkme/diff-review 0.1.10 → 0.1.12

package/lib/agents.mjs

@@ -6,9 +6,21 @@
  * no se toca el portapapeles ni se choca con el límite de largo de la línea de comandos de los shims `.cmd`.
  */
 import { spawn } from "node:child_process";
-import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
+import {
+  accessSync,
+  constants,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { delimiter, join } from "node:path";
+import { outputRelPath } from "./output-name.mjs";
 
 /**
  * @typedef {{ value: string, label: string, hint?: string }} ModelOption
@@ -21,7 +33,10 @@ import { delimiter, join } from "node:path";
  *   models: ModelOption[],
  *   configuredModel?: (ctx: DetectContext) => { model: string, source: string } | null,
  *   args: (spec: RunSpec) => string[],
+ *   acp?: (ctx: { path: string }) => AcpLaunch,
  * }} AgentDef
+ * @typedef {{ file: string, args: string[], env?: Record<string, string>, sessionMeta?: Record<string, unknown> }} AcpLaunch
+ *   `env` se suma al del proceso; `sessionMeta` va como `_meta` en `session/new` / `session/load`.
  * @typedef {{ env: NodeJS.ProcessEnv, platform: NodeJS.Platform, home: string }} DetectContext
  * @typedef {{ def: AgentDef, path: string }} DetectedAgent
  */
@@ -78,6 +93,32 @@ function versionedBinaries(root, exe) {
   return out;
 }
 
+/**
+ * Carpeta de configuración para Cursor por ACP: la del usuario sin su allowlist. Cursor aprueba solo lo que matchee
+ * `permissions.allow` mirando el nombre del comando (`Shell(echo)` deja pasar `echo x > archivo`); vaciándola,
+ * cada comando pasa por la política de diff-review. El login no vive ahí, así que se conserva. El modelo elegido
+ * por ACP se guarda en esta carpeta y no pisa el default del usuario.
+ */
+export function cursorAcpConfigDir(ctx) {
+  const c = context(ctx);
+  const userDir = c.env.CURSOR_CONFIG_DIR?.trim() || (c.env.XDG_CONFIG_HOME?.trim() ? join(c.env.XDG_CONFIG_HOME, "cursor") : join(c.home, ".cursor"));
+  const dir = join(tmpdir(), "diff-review", "cursor-config");
+  mkdirSync(dir, { recursive: true });
+  const config = readJson(join(userDir, "cli-config.json")) ?? {};
+  writeFileSync(
+    join(dir, "cli-config.json"),
+    JSON.stringify({ ...config, permissions: { allow: [], deny: config.permissions?.deny ?? [] }, approvalMode: "allowlist" }, null, 2),
+  );
+  // El modelo que elige ACP queda en acp-config.json: arrancar siempre desde el default del usuario.
+  const userAcp = join(userDir, "acp-config.json");
+  if (existsSync(userAcp)) copyFileSync(userAcp, join(dir, "acp-config.json"));
+  else rmSync(join(dir, "acp-config.json"), { force: true });
+  return dir;
+}
+
+/** Adaptador ACP de Claude Code (antes `@zed-industries/claude-agent-acp`). */
+export const CLAUDE_ACP_PACKAGE = "@agentclientprotocol/claude-agent-acp@^0.91.0";
+
 /** @type {AgentDef[]} */
 export const AGENTS = [
   {
@@ -118,8 +159,26 @@ export const AGENTS = [
       "Glob",
       "Bash(git:*)",
       "Bash(npx --yes @jpkme/diff-review validate:*)",
-      `Edit(./${outputFilename})`,
+      `Edit(./${outputRelPath(outputFilename)})`,
     ],
+    // Claude Code no habla ACP solo: el adaptador oficial lo envuelve (usa el login de Claude Code del usuario).
+    acp: () => {
+      const local = findOnPath("claude-agent-acp", context());
+      return {
+        ...(local ? { file: local, args: [] } : { file: "npx", args: ["--yes", CLAUDE_ACP_PACKAGE] }),
+        sessionMeta: {
+          claudeCode: {
+            options: {
+              // Solo las tools que una review necesita (nada de web, subagentes ni MCP).
+              tools: ["Read", "Grep", "Glob", "Bash", "Edit", "Write"],
+              // Sin la configuración del usuario ni la del repo: su allowlist aprobaría comandos sin pasar por la
+              // política de diff-review (y un repo podría traer la suya en .claude/settings.json).
+              settingSources: [],
+            },
+          },
+        },
+      };
+    },
   },
   {
     id: "codex",
@@ -157,6 +216,8 @@ export const AGENTS = [
     // Con -p lee el prompt de stdin. Sin --force solo corre lo que esté en la allowlist del usuario
     // (`~/.cursor/cli-config.json`) y bloquearía el validate; no hay flag para pasar una allowlist.
     args: ({ model }) => ["-p", "--output-format", "text", "--trust", "--force", ...(model ? ["--model", model] : [])],
+    // Modo ACP nativo. Con su configuración aislada (ver cursorAcpConfigDir), cada comando pide permiso.
+    acp: ({ path }) => ({ file: path, args: ["acp"], env: { CURSOR_CONFIG_DIR: cursorAcpConfigDir() } }),
   },
   {
     id: "copilot",
@@ -180,8 +241,10 @@ export const AGENTS = [
       "--allow-tool",
       "shell(npx:*)",
       "--allow-tool",
-      `write(${outputFilename})`,
+      `write(${outputRelPath(outputFilename)})`,
     ],
+    // Modo ACP nativo. Su opción de sesión `allow_all` queda apagada: cada permiso pasa por nuestra política.
+    acp: ({ path }) => ({ file: path, args: ["--acp"] }),
   },
   {
     id: "gemini",
@@ -253,12 +316,10 @@ export function detectAgents(ctx) {
 
 /** Valor del select para "no pasar --model" (que el agente use el suyo). */
 export const AGENT_DEFAULT_MODEL = "";
-/** Valor del select para escribir un id de modelo a mano. */
-export const OTHER_MODEL = "__other__";
 
 /**
- * Opciones del select de modelo: primero el default del agente (marcado como inicial), después los conocidos y
- * "Otro…". Si el default configurado coincide con uno conocido, no se repite.
+ * Opciones del select de modelo: primero el default del agente (marcado como inicial), después los conocidos.
+ * Si el default configurado coincide con uno conocido, no se repite.
  * @param {AgentDef} def
  * @param {Partial<DetectContext>} [ctx]
  * @returns {{ options: ModelOption[], initialValue: string }}
@@ -270,7 +331,7 @@ export function modelChoices(def, ctx) {
     : { value: AGENT_DEFAULT_MODEL, label: "Por defecto del agente", hint: "no se pasa --model" };
   const rest = def.models.filter((m) => m.value !== configured?.model);
   return {
-    options: [first, ...rest, { value: OTHER_MODEL, label: "Otro…", hint: "escribir el id del modelo" }],
+    options: [first, ...rest],
     initialValue: AGENT_DEFAULT_MODEL,
   };
 }
@@ -295,6 +356,22 @@ function quoteForCmd(arg) {
   return /^[\w./:@=-]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '""')}"`;
 }
 
+/**
+ * `spawn` que también lanza los shims `.cmd`/`.bat` de npm en Windows (y `npx` a secas, que es uno de ellos).
+ * @param {string} file
+ * @param {string[]} args
+ * @param {import('node:child_process').SpawnOptions} options
+ */
+export function spawnCommand(file, args, options) {
+  const resolved =
+    process.platform === "win32" && !/[\\/]/.test(file) ? (findOnPath(file, context()) ?? file) : file;
+  // Node no lanza .cmd/.bat sin shell (CVE-2024-27980); con shell hay que citar a mano.
+  const viaShell = process.platform === "win32" && /\.(cmd|bat)$/i.test(resolved);
+  return viaShell
+    ? spawn([resolved, ...args].map(quoteForCmd).join(" "), { ...options, shell: true })
+    : spawn(resolved, args, options);
+}
+
 /**
  * Lanza el agente en el repo con el prompt por stdin; stdout/stderr van a la terminal.
  * @param {DetectedAgent} agent
@@ -303,11 +380,7 @@ function quoteForCmd(arg) {
  */
 export function runAgent(agent, { cwd, prompt, model, outputFilename }) {
   const args = agent.def.args({ model, outputFilename });
-  // Node no lanza .cmd/.bat sin shell (CVE-2024-27980); con shell hay que citar a mano.
-  const viaShell = process.platform === "win32" && /\.(cmd|bat)$/i.test(agent.path);
-  const child = viaShell
-    ? spawn([agent.path, ...args].map(quoteForCmd).join(" "), { cwd, shell: true, stdio: ["pipe", "inherit", "inherit"] })
-    : spawn(agent.path, args, { cwd, stdio: ["pipe", "inherit", "inherit"] });
+  const child = spawnCommand(agent.path, args, { cwd, stdio: ["pipe", "inherit", "inherit"] });
   // Si el agente sale antes de leer stdin (p. ej. un modelo inválido), el EPIPE no debe tirar abajo la CLI.
   child.stdin?.on("error", () => {});
   child.stdin?.end(prompt);

package/lib/agents.test.mjs

@@ -9,7 +9,6 @@ import {
   detectAgents,
   findOnPath,
   modelChoices,
-  OTHER_MODEL,
   topLevelTomlModel,
 } from "./agents.mjs";
 
@@ -78,16 +77,15 @@ describe("detectAgents", () => {
 });
 
 describe("modelChoices", () => {
-  it("sin modelo configurado: 'Por defecto del agente' primero y como inicial, y 'Otro…' al final", () => {
+  it("sin modelo configurado: 'Por defecto del agente' primero y como inicial", () => {
     const { options, initialValue } = modelChoices(claude, { env: {}, platform: "linux", home: sandbox() });
     assert.equal(initialValue, AGENT_DEFAULT_MODEL);
     assert.equal(options[0].value, AGENT_DEFAULT_MODEL);
     assert.equal(options[0].label, "Por defecto del agente");
     assert.deepEqual(
-      options.slice(1, -1).map((o) => o.value),
+      options.slice(1).map((o) => o.value),
       ["opus", "sonnet", "haiku"]
     );
-    assert.equal(options.at(-1).value, OTHER_MODEL);
   });
 
   it("muestra el modelo configurado en ~/.claude/settings.json y no lo repite en la lista", () => {
@@ -127,7 +125,7 @@ describe("args", () => {
   it("claude: -p, --model solo si se eligió uno, y escritura limitada al JSON del review", () => {
     const args = claude.args({ model: "opus", outputFilename: "diff-rev_a_b.json" });
     assert.deepEqual(args.slice(0, 3), ["-p", "--model", "opus"]);
-    assert.ok(args.includes("Edit(./diff-rev_a_b.json)"));
+    assert.ok(args.includes("Edit(./.diff-review/diff-rev_a_b.json)"));
     assert.ok(!claude.args({ outputFilename: "x.json" }).includes("--model"));
   });
 
@@ -189,7 +187,7 @@ describe("copilot", () => {
     const args = copilot.args({ model: "auto", outputFilename: "diff-rev_a_b.json" });
     assert.ok(!args.includes("-p"));
     assert.deepEqual(args.slice(0, 3), ["-s", "--model", "auto"]);
-    assert.ok(args.includes("write(diff-rev_a_b.json)"));
+    assert.ok(args.includes("write(.diff-review/diff-rev_a_b.json)"));
     assert.ok(!args.includes("--allow-all-tools"));
   });
 });

package/lib/check-report.mjs

@@ -2,13 +2,20 @@
  * Valida un JSON de review y arma un texto accionable para el agente.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { globMatch } from "./config.mjs";
-import { extractBranchDiff } from "./extract.mjs";
+import { loadBranchDiff } from "./extract.mjs";
 import { tryResolveGitRoot } from "./git.mjs";
 import { decodePayload } from "./json-payload.mjs";
+import { OUTPUT_DIR } from "./output-name.mjs";
 import { REVIEW_SCHEMA, reviewIssues, validateAgainst } from "./validate.mjs";
 
+/** Raíz del repo a partir del JSON (`.diff-review/foo.json` → parent, o la carpeta del archivo legacy). */
+function repoRootFromReviewFile(absJson) {
+  const dir = dirname(absJson);
+  return basename(dir) === OUTPUT_DIR ? dirname(dir) : dir;
+}
+
 const MISSING_LIMIT = 40;
 
 /**
@@ -70,7 +77,8 @@ export function checkPayload(payload, paths = []) {
 
 /**
  * @param {string} filePath
- * @param {{ repo?: string, branch?: string, base?: string, cwd?: string }} [opts]
+ * @param {{ repo?: string, branch?: string, base?: string, cwd?: string, paths?: string[] }} [opts]
+ *   `paths`: lista ya conocida (p. ej. de la sesión); si viene, no se lee el `.diff` ni se llama a git.
  */
 export function checkReportFile(filePath, opts = {}) {
   const cwd = opts.cwd || process.cwd();
@@ -101,28 +109,38 @@ export function checkReportFile(filePath, opts = {}) {
   const branch = String(opts.branch || meta.branch || "").trim();
   const base = String(opts.base || meta.base || "develop").trim();
   const repoHint = String(opts.repo || meta.repo || "").trim();
-  const repo =
-    (repoHint && !/^(https?:\/\/|git@|ssh:\/\/)/i.test(repoHint) && tryResolveGitRoot(repoHint)) ||
-    tryResolveGitRoot(cwd);
+  const fromHint =
+    repoHint && !/^(https?:\/\/|git@|ssh:\/\/)/i.test(repoHint)
+      ? tryResolveGitRoot(repoHint) || (existsSync(repoHint) ? resolve(repoHint) : null)
+      : null;
+  const repo = fromHint || tryResolveGitRoot(cwd) || repoRootFromReviewFile(abs);
 
   /** @type {string[]} */
-  let paths = [];
+  let paths = Array.isArray(opts.paths) ? opts.paths.map(String).filter(Boolean) : [];
   /** @type {string[]} */
   const errors = [];
 
-  if (!branch) {
+  if (paths.length) {
+    /* cobertura ya resuelta por el caller */
+  } else if (!branch) {
     errors.push("Falta meta.branch (o --branch) para contrastar el diff.");
   } else if (!repo) {
     errors.push(
-      "No encontré un repo git local (meta.repo o el directorio actual). Sin eso no puedo verificar cobertura."
+      "No encontré un repo local (meta.repo, el directorio actual, o la carpeta del JSON). Sin eso no puedo verificar cobertura."
     );
   } else {
     try {
-      const extracted = extractBranchDiff({ repo, branch, base });
+      // Preferí el companion `.diff` (mismo stem que el JSON); solo cae a `git diff` si falta.
+      const extracted = loadBranchDiff({
+        repo,
+        branch,
+        base,
+        filename: basename(abs),
+      });
       paths = (extracted.files || []).map((f) => f.path);
     } catch (err) {
       errors.push(
-        `No pude listar el diff con git (${err instanceof Error ? err.message : String(err)}). Revisá meta.repo, meta.branch y meta.base.`
+        `No pude listar el diff (${err instanceof Error ? err.message : String(err)}). Revisá meta.repo, meta.branch y meta.base, o el companion .diff.`
       );
     }
   }

package/lib/extract-cache.test.mjs

@@ -0,0 +1,162 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, test } from "node:test";
+import { extractBranchDiff, parseGitDiffFiles } from "./extract.mjs";
+import { OUTPUT_DIR } from "./output-name.mjs";
+import { companionPaths, ensureReviewDir, writeDiffText } from "./review-dir.mjs";
+import { checkReportFile } from "./check-report.mjs";
+
+const sample = [
+  "diff --git a/src/a.ts b/src/a.ts",
+  "index 111..222 100644",
+  "--- a/src/a.ts",
+  "+++ b/src/a.ts",
+  "@@ -1,2 +1,3 @@",
+  " keep",
+  "-old",
+  "+new",
+  "+extra",
+  "diff --git a/package-lock.json b/package-lock.json",
+  "index 1..2 100644",
+  "--- a/package-lock.json",
+  "+++ b/package-lock.json",
+  "@@ -1 +1 @@",
+  "-{}",
+  "+{ }",
+  "diff --git a/old.ts b/new.ts",
+  "similarity index 90%",
+  "rename from old.ts",
+  "rename to new.ts",
+  "index 1..2 100644",
+  "--- a/old.ts",
+  "+++ b/new.ts",
+  "@@ -1 +1 @@",
+  "-x",
+  "+y",
+].join("\n");
+
+const dirs = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) {
+    try {
+      rmSync(d, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+});
+
+test("parseGitDiffFiles splits paths and change types", () => {
+  const files = parseGitDiffFiles(sample);
+  assert.equal(files.length, 3);
+  assert.equal(files[0].path, "src/a.ts");
+  assert.equal(files[0].changeType, "modified");
+  assert.match(files[0].hunkDiff, /^@@/);
+  assert.equal(files[1].path, "package-lock.json");
+  assert.equal(files[2].changeType, "renamed");
+  assert.equal(files[2].path, "new.ts");
+  assert.equal(files[2].oldPath, "old.ts");
+});
+
+test("extractBranchDiff with cachedDiff applies DEFAULT_IGNORE", () => {
+  const repo = mkdtempSync(join(tmpdir(), "diff-review-cache-"));
+  dirs.push(repo);
+  mkdirSync(join(repo, "src"), { recursive: true });
+  // repo path only used for config/guidelines; no git needed when cachedDiff is set
+  const skeleton = extractBranchDiff({
+    repo,
+    branch: "feature",
+    base: "develop",
+    cachedDiff: sample,
+  });
+  assert.deepEqual(
+    skeleton.files.map((f) => f.path).sort(),
+    ["new.ts", "src/a.ts"]
+  );
+  assert.ok(skeleton.context.ignored.includes("package-lock.json"));
+  assert.match(skeleton.files.find((f) => f.path === "src/a.ts").diff, /^@@/);
+});
+
+test("checkReportFile reuses companion .diff paths without inventing coverage", () => {
+  const repo = mkdtempSync(join(tmpdir(), "diff-review-check-"));
+  dirs.push(repo);
+  ensureReviewDir(repo);
+  const filename = "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json";
+  writeDiffText(repo, filename, sample);
+  const payload = {
+    meta: {
+      agent: "Cursor",
+      model: "composer",
+      repo,
+      branch: "feature",
+      base: "develop",
+    },
+    intent: "Cambia src/a.ts y renombra old.ts para dejar el módulo listo en la rama.",
+    groups: [{ id: "g1", kind: "feat", title: "Ajuste", intent: "base" }],
+    blocks: [
+      {
+        id: "b1",
+        group: "g1",
+        file: "src/a.ts",
+        lines: "L1-3",
+        op: "mod",
+        what: "cambia la lógica",
+        why: "hace falta",
+        source: "code",
+      },
+      {
+        id: "b2",
+        group: "g1",
+        file: "new.ts",
+        lines: "L1",
+        op: "rename",
+        what: "renombra el módulo",
+        why: "nombre más claro",
+        source: "code",
+      },
+    ],
+    findings: [],
+    skipped: [{ file: "package-lock.json", reason: "lockfile" }],
+  };
+  const jsonPath = companionPaths(repo, filename).json;
+  writeFileSync(jsonPath, JSON.stringify(payload));
+  // Sin git: loadBranchDiff lee el .diff y aplica ignore (lockfile fuera de paths).
+  const result = checkReportFile(jsonPath, { repo, branch: "feature", base: "develop" });
+  assert.equal(result.ok, true, result.errors.join("; "));
+});
+
+test("buildPrompt with precomputed context skips merge-base rediscovery", async () => {
+  const { buildPrompt } = await import("./prompt.mjs");
+  const text = buildPrompt(
+    { source: "local", repo: "/tmp/r", branch: "feat", base: "develop" },
+    {
+      outputFilename: "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json",
+      diffRelPath: ".diff-review/diff-rev_aaaaaaaaaa_bbbbbbbbbb.diff",
+      mergeBase: "abc123",
+      branchSha: "def456",
+      baseSha: "789abc",
+      files: [{ path: "src/a.ts", changeType: "modified" }],
+      ignored: ["package-lock.json"],
+      ignoreGlobs: ["**/package-lock.json"],
+    }
+  );
+  assert.match(text, /Precomputed git context/);
+  assert.match(text, /diff-rev_aaaaaaaaaa_bbbbbbbbbb\.diff/);
+  assert.match(text, /Merge-base SHA: `abc123`/);
+  assert.match(text, /modified: src\/a\.ts/);
+  assert.doesNotMatch(text, /Resolve the merge-base/);
+  assert.doesNotMatch(text, /Run exactly: `git diff/);
+});
+
+test("buildPrompt acp omits validate CLI", async () => {
+  const { buildPrompt, validateCliCommand } = await import("./prompt.mjs");
+  const filename = "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json";
+  const text = buildPrompt(
+    { source: "local", repo: "/tmp/r", branch: "feat", base: "develop" },
+    { outputFilename: filename, acp: true, diffRelPath: `.${OUTPUT_DIR}/${filename.replace(/\.json$/, ".diff")}` }
+  );
+  assert.doesNotMatch(text, new RegExp(validateCliCommand(filename).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  assert.match(text, /host validates/i);
+});

package/lib/extract.mjs

@@ -2,14 +2,195 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { capDiff, collectGuidelines, isIgnored, isTestPath, loadReviewConfig } from "./config.mjs";
 import { commitLog, git } from "./git.mjs";
+import { readDiffCache } from "./review-dir.mjs";
 
 export function flattenFiles(report) {
   return Array.isArray(report?.files) ? report.files : [];
 }
 
-export function extractBranchDiff({ repo, branch, base = "develop" }) {
+/**
+ * Parte un `git diff` multi-archivo (texto de `writeDiffCache`) en entradas por path.
+ * @param {string} text
+ * @returns {Array<{ path: string, oldPath?: string, changeType: string, hunkDiff: string }>}
+ */
+export function parseGitDiffFiles(text) {
+  const raw = String(text || "").replace(/\r\n/g, "\n");
+  if (!raw.trim()) return [];
+
+  const parts = raw.split(/^diff --git /m);
+  /** @type {Array<{ path: string, oldPath?: string, changeType: string, hunkDiff: string }>} */
+  const out = [];
+
+  for (const part of parts) {
+    const chunk = part.trimStart();
+    if (!chunk) continue;
+
+    const firstNl = chunk.indexOf("\n");
+    const firstLine = (firstNl === -1 ? chunk : chunk.slice(0, firstNl)).trim();
+    // `a/path b/path` (paths sin espacios raros; el formato de git suele ser este)
+    const paths = firstLine.match(/^a\/(.+) b\/(.+)$/);
+    if (!paths) continue;
+
+    let oldPath = paths[1];
+    let path = paths[2];
+    const body = firstNl === -1 ? "" : chunk.slice(firstNl + 1);
+
+    let changeType = "modified";
+    if (/^new file mode /m.test(body) || /^--- \/dev\/null/m.test(body)) changeType = "added";
+    else if (/^deleted file mode /m.test(body) || /^\+\+\+ \/dev\/null/m.test(body)) changeType = "deleted";
+    else if (/^rename from /m.test(body) || /^rename to /m.test(body)) {
+      changeType = "renamed";
+      const from = body.match(/^rename from (.+)$/m);
+      const to = body.match(/^rename to (.+)$/m);
+      if (from) oldPath = from[1].trim();
+      if (to) path = to[1].trim();
+    }
+
+    let hunkDiff = "";
+    const idx = `\n${body}`.indexOf("\n@@");
+    if (idx !== -1) hunkDiff = `\n${body}`.slice(idx + 1);
+    else if (/^Binary files /m.test(body)) hunkDiff = "";
+
+    out.push({
+      path,
+      oldPath: oldPath !== path ? oldPath : undefined,
+      changeType,
+      hunkDiff,
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Stats baratos desde el texto del diff (sin volver a llamar a git).
+ * @param {string} text
+ */
+function statsFromDiffText(text) {
+  let insertions = 0;
+  let deletions = 0;
+  for (const line of String(text || "").split("\n")) {
+    if (!line.length) continue;
+    if (line.startsWith("+++") || line.startsWith("---") || line.startsWith("diff ") || line.startsWith("index ")) {
+      continue;
+    }
+    if (line.startsWith("+")) insertions += 1;
+    else if (line.startsWith("-")) deletions += 1;
+  }
+  return { insertions, deletions };
+}
+
+/**
+ * Tips / merge-base si git responde; si no, strings vacíos (el contenido del diff ya viene del cache).
+ */
+function tryTips(repo, branch, base) {
+  try {
+    return {
+      mergeBase: git(repo, ["merge-base", base, branch]).trim(),
+      branchSha: git(repo, ["rev-parse", branch]).trim(),
+      baseSha: git(repo, ["rev-parse", base]).trim(),
+    };
+  } catch {
+    return { mergeBase: "", branchSha: "", baseSha: "" };
+  }
+}
+
+/**
+ * Arma el mismo shape que `extractBranchDiff` a partir de un texto de `git diff` ya cacheado.
+ * No vuelve a correr `git diff`.
+ */
+function skeletonFromCachedDiff(repo, branch, base, cachedDiff) {
+  const config = loadReviewConfig(repo);
+  const tips = tryTips(repo, branch, base);
+  const parsed = parseGitDiffFiles(cachedDiff);
+
+  const ignored = [];
+  const included = [];
+  for (const f of parsed) {
+    if (isIgnored(f.path, config.ignore)) ignored.push(f.path);
+    else included.push(f);
+  }
+
+  const files = included.map((f) => {
+    const capped = capDiff(f.hunkDiff);
+    return {
+      path: f.path,
+      oldPath: f.oldPath || undefined,
+      changeType: f.changeType,
+      diff: capped.diff,
+      diffChars: capped.diffChars,
+      truncated: capped.truncated,
+      modelChars: capped.diff.length,
+      group: "",
+    };
+  });
+
+  const { insertions, deletions } = statsFromDiffText(cachedDiff);
+  let commits = [];
+  if (tips.mergeBase) {
+    try {
+      commits = commitLog(repo, tips.mergeBase, branch);
+    } catch {
+      commits = [];
+    }
+  }
+
+  return {
+    version: 2,
+    repo,
+    branch,
+    baseBranch: base,
+    mergeBase: tips.mergeBase,
+    branchSha: tips.branchSha,
+    baseSha: tips.baseSha,
+    generatedAt: new Date().toISOString(),
+    intent: "",
+    stats: {
+      filesChanged: files.length,
+      filesIgnored: ignored.length,
+      filesTruncated: files.filter((f) => f.truncated).length,
+      insertions,
+      deletions,
+    },
+    context: {
+      commits,
+      rules: config.rules,
+      rulesFile: config.rulesFile,
+      ignored: ignored.slice(0, 40),
+      testsTouched: files.filter((f) => isTestPath(f.path)).map((f) => f.path),
+      testsMissing: files.filter((f) => !isTestPath(f.path)).length,
+      guidelines: collectGuidelines(repo, files.map((f) => f.path), {
+        rulesFile: config.rulesFile,
+        skipNames: config.rules.trim() ? [config.rulesFile] : [],
+        maxDepth: 1,
+        maxChars: 8_000,
+        maxTotalChars: 12_000,
+      }),
+    },
+    files,
+    groups: [],
+    blocks: [],
+    findings: [],
+    skipped: [],
+  };
+}
+
+/**
+ * @param {{
+ *   repo: string,
+ *   branch: string,
+ *   base?: string,
+ *   cachedDiff?: string | null,
+ * }} opts
+ *   `cachedDiff`: texto de `git diff base...branch` ya materializado; si viene, no se vuelve a calcular el diff.
+ */
+export function extractBranchDiff({ repo, branch, base = "develop", cachedDiff = null } = {}) {
   if (!branch) throw new Error("Falta el branch a revisar.");
 
+  if (typeof cachedDiff === "string" && cachedDiff.length) {
+    return skeletonFromCachedDiff(repo, branch, base, cachedDiff);
+  }
+
   const config = loadReviewConfig(repo);
   const mergeBase = git(repo, ["merge-base", base, branch]).trim();
   const branchSha = git(repo, ["rev-parse", branch]).trim();
@@ -103,6 +284,21 @@ export function extractBranchDiff({ repo, branch, base = "develop" }) {
   };
 }
 
+/**
+ * Preferí el companion `.diff` en `.diff-review/` si existe; si no, `git diff` vía `extractBranchDiff`.
+ * @param {{ repo: string, branch: string, base?: string, filename?: string }} opts
+ */
+export function loadBranchDiff({ repo, branch, base = "develop", filename } = {}) {
+  const name = String(filename || "").trim();
+  if (name) {
+    const cached = readDiffCache(repo, name);
+    if (cached != null && cached.length) {
+      return extractBranchDiff({ repo, branch, base, cachedDiff: cached });
+    }
+  }
+  return extractBranchDiff({ repo, branch, base });
+}
+
 export function writeSkeleton(outPath, skeleton) {
   const resolved = resolve(outPath);
   mkdirSync(dirname(resolved), { recursive: true });