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

code_review_graph/tools/community_tools.py

@@ -0,0 +1,246 @@
+"""Tools 13, 14, 15: community listing, detail, architecture overview."""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+from ..communities import get_architecture_overview, get_communities
+from ..context_savings import attach_context_savings
+from ..graph import node_to_dict
+from ..hints import generate_hints, get_session
+from ._common import _get_store
+
+# ---------------------------------------------------------------------------
+# Tool 13: list_communities  [EXPLORE]
+# ---------------------------------------------------------------------------
+
+
+def list_communities_func(
+    repo_root: str | None = None,
+    sort_by: str = "size",
+    min_size: int = 0,
+    detail_level: str = "standard",
+) -> dict[str, Any]:
+    """List detected code communities in the codebase.
+
+    [EXPLORE] Retrieves stored communities from the knowledge graph.
+    Each community represents a cluster of related code entities
+    (functions, classes) detected via the Leiden algorithm or
+    file-based grouping.
+
+    Args:
+        repo_root: Repository root path. Auto-detected if omitted.
+        sort_by: Sort column: size, cohesion, or name.
+        min_size: Minimum community size to include (default: 0).
+        detail_level: "standard" (default) returns full community data;
+                      "minimal" returns only name, size, and cohesion
+                      per community.
+
+    Returns:
+        List of communities with size and cohesion scores.
+    """
+    store, root = _get_store(repo_root)
+    try:
+        communities = get_communities(
+            store, sort_by=sort_by, min_size=min_size
+        )
+        if detail_level == "minimal":
+            communities = [
+                {"name": c["name"], "size": c["size"], "cohesion": c["cohesion"]}
+                for c in communities
+            ]
+        result: dict[str, object] = {
+            "status": "ok",
+            "summary": f"Found {len(communities)} communities",
+            "communities": communities,
+        }
+        result["_hints"] = generate_hints(
+            "list_communities", result, get_session()
+        )
+        return result
+    except Exception as exc:
+        return {"status": "error", "error": str(exc)}
+    finally:
+        store.close()
+
+
+# ---------------------------------------------------------------------------
+# Tool 14: get_community  [EXPLORE]
+# ---------------------------------------------------------------------------
+
+
+def get_community_func(
+    community_name: str | None = None,
+    community_id: int | None = None,
+    include_members: bool = False,
+    repo_root: str | None = None,
+) -> dict[str, Any]:
+    """Get details of a single code community.
+
+    [EXPLORE] Retrieves a community by its database ID or by name match.
+    Optionally includes the full list of member nodes.
+
+    Args:
+        community_name: Name to search for (partial match). Ignored if
+                        community_id given.
+        community_id: Database ID of the community.
+        include_members: If True, include full member node details.
+        repo_root: Repository root path. Auto-detected if omitted.
+
+    Returns:
+        Community details, or not_found status.
+    """
+    store, root = _get_store(repo_root)
+    try:
+        community: dict | None = None
+        all_communities = get_communities(store)
+
+        if community_id is not None:
+            for c in all_communities:
+                if c.get("id") == community_id:
+                    community = c
+                    break
+        elif community_name is not None:
+            for c in all_communities:
+                if community_name.lower() in c["name"].lower():
+                    community = c
+                    break
+
+        if community is None:
+            return {
+                "status": "not_found",
+                "summary": (
+                    "No community found matching the given criteria."
+                ),
+            }
+
+        if include_members:
+            cid = community.get("id")
+            if cid is not None:
+                member_nodes = store.get_nodes_by_community_id(cid)
+                members = [node_to_dict(n) for n in member_nodes]
+                community["member_details"] = members
+
+        result = {
+            "status": "ok",
+            "summary": (
+                f"Community '{community['name']}': "
+                f"{community['size']} nodes, "
+                f"cohesion {community['cohesion']:.4f}"
+            ),
+            "community": community,
+        }
+        result["_hints"] = generate_hints(
+            "get_community", result, get_session()
+        )
+        return result
+    except Exception as exc:
+        return {"status": "error", "error": str(exc)}
+    finally:
+        store.close()
+
+
+# ---------------------------------------------------------------------------
+# Tool 15: get_architecture_overview  [EXPLORE]
+# ---------------------------------------------------------------------------
+
+
+_MINIMAL_COMMUNITY_FIELDS = ("id", "name", "size", "cohesion", "dominant_language")
+
+
+def _minimal_overview(overview: dict[str, Any]) -> dict[str, Any]:
+    """Compress overview for ``detail_level="minimal"``.
+
+    The full overview can exceed 600KB on medium repos because it embeds
+    every community's member list and every individual cross-community
+    edge. Minimal mode drops member lists and aggregates the edge list
+    to one row per community pair with a count and the top edge kinds —
+    enough to spot coupling smells without exploding token budgets.
+    """
+    communities = [
+        {k: c[k] for k in _MINIMAL_COMMUNITY_FIELDS if k in c}
+        for c in overview.get("communities", [])
+    ]
+    id_to_name = {c["id"]: c["name"] for c in communities if "id" in c}
+
+    edge_pair_counts: Counter[tuple[int, int]] = Counter()
+    edge_pair_kinds: dict[tuple[int, int], Counter[str]] = {}
+    for e in overview.get("cross_community_edges", []):
+        # Use canonical (low, high) ordering so A↔B and B↔A aggregate together.
+        a, b = e["source_community"], e["target_community"]
+        pair = (a, b) if a <= b else (b, a)
+        edge_pair_counts[pair] += 1
+        edge_pair_kinds.setdefault(pair, Counter())[e["edge_kind"]] += 1
+
+    cross_pairs = [
+        {
+            "source_community": id_to_name.get(a, f"community-{a}"),
+            "target_community": id_to_name.get(b, f"community-{b}"),
+            "edge_count": count,
+            "top_kinds": [k for k, _ in edge_pair_kinds[(a, b)].most_common(3)],
+        }
+        for (a, b), count in edge_pair_counts.most_common()
+    ]
+    return {
+        "communities": communities,
+        "cross_community_edges": cross_pairs,
+        "warnings": overview.get("warnings", []),
+    }
+
+
+def get_architecture_overview_func(
+    repo_root: str | None = None,
+    detail_level: str = "minimal",
+) -> dict[str, Any]:
+    """Generate an architecture overview based on community structure.
+
+    [EXPLORE] Builds a high-level view of the codebase architecture by
+    analyzing community boundaries and cross-community coupling.
+    Includes warnings for high coupling between communities.
+
+    Args:
+        repo_root: Repository root path. Auto-detected if omitted.
+        detail_level: "minimal" (default) drops community member lists
+                      and aggregates edges to one row per community pair
+                      (typical reduction: 600KB -> <5KB);
+                      "standard" returns the full overview including
+                      per-edge cross-community detail.
+
+    Returns:
+        Architecture overview with communities, cross-community edges,
+        and warnings.
+    """
+    store, root = _get_store(repo_root)
+    try:
+        full_overview = get_architecture_overview(store)
+        overview = full_overview
+        if detail_level == "minimal":
+            overview = _minimal_overview(full_overview)
+        n_communities = len(overview["communities"])
+        n_cross = len(overview["cross_community_edges"])
+        n_warnings = len(overview["warnings"])
+        cross_label = (
+            "community pairs"
+            if detail_level == "minimal"
+            else "cross-community edges"
+        )
+        result = {
+            "status": "ok",
+            "summary": (
+                f"Architecture: {n_communities} communities, "
+                f"{n_cross} {cross_label}, "
+                f"{n_warnings} warning(s)"
+            ),
+            **overview,
+        }
+        result["_hints"] = generate_hints(
+            "get_architecture_overview", result, get_session()
+        )
+        if detail_level == "minimal":
+            attach_context_savings(result, original_context=full_overview)
+        return result
+    except Exception as exc:
+        return {"status": "error", "error": str(exc)}
+    finally:
+        store.close()

