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

code_review_graph/tools/_common.py

@@ -0,0 +1,176 @@
+"""Shared utilities for tool sub-modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..graph import GraphStore
+from ..incremental import find_project_root, get_db_path
+
+
+def _error_response(
+    message: str, status: str = "error", **extra: Any,
+) -> dict[str, Any]:
+    """Build a standardised error response dict."""
+    return {"status": status, "error": message, "summary": message, **extra}
+
+# Common JS/TS builtin method names filtered from callers_of results.
+# "Who calls .map()?" returns hundreds of hits and is never useful.
+# These are kept in the graph (callees_of still shows them) but excluded
+# when doing reverse call tracing to reduce noise.
+_BUILTIN_CALL_NAMES: set[str] = {
+    "map", "filter", "reduce", "reduceRight", "forEach", "find", "findIndex",
+    "some", "every", "includes", "indexOf", "lastIndexOf",
+    "push", "pop", "shift", "unshift", "splice", "slice",
+    "concat", "join", "flat", "flatMap", "sort", "reverse", "fill",
+    "keys", "values", "entries", "from", "isArray", "of", "at",
+    "trim", "trimStart", "trimEnd", "split", "replace", "replaceAll",
+    "match", "matchAll", "search", "substring", "substr",
+    "toLowerCase", "toUpperCase", "startsWith", "endsWith",
+    "padStart", "padEnd", "repeat", "charAt", "charCodeAt",
+    "assign", "freeze", "defineProperty", "getOwnPropertyNames",
+    "hasOwnProperty", "create", "is", "fromEntries",
+    "log", "warn", "error", "info", "debug", "trace", "dir", "table",
+    "time", "timeEnd", "assert", "clear", "count",
+    "then", "catch", "finally", "resolve", "reject", "all", "allSettled", "race", "any",
+    "parse", "stringify",
+    "floor", "ceil", "round", "random", "max", "min", "abs", "pow", "sqrt",
+    "addEventListener", "removeEventListener", "querySelector", "querySelectorAll",
+    "getElementById", "createElement", "appendChild", "removeChild",
+    "setAttribute", "getAttribute", "preventDefault", "stopPropagation",
+    "setTimeout", "clearTimeout", "setInterval", "clearInterval",
+    "toString", "valueOf", "toJSON", "toISOString",
+    "getTime", "getFullYear", "now",
+    "isNaN", "parseInt", "parseFloat", "toFixed",
+    "encodeURIComponent", "decodeURIComponent",
+    "call", "apply", "bind", "next",
+    "emit", "on", "off", "once",
+    "pipe", "write", "read", "end", "close", "destroy",
+    "send", "status", "json", "redirect",
+    "set", "get", "delete", "has",
+    "findUnique", "findFirst", "findMany", "createMany",
+    "update", "updateMany", "deleteMany", "upsert",
+    "aggregate", "groupBy", "transaction",
+    "describe", "it", "test", "expect", "beforeEach", "afterEach",
+    "beforeAll", "afterAll", "mock", "spyOn",
+    "require", "fetch",
+}
+
+
+def _validate_repo_root(path: "Path | str") -> Path:
+    """Validate that a path is a plausible project root.
+
+    Ensures the path is an existing directory that contains a ``.git``,
+    ``.svn``, or ``.code-review-graph`` directory, preventing arbitrary
+    file-system traversal via the ``repo_root`` parameter.
+    """
+    resolved = Path(path).resolve()
+    if not resolved.is_dir():
+        raise ValueError(
+            f"repo_root is not an existing directory: {resolved}"
+        )
+    has_vcs = (
+        (resolved / ".git").exists()
+        or (resolved / ".svn").exists()
+        or (resolved / ".code-review-graph").exists()
+    )
+    if not has_vcs:
+        raise ValueError(
+            f"repo_root does not look like a project root "
+            f"(no .git, .svn, or .code-review-graph directory found): "
+            f"{resolved}"
+        )
+    return resolved
+
+
+def _resolve_root(repo_root: str | None = None) -> Path:
+    """Resolve and validate the repository root without opening a store."""
+    return _validate_repo_root(Path(repo_root)) if repo_root else find_project_root()
+
+
+def _get_store(repo_root: str | None = None) -> tuple[GraphStore, Path]:
+    """Resolve repo root and open the graph store.
+
+    Callers own the returned store and must close it (try/finally or
+    context manager) to avoid leaking SQLite file descriptors.
+    """
+    root = _resolve_root(repo_root)
+    db_path = get_db_path(root)
+    return GraphStore(db_path), root
+
+
+def _resolve_graph_file_paths(
+    store: GraphStore, root: Path, file_paths: list[str],
+) -> list[str]:
+    """Resolve user-facing file paths to the paths stored in the graph.
+
+    Graphs may contain absolute paths, repo-relative paths, or cwd-relative
+    paths depending on how they were built. Tool inputs are usually relative to
+    repo root, so exact matching alone can miss existing graph nodes.
+    """
+    resolved: list[str] = []
+    seen: set[str] = set()
+
+    def add(path: str) -> None:
+        if path not in seen:
+            resolved.append(path)
+            seen.add(path)
+
+    for file_path in file_paths:
+        raw = file_path.replace("\\", "/")
+        candidates = [raw]
+        path = Path(file_path)
+        if path.is_absolute():
+            try:
+                candidates.append(str(path.resolve().relative_to(root)).replace("\\", "/"))
+            except ValueError:
+                pass
+        else:
+            candidates.append(str(root / path))
+
+        for candidate in candidates:
+            if store.get_nodes_by_file(candidate):
+                add(candidate)
+
+        suffixes = []
+        for candidate in candidates:
+            normalized = candidate.replace("\\", "/")
+            if normalized not in suffixes:
+                suffixes.append(normalized)
+
+        for suffix in suffixes:
+            for matched_path in store.get_files_matching(suffix):
+                add(matched_path)
+
+    return resolved
+
+
+def compact_response(
+    summary: str,
+    key_entities: list[str] | None = None,
+    risk: str = "unknown",
+    communities: list[str] | None = None,
+    flows_affected: list[str] | None = None,
+    next_tool_suggestions: list[str] | None = None,
+    data: dict[str, Any] | None = None,
+    detail_level: str = "minimal",
+) -> dict[str, Any]:
+    """Standard compact response format for token efficiency."""
+    resp: dict[str, Any] = {
+        "status": "ok",
+        "summary": summary,
+    }
+    if key_entities:
+        resp["key_entities"] = key_entities[:10]
+    if risk != "unknown":
+        resp["risk"] = risk
+    if communities:
+        resp["communities"] = communities[:5]
+    if flows_affected:
+        resp["flows_affected"] = flows_affected[:5]
+    if next_tool_suggestions:
+        resp["next_tool_suggestions"] = next_tool_suggestions[:3]
+    if detail_level != "minimal" and data:
+        resp["data"] = data
+    return resp

code_review_graph/tools/analysis_tools.py

@@ -0,0 +1,184 @@
+"""MCP tool wrappers for graph analysis features."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..analysis import (
+    find_bridge_nodes,
+    find_hub_nodes,
+    find_knowledge_gaps,
+    find_surprising_connections,
+    generate_suggested_questions,
+)
+from ._common import _get_store
+
+
+def get_hub_nodes_func(
+    repo_root: str | None = None,
+    top_n: int = 10,
+) -> dict[str, Any]:
+    """Find the most connected nodes in the codebase graph.
+
+    Hub nodes have the highest total degree (in + out edges).
+    These are architectural hotspots -- changes to them have
+    disproportionate blast radius.
+
+    Args:
+        repo_root: Repository root (auto-detected if omitted).
+        top_n: Number of top hubs to return (default 10).
+    """
+    store, _root = _get_store(repo_root or None)
+    try:
+        hubs = find_hub_nodes(store, top_n=top_n)
+        return {
+            "hub_nodes": hubs,
+            "count": len(hubs),
+            "next_tool_suggestions": [
+                "get_impact_radius -- check blast radius of a hub",
+                "query_graph callers_of -- see what calls a hub",
+                "get_bridge_nodes -- find architectural chokepoints",
+            ],
+        }
+    finally:
+        store.close()
+
+
+def get_bridge_nodes_func(
+    repo_root: str | None = None,
+    top_n: int = 10,
+) -> dict[str, Any]:
+    """Find architectural chokepoints via betweenness centrality.
+
+    Bridge nodes sit on the shortest paths between many node
+    pairs. If they break, multiple code regions lose
+    connectivity.
+
+    Args:
+        repo_root: Repository root (auto-detected if omitted).
+        top_n: Number of top bridges to return (default 10).
+    """
+    store, _root = _get_store(repo_root or None)
+    try:
+        bridges = find_bridge_nodes(store, top_n=top_n)
+        return {
+            "bridge_nodes": bridges,
+            "count": len(bridges),
+            "next_tool_suggestions": [
+                "get_hub_nodes -- find most connected nodes",
+                "get_impact_radius -- check blast radius",
+                "detect_changes -- see if bridges are affected",
+            ],
+        }
+    finally:
+        store.close()
+
+
+def get_knowledge_gaps_func(
+    repo_root: str | None = None,
+) -> dict[str, Any]:
+    """Identify structural weaknesses in the codebase.
+
+    Finds: isolated nodes (disconnected), thin communities
+    (< 3 members), untested hotspots (high-degree, no tests),
+    and single-file communities.
+
+    Args:
+        repo_root: Repository root (auto-detected if omitted).
+    """
+    store, _root = _get_store(repo_root or None)
+    try:
+        gaps = find_knowledge_gaps(store)
+        total = sum(len(v) for v in gaps.values())
+        return {
+            "gaps": gaps,
+            "total_gaps": total,
+            "summary": {
+                "isolated_nodes": len(gaps["isolated_nodes"]),
+                "thin_communities": len(
+                    gaps["thin_communities"]
+                ),
+                "untested_hotspots": len(
+                    gaps["untested_hotspots"]
+                ),
+                "single_file_communities": len(
+                    gaps["single_file_communities"]
+                ),
+            },
+            "next_tool_suggestions": [
+                "refactor dead_code -- find unused symbols",
+                "get_hub_nodes -- find high-impact nodes",
+                "get_suggested_questions -- review prompts",
+            ],
+        }
+    finally:
+        store.close()
+
+
+def get_surprising_connections_func(
+    repo_root: str | None = None,
+    top_n: int = 15,
+) -> dict[str, Any]:
+    """Find unexpected architectural coupling in the codebase.
+
+    Scores edges by surprise factors: cross-community,
+    cross-language, peripheral-to-hub, cross-test-boundary.
+
+    Args:
+        repo_root: Repository root (auto-detected if omitted).
+        top_n: Number of top surprises to return (default 15).
+    """
+    store, _root = _get_store(repo_root or None)
+    try:
+        surprises = find_surprising_connections(
+            store, top_n=top_n
+        )
+        return {
+            "surprising_connections": surprises,
+            "count": len(surprises),
+            "next_tool_suggestions": [
+                "get_architecture_overview -- community structure",
+                "query_graph callers_of -- trace the coupling",
+                "get_bridge_nodes -- find chokepoints",
+            ],
+        }
+    finally:
+        store.close()
+
+
+def get_suggested_questions_func(
+    repo_root: str | None = None,
+) -> dict[str, Any]:
+    """Auto-generate review questions from graph analysis.
+
+    Produces questions about: bridge nodes, untested hubs,
+    surprising connections, thin communities, and untested
+    hotspots.
+
+    Args:
+        repo_root: Repository root (auto-detected if omitted).
+    """
+    store, _root = _get_store(repo_root or None)
+    try:
+        questions = generate_suggested_questions(store)
+        by_priority: dict[str, list[dict[str, Any]]] = {
+            "high": [], "medium": [], "low": [],
+        }
+        for q in questions:
+            prio = q.get("priority", "medium")
+            if prio in by_priority:
+                by_priority[prio].append(q)
+        return {
+            "questions": questions,
+            "count": len(questions),
+            "by_priority": {
+                k: len(v) for k, v in by_priority.items()
+            },
+            "next_tool_suggestions": [
+                "get_knowledge_gaps -- structural weaknesses",
+                "detect_changes -- risk-scored review",
+                "get_architecture_overview -- community map",
+            ],
+        }
+    finally:
+        store.close()