@jpkme/diff-review 0.1.4 → 0.1.6

package/lib/check-report.mjs

@@ -0,0 +1,213 @@
+/**
+ * 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 { globMatch } from "./config.mjs";
+import { extractBranchDiff } from "./extract.mjs";
+import { tryResolveGitRoot } from "./git.mjs";
+import { decodePayload } from "./json-payload.mjs";
+import { REVIEW_SCHEMA, reviewIssues, validateAgainst } from "./validate.mjs";
+
+const MISSING_LIMIT = 40;
+
+/**
+ * @param {unknown} payload
+ * @param {string[]} [paths] rutas del diff (sin ignorados)
+ * @returns {{ ok: boolean, errors: string[], notes: string[] }}
+ */
+export function checkPayload(payload, paths = []) {
+  const errors = [...validateAgainst(REVIEW_SCHEMA, payload), ...reviewIssues(payload)];
+  const notes = [];
+  const known = (paths || []).map((p) => String(p || "").replaceAll("\\", "/")).filter(Boolean);
+
+  if (known.length) {
+    const blocks = Array.isArray(payload?.blocks) ? payload.blocks : [];
+    const findings = Array.isArray(payload?.findings) ? payload.findings : [];
+    const skipped = Array.isArray(payload?.skipped) ? payload.skipped : [];
+    const skippedPatterns = skipped.map((s) => String(s?.file || "")).filter(Boolean);
+
+    const covers = (file) => {
+      const norm = String(file || "").replaceAll("\\", "/");
+      if (blocks.some((b) => String(b?.file || "").replaceAll("\\", "/") === norm)) return true;
+      return skippedPatterns.some((pattern) => {
+        const p = pattern.replaceAll("\\", "/");
+        return p === norm || globMatch(norm, p);
+      });
+    };
+
+    for (const block of blocks) {
+      const file = String(block?.file || "").replaceAll("\\", "/");
+      if (file && !known.includes(file)) {
+        errors.push(`el bloque ${block.id || file} apunta a un archivo que no está en el diff: ${file}`);
+      }
+    }
+    for (const finding of findings) {
+      const file = String(finding?.file || "").replaceAll("\\", "/");
+      if (file && !known.includes(file)) {
+        errors.push(
+          `el hallazgo ${finding.id || finding.what || file} apunta a un archivo fuera del diff: ${file}`
+        );
+      }
+    }
+
+    const missing = known.filter((file) => !covers(file));
+    if (missing.length) {
+      const shown = missing.slice(0, MISSING_LIMIT);
+      const rest = missing.length - shown.length;
+      errors.push(
+        `quedaron ${missing.length} archivo(s) del diff sin bloque ni skipped: ${shown.join(", ")}${
+          rest > 0 ? ` … y ${rest} más` : ""
+        }`
+      );
+    }
+  } else {
+    notes.push("No contrasté cobertura contra git (sin lista de paths del diff).");
+  }
+
+  return { ok: errors.length === 0, errors, notes };
+}
+
+/**
+ * @param {string} filePath
+ * @param {{ repo?: string, branch?: string, base?: string, cwd?: string }} [opts]
+ */
+export function checkReportFile(filePath, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const abs = isAbsolute(filePath) ? filePath : resolve(cwd, filePath);
+  if (!existsSync(abs)) {
+    return {
+      ok: false,
+      file: abs,
+      errors: [`No existe el archivo: ${abs}`],
+      notes: [],
+      usage: true,
+    };
+  }
+
+  let payload;
+  try {
+    payload = decodePayload(readFileSync(abs, "utf8"));
+  } catch (err) {
+    return {
+      ok: false,
+      file: abs,
+      errors: [err instanceof Error ? err.message : String(err)],
+      notes: [],
+    };
+  }
+
+  const meta = payload && typeof payload === "object" ? payload.meta || {} : {};
+  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);
+
+  /** @type {string[]} */
+  let paths = [];
+  /** @type {string[]} */
+  const errors = [];
+
+  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."
+    );
+  } else {
+    try {
+      const extracted = extractBranchDiff({ repo, branch, base });
+      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.`
+      );
+    }
+  }
+
+  const result = checkPayload(payload, paths);
+  const allErrors = [...result.errors, ...errors];
+  return { ok: allErrors.length === 0, errors: allErrors, notes: result.notes, file: abs };
+}
+
+/**
+ * @param {string} file
+ * @param {string} command
+ * @param {{ ok: boolean, errors: string[], notes: string[] }} result
+ */
+export function formatCheckReport(file, command, result) {
+  if (result.ok) {
+    const extra = result.notes?.length ? `\n${result.notes.map((n) => `Note: ${n}`).join("\n")}` : "";
+    return `OK: ${file}${extra}\nSchema and references passed. You can stop.`;
+  }
+
+  const problems = (result.errors || []).map((e) => `- ${e}`).join("\n");
+  const notes = (result.notes || []).map((n) => `Note: ${n}`).join("\n");
+  const lines = [
+    `INVALID: ${file}`,
+    "",
+    "The JSON is not ready. Edit this same file until the command prints OK. Do not create a new filename.",
+    "",
+    "Problems:",
+    problems || "- (unknown)",
+  ];
+  if (notes) lines.push("", notes);
+  lines.push(
+    "",
+    "How to continue:",
+    "- Fix every problem above in place. Keep existing meta/intent/groups/blocks/findings; only change what is wrong or missing.",
+    '- Every diff path must appear in "blocks" or "skipped" (a skipped glob counts).',
+    "- what/why/fix stay ≤120 chars; intent ≥40 chars; enums exactly as in the schema.",
+    "- Human-readable strings in Spanish.",
+    `- Re-run exactly: \`${command}\``,
+    "- Stop only when that command prints OK."
+  );
+  return lines.join("\n");
+}
+
+/**
+ * @param {string[]} argv args después de `validate`
+ * @param {{ stdout?: (s: string) => void, stderr?: (s: string) => void, cwd?: string }} [io]
+ * @returns {number} exit code
+ */
+export function runValidateCli(argv, io = {}) {
+  const stdout = io.stdout || ((s) => console.log(s));
+  const stderr = io.stderr || ((s) => console.error(s));
+  const fileFlag = [];
+  /** @type {{ repo?: string, branch?: string, base?: string }} */
+  const opts = { cwd: io.cwd };
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      stdout(`Usage: npx --yes @jpkme/diff-review validate <file.json> [--repo <path>] [--branch <b>] [--base <b>]
+
+Exit 0 and "OK" when the JSON matches the review contract (and diff coverage, when git can list paths).
+Exit 1 with problems and how to continue otherwise.`);
+      return 0;
+    }
+    if (a === "--repo") opts.repo = argv[++i];
+    else if (a === "--branch") opts.branch = argv[++i];
+    else if (a === "--base") opts.base = argv[++i];
+    else if (a.startsWith("-")) {
+      stderr(`Opción desconocida: ${a}`);
+      return 2;
+    } else fileFlag.push(a);
+  }
+
+  const file = fileFlag[0];
+  if (!file) {
+    stderr("Falta el archivo JSON. Uso: diff-review validate <file.json>");
+    return 2;
+  }
+
+  const command = `npx --yes @jpkme/diff-review validate ${file}`;
+  const result = checkReportFile(file, opts);
+  const text = formatCheckReport(result.file || file, command, result);
+  if (result.ok) stdout(text);
+  else stderr(text);
+  if (result.usage) return 2;
+  return result.ok ? 0 : 1;
+}

