@jpkme/diff-review 0.1.3 → 0.1.4

package/lib/extract.mjs

@@ -0,0 +1,111 @@
+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";
+
+export function flattenFiles(report) {
+  return Array.isArray(report?.files) ? report.files : [];
+}
+
+export function extractBranchDiff({ repo, branch, base = "develop" }) {
+  if (!branch) throw new Error("Falta el branch a revisar.");
+
+  const config = loadReviewConfig(repo);
+  const mergeBase = git(repo, ["merge-base", base, branch]).trim();
+  const branchSha = git(repo, ["rev-parse", branch]).trim();
+  const baseSha = git(repo, ["rev-parse", base]).trim();
+
+  const nameStatus = git(repo, ["diff", mergeBase, branch, "--name-status"])
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => {
+      const [status, ...rest] = line.split("\t");
+      const path = rest[rest.length - 1];
+      const oldPath = rest.length > 1 ? rest[0] : null;
+      let changeType = "modified";
+      if (status.startsWith("A")) changeType = "added";
+      else if (status.startsWith("D")) changeType = "deleted";
+      else if (status.startsWith("R")) changeType = "renamed";
+      return { path, oldPath, changeType };
+    });
+
+  const ignored = [];
+  const included = [];
+  for (const f of nameStatus) {
+    if (isIgnored(f.path, config.ignore)) ignored.push(f.path);
+    else included.push(f);
+  }
+
+  const files = included.map((f) => {
+    let raw = "";
+    try {
+      raw = git(repo, ["diff", mergeBase, branch, "--", f.path]);
+      const idx = raw.indexOf("\n@@");
+      if (idx !== -1) raw = raw.slice(idx + 1);
+    } catch {
+      raw = "";
+    }
+    const capped = capDiff(raw);
+    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 shortstat = git(repo, ["diff", mergeBase, branch, "--shortstat"]).trim();
+  const insMatch = shortstat.match(/(\d+) insertion/);
+  const delMatch = shortstat.match(/(\d+) deletion/);
+
+  return {
+    version: 2,
+    repo,
+    branch,
+    baseBranch: base,
+    mergeBase,
+    branchSha,
+    baseSha,
+    generatedAt: new Date().toISOString(),
+    intent: "",
+    stats: {
+      filesChanged: files.length,
+      filesIgnored: ignored.length,
+      filesTruncated: files.filter((f) => f.truncated).length,
+      insertions: insMatch ? Number(insMatch[1]) : 0,
+      deletions: delMatch ? Number(delMatch[1]) : 0,
+    },
+    context: {
+      commits: commitLog(repo, mergeBase, branch),
+      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: [],
+  };
+}
+
+export function writeSkeleton(outPath, skeleton) {
+  const resolved = resolve(outPath);
+  mkdirSync(dirname(resolved), { recursive: true });
+  writeFileSync(resolved, JSON.stringify(skeleton, null, 2), "utf8");
+  return resolved;
+}

package/lib/git.mjs

@@ -0,0 +1,202 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export function assertGitRepo(repo) {
+  const raw = String(repo || "").trim();
+  if (!raw) {
+    throw new Error("Indicá la ruta absoluta de un repositorio git.");
+  }
+  if (!/[\\/]/.test(raw) && !/^[A-Za-z]:/.test(raw)) {
+    throw new Error(
+      `"${raw}" no es una ruta. Pegá la ruta absoluta del repo (ej. C:\\tienda-argenta\\tienda-argenta-2).`,
+    );
+  }
+  const resolved = resolve(raw);
+  if (!resolved || resolved === ".") {
+    throw new Error("Indicá la ruta absoluta de un repositorio git.");
+  }
+  if (!existsSync(resolved)) {
+    throw new Error(`No existe la carpeta: ${resolved}`);
+  }
+  if (!existsSync(join(resolved, ".git"))) {
+    throw new Error(`No es un repositorio git (falta .git): ${resolved}`);
+  }
+  return resolved;
+}
+
+/**
+ * Si `cwd` está dentro de un repo git, devuelve la raíz absoluta; si no, null.
+ * Acepta subcarpetas (usa `git rev-parse --show-toplevel`).
+ */
+export function tryResolveGitRoot(cwd) {
+  const raw = String(cwd || "").trim();
+  if (!raw) return null;
+  const dir = resolve(raw);
+  if (!existsSync(dir)) return null;
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: dir,
+      encoding: "utf8",
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return root ? resolve(root) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function git(repo, args, { maxBuffer = 64 * 1024 * 1024 } = {}) {
+  return execFileSync("git", args, {
+    cwd: repo,
+    encoding: "utf8",
+    maxBuffer,
+    windowsHide: true,
+  });
+}
+
+export function slug(s) {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/(^-|-$)/g, "");
+}
+
+export function resolveRev(repo, ref) {
+  return git(repo, ["rev-parse", ref]).trim();
+}
+
+export function branchTips(repo, branch, base) {
+  return {
+    branchSha: resolveRev(repo, branch),
+    baseSha: resolveRev(repo, base),
+  };
+}
+
+export function fingerprint(branchSha, baseSha) {
+  const a = shortSha(branchSha);
+  const b = shortSha(baseSha);
+  if (!a || !b) return null;
+  return `${a}-${b}`;
+}
+
+/** File/URL id: short tip of the reviewed branch + short tip of the base. */
+export function reportId(branchSha, baseSha) {
+  const id = fingerprint(branchSha, baseSha);
+  if (!id) throw new Error("Faltan SHAs de los tips para el id del reporte.");
+  return id;
+}
+
+function shortSha(sha, n = 10) {
+  const hex = String(sha || "").toLowerCase().replace(/[^a-f0-9]/g, "");
+  return hex.length >= 7 ? hex.slice(0, n) : "";
+}
+
+export function commitLog(repo, mergeBase, branch, limit = 25) {
+  try {
+    return git(repo, [
+      "log",
+      "--oneline",
+      "--no-merges",
+      "-n",
+      String(limit),
+      `${mergeBase}..${branch}`,
+    ])
+      .trim()
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+const FILE_LINE_CACHE = new Map();
+const FILE_LINE_CACHE_MAX = 48;
+
+function rememberFileLines(key, lines) {
+  if (FILE_LINE_CACHE.has(key)) FILE_LINE_CACHE.delete(key);
+  FILE_LINE_CACHE.set(key, lines);
+  while (FILE_LINE_CACHE.size > FILE_LINE_CACHE_MAX) {
+    const oldest = FILE_LINE_CACHE.keys().next().value;
+    FILE_LINE_CACHE.delete(oldest);
+  }
+}
+
+export function showFileLines(repo, rev, path) {
+  const resolved = assertGitRepo(repo);
+  const safeRev = String(rev || "").trim();
+  const safePath = String(path || "").replace(/\\/g, "/").trim();
+  if (!safeRev || !/^[A-Za-z0-9._/\-]+$/.test(safeRev)) {
+    throw new Error("Rev inválido.");
+  }
+  if (!safePath || safePath.startsWith("/") || safePath.includes("..") || safePath.includes("\0")) {
+    throw new Error("Ruta inválida.");
+  }
+  const key = `${resolved}\0${safeRev}\0${safePath}`;
+  if (FILE_LINE_CACHE.has(key)) return FILE_LINE_CACHE.get(key);
+  let text;
+  try {
+    text = git(resolved, ["show", `${safeRev}:${safePath}`]);
+  } catch {
+    rememberFileLines(key, null);
+    return null;
+  }
+  if (text.includes("\0")) {
+    rememberFileLines(key, null);
+    return null;
+  }
+  const raw = text.replace(/\r\n/g, "\n");
+  const lines = raw.endsWith("\n") ? raw.slice(0, -1).split("\n") : raw.split("\n");
+  rememberFileLines(key, lines);
+  return lines;
+}
+
+export function listBranches(repo) {
+  const raw = git(repo, [
+    "for-each-ref",
+    "--sort=-committerdate",
+    "--format=%(refname:short)",
+    "refs/heads",
+    "refs/remotes",
+  ]);
+  const names = raw
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((name) => name.replace(/^origin\//, ""))
+    .filter((name) => name !== "HEAD" && !name.endsWith("/HEAD"));
+
+  // Dedup conservando el orden de for-each-ref (más reciente primero).
+  const unique = [...new Set(names)];
+
+  const current = git(repo, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+  const bases = unique.filter((n) => n === "develop" || n === "main" || n === "master");
+  const defaultBase = bases.includes("develop")
+    ? "develop"
+    : bases.includes("main")
+      ? "main"
+      : bases[0] || "develop";
+
+  return { branches: unique, current, defaultBase };
+}
+
+/** URL del remote (origin, o el primero disponible). Vacío si no hay. */
+export function getRemoteUrl(repo, preferred = "origin") {
+  try {
+    const url = git(repo, ["remote", "get-url", preferred]).trim();
+    if (url) return url;
+  } catch {
+    /* sin origin */
+  }
+  try {
+    const remotes = git(repo, ["remote"])
+      .split("\n")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (!remotes.length) return "";
+    return git(repo, ["remote", "get-url", remotes[0]]).trim();
+  } catch {
+    return "";
+  }
+}

package/lib/git.test.mjs

@@ -0,0 +1,29 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { fingerprint, reportId, tryResolveGitRoot } from "./git.mjs";
+
+const branch = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
+const base = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+test("reportId is short branch tip then base tip, hyphenated", () => {
+  assert.equal(reportId(branch, base), "aaaaaaaaaa-bbbbbbbbbb");
+  assert.equal(fingerprint(branch, base), "aaaaaaaaaa-bbbbbbbbbb");
+});
+
+test("reportId rejects missing shas", () => {
+  assert.equal(fingerprint("", base), null);
+  assert.throws(() => reportId("", base), /Faltan SHAs/);
+});
+
+test("tryResolveGitRoot finds repo from subdirectory", () => {
+  const root = tryResolveGitRoot(join(repoRoot, "lib"));
+  assert.ok(root);
+  assert.match(root.replace(/\\/g, "/"), /diff-review$/i);
+});
+
+test("tryResolveGitRoot returns null outside a repo", () => {
+  assert.equal(tryResolveGitRoot(dirname(repoRoot)), null);
+});

package/lib/json-payload.mjs

@@ -0,0 +1,31 @@
+function tryParseJson(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+
+/** Extrae un objeto JSON del texto del modelo (fences, prosa alrededor, envelope). */
+export function decodePayload(text) {
+  const raw = String(text || "").trim();
+  if (!raw) throw new Error("Respuesta vacía.");
+
+  const fence = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence) {
+    const parsed = tryParseJson(fence[1].trim());
+    if (parsed && typeof parsed === "object") return parsed;
+  }
+
+  const direct = tryParseJson(raw);
+  if (direct && typeof direct === "object") return direct;
+
+  const start = raw.indexOf("{");
+  const end = raw.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    const parsed = tryParseJson(raw.slice(start, end + 1));
+    if (parsed && typeof parsed === "object") return parsed;
+  }
+
+  throw new Error("No se pudo interpretar la respuesta como JSON.");
+}

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,56 @@
+/**
+ * Nombre del JSON que escribe el agente.
+ * Preferido: tips cortos + stamp. Legacy sin tips sigue siendo válido al importar.
+ */
+import { fingerprint } from "./git.mjs";
+
+/** Prefijo del formato actual (con tips). */
+export const OUTPUT_PREFIX = "diff-report";
+
+/** Prefijo legacy (sin tips). */
+export const OUTPUT_PREFIX_LEGACY = "diff-review-output";
+
+/** Nombre legacy fijo. */
+export const OUTPUT_FILENAME_LEGACY = `${OUTPUT_PREFIX_LEGACY}.json`;
+
+/**
+ * Válidos:
+ * - diff-review-output.json
+ * - diff-review-output-YYYYMMDD-HHmmss.json
+ * - diff-report_{branchTip}-{baseTip}_YYYYMMDD-HHmmss.json
+ */
+export const OUTPUT_FILENAME_RE =
+  /^(?:diff-review-output(?:-\d{8}-\d{6})?|diff-report_[0-9a-f]{7,12}-[0-9a-f]{7,12}_\d{8}-\d{6})\.json$/i;
+
+/**
+ * @param {Date} [when]
+ * @returns {string} ej. 20260915-143045
+ */
+export function formatOutputStamp(when = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0");
+  const y = when.getFullYear();
+  const mo = pad(when.getMonth() + 1);
+  const d = pad(when.getDate());
+  const h = pad(when.getHours());
+  const mi = pad(when.getMinutes());
+  const s = pad(when.getSeconds());
+  return `${y}${mo}${d}-${h}${mi}${s}`;
+}
+
+/**
+ * @param {{ branchSha?: string, baseSha?: string, stamp?: string, when?: Date } | Date} [input]
+ * @returns {string}
+ *   con tips: diff-report_aaaaaaaaaa-bbbbbbbbbb_20260915-143045.json
+ *   sin tips: diff-review-output-20260915-143045.json
+ */
+export function makeOutputFilename(input = {}) {
+  const opts = input instanceof Date ? { when: input } : input || {};
+  const stamp = opts.stamp || formatOutputStamp(opts.when ?? new Date());
+  const fp = fingerprint(opts.branchSha, opts.baseSha);
+  if (fp) return `${OUTPUT_PREFIX}_${fp}_${stamp}.json`;
+  return `${OUTPUT_PREFIX_LEGACY}-${stamp}.json`;
+}
+
+export function isOutputFilename(name) {
+  return OUTPUT_FILENAME_RE.test(String(name || "").trim());
+}

package/lib/output-name.test.mjs

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  formatOutputStamp,
+  isOutputFilename,
+  makeOutputFilename,
+  OUTPUT_FILENAME_LEGACY,
+} from "./output-name.mjs";
+
+describe("output-name", () => {
+  const when = new Date(2026, 8, 15, 14, 30, 45);
+  const stamp = "20260915-143045";
+
+  it("formats stamp", () => {
+    assert.equal(formatOutputStamp(when), stamp);
+  });
+
+  it("builds name with short tip hashes", () => {
+    const name = makeOutputFilename({
+      branchSha: "aaaaaaaaaa1111111111",
+      baseSha: "bbbbbbbbbb2222222222",
+      when,
+    });
+    assert.equal(name, "diff-report_aaaaaaaaaa-bbbbbbbbbb_20260915-143045.json");
+    assert.equal(isOutputFilename(name), true);
+  });
+
+  it("reuses an explicit stamp", () => {
+    const name = makeOutputFilename({
+      branchSha: "abcdef0123456789",
+      baseSha: "fedcba9876543210",
+      stamp: "20260101-000000",
+    });
+    assert.equal(name, "diff-report_abcdef0123-fedcba9876_20260101-000000.json");
+  });
+
+  it("falls back to legacy stamp without tips", () => {
+    const name = makeOutputFilename({ when });
+    assert.equal(name, "diff-review-output-20260915-143045.json");
+    assert.equal(isOutputFilename(name), true);
+  });
+
+  it("accepts legacy names", () => {
+    assert.equal(OUTPUT_FILENAME_LEGACY, "diff-review-output.json");
+    assert.equal(isOutputFilename(OUTPUT_FILENAME_LEGACY), true);
+    assert.equal(isOutputFilename("diff-review-output-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-report_short-tips_20260915-143045.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,154 @@
+/**
+ * Prompt de review para el agente (compartido CLI + UI).
+ * Mantener alineado con el contrato de schema.json / validate.mjs.
+ */
+import {
+  makeOutputFilename,
+  formatOutputStamp,
+  isOutputFilename,
+  OUTPUT_FILENAME_LEGACY,
+} from "./output-name.mjs";
+
+export {
+  makeOutputFilename,
+  formatOutputStamp,
+  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>"
+  },
+  "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)}${remoteUrl ? "," : ""}`,
+  ];
+  if (remoteUrl) metaLines.push(`    "remoteUrl": ${JSON.stringify(remoteUrl)}`);
+  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" exactly as given):
+
+${outputSchemaBlock(meta)}
+
+Include "meta" with the source/repo/branch/base above (and origin "remoteUrl" when local). 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.`;
+}