@mechanai/deepreview 1.0.1 → 2.0.1

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

@@ -0,0 +1,66 @@
+---
+description: "Formats review synthesis into individual thread findings for GitHub PR review posting. Part of the deepreview pipeline."
+mode: subagent
+temperature: 0.1
+permission:
+  edit: allow
+  bash: deny
+---
+
+You are a formatter that converts a code review synthesis into individual, postable comment threads for a GitHub PR review.
+
+## Input
+
+You will receive:
+
+1. A path to `synthesis.md` — the unified review synthesis
+2. A path to `input.txt` — the PR diff
+3. The PR head commit SHA — provided inline in the prompt text
+
+Read both files.
+
+## Process
+
+1. Read the synthesis and identify every individual finding (each bullet or paragraph that describes a distinct issue)
+2. For each finding, determine:
+   - `path`: the file path (relative to repo root) the finding refers to
+   - `line`: the specific line number (new-side of diff). If the synthesis gives a range, use the end line.
+   - `startLine`: if the finding spans multiple lines, use the start of the range. Omit if single-line.
+3. Read `input.txt` (the diff) to:
+   - Verify line references are correct
+   - Generate ` ```suggestion ` blocks where a concrete fix is obvious and fits within the diff
+4. Write each finding as a document in the output file
+
+## Output format
+
+Write to the output path provided. Use this exact format — one document per finding, separated by `---`:
+
+```
+---
+path: <file path>
+startLine: <start line, omit if single-line>
+line: <line number>
+---
+<markdown body of the comment>
+```
+
+## Content rules
+
+- One finding per document. Never bundle multiple issues.
+- No stats, severity counts, or framing ("3 critical issues found")
+- No references to local file paths, session directories, AI tooling, or the deepreview pipeline
+- Use permalinks for code references: `https://github.com/OWNER/REPO/blob/$PR_HEAD_SHA/<path>#L<line>`
+  - Get OWNER/REPO from the diff header or from `input.txt` context
+- Use ` ```suggestion ` blocks where a concrete fix is obvious
+- American English. Succinct. No filler.
+- Do NOT classify findings into tiers — the posting pipeline handles placement
+
+## Line number rules
+
+- All line numbers refer to the NEW (right) side of the diff
+- 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
+
+## 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-pipeline.md

@@ -0,0 +1,57 @@
+---
+internal: true
+description: "Shared pipeline stages for deepreview commands (review → validate → synthesize)"
+---
+
+# Shared Pipeline: Review → Validate → Synthesize
+
+This template defines 3 stages used by deepreview orchestrator commands. The orchestrator must set SESSION_DIR and INPUT_DESCRIPTION before invoking these stages.
+
+## STAGE 1: INITIAL REVIEW (one task per review perspective)
+
+Dispatch ALL of these Task tool calls simultaneously in a single message:
+
+Task — Use the Task tool with subagent_type="deepreview-correctness":
+"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-correctness.md."
+
+Task — Use the Task tool with subagent_type="deepreview-security":
+"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-security.md."
+
+Task — Use the Task tool with subagent_type="deepreview-architecture":
+"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-architecture.md."
+
+Task — Use the Task tool with subagent_type="deepreview-docs":
+"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-docs.md."
+
+Task — Use the Task tool with subagent_type="deepreview-compatibility":
+"You are reviewing $INPUT_DESCRIPTION. Read the content at $SESSION_DIR/input.txt. Write your review to $SESSION_DIR/review-compatibility.md."
+
+Wait for all 5 to return. Record which succeeded and which failed.
+
+## STAGE 2: CROSS-VALIDATION (5 parallel tasks)
+
+Only proceed with reviews that exist. For each validator below, replace $REVIEW_FILE_LIST with ONLY the review files that were successfully created in Stage 1. If a review file failed, omit it from the list entirely. Dispatch validators simultaneously:
+
+Task — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: correctness. Read all available review files at: $REVIEW_FILE_LIST. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-correctness.md."
+
+Task — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: security. Read all available review files at: $REVIEW_FILE_LIST. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-security.md."
+
+Task — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: architecture. Read all available review files at: $REVIEW_FILE_LIST. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-architecture.md."
+
+Task — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: docs. Read all available review files at: $REVIEW_FILE_LIST. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-docs.md."
+
+Task — Use the Task tool with subagent_type="deepreview-validator":
+"Your perspective: compatibility. Read all available review files at: $REVIEW_FILE_LIST. Also read the original input at $SESSION_DIR/input.txt for context. Write your validated review to $SESSION_DIR/validated-compatibility.md."
+
+Wait for all 5 to return.
+
+## STAGE 3: SYNTHESIS (1 task)
+
+Task — Use the Task tool with subagent_type="deepreview-synthesizer":
+"Read the validated reviews at: $SESSION_DIR/validated-correctness.md, $SESSION_DIR/validated-security.md, $SESSION_DIR/validated-architecture.md, $SESSION_DIR/validated-docs.md, $SESSION_DIR/validated-compatibility.md (skip any that don't exist). Write the synthesis to $SESSION_DIR/synthesis.md."
+
+Record the stats line from its return.

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

@@ -0,0 +1,61 @@
+---
+description: "Multi-agent parallel code review posted as a pending GitHub PR review"
+---
+
+You are an orchestrator for a multi-agent code review pipeline that posts findings as a pending GitHub PR review. Follow these steps EXACTLY. Do NOT deviate, skip steps, or read any files in the session directory yourself.
+
+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)"
+Create the directory with `mkdir -p $SESSION_DIR`
+Set INPUT_DESCRIPTION="a PR diff (code changes)"
+
+STEP 2: PREPARE INPUT
+Run `gh pr diff $ARGUMENTS > $SESSION_DIR/input.txt`
+Check if input.txt is empty (0 bytes). If empty, tell the user "Nothing to review — PR has no diff." and STOP.
+
+Get and store the PR head SHA:
+Run `gh pr view $ARGUMENTS --json headRefOid --jq .headRefOid` and save the output as PR_HEAD_SHA.
+
+## Stage 1-3: Shared Pipeline
+
+Follow the shared pipeline at `commands/_deepreview-pipeline.md` with:
+
+- INPUT: `$SESSION_DIR/input.txt`
+- OUTPUT: `$SESSION_DIR/synthesis.md`
+
+If stats show 0 critical, 0 warnings, 0 suggestions, tell the user "No findings to post. PR looks good!" and STOP.
+
+STEP 3: FORMAT THREADS (1 task)
+
+Get the repo owner/name:
+Run `gh repo view --json owner,name --jq '.owner.login + "/" + .name'` and save as OWNER_REPO.
+
+Task — Use the Task tool with subagent_type="deepreview-review-formatter":
+"Read the synthesis at $SESSION_DIR/synthesis.md and the diff at $SESSION_DIR/input.txt. The PR is $OWNER_REPO#$ARGUMENTS, head SHA is $PR_HEAD_SHA. Write the formatted threads to $SESSION_DIR/threads.md."
+
+Wait for it to return.
+
+STEP 4: POST REVIEW
+Use the `deepreview-post-review` tool:
+
+- `threads_path`: The absolute path to `$SESSION_DIR/threads.md`
+- `pr_number`: $ARGUMENTS (the PR number)
+
+STEP 5: PRESENT RESULTS
+Show the user:
+
+- Session directory: $SESSION_DIR/
+- Which reviewers completed (and any that failed)
+- Stats from synthesis (the stats line from Stage 3)
+- Output from the posting script (how many threads posted, any demotions)
+- Remind: "The review is PENDING. Submit it via the GitHub UI when ready."
+
+IMPORTANT RULES:
+
+- Do NOT read any files in $SESSION_DIR yourself. Ever.
+- Use ONLY the file paths and stats/summary lines returned by subagents.
+- If a subagent fails, note which one failed and continue with what you have.
+- If all 5 reviewers fail in Stage 1, tell the user and STOP.
+- Do NOT submit the review. It stays pending.

package/.opencode/plugins/deepreview.ts

@@ -0,0 +1,45 @@
+import { type Plugin, type PluginInput, tool } from "@opencode-ai/plugin";
+import { postReview } from "@mechanai/deepreview/api";
+
+// oxlint-disable-next-line require-await -- Why: Plugin type signature requires async but this plugin has no async initialization
+export const server: Plugin = async (_input: PluginInput) => {
+  return {
+    tool: {
+      "deepreview-post-review": tool({
+        description:
+          "Post a GitHub PR review from a threads.md file. " +
+          "Parses findings, classifies them into line-level/file-level/review-body " +
+          "tiers based on the PR diff, and submits via GitHub GraphQL API. " +
+          "Returns a summary of what was posted.",
+        args: {
+          threads_path: tool.schema
+            .string()
+            .describe("Relative path to the threads.md file (from workspace root)"),
+          pr_number: tool.schema.number().int().positive().describe("Pull request number"),
+          dry_run: tool.schema
+            .boolean()
+            .optional()
+            .describe("Print what would be posted without submitting"),
+          skip_ids: tool.schema
+            .array(tool.schema.string())
+            .optional()
+            .describe("Finding IDs to skip (for retrying partial failures)"),
+        },
+        async execute(args, context) {
+          try {
+            const result = await postReview({
+              threadsPath: args.threads_path,
+              prNumber: args.pr_number,
+              dryRun: args.dry_run ?? false,
+              skipIds: args.skip_ids,
+              cwd: context.directory,
+            });
+            return result.summary;
+          } catch (err) {
+            throw err instanceof Error ? err : new Error(String(err));
+          }
+        },
+      }),
+    },
+  };
+};

package/README.md

@@ -4,132 +4,80 @@ Multi-agent parallel code/spec review for [OpenCode](https://opencode.ai). Spawn
 review agents, cross-validates findings, synthesizes results, and produces an actionable
 implementation plan.
 
-## How it works
-
-### Code review (`/deepreview`)
-
-```
-Stage 1: 5 parallel reviewers (correctness, security, architecture, docs, compatibility)
-Stage 2: 5 parallel cross-validators (try to disprove each finding)
-Stage 3: Synthesizer (deduplicate, rank, produce unified report)
-Stage 4: Planner (write exact code fixes)
-Stage 5: Applier (apply fixes — user-gated)
-```
-
-### Spec/plan review (`/deepreview-spec`)
-
-```
-Stage 1: 5 parallel reviewers (completeness, consistency, feasibility, docs, architecture)
-Stage 2: 5 parallel cross-validators (try to disprove each finding)
-Stage 3: Synthesizer (deduplicate, rank, produce unified report)
-Stage 4: Planner (write spec/plan fixes, not code fixes)
-Stage 5: Applier (apply fixes — user-gated)
-```
-
-All communication between stages happens via files on disk. The orchestrator never reads
-review content into its own context, keeping token usage minimal.
-
 ## Install
 
-```bash
-npx @mechanai/deepreview install
-```
-
-This copies agent and command files into `~/.config/opencode/` and adds `.ai/deepreview/`
-to the local `.gitignore` (where review output is written). Run it again after updating
-the package to sync changes.
+Add to your `opencode.json` (project-level or global):
 
-To add the gitignore entry to your global gitignore instead:
-
-```bash
-npx @mechanai/deepreview install --gitignore-global
+```jsonc
+{
+  "plugin": ["@mechanai/deepreview"],
+}
 ```
 
