Add PR-ready change review reports

README.md

@@ -12,7 +12,7 @@ RepoLens MCP is an original TypeScript implementation built around fast local ve
 
 ## Why It Stands Out
 
-- **MCP-native**: exposes 38 tools for indexing, version/update status, repeatable benchmarking, persistent config, project inventory/status, fleet summaries, cross-repo graphing, multi-agent setup, optional startup auto-indexing and git-aware auto-sync, BM25 code search, redacted secret scanning, symbol search, reference lookup, semantic search, vector search, context packs, source snippets, graph schema with relationship patterns and label properties, structural graph search, graph community detection, read-only Cypher-like graph queries, route-call links, runtime trace ingestion, channel/event edges, typed inheritance/implementation/use edges, receiver-aware method call edges, conservative data-flow edges, import-resolved file graphs, multi-ecosystem package manifests, lockfile resolved-dependency graphs, Docker/Kubernetes infrastructure nodes, dependency-cycle detection, architecture reports, architecture summaries, git-history hotspots, tracing, git-change impact, dead-code candidates, maintainable ADR memory, graph snapshots, and graph package exchange.
+- **MCP-native**: exposes 39 tools for indexing, version/update status, repeatable benchmarking, persistent config, project inventory/status, fleet summaries, cross-repo graphing, multi-agent setup, optional startup auto-indexing and git-aware auto-sync, BM25 code search, redacted secret scanning, symbol search, reference lookup, semantic search, vector search, context packs, source snippets, graph schema with relationship patterns and label properties, structural graph search, graph community detection, read-only Cypher-like graph queries, route-call links, runtime trace ingestion, channel/event edges, typed inheritance/implementation/use edges, receiver-aware method call edges, conservative data-flow edges, import-resolved file graphs, multi-ecosystem package manifests, lockfile resolved-dependency graphs, Docker/Kubernetes infrastructure nodes, dependency-cycle detection, architecture reports, PR-ready change review reports, architecture summaries, git-history hotspots, tracing, git-change impact, dead-code candidates, maintainable ADR memory, graph snapshots, and graph package exchange.
 - **Agent-ready setup**: `doctor` inspects the local Codex MCP configuration, `install-codex` can add a managed MCP block with dry-run and force safeguards, `uninstall-codex` removes only managed RepoLens config, and `agent-setup`/`install-agents` generate reviewable guidance plus opt-in hook/reminder files for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro.
 - **Local-first SQLite memory**: all indexed data stays in `.repolens/memory.db`.
 - **Project catalog and cross-repo graphing**: `list-projects`, `project-status`, `fleet-summary`, `fleet-graph`, and `delete-project` track indexed repositories, aggregate languages/routes/HTTP calls/dependencies, and produce a catalog-wide graph with shared dependencies, route overlaps, and inferred consumer/provider service links.
@@ -116,6 +116,7 @@ repolens-mcp dead-code [--db path]
 repolens-mcp cycles [--db path] [--limit n]
 repolens-mcp ingest-traces traces.json [--db path]
 repolens-mcp changes [repo] [--db path]
+repolens-mcp review-report [repo] [--db path] [--limit n] [--format markdown|json] [--out report.md]
 repolens-mcp report [--db path] [--format markdown|html] [--graph-limit n] [--out report.html]
 repolens-mcp export-graph --out graph.html [--db path]
 repolens-mcp pack-graph --out graph.rlgz [--db path] [--label name]
@@ -168,6 +169,7 @@ repolens-mcp mcp
 | `find_dependency_cycles` | Find import-resolved dependency cycles between architecture clusters. |
 | `ingest_traces` | Add observed runtime HTTP, event, or symbol edges as `OBSERVED_*` relationships. |
 | `detect_changes` | Map uncommitted git changes to indexed graph impact with per-file blast radius, relationship counts, and risk reasons. |
+| `change_review_report` | Generate a PR-ready Markdown or JSON report with change risk, impacted graph items, security notes, and review checklist items. |
 | `architecture_report` | Generate a markdown or HTML architecture report with graph, hotspot, history, risk, and recommendation sections. |
 | `remember_decision` | Persist an ADR-style architecture decision. |
 | `list_decisions` | Retrieve saved decisions. |
@@ -246,6 +248,7 @@ node --experimental-sqlite dist/src/cli.js context-pack "order checkout flow" --
 node --experimental-sqlite dist/src/cli.js cycles --db /tmp/memory.db
 node --experimental-sqlite dist/src/cli.js query-graph "MATCH (f:Function) RETURN f.name,f.filePath LIMIT 5" --db /tmp/memory.db
 node --experimental-sqlite dist/src/cli.js ingest-traces traces.json --db /tmp/memory.db
