@jphutchins/code-review 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/index.js

@@ -53,15 +53,138 @@ 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 === null || patch === void 0) return { kind: "none" };
+  const lowered = patchToSuggestion(patch);
+  return typeof lowered === "string" ? { kind: "suggestion", text: escapeFence(lowered) } : { kind: "patch", raw: escapeFence(patch) };
+};
+
 // 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,
@@ -77,6 +200,7 @@ 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(", ") : "";
@@ -85,6 +209,7 @@ var render = (input) => {
     envelope: input.envelope,
     usageAvailable,
     costReport,
+    pricesProvided,
     route,
     effort,
     modelNames,
@@ -93,8 +218,14 @@ var render = (input) => {
     severityCounts: input.severityCounts ?? computeSeverityCounts(input.findings.findings),
     strays: (input.strays ?? []).map(sanitizeFinding),
     inlineDisposition: input.inlineDisposition ?? null,
+    runUrl: input.runUrl ?? null,
+    jsonUrl: input.jsonUrl ?? null,
+    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.toFixed(3)}` : "\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);
@@ -112,20 +243,7 @@ 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
   });
 };
 var key = (path, line) => `${path}:${String(line)}`;
@@ -182,33 +300,32 @@ var partitionFindings = (findings, index) => {
 };
 
 // src/inline.ts
-var escapeBackticks2 = (text) => text.replace(/```/g, "`` ` ``");
-var buildCommentBody = (f) => {
-  const parts = [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) => {
-  return eta.renderString(template, {
+var formatModels = (models) => models.length > 0 ? models.map((m) => `\`${m}\``).join("/") : "an AI model";
+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
-  });
-};
-var buildInlineComments = (findings, diff, inlineTemplate) => {
+    patchProjection: projectPatch(f.patch),
+    severityEmoji,
+    modelsText,
+    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) : buildCommentBody(f)
+      body: renderCommentBody(f, eta, inlineTemplate, modelsText, jsonUrl, pointer)
     };
     if (f.start_line < f.end_line) {
       return {
@@ -262,14 +379,16 @@ 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
+    code_url: t.string,
+    recommendation: t.string,
+    patch: t.union([t.string, t.null])
   })
 ]);
 var EndGeStart = t.refinement(
@@ -345,7 +464,13 @@ var TestSummaryCodec = t.intersection([
     failures: t.array(TestFailureCodec)
   })
 ]);
-var DEFAULT_SCHEMA_VERSION = "0.2.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;
@@ -381,10 +506,32 @@ var unsafeUnwrap = (decoded) => {
   if (decoded._tag === "Right") return decoded.right;
   throw new Error("io-ts decode failed \u2014 data does not match expected shape");
 };
