Merge scaling phases 2-12 into main

Completes the Scaling + Token Efficiency initiative (Phases 2-12).
Phase 1 was already merged via PR #115.

Author: tirth8205

CLAUDE.md

@@ -4,6 +4,14 @@
 
 **code-review-graph** is a persistent, incrementally-updated knowledge graph for token-efficient code reviews with Claude Code. It parses codebases using Tree-sitter, builds a structural graph in SQLite, and exposes it via MCP tools and prompts.
 
+## Graph Tool Usage (Token-Efficient)
+When using code-review-graph MCP tools, follow these rules:
+1. First call: `get_minimal_context(task="<description>")` — costs ~100 tokens, gives you the full picture.
+2. All subsequent calls: use `detail_level="minimal"` unless you need more.
+3. Prefer `query_graph` with a specific target over broad `list_*` calls.
+4. The `next_tool_suggestions` field in every response tells you the optimal next step.
+5. Target: ≤5 tool calls per task, ≤800 total tokens of graph context.
+
 ## Architecture
 
 - **Core Package**: `code_review_graph/` (Python 3.10+)

code_review_graph/cli.py

@@ -86,6 +86,7 @@ def _print_banner() -> None:
     {g}register{r}    Register a repository in the multi-repo registry
     {g}unregister{r}  Remove a repository from the registry
     {g}repos{r}       List registered repositories
+    {g}postprocess{r} Run post-processing {d}(flows, communities, FTS){r}
     {g}eval{r}        Run evaluation benchmarks
     {g}serve{r}       Start MCP server
 
@@ -226,11 +227,37 @@ def main() -> None:
     # build
     build_cmd = sub.add_parser("build", help="Full graph build (re-parse all files)")
     build_cmd.add_argument("--repo", default=None, help="Repository root (auto-detected)")
+    build_cmd.add_argument(
+        "--skip-flows", action="store_true",
+        help="Skip flow/community detection (signatures + FTS only)",
+    )
+    build_cmd.add_argument(
+        "--skip-postprocess", action="store_true",
+        help="Skip all post-processing (raw parse only)",
+    )
 
     # update
     update_cmd = sub.add_parser("update", help="Incremental update (only changed files)")
     update_cmd.add_argument("--base", default="HEAD~1", help="Git diff base (default: HEAD~1)")
     update_cmd.add_argument("--repo", default=None, help="Repository root (auto-detected)")
+    update_cmd.add_argument(
+        "--skip-flows", action="store_true",
+        help="Skip flow/community detection (signatures + FTS only)",
+    )
+    update_cmd.add_argument(
+        "--skip-postprocess", action="store_true",
+        help="Skip all post-processing (raw parse only)",
+    )
+
+    # postprocess
+    pp_cmd = sub.add_parser(
+        "postprocess",
+        help="Run post-processing on existing graph (flows, communities, FTS)",
+    )
+    pp_cmd.add_argument("--repo", default=None, help="Repository root (auto-detected)")
+    pp_cmd.add_argument("--no-flows", action="store_true", help="Skip flow detection")
+    pp_cmd.add_argument("--no-communities", action="store_true", help="Skip community detection")
+    pp_cmd.add_argument("--no-fts", action="store_true", help="Skip FTS rebuild")
 
     # watch
     watch_cmd = sub.add_parser("watch", help="Watch for changes and auto-update")
@@ -243,6 +270,12 @@ def main() -> None:
     # visualize
     vis_cmd = sub.add_parser("visualize", help="Generate interactive HTML graph visualization")
     vis_cmd.add_argument("--repo", default=None, help="Repository root (auto-detected)")
+    vis_cmd.add_argument(
+        "--mode",
+        choices=["auto", "full", "community", "file"],
+        default="auto",
+        help="Rendering mode: auto (default), full, community, or file",
+    )
     vis_cmd.add_argument(
         "--serve", action="store_true",
         help="Start a local HTTP server to view the visualization (localhost:8765)",
@@ -402,6 +435,30 @@ def main() -> None:
         watch,
     )
 
+    if args.command == "postprocess":
+        repo_root = Path(args.repo) if args.repo else find_project_root()
+        db_path = get_db_path(repo_root)
+        store = GraphStore(db_path)
+        try:
+            from .tools.build import run_postprocess
+            result = run_postprocess(
+                flows=not getattr(args, "no_flows", False),
+                communities=not getattr(args, "no_communities", False),
+                fts=not getattr(args, "no_fts", False),
+                repo_root=str(repo_root),
+            )
+            parts = []
+            if result.get("flows_detected"):
+                parts.append(f"{result['flows_detected']} flows")
+            if result.get("communities_detected"):
+                parts.append(f"{result['communities_detected']} communities")
+            if result.get("fts_indexed"):
+                parts.append(f"{result['fts_indexed']} FTS entries")
+            print(f"Post-processing: {', '.join(parts) or 'done'}")
+        finally:
+            store.close()
+        return
+
     if args.command in ("update", "detect-changes"):
         # update and detect-changes require git for diffing
         repo_root = Path(args.repo) if args.repo else find_repo_root()
@@ -420,19 +477,40 @@ def main() -> None:
 
     try:
         if args.command == "build":