code_review_graph/tools/context.py

@@ -0,0 +1,152 @@
+"""Tool: get_minimal_context — ultra-compact context for token-efficient workflows."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ._common import _get_store, compact_response
+
+logger = logging.getLogger(__name__)
+
+
+def _has_git_changes(root: Path, base: str) -> bool:
+    """Quick check for uncommitted or diffed changes."""
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", base, "--"],
+            capture_output=True, stdin=subprocess.DEVNULL, text=True,
+            cwd=str(root), timeout=10,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return True
+        # Also check staged/unstaged
+        result2 = subprocess.run(
+            ["git", "status", "--porcelain"],
+            capture_output=True, stdin=subprocess.DEVNULL, text=True,
+            cwd=str(root), timeout=10,
+        )
+        return bool(result2.stdout.strip())
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def get_minimal_context(
+    task: str = "",
+    changed_files: list[str] | None = None,
+    repo_root: str | None = None,
+    base: str = "HEAD~1",
+) -> dict[str, Any]:
+    """Return minimum context an agent needs to start any task (~100 tokens).
+
+    Combines graph stats, top communities, top flows, risk score,
+    and suggested next tools into an ultra-compact response.
+
+    Args:
+        task: Natural language description of what the agent is doing
+              (e.g. "review PR #42", "debug login timeout").
+        changed_files: Explicit changed files. Auto-detected from git if None.
+        repo_root: Repository root path. Auto-detected if None.
+        base: Git ref for diff comparison.
+    """
+    store, root = _get_store(repo_root)
+    try:
+        # 1. Quick stats
+        stats = store.get_stats()
+
+        # 2. Risk from changed files
+        risk = "unknown"
+        risk_score = 0.0
+        top_affected: list[str] = []
+        test_gap_count = 0
+        if changed_files or _has_git_changes(root, base):
+            try:
+                from ..changes import analyze_changes
+                from ..incremental import get_changed_files as _get_changed
+
+                files = changed_files
+                if not files:
+                    files = _get_changed(root, base)
+                if files:
+                    abs_files = [str(root / f) for f in files]
+                    analysis = analyze_changes(
+                        store, abs_files, repo_root=str(root), base=base,
+                    )
+                    risk_score = analysis.get("risk_score", 0.0)
+                    risk = (
+                        "high" if risk_score > 0.7
+                        else "medium" if risk_score > 0.4
+                        else "low"
+                    )
+                    top_affected = [
+                        f.get("name", "")
+                        for f in analysis.get("changed_functions", [])[:5]
+                    ]
+                    test_gap_count = len(analysis.get("test_gaps", []))
+            except (
+                ImportError, OSError, ValueError,
+                sqlite3.Error, subprocess.SubprocessError,
+            ):
+                logger.debug("Risk analysis failed in get_minimal_context", exc_info=True)
+
+        # 3. Top 3 communities
+        communities: list[str] = []
+        try:
+            rows = store._conn.execute(
+                "SELECT name FROM communities ORDER BY size DESC LIMIT 3"
+            ).fetchall()
+            communities = [r[0] for r in rows]
+        except sqlite3.OperationalError:  # nosec B110 — table may not exist yet
+            logger.debug("communities table not yet populated")
+
+        # 4. Top 3 critical flows
+        flows: list[str] = []
+        try:
+            rows = store._conn.execute(
+                "SELECT name FROM flows ORDER BY criticality DESC LIMIT 3"
+            ).fetchall()
+            flows = [r[0] for r in rows]
+        except sqlite3.OperationalError:  # nosec B110 — table may not exist yet
+            logger.debug("flows table not yet populated")
+
+        # 5. Suggest next tools based on task keywords
+        task_lower = task.lower()
+        if any(w in task_lower for w in ("review", "pr", "merge", "diff")):
+            suggestions = ["detect_changes", "get_affected_flows", "get_review_context"]
+        elif any(w in task_lower for w in ("debug", "bug", "error", "fix")):
+            suggestions = ["semantic_search_nodes", "query_graph", "get_flow"]
+        elif any(w in task_lower for w in ("refactor", "rename", "dead", "clean")):
+            suggestions = ["refactor", "find_large_functions", "get_architecture_overview"]
+        elif any(w in task_lower for w in ("onboard", "understand", "explore", "arch")):
+            suggestions = [
+                "get_architecture_overview", "list_communities", "list_flows",
+            ]
+        else:
+            suggestions = [
+                "detect_changes", "semantic_search_nodes",
+                "get_architecture_overview",
+            ]
+
+        # Build summary
+        summary_parts = [
+            f"{stats.total_nodes} nodes, {stats.total_edges} edges"
+            f" across {stats.files_count} files.",
+        ]
+        if risk != "unknown":
+            summary_parts.append(f"Risk: {risk} ({risk_score:.2f}).")
+        if test_gap_count:
+            summary_parts.append(f"{test_gap_count} test gaps.")
+
+        return compact_response(
+            summary=" ".join(summary_parts),
+            key_entities=top_affected or None,
+            risk=risk,
+            communities=communities or None,
+            flows_affected=flows or None,
+            next_tool_suggestions=suggestions,
+        )
+    finally:
+        store.close()

code_review_graph/tools/docs.py

@@ -0,0 +1,274 @@
+"""Tools 7, 8, 19, 20: embed_graph, get_docs_section, wiki tools."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from ..embeddings import EmbeddingStore, embed_all_nodes
+from ..incremental import find_project_root, get_db_path
+from ._common import _get_store, _resolve_root, _validate_repo_root
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Tool 7: embed_graph
+# ---------------------------------------------------------------------------
+
+
+def embed_graph(
+    repo_root: str | None = None,
+    model: str | None = None,
+    provider: str | None = None,
+) -> dict[str, Any]:
+    """Compute vector embeddings for all graph nodes to enable semantic search.
+
+    Requires: ``pip install code-review-graph[embeddings]`` (local provider only;
+    cloud providers like ``openai`` / ``google`` / ``minimax`` use stdlib ``urllib``).
+    Default model: all-MiniLM-L6-v2. Override via ``model`` param or
+    CRG_EMBEDDING_MODEL env var.
+    Changing the model or provider re-embeds all nodes automatically.
+
+    Only embeds nodes that don't already have up-to-date embeddings.
+
+    Args:
+        repo_root: Repository root path. Auto-detected if omitted.
+        model: Embedding model name. For local: HuggingFace ID or path;
+               for openai: model ID (e.g. ``text-embedding-3-small``);
+               for google: Gemini model ID. Falls back to
+               CRG_EMBEDDING_MODEL / CRG_OPENAI_MODEL env vars as appropriate.
+        provider: Provider name: ``local`` (default), ``openai``, ``google``,
+                  or ``minimax``. ``openai`` requires CRG_OPENAI_BASE_URL +
+                  CRG_OPENAI_API_KEY + CRG_OPENAI_MODEL env vars and accepts
+                  any OpenAI-compatible endpoint (real OpenAI, Azure, new-api,
+                  LiteLLM, vLLM, LocalAI, Ollama openai-mode, etc.).
+
+    Returns:
+        Number of nodes embedded and total embedding count.
+    """
+    store, root = _get_store(repo_root)
+    try:
+        db_path = get_db_path(root)
+        try:
+            emb_store = EmbeddingStore(db_path, provider=provider, model=model)
+        except ValueError as exc:
+            # Unknown provider name or missing provider env vars — surface
+            # as a structured error rather than a traceback.
+            logger.error("embed_graph: %s", exc)
+            return {"status": "error", "error": str(exc)}
+        try:
+            if not emb_store.available:
+                if provider in ("openai", "google", "minimax"):
+                    err = (
+                        f"The '{provider}' embedding provider is not available. "
+                        "Check the required environment variables "
+                        "(see README and `get_provider()` docstring) and that "
+                        "the endpoint is reachable."
+                    )
+                else:
+                    err = (
+                        "The local embedding provider needs sentence-transformers. "
+                        "Install with: pip install code-review-graph[embeddings] — "
+                        "or switch provider to 'openai' / 'google' / 'minimax'."
+                    )
+                return {"status": "error", "error": err}
+
+            newly_embedded = embed_all_nodes(store, emb_store)
+            total = emb_store.count()
+
+            return {
+                "status": "ok",
+                "summary": (
+                    f"Embedded {newly_embedded} new node(s). "
+                    f"Total embeddings: {total}. "
+                    "Semantic search is now active."
+                ),
+                "newly_embedded": newly_embedded,
+                "total_embeddings": total,
+            }
+        finally:
+            emb_store.close()
+    finally:
+        store.close()
+
+
+# ---------------------------------------------------------------------------
+# Tool 8: get_docs_section
+# ---------------------------------------------------------------------------
+
+
+def get_docs_section(
+    section_name: str, repo_root: str | None = None
+) -> dict[str, Any]:
+    """Return a specific section from the LLM-optimized reference.
+
+    Used by skills and Claude Code to load only the exact documentation
+    section needed, keeping token usage minimal (90%+ savings).
+
+    Args:
+        section_name: Exact section name. One of: usage, review-delta,
+                      review-pr, commands, legal, watch, embeddings,
+                      languages, troubleshooting.
+        repo_root: Repository root path. Auto-detected from current
+                   directory if omitted.
+
+    Returns:
+        The section content, or an error if not found.
+    """
+    import re as _re
+
+    search_roots: list[Path] = []
+
+    # Wheel install: docs are packaged inside code_review_graph/docs.
+    in_pkg_docs = (
+        Path(__file__).parent.parent
+        / "docs"
+        / "LLM-OPTIMIZED-REFERENCE.md"
+    )
+    if repo_root:
+        try:
+            search_roots.append(_validate_repo_root(Path(repo_root)))
+        except ValueError:
+            pass
+    elif in_pkg_docs.exists():
+        in_pkg_root = in_pkg_docs.parent.parent
+        search_roots.append(in_pkg_root)
+
+    if not repo_root:
+        project_root = find_project_root()
+        if project_root not in search_roots:
+            search_roots.append(project_root)
+
+    # Editable/source-tree fallback: docs live next to code_review_graph/.
+    pkg_docs = (
+        Path(__file__).parent.parent.parent
+        / "docs"
+        / "LLM-OPTIMIZED-REFERENCE.md"
+    )
+    if pkg_docs.exists():
+        pkg_root = pkg_docs.parent.parent
+        if pkg_root not in search_roots:
+            search_roots.append(pkg_root)
+
+    for search_root in search_roots:
+        candidate = search_root / "docs" / "LLM-OPTIMIZED-REFERENCE.md"
+        if candidate.exists():
+            content = candidate.read_text(encoding="utf-8", errors="replace")
+            match = _re.search(
+                rf'<section name="{_re.escape(section_name)}">'
+                r"(.*?)</section>",
+                content,
+                _re.DOTALL | _re.IGNORECASE,
+            )
+            if match:
+                return {
+                    "status": "ok",
+                    "section": section_name,
+                    "content": match.group(1).strip(),
+                }
+
+    available = [
+        "usage", "review-delta", "review-pr", "commands",
+        "legal", "watch", "embeddings", "languages", "troubleshooting",
+    ]
+    return {
+        "status": "not_found",
+        "error": (
+            f"Section '{section_name}' not found. "
+            f"Available: {', '.join(available)}"
+        ),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Tool 19: generate_wiki  [DOCS]
+# ---------------------------------------------------------------------------
+
+
+def generate_wiki_func(
+    repo_root: str | None = None,
+    force: bool = False,
+) -> dict[str, Any]:
+    """Generate a markdown wiki from the community structure.
+
+    [DOCS] Creates a wiki page for each detected community and an index
+    page. Pages are written to ``.code-review-graph/wiki/`` inside the
+    repository. Only regenerates pages whose content has changed unless
+    force=True.
+
+    Args:
+        repo_root: Repository root path. Auto-detected if omitted.
+        force: If True, regenerate all pages even if content is unchanged.
+
+    Returns:
+        Status with pages_generated, pages_updated, pages_unchanged counts.
+    """
+    from ..incremental import get_data_dir
+    from ..wiki import generate_wiki
+
+    store, root = _get_store(repo_root)
+    try:
+        wiki_dir = get_data_dir(root) / "wiki"
+        result = generate_wiki(store, wiki_dir, force=force)
+        total = (
+            result["pages_generated"]
+            + result["pages_updated"]
+            + result["pages_unchanged"]
+        )
+        return {
+            "status": "ok",
+            "summary": (
+                f"Wiki generated: {result['pages_generated']} new, "
+                f"{result['pages_updated']} updated, "
+                f"{result['pages_unchanged']} unchanged "
+                f"({total} total pages)"
+            ),
+            "wiki_dir": str(wiki_dir),
+            **result,
+        }
+    except Exception as exc:
+        return {"status": "error", "error": str(exc)}
+    finally:
+        store.close()
+
+
+# ---------------------------------------------------------------------------
+# Tool 20: get_wiki_page  [DOCS]
+# ---------------------------------------------------------------------------
+
+
+def get_wiki_page_func(
+    community_name: str,
+    repo_root: str | None = None,
+) -> dict[str, Any]:
+    """Retrieve a specific wiki page by community name.
+
+    [DOCS] Returns the markdown content of the wiki page for the given
+    community. The wiki must have been generated first via generate_wiki.
+
+    Args:
+        community_name: Community name to look up (slugified for filename).
+        repo_root: Repository root path. Auto-detected if omitted.
+
+    Returns:
+        Page content or not_found status.
+    """
+    from ..incremental import get_data_dir
+    from ..wiki import get_wiki_page
+
+    root = _resolve_root(repo_root)
+    wiki_dir = get_data_dir(root) / "wiki"
+    content = get_wiki_page(wiki_dir, community_name)
+    if content is None:
+        return {
+            "status": "not_found",
+            "summary": f"No wiki page found for '{community_name}'.",
+        }
+    return {
+        "status": "ok",
+        "summary": (
+            f"Wiki page for '{community_name}' ({len(content)} chars)"
+        ),
+        "content": content,
+    }