feat(mcp): codegraph_review_context — structured PR-review context from a diff

[andreinknv]

🔄 Rebased onto post-refactor patterns (review-context MCP tool)
This PR has been rebased to use the per-thing file layout established by refactor PRs #116/#117/#118/#119. Behavior shipped is identical to the original; only the internal code shape changed.

What this PR now ships:

• src/mcp/tools/review-context.ts — REVIEW_CONTEXT_TOOL: ToolModule
• src/review/index.ts + src/review/diff-parser.ts — pure diff→context builder
• src/mcp/tools/registry.ts — 2 lines
• src/mcp/tools/types.ts — 1 HandlerKey entry
• src/mcp/tools.ts — handleReviewContext method on ToolHandler + JSON-cap serializer
• src/index.ts — buildReviewContext public method
• __tests__/review-context.test.ts

What you'll see in the diff: until #116-#119 land, the diff against main includes the refactor commits as part of the branch history. After they merge, GitHub auto-shrinks this PR's diff to just the files above. Full context: #120.

---

Summary

Adds a new MCP tool codegraph_review_context that takes a unified diff and returns structured review context for an LLM-driven PR reviewer. Codegraph becomes a substrate for Greptile/CodeRabbit-style products without itself doing the synthesis — the LLM consumer (Claude Code, ultrareview, etc.) writes the review comments, decides severity, and posts to GitHub.

What it returns (JSON)

Per changed file:

• Status (added / modified / deleted / renamed)
• Hunks (line ranges)
• Affected symbols (line-range overlap with hunks)
• Tests covering the file (via PR feat(graph): convention-based tests-as-edges (test file → subject file) #106's tests edges; graceful no-op if those edges aren't present)

Per affected symbol:

• Signature, docstring
• Top-N callers (PR perf(db): batch node lookups, fix insertNode cache, auto-ANALYZE after writes #108's batch lookups make this fast)
• Top-N callees
• Impact-radius node count

For deleted files:

• brokenIncomingRefs — every distinct caller of a vanishing symbol (deduped by source name + file + line)

Co-change warnings (the genuinely novel signal):

• For each changed file, surface up to N historical co-changers that were NOT touched in this PR
• Catches "you changed schema.sql but didn't update migrations.ts" coupling violations that no static analyzer can see
• Graceful degrade if PR feat(cochange): file-level co-change graph mined from git history #105's co_changes table isn't present

Components

• src/review/diff-parser.ts — pure unified-diff parser. Handles modified, added (/dev/null in ---), deleted (/dev/null in +++), renamed (rename from/to), multi-hunk, single-line hunks, C-style-quoted paths with spaces, and hunk-less rename / mode-change files mid-diff.

• src/review/index.ts — buildReviewContext(diff, queries, traverser, options). Iterates files, maps hunks to symbols, attaches per-symbol context, surfaces co-change warnings.

• CodeGraph.buildReviewContext(diff, options) — public API method.

• MCP tool in src/mcp/tools.ts — JSON output runs through serializeReviewContextWithinCap which progressively trims (docstrings → signatures → caller/callee caps → drop callers/callees → drop oldest files → summary-only) so the result stays valid JSON even when it would exceed MAX_OUTPUT_LENGTH. (Naive mid-string truncation would corrupt JSON parsing.)

Files changed

File	Change
src/review/diff-parser.ts (NEW)	Pure unified-diff parser
src/review/index.ts (NEW)	buildReviewContext + co-change warnings
src/index.ts	Add CodeGraph.buildReviewContext public API
src/mcp/tools.ts	New tool + handler + JSON-safe truncation
__tests__/review-context.test.ts (NEW)	25 regression tests

Example flow

# Get the diff for a PR you want to review
gh pr diff 42 > /tmp/pr-42.diff

# Then the LLM (via MCP) calls:
codegraph_review_context({ diff: <diff text> })
# → returns structured JSON; LLM writes review comments,
#   posts via gh pr comment / gh api

Test plan

• npm test: 405/405 pass on macOS
• npx tsc --noEmit clean
• Independent reviewer pass before pushing — addressed four findings:
  • Mid-diff hunk-less rename / mode-change was silently dropped (request_changes → fixed; flushHunkless on every header transition, flags reset after consumption to prevent phantom emits)
  • truncateOutput sliced JSON mid-string producing invalid JSON (request_changes → tier-and-trim helper, regression test asserts output stays parseable even with 200-symbol over-cap context)
  • brokenIncomingRefs could double-list the same caller with multiple edge types (info → dedup by name|filePath|line)
  • C-style-quoted paths in diff --git "a/x" "b/y" headers were not stripped (info → regex now matches both shapes; unquote helper handles the value)

Forward-compat with sibling PRs

This PR works on a clean upstream/main install today. When PRs #105 (co-change graph) and #106 (tests-as-edges) land, the output gets richer automatically — no further code changes required.

🤖 Generated with Claude Code

[andreinknv]

Heads-up: this branch has been force-pushed. This PR's contents have been rebased to use the per-thing file layout established by refactor PRs #116-#119. Functionality is identical to the original; the internal file shape now matches the post-refactor architecture so this PR can be merged after the refactors with zero conflicts.

The current diff against main looks larger than the feature alone because it transitively includes the 4 refactor commits + any prerequisite PRs. That diff auto-shrinks as the prerequisites merge in the order documented in #120. See #120 (comment) for the full rebase summary.