package/lib/check-report.test.mjs

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { checkPayload, formatCheckReport } from "./check-report.mjs";
+
+const valid = () => ({
+  intent: "Agrega el ABM de depósitos locales end-to-end para dejar de administrarlos por SQL.",
+  groups: [{ id: "g1", kind: "feat", title: "CRUD de depósitos", intent: "base de todo" }],
+  blocks: [
+    {
+      id: "b1",
+      group: "g1",
+      file: "src/a.ts",
+      lines: "L1-20",
+      op: "add",
+      what: "controller nuevo",
+      why: "",
+      source: "code",
+    },
+  ],
+  findings: [],
+  skipped: [{ file: "**/*.lock", reason: "lockfile" }],
+});
+
+test("checkPayload acepta cobertura exacta y por glob", () => {
+  const result = checkPayload(valid(), ["src/a.ts", "bun.lock"]);
+  assert.equal(result.ok, true);
+  assert.deepEqual(result.errors, []);
+});
+
+test("checkPayload lista archivos del diff sin cubrir", () => {
+  const result = checkPayload(valid(), ["src/a.ts", "src/olvidado.ts"]);
+  assert.equal(result.ok, false);
+  assert.ok(result.errors.some((e) => e.includes("src/olvidado.ts")));
+});
+
+test("formatCheckReport explica cómo seguir", () => {
+  const text = formatCheckReport("diff-rev_a_b.json", "npx --yes @jpkme/diff-review validate diff-rev_a_b.json", {
+    ok: false,
+    errors: ["$.intent: texto demasiado corto"],
+    notes: [],
+  });
+  assert.match(text, /INVALID/);
+  assert.match(text, /How to continue/);
+  assert.match(text, /npx --yes @jpkme\/diff-review validate/);
+  assert.match(text, /same file/);
+});