-To remove:
+OpenCode installs the package automatically at startup.
+
+## Usage
 
-```bash
-npx @mechanai/deepreview uninstall
 ```
+/deepreview                   # Review current branch vs main
+/deepreview 123               # Review PR #123
+/deepreview file1.ts file2.ts # Review specific files
 
-## Usage
+/deepreview-loop              # Review + fix loop (repeats until clean or 5 iterations)
+/deepreview-loop 123          # Same, targeting a PR
 
-In any OpenCode session inside a git repo:
+/deepreview-pr-review 123     # Review PR and post findings as a pending GitHub review
 
+/deepreview-spec spec.md      # Spec-focused review (completeness, consistency, feasibility)
+/deepreview-spec-loop spec.md # Spec review + fix loop
 ```
-/deepreview                        # Review current branch vs main
-/deepreview 123                    # Review PR #123
-/deepreview path/to/spec.md        # Review a spec or plan
-/deepreview doc1.md doc2.md        # Review multiple files
 
-/deepreview-loop                   # Review + fix loop until clean
-/deepreview-loop 123               # Same, targeting a PR
-/deepreview-loop spec.md           # Same, targeting files
+All commands accept a branch diff, PR number, or file path(s). The `-loop` variants
+apply fixes automatically and re-review until no findings remain. Pauses on plateaus
+(same finding persists across iterations).
 
-/deepreview-spec spec.md           # Spec-focused review (completeness, consistency, feasibility)
-/deepreview-spec a.md b.md         # Review multiple spec/plan files
+## Pipeline
 
-/deepreview-spec-loop spec.md      # Review + fix loop for specs until clean
-/deepreview-spec-loop a.md b.md    # Same, targeting multiple files
+```mermaid
+graph LR
+    A[5 Reviewers] --> B[5 Validators]
+    B --> C[Synthesizer]
+    C --> D[Planner]
+    D --> E[Applier]
 ```
 
-`/deepreview-loop` runs the full code review, applies all fixes automatically, then
-re-reviews. It repeats until no findings remain or hits the iteration limit (5,
-extendable). Pauses on decision deadlocks (same finding persists across iterations).
+Stages communicate via files on disk — the orchestrator never reads review content into
+its own context, keeping token usage minimal.
 
-`/deepreview-spec-loop` does the same for spec/plan files, applying spec fixes (not code
-fixes) each iteration. Includes plateau detection to stop when findings oscillate rather
-than converge.
+### Review agents
 
-The pipeline runs automatically. At the end, you'll see a summary and be asked whether
-to apply the fixes.
+| Agent                       | Code review                            | Spec review                                  |
+| --------------------------- | -------------------------------------- | -------------------------------------------- |
+| correctness / completeness  | Logic bugs, edge cases, error handling | Gaps, missing edge cases, undefined behavior |
+| security / consistency      | Vulnerabilities, performance           | Contradictions, name mismatches, type drift  |
+| architecture                | Patterns, coupling, complexity         | Patterns, coupling, complexity               |
+| docs                        | Comment quality, stale claims          | Comment quality, stale claims                |
+| compatibility / feasibility | Breaking changes, API contracts        | Implicit dependencies, can it be built       |
 
 ## Requirements
 
 - [OpenCode](https://opencode.ai)
-- `git` (for diffs)
-- `gh` CLI (only if reviewing PRs by number)
+- `git`
+- `gh` CLI (only for PR commands)
 
-## Review agents
+> [!NOTE]
+> If upgrading from the old `npx @anthropic/deepreview install` workflow, remove
+> `~/.config/opencode/agents/deepreview*` files — they are no longer used.
 
-### Code review
+## Development
 
-| Agent         | Focus                                                 |
-| ------------- | ----------------------------------------------------- |
-| correctness   | Logic bugs, edge cases, error handling, missing tests |
-| security      | Vulnerabilities, auth issues, performance bottlenecks |
-| architecture  | Patterns, coupling, abstractions, complexity          |
-| docs          | Comment quality, stale claims, duplicate content      |
-| compatibility | Breaking changes, API contract violations             |
+This project uses [Bun](https://bun.sh/) as its runtime and package manager.
 
-### Spec/plan review
-
-| Agent             | Focus                                              |
-| ----------------- | -------------------------------------------------- |
-| spec-completeness | Gaps, missing edge cases, undefined behavior       |
-| spec-consistency  | Contradictions, name mismatches, type drift        |
-| spec-feasibility  | Can it be built, implicit dependencies, complexity |
-| docs              | Comment quality, stale claims, duplicate content   |
-| architecture      | Patterns, coupling, abstractions, complexity       |
-
-## Output
-
-All review artifacts are saved to `.ai/deepreview/<branch-or-PR>-<date>/`:
-
-```
-.ai/deepreview/feature-xyz-2025-05-10/
-├── diff.txt
-├── review-correctness.md
-├── review-security.md
-├── review-architecture.md
-├── review-docs.md
-├── review-compatibility.md
-├── validated-correctness.md
-├── validated-security.md
-├── validated-architecture.md
-├── validated-docs.md
-├── validated-compatibility.md
-├── synthesis.md
-└── implementation-plan.md
+```bash
+bun install
+mise run test
+mise run lint
+mise run fmt
 ```
 
 ## License

