code-review-graph-codeblackwell 2.3.6.post1__py3-none-any.whl

code_review_graph/spring_resolver.py

@@ -0,0 +1,200 @@
+"""Post-build Spring DI call resolver.
+
+After tree-sitter parsing, Java CALLS edges whose target is a bare method
+name (e.g. ``calculate``) carry ``extra.receiver`` naming the local variable
+that was called on (e.g. ``invoiceCalculationService``).  This module
+resolves those receivers through the INJECTS map to their declared type, then
+optionally to the unique concrete implementation via INHERITS edges.
+
+Resolution chain:
+    receiver variable name
+        → injected interface/class (from INJECTS.extra.field_name)
+        → concrete implementation (from INHERITS, when unique)
+
+Only Java files are processed.  Edges that are already qualified (contain
+``::``) or have no ``receiver`` extra key are skipped.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .graph import GraphStore
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_spring_di_calls(store: GraphStore) -> dict:
+    """Resolve Java CALLS edges whose receiver is a Spring-injected field.
+
+    Safe to call multiple times — already-resolved edges (targets containing
+    ``::``) are skipped.
+
+    Returns a dict with resolution counts for telemetry.
+    """
+    conn = store._conn
+
+    # Only process Java files
+    java_files: set[str] = {
+        row["file_path"]
+        for row in conn.execute(
+            "SELECT DISTINCT file_path FROM nodes WHERE language = 'java'"
+        ).fetchall()
+    }
+    if not java_files:
+        return {"files_indexed": 0, "calls_resolved": 0}
+
+    # -----------------------------------------------------------------------
+    # Build field_map: (source_qualified_class, field_name) → injected_type
+    # from INJECTS edges that carry extra.field_name
+    # -----------------------------------------------------------------------
+    field_map: dict[tuple[str, str], str] = {}
+    injects_rows = conn.execute(
+        "SELECT source_qualified, target_qualified, extra FROM edges WHERE kind = 'INJECTS'"
+    ).fetchall()
+    for row in injects_rows:
+        try:
+            extra = json.loads(row["extra"] or "{}")
+        except (json.JSONDecodeError, TypeError):
+            extra = {}
+        fname = extra.get("field_name")
+        if not fname:
+            continue
+        # source_qualified is the full class qualified name
+        class_qual = row["source_qualified"]
+        field_map[(class_qual, fname)] = row["target_qualified"]
+
+    if not field_map:
+        logger.info("Spring resolver: no INJECTS edges with field_name found, skipping")
+        return {"files_indexed": len(java_files), "calls_resolved": 0}
+
+    # -----------------------------------------------------------------------
+    # Build class_name → qualified_name lookup from nodes.
+    # Keyed by bare class name; value is the full "file_path::ClassName" form
+    # that callers_of uses for its target_qualified exact-match lookup.
+    # When a name appears in multiple files (e.g. same interface in several
+    # services), we keep the entry with the shortest path as a tiebreaker —
+    # this is overridden by the concrete-implementation lookup below.
+    # -----------------------------------------------------------------------
+    name_to_qual: dict[str, str] = {}
+    for row in conn.execute(
+        "SELECT name, qualified_name FROM nodes WHERE kind = 'Class' AND language = 'java'"
+    ).fetchall():
+        bare = row["name"]
+        qual = row["qualified_name"]
+        if bare not in name_to_qual or len(qual) < len(name_to_qual[bare]):
+            name_to_qual[bare] = qual
+
+    # Also index Function nodes so we can build "file::Class.method" targets.
+    # key: (class_name, method_name) → full qualified_name of the method node
+    method_to_qual: dict[tuple[str, str], str] = {}
+    for row in conn.execute(
+        "SELECT name, qualified_name, parent_name FROM nodes "
+        "WHERE kind IN ('Function', 'Test') AND language = 'java' AND parent_name IS NOT NULL"
+    ).fetchall():
+        method_to_qual[(row["parent_name"], row["name"])] = row["qualified_name"]
+
+    # -----------------------------------------------------------------------
+    # Build implementors: bare interface name → list of implementing class quals
+    # from INHERITS edges (Java uses INHERITS for both extends and implements)
+    # -----------------------------------------------------------------------
+    implementors: dict[str, list[str]] = {}
+    for row in conn.execute(
+        "SELECT source_qualified, target_qualified FROM edges WHERE kind = 'INHERITS'"
+    ).fetchall():
+        iface = row["target_qualified"]
+        impl = row["source_qualified"]
+        if any(impl.startswith(f) for f in java_files) or "::" in impl:
+            implementors.setdefault(iface, []).append(impl)
+
+    # -----------------------------------------------------------------------
+    # Resolve CALLS edges
+    # -----------------------------------------------------------------------
+    calls_rows = conn.execute(
+        "SELECT id, source_qualified, target_qualified, extra, file_path "
+        "FROM edges WHERE kind = 'CALLS'"
+    ).fetchall()
+
+    resolved = 0
+
+    for row in calls_rows:
+        if row["file_path"] not in java_files:
+            continue
+
+        try:
+            extra = json.loads(row["extra"] or "{}")
+        except (json.JSONDecodeError, TypeError):
+            extra = {}
+
+        receiver = extra.get("receiver")
+        if not receiver:
+            continue
+
+        # Skip edges already spring-resolved in a previous pass
+        if extra.get("spring_resolved"):
+            continue
+
+        # Strip any prior (possibly wrong) qualification — we have a receiver so
+        # we can do a better resolution.  E.g. "file::ClassName.method" → "method"
+        raw_target = row["target_qualified"]
+        if "::" in raw_target:
+            after = raw_target.split("::", 1)[1]
+            method_name = after.split(".")[-1] if "." in after else after
+        else:
+            method_name = raw_target
+        source_qual = row["source_qualified"]
+
+        # Derive the enclosing class qualified name from source
+        # source_qual format: "file_path::ClassName.method_name"
+        enclosing_class_qual: str | None = None
+        if "::" in source_qual:
+            after_sep = source_qual.split("::", 1)[1]
+            if "." in after_sep:
+                class_part = after_sep.split(".")[0]
+                prefix = source_qual.split("::")[0]
+                enclosing_class_qual = f"{prefix}::{class_part}"
+            else:
+                enclosing_class_qual = source_qual
+
+        if not enclosing_class_qual:
+            continue
+
+        # Look up receiver in field_map for this class
+        injected_type = field_map.get((enclosing_class_qual, receiver))
+        if not injected_type:
+            continue
+
+        # Resolve to concrete implementation if unique
+        impls = implementors.get(injected_type, [])
+        if len(impls) == 1:
+            concrete_class = impls[0].split("::")[-1]
+            fallback = f"{impls[0]}.{method_name}"
+            new_target = method_to_qual.get((concrete_class, method_name)) or fallback
+        else:
+            type_bare = injected_type.rsplit(".", 1)[-1]
+            fallback = f"{injected_type}.{method_name}"
+            new_target = method_to_qual.get((type_bare, method_name)) or fallback
+
+        extra["spring_resolved"] = True
+        extra["injected_type"] = injected_type
+        new_extra = json.dumps(extra)
+
+        conn.execute(
+            "UPDATE edges SET target_qualified = ?, extra = ? WHERE id = ?",
+            (new_target, new_extra, row["id"]),
+        )
+        resolved += 1
+        logger.debug(
+            "Spring resolved: %s → %s (was %s, receiver=%s)",
+            source_qual, new_target, method_name, receiver,
+        )
+
+    if resolved:
+        conn.commit()
+
+    logger.info("Spring DI resolver: resolved %d CALLS edges in %d Java files",
+                resolved, len(java_files))
+    return {"files_indexed": len(java_files), "calls_resolved": resolved}

code_review_graph/temporal_resolver.py

@@ -0,0 +1,199 @@
+"""Post-build Temporal workflow/activity call resolver.
+
+After tree-sitter parsing, Java CALLS edges whose target is a bare method
+name carry ``extra.receiver`` naming the local variable called on.  This
+module resolves those receivers through the TEMPORAL_STUB map to their
+declared Temporal interface type, then optionally to the unique concrete
+implementation via INHERITS edges.
+
+Resolution chain:
+    receiver variable name
+        → temporal stub field type (from TEMPORAL_STUB.extra.field_name)
+        → concrete implementation (from INHERITS, when unique)
+
+Only Java files are processed.  TEMPORAL_STUB edges whose target is not a
+node with ``temporal_role`` in extra are silently skipped (they may be
+non-Temporal types that happen to end in 'Activity'/'Workflow').
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .graph import GraphStore
+
+logger = logging.getLogger(__name__)
+
+
+def resolve_temporal_calls(store: GraphStore) -> dict:
+    """Resolve Java CALLS edges whose receiver is a Temporal activity/workflow stub.
+
+    Safe to call multiple times — already-resolved edges (with
+    ``extra.temporal_resolved``) are skipped.
+
+    Returns a dict with resolution counts for telemetry.
+    """
+    conn = store._conn
+
+    java_files: set[str] = {
+        row["file_path"]
+        for row in conn.execute(
+            "SELECT DISTINCT file_path FROM nodes WHERE language = 'java'"
+        ).fetchall()
+    }
+    if not java_files:
+        return {"files_indexed": 0, "calls_resolved": 0}
+
+    # -----------------------------------------------------------------------
+    # Collect Temporal interface nodes: bare name → qualified_name
+    # (nodes whose extra contains temporal_role = workflow_interface|activity_interface)
+    # -----------------------------------------------------------------------
+    temporal_interfaces: dict[str, str] = {}  # bare_name → qualified_name
+    for row in conn.execute(
+        "SELECT name, qualified_name, extra FROM nodes "
+        "WHERE language = 'java' AND extra IS NOT NULL AND extra LIKE '%temporal_role%'"
+    ).fetchall():
+        try:
+            ex = json.loads(row["extra"] or "{}")
+        except (json.JSONDecodeError, TypeError):
+            ex = {}
+        if ex.get("temporal_role") in ("workflow_interface", "activity_interface"):
+            temporal_interfaces[row["name"]] = row["qualified_name"]
+
+    if not temporal_interfaces:
+        logger.info("Temporal resolver: no Workflow/ActivityInterface nodes, skipping")
+        return {"files_indexed": len(java_files), "calls_resolved": 0}
+
+    # -----------------------------------------------------------------------
+    # Build field_map: (source_qualified_class, field_name) → interface_type
+    # from TEMPORAL_STUB edges whose target is a known Temporal interface
+    # -----------------------------------------------------------------------
+    field_map: dict[tuple[str, str], str] = {}
+    for row in conn.execute(
+        "SELECT source_qualified, target_qualified, extra FROM edges WHERE kind = 'TEMPORAL_STUB'"
+    ).fetchall():
+        bare_target = row["target_qualified"]
+        if bare_target not in temporal_interfaces:
+            continue
+        try:
+            extra = json.loads(row["extra"] or "{}")
+        except (json.JSONDecodeError, TypeError):
+            extra = {}
+        fname = extra.get("field_name")
+        if not fname:
+            continue
+        field_map[(row["source_qualified"], fname)] = bare_target
+
+    if not field_map:
+        logger.info("Temporal resolver: no TEMPORAL_STUB edges found, skipping")
+        return {"files_indexed": len(java_files), "calls_resolved": 0}
+
+    # -----------------------------------------------------------------------
+    # method_to_qual: (class_name, method_name) → full qualified_name
+    # -----------------------------------------------------------------------
+    method_to_qual: dict[tuple[str, str], str] = {}
+    for row in conn.execute(
+        "SELECT name, qualified_name, parent_name FROM nodes "
+        "WHERE kind IN ('Function', 'Test') AND language = 'java' AND parent_name IS NOT NULL"
+    ).fetchall():
+        method_to_qual[(row["parent_name"], row["name"])] = row["qualified_name"]
+
+    # -----------------------------------------------------------------------
+    # implementors: bare interface name → list of implementing class quals
+    # -----------------------------------------------------------------------
+    implementors: dict[str, list[str]] = {}
+    for row in conn.execute(
+        "SELECT source_qualified, target_qualified FROM edges WHERE kind = 'INHERITS'"
+    ).fetchall():
+        iface = row["target_qualified"]
+        impl = row["source_qualified"]
+        if any(impl.startswith(f) for f in java_files) or "::" in impl:
+            implementors.setdefault(iface, []).append(impl)
+
+    # -----------------------------------------------------------------------
+    # Resolve CALLS edges
+    # -----------------------------------------------------------------------
+    calls_rows = conn.execute(
+        "SELECT id, source_qualified, target_qualified, extra, file_path "
+        "FROM edges WHERE kind = 'CALLS'"
+    ).fetchall()
+
+    resolved = 0
+
+    for row in calls_rows:
+        if row["file_path"] not in java_files:
+            continue
+
+        try:
+            extra = json.loads(row["extra"] or "{}")
+        except (json.JSONDecodeError, TypeError):
+            extra = {}
+
+        receiver = extra.get("receiver")
+        if not receiver:
+            continue
+
+        if extra.get("temporal_resolved") or extra.get("spring_resolved"):
+            continue
+
+        raw_target = row["target_qualified"]
+        if "::" in raw_target:
+            after = raw_target.split("::", 1)[1]
+            method_name = after.split(".")[-1] if "." in after else after
+        else:
+            method_name = raw_target
+
+        source_qual = row["source_qualified"]
+
+        # Derive enclosing class qualified name
+        enclosing_class_qual: str | None = None
+        if "::" in source_qual:
+            after_sep = source_qual.split("::", 1)[1]
+            if "." in after_sep:
+                class_part = after_sep.split(".")[0]
+                prefix = source_qual.split("::")[0]
+                enclosing_class_qual = f"{prefix}::{class_part}"
+            else:
+                enclosing_class_qual = source_qual
+
+        if not enclosing_class_qual:
+            continue
+
+        interface_bare = field_map.get((enclosing_class_qual, receiver))
+        if not interface_bare:
+            continue
+
+        interface_qual = temporal_interfaces.get(interface_bare, interface_bare)
+
+        impls = implementors.get(interface_qual, [])
+        if len(impls) == 1:
+            concrete_class = impls[0].split("::")[-1]
+            fallback = f"{impls[0]}.{method_name}"
+            new_target = method_to_qual.get((concrete_class, method_name)) or fallback
+        else:
+            fallback = f"{interface_qual}.{method_name}"
+            new_target = method_to_qual.get((interface_bare, method_name)) or fallback
+
+        extra["temporal_resolved"] = True
+        extra["temporal_interface"] = interface_bare
+        new_extra = json.dumps(extra)
+
+        conn.execute(
+            "UPDATE edges SET target_qualified = ?, extra = ? WHERE id = ?",
+            (new_target, new_extra, row["id"]),
+        )
+        resolved += 1
+        logger.debug(
+            "Temporal resolved: %s → %s (receiver=%s, interface=%s)",
+            source_qual, new_target, receiver, interface_bare,
+        )
+
+    if resolved:
+        conn.commit()
+
+    logger.info("Temporal resolver: resolved %d CALLS edges in %d Java files",
+                resolved, len(java_files))
+    return {"files_indexed": len(java_files), "calls_resolved": resolved}