+
+// src/format.ts
+var FENCE_RE = /^\s*```/;
+var scanLine = (state, line) => {
+  if (FENCE_RE.test(line)) {
+    return { lines: [...state.lines, line], inFence: !state.inFence, blankRun: 0 };
+  }
+  if (state.inFence) {
+    return { lines: [...state.lines, line], inFence: true, blankRun: 0 };
+  }
+  const trimmed = line.replace(/[ \t]+$/, "");
+  if (trimmed !== "") {
+    return { lines: [...state.lines, trimmed], inFence: false, blankRun: 0 };
+  }
+  const blankRun = state.blankRun + 1;
+  return blankRun === 1 ? { lines: [...state.lines, ""], inFence: false, blankRun } : { ...state, blankRun };
+};
+var formatMarkdown = (md) => {
+  const { lines } = md.split("\n").reduce(scanLine, { lines: [], inFence: false, blankRun: 0 });
+  return `${lines.join("\n").replace(/\n+$/, "")}
+`;
+};
 var identity = (decoded) => decoded;
 var findingsTable = [
   {
-    minor: "0.2",
+    minor: "0.4",
     defaultVersion: DEFAULT_SCHEMA_VERSION,
     schemaFile: "findings.schema.json",
     codec: FindingsCodec,
@@ -528,12 +675,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 {
@@ -595,9 +736,22 @@ var loadTestReport = (path) => {
   }
   return decoded.right;
 };
-var postInlineReview = async (repo, prNumber, headSha, comments, ghApi) => {
+var parseHtmlUrl = (raw) => {
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed.html_url === "string" ? parsed.html_url : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var postInlineReview = async (repo, prNumber, headSha, comments, stickyUrl, marker, ghApi) => {
+  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.`;
+  const pointer = marker ? `${marker}
+
+${linkLine}` : linkLine;
   const body = JSON.stringify({
-    body: `\u{1F916} Automated code review for \`${headSha.slice(0, 7)}\` \u2014 verdict, walkthrough, and cost are in the summary comment.`,
+    body: pointer,
     commit_id: headSha,
     event: "COMMENT",
     comments: comments.map((c) => ({
@@ -605,10 +759,14 @@ var postInlineReview = async (repo, prNumber, headSha, comments, ghApi) => {
       line: c.line,
       side: c.side,
       ...c.start_line !== void 0 && c.start_side !== void 0 ? { start_line: c.start_line, start_side: c.start_side } : {},
-      body: c.body
+      body: formatMarkdown(c.body)
     }))
   });
-  await ghApi([`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"], body);
+  const stdout = await ghApi(
+    [`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"],
+    body
+  );
+  return parseHtmlUrl(stdout);
 };
 var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   const stdout = await ghApi(
@@ -628,30 +786,42 @@ var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   const parsed = JSON.parse(last);
   return { id: parsed.id, body: parsed.body };
 };
+var parseCommentRef = (raw) => {
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed.id === "number" && typeof parsed.html_url === "string" ? { id: parsed.id, html_url: parsed.html_url } : null;
+  } catch {
+    return null;
+  }
+};
 var patchComment = async (repo, commentId, body, ghApi) => {
-  await ghApi(
+  const stdout = await ghApi(
     [`repos/${repo}/issues/comments/${String(commentId)}`, "--input", "-"],
     JSON.stringify({ body })
   );
+  const htmlUrl = parseHtmlUrl(stdout);
+  return htmlUrl !== void 0 ? { html_url: htmlUrl } : null;
 };
 var postComment = async (repo, prNumber, body, ghApi) => {
-  await ghApi(
+  const stdout = await ghApi(
     [`repos/${repo}/issues/${String(prNumber)}/comments`, "--input", "-"],
     JSON.stringify({ body })
   );
+  return parseCommentRef(stdout);
 };
 var upsertSticky = async (repo, prNumber, existing, body, ghApi) => {
   if (existing !== null) {
-    await patchComment(repo, existing.id, body, ghApi);
+    const patched = await patchComment(repo, existing.id, body, ghApi);
     process.stderr.write(
       `Updated sticky comment #${String(existing.id)} on PR #${String(prNumber)}
 `
     );
-  } else {
-    await postComment(repo, prNumber, body, ghApi);
-    process.stderr.write(`Posted new sticky comment on PR #${String(prNumber)}
-`);
+    return { id: existing.id, url: patched?.html_url };
   }
+  const posted = await postComment(repo, prNumber, body, ghApi);
+  process.stderr.write(`Posted new sticky comment on PR #${String(prNumber)}
+`);
+  return posted ? { id: posted.id, url: posted.html_url } : null;
 };
 var isBotReview = (r) => typeof r === "object" && r !== null && typeof r.id === "number" && typeof r.state === "string" && typeof r.user?.login === "string";
 var fetchBotReviews = async (repo, prNumber, botLogin, ghApi) => {
@@ -719,16 +889,21 @@ 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 renderNotice = (message) => render({
-    findings: noticeFindings(message),
-    envelope: null,
-    prices: decodedPrices.right,
-    template,
-    route: input.route,
-    reviewedSha: input.headSha,
-    effort: input.effort
-  });
+  const inlineTemplate = readFileSync(input.inlineTemplatePath, "utf-8");
+  const renderNotice = (message) => formatMarkdown(
+    render({
+      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
+    })
+  );
   if (isEmptyDiff(diff)) {
     await upsertSticky(
       input.repo,
@@ -754,28 +929,34 @@ var post = async (input, ghApi = runGhApi) => {
   const envelope = loadEnvelope(input.envelopePath);
   const testReport = input.testReportPath ? loadTestReport(input.testReportPath) : void 0;
   if (envelope === null) {
-    const body2 = render({
-      findings,
-      envelope: null,
-      prices: decodedPrices.right,
-      template,
-      route: input.route,
-      reviewedSha: input.headSha,
-      effort: input.effort,
-      testReport,
-      inlineDisposition: { kind: "no-envelope" }
-    });
-    await upsertSticky(input.repo, prNumber, existingSticky, body2, ghApi);
+    const body = formatMarkdown(
+      render({
+        findings,
+        envelope: null,
+        prices: decodedPrices.right,
+        pricesProvided: input.pricesProvided,
+        template,
+        route: input.route,
+        reviewedSha: input.headSha,
+        effort: input.effort,
+        testReport,
+        inlineDisposition: { kind: "no-envelope" },
+        runUrl: input.runUrl,
+        jsonUrl: input.jsonUrl
+      })
+    );
+    await upsertSticky(input.repo, prNumber, existingSticky, body, ghApi);
     process.stderr.write(
       "Result envelope missing or malformed \u2014 posted sticky summary without usage/cost data; no inline review\n"
     );
     process.exit(0);
   }
-  const { comments: rawComments, strays } = buildInlineComments(
-    findings.findings,
-    diff,
-    inlineTemplate
-  );
+  const findingsMarker = findingsPointer(findings, input.jsonUrl);
+  const { comments: rawComments, strays } = buildInlineComments(findings.findings, diff, {
+    inlineTemplate,
+    models: envelope.models.map((m) => m.model),
+    findingsPointer: findingsMarker
+  });
   const { comments, longFiles } = checkLongSuggestions(rawComments);
   for (const wf of longFiles) {
     process.stderr.write(
@@ -785,11 +966,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 body = render({
+  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,
@@ -797,14 +979,24 @@ var post = async (input, ghApi = runGhApi) => {
     testReport,
     severityCounts: computeSeverityCounts(findings.findings),
     strays,
-    inlineDisposition
-  }) + (longFiles.length > 0 ? `
+    runUrl: input.runUrl,
+    jsonUrl: input.jsonUrl,
+    findingsPointer: findingsMarker
+  };
+  const longFilesNote = longFiles.length > 0 ? `
 
 ---
 
 > **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.
-` : "");
-  await upsertSticky(input.repo, prNumber, existingSticky, body, 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(
@@ -817,11 +1009,41 @@ var post = async (input, ghApi = runGhApi) => {
   if (stalePriorReviewIds.length > 0) {
     await dismissReviews(input.repo, prNumber, stalePriorReviewIds, ghApi);
   }
-  await postInlineReview(input.repo, prNumber, input.headSha, comments, ghApi);
+  const reviewUrl = await postInlineReview(
+    input.repo,
+    prNumber,
+    input.headSha,
+    comments,
+    stickyRef?.url,
+    findingsMarker,
+    ghApi
+  );
   process.stderr.write(
     `Posted ${String(comments.length)} inline comments on PR #${String(prNumber)}
 `
   );
+  if (stickyRef !== null) {
+    const confirmedDisposition = {
+      kind: "posted",
+      count: comments.length,
+      sha: input.headSha
+    };
+    try {
+      await patchComment(
+        input.repo,
+        stickyRef.id,
+        renderBody(confirmedDisposition, reviewUrl),
+        ghApi
+      );
+      process.stderr.write(`Linked sticky comment #${String(stickyRef.id)} to the review
+`);
+    } catch (err) {
+      process.stderr.write(
+        `Warning: failed to link the sticky summary to the review: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
+  }
 };
 var renderOutputs = (result) => {
   switch (result.kind) {
@@ -1032,7 +1254,7 @@ var candidateFromJsonText = (kind, text) => {
 };
 var FENCE_OPEN = /^\s*(`{3,})/;
 var FENCE_MARKER_ONLY = /^`+$/;
-var scanLine = (state, line) => {
+var scanLine2 = (state, line) => {
   if (state.openLength === null) {
     const opened = FENCE_OPEN.exec(line)?.[1]?.length;
     return opened !== void 0 ? { blocks: state.blocks, openLength: opened, buffer: [] } : state;
@@ -1041,7 +1263,7 @@ var scanLine = (state, line) => {
   const closes = FENCE_MARKER_ONLY.test(trimmed) && trimmed.length >= state.openLength;
   return closes ? { blocks: [...state.blocks, state.buffer.join("\n")], openLength: null, buffer: [] } : { ...state, buffer: [...state.buffer, line] };
 };
-var scanFencedBlocks = (text) => text.split("\n").reduce(scanLine, { blocks: [], openLength: null, buffer: [] }).blocks;
+var scanFencedBlocks = (text) => text.split("\n").reduce(scanLine2, { blocks: [], openLength: null, buffer: [] }).blocks;
 var ladderFailureDiagnostics = (input) => {
   const native = parseNativeForExtraction(input.native);
   const preview = (s) => {
@@ -1144,24 +1366,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) {
@@ -1175,6 +1415,86 @@ var adapt = (adapterName, native, agentFilePath, meta = {}) => {
     }
   }
 };
+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 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 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) };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return {
+      kind: "invalid",
+      errors: [`not valid JSON: ${err instanceof Error ? err.message : String(err)}`]
+    };
+  }
+  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)] };
+  }
+};
+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) => {
@@ -1210,12 +1530,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({
@@ -1263,14 +1584,15 @@ 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,
@@ -1298,14 +1620,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)
     );
@@ -1335,8 +1660,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",
@@ -1475,6 +1799,66 @@ ${ladderFailureDiagnostics(input)}
     fail(describeLadderFailure(outcome));
   }
 });
+var withoutPatch = (finding) => {
+  const copy = { ...finding };
+  delete copy.patch;
+  return copy;
+};
+var readFileLines = (path) => {
+  try {
+    const rawLines = readFileSync(path, "utf-8").split("\n");
+    return rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+  } catch {
+    return null;
+  }
+};
+var validateFinding = (finding, repoRoot) => {
+  if (finding.patch === void 0 || finding.patch === null) return finding;
+  const lines = readFileLines(resolve$1(repoRoot, finding.path));
+  if (lines === null) {
+    process.stderr.write(
+      `validate-patches: ${finding.path}: could not read file at "${repoRoot}" \u2014 dropping patch
+`
+    );
+    return withoutPatch(finding);
+  }
+  const result = validatePatch(finding.patch, lines);
+  if ("kind" in result) {
+    process.stderr.write(
+      `validate-patches: ${finding.path}:${String(finding.start_line)}: ${result.reason} \u2014 dropping patch
+`
+    );
+    return withoutPatch(finding);
+  }
+  return { ...finding, start_line: result.startLine, end_line: result.endLine };
+};
+var validatePatchesCmd = defineCommand({
+  meta: {
+    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: {
+      type: "positional",
+      description: "Path to findings JSON",
+      required: true
+    },
+    "repo-root": {
+      type: "string",
+      description: "Directory to resolve each finding's path against \u2014 the review job's checked-out, clean PR-head tree (default: .)"
+    }
+  },
+  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 validated = {
+      ...findings,
+      findings: findings.findings.map((f) => validateFinding(f, repoRoot))
+    };
+    process.stdout.write(`${JSON.stringify(validated, null, 2)}
+`);
+  }
+});
 var requireAdapterName = (name) => {
   if (isAdapterName(name)) return name;
   fail(`Unknown adapter "${name}" \u2014 supported: claude-code`);
@@ -1521,6 +1905,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",
@@ -1605,7 +2080,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",
@@ -1626,22 +2101,34 @@ var postCmd = defineCommand({
     "test-report": {
       type: "string",
       description: TEST_REPORT_DESCRIPTION
+    },
+    "run-url": {
+      type: "string",
+      description: "Workflow run URL (transcript/traces), rendered as a link in the LLM Disclosure aside"
+    },
+    "json-url": {
+      type: "string",
+      description: "URL to the machine-readable findings JSON artifact, pointed at from the sticky and each inline comment"
     }
   },
   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"]
+      testReportPath: args["test-report"],
+      runUrl: args["run-url"],
+      jsonUrl: args["json-url"]
     });
   }
 });
@@ -1649,7 +2136,7 @@ var main = defineCommand({
   meta: {
     name: "code-review",
     version: packageVersion,
-    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, 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,
@@ -1660,7 +2147,9 @@ var main = defineCommand({
     validate: validateCmd,
     adapt: adaptCmd,
     extract: extractCmd,
-    "print-schema": printSchemaCmd
+    "validate-patches": validatePatchesCmd,
+    "print-schema": printSchemaCmd,
+    "stop-gate": stopGateCmd
   }
 });
 if (!process.env["VITEST"]) {