+node --experimental-sqlite dist/src/cli.js review-report /path/to/big/repo --db /tmp/memory.db --out change-review.md
 node --experimental-sqlite dist/src/cli.js report --db /tmp/memory.db --format html --out report.html
 node --experimental-sqlite dist/src/cli.js export-graph --db /tmp/memory.db --out graph.html --limit 1000
 node --experimental-sqlite dist/src/cli.js pack-graph --db /tmp/memory.db --out graph.rlgz --label validation

docs/agent-guide.md

@@ -37,6 +37,7 @@ On Windows PowerShell, the local installer mirrors the shell installer:
 2. Use `architecture`, `schema`, `communities`, or `fleet-summary` to understand the project shape. `schema` includes relationship patterns and label property hints for safer graph queries.
 3. Use `search`, `symbols`, `references`, `trace`, `cycles`, and `context-pack` for focused code context.
 4. Use `changes` after edits to map uncommitted files back to graph impact, including per-file blast radius, relationship counts, and risk reasons.
+5. Use `review-report --out change-review.md` when you need a PR-ready summary of changed-file risk, impacted graph items, security review notes, and checklist items.
 
 ## Useful MCP Tools
 
@@ -50,6 +51,7 @@ On Windows PowerShell, the local installer mirrors the shell installer:
 - `get_graph_schema`: inspect labels, edge types, relationship patterns, and label properties before writing graph queries.
 - `scan_secrets`: return redacted high-signal secret findings from indexed lines.
 - `architecture_report`: generate Markdown or HTML reports.
+- `change_review_report`: generate PR-ready Markdown or JSON from git change impact and graph context.
 - `export_graph_package` / `import_graph_package`: share or bootstrap local graph snapshots.
 
 ## Big-Repo Validation Pattern
@@ -87,3 +89,4 @@ For behavior changes, include:
 - Documentation updates for CLI, MCP, graph schema, dashboard, or security behavior.
 - Package boundary validation when package contents changed.
 - Report or graph artifact paths when output behavior changed.
+- `review-report` output for changes where graph impact, release risk, or security-sensitive paths need review evidence.

docs/research-notes.md

@@ -25,7 +25,7 @@ RepoLens MCP is not a fork or a drop-in static C replacement. It is an original
 
 - Node 24 plus native SQLite for a dependency-light local graph store.
 - Stable MCP SDK v1 package rather than the pre-alpha v2 branch.
-- Clear CLI commands and MCP tools for Codex setup checks, persistent config, 11-agent setup guidance, graph package bootstrap, optional MCP startup auto-indexing, git-aware MCP auto-sync, indexing, repeatable full/incremental benchmarks, project inventory/status, fleet summaries with inferred service links, cross-repo fleet graphs, graph package exchange, BM25 code search, reference lookup, typed inheritance/implementation/use/data-flow edges, redacted secret scanning, semantic search, local vector search, context packs, source snippets, graph schema with relationship patterns and label properties, graph community detection, structural graph search, read-only Cypher-like graph queries with `DISTINCT`, `count`, `ORDER BY`, and `SKIP`, runtime trace ingestion, import-resolved file graph edges, multi-ecosystem manifest and lockfile extraction, Docker/Kubernetes/Kustomize infrastructure graph extraction, channel/event graph extraction, GraphQL/gRPC/tRPC/OpenAPI protocol extraction, route-call linking, relative and workspace-package import cycle detection, architecture reports, architecture summaries, git-history hotspots, tracing, impact analysis, dead-code candidates, git-change impact, and architecture decisions.
+- Clear CLI commands and MCP tools for Codex setup checks, persistent config, 11-agent setup guidance, graph package bootstrap, optional MCP startup auto-indexing, git-aware MCP auto-sync, indexing, repeatable full/incremental benchmarks, project inventory/status, fleet summaries with inferred service links, cross-repo fleet graphs, graph package exchange, BM25 code search, reference lookup, typed inheritance/implementation/use/data-flow edges, redacted secret scanning, semantic search, local vector search, context packs, source snippets, graph schema with relationship patterns and label properties, graph community detection, structural graph search, read-only Cypher-like graph queries with `DISTINCT`, `count`, `ORDER BY`, and `SKIP`, runtime trace ingestion, import-resolved file graph edges, multi-ecosystem manifest and lockfile extraction, Docker/Kubernetes/Kustomize infrastructure graph extraction, channel/event graph extraction, GraphQL/gRPC/tRPC/OpenAPI protocol extraction, route-call linking, relative and workspace-package import cycle detection, architecture reports, PR-ready change review reports, architecture summaries, git-history hotspots, tracing, impact analysis, dead-code candidates, git-change impact, and architecture decisions.
 - Incremental indexing skips unchanged files, prunes removed files, and avoids call-edge rebuilds when there is no repository delta.
 - Watch mode keeps the graph fresh with polling-based incremental refreshes while preserving deterministic CLI behavior for tests and automation; git-aware auto-sync skips unchanged HEAD/status polls during long-running MCP sessions.
 - Browser dashboard without a bundler so the project is easy to build and inspect.
