@mechanai/deepreview 2.2.1 → 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/.opencode/commands/deepreview-loop.md

@@ -18,13 +18,16 @@ Set ITERATION=1
 Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
 
+Determine REPO_ROOT — the main repository root (not a worktree root). Run:
+`REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
+
 If CONTEXT_FILE exists, read its contents and set PRIOR_CONTEXT to:
 "## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n"
 
 STEP 2: RUN INITIAL DEEPREVIEW (full pipeline with cross-validation)
 Run the full deepreview pipeline (Stages 1-5 from the deepreview command):
 
-- Determine SESSION_DIR and write input.txt
+- Determine SESSION_DIR=`$REPO_ROOT/.ai/deepreview/loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)` and write input.txt
 - Append SESSION_DIR to ALL_SESSION_DIRS
 - Stage 1: 5 parallel reviewers — prepend PRIOR_CONTEXT (if non-empty) to each reviewer's prompt as "${PRIOR_CONTEXT}You are reviewing ... Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-{perspective}.md."
 - Stage 2: 5 parallel validators (cross-validation)
@@ -68,7 +71,7 @@ If ITERATION > 5:
 - If user says stop → STOP.
 - If user says continue → reset limit to ITERATION + 5 and proceed.
 
-Create new session directory: SESSION_DIR=".ai/deepreview/loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
+Create new session directory: SESSION_DIR="$REPO_ROOT/.ai/deepreview/loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
 Run `mkdir -p $SESSION_DIR`
 Append SESSION_DIR to ALL_SESSION_DIRS
 

package/.opencode/commands/deepreview-pr-review.md

@@ -7,7 +7,10 @@ You are an orchestrator for a multi-agent code review pipeline that posts findin
 STEP 1: VALIDATE INPUT
 $ARGUMENTS must be a PR number (integer). If it is not a number, tell the user "Usage: /deepreview-pr-review <PR_NUMBER>" and STOP.
 
-Set SESSION_DIR=".ai/deepreview/$ARGUMENTS-review-$(date +%Y-%m-%d-%H%M%S)"
+Determine REPO_ROOT — the main repository root (not a worktree root). Run:
+`REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
+
+Set SESSION_DIR="$REPO_ROOT/.ai/deepreview/$ARGUMENTS-review-$(date +%Y-%m-%d-%H%M%S)"
 Create the directory with `mkdir -p $SESSION_DIR`
 Set INPUT_DESCRIPTION="a PR diff (code changes)"
 

package/.opencode/commands/deepreview-spec-loop.md

@@ -13,12 +13,14 @@ STEP 1: DETERMINE INPUT
 - Set ITERATION=1
 - Set PRIOR_CONTEXT="" (empty — built up across iterations; holds both design context and prior findings)
 - Set ALL_SESSION_DIRS=[] (list of all session directories used, in order)
+- Determine REPO_ROOT — the main repository root (not a worktree root). Run:
+  `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
 - If CONTEXT_FILE exists, set PRIOR_CONTEXT="## Design Decisions (intentional — do not flag)\nThe following are deliberate design choices. Do NOT flag these as issues or suggest alternatives.\n`\n" + contents of CONTEXT_FILE + "\n`\n\n"
 
 STEP 2: RUN INITIAL DEEPREVIEW-SPEC (full pipeline with cross-validation)
 Run the full deepreview-spec pipeline (Stages 1-5 from the deepreview-spec command):
 
-- Determine SESSION_DIR=".ai/deepreview/spec-loop-iter1-$(date +%Y-%m-%d-%H%M%S)" and write input.txt
+- Determine SESSION_DIR="$REPO_ROOT/.ai/deepreview/spec-loop-iter1-$(date +%Y-%m-%d-%H%M%S)" and write input.txt
 - Append SESSION_DIR to ALL_SESSION_DIRS
 - Stage 1: 5 parallel reviewers (completeness, consistency, feasibility, docs, architecture) — prepend PRIOR_CONTEXT (if non-empty) to each reviewer's prompt as "${PRIOR_CONTEXT}You are reviewing ... Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-{perspective}.md."
 - Stage 2: 5 parallel validators (cross-validation)
@@ -57,7 +59,7 @@ If ITERATION > 7:
 - Show the latest stats.
 - STOP.
 
-Create new session directory: SESSION_DIR=".ai/deepreview/spec-loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
+Create new session directory: SESSION_DIR="$REPO_ROOT/.ai/deepreview/spec-loop-iter$ITERATION-$(date +%Y-%m-%d-%H%M%S)"
 Run `mkdir -p $SESSION_DIR`
 Append SESSION_DIR to ALL_SESSION_DIRS
 

package/.opencode/commands/deepreview-spec.md

@@ -8,7 +8,9 @@ STEP 1: DETERMINE SESSION DIRECTORY
 
 - If "$ARGUMENTS" starts with `--context <path>`, extract CONTEXT_FILE=<path> and remove it from $ARGUMENTS before parsing the rest.
 - Validate CONTEXT_FILE: it must be a relative path (no leading `/`), must not contain `..`, must exist on disk, and must be a regular file (not a directory or symlink to outside the project), and must be under 50KB. If validation fails, tell the user the error and STOP.
-- Set SESSION_DIR=".ai/deepreview/spec-$(date +%Y-%m-%d-%H%M%S)"
+- Determine REPO_ROOT — the main repository root (not a worktree root). Run:
+  `REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
+- Set SESSION_DIR="$REPO_ROOT/.ai/deepreview/spec-$(date +%Y-%m-%d-%H%M%S)"
 - Create the directory with `mkdir -p $SESSION_DIR`
 
 STEP 2: PREPARE INPUT

package/.opencode/commands/deepreview.md

@@ -14,11 +14,14 @@ Classify "$ARGUMENTS":
 - If it is multiple space-separated file paths → MODE=files
 - If it is empty → MODE=branch
 
+Determine REPO_ROOT — the main repository root (not a worktree root). Run:
+`REPO_ROOT=$(realpath "$(git rev-parse --git-common-dir)" | sed 's|/\.git$||')`
+
 Set SESSION_DIR based on mode:
 
-- MODE=pr: SESSION_DIR=".ai/deepreview/$ARGUMENTS-$(date +%Y-%m-%d)"
-- MODE=files: SESSION_DIR=".ai/deepreview/files-$(date +%Y-%m-%d-%H%M%S)"
-- MODE=branch: SESSION_DIR=".ai/deepreview/$(git branch --show-current)-$(date +%Y-%m-%d)"
+- MODE=pr: SESSION_DIR="$REPO_ROOT/.ai/deepreview/$ARGUMENTS-$(date +%Y-%m-%d)"
+- MODE=files: SESSION_DIR="$REPO_ROOT/.ai/deepreview/files-$(date +%Y-%m-%d-%H%M%S)"
+- MODE=branch: SESSION_DIR="$REPO_ROOT/.ai/deepreview/$(git branch --show-current)-$(date +%Y-%m-%d)"
 
 Create the directory with `mkdir -p $SESSION_DIR`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "2.2.1",
+  "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));
+}