@jpkme/diff-review 0.1.3 → 0.1.5

package/lib/json-payload.test.mjs

@@ -0,0 +1,22 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { decodePayload } from "./json-payload.mjs";
+
+test("decodePayload parses raw JSON", () => {
+  assert.deepEqual(decodePayload('{"intent":"hola mundo largo para cumplir minimo"}'), {
+    intent: "hola mundo largo para cumplir minimo",
+  });
+});
+
+test("decodePayload parses fenced JSON", () => {
+  assert.deepEqual(decodePayload('```json\n{"intent":"ok"}\n```'), { intent: "ok" });
+});
+
+test("decodePayload rescues JSON with prose around", () => {
+  assert.deepEqual(decodePayload("Here:\n{\"intent\":\"x\"}\nDone."), { intent: "x" });
+});
+
+test("decodePayload fails on garbage", () => {
+  assert.throws(() => decodePayload(""), /vacía/);
+  assert.throws(() => decodePayload("no json here"), /JSON/i);
+});

package/lib/output-name.mjs

@@ -0,0 +1,44 @@
+/**
+ * Nombre del JSON que escribe el agente.
+ * Preferido: tips cortos branch/base. Legacy (con stamp o sin tips) sigue válido al importar.
+ */
+import { fingerprint } from "./git.mjs";
+
+/** Prefijo del formato actual. */
+export const OUTPUT_PREFIX = "diff-rev";
+
+/** Prefijo legacy (sin tips / con stamp). */
+export const OUTPUT_PREFIX_LEGACY = "diff-review-output";
+export const OUTPUT_PREFIX_REPORT = "diff-report";
+
+/** Nombre legacy fijo. */
+export const OUTPUT_FILENAME_LEGACY = `${OUTPUT_PREFIX_LEGACY}.json`;
+
+/**
+ * Válidos:
+ * - diff-rev_{branchTip}_{baseTip}.json
+ * - diff-report_{branchTip}-{baseTip}_YYYYMMDD-HHmmss.json (legacy)
+ * - diff-review-output.json / diff-review-output-YYYYMMDD-HHmmss.json (legacy)
+ */
+export const OUTPUT_FILENAME_RE =
+  /^(?:diff-rev_[0-9a-f]{7,12}_[0-9a-f]{7,12}|diff-report_[0-9a-f]{7,12}-[0-9a-f]{7,12}_\d{8}-\d{6}|diff-review-output(?:-\d{8}-\d{6})?)\.json$/i;
+
+/**
+ * @param {{ branchSha?: string, baseSha?: string }} [input]
+ * @returns {string}
+ *   con tips: diff-rev_aaaaaaaaaa_bbbbbbbbbb.json
+ *   sin tips: diff-review-output.json
+ */
+export function makeOutputFilename(input = {}) {
+  const opts = input instanceof Date ? {} : input || {};
+  const fp = fingerprint(opts.branchSha, opts.baseSha);
+  if (fp) {
+    const [branchTip, baseTip] = fp.split("-");
+    if (branchTip && baseTip) return `${OUTPUT_PREFIX}_${branchTip}_${baseTip}.json`;
+  }
+  return OUTPUT_FILENAME_LEGACY;
+}
+
+export function isOutputFilename(name) {
+  return OUTPUT_FILENAME_RE.test(String(name || "").trim());
+}

package/lib/output-name.test.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  isOutputFilename,
+  makeOutputFilename,
+  OUTPUT_FILENAME_LEGACY,
+} from "./output-name.mjs";
+
+describe("output-name", () => {
+  it("builds name with short tip hashes", () => {
+    const name = makeOutputFilename({
+      branchSha: "aaaaaaaaaa1111111111",
+      baseSha: "bbbbbbbbbb2222222222",
+    });
+    assert.equal(name, "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json");
+    assert.equal(isOutputFilename(name), true);
+  });
+
+  it("falls back to legacy without tips", () => {
+    assert.equal(makeOutputFilename({}), OUTPUT_FILENAME_LEGACY);
+    assert.equal(isOutputFilename(OUTPUT_FILENAME_LEGACY), true);
+  });
+
+  it("accepts legacy stamped and report names", () => {
+    assert.equal(isOutputFilename("diff-review-output-20260915-143045.json"), true);
+    assert.equal(
+      isOutputFilename("diff-report_aaaaaaaaaa-bbbbbbbbbb_20260915-143045.json"),
+      true
+    );
+  });
+
+  it("rejects other names", () => {
+    assert.equal(isOutputFilename("review.json"), false);
+    assert.equal(isOutputFilename("diff-review-output-foo.json"), false);
+    assert.equal(isOutputFilename("diff-rev_short_tips.json"), false);
+  });
+});

