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

code_review_graph/graph_diff.py

@@ -0,0 +1,122 @@
+"""Graph snapshot diffing -- compare graph state over time."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from .graph import GraphStore
+
+logger = logging.getLogger(__name__)
+
+
+def take_snapshot(store: GraphStore) -> dict[str, Any]:
+    """Take a snapshot of the current graph state.
+
+    Returns a dict with node and edge counts, qualified names,
+    and community assignments for later diffing.
+    """
+    stats = store.get_stats()
+    nodes = store.get_all_nodes(exclude_files=False)
+    community_map = store.get_all_community_ids()
+
+    return {
+        "node_count": stats.total_nodes,
+        "edge_count": stats.total_edges,
+        "nodes": {
+            n.qualified_name: {
+                "kind": n.kind,
+                "file": n.file_path,
+                "community_id": community_map.get(
+                    n.qualified_name
+                ),
+            }
+            for n in nodes
+        },
+        "edges": {
+            f"{e.source_qualified}->"
+            f"{e.target_qualified}:{e.kind}"
+            for e in store.get_all_edges()
+        },
+    }
+
+
+def save_snapshot(snapshot: dict, path: Path) -> None:
+    """Save a snapshot to a JSON file."""
+    data = dict(snapshot)
+    if isinstance(data.get("edges"), set):
+        data["edges"] = sorted(data["edges"])
+    path.write_text(
+        json.dumps(data, indent=2), encoding="utf-8"
+    )
+
+
+def load_snapshot(path: Path) -> dict:
+    """Load a snapshot from a JSON file."""
+    data = json.loads(path.read_text(encoding="utf-8"))
+    if isinstance(data.get("edges"), list):
+        data["edges"] = set(data["edges"])
+    return data
+
+
+def diff_snapshots(
+    before: dict, after: dict,
+) -> dict[str, Any]:
+    """Compare two graph snapshots.
+
+    Returns:
+        Dict with new_nodes, removed_nodes, new_edges,
+        removed_edges, community_changes, and summary
+        statistics.
+    """
+    before_nodes = set(before.get("nodes", {}).keys())
+    after_nodes = set(after.get("nodes", {}).keys())
+    before_edges = before.get("edges", set())
+    after_edges = after.get("edges", set())
+
+    new_nodes = after_nodes - before_nodes
+    removed_nodes = before_nodes - after_nodes
+    new_edges = after_edges - before_edges
+    removed_edges = before_edges - after_edges
+
+    # Community changes for nodes that exist in both
+    community_changes = []
+    for qn in before_nodes & after_nodes:
+        before_cid = before["nodes"][qn].get(
+            "community_id"
+        )
+        after_cid = after["nodes"][qn].get(
+            "community_id"
+        )
+        if before_cid != after_cid:
+            community_changes.append({
+                "node": qn,
+                "before_community": before_cid,
+                "after_community": after_cid,
+            })
+
+    return {
+        "new_nodes": [
+            {"qualified_name": qn, **after["nodes"][qn]}
+            for qn in sorted(new_nodes)
+        ][:100],
+        "removed_nodes": sorted(removed_nodes)[:100],
+        "new_edges": sorted(new_edges)[:100],
+        "removed_edges": sorted(removed_edges)[:100],
+        "community_changes": community_changes[:50],
+        "summary": {
+            "nodes_added": len(new_nodes),
+            "nodes_removed": len(removed_nodes),
+            "edges_added": len(new_edges),
+            "edges_removed": len(removed_edges),
+            "community_moves": len(community_changes),
+            "before_total": before.get(
+                "node_count", 0
+            ),
+            "after_total": after.get(
+                "node_count", 0
+            ),
+        },
+    }

code_review_graph/hints.py

@@ -0,0 +1,384 @@
+"""Context-aware hints system for MCP tool responses.
+
+Tracks session state (in-memory only) and generates intelligent
+next-step suggestions after each tool call.  Hints are appended as
+``_hints`` to new tool responses so that Claude Code can propose
+follow-up actions without the user having to discover them.
+"""
+
+from __future__ import annotations
+
+import time
+from collections import deque
+from typing import Any
+
+# ---- intent categories and their characteristic tool names ----
+
+_INTENT_TOOLS: dict[str, set[str]] = {
+    "reviewing": {
+        "detect_changes", "get_review_context", "get_affected_flows", "get_impact_radius",
+    },
+    "debugging": {
+        "query_graph", "get_flow", "semantic_search_nodes",
+    },
+    "refactoring": {
+        "refactor", "find_dead_code", "suggest_refactorings",
+    },
+    "exploring": {
+        "list_communities", "get_architecture_overview", "list_flows", "list_graph_stats",
+    },
+}
+
+# ---- workflow adjacency: for each tool, which tools are useful next ----
+
+_WORKFLOW: dict[str, list[dict[str, str]]] = {
+    "list_flows": [
+        {
+            "tool": "get_flow",
+            "suggestion": "Drill into a specific flow for step-by-step details",
+        },
+        {
+            "tool": "get_affected_flows",
+            "suggestion": "Check which flows are affected by recent changes",
+        },
+        {
+            "tool": "get_architecture_overview",
+            "suggestion": "See the high-level architecture",
+        },
+    ],
+    "get_flow": [
+        {
+            "tool": "query_graph",
+            "suggestion": "Inspect callers/callees of a step in this flow",
+        },
+        {
+            "tool": "get_affected_flows",
+            "suggestion": "Check if changes affect this flow",
+        },
+        {
+            "tool": "list_flows",
+            "suggestion": "Browse other execution flows",
+        },
+    ],
+    "get_affected_flows": [
+        {
+            "tool": "detect_changes",
+            "suggestion": "Get risk-scored change analysis",
+        },
+        {
+            "tool": "get_flow",
+            "suggestion": "Inspect a specific affected flow",
+        },
+        {
+            "tool": "get_review_context",
+            "suggestion": "Build a full review context for the changes",
+        },
+    ],
+    "list_communities": [
+        {
+            "tool": "get_community",
+            "suggestion": "Inspect a specific community's members",
+        },
+        {
+            "tool": "get_architecture_overview",
+            "suggestion": "See cross-community coupling and warnings",
+        },
+        {
+            "tool": "list_flows",
+            "suggestion": "See execution flows across communities",
+        },
+    ],
+    "get_community": [
+        {
+            "tool": "query_graph",
+            "suggestion": "Explore callers/callees of community members",
+        },
+        {
+            "tool": "list_communities",
+            "suggestion": "Browse other communities",
+        },
+        {
+            "tool": "get_architecture_overview",
+            "suggestion": "See how this community fits the architecture",
+        },
+    ],
+    "get_architecture_overview": [
+        {
+            "tool": "list_communities",
+            "suggestion": "Drill into individual communities",
+        },
+        {
+            "tool": "detect_changes",
+            "suggestion": "See how recent changes affect the architecture",
+        },
+        {
+            "tool": "list_flows",
+            "suggestion": "Explore execution flows",
+        },
+    ],
+    "detect_changes": [
+        {
+            "tool": "get_review_context",
+            "suggestion": "Build a full review context with source snippets",
+        },
+        {
+            "tool": "get_affected_flows",
+            "suggestion": "See which execution flows are affected",
+        },
+        {
+            "tool": "get_impact_radius",
+            "suggestion": "Expand the blast radius analysis",
+        },
+        {
+            "tool": "refactor",
+            "suggestion": "Look for refactoring opportunities in changed code",
+        },
+    ],
+    "refactor": [
+        {
+            "tool": "query_graph",
+            "suggestion": "Verify call sites before applying a rename",
+        },
+        {
+            "tool": "detect_changes",
+            "suggestion": "Check risk of the refactored code",
+        },
+        {
+            "tool": "semantic_search_nodes",
+            "suggestion": "Find related symbols to also rename",
+        },
+    ],
+    "semantic_search_nodes": [
+        {
+            "tool": "query_graph",
+            "suggestion": "Inspect callers/callees of a search result",
+        },
+        {
+            "tool": "get_flow",
+            "suggestion": "See the execution flow through a matched node",
+        },
+        {
+            "tool": "get_impact_radius",
+            "suggestion": "Check the blast radius from matched nodes",
+        },
+    ],
+}
+
+# Maximum items per hints category returned to the caller.
+_MAX_PER_CATEGORY = 3
+
+# Session history caps.
+_MAX_TOOLS_HISTORY = 100
+_MAX_NODES_TRACKED = 1000
+
+
+# ---------------------------------------------------------------------------
+# SessionState
+# ---------------------------------------------------------------------------
+
+
+class SessionState:
+    """In-memory session state for a single MCP connection."""
+
+    def __init__(self) -> None:
+        self.tools_called: deque[str] = deque(maxlen=_MAX_TOOLS_HISTORY)
+        self.nodes_queried: set[str] = set()
+        self.files_touched: set[str] = set()
+        self.inferred_intent: str | None = None
+        self.last_tool_time: float = 0.0
+
+    def record_tool_call(self, tool_name: str) -> None:
+        """Record a tool invocation (FIFO, capped at 100)."""
+        self.tools_called.append(tool_name)
+        self.last_tool_time = time.time()
+
+    def record_nodes(self, node_ids: list[str]) -> None:
+        """Record queried node identifiers (capped at 1000)."""
+        for nid in node_ids:
+            if len(self.nodes_queried) >= _MAX_NODES_TRACKED:
+                break
+            self.nodes_queried.add(nid)
+
+    def record_files(self, files: list[str]) -> None:
+        """Record touched file paths."""
+        self.files_touched.update(files)
+
+
+# ---------------------------------------------------------------------------
+# Intent inference
+# ---------------------------------------------------------------------------
+
+
+def infer_intent(session: SessionState) -> str:
+    """Classify the user's likely intent from their tool-call history.
+
+    Returns one of: ``"reviewing"``, ``"debugging"``, ``"refactoring"``,
+    ``"exploring"`` (default).
+    """
+    if not session.tools_called:
+        return "exploring"
+
+    # Score each intent by how many of the last N calls match its tools.
+    recent = list(session.tools_called)[-10:]
+    scores: dict[str, int] = {intent: 0 for intent in _INTENT_TOOLS}
+    for tool in recent:
+        for intent, tools in _INTENT_TOOLS.items():
+            if tool in tools:
+                scores[intent] += 1
+
+    best = max(scores, key=lambda k: scores[k])
+    if scores[best] == 0:
+        return "exploring"
+    return best
+
+
+# ---------------------------------------------------------------------------
+# Hints generation
+# ---------------------------------------------------------------------------
+
+
+def generate_hints(
+    tool_name: str,
+    result: dict[str, Any],
+    session: SessionState,
+) -> dict[str, Any]:
+    """Build context-aware hints for a tool response.
+
+    Returns::
+
+        {
+            "next_steps": [{"tool": ..., "suggestion": ...}, ...],
+            "related": [...],
+            "warnings": [...],
+        }
+
+    At most ``_MAX_PER_CATEGORY`` items per list.  Tools already called
+    in this session are suppressed from ``next_steps``.
+    """
+    # Update session state.
+    session.record_tool_call(tool_name)
+    session.inferred_intent = infer_intent(session)
+
+    next_steps = _build_next_steps(tool_name, session)
+    warnings = _extract_warnings(result)
+    # Build related BEFORE tracking, so that the current result's files
+    # are not yet in files_touched and can appear as suggestions.
+    related = _build_related(tool_name, result, session)
+
+    # Collect files/nodes from result for session tracking.
+    _track_result(result, session)
+
+    return {
+        "next_steps": next_steps[:_MAX_PER_CATEGORY],
+        "related": related[:_MAX_PER_CATEGORY],
+        "warnings": warnings[:_MAX_PER_CATEGORY],
+    }
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _track_result(result: dict[str, Any], session: SessionState) -> None:
+    """Extract node IDs and file paths from a tool result and record them."""
+    # Files
+    for key in ("changed_files", "impacted_files"):
+        files = result.get(key)
+        if isinstance(files, list):
+            session.record_files([f for f in files if isinstance(f, str)])
+
+    # Nodes — look in common result shapes
+    node_ids: list[str] = []
+    for key in ("results", "changed_nodes", "impacted_nodes"):
+        items = result.get(key)
+        if isinstance(items, list):
+            for item in items:
+                if isinstance(item, dict):
+                    qn = item.get("qualified_name")
+                    if qn:
+                        node_ids.append(qn)
+    if node_ids:
+        session.record_nodes(node_ids)
+
+
+def _build_next_steps(
+    tool_name: str, session: SessionState
+) -> list[dict[str, str]]:
+    """Return next-step suggestions, filtering already-called tools."""
+    called = set(session.tools_called)
+    candidates = _WORKFLOW.get(tool_name, [])
+    out: list[dict[str, str]] = []
+    for c in candidates:
+        if c["tool"] not in called:
+            out.append(c)
+    return out
+
+
+def _extract_warnings(result: dict[str, Any]) -> list[str]:
+    """Pull warning signals from a tool result."""
+    warnings: list[str] = []
+
+    # Test gaps
+    test_gaps = result.get("test_gaps")
+    if isinstance(test_gaps, list) and test_gaps:
+        names = [g.get("name", g) if isinstance(g, dict) else str(g) for g in test_gaps[:5]]
+        warnings.append(
+            f"Test coverage gaps: {', '.join(names)}"
+        )
+
+    # High risk score
+    risk = result.get("risk_score")
+    if isinstance(risk, (int, float)) and risk > 0.7:
+        warnings.append(f"High risk score ({risk:.2f}) — review carefully")
+
+    # Coupling warnings from architecture overview
+    arch_warnings = result.get("warnings")
+    if isinstance(arch_warnings, list):
+        for w in arch_warnings[:3]:
+            if isinstance(w, str):
+                warnings.append(w)
+            elif isinstance(w, dict) and "message" in w:
+                warnings.append(w["message"])
+
+    return warnings
+
+
+def _build_related(
+    tool_name: str,
+    result: dict[str, Any],
+    session: SessionState,
+) -> list[str]:
+    """Suggest related node/file identifiers from the result."""
+    related: list[str] = []
+    seen: set[str] = set()
+
+    # Suggest impacted files the user hasn't touched yet
+    impacted = result.get("impacted_files")
+    if isinstance(impacted, list):
+        for f in impacted:
+            if isinstance(f, str) and f not in session.files_touched and f not in seen:
+                related.append(f)
+                seen.add(f)
+                if len(related) >= _MAX_PER_CATEGORY:
+                    break
+
+    return related
+
+
+# ---------------------------------------------------------------------------
+# Module-level session singleton
+# ---------------------------------------------------------------------------
+
+_session = SessionState()
+
+
+def get_session() -> SessionState:
+    """Return the global in-memory session state."""
+    return _session
+
+
+def reset_session() -> None:
+    """Reset the global session (useful for testing)."""
+    global _session
+    _session = SessionState()