@mechanai/deepreview 2.2.2 → 2.2.3

package/.opencode/agents/deepreview-review-formatter.md

@@ -77,6 +77,38 @@ line: <line number>
 - If the synthesis says "line 42" but looking at the diff that corresponds to a different new-side line, use the correct new-side line
 - If you cannot determine an exact line, use the first line of the relevant function/block
 
+## Suggestion block rules
+
+When a finding contains a ` ```suggestion ` block, the `startLine..line` anchor MUST cover every line that the suggestion replaces — not just the line referenced in the synthesis.
+
+Before writing a suggestion:
+
+1. Identify the exact lines in the diff that will be replaced by the suggestion content
+2. Count those lines — this is your replacement scope
+3. Set `startLine` to the first line being replaced and `line` to the last
+4. The anchor range (startLine..line) MUST cover all original lines being removed or modified. The suggestion may be shorter than the anchor range (deletions are fine), but should not be longer — if your replacement has more lines than the anchor covers, widen the anchor to include all affected lines.
+
+Example — replacing a 5-line callout block (lines 246-250). Note: use exactly three backticks for suggestion blocks in output — the four-backtick fence below is only for illustration:
+
+````
+---
+path: docs/migration.md
+startLine: 246
+line: 250
+---
+```suggestion
+> [!WARNING]
+> The actual default is 1 MB, not 10 MB.
+```
+````
+
+Common mistakes to avoid:
+
+- Anchoring to a single line inside a multi-line block (e.g., `line: 247` when replacing lines 246-250) — this duplicates surrounding lines when applied
+- Including lines in the suggestion body that already exist outside the anchor range — this creates duplicates
+- If you cannot determine the exact replacement scope from the diff, use prose instead of a suggestion block
+- As a safety net, the posting pipeline strips suggestion blocks that exceed the anchor range — if your suggestion disappears, widen the anchor
+
 ## Response contract
 
 After writing the threads file, your ONLY response must be the absolute path to your output file and a count line (e.g., "12 threads written"). Do not summarize findings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Multi-agent parallel code/spec review for OpenCode",
   "license": "MIT",
   "repository": {

package/src/diff-classifier.ts

@@ -9,6 +9,8 @@ export interface Finding {
 
 export interface ClassifiedFinding extends Finding {
   tier: 1 | 2 | 3;
+  /** Body with suggestion blocks stripped for rendering. Set for tier-1 findings with oversized suggestions and all tier-2 findings containing suggestions. Original `body` is used for ID computation. Set in review-helpers.ts, not in classifyFindings. */
+  renderedBody?: string;
 }
 
 interface FileHunks {

package/src/post-review.ts

@@ -65,7 +65,7 @@ async function updateExistingThreads(
     const batch = toUpdate.slice(i, i + CONCURRENCY);
     await Promise.all(
       batch.map(async ({ finding, commentId, id }) => {
-        const body = embedFindingId(finding.body, id);
+        const body = embedFindingId(finding.renderedBody ?? finding.body, id);
         await updateReviewComment(commentId, body);
       }),
     );
@@ -147,7 +147,7 @@ async function postInlineThreads(
       batch.map(async (f) => {
         const id = findingId(f.path, f.startLine, f.line, f.body);
         // Body rendered by GitHub's Markdown sanitizer; no escaping needed here
-        const body = embedFindingId(f.body, id);
+        const body = embedFindingId(f.renderedBody ?? f.body, id);
         const ok = await postWithRetry(reviewId, f, body);
         return ok ? null : id;
       }),

package/src/review-helpers.test.ts

@@ -0,0 +1,170 @@
+import { describe, it } from "bun:test";
+import assert from "node:assert/strict";
+import { validateSuggestionAnchors, classifyAndLog } from "./review-helpers.ts";
+
+describe("validateSuggestionAnchors — no warnings", () => {
+  it("returns no warnings for findings without suggestion blocks", () => {
+    const findings = [
+      { path: "foo.go", line: 10, body: "This is just prose feedback.", tier: 1 as const },
+    ];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+
+  it("returns no warnings when suggestion lines fit within anchor range", () => {
+    const body = [
+      "Replace this function:",
+      "```suggestion",
+      "func foo() {",
+      "  return 42",
+      "}",
+      "```",
+    ].join("\n");
+    // Anchor covers 3 lines (8..10), suggestion has 3 lines — matches
+    const findings = [{ path: "foo.go", startLine: 8, line: 10, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+
+  it("ignores non-suggestion fenced code blocks", () => {
+    const body = [
+      "Example:",
+      "```go",
+      "func foo() {}",
+      "func bar() {}",
+      "func baz() {}",
+      "```",
+    ].join("\n");
+    const findings = [{ path: "foo.go", line: 5, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+
+  it("skips tier 2 and tier 3 findings", () => {
+    const body = ["```suggestion", "a", "b", "c", "```"].join("\n");
+    const findings = [
+      { path: "foo.go", line: 5, body, tier: 2 as const },
+      { path: "bar.go", line: 10, body, tier: 3 as const },
+    ];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 0);
+  });
+});
+
+describe("validateSuggestionAnchors — warnings", () => {
+  it("warns when suggestion has more lines than anchor range", () => {
+    const body = [
+      "Fix this:",
+      "```suggestion",
+      "line1",
+      "line2",
+      "line3",
+      "line4",
+      "line5",
+      "```",
+    ].join("\n");
+    // Anchor is single-line (31), suggestion has 5 lines
+    const findings = [{ path: "mise.toml", line: 31, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 1);
+    assert.ok(warnings[0].includes("mise.toml:31"));
+    assert.ok(warnings[0].includes("1-line anchor"));
+    assert.ok(warnings[0].includes("5-line suggestion"));
+  });
+
+  it("warns for multi-line anchor that is still too narrow", () => {
+    const body = ["```suggestion", "line1", "line2", "line3", "line4", "line5", "```"].join("\n");
+    // Anchor covers 2 lines (893..894), suggestion has 5 lines
+    const findings = [{ path: "migration.md", startLine: 893, line: 894, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    assert.equal(warnings.length, 1);
+    assert.ok(warnings[0].includes("migration.md:893-894"));
+    assert.ok(warnings[0].includes("2-line anchor"));
+  });
+
+  it("handles multiple suggestion blocks — warns based on largest", () => {
+    const body = [
+      "First fix:",
+      "```suggestion",
+      "a",
+      "b",
+      "c",
+      "```",
+      "Second fix:",
+      "```suggestion",
+      "x",
+      "y",
+      "```",
+    ].join("\n");
+    // Single-line anchor, two suggestion blocks (3 lines and 2 lines)
+    const findings = [{ path: "foo.go", line: 5, body, tier: 1 as const }];
+    const warnings = validateSuggestionAnchors(findings);
+    // Should warn — the largest suggestion (3 lines) exceeds the 1-line anchor
+    assert.equal(warnings.length, 1);
+    assert.ok(warnings[0].includes("3-line suggestion"));
+  });
+});
+
+// Minimal diff that puts foo.go line 10 in a hunk (tier 1)
+const DIFF_FOO = `diff --git a/foo.go b/foo.go
+--- a/foo.go
++++ b/foo.go
+@@ -1,15 +1,15 @@
+ line1
+ line2
+ line3
+ line4
+ line5
+ line6
+ line7
+ line8
+ line9
+-old
++new
+ line11
+ line12
+ line13
+ line14
+ line15
+`;
+
+describe("classifyAndLog — suggestion stripping", () => {
+  it("sets renderedBody when suggestion exceeds anchor", () => {
+    const body = ["Replace this:", "```suggestion", "line A", "line B", "line C", "```"].join("\n");
+    // Single-line anchor (no startLine), 3-line suggestion — exceeds
+    const findings = [{ path: "foo.go", line: 10, body }];
+    const { tier1 } = classifyAndLog(findings, DIFF_FOO);
+    assert.equal(tier1.length, 1);
+    assert.notEqual(tier1[0].renderedBody, undefined);
+    assert.ok(!tier1[0].renderedBody!.includes("```suggestion"));
+    // Original body is untouched
+    assert.ok(tier1[0].body.includes("```suggestion"));
+  });
+
+  it("preserves content from unclosed suggestion blocks", () => {
+    const body = [
+      "Some prose",
+      "```suggestion",
+      "line A",
+      "line B",
+      // No closing fence
+    ].join("\n");
+    const findings = [{ path: "foo.go", line: 10, body }];
+    const { tier1 } = classifyAndLog(findings, DIFF_FOO);
+    assert.equal(tier1.length, 1);
+    // renderedBody should contain the unclosed block content
+    const rendered = tier1[0].renderedBody ?? tier1[0].body;
+    assert.ok(rendered.includes("line A"));
+    assert.ok(rendered.includes("line B"));
+  });
+
+  it("handles inverted startLine/line without negative anchorLines", () => {
+    const body = ["Fix:", "```suggestion", "x", "```"].join("\n");
+    // startLine > line (inverted) — anchorLines should clamp to 1
+    const findings = [{ path: "foo.go", startLine: 12, line: 10, body }];
+    const { tier1 } = classifyAndLog(findings, DIFF_FOO);
+    assert.equal(tier1.length, 1);
+    // 1-line suggestion vs clamped 1-line anchor — fits, no stripping
+    assert.equal(tier1[0].renderedBody, undefined);
+  });
+});

package/src/review-helpers.ts

@@ -4,6 +4,7 @@ import { classifyFindings, type Finding, type ClassifiedFinding } from "./diff-c
 const FINDING_ID_RE = /<!-- finding:([a-f0-9]+) -->/u;
 const AI_TRAILER = "\n\n---\n🤖 Review generated by AI";
 const GITHUB_NAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u;
+const SUGGESTION_OPEN_RE = /^```suggestion\b/u;
 
 export function escapeHtml(s: string): string {
   return s
@@ -96,9 +97,9 @@ export function buildReviewBody(
     }
     if (validOid && validRepo) {
       const permalink = `https://github.com/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/blob/${headOid}/${f.path.split("/").map(encodeURIComponent).join("/")}#L${f.line}`;
-      body += `<details>\n<summary><a href="${permalink}"><code>${escapeHtml(f.path)}:${f.line}</code></a></summary>\n\n${f.body}\n</details>\n\n`;
+      body += `<details>\n<summary><a href="${permalink}"><code>${escapeHtml(f.path)}:${f.line}</code></a></summary>\n\n${f.renderedBody ?? f.body}\n</details>\n\n`;
     } else {
-      body += `<details>\n<summary><code>${escapeHtml(f.path)}:${f.line}</code></summary>\n\n${f.body}\n</details>\n\n`;
+      body += `<details>\n<summary><code>${escapeHtml(f.path)}:${f.line}</code></summary>\n\n${f.renderedBody ?? f.body}\n</details>\n\n`;
     }
   }
   body += AI_TRAILER;
@@ -127,5 +128,134 @@ export function classifyAndLog(
   for (const f of tier3) {
     console.warn(`WARN: ${f.path}:${f.line} demoted to review body`);
   }
+  // Identify findings whose suggestion blocks exceed the anchor range
+  const oversized = findingsExceedingAnchor(classified);
+  const suggestionWarnings = formatSuggestionWarnings(oversized);
+  for (const w of suggestionWarnings) {
+    console.warn(w);
+  }
+  // Strip oversized suggestion blocks from tier-1 findings
+  for (const f of tier1) {
+    if (oversized.has(f)) {
+      f.renderedBody = stripSuggestionBlocks(f.body);
+    }
+  }
+  // Tier-2 findings are posted as file-level comments where suggestion blocks
+  // render as inert code — strip them unconditionally.
+  for (const f of tier2) {
+    const stripped = stripSuggestionBlocks(f.body);
+    if (stripped !== f.body) {
+      f.renderedBody = stripped;
+    }
+  }
+  // Tier-3 findings are posted inside the review body where suggestion blocks
+  // render as inert code — strip them unconditionally.
+  for (const f of tier3) {
+    const stripped = stripSuggestionBlocks(f.body);
+    if (stripped !== f.body) {
+      f.renderedBody = stripped;
+    }
+  }
   return { tier1, tier2, tier3 };
 }
+
+/**
+ * Find the largest ```suggestion block in a finding body by line count.
+ * Returns the maximum line count across all suggestion blocks, or 0 if none.
+ */
+function maxSuggestionLines(body: string): number {
+  let max = 0;
+  let inSuggestion = false;
+  let count = 0;
+  for (const line of body.split("\n")) {
+    if (!inSuggestion && SUGGESTION_OPEN_RE.test(line.trim())) {
+      inSuggestion = true;
+      count = 0;
+    } else if (inSuggestion && line.trimEnd() === "```") {
+      inSuggestion = false;
+      max = Math.max(max, count);
+    } else if (inSuggestion) {
+      count++;
+    }
+  }
+  if (inSuggestion) {
+    max = Math.max(max, count);
+  }
+  return max;
+}
+
+/**
+ * Remove all ```suggestion blocks from a finding body, preserving other content.
+ */
+function stripSuggestionBlocks(body: string): string {
+  const lines = body.split("\n");
+  const result: string[] = [];
+  let inSuggestion = false;
+  let pendingBlock: string[] = [];
+  for (const line of lines) {
+    if (!inSuggestion && SUGGESTION_OPEN_RE.test(line.trim())) {
+      inSuggestion = true;
+      pendingBlock = [line];
+    } else if (inSuggestion && line.trimEnd() === "```") {
+      inSuggestion = false;
+      pendingBlock = [];
+    } else if (inSuggestion) {
+      pendingBlock.push(line);
+    } else {
+      result.push(line);
+    }
+  }
+  if (inSuggestion) {
+    // Unclosed block — preserve all lines as-is
+    result.push(...pendingBlock);
+  }
+  return result.join("\n");
+}
+
+function anchorLineCount(f: Finding): number {
+  return f.startLine === undefined ? 1 : Math.max(1, f.line - f.startLine + 1);
+}
+
+/**
+ * Identify tier-1 findings whose largest suggestion block exceeds the anchor range.
+ * Returns a Set of findings that need their suggestion blocks stripped.
+ */
+function findingsExceedingAnchor(findings: ClassifiedFinding[]): Set<ClassifiedFinding> {
+  const exceeded = new Set<ClassifiedFinding>();
+  for (const f of findings) {
+    if (f.tier !== 1) continue;
+    const suggLines = maxSuggestionLines(f.body);
+    if (suggLines === 0) continue;
+    const anchorLines = anchorLineCount(f);
+    if (suggLines > anchorLines) {
+      exceeded.add(f);
+    }
+  }
+  return exceeded;
+}
+
+/**
+ * Format warning messages for findings whose suggestion blocks exceed their anchor range.
+ * @internal
+ */
+export function formatSuggestionWarnings(oversized: Set<ClassifiedFinding>): string[] {
+  const warnings: string[] = [];
+  for (const f of oversized) {
+    const suggLines = maxSuggestionLines(f.body);
+    const anchorLines = anchorLineCount(f);
+    const anchor =
+      f.startLine === undefined ? `${f.path}:${f.line}` : `${f.path}:${f.startLine}-${f.line}`;
+    warnings.push(
+      `WARN: ${anchor} has ${anchorLines}-line anchor but ${suggLines}-line suggestion — anchor should be widened to cover all lines being replaced`,
+    );
+  }
+  return warnings;
+}
+
+/**
+ * Validate that suggestion blocks fit within their anchor ranges.
+ * @internal
+ */
+export function validateSuggestionAnchors(findings: ClassifiedFinding[]): string[] {
+  return formatSuggestionWarnings(findingsExceedingAnchor(findings));
+}