package/lib/output-name.mjs

@@ -1,54 +1,42 @@
 /**
  * Nombre del JSON que escribe el agente.
- * Preferido: tips cortos + stamp. Legacy sin tips sigue siendo válido al importar.
+ * 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 (con tips). */
-export const OUTPUT_PREFIX = "diff-report";
+/** Prefijo del formato actual. */
+export const OUTPUT_PREFIX = "diff-rev";
 
-/** Prefijo legacy (sin tips). */
+/** 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-review-output.json
- * - diff-review-output-YYYYMMDD-HHmmss.json
- * - diff-report_{branchTip}-{baseTip}_YYYYMMDD-HHmmss.json
+ * - 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-review-output(?:-\d{8}-\d{6})?|diff-report_[0-9a-f]{7,12}-[0-9a-f]{7,12}_\d{8}-\d{6})\.json$/i;
+  /^(?: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 {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]
+ * @param {{ branchSha?: string, baseSha?: string }} [input]
  * @returns {string}
- *   con tips: diff-report_aaaaaaaaaa-bbbbbbbbbb_20260915-143045.json
- *   sin tips: diff-review-output-20260915-143045.json
+ *   con tips: diff-rev_aaaaaaaaaa_bbbbbbbbbb.json
+ *   sin tips: diff-review-output.json
  */
 export function makeOutputFilename(input = {}) {
-  const opts = input instanceof Date ? { when: input } : input || {};
-  const stamp = opts.stamp || formatOutputStamp(opts.when ?? new Date());
+  const opts = input instanceof Date ? {} : input || {};
   const fp = fingerprint(opts.branchSha, opts.baseSha);
-  if (fp) return `${OUTPUT_PREFIX}_${fp}_${stamp}.json`;
-  return `${OUTPUT_PREFIX_LEGACY}-${stamp}.json`;
+  if (fp) {
+    const [branchTip, baseTip] = fp.split("-");
+    if (branchTip && baseTip) return `${OUTPUT_PREFIX}_${branchTip}_${baseTip}.json`;
+  }
+  return OUTPUT_FILENAME_LEGACY;
 }
 
 export function isOutputFilename(name) {

package/lib/output-name.test.mjs

@@ -1,54 +1,37 @@
 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(name, "diff-rev_aaaaaaaaaa_bbbbbbbbbb.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("falls back to legacy without tips", () => {
+    assert.equal(makeOutputFilename({}), OUTPUT_FILENAME_LEGACY);
+    assert.equal(isOutputFilename(OUTPUT_FILENAME_LEGACY), true);
   });
 
-  it("accepts legacy names", () => {
-    assert.equal(OUTPUT_FILENAME_LEGACY, "diff-review-output.json");
-    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-report_short-tips_20260915-143045.json"), false);
+    assert.equal(isOutputFilename("diff-rev_short_tips.json"), false);
   });
 });

package/lib/prompt.mjs

@@ -4,14 +4,12 @@
  */
 import {
   makeOutputFilename,
-  formatOutputStamp,
   isOutputFilename,
   OUTPUT_FILENAME_LEGACY,
 } from "./output-name.mjs";
 
 export {
   makeOutputFilename,
-  formatOutputStamp,
   isOutputFilename,
   OUTPUT_FILENAME_LEGACY,
 };
