diffprism 0.10.0 → 0.10.2

package/README.md

@@ -2,97 +2,127 @@
 
 Local-first code review tool for agent-generated code changes. Opens a browser-based diff viewer from the CLI or Claude Code (via MCP).
 
-DiffPrism gives you a visual review step for AI-written code — stage your changes, run the tool, and a browser window opens with a syntax-highlighted diff viewer. Approve or request changes, and the result is returned as structured JSON.
+DiffPrism gives you a visual review step for AI-written code — stage your changes, run the tool, and a browser window opens with a full-featured diff viewer. Review inline, leave comments, and your decision is returned as structured JSON.
+
+## Features
+
+- **Syntax-highlighted diffs** — unified or split (side-by-side) view with toggle
+- **Inline line-level commenting** — click any line to add comments typed as `must_fix`, `suggestion`, `question`, or `nitpick`
+- **File-level review status** — mark each file as reviewed, approved, or needs changes
+- **Review briefing bar** — summary stats, complexity scoring, test coverage gaps, pattern flags, and dependency tracking
+- **Agent reasoning panel** — see why the AI made each change
+- **Dark/light mode** — toggle with theme persistence
+- **Keyboard shortcuts** — `j`/`k` navigate files, `Space`/`Enter` cycle file status
+- **Three-way decisions** — approve, request changes, or approve with comments
+- **Branch display** — current git branch shown in the review header
 
 ## Quick Start
 
-```bash
-# Clone and install
-git clone <repo-url> && cd diffprism
-pnpm install
+### Use with Claude Code (recommended)
 
-# Review staged changes
-pnpm cli review --staged
+**1. Add the MCP server** — create `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "diffprism": {
+      "command": "npx",
+      "args": ["diffprism", "serve"]
+    }
+  }
+}
 ```
 
-A browser window opens with the diff viewer. Click **Approve** or **Request Changes**, and the result prints to stdout as JSON.
+**2. Auto-approve the tool** (optional) — add to `.claude/settings.json` so Claude can open reviews without prompting:
 
-## Usage
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__diffprism__open_review"
+    ]
+  }
+}
+```
 
-### CLI
+**3. Tell Claude to use it** — add to your project's `CLAUDE.md`:
 
-```bash
-# Review staged changes (default)
-pnpm cli review
-pnpm cli review --staged
+```markdown
+## Code Review
 
-# Review unstaged changes
-pnpm cli review --unstaged
+Before committing changes, use the diffprism MCP tool to open a review:
+- Call `open_review` with the appropriate `diff_ref` (e.g. `"staged"`, `"HEAD~1..HEAD"`)
+- Include a `title` and `description` summarizing the changes
+- Wait for the user's review decision before proceeding
+```
 
-# Review a specific ref range
-pnpm cli review HEAD~3
-pnpm cli review main..feature-branch
+That's it. Claude will now open a browser-based review before committing. You review the diff, leave comments, and the result goes back to Claude as structured JSON.
 
-# Add a title to the review
-pnpm cli review --staged --title "Add auth middleware"
-```
+See the [full setup guide](docs/claude-setup.md) for Claude Desktop config, troubleshooting, and advanced options.
 
-**Output:** A `ReviewResult` JSON object:
+### Use from the CLI
 