package/package.json

@@ -1,24 +1,47 @@
 {
   "name": "@mechanai/deepreview",
-  "version": "1.0.1",
+  "version": "2.0.1",
   "description": "Multi-agent parallel code/spec review for OpenCode",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/mechanai/deepreview"
   },
-  "bin": "./src/cli.js",
   "files": [
     "src/",
-    "agents/",
-    "commands/"
+    ".opencode/"
   ],
+  "type": "module",
+  "main": "./.opencode/plugins/deepreview.ts",
+  "exports": {
+    ".": "./.opencode/plugins/deepreview.ts",
+    "./api": "./src/post-review.ts"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "gray-matter": "4.0.3",
+    "js-yaml": "4.1.0",
+    "parse-diff": "0.11.1"
+  },
   "devDependencies": {
+    "@opencode-ai/plugin": "1.4.7",
+    "@types/js-yaml": "^4.0.9",
+    "bun-types": "^1.3.14",
     "oxfmt": "0.52.0",
-    "oxlint": "1.67.0"
+    "oxlint": "1.67.0",
+    "oxlint-tsgolint": "^0.23.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
   },
-  "packageManager": "yarn@4.15.0"
+  "engines": {
+    "bun": ">=1.2.0"
+  }
 }

package/src/diff-classifier.test.ts