package/lib/pick-folder.mjs

@@ -0,0 +1,4 @@
+/** La app web usa web/src/lib/server/pick-folder.ts. */
+export async function pickFolder() {
+  throw new Error("Usá la app web (pick-folder del server) para elegir carpeta.");
+}

package/lib/prompt.mjs

@@ -0,0 +1,160 @@
+/**
+ * Prompt de review para el agente (compartido CLI + UI).
+ * Mantener alineado con el contrato de schema.json / validate.mjs.
+ */
+import {
+  makeOutputFilename,
+  isOutputFilename,
+  OUTPUT_FILENAME_LEGACY,
+} from "./output-name.mjs";
+
+export {
+  makeOutputFilename,
+  isOutputFilename,
+  OUTPUT_FILENAME_LEGACY,
+};
+
+export const OUTPUT_SCHEMA_BLOCK = `{
+  "meta": {
+    "source": "local|url",
+    "repo": "<absolute path or git URL>",
+    "branch": "<branch under review>",
+    "base": "develop",
+    "remoteUrl": "<origin URL; optional when source=url>",
+    "generatedAt": "<ISO-8601 datetime; optional, informational>",
+    "agent": "<tool name e.g. Claude Code / Cursor; optional, informational>",
+    "model": "<model id e.g. claude-opus-…; optional, informational>"
+  },
+  "intent": "string",
+  "groups": [
+    {
+      "id": "g1",
+      "kind": "feat|fix|refactor|perf|test|chore|docs|infra",
+      "title": "string ≤72 chars, imperative, no kind prefix",
+      "intent": "string"
+    }
+  ],
+  "blocks": [
+    {
+      "id": "b1",
+      "group": "g1",
+      "file": "relative/path.ext",
+      "lines": "L40-58",
+      "side": "new|old",
+      "start": 40,
+      "end": 58,
+      "op": "add|mod|del|rename",
+      "what": "string",
+      "why": "string",
+      "source": "code|commit|pr|issue|inferred"
+    }
+  ],
+  "findings": [
+    {
+      "id": "f1",
+      "class": "risk|quality",
+      "severity": "high|med|low|nit",
+      "blocking": false,
+      "kind": "bug|race|auth|security|api-break|missing-test|perf|maintainability|docs|other",
+      "file": "relative/path.ext",
+      "line": 87,
+      "block": "b1",
+      "what": "string",
+      "fix": "string"
+    }
+  ],
+  "skipped": [
+    { "file": "relative/path-or-glob", "reason": "generated|lockfile|format|vendored|binary|trivial|ignored" }
+  ],
+  "notes": ["optional short limitations"]
+}`;
+
+const RULES = `- Coverage (hard): every path in the diff MUST appear in "blocks" and/or "skipped". Prefer a skipped glob when many files share one reason.
+- Do NOT invent files, hunks, or line ranges that are not in the diff.
+- Line anchors: "lines"/"start"/"end"/"line" MUST match the chosen "side" ("new" = post-image / right side of @@; "old" = pre-image, typically deletions). One block per coherent change span — not one per line. Point findings at that block; leave "block" empty only if cross-cutting.
+- Do NOT report: pre-existing code outside the diff; linter/formatter noise; naming/style prefs with no real consequence; intentional branch behavior; silenced lint rules; "missing docs/coverage" without a concrete broken scenario.
+- Quality findings must name a concrete cost, not a vague feeling.
+- Signal over volume: prefer fewer high-signal findings. Order findings by severity (high → nit). Use "nit" sparingly.
+- "blocking": true ONLY if the branch should not merge as-is. Use only with class "risk".
+- Write human-readable strings (intent, title, what, why, fix, notes) in Spanish. Keep enums/ids/paths/JSON keys exactly as in the schema.`;
+
+function workflowLocal(base, branch) {
+  return `Workflow:
+1. Resolve the merge-base of \`${base}\` and \`${branch}\`.
+2. Run exactly: \`git diff ${base}...${branch}\` (three-dot / merge-base diff). Do not use two-dot unless three-dot is impossible.
+3. Read enough surrounding code (types, callers, tests) to judge behavior — not only the hunk lines.
+4. Emit the JSON file. Do not modify the repo.`;
+}
+
+function workflowUrl(base, branch) {
+  return `Workflow:
+1. If the repo is not local, clone it (or use whatever access you have). Do not modify it.
+2. Resolve the merge-base of \`${base}\` and \`${branch}\`.
+3. Run exactly: \`git diff ${base}...${branch}\` (three-dot / merge-base diff). Do not use two-dot unless three-dot is impossible.
+4. Read enough surrounding code (types, callers, tests) to judge behavior — not only the hunk lines.
+5. Emit the JSON file.`;
+}
+
+/**
+ * @param {{ source?: string, repo?: string, branch?: string, base?: string, remoteUrl?: string }} meta
+ */
+export function outputSchemaBlock(meta) {
+  const source = meta.source === "url" ? "url" : "local";
+  const repo =
+    String(meta.repo || "").trim() || (source === "url" ? "<git URL>" : "<absolute repo path>");
+  const branch = String(meta.branch || "").trim() || "<branch under review>";
+  const base = String(meta.base || "").trim() || "develop";
+  const remoteUrl = String(meta.remoteUrl || "").trim() || (source === "url" ? repo : "");
+  const metaLines = [
+    `    "source": ${JSON.stringify(source)},`,
+    `    "repo": ${JSON.stringify(repo)},`,
+    `    "branch": ${JSON.stringify(branch)},`,
+    `    "base": ${JSON.stringify(base)},`,
+  ];
+  if (remoteUrl) metaLines.push(`    "remoteUrl": ${JSON.stringify(remoteUrl)},`);
+  metaLines.push(
+    `    "generatedAt": "<ISO-8601 datetime>",`,
+    `    "agent": "<tool name, e.g. Claude Code / Cursor>",`,
+    `    "model": "<model id>"`
+  );
+  const metaBlock = `"meta": {\n${metaLines.join("\n")}\n  }`;
+  return OUTPUT_SCHEMA_BLOCK.replace(/"meta": \{[\s\S]*?\n  \}/, metaBlock);
+}
+
+/**
+ * @param {{ source?: string, repo?: string, branch?: string, base?: string, remoteUrl?: string }} meta
+ * @param {{ outputFilename?: string }} [opts]
+ */
+export function buildPrompt(meta, opts = {}) {
+  const outputFilename = opts.outputFilename || makeOutputFilename();
+  const repo =
+    String(meta.repo || "").trim() ||
+    (meta.source === "url" ? "<git URL>" : "<absolute repo path>");
+  const branch = String(meta.branch || "").trim() || "<branch under review>";
+  const base = String(meta.base || "").trim() || "develop";
+  const workflow = meta.source === "url" ? workflowUrl(base, branch) : workflowLocal(base, branch);
+
+  return `You are a senior code reviewer: strict but fair.
+
+Repo: ${repo}
+Branch under review: ${branch}
+Base (merge-base): ${base}
+
+${workflow}
+
+Rules:
+${RULES}
+
+Write the result to \`${outputFilename}\` at the repo root.
+- One JSON object only: first character \`{\`, last character \`}\`.
+- No prose before/after, no markdown fences.
+- Shape (copy "meta" source/repo/branch/base/remoteUrl as given; fill generatedAt/agent/model):
+
+${outputSchemaBlock(meta)}
+
+Include "meta" with the source/repo/branch/base above (and origin "remoteUrl" when local). Also set informational fields: "generatedAt" (ISO-8601 now), "agent" (tool name), "model" (model id). That lets someone reopen the report elsewhere without re-picking the repo.
+
+Do NOT include diffs or a "files" array — the tool computes them with git when opening the report. Do not invent hunks or paste patches into the JSON.
+
+When done, tell me that \`${outputFilename}\` was written.`;
+}

