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

package/README.md

@@ -25,8 +25,9 @@ the security boundary, and the cost.
 ## The CLI
 
 The npm package is the **deterministic commenter** — the presentation and posting layer that no
-model should do, plus the adapter glue between an agent CLI's native output and the spec's abstract
-envelope ([SPEC §6.1](SPEC.md#61-result-envelope)).
+model should do, plus the adapter glue between an agent CLI's native output and the abstract result
+envelope defined in [`src/schema.ts`](src/schema.ts) (the deliverable of
+[SPEC §3.2](SPEC.md#32-the-deliverable)).
 
 ```sh
 npm install -g @jphutchins/code-review
@@ -40,7 +41,7 @@ npx @jphutchins/code-review <subcommand>
 | `gather` | Resolve the PR from the CI head SHA and gather the review inputs (diff with git-diff fallback, PR context, prior bot review, failing-job logs) into the workspace for the agent |
 | `render` | Render the sticky-comment markdown from findings + usage + prices |
 | `inline` | Build the GitHub reviews `comments[]` payload from findings + diff (in-diff validation; strays demote to the summary) |
-| `adapt` | Map a native agent-CLI result envelope onto the abstract SPEC §6.1 envelope |
+| `adapt` | Map a native agent-CLI result envelope onto the abstract result envelope (`src/schema.ts`) |
 | `extract` | Recover findings/triage JSON from a native envelope via the deterministic extraction ladder |
 | `validate-patches` | Validate each finding's `patch` against the real PR-head file, aligning the finding's line range to it and keeping the patch (projected into a suggestion at render time), or dropping the patch |
 | `cost` | Recompute USD cost from the envelope's per-model token counts + a price map |
@@ -63,16 +64,17 @@ in [templates/](templates/). See [docs/adapters.md](docs/adapters.md) for the ad
    letting the CLI pick where your key gets sent.
 3. Commit `.github/prices.json` (fork [schema/prices.example.json](schema/prices.example.json) and
    fill in your provider's per-token rates) — without it the cost footer renders **$0**
-   ([SPEC §6.2](SPEC.md#62-price-map)).
+   ([SPEC §4.4](SPEC.md#44-required-controls-conformance)).
 4. Merge to your default branch first — `workflow_run` only fires from the default branch, so the
    introducing PR won't review itself — then open a test PR.
 5. First run: consider `egress-policy: audit` to discover the real allowlist, then switch to `block`
-   ([SPEC §8.4](SPEC.md#84-egress-allowlist)).
+   ([SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
 
 Every model knob is committed step `env` on the workflow's triage and review steps — models,
 efforts, the subagent model, and the tier aliases, right where each is consumed — edited and
-PR-reviewed like the rest of the file ([SPEC §8.5](SPEC.md#85-model-backend-env)). Only the backend
-endpoint is a per-repo **Actions variable** (`API_BASE_URL`, required, no default); pointing it at
+PR-reviewed like the rest of the file (implementation detail the spec deliberately leaves to this
+repo — see [SPEC Appendix A](SPEC.md#appendix-a--reference-realization-github-actions-non-normative)).
+Only the backend endpoint is a per-repo **Actions variable** (`API_BASE_URL`, required, no default); pointing it at
 another provider requires adding that provider's API host to the workflow's egress allowlist in the
 same reviewed PR.
 
@@ -87,8 +89,8 @@ links to:
   downstream tool) SHOULD base64-decode and parse that marker rather than parse the comment's prose.
   Embedding in the comment (rather than only linking the artifact) keeps the pointer from expiring
   with artifact retention; when the encoded findings are too large to embed, the sticky falls back to
-  a `<!-- code-review:findings-json <url> -->` link marker instead
-  ([SPEC §5.1 item 7](SPEC.md#51-sticky-summary-comment)).
+  a `<!-- code-review:findings-json <url> -->` link marker instead — the shared serializer is
+  [`src/surface.ts`](src/surface.ts).
 - **`code-review-transcript`** — the full Claude Code session transcripts for the triage and review
   phases. This is advisory/auditability only: it is never read by the comment job and never affects
   what gets posted.

package/dist/index.js

@@ -89,6 +89,10 @@ var drop = (reason) => ({
   kind: "drop",
   reason
 });
+var keep = (reason) => ({
+  kind: "keep",
+  reason
+});
 var parseHunk = (patch) => {
   const rawLines = patch.split("\n");
   const lines = rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
@@ -128,10 +132,12 @@ var validatePatch = (patch, fileLines) => {
   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");
+  if (removedCount === 0) {
+    return keep("pure insertion applies cleanly but has no removed 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 };
+  return { kind: "anchored", startLine: firstRemoved, endLine: lastRemoved };
 };
 var patchToSuggestion = (patch) => {
   const parsed = parseHunk(patch);
@@ -164,18 +170,28 @@ var severityEmoji = (s) => {
 };
 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");
+var encodeMarker = (document, jsonUrl, limit) => {
+  const b64 = Buffer.from(JSON.stringify(document), "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 findingsPointer = (findings, jsonUrl, limit = EMBED_LIMIT) => encodeMarker(findings, jsonUrl, limit);
+var findingPointer = (finding, schemaVersion, jsonUrl, limit = EMBED_LIMIT) => encodeMarker({ schema_version: schemaVersion, findings: [finding] }, jsonUrl, limit);
 var escapeFence = (text) => text.replace(/```/g, "`` ` ``");
 var projectPatch = (patch) => {
-  if (patch === null || patch === void 0) return { kind: "none" };
+  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 escapePipes = (text) => text.replace(/\|/g, "\\|");
@@ -215,6 +231,7 @@ var render = (input) => {
     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,
@@ -243,7 +260,8 @@ var render = (input) => {
           return `\u2753 ${v}`;
       }
     },
-    severityEmoji
+    severityEmoji,
+    formatConfidence
   });
 };
 var key = (path, line) => `${path}:${String(line)}`;
@@ -308,6 +326,7 @@ var renderCommentBody = (f, eta, template, modelsText, jsonUrl, pointer) => (
     ...f,
     patchProjection: projectPatch(f.patch),
     severityEmoji,
+    formatConfidence,
     modelsText,
     jsonUrl: jsonUrl ?? null,
     findingsPointer: pointer
@@ -319,8 +338,8 @@ var buildInlineComments = (findings, diff, context) => {
   const { inDiff, strays } = partitionFindings(findings, index);
   const eta = new Eta({ autoTrim: false });
   const modelsText = formatModels(models);
-  const pointer = context.findingsPointer ?? (fullFindings ? findingsPointer(fullFindings, jsonUrl) : "");
   const comments = inDiff.map((f) => {
+    const pointer = fullFindings ? findingPointer(f, fullFindings.schema_version, jsonUrl) : "";
     const comment = {
       path: f.path,
       line: f.end_line,
@@ -388,7 +407,7 @@ var FindingShape = t.intersection([
     code: t.string,
     code_url: t.string,
     recommendation: t.string,
-    patch: t.union([t.string, t.null])
+    patch: t.string
   })
 ]);
 var EndGeStart = t.refinement(
@@ -528,6 +547,8 @@ 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 = [
   {
@@ -745,11 +766,7 @@ var parseHtmlUrl = (raw) => {
   }
 };
 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 pointer = reviewBodyPointer(headSha, stickyUrl, marker);
   const body = JSON.stringify({
     body: pointer,
     commit_id: headSha,
@@ -859,6 +876,84 @@ var dismissReviews = async (repo, prNumber, ids, ghApi) => {
     }
   }
 };
+var REVIEW_THREAD_COMMENTS_QUERY = "query($owner:String!,$name:String!,$pr:Int!){repository(owner:$owner,name:$name){pullRequest(number:$pr){reviewThreads(first:100){pageInfo{hasNextPage}nodes{comments(first:100){nodes{id isMinimized author{login} originalCommit{oid}}}}}}}}";
+var MINIMIZE_COMMENT_MUTATION = "mutation($id:ID!){minimizeComment(input:{subjectId:$id,classifier:OUTDATED}){minimizedComment{isMinimized}}}";
+var supersededCommentId = (c, headSha, logins) => {
+  if (typeof c !== "object" || c === null) return null;
+  const o = c;
+  const login = o.author?.login;
+  const oid = o.originalCommit?.oid;
+  return typeof o.id === "string" && o.isMinimized !== true && typeof login === "string" && logins.includes(login) && typeof oid === "string" && oid !== headSha ? o.id : null;
+};
+var supersededBotCommentIds = (raw, headSha, botLogin) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ids: [], truncated: false };
+  }
+  const conn = parsed.data?.repository?.pullRequest?.reviewThreads;
+  const truncated = conn?.pageInfo?.hasNextPage === true;
+  const nodes = conn?.nodes;
+  if (!Array.isArray(nodes)) return { ids: [], truncated };
+  const logins = [botLogin.replace(/\[bot\]$/, ""), botLogin];
+  const ids = nodes.flatMap((t4) => {
+    const cnodes = t4.comments?.nodes;
+    return Array.isArray(cnodes) ? cnodes.map((c) => supersededCommentId(c, headSha, logins)).filter((id) => id !== null) : [];
+  });
+  return { ids, truncated };
+};
+var minimizeSupersededComments = async (repo, prNumber, headSha, botLogin, ghApi) => {
+  const slash = repo.indexOf("/");
+  if (slash <= 0) return;
+  const owner = repo.slice(0, slash);
+  const name = repo.slice(slash + 1);
+  let raw;
+  try {
+    raw = await ghApi([
+      "graphql",
+      "-f",
+      `query=${REVIEW_THREAD_COMMENTS_QUERY}`,
+      "-f",
+      `owner=${owner}`,
+      "-f",
+      `name=${name}`,
+      "-F",
+      `pr=${String(prNumber)}`
+    ]);
+  } catch (err) {
+    process.stderr.write(
+      `Warning: could not list review threads to minimize stale comments on PR #${String(prNumber)}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return;
+  }
+  const { ids, truncated } = supersededBotCommentIds(raw, headSha, botLogin);
+  if (truncated) {
+    process.stderr.write(
+      `Note: PR #${String(prNumber)} has more than 100 review threads \u2014 only the first 100 were scanned for stale bot comments
+`
+    );
+  }
+  let minimized = 0;
+  for (const id of ids) {
+    try {
+      await ghApi(["graphql", "-f", `query=${MINIMIZE_COMMENT_MUTATION}`, "-f", `id=${id}`]);
+      minimized += 1;
+    } catch (err) {
+      process.stderr.write(
+        `Warning: failed to minimize a stale review comment on PR #${String(prNumber)}: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
+  }
+  if (minimized > 0) {
+    process.stderr.write(
+      `Minimized ${String(minimized)} stale inline comment(s) from superseded reviews on PR #${String(prNumber)}
+`
+    );
+  }
+};
 var post = async (input, ghApi = runGhApi) => {
   const candidates = await fetchPrCandidates(input.repo, input.headSha, ghApi);
   const resolution = resolvePr(candidates, input.headBranch);
@@ -901,7 +996,8 @@ var post = async (input, ghApi = runGhApi) => {
       reviewedSha: input.headSha,
       effort: input.effort,
       runUrl: input.runUrl,
-      jsonUrl: input.jsonUrl
+      jsonUrl: input.jsonUrl,
+      postedAt: input.postedAt
     })
   );
   if (isEmptyDiff(diff)) {
@@ -942,7 +1038,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);
@@ -955,7 +1052,8 @@ var post = async (input, ghApi = runGhApi) => {
   const { comments: rawComments, strays } = buildInlineComments(findings.findings, diff, {
     inlineTemplate,
     models: envelope.models.map((m) => m.model),
-    findingsPointer: findingsMarker
+    findings,
+    jsonUrl: input.jsonUrl
   });
   const { comments, longFiles } = checkLongSuggestions(rawComments);
   for (const wf of longFiles) {
@@ -981,7 +1079,8 @@ var post = async (input, ghApi = runGhApi) => {
     strays,
     runUrl: input.runUrl,
     jsonUrl: input.jsonUrl,
-    findingsPointer: findingsMarker
+    findingsPointer: findingsMarker,
+    postedAt: input.postedAt
   };
   const longFilesNote = longFiles.length > 0 ? `
 
@@ -1022,6 +1121,7 @@ var post = async (input, ghApi = runGhApi) => {
     `Posted ${String(comments.length)} inline comments on PR #${String(prNumber)}
 `
   );
+  await minimizeSupersededComments(input.repo, prNumber, input.headSha, input.botLogin, ghApi);
   if (stickyRef !== null) {
     const confirmedDisposition = {
       kind: "posted",
@@ -1597,7 +1697,8 @@ var renderCmd = defineCommand({
       reviewedSha: args["reviewed-sha"],
       route: args.route,
       effort: args.effort,
-      testReport
+      testReport,
+      postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
     process.stdout.write(output);
   }
@@ -1813,7 +1914,7 @@ var readFileLines = (path) => {
   }
 };
 var validateFinding = (finding, repoRoot) => {
-  if (finding.patch === void 0 || finding.patch === null) return finding;
+  if (finding.patch === void 0) return finding;
   const lines = readFileLines(resolve$1(repoRoot, finding.path));
   if (lines === null) {
     process.stderr.write(
@@ -1823,19 +1924,23 @@ var validateFinding = (finding, repoRoot) => {
     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
+  switch (result.kind) {
+    case "anchored":
+      return { ...finding, start_line: result.startLine, end_line: result.endLine };
+    case "keep":
+      return finding;
+    case "drop":
+      process.stderr.write(
+        `validate-patches: ${finding.path}:${String(finding.start_line)}: ${result.reason} \u2014 dropping patch
 `
-    );
-    return withoutPatch(finding);
+      );
+      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)"
+    description: "Validate each finding's patch against the real PR-head tree, aligning the finding's range and keeping the patch when it anchors, keeping it unaligned when it's a pure insertion, or dropping it when it doesn't apply (issue #10)"
   },
   args: {
     findings: {
@@ -2128,7 +2233,8 @@ var postCmd = defineCommand({
       effort: args.effort,
       testReportPath: args["test-report"],
       runUrl: args["run-url"],
-      jsonUrl: args["json-url"]
+      jsonUrl: args["json-url"],
+      postedAt: formatUtc(/* @__PURE__ */ new Date())
     });
   }
 });