@@ -0,0 +1,45 @@
+import { describe, it } from "bun:test";
+import assert from "node:assert/strict";
+import { classifyFindings } from "./diff-classifier.ts";
+
+const SAMPLE_DIFF = [
+  "diff --git a/pkg/server/handler.go b/pkg/server/handler.go",
+  "index abc1234..def5678 100644",
+  "--- a/pkg/server/handler.go",
+  "+++ b/pkg/server/handler.go",
+  "@@ -40,6 +40,10 @@ func Handle() {",
+  "     existing()",
+  "+    newLine1()",
+  "+    newLine2()",
+  "+    newLine3()",
+  "+    newLine4()",
+  "     more()",
+  "diff --git a/README.md b/README.md",
+  "index 111..222 100644",
+  "--- a/README.md",
+  "+++ b/README.md",
+  "@@ -1,3 +1,4 @@",
+  " # Title",
+  "+New line",
+  " Rest",
+].join("\n");
+
+describe("classifyFindings", () => {
+  it("tier 1: line within a diff hunk", () => {
+    const findings = [{ path: "pkg/server/handler.go", line: 42, body: "issue" }];
+    const result = classifyFindings(findings, SAMPLE_DIFF);
+    assert.equal(result[0].tier, 1);
+  });
+
+  it("tier 2: file in diff but line not in any hunk", () => {
+    const findings = [{ path: "pkg/server/handler.go", line: 200, body: "issue" }];
+    const result = classifyFindings(findings, SAMPLE_DIFF);
+    assert.equal(result[0].tier, 2);
+  });
+
+  it("tier 3: file not in diff at all", () => {
+    const findings = [{ path: "internal/other.go", line: 10, body: "issue" }];
+    const result = classifyFindings(findings, SAMPLE_DIFF);
+    assert.equal(result[0].tier, 3);
+  });
+});

