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

code_review_graph/enrich.py

@@ -0,0 +1,303 @@
+"""PreToolUse search enrichment for Claude Code hooks.
+
+Intercepts Grep/Glob/Bash/Read tool calls and enriches them with
+structural context from the code knowledge graph: callers, callees,
+execution flows, community membership, and test coverage.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Flags that consume the next token in grep/rg commands
+_RG_FLAGS_WITH_VALUES = frozenset({
+    "-e", "-f", "-m", "-A", "-B", "-C", "-g", "--glob",
+    "-t", "--type", "--include", "--exclude", "--max-count",
+    "--max-depth", "--max-filesize", "--color", "--colors",
+    "--context-separator", "--field-match-separator",
+    "--path-separator", "--replace", "--sort", "--sortr",
+})
+
+
+def extract_pattern(tool_name: str, tool_input: dict[str, Any]) -> str | None:
+    """Extract a search pattern from a tool call's input.
+
+    Returns None if no meaningful pattern can be extracted.
+    """
+    if tool_name == "Grep":
+        return tool_input.get("pattern")
+
+    if tool_name == "Glob":
+        raw = tool_input.get("pattern", "")
+        # Extract meaningful name from glob: "**/auth*.ts" -> "auth"
+        # Skip pure extension globs like "**/*.ts"
+        match = re.search(r"[*/]([a-zA-Z][a-zA-Z0-9_]{2,})", raw)
+        return match.group(1) if match else None
+
+    if tool_name == "Bash":
+        cmd = tool_input.get("command", "")
+        if not re.search(r"\brg\b|\bgrep\b", cmd):
+            return None
+        tokens = cmd.split()
+        found_cmd = False
+        skip_next = False
+        for token in tokens:
+            if skip_next:
+                skip_next = False
+                continue
+            if not found_cmd:
+                if re.search(r"\brg$|\bgrep$", token):
+                    found_cmd = True
+                continue
+            if token.startswith("-"):
+                if token in _RG_FLAGS_WITH_VALUES:
+                    skip_next = True
+                continue
+            cleaned = token.strip("'\"")
+            return cleaned if len(cleaned) >= 3 else None
+        return None
+
+    return None
+
+
+def _make_relative(file_path: str, repo_root: str) -> str:
+    """Make a file path relative to repo_root for display."""
+    try:
+        return str(Path(file_path).relative_to(repo_root))
+    except ValueError:
+        return file_path
+
+
+def _get_community_name(conn: Any, community_id: int) -> str:
+    """Fetch a community name by ID."""
+    row = conn.execute(
+        "SELECT name FROM communities WHERE id = ?", (community_id,)
+    ).fetchone()
+    return row["name"] if row else ""
+
+
+def _get_flow_names_for_node(conn: Any, node_id: int) -> list[str]:
+    """Fetch execution flow names that a node participates in (max 3)."""
+    rows = conn.execute(
+        "SELECT f.name FROM flow_memberships fm "
+        "JOIN flows f ON fm.flow_id = f.id "
+        "WHERE fm.node_id = ? LIMIT 3",
+        (node_id,),
+    ).fetchall()
+    return [r["name"] for r in rows]
+
+
+def _format_node_context(
+    node: Any,
+    store: Any,
+    conn: Any,
+    repo_root: str,
+) -> list[str]:
+    """Format a single node's structural context as plain text lines."""
+    from .graph import GraphNode
+    assert isinstance(node, GraphNode)
+
+    qn = node.qualified_name
+    loc = _make_relative(node.file_path, repo_root)
+    if node.line_start:
+        loc = f"{loc}:{node.line_start}"
+
+    header = f"{node.name} ({loc})"
+
+    # Community
+    if node.extra.get("community_id"):
+        cname = _get_community_name(conn, node.extra["community_id"])
+        if cname:
+            header += f" [{cname}]"
+    else:
+        # Check via direct query
+        row = conn.execute(
+            "SELECT community_id FROM nodes WHERE id = ?", (node.id,)
+        ).fetchone()
+        if row and row["community_id"]:
+            cname = _get_community_name(conn, row["community_id"])
+            if cname:
+                header += f" [{cname}]"
+
+    lines = [header]
+
+    # Callers (max 5, deduplicated)
+    callers: list[str] = []
+    seen: set[str] = set()
+    for e in store.get_edges_by_target(qn):
+        if e.kind == "CALLS" and len(callers) < 5:
+            c = store.get_node(e.source_qualified)
+            if c and c.name not in seen:
+                seen.add(c.name)
+                callers.append(c.name)
+    if callers:
+        lines.append(f"  Called by: {', '.join(callers)}")
+
+    # Callees (max 5, deduplicated)
+    callees: list[str] = []
+    seen.clear()
+    for e in store.get_edges_by_source(qn):
+        if e.kind == "CALLS" and len(callees) < 5:
+            c = store.get_node(e.target_qualified)
+            if c and c.name not in seen:
+                seen.add(c.name)
+                callees.append(c.name)
+    if callees:
+        lines.append(f"  Calls: {', '.join(callees)}")
+
+    # Execution flows
+    flow_names = _get_flow_names_for_node(conn, node.id)
+    if flow_names:
+        lines.append(f"  Flows: {', '.join(flow_names)}")
+
+    # Tests
+    tests: list[str] = []
+    for e in store.get_edges_by_target(qn):
+        if e.kind == "TESTED_BY" and len(tests) < 3:
+            t = store.get_node(e.source_qualified)
+            if t:
+                tests.append(t.name)
+    if tests:
+        lines.append(f"  Tests: {', '.join(tests)}")
+
+    return lines
+
+
+def enrich_search(pattern: str, repo_root: str) -> str:
+    """Search the graph for pattern and return enriched context."""
+    from .graph import GraphStore
+    from .search import _fts_search
+
+    db_path = Path(repo_root) / ".code-review-graph" / "graph.db"
+    if not db_path.exists():
+        return ""
+
+    store = GraphStore(db_path)
+    try:
+        conn = store._conn
+
+        fts_results = _fts_search(conn, pattern, limit=8)
+        if not fts_results:
+            return ""
+
+        all_lines: list[str] = []
+        count = 0
+        for node_id, _score in fts_results:
+            if count >= 5:
+                break
+            node = store.get_node_by_id(node_id)
+            if not node or node.is_test:
+                continue
+            node_lines = _format_node_context(node, store, conn, repo_root)
+            all_lines.extend(node_lines)
+            all_lines.append("")
+            count += 1
+
+        if not all_lines:
+            return ""
+
+        header = f'[code-review-graph] {count} symbol(s) matching "{pattern}":\n'
+        return header + "\n".join(all_lines)
+    finally:
+        store.close()
+
+
+def enrich_file_read(file_path: str, repo_root: str) -> str:
+    """Enrich a file read with structural context for functions in that file."""
+    from .graph import GraphStore
+
+    db_path = Path(repo_root) / ".code-review-graph" / "graph.db"
+    if not db_path.exists():
+        return ""
+
+    store = GraphStore(db_path)
+    try:
+        conn = store._conn
+        nodes = store.get_nodes_by_file(file_path)
+        if not nodes:
+            # Try with resolved path
+            try:
+                resolved = str(Path(file_path).resolve())
+                nodes = store.get_nodes_by_file(resolved)
+            except (OSError, ValueError):
+                pass
+        if not nodes:
+            return ""
+
+        # Filter to functions/classes/types (skip File nodes), limit to 10
+        interesting = [
+            n for n in nodes
+            if n.kind in ("Function", "Class", "Type", "Test")
+        ][:10]
+
+        if not interesting:
+            return ""
+
+        all_lines: list[str] = []
+        for node in interesting:
+            node_lines = _format_node_context(node, store, conn, repo_root)
+            all_lines.extend(node_lines)
+            all_lines.append("")
+
+        rel_path = _make_relative(file_path, repo_root)
+        header = (
+            f"[code-review-graph] {len(interesting)} symbol(s) in {rel_path}:\n"
+        )
+        return header + "\n".join(all_lines)
+    finally:
+        store.close()
+
+
+def run_hook() -> None:
+    """Entry point for the enrich CLI subcommand.
+
+    Reads Claude Code hook JSON from stdin, extracts the search pattern,
+    queries the graph, and outputs hookSpecificOutput JSON to stdout.
+    """
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return
+
+    tool_name = hook_input.get("tool_name", "")
+    tool_input = hook_input.get("tool_input", {})
+    cwd = hook_input.get("cwd", os.getcwd())
+
+    # Find repo root by walking up from cwd
+    from .incremental import find_project_root
+
+    repo_root = str(find_project_root(Path(cwd)))
+    db_path = Path(repo_root) / ".code-review-graph" / "graph.db"
+    if not db_path.exists():
+        return
+
+    # Dispatch
+    context = ""
+    if tool_name == "Read":
+        fp = tool_input.get("file_path", "")
+        if fp:
+            context = enrich_file_read(fp, repo_root)
+    else:
+        pattern = extract_pattern(tool_name, tool_input)
+        if not pattern or len(pattern) < 3:
+            return
+        context = enrich_search(pattern, repo_root)
+
+    if not context:
+        return
+
+    response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": context,
+        }
+    }
+    json.dump(response, sys.stdout)