@@ -44,7 +44,7 @@ RepoLens MCP is not a fork or a drop-in static C replacement. It is an original
 - Built-in ADR memory, not just structural graph search.
 - Dashboard API and HTML are included in the same binary entrypoint, avoiding a separate frontend build while still exposing graph exploration, fleet service links, schema counts, relationship patterns, label property hints, review signals, dead-code samples, and report links.
 - Swift extraction and big-repo validation now cover a mixed mobile/web monorepo, not only TypeScript services.
-- Structural graph search, BM25 source search with code-aware token expansion, reference lookup, typed inheritance/implementation/use edges, conservative data-flow edges, persistent startup config, redacted secret scanning, context packs for agents, multi-agent setup guidance, graph package bootstrap, optional startup auto-indexing, git-aware auto-sync, repeatable benchmark output, import-resolved local file edges, multi-ecosystem package/dependency nodes, resolved lockfile dependency nodes, project inventory/status, fleet summaries with cross-project service links, cross-repo graphing, runtime trace ingestion, Docker/Kubernetes infrastructure nodes, channel/event edges, first-class HTTP call nodes, GraphQL/gRPC/tRPC/OpenAPI protocol nodes, route-call edges, deterministic graph communities, dependency-free semantic search, persisted local vector search, read-only Cypher-like graph queries, graph schema relationship/property summaries, dependency-cycle detection, dead-code candidates, git-history hotspots, git-diff impact mapping with per-file blast radius, watch indexing, and portable graph/package exports are first-class workflows.
+- Structural graph search, BM25 source search with code-aware token expansion, reference lookup, typed inheritance/implementation/use edges, conservative data-flow edges, persistent startup config, redacted secret scanning, context packs for agents, multi-agent setup guidance, graph package bootstrap, optional startup auto-indexing, git-aware auto-sync, repeatable benchmark output, import-resolved local file edges, multi-ecosystem package/dependency nodes, resolved lockfile dependency nodes, project inventory/status, fleet summaries with cross-project service links, cross-repo graphing, runtime trace ingestion, Docker/Kubernetes infrastructure nodes, channel/event edges, first-class HTTP call nodes, GraphQL/gRPC/tRPC/OpenAPI protocol nodes, route-call edges, deterministic graph communities, dependency-free semantic search, persisted local vector search, read-only Cypher-like graph queries, graph schema relationship/property summaries, dependency-cycle detection, dead-code candidates, git-history hotspots, git-diff impact mapping with per-file blast radius, PR-ready change review reports, watch indexing, and portable graph/package exports are first-class workflows.
 - Indexing now writes local `SIMILAR_TO` and `SEMANTICALLY_RELATED` edges plus deterministic symbol vectors without external embeddings or network calls.
 - Architecture reports combine metrics, language mix, schema counts, structural hotspots, git-history churn, boundaries, import-resolved cycle checks, recommendations, dead-code samples, review signals, and a graph preview into one shareable artifact; the live schema API additionally exposes relationship patterns and label property hints for query authors.
 - A repeatable benchmark run on the large validation repo completed a full index in 16,484 ms and a no-op incremental index in 233 ms while preserving a 5,812-symbol, 38,645-edge graph with 153 Next.js route nodes, 653 resolved import edges, 5,957 type-use edges, 976 data-flow edges, and 387 locked dependencies.

llms.txt

@@ -6,6 +6,7 @@ RepoLens MCP is a local-first repository intelligence server for AI coding agent
 
 - You need architecture context before changing a codebase.
 - You need symbol, reference, route, dependency, or impact lookup without manually reading every file.
+- You need a PR-ready change review report from git impact, graph risk, security notes, and checklist items.
 - You want a repeatable full/incremental benchmark for a repository graph.
 - You need a portable `.rlgz` graph package for local sharing or bootstrap.
 - You want redacted secret-scan results, package/dependency graph data, runtime trace edges, or architecture reports.