package/src/diff-classifier.ts

@@ -0,0 +1,63 @@
+import parseDiff from "parse-diff";
+
+export interface Finding {
+  path: string;
+  line: number;
+  startLine?: number;
+  body: string;
+}
+
+export interface ClassifiedFinding extends Finding {
+  tier: 1 | 2 | 3;
+}
+
+interface FileHunks {
+  hunks: { newStart: number; newLines: number }[];
+}
+
+/**
+ * Classify findings into placement tiers based on the PR diff.
+ *
+ * Tier 1: line-level (line within a diff hunk's new-side range)
+ * Tier 2: file-level (file in diff but line not in any hunk)
+ * Tier 3: review body (file not in diff)
+ */
+export function classifyFindings(findings: Finding[], diffText: string): ClassifiedFinding[] {
+  const parsed = parseDiff(diffText);
+  const fileMap = buildFileMap(parsed);
+
+  return findings.map((finding) => {
+    const file = fileMap.get(finding.path);
+    if (!file) {
+      return { ...finding, tier: 3 as const };
+    }
+
+    const lineInHunk = file.hunks.some((hunk) => {
+      return finding.line >= hunk.newStart && finding.line < hunk.newStart + hunk.newLines;
+    });
+
+    if (lineInHunk) {
+      return { ...finding, tier: 1 as const };
+    }
+    return { ...finding, tier: 2 as const };
+  });
+}
+
+/**
+ * Build a map of file path → {hunks: [{newStart, newLines}]}
+ */
+function buildFileMap(parsedDiff: parseDiff.File[]): Map<string, FileHunks> {
+  const map = new Map<string, FileHunks>();
+  for (const file of parsedDiff) {
+    const filePath = file.to === "/dev/null" ? file.from : file.to;
+    if (filePath === undefined || filePath === "") continue;
+
+    const hunks = file.chunks.map((chunk) => ({
+      newStart: chunk.newStart,
+      newLines: chunk.newLines,
+    }));
+
+    map.set(filePath, { hunks });
+  }
+  return map;
+}