@jphutchins/code-review 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/index.js

@@ -53,15 +53,146 @@ var computeCost = (models, prices, warn = defaultWarn) => {
   };
 };
 
+// src/patch.ts
+var HUNK_HEADER_RE = /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@/;
+var hunkOldStart = (line) => {
+  const raw = HUNK_HEADER_RE.exec(line)?.[1];
+  return raw !== void 0 ? Number(raw) : null;
+};
+var classifyBodyLine = (line) => {
+  if (line.startsWith(" ")) return { kind: "context", text: line.slice(1) };
+  if (line.startsWith("-")) return { kind: "removed", text: line.slice(1) };
+  if (line.startsWith("+")) return { kind: "added", text: line.slice(1) };
+  return null;
+};
+var trimmedMiddle = (body) => {
+  const first = body.findIndex((l) => l.kind !== "context");
+  if (first === -1) return [];
+  const last = body.findLastIndex((l) => l.kind !== "context");
+  return body.slice(first, last + 1);
+};
+var isContiguousChange = (middle) => {
+  if (middle.some((l) => l.kind === "context")) return false;
+  const firstAdded = middle.findIndex((l) => l.kind === "added");
+  if (firstAdded === -1) return true;
+  return middle.slice(0, firstAdded).every((l) => l.kind === "removed") && middle.slice(firstAdded).every((l) => l.kind === "added");
+};
+var removedRange = (body, oldStart) => body.reduce(
+  (acc, line) => line.kind === "added" ? acc : {
+    lineNumber: acc.lineNumber + 1,
+    firstRemoved: line.kind === "removed" && acc.firstRemoved === null ? acc.lineNumber : acc.firstRemoved,
+    lastRemoved: line.kind === "removed" ? acc.lineNumber : acc.lastRemoved
+  },
+  { lineNumber: oldStart, firstRemoved: null, lastRemoved: null }
+);
+var drop = (reason) => ({
+  kind: "drop",
+  reason
+});
+var parseHunk = (patch) => {
+  const rawLines = patch.split("\n");
+  const lines = rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+  const headerHits = lines.reduce(
+    (acc, line, index) => {
+      const oldStart = hunkOldStart(line);
+      return oldStart !== null ? [...acc, { index, oldStart }] : acc;
+    },
+    []
+  );
+  if (headerHits.length !== 1) {
+    return drop(`expected exactly one hunk, got ${String(headerHits.length)}`);
+  }
+  const hit = headerHits[0];
+  if (hit === void 0) return drop("malformed hunk header");
+  const bodyRaw = lines.slice(hit.index + 1).filter((line) => !line.startsWith("\\"));
+  const classified = bodyRaw.map(classifyBodyLine);
+  if (classified.some((line) => line === null)) return drop("malformed hunk body line");
+  const body = classified.filter((line) => line !== null);
+  return { kind: "ok", oldStart: hit.oldStart, body };
+};
+var validatePatch = (patch, fileLines) => {
+  const parsed = parseHunk(patch);
+  if (parsed.kind === "drop") return parsed;
+  const { oldStart, body } = parsed;
+  const oldSideTexts = body.filter((l) => l.kind !== "added").map((l) => l.text);
+  const expected = fileLines.slice(oldStart - 1, oldStart - 1 + oldSideTexts.length);
+  const oldSideMatches = expected.length === oldSideTexts.length && expected.every((line, i) => line === oldSideTexts[i]);
+  if (!oldSideMatches) {
+    return drop(
+      `patch context does not match the file at lines ${String(oldStart)}..${String(oldStart + oldSideTexts.length - 1)}`
+    );
+  }
+  if (!isContiguousChange(trimmedMiddle(body))) {
+    return drop("change is not a single contiguous block");
+  }
+  const removedCount = body.filter((l) => l.kind === "removed").length;
+  const addedCount = body.filter((l) => l.kind === "added").length;
+  if (removedCount === 0 && addedCount === 0) return drop("hunk contains no changes");
+  if (removedCount === 0) return drop("pure insertion has no range to anchor a suggestion");
+  const { firstRemoved, lastRemoved } = removedRange(body, oldStart);
+  if (firstRemoved === null || lastRemoved === null) return drop("malformed hunk body");
+  return { startLine: firstRemoved, endLine: lastRemoved };
+};
+var patchToSuggestion = (patch) => {
+  const parsed = parseHunk(patch);
+  if (parsed.kind === "drop") return parsed;
+  const { body } = parsed;
+  if (!isContiguousChange(trimmedMiddle(body))) {
+    return drop("change is not a single contiguous block");
+  }
+  const removedCount = body.filter((l) => l.kind === "removed").length;
+  const addedLines = body.filter((l) => l.kind === "added");
+  if (removedCount === 0 && addedLines.length === 0) return drop("hunk contains no changes");
+  if (removedCount === 0) return drop("pure insertion can't be expressed as a suggestion");
+  return addedLines.map((l) => l.text).join("\n");
+};
+
+// src/surface.ts
+var severityEmoji = (s) => {
+  switch (s) {
+    case "critical":
+      return "\u{1F534}";
+    case "major":
+      return "\u{1F7E0}";
+    case "minor":
+      return "\u{1F535}";
+    case "nit":
+      return "\u26AA";
+    default:
+      return "\u2753";
+  }
+};
+var EMBED_LIMIT = 4e4;
+var AGENTS_STOP_DIRECTIVE = "<!-- AGENTS: STOP \u2014 do not parse the prose below; decode this findings JSON and read schema_version first. -->";
+var findingsPointer = (findings, jsonUrl, limit = EMBED_LIMIT) => {
+  const b64 = Buffer.from(JSON.stringify(findings), "utf-8").toString("base64");
+  const marker = b64.length <= limit ? `<!-- code-review:findings-json;base64 ${b64} -->` : jsonUrl ? `<!-- code-review:findings-json ${jsonUrl} -->` : "";
+  return marker ? `${AGENTS_STOP_DIRECTIVE}
+${marker}` : "";
+};
+var escapeFence = (text) => text.replace(/```/g, "`` ` ``");
+var projectPatch = (patch) => {
+  if (patch === void 0) return { kind: "none" };
+  const lowered = patchToSuggestion(patch);
+  return typeof lowered === "string" ? { kind: "suggestion", text: escapeFence(lowered) } : { kind: "patch", raw: escapeFence(patch) };
+};
+var formatConfidence = (n) => n.toFixed(2);
+var reviewBodyPointer = (headSha, stickyUrl, marker) => {
+  const sha7 = headSha.slice(0, 7);
+  const linkLine = stickyUrl ? `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the [summary comment](${stickyUrl}) for the verdict, walkthrough, and cost.` : `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the summary comment for the verdict, walkthrough, and cost.`;
+  return marker ? `${marker}
+
+${linkLine}` : linkLine;
+};
+
 // src/render.ts
-var escapeBackticks = (text) => text.replace(/```/g, "`` ` ``");
 var escapePipes = (text) => text.replace(/\|/g, "\\|");
 var escapeCodeBackticks = (text) => text.replace(/`/g, "-");
 var sanitizeFinding = (f) => ({
   ...f,
   title: escapePipes(f.title),
   path: escapeCodeBackticks(f.path),
-  suggestion: f.suggestion ? escapeBackticks(f.suggestion) : f.suggestion
+  patchProjection: projectPatch(f.patch)
 });
 var emptySeverityCounts = () => ({
   critical: 0,
@@ -73,35 +204,37 @@ var computeSeverityCounts = (findings) => findings.reduce(
   (acc, f) => f.severity in acc ? { ...acc, [f.severity]: acc[f.severity] + 1 } : acc,
   emptySeverityCounts()
 );
-var EMBED_LIMIT = 4e4;
 var render = (input) => {
   const eta = new Eta({ autoTrim: false });
   const usageAvailable = input.envelope !== null;
   const costReport = input.envelope ? computeCost(input.envelope.models, input.prices) : null;
+  const pricesProvided = input.pricesProvided ?? true;
   const route = input.route ?? input.envelope?.route ?? null;
   const effort = input.effort ?? input.envelope?.effort ?? null;
   const modelNames = input.envelope ? input.envelope.models.map((m) => m.model).join(", ") : "";
-  const findingsB64 = Buffer.from(JSON.stringify(input.findings), "utf-8").toString("base64");
-  const embeddedFindings = findingsB64.length <= EMBED_LIMIT ? findingsB64 : null;
   return eta.renderString(input.template, {
     findings: input.findings,
     envelope: input.envelope,
     usageAvailable,
     costReport,
+    pricesProvided,
     route,
     effort,
     modelNames,
     testReport: input.testReport ?? null,
     reviewedSha: input.reviewedSha ?? "0000000000000000000000000000000000000000",
+    postedAt: input.postedAt ?? "",
     severityCounts: input.severityCounts ?? computeSeverityCounts(input.findings.findings),
     strays: (input.strays ?? []).map(sanitizeFinding),
     inlineDisposition: input.inlineDisposition ?? null,
     runUrl: input.runUrl ?? null,
     jsonUrl: input.jsonUrl ?? null,
-    embeddedFindings,
+    findingsPointer: input.findingsPointer ?? findingsPointer(input.findings, input.jsonUrl),
     reviewUrl: input.reviewUrl ?? null,
     formatTokens: (n) => Number.isFinite(n) && n >= 0 ? n.toLocaleString("en-US") : "\u2014",
-    formatCost: (n) => Number.isFinite(n) ? n > 0 && n.toFixed(2) === "0.00" ? "<$0.01" : `$${n.toFixed(2)}` : "\u2014",
+    // Cost cells render N/A (never a false $0.00) when no real price map was provided — there are
+    // real tokens spent, we simply have no rates to price them (SPEC §6.2).
+    formatCost: (n) => !pricesProvided ? "N/A" : Number.isFinite(n) ? n > 0 && n.toFixed(2) === "0.00" ? "<$0.01" : `$${n.toFixed(2)}` : "\u2014",
     formatDuration: (ms) => {
       if (!Number.isFinite(ms) || ms < 0) return "\u2014";
       const s = Math.round(ms / 1e3);
@@ -119,20 +252,8 @@ var render = (input) => {
           return `\u2753 ${v}`;
       }
     },
-    severityEmoji: (s) => {
-      switch (s) {
-        case "critical":
-          return "\u{1F534}";
-        case "major":
-          return "\u{1F7E0}";
-        case "minor":
-          return "\u{1F535}";
-        case "nit":
-          return "\u26AA";
-        default:
-          return "\u2753";
-      }
-    }
+    severityEmoji,
+    formatConfidence
   });
 };
 var key = (path, line) => `${path}:${String(line)}`;
@@ -189,56 +310,33 @@ var partitionFindings = (findings, index) => {
 };
 
 // src/inline.ts
-var escapeBackticks2 = (text) => text.replace(/```/g, "`` ` ``");
-var severityEmoji = (s) => {
-  switch (s) {
-    case "critical":
-      return "\u{1F534}";
-    case "major":
-      return "\u{1F7E0}";
-    case "minor":
-      return "\u{1F535}";
-    case "nit":
-      return "\u26AA";
-    default:
-      return "\u2753";
-  }
-};
-var severityHeader = (f) => `${severityEmoji(f.severity)} **${f.severity}** \u2014 ${f.title}`;
-var jsonUrlMarker = (jsonUrl) => jsonUrl ? `<!-- code-review:findings-json ${jsonUrl} -->` : void 0;
 var formatModels = (models) => models.length > 0 ? models.map((m) => `\`${m}\``).join("/") : "an AI model";
-var buildCommentBody = (f, jsonUrl) => {
-  const marker = jsonUrlMarker(jsonUrl);
-  const parts = [...marker ? [marker] : [], severityHeader(f), f.body];
-  if (f.suggestion !== null && f.suggestion !== void 0) {
-    const safe = escapeBackticks2(f.suggestion);
-    parts.push(`\`\`\`suggestion
-${safe}
-\`\`\``);
-  }
-  return parts.join("\n\n");
-};
-var renderCommentBody = (f, eta, template, modelsText, jsonUrl) => {
-  return eta.renderString(template, {
+var renderCommentBody = (f, eta, template, modelsText, jsonUrl, pointer) => (
+  // Eta.renderString returns string | Promise<string>; with autoTrim:false it's always sync.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+  eta.renderString(template, {
     ...f,
-    suggestion: f.suggestion !== null && f.suggestion !== void 0 ? escapeBackticks2(f.suggestion) : null,
+    patchProjection: projectPatch(f.patch),
     severityEmoji,
+    formatConfidence,
     modelsText,
-    jsonUrl: jsonUrl ?? null
-  });
-};
-var buildInlineComments = (findings, diff, context = {}) => {
-  const { inlineTemplate, models = [], jsonUrl } = context;
+    jsonUrl: jsonUrl ?? null,
+    findingsPointer: pointer
+  })
+);
+var buildInlineComments = (findings, diff, context) => {
+  const { inlineTemplate, models = [], jsonUrl, findings: fullFindings } = context;
   const index = indexDiff(diff);
   const { inDiff, strays } = partitionFindings(findings, index);
-  const eta = inlineTemplate ? new Eta({ autoTrim: false }) : null;
+  const eta = new Eta({ autoTrim: false });
   const modelsText = formatModels(models);
+  const pointer = context.findingsPointer ?? (fullFindings ? findingsPointer(fullFindings, jsonUrl) : "");
   const comments = inDiff.map((f) => {
     const comment = {
       path: f.path,
       line: f.end_line,
       side: defaultSide(f.side),
-      body: eta && inlineTemplate ? renderCommentBody(f, eta, inlineTemplate, modelsText, jsonUrl) : buildCommentBody(f, jsonUrl)
+      body: renderCommentBody(f, eta, inlineTemplate, modelsText, jsonUrl, pointer)
     };
     if (f.start_line < f.end_line) {
       return {
@@ -292,15 +390,15 @@ var FindingShape = t.intersection([
     end_line: LineNumber,
     severity: SeverityCodec,
     title: t.string,
-    body: t.string
+    description: t.string,
+    reasoning: t.string,
+    confidence: Confidence
   }),
   t.partial({
     side: SideCodec,
-    suggestion: t.union([t.string, t.null]),
-    confidence: Confidence,
     code: t.string,
     code_url: t.string,
-    reasoning: t.string,
+    recommendation: t.string,
     patch: t.string
   })
 ]);
@@ -377,7 +475,13 @@ var TestSummaryCodec = t.intersection([
     failures: t.array(TestFailureCodec)
   })
 ]);
-var DEFAULT_SCHEMA_VERSION = "0.3.0";
+var DEFAULT_SCHEMA_VERSION = "0.4.0";
+var noticeFindings = (summary) => ({
+  schema_version: DEFAULT_SCHEMA_VERSION,
+  summary,
+  verdict: "comment",
+  findings: []
+});
 
 // src/validate.ts
 var addFormats = _addFormats;
@@ -435,23 +539,17 @@ var formatMarkdown = (md) => {
   return `${lines.join("\n").replace(/\n+$/, "")}
 `;
 };
+var pad2 = (n) => String(n).padStart(2, "0");
+var formatUtc = (d) => `${String(d.getUTCFullYear())}-${pad2(d.getUTCMonth() + 1)}-${pad2(d.getUTCDate())} ${pad2(d.getUTCHours())}:${pad2(d.getUTCMinutes())} UTC`;
 var identity = (decoded) => decoded;
 var findingsTable = [
   {
-    minor: "0.3",
+    minor: "0.4",
     defaultVersion: DEFAULT_SCHEMA_VERSION,
     schemaFile: "findings.schema.json",
     codec: FindingsCodec,
     normalize: identity,
     latest: true
-  },
-  {
-    minor: "0.2",
-    defaultVersion: "0.2.0",
-    schemaFile: "v0.2/findings.schema.json",
-    codec: FindingsCodec,
-    normalize: identity,
-    latest: false
   }
 ];
 var triageTable = [
@@ -590,12 +688,6 @@ var checkLongSuggestions = (comments) => {
   });
   return { comments: adjusted, longFiles };
 };
-var noticeFindings = (message) => ({
-  schema_version: DEFAULT_SCHEMA_VERSION,
-  summary: `### \u26A0\uFE0F ${message}`,
-  verdict: "comment",
-  findings: []
-});
 var loadFindings = (path) => {
   let raw;
   try {
@@ -665,9 +757,8 @@ var parseHtmlUrl = (raw) => {
     return void 0;
   }
 };
-var postInlineReview = async (repo, prNumber, headSha, comments, stickyUrl, ghApi) => {
-  const sha7 = headSha.slice(0, 7);
-  const pointer = stickyUrl ? `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the [summary comment](${stickyUrl}) for the verdict, walkthrough, and cost.` : `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the summary comment for the verdict, walkthrough, and cost.`;
+var postInlineReview = async (repo, prNumber, headSha, comments, stickyUrl, marker, ghApi) => {
+  const pointer = reviewBodyPointer(headSha, stickyUrl, marker);
   const body = JSON.stringify({
     body: pointer,
     commit_id: headSha,
@@ -807,18 +898,20 @@ var post = async (input, ghApi = runGhApi) => {
     throw new Error(`Price map at ${input.pricesPath} does not match the expected shape`);
   }
   const template = readFileSync(input.templatePath, "utf-8");
-  const inlineTemplate = input.inlineTemplatePath ? readFileSync(input.inlineTemplatePath, "utf-8") : void 0;
+  const inlineTemplate = readFileSync(input.inlineTemplatePath, "utf-8");
   const renderNotice = (message) => formatMarkdown(
     render({
-      findings: noticeFindings(message),
+      findings: noticeFindings(`### \u26A0\uFE0F ${message}`),
       envelope: null,
       prices: decodedPrices.right,
+      pricesProvided: input.pricesProvided,
       template,
       route: input.route,
       reviewedSha: input.headSha,
       effort: input.effort,
       runUrl: input.runUrl,
-      jsonUrl: input.jsonUrl
+      jsonUrl: input.jsonUrl,
+      postedAt: input.postedAt
     })
   );
   if (isEmptyDiff(diff)) {
@@ -851,6 +944,7 @@ var post = async (input, ghApi = runGhApi) => {
         findings,
         envelope: null,
         prices: decodedPrices.right,
+        pricesProvided: input.pricesProvided,
         template,
         route: input.route,
         reviewedSha: input.headSha,
@@ -858,7 +952,8 @@ var post = async (input, ghApi = runGhApi) => {
         testReport,
         inlineDisposition: { kind: "no-envelope" },
         runUrl: input.runUrl,
-        jsonUrl: input.jsonUrl
+        jsonUrl: input.jsonUrl,
+        postedAt: input.postedAt
       })
     );
     await upsertSticky(input.repo, prNumber, existingSticky, body, ghApi);
@@ -867,10 +962,11 @@ var post = async (input, ghApi = runGhApi) => {
     );
     process.exit(0);
   }
+  const findingsMarker = findingsPointer(findings, input.jsonUrl);
   const { comments: rawComments, strays } = buildInlineComments(findings.findings, diff, {
     inlineTemplate,
     models: envelope.models.map((m) => m.model),
-    jsonUrl: input.jsonUrl
+    findingsPointer: findingsMarker
   });
   const { comments, longFiles } = checkLongSuggestions(rawComments);
   for (const wf of longFiles) {
@@ -881,11 +977,12 @@ var post = async (input, ghApi = runGhApi) => {
   }
   const botReviews = comments.length > 0 ? await fetchBotReviews(input.repo, prNumber, input.botLogin, ghApi) : [];
   const alreadyReviewedThisSha = botReviews.some((r) => r.commitId === input.headSha);
-  const inlineDisposition = comments.length > 0 ? alreadyReviewedThisSha ? { kind: "suppressed-existing-review", sha: input.headSha } : { kind: "posted", count: comments.length, sha: input.headSha } : strays.length > 0 ? { kind: "none-in-diff" } : void 0;
+  const initialDisposition = comments.length > 0 ? alreadyReviewedThisSha ? { kind: "suppressed-existing-review", sha: input.headSha } : void 0 : strays.length > 0 ? { kind: "none-in-diff" } : void 0;
   const commonRenderInput = {
     findings,
     envelope,
     prices: decodedPrices.right,
+    pricesProvided: input.pricesProvided,
     template,
     route: input.route,
     reviewedSha: input.headSha,
@@ -893,9 +990,10 @@ var post = async (input, ghApi = runGhApi) => {
     testReport,
     severityCounts: computeSeverityCounts(findings.findings),
     strays,
-    inlineDisposition,
     runUrl: input.runUrl,
-    jsonUrl: input.jsonUrl
+    jsonUrl: input.jsonUrl,
+    findingsPointer: findingsMarker,
+    postedAt: input.postedAt
   };
   const longFilesNote = longFiles.length > 0 ? `
 
@@ -903,8 +1001,14 @@ var post = async (input, ghApi = runGhApi) => {
 
 > **Note:** ${String(longFiles.length)} suggestion(s) exceeded GitHub's ~10-line inline suggestion limit and were omitted from the inline comments; the affected findings remain in the review.
 ` : "";
-  const renderBody = (reviewUrl2) => formatMarkdown(render({ ...commonRenderInput, reviewUrl: reviewUrl2 }) + longFilesNote);
-  const stickyRef = await upsertSticky(input.repo, prNumber, existingSticky, renderBody(), ghApi);
+  const renderBody = (inlineDisposition, reviewUrl2) => formatMarkdown(render({ ...commonRenderInput, inlineDisposition, reviewUrl: reviewUrl2 }) + longFilesNote);
+  const stickyRef = await upsertSticky(
+    input.repo,
+    prNumber,
+    existingSticky,
+    renderBody(initialDisposition),
+    ghApi
+  );
   if (comments.length === 0) return;
   if (alreadyReviewedThisSha) {
     process.stderr.write(
@@ -923,15 +1027,26 @@ var post = async (input, ghApi = runGhApi) => {
     input.headSha,
     comments,
     stickyRef?.url,
+    findingsMarker,
     ghApi
   );
   process.stderr.write(
     `Posted ${String(comments.length)} inline comments on PR #${String(prNumber)}
 `
   );
-  if (stickyRef !== null && reviewUrl !== void 0) {
+  if (stickyRef !== null) {
+    const confirmedDisposition = {
+      kind: "posted",
+      count: comments.length,
+      sha: input.headSha
+    };
     try {
-      await patchComment(input.repo, stickyRef.id, renderBody(reviewUrl), ghApi);
+      await patchComment(
+        input.repo,
+        stickyRef.id,
+        renderBody(confirmedDisposition, reviewUrl),
+        ghApi
+      );
       process.stderr.write(`Linked sticky comment #${String(stickyRef.id)} to the review
 `);
     } catch (err) {
@@ -1263,24 +1378,42 @@ var mapModelUsage = (modelUsage) => Object.entries(modelUsage).map(([model, entr
   ...entry.cacheReadInputTokens !== void 0 ? { cache_read_tokens: entry.cacheReadInputTokens } : {},
   ...entry.cacheCreationInputTokens !== void 0 ? { cache_write_tokens: entry.cacheCreationInputTokens } : {}
 }));
+var findingsOutcome = (native, agentFilePath) => {
+  const ladder = extractStructured({ kind: "findings", native, agentFilePath });
+  if (ladder.kind !== "ok")
+    return { kind: "telemetry-only", reason: describeLadderFailure(ladder) };
+  const resolution = resolve("findings", ladder.candidate);
+  return resolution.kind === "ok" ? { kind: "ok", version: resolution.version, findings: resolution.value } : {
+    kind: "telemetry-only",
+    reason: "internal error: the extraction ladder validated a candidate the registry then rejected"
+  };
+};
 var adaptClaudeCode = (native, agentFilePath, meta) => {
-  const outcome = extractStructured({ kind: "findings", native, agentFilePath });
-  if (outcome.kind !== "ok") {
-    return left(describeLadderFailure(outcome));
-  }
-  const resolution = resolve("findings", outcome.candidate);
-  return resolution.kind === "ok" ? right({
-    schema_version: resolution.version,
-    findings: resolution.value,
+  const telemetry = {
     models: mapModelUsage(native.modelUsage),
     turns: native.num_turns,
     duration_ms: native.duration_ms,
     vendor_cost_usd: native.total_cost_usd ?? null,
     ...meta.route ? { route: meta.route } : {},
     ...meta.effort ? { effort: meta.effort } : {}
-  }) : left(
-    "internal error: the extraction ladder validated a candidate the registry then rejected"
-  );
+  };
+  const outcome = findingsOutcome(native, agentFilePath);
+  switch (outcome.kind) {
+    case "ok":
+      return right({
+        schema_version: outcome.version,
+        findings: outcome.findings,
+        ...telemetry
+      });
+    case "telemetry-only":
+      return right({
+        schema_version: DEFAULT_SCHEMA_VERSION,
+        findings: noticeFindings(`### \u26A0\uFE0F Review did not complete
+
+${outcome.reason}`),
+        ...telemetry
+      });
+  }
 };
 var adapt = (adapterName, native, agentFilePath, meta = {}) => {
   switch (adapterName) {
@@ -1294,83 +1427,86 @@ var adapt = (adapterName, native, agentFilePath, meta = {}) => {
     }
   }
 };
-
-// src/patch.ts
-var HUNK_HEADER_RE = /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@/;
-var hunkOldStart = (line) => {
-  const raw = HUNK_HEADER_RE.exec(line)?.[1];
-  return raw !== void 0 ? Number(raw) : null;
-};
-var classifyBodyLine = (line) => {
-  if (line.startsWith(" ")) return { kind: "context", text: line.slice(1) };
-  if (line.startsWith("-")) return { kind: "removed", text: line.slice(1) };
-  if (line.startsWith("+")) return { kind: "added", text: line.slice(1) };
-  return null;
-};
-var trimmedMiddle = (body) => {
-  const first = body.findIndex((l) => l.kind !== "context");
-  if (first === -1) return [];
-  const last = body.findLastIndex((l) => l.kind !== "context");
-  return body.slice(first, last + 1);
+var whatsWrong = (state, draftPath, kind) => {
+  switch (state.kind) {
+    case "missing":
+      return `${draftPath} does not exist yet`;
+    case "unreadable":
+      return `${draftPath} could not be read: ${state.error}`;
+    case "invalid":
+      return `${draftPath} does not validate against the ${kind} schema:
+${state.errors.map((e) => `  - ${e}`).join("\n")}`;
+  }
 };
-var isContiguousChange = (middle) => {
-  if (middle.some((l) => l.kind === "context")) return false;
-  const firstAdded = middle.findIndex((l) => l.kind === "added");
-  if (firstAdded === -1) return true;
-  return middle.slice(0, firstAdded).every((l) => l.kind === "removed") && middle.slice(firstAdded).every((l) => l.kind === "added");
+var decideGate = (state, nudges, maxNudges, draftPath, kind) => {
+  if (state.kind === "valid") return { kind: "allow" };
+  if (nudges >= maxNudges) return { kind: "allow" };
+  return {
+    kind: "block",
+    reason: [
+      `This review is not complete \u2014 ${whatsWrong(state, draftPath, kind)}`,
+      `The only deliverable is a ${kind} document that validates against the ${kind} schema \u2014 run "code-review print-schema ${kind}" to see the exact shape.`,
+      `Write it to ${draftPath}, then run "code-review validate ${draftPath} --kind ${kind}" until it exits 0 before ending your turn.`
+    ].join("\n")
+  };
 };
-var removedRange = (body, oldStart) => body.reduce(
-  (acc, line) => line.kind === "added" ? acc : {
-    lineNumber: acc.lineNumber + 1,
-    firstRemoved: line.kind === "removed" && acc.firstRemoved === null ? acc.lineNumber : acc.firstRemoved,
-    lastRemoved: line.kind === "removed" ? acc.lineNumber : acc.lastRemoved
-  },
-  { lineNumber: oldStart, firstRemoved: null, lastRemoved: null }
-);
-var drop = (reason) => ({ kind: "drop", reason });
-var lowerPatch = (patch, fileLines) => {
-  const rawLines = patch.split("\n");
-  const lines = rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
-  const headerHits = lines.reduce(
-    (acc, line, index) => {
-      const oldStart = hunkOldStart(line);
-      return oldStart !== null ? [...acc, { index, oldStart }] : acc;
-    },
-    []
-  );
-  if (headerHits.length !== 1) {
-    return drop(`expected exactly one hunk, got ${String(headerHits.length)}`);
+var draftState = (draftPath, resolveSchema) => {
+  let raw;
+  try {
+    raw = readFileSync(draftPath, "utf-8");
+  } catch (err) {
+    if (err instanceof Error && err.code === "ENOENT") {
+      return { kind: "missing" };
+    }
+    return { kind: "unreadable", error: err instanceof Error ? err.message : String(err) };
   }
-  const hit = headerHits[0];
-  if (hit === void 0) return drop("malformed hunk header");
-  const bodyRaw = lines.slice(hit.index + 1).filter((line) => !line.startsWith("\\"));
-  const classified = bodyRaw.map(classifyBodyLine);
-  if (classified.some((line) => line === null)) return drop("malformed hunk body line");
-  const body = classified.filter((line) => line !== null);
-  const oldSideTexts = body.filter((l) => l.kind !== "added").map((l) => l.text);
-  const expected = fileLines.slice(hit.oldStart - 1, hit.oldStart - 1 + oldSideTexts.length);
-  const oldSideMatches = expected.length === oldSideTexts.length && expected.every((line, i) => line === oldSideTexts[i]);
-  if (!oldSideMatches) {
-    return drop(
-      `patch context does not match the file at lines ${String(hit.oldStart)}..${String(hit.oldStart + oldSideTexts.length - 1)}`
-    );
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      kind: "invalid",
+      errors: [`not valid JSON: ${err instanceof Error ? err.message : String(err)}`]
+    };
   }
-  if (!isContiguousChange(trimmedMiddle(body))) {
-    return drop("change is not a single contiguous block");
+  let schemaPath;
+  try {
+    schemaPath = resolveSchema(parsed);
+  } catch (err) {
+    return { kind: "invalid", errors: [err instanceof Error ? err.message : String(err)] };
+  }
+  try {
+    const { valid, errors } = validateAgainstSchema(parsed, schemaPath);
+    return valid ? { kind: "valid" } : { kind: "invalid", errors };
+  } catch (err) {
+    return { kind: "invalid", errors: [err instanceof Error ? err.message : String(err)] };
   }
-  const removedCount = body.filter((l) => l.kind === "removed").length;
-  const addedLines = body.filter((l) => l.kind === "added");
-  if (removedCount === 0 && addedLines.length === 0) return drop("hunk contains no changes");
-  if (removedCount === 0) return drop("pure insertion can't be expressed as a suggestion");
-  const { firstRemoved, lastRemoved } = removedRange(body, hit.oldStart);
-  if (firstRemoved === null || lastRemoved === null) return drop("malformed hunk body");
-  return {
-    kind: "ok",
-    startLine: firstRemoved,
-    endLine: lastRemoved,
-    suggestion: addedLines.map((l) => l.text).join("\n")
-  };
 };
+var readNudges = (counterPath) => {
+  try {
+    const n = Number.parseInt(readFileSync(counterPath, "utf-8").trim(), 10);
+    return Number.isInteger(n) && n >= 0 ? n : 0;
+  } catch {
+    return 0;
+  }
+};
+var bumpNudges = (counterPath, current) => {
+  writeFileSync(counterPath, `${String(current + 1)}
+`);
+};
+var shellQuote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+var defaultHookCommand = (draftPath, opts) => [
+  "code-review stop-gate --draft",
+  shellQuote(draftPath),
+  ...opts.kind ? ["--kind", shellQuote(opts.kind)] : [],
+  ...opts.schema ? ["--schema", shellQuote(opts.schema)] : [],
+  ...opts.schemaVersion ? ["--schema-version", shellQuote(opts.schemaVersion)] : [],
+  ...opts.maxNudges ? ["--max-nudges", shellQuote(opts.maxNudges)] : [],
+  ...opts.counter ? ["--counter", shellQuote(opts.counter)] : []
+].join(" ");
+var stopHookSettings = (command) => ({
+  hooks: { Stop: [{ hooks: [{ type: "command", command }] }] }
+});
 
 // src/index.ts
 var readJSON = (path) => {
@@ -1406,12 +1542,13 @@ var unwrapAdapt = (either) => {
 var bundledPath = (...segments) => resolve$1(import.meta.dirname, "..", ...segments);
 var packageVersion = JSON.parse(readFileSync(bundledPath("package.json"), "utf-8")).version;
 var resolveTemplatePath = (templateArg) => templateArg ? resolve$1(templateArg) : bundledPath("templates", "comment.eta");
-var resolvePricesPath = (pricesArg) => {
-  if (pricesArg) return resolve$1(pricesArg);
+var resolveInlineTemplatePath = (templateArg) => templateArg ? resolve$1(templateArg) : bundledPath("templates", "inline.eta");
+var resolvePrices = (pricesArg) => {
+  if (pricesArg) return { kind: "provided", path: resolve$1(pricesArg) };
   process.stderr.write(
-    "code-review: no --prices given \u2014 using the bundled example prices (all zero); cost figures will be $0\n"
+    "code-review: no --prices given \u2014 cost will be reported as N/A (no price map to recompute from)\n"
   );
-  return bundledPath("schema", "prices.example.json");
+  return { kind: "absent", path: bundledPath("schema", "prices.example.json") };
 };
 var TEST_REPORT_DESCRIPTION = 'Path to a JSON test summary: {"passed": number, "failed": number, "total": number, "failures"?: [{"name": string, "message"?: string}]}';
 var renderCmd = defineCommand({
@@ -1459,19 +1596,21 @@ var renderCmd = defineCommand({
     const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
     const envelope = decode(ResultEnvelopeCodec.decode(readJSON(args.usage)), "envelope");
     const templatePath = resolveTemplatePath(args.template);
-    const pricesPath = resolvePricesPath(args.prices);
-    const prices = decode(PriceMapCodec.decode(readJSON(pricesPath)), "prices");
+    const priceResolution = resolvePrices(args.prices);
+    const prices = decode(PriceMapCodec.decode(readJSON(priceResolution.path)), "prices");
     const template = readFileSync(templatePath, "utf-8");
     const testReport = args["test-report"] ? decode(TestSummaryCodec.decode(readJSON(args["test-report"])), "test report") : void 0;
     const output = render({
       findings,
       envelope,
       prices,
+      pricesProvided: priceResolution.kind === "provided",
       template,
       reviewedSha: args["reviewed-sha"],
       route: args.route,
       effort: args.effort,
-      testReport
+      testReport,
+      postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
     process.stdout.write(output);
   }
@@ -1494,14 +1633,17 @@ var inlineCmd = defineCommand({
     },
     template: {
       type: "string",
-      description: "Path to inline comment Eta template (default: built-in format)"
+      description: "Path to inline comment Eta template (default: bundled templates/inline.eta)"
     }
   },
   run: async ({ args }) => {
     const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
     const diff = readFileSync(resolve$1(args.diff), "utf-8");
-    const inlineTemplate = args.template ? readFileSync(resolve$1(args.template), "utf-8") : void 0;
-    const { comments, strays } = buildInlineComments(findings.findings, diff, { inlineTemplate });
+    const inlineTemplate = readFileSync(resolveInlineTemplatePath(args.template), "utf-8");
+    const { comments, strays } = buildInlineComments(findings.findings, diff, {
+      inlineTemplate,
+      findings
+    });
     process.stdout.write(
       JSON.stringify({ comments, strays, stray_markdown: renderStraysSection(strays) }, null, 2)
     );
@@ -1531,8 +1673,7 @@ var costCmd = defineCommand({
     process.stdout.write(JSON.stringify(report, null, 2));
   }
 });
-var declaredSchemaVersion = (raw) => typeof raw === "object" && raw !== null && "schema_version" in raw ? typeof raw.schema_version === "string" ? raw.schema_version : void 0 : void 0;
-var derivedSchemaVersion = (kind, raw) => kind === "findings" ? declaredSchemaVersion(raw) : void 0;
+var derivedSchemaVersion = (kind, raw) => kind === "findings" ? declaredVersion(raw) : void 0;
 var validateCmd = defineCommand({
   meta: {
     name: "validate",
@@ -1684,36 +1825,30 @@ var readFileLines = (path) => {
     return null;
   }
 };
-var lowerFinding = (finding, repoRoot) => {
+var validateFinding = (finding, repoRoot) => {
   if (finding.patch === void 0) return finding;
-  const base = withoutPatch(finding);
   const lines = readFileLines(resolve$1(repoRoot, finding.path));
   if (lines === null) {
     process.stderr.write(
-      `lower-suggestions: ${finding.path}: could not read file at "${repoRoot}" \u2014 dropping patch
+      `validate-patches: ${finding.path}: could not read file at "${repoRoot}" \u2014 dropping patch
 `
     );
-    return base;
+    return withoutPatch(finding);
   }
-  const result = lowerPatch(finding.patch, lines);
-  if (result.kind === "drop") {
+  const result = validatePatch(finding.patch, lines);
+  if ("kind" in result) {
     process.stderr.write(
-      `lower-suggestions: ${finding.path}:${String(finding.start_line)}: ${result.reason} \u2014 dropping patch
+      `validate-patches: ${finding.path}:${String(finding.start_line)}: ${result.reason} \u2014 dropping patch
 `
     );
-    return base;
+    return withoutPatch(finding);
   }
-  return {
-    ...base,
-    suggestion: result.suggestion,
-    start_line: result.startLine,
-    end_line: result.endLine
-  };
+  return { ...finding, start_line: result.startLine, end_line: result.endLine };
 };
-var lowerSuggestionsCmd = defineCommand({
+var validatePatchesCmd = defineCommand({
   meta: {
-    name: "lower-suggestions",
-    description: "Validate each finding's patch against the real PR-head tree and lower it to an exact suggestion + range, or drop it (issue #10)"
+    name: "validate-patches",
+    description: "Validate each finding's patch against the real PR-head tree, aligning the finding's range to it and keeping the patch, or dropping the patch (issue #10)"
   },
   args: {
     findings: {
@@ -1729,11 +1864,11 @@ var lowerSuggestionsCmd = defineCommand({
   run: async ({ args }) => {
     const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
     const repoRoot = args["repo-root"] ? resolve$1(args["repo-root"]) : process.cwd();
-    const lowered = {
+    const validated = {
       ...findings,
-      findings: findings.findings.map((f) => lowerFinding(f, repoRoot))
+      findings: findings.findings.map((f) => validateFinding(f, repoRoot))
     };
-    process.stdout.write(`${JSON.stringify(lowered, null, 2)}
+    process.stdout.write(`${JSON.stringify(validated, null, 2)}
 `);
   }
 });
@@ -1783,6 +1918,97 @@ var printSchemaCmd = defineCommand({
 `);
   }
 });
+var MAX_NUDGES_DEFAULT = 5;
+var drainStdin = () => {
+  if (process.stdin.isTTY) return;
+  try {
+    readFileSync(0);
+  } catch {
+  }
+};
+var requireMaxNudges = (raw) => {
+  if (raw === void 0) return MAX_NUDGES_DEFAULT;
+  if (!/^\d+$/.test(raw)) {
+    fail(`--max-nudges must be a non-negative integer; got "${raw}"`);
+  }
+  const n = Number.parseInt(raw, 10);
+  if (n < 1) {
+    fail(`--max-nudges must be >= 1 \u2014 a gate that never blocks must be omitted, not set to ${raw}`);
+  }
+  return n;
+};
+var stopGateCmd = defineCommand({
+  meta: {
+    name: "stop-gate",
+    description: "Claude Code Stop-hook gate: refuse to let the agent end its turn until --draft validates against the schema (bounded by --max-nudges). With --print-settings, emit the --settings JSON that wires this as the Stop hook."
+  },
+  args: {
+    draft: {
+      type: "string",
+      description: "Path to the findings document the agent must produce and keep valid",
+      required: true
+    },
+    kind: {
+      type: "string",
+      description: "Schema kind to validate against: findings | triage | prices (default: findings)"
+    },
+    schema: { type: "string", description: "Path to a schema file (wins over --kind)" },
+    "schema-version": {
+      type: "string",
+      description: "Schema major.minor to validate against (default: the draft's declared version)"
+    },
+    "max-nudges": {
+      type: "string",
+      description: `Times to block before relenting so the step fails downstream as before (default: ${String(MAX_NUDGES_DEFAULT)})`
+    },
+    counter: {
+      type: "string",
+      description: "Path for the nudge counter (default: <draft>.nudges)"
+    },
+    "print-settings": {
+      type: "boolean",
+      description: "Print the Stop-hook settings JSON that wires this gate, then exit"
+    }
+  },
+  run: async ({ args }) => {
+    const draftPath = resolve$1(args.draft);
+    if (args["print-settings"]) {
+      const command = defaultHookCommand(draftPath, {
+        kind: args.kind,
+        schema: args.schema,
+        schemaVersion: args["schema-version"],
+        maxNudges: args["max-nudges"],
+        counter: args.counter
+      });
+      process.stdout.write(`${JSON.stringify(stopHookSettings(command))}
+`);
+      return;
+    }
+    drainStdin();
+    const kind = requireSchemaKind(args.kind || "findings");
+    const maxNudges = requireMaxNudges(args["max-nudges"]);
+    const counterPath = args.counter ? resolve$1(args.counter) : `${draftPath}.nudges`;
+    const state = draftState(
+      draftPath,
+      (parsed) => args.schema ? resolve$1(args.schema) : schemaPathFor(kind, args["schema-version"] || derivedSchemaVersion(kind, parsed))
+    );
+    const nudges = readNudges(counterPath);
+    const decision = decideGate(state, nudges, maxNudges, draftPath, kind);
+    if (decision.kind === "block") {
+      try {
+        bumpNudges(counterPath, nudges);
+      } catch (err) {
+        process.stderr.write(
+          `stop-gate: cannot persist nudge counter at ${counterPath} \u2192 allowing to avoid an unbounded block loop: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+        return;
+      }
+      process.stdout.write(`${JSON.stringify({ decision: "block", reason: decision.reason })}
+`);
+    }
+  }
+});
 var gatherCmd = defineCommand({
   meta: {
     name: "gather",
@@ -1867,7 +2093,7 @@ var postCmd = defineCommand({
     },
     "inline-template": {
       type: "string",
-      description: "Path to inline comment Eta template (default: built-in format)"
+      description: "Path to inline comment Eta template (default: bundled templates/inline.eta)"
     },
     route: {
       type: "string",
@@ -1899,21 +2125,24 @@ var postCmd = defineCommand({
     }
   },
   run: async ({ args }) => {
+    const priceResolution = resolvePrices(args.prices);
     await post({
       repo: args.repo,
       headSha: args["head-sha"],
       botLogin: args["bot-login"] || "github-actions[bot]",
       findingsPath: args.findings,
       envelopePath: args.usage,
-      pricesPath: resolvePricesPath(args.prices),
+      pricesPath: priceResolution.path,
+      pricesProvided: priceResolution.kind === "provided",
       templatePath: resolveTemplatePath(args.template),
-      inlineTemplatePath: args["inline-template"] ? resolve$1(args["inline-template"]) : void 0,
+      inlineTemplatePath: resolveInlineTemplatePath(args["inline-template"]),
       route: args.route,
       headBranch: args["head-branch"],
       effort: args.effort,
       testReportPath: args["test-report"],
       runUrl: args["run-url"],
-      jsonUrl: args["json-url"]
+      jsonUrl: args["json-url"],
+      postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
   }
 });
@@ -1921,7 +2150,7 @@ var main = defineCommand({
   meta: {
     name: "code-review",
     version: packageVersion,
-    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, lower-suggestions, cost, and validate findings JSON"
+    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, validate-patches, cost, validate, and stop-gate findings JSON"
   },
   subCommands: {
     gather: gatherCmd,
@@ -1932,8 +2161,9 @@ var main = defineCommand({
     validate: validateCmd,
     adapt: adaptCmd,
     extract: extractCmd,
-    "lower-suggestions": lowerSuggestionsCmd,
-    "print-schema": printSchemaCmd
+    "validate-patches": validatePatchesCmd,
+    "print-schema": printSchemaCmd,
+    "stop-gate": stopGateCmd
   }
 });
 if (!process.env["VITEST"]) {