-```json
-{
-  "decision": "approved",
-  "comments": [],
-  "summary": ""
-}
-```
+```bash
+# Install globally (or use npx)
+npm install -g diffprism
 
-Decisions are one of: `approved`, `changes_requested`, or `approved_with_comments`.
+# Review all changes (staged + unstaged, default)
+diffprism review
 
-### Claude Code (MCP)
+# Review staged changes only
+diffprism review --staged
 
-DiffPrism ships an MCP server so Claude Code can open reviews during a coding session.
+# Review unstaged changes only
+diffprism review --unstaged
 
-**Setup:** Add to your Claude Code MCP config (`.mcp.json` or project settings). See the [full setup guide](docs/claude-setup.md) for detailed instructions covering Claude Code, Claude Desktop, auto-approval, and troubleshooting.
+# Review a specific ref range
+diffprism review HEAD~3
+diffprism review main..feature-branch
 
-```json
-{
-  "mcpServers": {
-    "diffprism": {
-      "command": "npx",
-      "args": ["diffprism", "serve"]
-    }
-  }
-}
+# Add a title to the review
+diffprism review --staged --title "Add auth middleware"
 ```
 
-**Tool:** `open_review`
+A browser window opens with the diff viewer. Review the changes and click **Approve**, **Request Changes**, or **Approve with Comments**.
 
-| Parameter     | Required | Description                          |
-|---------------|----------|--------------------------------------|
-| `diff_ref`    | yes      | Git diff reference: `"staged"`, `"unstaged"`, or a ref range |
-| `title`       | no       | Title shown in the review UI         |
-| `description` | no       | Description of the changes           |
-| `reasoning`   | no       | Agent reasoning about why changes were made |
+## MCP Tool Reference
 
-The tool opens a browser, blocks until you submit a review, and returns the `ReviewResult` to Claude Code.
+The MCP server exposes one tool: **`open_review`**
 
-**Auto-approve the tool:** By default Claude Code prompts for confirmation each time. To skip that, add `mcp__diffprism__open_review` to the `permissions.allow` array in your project's `.claude/settings.json` or your user-level `~/.claude/settings.json`:
+| Parameter     | Required | Description                                                       |
+|---------------|----------|-------------------------------------------------------------------|
+| `diff_ref`    | Yes      | `"staged"`, `"unstaged"`, or a git ref range (e.g. `"HEAD~3..HEAD"`, `"main..feature"`) |
+| `title`       | No       | Title displayed in the review UI                                  |
+| `description` | No       | Description of the changes                                        |
+| `reasoning`   | No       | Agent reasoning about why the changes were made (shown in the reasoning panel) |
+
+**Returns:** A `ReviewResult` JSON object:
 
 ```json
 {
-  "permissions": {
-    "allow": [
-      "mcp__diffprism__open_review"
-    ]
-  }
+  "decision": "approved",
+  "comments": [
+    {
+      "file": "src/index.ts",
+      "line": 42,
+      "body": "Consider adding a null check here",
+      "type": "suggestion"
+    }
+  ],
+  "summary": "Looks good, one minor suggestion."
 }
 ```
 
+| Field | Description |
+|-------|-------------|
+| `decision` | `approved`, `changes_requested`, or `approved_with_comments` |
+| `comments` | Array of inline comments with file, line, body, and type (`must_fix`, `suggestion`, `question`, `nitpick`) |
+| `summary` | Optional reviewer summary |
+
 ## How It Works
 
 1. **Extract** — runs `git diff` and parses the output into a structured `DiffSet`
-2. **Analyze** — generates a `ReviewBriefing` with file stats, impact detection, and triage
+2. **Analyze** — generates a `ReviewBriefing`: file stats, complexity scores, test gap detection, pattern flags, dependency changes
 3. **Serve** — starts a Vite dev server (React UI) and WebSocket bridge on random ports
 4. **Review** — opens a browser to the diff viewer, waits for your decision
 5. **Return** — cleans up servers and returns the `ReviewResult`
@@ -100,8 +130,12 @@ The tool opens a browser, blocks until you submit a review, and returns the `Rev
 ## Development
 
 ```bash
-pnpm install                                    # Install all deps
+git clone https://github.com/CodeJonesW/diffprism.git
+cd diffprism
+pnpm install
 pnpm test                                       # Run all tests (Vitest)
+pnpm run build                                  # Build all packages
+pnpm cli review --staged                        # Run CLI from source
 npx tsc --noEmit -p packages/core/tsconfig.json # Type-check a package
 ```
 
@@ -110,15 +144,19 @@ npx tsc --noEmit -p packages/core/tsconfig.json # Type-check a package
 ```
 packages/core       — Shared types, pipeline orchestrator, WebSocket bridge
 packages/git        — Git diff extraction + unified diff parser
-packages/analysis   — Deterministic review briefing generation
-packages/ui         — React 19 + Vite + Tailwind diff viewer
+packages/analysis   — Deterministic review briefing (complexity, test gaps, patterns)
+packages/ui         — React 19 + Vite 6 + Tailwind + Zustand diff viewer
 packages/mcp-server — MCP tool server (open_review)
-packages/github     — Placeholder (future GitHub integration)
 cli/                — Commander CLI entry point
 ```
 
 ### Requirements
 
 - Node.js >= 20
-- pnpm
+- pnpm (for development)
 - Git
+
+## Documentation
+
+- [Claude Code / Claude Desktop Setup Guide](docs/claude-setup.md) — detailed MCP configuration, auto-approval, and troubleshooting
+- [UX Design Notes](docs/ux-design-notes.md) — design decisions, CLI defaults rationale, and multi-agent workflow thinking

package/dist/bin.js

@@ -42,7 +42,7 @@ async function serve() {
 
 // cli/src/index.ts
 var program = new Command();
-program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.10.0" : "0.0.0-dev");
+program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.10.2" : "0.0.0-dev");
 program.command("review [ref]").description("Open a browser-based diff review").option("--staged", "Review staged changes").option("--unstaged", "Review unstaged changes").option("-t, --title <title>", "Review title").option("--dev", "Use Vite dev server with HMR instead of static files").action(review);
 program.command("serve").description("Start the MCP server for Claude Code integration").action(serve);
 program.parse();

package/dist/mcp-server.js

@@ -11,7 +11,7 @@ import { z } from "zod";
 async function startMcpServer() {
   const server = new McpServer({
     name: "diffprism",
-    version: true ? "0.10.0" : "0.0.0-dev"
+    version: true ? "0.10.2" : "0.0.0-dev"
   });
   server.tool(
     "open_review",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffprism",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "type": "module",
   "description": "Local-first code review tool for agent-generated code changes",
   "bin": {