code_review_graph/eval/__init__.py

@@ -0,0 +1,33 @@
+"""Evaluation framework for code-review-graph.
+
+Provides scoring metrics (token efficiency, MRR, precision/recall),
+benchmark runners, and report generators for benchmarking graph-based code reviews.
+"""
+
+from __future__ import annotations
+
+from .reporter import generate_full_report, generate_markdown_report, generate_readme_tables
+from .scorer import compute_mrr, compute_precision_recall, compute_token_efficiency
+
+
+def __getattr__(name: str):
+    """Lazy-import runner functions (require pyyaml)."""
+    _runner_names = {"load_all_configs", "load_config", "run_eval", "write_csv"}
+    if name in _runner_names:
+        from . import runner
+        return getattr(runner, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "compute_mrr",
+    "compute_precision_recall",
+    "compute_token_efficiency",
+    "generate_full_report",
+    "generate_markdown_report",
+    "generate_readme_tables",
+    "load_all_configs",
+    "load_config",
+    "run_eval",
+    "write_csv",
+]

code_review_graph/eval/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Benchmark modules for the evaluation framework."""

code_review_graph/eval/benchmarks/agent_baseline.py

@@ -0,0 +1,193 @@
+"""Agent baseline benchmark: grep-and-read-top-k versus a graph query.
+
+The whole-corpus baseline in the standalone token benchmark is an upper
+bound no real agent pays: a competent agent greps for identifiers from the
+question and reads only the best-matching files. This benchmark measures
+that realistic baseline:
+
+1. Derive search terms from the question (identifier-shaped tokens via
+   ``search.extract_query_identifiers`` plus plain keywords).
+2. Pure-python grep over the corpus (no external ``rg``/``grep`` binary),
+   ranking files by total case-insensitive match count.
+3. Read the top-k files (k=3) and token-count them with the chars/4 utility
+   (``token_benchmark.estimate_tokens``) as ``baseline_tokens``.
+4. Compare against the graph-query cost for the same question — hybrid
+   search hits plus one hop of neighbor edges, the same accounting used by
+   ``code_review_graph/token_benchmark.py``.
+
+Questions come from ``agent_questions:`` in the repo config, falling back to
+the ``search_queries`` query strings when absent.
+
+Failure semantics match the other benchmarks: a thrown search is recorded
+with ``status="error"`` and excluded from aggregates; rows where either side
+of the ratio is zero get ``status="no_graph_results"`` /
+``status="no_baseline_match"`` and are likewise excluded.
+"""
+
+from __future__ import annotations
+
+import logging
+import statistics
+from collections.abc import Iterator
+from pathlib import Path
+
+from code_review_graph.token_benchmark import estimate_tokens
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TOP_K = 3
+
+_SOURCE_EXTS = (
+    ".py", ".js", ".ts", ".tsx", ".go", ".rs", ".java",
+    ".c", ".cpp", ".h", ".rb", ".php", ".swift", ".kt",
+)
+
+_SKIP_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "__pycache__",
+    ".code-review-graph", ".venv", "venv", "dist", "build",
+}
+
+_STOPWORDS = {
+    "how", "does", "do", "the", "a", "an", "is", "are", "was", "what",
+    "where", "when", "which", "who", "why", "and", "or", "in", "on", "of",
+    "to", "for", "with", "via", "into", "from", "this", "that", "it", "its",
+}
+
+
+def derive_search_terms(question: str) -> list[str]:
+    """Derive lowercase grep terms: identifiers first, then plain keywords.
+
+    Identifier-shaped tokens (``Client.request``, ``get_users``, ``APIRoute``)
+    are extracted via ``search.extract_query_identifiers``; remaining words of
+    3+ characters that are not stopwords are appended. Order is deterministic.
+    """
+    from code_review_graph.search import extract_query_identifiers
+
+    terms: list[str] = []
+    seen: set[str] = set()
+    for ident in extract_query_identifiers(question):
+        if ident not in seen:
+            seen.add(ident)
+            terms.append(ident)
+    for word in question.split():
+        w = word.strip(".,;:!?\"'()[]{}`").lower()
+        if len(w) >= 3 and w not in _STOPWORDS and w not in seen:
+            seen.add(w)
+            terms.append(w)
+    return terms
+
+
+def iter_source_files(repo_path: Path) -> Iterator[Path]:
+    """Yield source files under *repo_path*, skipping vendored/VCS dirs."""
+    for path in sorted(repo_path.rglob("*")):
+        if path.suffix not in _SOURCE_EXTS or not path.is_file():
+            continue
+        if any(part in _SKIP_DIRS for part in path.parts):
+            continue
+        yield path
+
+
+def grep_rank(
+    repo_path: Path, terms: list[str], k: int = DEFAULT_TOP_K,
+) -> list[tuple[str, int]]:
+    """Rank source files by total case-insensitive term matches; take top-k.
+
+    Pure python — no external grep/rg dependency. Deterministic: ties break
+    on the relative path. Files with zero matches are dropped.
+    """
+    lowered = [t.lower() for t in terms if t]
+    if not lowered:
+        return []
+    scores: list[tuple[str, int]] = []
+    for path in iter_source_files(repo_path):
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace").lower()
+        except OSError:
+            continue
+        count = sum(text.count(term) for term in lowered)
+        if count > 0:
+            scores.append((str(path.relative_to(repo_path)), count))
+    scores.sort(key=lambda item: (-item[1], item[0]))
+    return scores[:k]
+
+
+def run(repo_path: Path, store, config: dict) -> list[dict]:
+    """Run the agent baseline benchmark for one repo."""
+    questions = list(config.get("agent_questions") or [])
+    if not questions:
+        questions = [sq["query"] for sq in config.get("search_queries", [])]
+
+    k = int(config.get("agent_baseline_top_k", DEFAULT_TOP_K))
+    results: list[dict] = []
+
+    for question in questions:
+        terms = derive_search_terms(question)
+        top = grep_rank(repo_path, terms, k=k)
+        baseline_tokens = 0
+        for rel, _count in top:
+            try:
+                baseline_tokens += estimate_tokens(
+                    (repo_path / rel).read_text(encoding="utf-8", errors="replace")
+                )
+            except OSError:
+                continue
+
+        row: dict = {
+            "repo": config["name"],
+            "question": question,
+            "terms": " ".join(terms),
+            "files_matched": len(top),
+            "top_files": ";".join(rel for rel, _ in top),
+            "baseline_tokens": baseline_tokens,
+            "graph_tokens": "",
+            "baseline_to_graph_ratio": "",
+            "status": "ok",
+            "error": "",
+        }
+
+        try:
+            from code_review_graph.search import hybrid_search
+            hits = hybrid_search(store, question, limit=5)
+        except Exception as exc:
+            logger.warning("hybrid_search failed on %r: %s", question, exc)
+            row["status"] = "error"
+            row["error"] = str(exc)[:200]
+            results.append(row)
+            continue
+
+        # Same accounting as the standalone token benchmark: search hits
+        # plus up to 5 outgoing edges of neighbor context per hit.
+        graph_tokens = 0
+        for hit in hits:
+            graph_tokens += estimate_tokens(str(hit))
+            qn = hit.get("qualified_name", "")
+            for edge in store.get_edges_by_source(qn)[:5]:
+                graph_tokens += estimate_tokens(str(edge))
+
+        row["graph_tokens"] = graph_tokens
+        if baseline_tokens > 0 and graph_tokens > 0:
+            row["baseline_to_graph_ratio"] = round(baseline_tokens / graph_tokens, 1)
+        elif graph_tokens == 0:
+            row["status"] = "no_graph_results"
+        else:
+            row["status"] = "no_baseline_match"
+        results.append(row)
+
+    return results
+
+
+def aggregate(results: list[dict]) -> dict:
+    """Aggregate over rows where both sides of the comparison exist."""
+    ok = [r for r in results if r.get("status") == "ok"]
+    ratios = [float(r["baseline_to_graph_ratio"]) for r in ok]
+    return {
+        "total_rows": len(results),
+        "ok_rows": len(ok),
+        "error_rows": sum(1 for r in results if r.get("status") == "error"),
+        "median_baseline_to_graph_ratio": (
+            round(statistics.median(ratios), 1) if ratios else None
+        ),
+        "mean_baseline_to_graph_ratio": (
+            round(statistics.mean(ratios), 1) if ratios else None
+        ),
+    }

code_review_graph/eval/benchmarks/build_performance.py

@@ -0,0 +1,60 @@
+"""Build performance benchmark: measures timing of graph operations."""
+
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def run(repo_path: Path, store, config: dict) -> list[dict]:
+    """Run build performance benchmark."""
+    stats = store.get_stats()
+
+    # Time flow detection
+    try:
+        from code_review_graph.flows import store_flows, trace_flows
+        t0 = time.perf_counter()
+        flows = trace_flows(store)
+        store_flows(store, flows)
+        flow_time = time.perf_counter() - t0
+    except Exception as exc:
+        logger.warning("Flow detection failed: %s", exc)
+        flow_time = 0.0
+
+    # Time community detection
+    try:
+        from code_review_graph.communities import detect_communities, store_communities
+        t0 = time.perf_counter()
+        comms = detect_communities(store)
+        store_communities(store, comms)
+        community_time = time.perf_counter() - t0
+    except Exception as exc:
+        logger.warning("Community detection failed: %s", exc)
+        community_time = 0.0
+
+    # Time search (average of queries)
+    search_times: list[float] = []
+    for sq in config.get("search_queries", [])[:10]:
+        t0 = time.perf_counter()
+        store.search_nodes(sq["query"], limit=20)
+        search_times.append(time.perf_counter() - t0)
+
+    avg_search_ms = round(
+        sum(search_times) / max(len(search_times), 1) * 1000, 1
+    )
+
+    return [{
+        "repo": config["name"],
+        "file_count": stats.files_count,
+        "node_count": stats.total_nodes,
+        "edge_count": stats.total_edges,
+        "flow_detection_seconds": round(flow_time, 3),
+        "community_detection_seconds": round(community_time, 3),
+        "search_avg_ms": avg_search_ms,
+        "nodes_per_second": round(
+            stats.total_nodes / max(flow_time, 0.001)
+        ),
+    }]

code_review_graph/eval/benchmarks/flow_completeness.py

@@ -0,0 +1,36 @@
+"""Flow completeness benchmark: evaluates entry point detection and flow tracing."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def run(repo_path: Path, store, config: dict) -> list[dict]:
+    """Run flow completeness benchmark."""
+    from code_review_graph.flows import store_flows, trace_flows
+
+    flows = trace_flows(store)
+    count = store_flows(store, flows)
+
+    # Get detected entry point names
+    detected_entries = set()
+    for flow in flows:
+        detected_entries.add(flow.get("entry_point") or flow.get("name", ""))
+
+    known = set(config.get("entry_points", []))
+    found = sum(1 for ep in known if any(ep in d for d in detected_entries))
+
+    depths = [f.get("depth", 0) for f in flows]
+
+    return [{
+        "repo": config["name"],
+        "known_entry_points": len(known),
+        "detected_entry_points": found,
+        "recall": round(found / max(len(known), 1), 3),
+        "detected_flows": count,
+        "avg_flow_depth": round(sum(depths) / max(len(depths), 1), 1),
+        "max_flow_depth": max(depths, default=0),
+    }]