suitable-loop 0.1.0__py3-none-any.whl

suitable_loop/graph/engine.py

@@ -0,0 +1,341 @@
+"""NetworkX-based graph engine for CodeZero.
+
+Builds an in-memory directed graph from the database and exposes
+query methods for callers/callees, dependency trees, blast-radius
+analysis, and centrality reports.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import networkx as nx  # type: ignore[import-untyped]
+
+from suitable_loop.db import Database
+from suitable_loop.models import (
+    ClassEntity,
+    FileEntity,
+    FunctionEntity,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class GraphEngine:
+    """Provides graph-based queries over the indexed codebase."""
+
+    def __init__(self, db: Database) -> None:
+        self.db = db
+        self.graph: nx.DiGraph = nx.DiGraph()
+        self._built = False
+
+    # ------------------------------------------------------------------
+    # Graph construction
+    # ------------------------------------------------------------------
+
+    def build_graph(self, project_root: str) -> None:
+        """Load all entities from the database and build the NetworkX graph.
+
+        Node types: ``"file"``, ``"function"``, ``"class"``.
+        Edge types: ``"contains"`` (file->function/class), ``"calls"``
+        (function->function), ``"imports"`` (file->file).
+        """
+        self.graph.clear()
+
+        files = self.db.get_all_files(project_root)
+        logger.info("Building graph for %d files", len(files))
+
+        for f in files:
+            file_node = f"file:{f.path}"
+            self.graph.add_node(
+                file_node,
+                type="file",
+                path=f.path,
+                entity_id=f.id,
+                line_count=f.line_count,
+                size_bytes=f.size_bytes,
+            )
+
+            # Functions
+            functions = self.db.get_functions_by_file(f.id)  # type: ignore[arg-type]
+            for func in functions:
+                func_node = f"func:{func.qualified_name}"
+                self.graph.add_node(
+                    func_node,
+                    type="function",
+                    name=func.name,
+                    qualified_name=func.qualified_name,
+                    entity_id=func.id,
+                    complexity=func.complexity,
+                    is_method=func.is_method,
+                    is_async=func.is_async,
+                    line_start=func.line_start,
+                    line_end=func.line_end,
+                    signature=func.signature,
+                    docstring=func.docstring,
+                    class_name=func.class_name,
+                )
+                self.graph.add_edge(file_node, func_node, type="contains")
+
+            # Classes
+            classes = self.db.get_classes_by_file(f.id)  # type: ignore[arg-type]
+            for cls in classes:
+                cls_node = f"class:{cls.qualified_name}"
+                self.graph.add_node(
+                    cls_node,
+                    type="class",
+                    name=cls.name,
+                    qualified_name=cls.qualified_name,
+                    entity_id=cls.id,
+                    bases=cls.bases,
+                    line_start=cls.line_start,
+                    line_end=cls.line_end,
+                    docstring=cls.docstring,
+                )
+                self.graph.add_edge(file_node, cls_node, type="contains")
+
+            # Call edges
+            for func in functions:
+                caller_node = f"func:{func.qualified_name}"
+                callees = self.db.get_callees(func.id)  # type: ignore[arg-type]
+                for callee in callees:
+                    callee_node = f"func:{callee.qualified_name}"
+                    self.graph.add_edge(caller_node, callee_node, type="calls")
+
+            # File-level import dependencies
+            deps = self.db.get_file_dependencies(f.id)  # type: ignore[arg-type]
+            for dep in deps:
+                target_node = f"file:{dep.path}"
+                self.graph.add_edge(file_node, target_node, type="imports")
+
+        self._built = True
+        logger.info(
+            "Graph built: %d nodes, %d edges",
+            self.graph.number_of_nodes(),
+            self.graph.number_of_edges(),
+        )
+
+    # ------------------------------------------------------------------
+    # Query methods
+    # ------------------------------------------------------------------
+
+    def get_callers(self, function_name: str) -> list[dict]:
+        """Find all direct callers of *function_name*.
+
+        *function_name* may be a bare name (``my_func``) or a qualified
+        name (``pkg.mod.my_func``).
+        """
+        node = self._find_function_node(function_name)
+        if node is None:
+            return []
+
+        callers: list[dict] = []
+        for pred in self.graph.predecessors(node):
+            edge_data = self.graph.edges[pred, node]
+            if edge_data.get("type") != "calls":
+                continue
+            callers.append(self._node_to_dict(pred))
+        return callers
+
+    def get_callees(self, function_name: str) -> list[dict]:
+        """Find all functions directly called by *function_name*."""
+        node = self._find_function_node(function_name)
+        if node is None:
+            return []
+
+        callees: list[dict] = []
+        for succ in self.graph.successors(node):
+            edge_data = self.graph.edges[node, succ]
+            if edge_data.get("type") != "calls":
+                continue
+            callees.append(self._node_to_dict(succ))
+        return callees
+
+    def dependency_tree(self, file_path: str, depth: int = 3) -> dict:
+        """Return a recursive import-dependency tree rooted at *file_path*.
+
+        Each level is a dict with ``"file"`` and ``"dependencies"`` keys.
+        The tree is bounded by *depth* to avoid runaway recursion.
+        """
+        node = self._find_file_node(file_path)
+        if node is None:
+            return {"file": file_path, "dependencies": [], "error": "file not found"}
+
+        return self._build_dep_tree(node, depth, visited=set())
+
+    def blast_radius(self, file_path: str) -> dict:
+        """Compute the transitive blast radius of changing *file_path*.
+
+        Returns counts and lists of all files and functions that
+        (transitively) depend on this file.
+        """
+        node = self._find_file_node(file_path)
+        if node is None:
+            return {
+                "file": file_path,
+                "error": "file not found",
+                "affected_files": [],
+                "affected_functions": [],
+                "total_affected_files": 0,
+                "total_affected_functions": 0,
+            }
+
+        # Reverse graph: we want nodes that *import* this file, transitively.
+        reverse = self.graph.reverse(copy=False)
+        try:
+            dependents = nx.descendants(reverse, node)
+        except nx.NetworkXError:
+            dependents = set()
+
+        affected_files: list[dict] = []
+        affected_functions: list[dict] = []
+
+        for dep_node in dependents:
+            data = self.graph.nodes[dep_node]
+            if data.get("type") == "file":
+                affected_files.append(self._node_to_dict(dep_node))
+            elif data.get("type") == "function":
+                affected_functions.append(self._node_to_dict(dep_node))
+
+        # Also include functions contained in the file itself.
+        for succ in self.graph.successors(node):
+            edge_data = self.graph.edges[node, succ]
+            if edge_data.get("type") == "contains":
+                data = self.graph.nodes[succ]
+                if data.get("type") == "function":
+                    affected_functions.append(self._node_to_dict(succ))
+
+        return {
+            "file": file_path,
+            "affected_files": affected_files,
+            "affected_functions": affected_functions,
+            "total_affected_files": len(affected_files),
+            "total_affected_functions": len(affected_functions),
+        }
+
+    def get_entity_info(self, name: str) -> dict | None:
+        """Look up any entity (file, function, class) by name.
+
+        Tries qualified name first, then falls back to a substring search
+        across node IDs.
+        """
+        # Direct lookup by known prefixes.
+        for prefix in ("func:", "class:", "file:"):
+            candidate = f"{prefix}{name}"
+            if candidate in self.graph:
+                return self._node_to_dict(candidate)
+
+        # Substring search.
+        for node_id, data in self.graph.nodes(data=True):
+            qname = data.get("qualified_name") or data.get("path") or ""
+            node_name = data.get("name", "")
+            if name == qname or name == node_name:
+                return self._node_to_dict(node_id)
+
+        return None
+
+    def get_most_connected(self, top_n: int = 10) -> list[dict]:
+        """Return the *top_n* nodes with the highest total degree."""
+        if not self.graph:
+            return []
+
+        degree_list = sorted(
+            self.graph.degree(), key=lambda pair: pair[1], reverse=True
+        )
+        results: list[dict] = []
+        for node_id, degree in degree_list[:top_n]:
+            info = self._node_to_dict(node_id)
+            info["degree"] = degree
+            results.append(info)
+        return results
+
+    def get_complexity_report(self, top_n: int = 20) -> list[dict]:
+        """Return the *top_n* most complex functions in the graph."""
+        func_nodes: list[tuple[str, dict[str, Any]]] = []
+        for node_id, data in self.graph.nodes(data=True):
+            if data.get("type") == "function" and data.get("complexity", 0) > 0:
+                func_nodes.append((node_id, data))
+
+        func_nodes.sort(key=lambda pair: pair[1].get("complexity", 0), reverse=True)
+
+        results: list[dict] = []
+        for node_id, data in func_nodes[:top_n]:
+            info = self._node_to_dict(node_id)
+            info["callers"] = len([
+                p for p in self.graph.predecessors(node_id)
+                if self.graph.edges[p, node_id].get("type") == "calls"
+            ])
+            info["callees"] = len([
+                s for s in self.graph.successors(node_id)
+                if self.graph.edges[node_id, s].get("type") == "calls"
+            ])
+            results.append(info)
+        return results
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _find_function_node(self, function_name: str) -> str | None:
+        """Find a function node by qualified or bare name."""
+        candidate = f"func:{function_name}"
+        if candidate in self.graph:
+            return candidate
+
+        # Fall back to searching by bare name or suffix.
+        for node_id, data in self.graph.nodes(data=True):
+            if data.get("type") != "function":
+                continue
+            if data.get("name") == function_name:
+                return node_id
+            qname = data.get("qualified_name", "")
+            if qname.endswith(f".{function_name}"):
+                return node_id
+        return None
+
+    def _find_file_node(self, file_path: str) -> str | None:
+        """Find a file node by path (exact or suffix match)."""
+        candidate = f"file:{file_path}"
+        if candidate in self.graph:
+            return candidate
+
+        # Try suffix matching for relative paths.
+        for node_id, data in self.graph.nodes(data=True):
+            if data.get("type") != "file":
+                continue
+            path = data.get("path", "")
+            if path.endswith(file_path) or file_path.endswith(path):
+                return node_id
+        return None
+
+    def _node_to_dict(self, node_id: str) -> dict:
+        """Convert a graph node to a plain dict for API consumption."""
+        data = dict(self.graph.nodes[node_id])
+        data["node_id"] = node_id
+        return data
+
+    def _build_dep_tree(
+        self, node: str, depth: int, visited: set[str]
+    ) -> dict:
+        """Recursively build a dependency tree dict."""
+        data = self.graph.nodes[node]
+        result: dict[str, Any] = {
+            "file": data.get("path", node),
+            "node_id": node,
+            "dependencies": [],
+        }
+
+        if depth <= 0 or node in visited:
+            return result
+
+        visited.add(node)
+
+        for succ in self.graph.successors(node):
+            edge_data = self.graph.edges[node, succ]
+            if edge_data.get("type") != "imports":
+                continue
+            child = self._build_dep_tree(succ, depth - 1, visited)
+            result["dependencies"].append(child)
+
+        return result

suitable_loop/models.py

@@ -0,0 +1,131 @@
+"""Data models for CodeZero entities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FileEntity:
+    id: int | None = None
+    path: str = ""
+    project_root: str = ""
+    size_bytes: int = 0
+    last_modified: float = 0.0
+    last_indexed: float = 0.0
+    line_count: int = 0
+    hash: str = ""
+
+
+@dataclass
+class FunctionEntity:
+    id: int | None = None
+    file_id: int | None = None
+    name: str = ""
+    qualified_name: str = ""
+    class_name: str | None = None
+    line_start: int = 0
+    line_end: int = 0
+    signature: str = ""
+    docstring: str | None = None
+    complexity: int = 0
+    is_method: bool = False
+    is_async: bool = False
+
+
+@dataclass
+class ClassEntity:
+    id: int | None = None
+    file_id: int | None = None
+    name: str = ""
+    qualified_name: str = ""
+    line_start: int = 0
+    line_end: int = 0
+    bases: list[str] = field(default_factory=list)
+    docstring: str | None = None
+
+
+@dataclass
+class ImportEntity:
+    id: int | None = None
+    file_id: int | None = None
+    module: str = ""
+    alias: str | None = None
+    is_internal: bool = False
+    resolved_file_id: int | None = None
+
+
+@dataclass
+class CallEdge:
+    id: int | None = None
+    caller_id: int | None = None
+    callee_id: int | None = None
+    file_id: int | None = None
+    line_number: int = 0
+
+
+@dataclass
+class FileDependency:
+    id: int | None = None
+    source_file_id: int | None = None
+    target_file_id: int | None = None
+
+
+@dataclass
+class CommitInfo:
+    id: int | None = None
+    repo_path: str = ""
+    sha: str = ""
+    author: str = ""
+    timestamp: float = 0.0
+    message: str = ""
+    files_changed: int = 0
+    insertions: int = 0
+    deletions: int = 0
+    risk_score: float = 0.0
+
+
+@dataclass
+class CommitFile:
+    id: int | None = None
+    commit_id: int | None = None
+    file_path: str = ""
+    change_type: str = ""
+    insertions: int = 0
+    deletions: int = 0
+    complexity_before: int | None = None
+    complexity_after: int | None = None
+
+
+@dataclass
+class LogEntry:
+    id: int | None = None
+    source_file: str = ""
+    timestamp: float | None = None
+    level: str = ""
+    logger_name: str = ""
+    message: str = ""
+    raw_line: str = ""
+    error_group_id: int | None = None
+
+
+@dataclass
+class ErrorGroup:
+    id: int | None = None
+    signature: str = ""
+    exception_type: str = ""
+    exception_message: str = ""
+    traceback: str = ""
+    first_seen: float = 0.0
+    last_seen: float = 0.0
+    occurrence_count: int = 1
+
+
+@dataclass
+class ErrorCodeLink:
+    id: int | None = None
+    error_group_id: int | None = None
+    function_id: int | None = None
+    file_id: int | None = None
+    line_number: int = 0
+    frame_position: int = 0