-            result = full_build(repo_root, store)
+            pp = "none" if getattr(args, "skip_postprocess", False) else (
+                "minimal" if getattr(args, "skip_flows", False) else "full"
+            )
+            from .tools.build import build_or_update_graph
+            result = build_or_update_graph(
+                full_rebuild=True, repo_root=str(repo_root), postprocess=pp,
+            )
+            parsed = result.get("files_parsed", 0)
+            nodes = result.get("total_nodes", 0)
+            edges = result.get("total_edges", 0)
             print(
-                f"Full build: {result['files_parsed']} files, "
-                f"{result['total_nodes']} nodes, {result['total_edges']} edges"
+                f"Full build: {parsed} files, "
+                f"{nodes} nodes, {edges} edges"
+                f" (postprocess={pp})"
             )
-            if result["errors"]:
+            if result.get("errors"):
                 print(f"Errors: {len(result['errors'])}")
 
         elif args.command == "update":
-            result = incremental_update(repo_root, store, base=args.base)
+            pp = "none" if getattr(args, "skip_postprocess", False) else (
+                "minimal" if getattr(args, "skip_flows", False) else "full"
+            )
+            from .tools.build import build_or_update_graph
+            result = build_or_update_graph(
+                full_rebuild=False, repo_root=str(repo_root),
+                base=args.base, postprocess=pp,
+            )
+            updated = result.get("files_updated", 0)
+            nodes = result.get("total_nodes", 0)
+            edges = result.get("total_edges", 0)
             print(
-                f"Incremental: {result['files_updated']} files updated, "
-                f"{result['total_nodes']} nodes, {result['total_edges']} edges"
+                f"Incremental: {updated} files updated, "
+                f"{nodes} nodes, {edges} edges"
+                f" (postprocess={pp})"
             )
 
         elif args.command == "status":
@@ -464,8 +542,9 @@ def main() -> None:
         elif args.command == "visualize":
             from .visualization import generate_html
             html_path = repo_root / ".code-review-graph" / "graph.html"
-            generate_html(store, html_path)
-            print(f"Visualization: {html_path}")
+            vis_mode = getattr(args, "mode", "auto") or "auto"
+            generate_html(store, html_path, mode=vis_mode)
+            print(f"Visualization ({vis_mode}): {html_path}")
             if getattr(args, "serve", False):
                 import functools
                 import http.server

code_review_graph/communities.py

@@ -433,6 +433,46 @@ def detect_communities(
     return results
 
 
+def incremental_detect_communities(
+    store: GraphStore,
+    changed_files: list[str],
+    min_size: int = 2,
+) -> int:
+    """Re-detect communities only if changed files affect existing communities.
+
+    If no existing communities contain nodes from changed files, skips
+    re-detection entirely (the common case for small changes). Otherwise
+    re-runs full community detection.
+
+    Args:
+        store: The GraphStore instance.
+        changed_files: List of file paths that have changed.
+        min_size: Minimum number of nodes for a community to be included.
+
+    Returns:
+        Number of communities detected, or 0 if skipped.
+    """
+    if not changed_files:
+        return 0
+
+    conn = store._conn
+
+    # Check if any communities are affected
+    placeholders = ",".join("?" * len(changed_files))
+    affected = conn.execute(
+        f"SELECT COUNT(DISTINCT community_id) FROM nodes "  # nosec B608
+        f"WHERE community_id IS NOT NULL AND file_path IN ({placeholders})",
+        changed_files,
+    ).fetchone()
+
+    if not affected or affected[0] == 0:
+        return 0  # No communities affected, skip
+
+    # Re-run full community detection (correct and fast enough)
+    communities = detect_communities(store, min_size=min_size)
+    return store_communities(store, communities)
+
+
 def store_communities(
     store: GraphStore, communities: list[dict[str, Any]]
 ) -> int:

code_review_graph/constants.py

@@ -2,9 +2,22 @@
 
 from __future__ import annotations
 
+import os
+
 SECURITY_KEYWORDS: frozenset[str] = frozenset({
     "auth", "login", "password", "token", "session", "crypt", "secret",
     "credential", "permission", "sql", "query", "execute", "connect",
     "socket", "request", "http", "sanitize", "validate", "encrypt",
     "decrypt", "hash", "sign", "verify", "admin", "privilege",
 })
+
+# ---------------------------------------------------------------------------
+# Configurable limits (override via environment variables)
+# ---------------------------------------------------------------------------
+MAX_IMPACT_NODES = int(os.environ.get("CRG_MAX_IMPACT_NODES", "500"))
+MAX_IMPACT_DEPTH = int(os.environ.get("CRG_MAX_IMPACT_DEPTH", "2"))
+MAX_BFS_DEPTH = int(os.environ.get("CRG_MAX_BFS_DEPTH", "15"))
+MAX_SEARCH_RESULTS = int(os.environ.get("CRG_MAX_SEARCH_RESULTS", "20"))
+
+# BFS engine: "sql" (SQLite recursive CTE) or "networkx" (Python-side BFS)
+BFS_ENGINE = os.environ.get("CRG_BFS_ENGINE", "sql")