@@ -29,7 +30,7 @@ Run the MCP server with:
 node --experimental-sqlite dist/src/cli.js mcp
 ```
 
-The server exposes tools for indexing, benchmarking, config management, project cataloging, fleet summaries, cross-repo graphing, code search, secret scanning, symbol/reference lookup, graph schema with relationship patterns and label properties, graph search, semantic/vector search, context packs, read-only graph queries, trace ingestion, impact analysis, architecture reports, ADR memory, and graph package import/export.
+The server exposes tools for indexing, benchmarking, config management, project cataloging, fleet summaries, cross-repo graphing, code search, secret scanning, symbol/reference lookup, graph schema with relationship patterns and label properties, graph search, semantic/vector search, context packs, read-only graph queries, trace ingestion, impact analysis, PR-ready change review reports, architecture reports, ADR memory, and graph package import/export.
 
 ## Local Data Rules
 

scripts/test-skip-gate.mjs

@@ -17,7 +17,7 @@ const allowedSkips = [
     file: "tests/indexer.test.ts",
     reason: "git is not available",
     guard: "git.status !== 0",
-    expectedCount: 3
+    expectedCount: 4
   }
 ];
 

src/cli.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import {
   architectureReport,
   benchmarkRepository,
+  changeReviewReport,
   configGet,
   configList,
   configReset,
@@ -246,6 +247,22 @@ async function main(): Promise<void> {
     case "changes":
       print(detectChanges(args.positional[0] ? path.resolve(args.positional[0]) : undefined, numberFlag(args, "limit"), stringFlag(args, "db")));
       break;
+    case "review-report":
+    case "pr-report": {
+      const out = stringFlag(args, "out");
+      const format = reviewReportFormatFlag(args, out);
+      const report = changeReviewReport(args.positional[0] ? path.resolve(args.positional[0]) : undefined, numberFlag(args, "limit"), stringFlag(args, "db"));
+      const body = format === "json" ? `${jsonBlock(report)}\n` : report.markdown;
+      if (out) {
+        const outPath = path.resolve(out);
+        await fs.mkdir(path.dirname(outPath), { recursive: true });
+        await fs.writeFile(outPath, body);
+        print({ out: outPath, format, risk: report.risk, changedFiles: report.summary.changedFileCount, impactedItems: report.summary.impactedItemCount });
+      } else {
+        process.stdout.write(body);
+      }
+      break;
+    }
     case "decision": {
       const title = required(stringFlag(args, "title") ?? args.positional[0], "title");
       const body = required(stringFlag(args, "body") ?? args.positional.slice(1).join(" "), "body");
@@ -491,6 +508,14 @@ function traceModeFlag(args: ParsedArgs): TraceMode | undefined {
   throw new Error("Invalid --mode. Use one of: all, calls, data_flow, cross_service.");
 }
 
+function reviewReportFormatFlag(args: ParsedArgs, out?: string): "markdown" | "json" {
+  const value = stringFlag(args, "format") ?? (out?.endsWith(".json") ? "json" : "markdown");
+  if (value === "markdown" || value === "json") {
+    return value;
+  }
+  throw new Error("Invalid --format. Use one of: markdown, json.");
+}
+
 function decisionStatusFlag(args: ParsedArgs): "proposed" | "accepted" | "superseded" | undefined {
   const value = stringFlag(args, "status");
   if (!value) {
@@ -651,6 +676,7 @@ Usage:
   repolens-mcp cycles [--db path] [--limit n]
   repolens-mcp ingest-traces traces.json [--db path]
   repolens-mcp changes [repo] [--db path] [--limit n]
+  repolens-mcp review-report [repo] [--db path] [--limit n] [--format markdown|json] [--out report.md]
   repolens-mcp decision --title "ADR title" --body "Decision body" [--tags a,b]
   repolens-mcp decision-update <id> [--title "New title"] [--status proposed|accepted|superseded] [--body "Updated body"] [--tags a,b] [--db path]
   repolens-mcp decision-delete <id> [--db path]

src/core/api.ts

@@ -11,6 +11,7 @@ import { getRepoLensConfigValue, readRepoLensConfig, resetRepoLensConfigValue, s
 import { buildFleetGraph, type FleetGraphOptions } from "./fleet-graph.js";
 import { indexRepository } from "./indexer.js";
 import { buildArchitectureReport } from "./report.js";
+import { buildChangeReviewReport } from "./review.js";
 import { defaultDbPath, MemoryStore } from "./store.js";
 import { getVersionStatus as readVersionStatus, type VersionStatusOptions } from "./version.js";
 import { watchRepository } from "./watcher.js";
@@ -232,6 +233,10 @@ export function detectChanges(root?: string, limit?: number, dbPath?: string) {
   return withStore(dbPath, (store) => store.detectChanges(root, limit));
 }
 
+export function changeReviewReport(root?: string, limit?: number, dbPath?: string) {
+  return buildChangeReviewReport(detectChanges(root, limit, dbPath));
+}
+
 export function rememberDecision(decision: DecisionRecord, dbPath?: string) {
   return withStore(dbPath, (store) => store.addDecision(decision));
 }