suitable_loop/server.py

@@ -0,0 +1,46 @@
+"""Suitable Loop MCP Server — entry point."""
+
+from __future__ import annotations
+
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+from .config import load_config
+from .db import Database
+from .tools.code_tools import register_code_tools
+from .tools.git_tools import register_git_tools
+from .tools.log_tools import register_log_tools
+from .tools.util_tools import register_util_tools
+
+logger = logging.getLogger(__name__)
+
+
+def create_server() -> FastMCP:
+    config = load_config()
+
+    logging.basicConfig(
+        level=getattr(logging, config.log_level, logging.INFO),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    db = Database(config)
+    db.connect()
+
+    mcp = FastMCP("Suitable Loop", json_response=True)
+
+    register_code_tools(mcp, db, config)
+    register_git_tools(mcp, db, config)
+    register_log_tools(mcp, db, config)
+    register_util_tools(mcp, db, config)
+
+    logger.info("Suitable Loop MCP server initialized (db: %s)", config.db_path)
+    return mcp
+
+
+server = create_server()
+
+
+def main():
+    """CLI entry point for uvx / python -m suitable_loop."""
+    server.run(transport="stdio")

suitable_loop/tools/__init__.py

@@ -0,0 +1 @@
+"""Suitable Loop MCP tool handlers."""

suitable_loop/tools/code_tools.py

@@ -0,0 +1,104 @@
+"""MCP tool handlers for code analysis."""
+
+from __future__ import annotations
+
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+from ..analyzers.code_analyzer import CodeAnalyzer
+from ..config import SuitableLoopConfig
+from ..db import Database
+from ..graph.engine import GraphEngine
+
+logger = logging.getLogger(__name__)
+
+
+def register_code_tools(mcp: FastMCP, db: Database, config: SuitableLoopConfig):
+    analyzer = CodeAnalyzer(db, config)
+    graph = GraphEngine(db)
+
+    @mcp.tool()
+    def index_codebase(path: str, force: bool = False) -> dict:
+        """Index a Python codebase. Parses all .py files, extracts functions, classes,
+        imports, and call relationships. Builds a semantic graph for querying.
+        Use force=True to re-index even unchanged files."""
+        result = analyzer.index_codebase(path, force=force)
+        graph.build_graph(path)
+        return result
+
+    @mcp.tool()
+    def query_entity(name: str) -> dict:
+        """Look up a function, class, or file by name. Returns details and all
+        relationships (callers, callees, file location, complexity)."""
+        info = graph.get_entity_info(name)
+        if not info:
+            return {"error": f"Entity '{name}' not found. Try search_code for broader search."}
+        return info
+
+    @mcp.tool()
+    def find_callers(function_name: str) -> dict:
+        """Find all functions that call the given function."""
+        callers = graph.get_callers(function_name)
+        return {
+            "function": function_name,
+            "caller_count": len(callers),
+            "callers": callers,
+        }
+
+    @mcp.tool()
+    def find_callees(function_name: str) -> dict:
+        """Find all functions called by the given function."""
+        callees = graph.get_callees(function_name)
+        return {
+            "function": function_name,
+            "callee_count": len(callees),
+            "callees": callees,
+        }
+
+    @mcp.tool()
+    def dependency_tree(file_path: str, depth: int = 3) -> dict:
+        """Get the import dependency tree for a file, up to N levels deep."""
+        return graph.dependency_tree(file_path, depth=depth)
+
+    @mcp.tool()
+    def search_code(query: str, max_results: int = 20) -> dict:
+        """Full-text search across indexed functions and classes."""
+        functions = db.search_functions(query, limit=max_results)
+        results = []
+        for f in functions:
+            file_entity = db.get_file_by_id(f.file_id) if f.file_id else None
+            results.append({
+                "name": f.qualified_name,
+                "type": "method" if f.is_method else "function",
+                "file": file_entity.path if file_entity else None,
+                "line_start": f.line_start,
+                "line_end": f.line_end,
+                "complexity": f.complexity,
+                "signature": f.signature,
+                "docstring": f.docstring,
+            })
+        return {"query": query, "result_count": len(results), "results": results}
+
+    @mcp.tool()
+    def complexity_report(top_n: int = 20) -> dict:
+        """Get the most complex functions in the indexed codebase, ranked by
+        cyclomatic complexity."""
+        report = graph.get_complexity_report(top_n=top_n)
+        return {"top_n": top_n, "functions": report}
+
+    @mcp.tool()
+    def codebase_summary() -> dict:
+        """High-level summary of the indexed codebase: file count, function count,
+        class count, average complexity, most-connected modules."""
+        stats = db.get_stats()
+        most_connected = graph.get_most_connected(top_n=10)
+        return {
+            "files": stats.get("files", 0),
+            "functions": stats.get("functions", 0),
+            "classes": stats.get("classes", 0),
+            "imports": stats.get("imports", 0),
+            "call_edges": stats.get("call_edges", 0),
+            "file_dependencies": stats.get("file_dependencies", 0),
+            "most_connected_modules": most_connected,
+        }

suitable_loop/tools/git_tools.py

@@ -0,0 +1,52 @@
+"""MCP tool handlers for git analysis."""
+
+from __future__ import annotations
+
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+from ..analyzers.git_analyzer import GitAnalyzer
+from ..config import SuitableLoopConfig
+from ..db import Database
+
+logger = logging.getLogger(__name__)
+
+
+def register_git_tools(mcp: FastMCP, db: Database, config: SuitableLoopConfig):
+    analyzer = GitAnalyzer(db, config)
+
+    @mcp.tool()
+    def analyze_recent_changes(repo_path: str, n_commits: int = 50) -> dict:
+        """Analyze recent git commits and score them by risk. Risk factors include
+        complexity delta, blast radius, churn rate, lines changed, and file count.
+        Returns commits sorted by risk score (highest first)."""
+        commits = analyzer.analyze_recent_changes(repo_path, n_commits=n_commits)
+        return {
+            "repo_path": repo_path,
+            "commits_analyzed": len(commits),
+            "commits": commits,
+        }
+
+    @mcp.tool()
+    def analyze_commit(repo_path: str, sha: str) -> dict:
+        """Deep-dive a single git commit. Shows changed files, complexity delta per file,
+        blast radius, and detailed risk breakdown."""
+        return analyzer.analyze_commit(repo_path, sha)
+
+    @mcp.tool()
+    def hotspot_report(repo_path: str, n_commits: int = 100) -> dict:
+        """Find code hotspots — files that change frequently AND are highly depended upon.
+        These are the highest-risk areas of the codebase."""
+        hotspots = analyzer.hotspot_report(repo_path, n_commits=n_commits)
+        return {
+            "repo_path": repo_path,
+            "commits_analyzed": n_commits,
+            "hotspots": hotspots,
+        }
+
+    @mcp.tool()
+    def blast_radius(file_path: str) -> dict:
+        """Calculate the blast radius of a file — how many other files and functions
+        are transitively affected if this file breaks."""
+        return analyzer.blast_radius(file_path)