package/lib/remote-repo.mjs

@@ -0,0 +1,182 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { git } from "./git.mjs";
+
+const CACHE_ROOT = join(tmpdir(), "diff-review-clones");
+const MAX_DEEPEN_ROUNDS = 8;
+const DEEPEN_BY = "50";
+
+export function looksLikeGitUrl(value) {
+  const v = String(value || "").trim();
+  if (!v) return false;
+  if (/^(https?:\/\/|git@|ssh:\/\/)/i.test(v)) return true;
+  if (/\.git$/i.test(v) && !/^[A-Za-z]:/.test(v) && !v.startsWith("/") && !v.startsWith("\\")) {
+    return true;
+  }
+  return false;
+}
+
+export function normalizeGitUrl(url) {
+  const raw = String(url || "").trim();
+  if (!raw) throw new Error("Indicá la URL del repositorio.");
+  if (!looksLikeGitUrl(raw)) {
+    throw new Error(
+      `"${raw}" no parece una URL git. Usá https://…, git@… o ssh://…`,
+    );
+  }
+  if (/^(file:|javascript:|data:)/i.test(raw)) {
+    throw new Error("Esquema de URL no permitido.");
+  }
+  return raw.replace(/\/$/, "");
+}
+
+function cacheDirFor(url) {
+  const key = createHash("sha1").update(url).digest("hex").slice(0, 16);
+  return join(CACHE_ROOT, key);
+}
+
+function runGit(args, { cwd, timeout = 5 * 60 * 1000 } = {}) {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    windowsHide: true,
+    timeout,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+}
+
+/** Lista heads del remote sin clonar. */
+export function listRemoteBranches(url) {
+  const remote = normalizeGitUrl(url);
+  let raw;
+  try {
+    raw = runGit(["ls-remote", "--heads", remote]);
+  } catch (err) {
+    const stderr = String(/** @type {{ stderr?: string }} */ (err).stderr || err.message || err);
+    throw new Error("No se pudo listar branches del remote: " + stderr.split("\n").find(Boolean));
+  }
+
+  const branches = [
+    ...new Set(
+      raw
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => {
+          const ref = line.split("\t")[1] || "";
+          return ref.replace(/^refs\/heads\//, "");
+        })
+        .filter(Boolean),
+    ),
+  ].sort((a, b) => a.localeCompare(b));
+
+  if (!branches.length) {
+    throw new Error("El remote no expone branches (refs/heads).");
+  }
+
+  const defaultBase = branches.includes("develop")
+    ? "develop"
+    : branches.includes("main")
+      ? "main"
+      : branches.includes("master")
+        ? "master"
+        : branches[0];
+
+  return { branches, current: "", defaultBase };
+}
+
+function fetchRef(repo, ref) {
+  const name = String(ref || "").trim();
+  if (!name) return;
+  try {
+    runGit(["rev-parse", "--verify", name], { cwd: repo });
+    return;
+  } catch {
+    /* falta localmente */
+  }
+  runGit(
+    ["fetch", "--depth", DEEPEN_BY, "origin", `refs/heads/${name}:refs/heads/${name}`],
+    { cwd: repo },
+  );
+}
+
+function deepenUntilMergeBase(repo, base, branch) {
+  for (let i = 0; i < MAX_DEEPEN_ROUNDS; i++) {
+    try {
+      git(repo, ["merge-base", base, branch]);
+      return;
+    } catch {
+      runGit(
+        [
+          "fetch",
+          "--deepen",
+          DEEPEN_BY,
+          "origin",
+          `refs/heads/${base}:refs/heads/${base}`,
+          `refs/heads/${branch}:refs/heads/${branch}`,
+        ],
+        { cwd: repo },
+      );
+    }
+  }
+  throw new Error(
+    `No se encontró merge-base entre "${base}" y "${branch}" (historial shallow insuficiente). Probá con más historia o usá una carpeta local.`,
+  );
+}
+
+/**
+ * Asegura un worktree local (cache en tmp) con branch y base disponibles para diff.
+ * @returns {string} ruta absoluta del clone
+ */
+export function ensureRemoteWorktree(url, branch, base = "develop") {
+  const remote = normalizeGitUrl(url);
+  const b = String(branch || "").trim();
+  const baseRef = String(base || "develop").trim() || "develop";
+  if (!b) throw new Error("Falta el branch a revisar.");
+
+  mkdirSync(CACHE_ROOT, { recursive: true });
+  const dir = cacheDirFor(remote);
+  const gitDir = join(dir, ".git");
+
+	if (!existsSync(gitDir)) {
+		if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+		try {
+			runGit(
+				[
+					"clone",
+					"--filter=blob:none",
+					"--depth",
+					DEEPEN_BY,
+					"--branch",
+					b,
+					remote,
+					dir,
+				],
+				{ timeout: 10 * 60 * 1000 },
+			);
+		} catch (err) {
+			if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+			const stderr = String(/** @type {{ stderr?: string }} */ (err).stderr || err.message || err);
+			throw new Error("No se pudo clonar el repo: " + stderr.split("\n").find(Boolean));
+		}
+	} else {
+		try {
+			runGit(["remote", "set-url", "origin", remote], { cwd: dir });
+		} catch {
+			/* remote ya ok */
+		}
+		fetchRef(dir, b);
+		try {
+			runGit(["checkout", "--force", b], { cwd: dir });
+		} catch {
+			/* detached / already on branch */
+		}
+	}
+
+  if (baseRef !== b) fetchRef(dir, baseRef);
+  deepenUntilMergeBase(dir, baseRef, b);
+  return dir;
+}