code_review_graph/token_benchmark.py

@@ -0,0 +1,125 @@
+"""Token reduction benchmark -- measures graph query efficiency vs naive file reading."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .graph import GraphStore
+from .search import hybrid_search
+
+logger = logging.getLogger(__name__)
+
+# Sample questions for benchmarking
+_SAMPLE_QUESTIONS = [
+    "how does authentication work",
+    "what is the main entry point",
+    "how are database connections managed",
+    "what error handling patterns are used",
+    "how do tests verify core functionality",
+]
+
+
+def estimate_tokens(text: str) -> int:
+    """Rough token estimate: ~4 chars per token."""
+    return max(1, len(text) // 4)
+
+
+def compute_naive_tokens(repo_root: Path) -> int:
+    """Count tokens in all parseable source files."""
+    total = 0
+    exts = (
+        ".py", ".js", ".ts", ".go", ".rs", ".java",
+        ".c", ".cpp", ".rb", ".php", ".swift", ".kt",
+    )
+    for ext in exts:
+        for f in repo_root.rglob(f"*{ext}"):
+            try:
+                total += estimate_tokens(
+                    f.read_text(errors="replace")
+                )
+            except OSError:
+                continue
+    return total
+
+
+def run_token_benchmark(
+    store: GraphStore,
+    repo_root: Path,
+    questions: list[str] | None = None,
+) -> dict[str, Any]:
+    """Run token reduction benchmark.
+
+    Compares naive full-corpus token cost vs graph query token
+    cost for a set of sample questions.
+
+    The default sample questions are natural language and require semantic
+    search to match. If no embeddings are present in the graph, ``hybrid_search``
+    falls back to FTS5/LIKE matching on node names, which produces no hits for
+    questions like "how does authentication work" — every per-question ratio
+    becomes 0 and the benchmark silently appears to fail. We log a clear
+    warning when that is the case so callers know to run ``embed_graph`` first
+    (or to pass keyword-matching questions).
+    """
+    if questions is None:
+        questions = _SAMPLE_QUESTIONS
+
+    using_default_questions = questions is _SAMPLE_QUESTIONS
+    try:
+        cur = store._conn.execute("SELECT count(*) FROM embeddings")
+        embedding_count = cur.fetchone()[0]
+    except sqlite3.OperationalError:
+        embedding_count = 0
+    if embedding_count == 0 and using_default_questions:
+        logger.warning(
+            "No embeddings found in this graph. The default sample questions "
+            "are natural language and will not match via FTS5/LIKE alone — "
+            "every reduction ratio is likely to be 0. Run "
+            "`code-review-graph embed` first, or pass keyword-matching `questions=`."
+        )
+
+    naive_total = compute_naive_tokens(repo_root)
+
+    results = []
+    for q in questions:
+        search_results = hybrid_search(store, q, limit=5)
+        # Simulate graph context: search results + neighbors
+        graph_tokens = 0
+        for r in search_results:
+            graph_tokens += estimate_tokens(str(r))
+            # Add approximate neighbor context
+            qn = r.get("qualified_name", "")
+            edges = store.get_edges_by_source(qn)[:5]
+            for e in edges:
+                graph_tokens += estimate_tokens(str(e))
+
+        if graph_tokens > 0:
+            ratio = naive_total / graph_tokens
+        else:
+            ratio = 0
+        results.append({
+            "question": q,
+            "naive_tokens": naive_total,
+            "graph_tokens": graph_tokens,
+            "reduction_ratio": round(ratio, 1),
+        })
+
+    if results:
+        total = sum(
+            r["reduction_ratio"] for r in results  # type: ignore[misc]
+        )
+        avg_ratio = float(total) / len(results)  # type: ignore[arg-type]
+    else:
+        avg_ratio = 0.0
+
+    return {
+        "naive_corpus_tokens": naive_total,
+        "per_question": results,
+        "average_reduction_ratio": round(avg_ratio, 1),
+        "summary": (
+            f"Graph queries use ~{avg_ratio:.0f}x fewer tokens "
+            f"than reading all source files"
+        ),
+    }

code_review_graph/tools/__init__.py

@@ -0,0 +1,156 @@
+"""MCP tool definitions for the Code Review Graph server.
+
+Exposes 27 tools:
+1. build_or_update_graph  - full or incremental build
+2. get_impact_radius      - blast radius from changed files
+3. query_graph            - predefined graph queries
+4. get_review_context     - focused subgraph + review prompt
+5. semantic_search_nodes  - keyword + vector search across nodes
+6. list_graph_stats       - aggregate statistics
+7. embed_graph            - compute vector embeddings for semantic search
+8. get_docs_section       - token-optimized documentation retrieval
+9. find_large_functions   - find oversized functions/classes by line count
+10. list_flows            - list execution flows sorted by criticality
+11. get_flow              - get details of a single execution flow
+12. get_affected_flows    - find flows affected by changed files
+13. list_communities      - list detected code communities
+14. get_community         - get details of a single community
+15. get_architecture_overview - architecture overview from community structure
+16. detect_changes        - risk-scored change impact analysis for code review
+17. refactor_tool         - unified refactoring (rename preview, dead code, suggestions)
+18. apply_refactor_tool   - apply a previously previewed refactoring
+19. generate_wiki         - generate markdown wiki from community structure
+20. get_wiki_page         - retrieve a specific wiki page
+21. list_repos            - list registered repositories
+22. cross_repo_search     - search across all registered repositories
+23. get_hub_nodes         - find most connected nodes (architectural hotspots)
+24. get_bridge_nodes      - find architectural chokepoints (betweenness centrality)
+25. get_knowledge_gaps    - identify structural weaknesses
+26. get_surprising_connections - find unexpected architectural coupling
+27. get_suggested_questions - auto-generated review questions from graph analysis
+28. traverse_graph        - BFS/DFS traversal from best-matching node
+"""
+
+from __future__ import annotations
+
+# Re-export names that external code may patch via "code_review_graph.tools.*"
+from ..changes import parse_diff_ranges as parse_diff_ranges
+from ..changes import parse_git_diff_ranges as parse_git_diff_ranges
+from ..changes import parse_svn_diff_ranges as parse_svn_diff_ranges
+from ..incremental import (
+    get_changed_files as get_changed_files,
+)
+from ..incremental import (
+    get_staged_and_unstaged as get_staged_and_unstaged,
+)
+
+# -- _common ----------------------------------------------------------------
+from ._common import (
+    _BUILTIN_CALL_NAMES,
+    _get_store,
+    _validate_repo_root,
+)
+
+# -- analysis_tools ---------------------------------------------------------
+from .analysis_tools import (
+    get_bridge_nodes_func,
+    get_hub_nodes_func,
+    get_knowledge_gaps_func,
+    get_suggested_questions_func,
+    get_surprising_connections_func,
+)
+
+# -- build ------------------------------------------------------------------
+from .build import build_or_update_graph, run_postprocess
+
+# -- community_tools --------------------------------------------------------
+from .community_tools import (
+    get_architecture_overview_func,
+    get_community_func,
+    list_communities_func,
+)
+
+# -- context ----------------------------------------------------------------
+from .context import get_minimal_context
+
+# -- docs -------------------------------------------------------------------
+from .docs import embed_graph, generate_wiki_func, get_docs_section, get_wiki_page_func
+
+# -- flows_tools ------------------------------------------------------------
+from .flows_tools import get_flow, list_flows
+
+# -- query ------------------------------------------------------------------
+from .query import (
+    find_large_functions,
+    get_impact_radius,
+    list_graph_stats,
+    query_graph,
+    semantic_search_nodes,
+    traverse_graph_func,
+)
+
+# -- refactor_tools ---------------------------------------------------------
+from .refactor_tools import apply_refactor_func, refactor_func
+
+# -- registry_tools ---------------------------------------------------------
+from .registry_tools import cross_repo_search_func, list_repos_func
+
+# -- review -----------------------------------------------------------------
+from .review import (
+    detect_changes_func,
+    get_affected_flows_func,
+    get_review_context,
+)
+
+__all__ = [
+    # _common
+    "_BUILTIN_CALL_NAMES",
+    "_get_store",
+    "_validate_repo_root",
+    # build
+    "build_or_update_graph",
+    "run_postprocess",
+    # context
+    "get_minimal_context",
+    # community_tools
+    "get_architecture_overview_func",
+    "get_community_func",
+    "list_communities_func",
+    # docs
+    "embed_graph",
+    "generate_wiki_func",
+    "get_docs_section",
+    "get_wiki_page_func",
+    # flows_tools
+    "get_flow",
+    "list_flows",
+    # query
+    "find_large_functions",
+    "get_impact_radius",
+    "list_graph_stats",
+    "query_graph",
+    "semantic_search_nodes",
+    "traverse_graph_func",
+    # refactor_tools
+    "apply_refactor_func",
+    "refactor_func",
+    # registry_tools
+    "cross_repo_search_func",
+    "list_repos_func",
+    # review
+    "detect_changes_func",
+    "get_affected_flows_func",
+    "get_review_context",
+    # analysis_tools
+    "get_bridge_nodes_func",
+    "get_hub_nodes_func",
+    "get_knowledge_gaps_func",
+    "get_suggested_questions_func",
+    "get_surprising_connections_func",
+    # re-exported for backward compat (used in test patches)
+    "get_changed_files",
+    "get_staged_and_unstaged",
+    "parse_git_diff_ranges",
+    "parse_svn_diff_ranges",
+    "parse_diff_ranges",
+]