@@ -22,7 +20,10 @@ export const OUTPUT_SCHEMA_BLOCK = `{
     "repo": "<absolute path or git URL>",
     "branch": "<branch under review>",
     "base": "develop",
-    "remoteUrl": "<origin URL; optional when source=url>"
+    "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": [
@@ -82,7 +83,14 @@ function workflowLocal(base, branch) {
 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.`;
+4. Emit the JSON file. Do not modify the repo.
+5. Validate it with the command in the output section. If it prints INVALID, follow "How to continue" and re-run until it prints OK.`;
+}
+
+/** Comando que el agente debe correr; npx por si el bin no está en PATH. */
+export function validateCliCommand(filename) {
+  const file = String(filename || "diff-rev_<branchTip>_<baseTip>.json").trim();
+  return `npx --yes @jpkme/diff-review validate ${file}`;
 }
 
 function workflowUrl(base, branch) {
@@ -91,7 +99,8 @@ function workflowUrl(base, branch) {
 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.`;
+5. Emit the JSON file.
+6. Validate it with the command in the output section. If it prints INVALID, follow "How to continue" and re-run until it prints OK.`;
 }
 
 /**
@@ -108,9 +117,14 @@ export function outputSchemaBlock(meta) {
     `    "source": ${JSON.stringify(source)},`,
     `    "repo": ${JSON.stringify(repo)},`,
     `    "branch": ${JSON.stringify(branch)},`,
-    `    "base": ${JSON.stringify(base)}${remoteUrl ? "," : ""}`,
+    `    "base": ${JSON.stringify(base)},`,
   ];
-  if (remoteUrl) metaLines.push(`    "remoteUrl": ${JSON.stringify(remoteUrl)}`);
+  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);
 }
@@ -142,13 +156,18 @@ ${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):
+- 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). That lets someone reopen the report elsewhere without re-picking the repo.
+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.`;
+After writing the file, validate it (npx so it works even if \`diff-review\` is not on PATH):
+
+\`${validateCliCommand(outputFilename)}\`
+
+- Exit 0 and a line starting with \`OK\` means the JSON is acceptable. Then tell me that \`${outputFilename}\` was written.
+- Exit 1 prints \`INVALID\`, the problems, and how to continue. Fix the same file and re-run that exact command until it prints OK. Do not stop before OK.`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jpkme/diff-review",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Local UI to prompt a coding agent for a branch review and browse the result.",
   "type": "module",
   "bin": {
@@ -49,6 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@bindrs/rfd": "^2.2.2"
+    "@bindrs/rfd": "^2.2.2",
+    "@clack/prompts": "^1.8.1"
   }
 }

package/schema.json

@@ -21,6 +21,18 @@
         "remoteUrl": {
           "type": "string",
           "description": "URL del remote (origin). Fallback si la carpeta local no existe en otra máquina."
+        },
+        "generatedAt": {
+          "type": "string",
+          "description": "ISO-8601 de cuándo se escribió la review (informativo)."
+        },
+        "agent": {
+          "type": "string",
+          "description": "Nombre del tool/agente (informativo), ej. Claude Code / Cursor."
+        },
+        "model": {
+          "type": "string",
+          "description": "Id del modelo usado (informativo)."
         }
       }
     },

package/web/build/client/_app/immutable/chunks/{CAnYe5db.js → Ber_0nz7.js}

@@ -1 +1 @@
-import"./Dur-vdUf.js";import{c as e}from"./Gya4IU1I.js";var t={get data(){return e.data},get error(){return e.error},get form(){return e.form},get params(){return e.params},get route(){return e.route},get state(){return e.state},get status(){return e.status},get url(){return e.url}};export{t};
+import"./Dur-vdUf.js";import{c as e}from"./zvcaSoGP.js";var t={get data(){return e.data},get error(){return e.error},get form(){return e.form},get params(){return e.params},get route(){return e.route},get state(){return e.state},get status(){return e.status},get url(){return e.url}};export{t};

package/web/build/client/_app/immutable/chunks/Ber_0nz7.js.br

@@ -0,0 +1,2 @@
+%
@��\��'��ǚU��)d�"*�ߎ�0�,�4=�=�Ȧ�+3���_��澨#�
+�Y	��M!^!�ƙ�9�8W"����:�|G����=�������<��`,�Z�Fxc��j��˾���K7�����an?