package/lib/review.mjs

@@ -0,0 +1,228 @@
+import {
+  BLOCK_OPS,
+  FINDING_CLASSES,
+  FINDING_KINDS,
+  FINDING_SEVERITIES,
+  GROUP_KINDS,
+  SKIP_REASONS,
+  WHY_SOURCES,
+} from "./validate.mjs";
+
+const MAX = {
+  intent: 700,
+  groupTitle: 100,
+  groupIntent: 300,
+  what: 240,
+  why: 240,
+  finding: 360,
+};
+
+function text(value, max) {
+  const raw = String(value ?? "").replace(/\s+/g, " ").trim();
+  return raw.length > max ? `${raw.slice(0, max - 1).trimEnd()}…` : raw;
+}
+
+function oneOf(value, allowed, fallback) {
+  const raw = String(value ?? "").trim().toLowerCase();
+  return allowed.includes(raw) ? raw : fallback;
+}
+
+/**
+ * Rango de líneas de un bloque. `L40-58` es post-imagen (lo que quedó);
+ * `-L88-95` es pre-imagen, que es la única forma de señalar líneas borradas.
+ */
+export function parseLineRange(value) {
+  const raw = String(value ?? "").trim();
+  const match = /^(-)?L?(\d+)(?:\s*[-–]\s*L?(\d+))?$/i.exec(raw);
+  if (!match) return null;
+  const start = Number(match[2]);
+  const end = match[3] ? Number(match[3]) : start;
+  return {
+    side: match[1] ? "old" : "new",
+    start: Math.min(start, end),
+    end: Math.max(start, end),
+  };
+}
+
+export function formatLineRange(range) {
+  if (!range) return "";
+  const prefix = range.side === "old" ? "-L" : "L";
+  return range.start === range.end ? `${prefix}${range.start}` : `${prefix}${range.start}-${range.end}`;
+}
+
+export function countHunks(files) {
+  let total = 0;
+  for (const file of files || []) {
+    for (const line of String(file.diff || "").split("\n")) {
+      if (line.startsWith("@@")) total += 1;
+    }
+  }
+  return total;
+}
+
+function normalizeGroups(raw) {
+  const seen = new Set();
+  const groups = [];
+  for (const item of raw || []) {
+    const id = String(item?.id || "").trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    groups.push({
+      id,
+      kind: oneOf(item.kind, GROUP_KINDS, "chore"),
+      title: text(item.title, MAX.groupTitle) || `${oneOf(item.kind, GROUP_KINDS, "chore")}: cambios`,
+      intent: text(item.intent, MAX.groupIntent),
+    });
+  }
+  return groups;
+}
+
+function normalizeBlocks(raw, { groupIds, knownPaths }) {
+  const seen = new Set();
+  const blocks = [];
+  for (const item of raw || []) {
+    const id = String(item?.id || "").trim();
+    const group = String(item?.group || "").trim();
+    const file = String(item?.file || "").trim();
+    if (!id || seen.has(id)) continue;
+    if (!groupIds.has(group)) continue;
+    if (knownPaths.size && !knownPaths.has(file)) continue;
+    const range = parseLineRange(item.lines);
+    seen.add(id);
+    blocks.push({
+      id,
+      group,
+      file,
+      lines: range ? formatLineRange(range) : text(item.lines, 24),
+      side: range?.side || "new",
+      start: range?.start ?? 0,
+      end: range?.end ?? 0,
+      op: oneOf(item.op, BLOCK_OPS, "mod"),
+      what: text(item.what, MAX.what),
+      why: text(item.why, MAX.why),
+      source: oneOf(item.source, WHY_SOURCES, "inferred"),
+    });
+  }
+  blocks.sort((a, b) => a.file.localeCompare(b.file) || a.start - b.start);
+  return blocks;
+}
+
+function findingKey(finding) {
+  return [finding.file, finding.line ?? "", finding.kind, finding.what].join("|");
+}
+
+function normalizeFindings(raw, { blockIds, knownPaths }) {
+  const seen = new Set();
+  const findings = [];
+  for (const item of raw || []) {
+    const file = String(item?.file || item?.path || "").trim();
+    const what = text(item?.what || item?.title, MAX.finding);
+    if (!file || !what) continue;
+    if (knownPaths.size && !knownPaths.has(file)) continue;
+    const cls = oneOf(item.class, FINDING_CLASSES, "risk");
+    const severity = oneOf(item.severity, FINDING_SEVERITIES, "med");
+    const block = String(item?.block || "").trim();
+    const line = Number.isFinite(Number(item?.line)) ? Number(item.line) : null;
+    const finding = {
+      id: "",
+      class: cls,
+      severity,
+      // Una mejora de calidad nunca frena un merge, diga lo que diga el modelo;
+      // un riesgo alto sí, aunque el modelo se haya olvidado de marcarlo.
+      blocking: cls === "risk" && (item?.blocking === true || severity === "high"),
+      kind: oneOf(item.kind, FINDING_KINDS, "other"),
+      file,
+      line,
+      block: blockIds.has(block) ? block : "",
+      what,
+      fix: text(item.fix || item.detail, MAX.finding),
+    };
+    const key = findingKey(finding);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    findings.push(finding);
+  }
+  const rank = { high: 0, med: 1, low: 2, nit: 3 };
+  findings.sort(
+    (a, b) =>
+      Number(b.blocking) - Number(a.blocking) ||
+      (a.class === b.class ? 0 : a.class === "risk" ? -1 : 1) ||
+      rank[a.severity] - rank[b.severity] ||
+      a.file.localeCompare(b.file),
+  );
+  findings.forEach((finding, i) => {
+    finding.id = `f${i + 1}`;
+  });
+  return findings;
+}
+
+function normalizeSkipped(raw, ignored) {
+  const byFile = new Map();
+  for (const path of ignored || []) {
+    byFile.set(String(path), { file: String(path), reason: "ignored" });
+  }
+  for (const item of raw || []) {
+    const file = String(item?.file || "").trim();
+    if (!file) continue;
+    byFile.set(file, { file, reason: oneOf(item.reason, SKIP_REASONS, "trivial") });
+  }
+  return [...byFile.values()];
+}
+
+/** Tema donde se dibuja el archivo: el que aporta más bloques, desempatando por orden de tema. */
+export function dominantGroup(blocks, path, groupOrder) {
+  const tally = new Map();
+  for (const block of blocks) {
+    if (block.file !== path) continue;
+    tally.set(block.group, (tally.get(block.group) || 0) + 1);
+  }
+  if (!tally.size) return "";
+  return [...tally.entries()].sort(
+    (a, b) => b[1] - a[1] || groupOrder.indexOf(a[0]) - groupOrder.indexOf(b[0]),
+  )[0][0];
+}
+
+/**
+ * Documento final: lo que dijo el modelo, saneado y cruzado contra los archivos
+ * reales del diff. Todo lo que no cierra se descarta acá en vez de romper la UI.
+ */
+export function buildReview({ skeleton, payload, notes = [] }) {
+  const files = skeleton.files || [];
+  const knownPaths = new Set(files.map((f) => f.path));
+
+  const groups = normalizeGroups(payload?.groups);
+  const groupIds = new Set(groups.map((g) => g.id));
+  const blocks = normalizeBlocks(payload?.blocks, { groupIds, knownPaths });
+  const blockIds = new Set(blocks.map((b) => b.id));
+  const findings = normalizeFindings(payload?.findings, { blockIds, knownPaths });
+  const skipped = normalizeSkipped(payload?.skipped, skeleton.context?.ignored);
+
+  const usedGroups = new Set(blocks.map((b) => b.group));
+  const liveGroups = groups.filter((g) => usedGroups.has(g.id));
+  const groupOrder = liveGroups.map((g) => g.id);
+
+  const skippedFiles = new Set(skipped.map((s) => s.file));
+  const orphans = files.filter((f) => !blocks.some((b) => b.file === f.path) && !skippedFiles.has(f.path));
+  if (orphans.length) {
+    notes = [...notes, `${orphans.length} archivo(s) quedaron sin explicación del modelo.`];
+  }
+
+  const decorated = files.map((file) => ({
+    ...file,
+    group: dominantGroup(blocks, file.path, groupOrder),
+  }));
+
+  return {
+    ...skeleton,
+    version: 2,
+    intent: text(payload?.intent, MAX.intent),
+    groups: liveGroups,
+    blocks,
+    findings,
+    skipped,
+    files: decorated,
+    stats: { ...skeleton.stats, hunks: countHunks(files) },
+    notes,
+    generatedAt: new Date().toISOString(),
+  };
+}