cartograph-python 0.2.0__cp38-abi3-win_amd64.whl

cartograph/aio.py

@@ -0,0 +1,238 @@
+"""Asynchronous CodeGraph engine interface using asyncio and thread offloading."""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from cartograph.codegraph import CodeGraph
+from cartograph.models import (
+    ComplexityReport,
+    DeadCodeReport,
+    DiagnosisReport,
+    DiagramResult,
+    GraphStats,
+    ImpactResult,
+    IndexStats,
+    LintArchReport,
+    LocateResult,
+    LogicReport,
+    RouteTrace,
+    TestSelectorResult,
+)
+
+if TYPE_CHECKING:
+    import igraph as ig
+    import networkx as nx
+    import pandas as pd
+    import polars as pl
+
+
+class AsyncCodeGraph:
+    """Asynchronous CodeGraph engine interface for async services, agents, and FastAPI."""
+
+    def __init__(
+        self,
+        path: str | Path | None = None,
+        profile: str = "default",
+        in_memory: bool = False,
+    ) -> None:
+        self._sync_graph = CodeGraph(path=path, profile=profile, in_memory=in_memory)
+
+    @classmethod
+    async def open(
+        cls,
+        path: str | Path | None = None,
+        profile: str = "default",
+        in_memory: bool = False,
+    ) -> AsyncCodeGraph:
+        """Asynchronously open or initialize an AsyncCodeGraph instance."""
+        return await asyncio.to_thread(cls, path=path, profile=profile, in_memory=in_memory)
+
+    async def __aenter__(self) -> AsyncCodeGraph:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Asynchronously close database connections and release resources."""
+        await asyncio.to_thread(self._sync_graph.close)
+
+    @property
+    def is_open(self) -> bool:
+        """Check if database connection is active."""
+        return self._sync_graph.is_open
+
+    @property
+    def profile(self) -> str:
+        """Active storage profile name."""
+        return self._sync_graph.profile
+
+    async def index(
+        self,
+        force: bool = False,
+        staged: bool = False,
+        branch: str | None = None,
+        threads: int | None = None,
+    ) -> IndexStats:
+        """Scan workspace and populate the knowledge graph asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.index, force=force, staged=staged, branch=branch, threads=threads
+        )
+
+    async def status(self) -> GraphStats:
+        """Return aggregate statistics and health of the graph store asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.status)
+
+    async def locate(
+        self,
+        query: str,
+        code: bool = False,
+        limit: int = 10,
+    ) -> LocateResult:
+        """Natural language or exact code subgraph localization asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.locate, query=query, code=code, limit=limit
+        )
+
+    async def impact(
+        self,
+        target: str,
+        branch: str | None = None,
+        staged: bool = False,
+        depth: int = 3,
+    ) -> ImpactResult:
+        """Perform topological blast-radius and risk analysis asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.impact, target=target, branch=branch, staged=staged, depth=depth
+        )
+
+    async def test_selector(
+        self,
+        target: str,
+        branch: str | None = None,
+    ) -> TestSelectorResult:
+        """Predict minimal test set exercising the changed target asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.test_selector, target=target, branch=branch
+        )
+
+    async def routes(
+        self,
+        filter_query: str | None = None,
+    ) -> list[RouteTrace]:
+        """Discover API routes, controller endpoints, and full-stack traces asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.routes, filter_query=filter_query
+        )
+
+    async def lint_arch(
+        self,
+        strict: bool = False,
+    ) -> LintArchReport:
+        """Detect architecture boundary violations and circular dependencies asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.lint_arch, strict=strict
+        )
+
+    async def complexity(
+        self,
+        top: int = 15,
+        danger_zone: bool = False,
+    ) -> ComplexityReport:
+        """Analyze cyclomatic/cognitive complexity and test deficits asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.complexity, top=top, danger_zone=danger_zone
+        )
+
+    async def deadcode(
+        self,
+        min_lines: int = 20,
+    ) -> DeadCodeReport:
+        """Detect unreachable symbols and ghost dependencies asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.deadcode, min_lines=min_lines
+        )
+
+    async def extract_logic(
+        self,
+        query: str | None = None,
+        symbol: str | None = None,
+        concept: str | None = None,
+        deep: bool = False,
+    ) -> LogicReport:
+        """Extract business rules, invariants, and constraints asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.extract_logic, query=query, symbol=symbol, concept=concept, deep=deep
+        )
+
+    async def diagnose(
+        self,
+        trace_or_log: str,
+        file_path: str | None = None,
+        deep: bool = False,
+        offline: bool = True,
+    ) -> DiagnosisReport:
+        """Perform 8-stage topological root-cause fault diagnosis asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.diagnose,
+            trace_or_log=trace_or_log,
+            file_path=file_path,
+            deep=deep,
+            offline=offline,
+        )
+
+    async def diagram(
+        self,
+        symbol_or_concept: str | None = None,
+        diagram_type: str = "architecture",
+        format: str = "mermaid",
+        depth: int = 2,
+        direction: str = "both",
+        max_nodes: int = 30,
+        collapse_modules: bool = False,
+        theme: str = "dark",
+    ) -> DiagramResult:
+        """Render architecture, call graph, and component diagrams asynchronously."""
+        return await asyncio.to_thread(
+            self._sync_graph.diagram,
+            symbol_or_concept=symbol_or_concept,
+            diagram_type=diagram_type,
+            format=format,
+            depth=depth,
+            direction=direction,
+            max_nodes=max_nodes,
+            collapse_modules=collapse_modules,
+            theme=theme,
+        )
+
+    # ── Graph Data Science Integrations ─────────────────────────
+
+    async def to_networkx(self) -> nx.DiGraph:
+        """Stream codebase graph into a NetworkX DiGraph asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.to_networkx)
+
+    async def to_igraph(self) -> ig.Graph:
+        """Stream codebase graph into an igraph Graph asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.to_igraph)
+
+    async def nodes_df(self, engine: Literal["polars", "pandas"] = "polars") -> Any:
+        """Return nodes dataframe using Polars or Pandas asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.nodes_df, engine=engine)
+
+    async def edges_df(self, engine: Literal["polars", "pandas"] = "polars") -> Any:
+        """Return edges dataframe using Polars or Pandas asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.edges_df, engine=engine)
+
+    async def complexity_df(self, engine: Literal["polars", "pandas"] = "polars") -> Any:
+        """Return complexity hotspots dataframe using Polars or Pandas asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.complexity_df, engine=engine)
+
+    async def to_polars(self) -> dict[str, pl.DataFrame]:
+        """Export all primary tables to Polars DataFrames asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.to_polars)
+
+    async def to_pandas(self) -> dict[str, pd.DataFrame]:
+        """Export all primary tables to Pandas DataFrames asynchronously."""
+        return await asyncio.to_thread(self._sync_graph.to_pandas)

cartograph/codegraph.py

@@ -0,0 +1,247 @@
+"""Synchronous CodeGraph engine interface."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from cartograph._cartograph import (
+    CodeGraph as _NativeCodeGraph,
+    ComplexityReport,
+    DeadCodeReport,
+    DiagnosisReport,
+    DiagramResult,
+    GraphStats,
+    ImpactResult,
+    IndexStats,
+    LintArchReport,
+    LocateResult,
+    LogicReport,
+    Node,
+    RouteTrace,
+    TestSelectorResult,
+)
+from cartograph.dataframes import columnar_to_pandas, columnar_to_polars
+from cartograph.igraph_adapter import stream_to_igraph
+from cartograph.networkx_adapter import stream_to_networkx
+
+if TYPE_CHECKING:
+    import igraph as ig
+    import networkx as nx
+    import pandas as pd
+    import polars as pl
+
+
+class CodeGraph:
+    """High-performance code graph engine and knowledge graph for codebases."""
+
+    def __init__(
+        self,
+        path: str | Path | None = None,
+        profile: str = "default",
+        in_memory: bool = False,
+    ) -> None:
+        path_str = str(Path(path).resolve()) if path is not None else None
+        self._inner = _NativeCodeGraph.open(path=path_str, profile=profile, in_memory=in_memory)
+
+    @classmethod
+    def open(
+        cls,
+        path: str | Path | None = None,
+        profile: str = "default",
+        in_memory: bool = False,
+    ) -> CodeGraph:
+        """Open or initialize a CodeGraph instance."""
+        return cls(path=path, profile=profile, in_memory=in_memory)
+
+    def __enter__(self) -> CodeGraph:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close database connections and release resources."""
+        self._inner.close()
+
+    @property
+    def is_open(self) -> bool:
+        """Check if database connection is active."""
+        return self._inner.is_open()
+
+    @property
+    def profile(self) -> str:
+        """Active storage profile name."""
+        return self._inner.profile
+
+    def index(
+        self,
+        force: bool = False,
+        staged: bool = False,
+        branch: str | None = None,
+        threads: int | None = None,
+    ) -> IndexStats:
+        """Scan workspace and populate the knowledge graph."""
+        return self._inner.index(force=force, staged=staged, branch=branch, threads=threads)
+
+    def status(self) -> GraphStats:
+        """Return aggregate statistics and health of the graph store."""
+        return self._inner.status()
+
+    def locate(
+        self,
+        query: str,
+        code: bool = False,
+        limit: int = 10,
+    ) -> LocateResult:
+        """Natural language or exact code subgraph localization."""
+        return self._inner.locate(query=query, code=code, limit=limit)
+
+    def impact(
+        self,
+        target: str,
+        branch: str | None = None,
+        staged: bool = False,
+        depth: int = 3,
+    ) -> ImpactResult:
+        """Perform topological blast-radius and risk analysis."""
+        return self._inner.impact(target=target, branch=branch, staged=staged, depth=depth)
+
+    def test_selector(
+        self,
+        target: str,
+        branch: str | None = None,
+    ) -> TestSelectorResult:
+        """Predict minimal test set exercising the changed target."""
+        return self._inner.test_selector(target=target, branch=branch)
+
+    def routes(
+        self,
+        filter_query: str | None = None,
+    ) -> list[RouteTrace]:
+        """Discover API routes, controller endpoints, and full-stack traces."""
+        return self._inner.routes(filter_query=filter_query)
+
+    def lint_arch(
+        self,
+        strict: bool = False,
+    ) -> LintArchReport:
+        """Detect architecture boundary violations and circular dependencies."""
+        return self._inner.lint_arch(strict=strict)
+
+    def complexity(
+        self,
+        top: int = 15,
+        danger_zone: bool = False,
+    ) -> ComplexityReport:
+        """Analyze cyclomatic/cognitive complexity and test deficits."""
+        return self._inner.complexity(top=top, danger_zone=danger_zone)
+
+    def deadcode(
+        self,
+        min_lines: int = 20,
+    ) -> DeadCodeReport:
+        """Detect unreachable symbols and ghost dependencies."""
+        return self._inner.deadcode(min_lines=min_lines)
+
+    def extract_logic(
+        self,
+        query: str | None = None,
+        symbol: str | None = None,
+        concept: str | None = None,
+        deep: bool = False,
+    ) -> LogicReport:
+        """Extract business rules, invariants, and constraints."""
+        return self._inner.extract_logic(query=query, symbol=symbol, concept=concept, deep=deep)
+
+    def diagnose(
+        self,
+        trace_or_log: str,
+        file_path: str | None = None,
+        deep: bool = False,
+        offline: bool = True,
+    ) -> DiagnosisReport:
+        """Perform 8-stage topological root-cause fault diagnosis."""
+        return self._inner.diagnose(
+            trace_or_log=trace_or_log, file_path=file_path, deep=deep, offline=offline
+        )
+
+    def diagram(
+        self,
+        symbol_or_concept: str | None = None,
+        diagram_type: str = "architecture",
+        format: str = "mermaid",
+        depth: int = 2,
+        direction: str = "both",
+        max_nodes: int = 30,
+        collapse_modules: bool = False,
+        theme: str = "dark",
+    ) -> DiagramResult:
+        """Render architecture, call graph, and component diagrams."""
+        return self._inner.diagram(
+            symbol_or_concept=symbol_or_concept,
+            diagram_type=diagram_type,
+            format=format,
+            depth=depth,
+            direction=direction,
+            max_nodes=max_nodes,
+            collapse_modules=collapse_modules,
+            theme=theme,
+        )
+
+    # ── Graph Data Science Integrations ─────────────────────────
+
+    def to_networkx(self) -> nx.DiGraph:
+        """Stream codebase graph into a NetworkX DiGraph."""
+        streamer = self._inner.get_streamer()
+        return stream_to_networkx(streamer)
+
+    def to_igraph(self) -> ig.Graph:
+        """Stream codebase graph into an igraph Graph."""
+        streamer = self._inner.get_streamer()
+        return stream_to_igraph(streamer)
+
+    def nodes_df(self, engine: Literal["polars", "pandas"] = "polars") -> Any:
+        """Return nodes dataframe using Polars or Pandas."""
+        col_dict = self._inner.nodes_columnar()
+        if engine == "polars":
+            return columnar_to_polars(col_dict)
+        elif engine == "pandas":
+            return columnar_to_pandas(col_dict)
+        else:
+            raise ValueError(f"Unsupported engine: {engine}. Choose 'polars' or 'pandas'")
+
+    def edges_df(self, engine: Literal["polars", "pandas"] = "polars") -> Any:
+        """Return edges dataframe using Polars or Pandas."""
+        col_dict = self._inner.edges_columnar()
+        if engine == "polars":
+            return columnar_to_polars(col_dict)
+        elif engine == "pandas":
+            return columnar_to_pandas(col_dict)
+        else:
+            raise ValueError(f"Unsupported engine: {engine}. Choose 'polars' or 'pandas'")
+
+    def complexity_df(self, engine: Literal["polars", "pandas"] = "polars") -> Any:
+        """Return complexity hotspots dataframe using Polars or Pandas."""
+        col_dict = self._inner.complexity_columnar()
+        if engine == "polars":
+            return columnar_to_polars(col_dict)
+        elif engine == "pandas":
+            return columnar_to_pandas(col_dict)
+        else:
+            raise ValueError(f"Unsupported engine: {engine}. Choose 'polars' or 'pandas'")
+
+    def to_polars(self) -> dict[str, pl.DataFrame]:
+        """Export all primary tables (nodes, edges, complexity) to Polars DataFrames."""
+        return {
+            "nodes": self.nodes_df("polars"),
+            "edges": self.edges_df("polars"),
+            "complexity": self.complexity_df("polars"),
+        }
+
+    def to_pandas(self) -> dict[str, pd.DataFrame]:
+        """Export all primary tables (nodes, edges, complexity) to Pandas DataFrames."""
+        return {
+            "nodes": self.nodes_df("pandas"),
+            "edges": self.edges_df("pandas"),
+            "complexity": self.complexity_df("pandas"),
+        }

cartograph/dataframes.py

@@ -0,0 +1,42 @@
+"""Dataframe conversions for Polars, Pandas, and PyArrow."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import pandas as pd
+    import polars as pl
+    import pyarrow as pa
+
+
+def columnar_to_polars(col_dict: dict[str, Any]) -> pl.DataFrame:
+    """Convert a columnar dictionary directly into a Polars DataFrame."""
+    try:
+        import polars as pl
+    except ImportError as e:
+        raise ImportError(
+            "polars is not installed. Install it with: pip install 'cartograph[polars]'"
+        ) from e
+    return pl.DataFrame(col_dict)
+
+
+def columnar_to_pandas(col_dict: dict[str, Any]) -> pd.DataFrame:
+    """Convert a columnar dictionary directly into a Pandas DataFrame."""
+    try:
+        import pandas as pd
+    except ImportError as e:
+        raise ImportError(
+            "pandas is not installed. Install it with: pip install 'cartograph[pandas]'"
+        ) from e
+    return pd.DataFrame(col_dict)
+
+
+def columnar_to_arrow(col_dict: dict[str, Any]) -> pa.Table:
+    """Convert a columnar dictionary directly into a PyArrow Table."""
+    try:
+        import pyarrow as pa
+    except ImportError as e:
+        raise ImportError(
+            "pyarrow is not installed. Install it with: pip install pyarrow"
+        ) from e
+    return pa.Table.from_pydict(col_dict)

cartograph/igraph_adapter.py

@@ -0,0 +1,51 @@
+"""igraph conversion adapter for cartograph."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import igraph as ig
+
+
+def stream_to_igraph(streamer: Any) -> ig.Graph:
+    """Stream graph nodes and edges directly into an igraph Graph."""
+    try:
+        import igraph as ig
+    except ImportError as e:
+        raise ImportError(
+            "igraph is not installed. Install it with: pip install 'cartograph[igraph]'"
+        ) from e
+
+    nodes = streamer.get_nodes()
+    edges = streamer.get_edges()
+
+    node_indices = {n[0]: i for i, n in enumerate(nodes)}
+    edge_tuples = []
+    edge_kinds = []
+    edge_weights = []
+
+    for src, tgt, kind, weight in edges:
+        if src in node_indices and tgt in node_indices:
+            edge_tuples.append((node_indices[src], node_indices[tgt]))
+            edge_kinds.append(kind)
+            edge_weights.append(weight)
+
+    g = ig.Graph(
+        n=len(nodes),
+        edges=edge_tuples,
+        directed=True,
+        vertex_attrs={
+            "name": [n[0] for n in nodes],
+            "symbol_name": [n[1] for n in nodes],
+            "kind": [n[2] for n in nodes],
+            "filepath": [n[3] for n in nodes],
+            "start_line": [n[4] for n in nodes],
+            "end_line": [n[5] for n in nodes],
+            "complexity": [n[6] for n in nodes],
+        },
+        edge_attrs={
+            "kind": edge_kinds,
+            "weight": edge_weights,
+        },
+    )
+    return g

cartograph/jupyter.py

@@ -0,0 +1,38 @@
+"""Jupyter and IPython display integrations for cartograph."""
+from __future__ import annotations
+
+import html
+from typing import Any
+
+
+def render_mermaid_html(mermaid_code: str) -> str:
+    """Render a mermaid diagram inside Jupyter / IPython notebook via HTML."""
+    escaped = html.escape(mermaid_code)
+    return f"""
+    <div class="cartograph-mermaid-container" style="background: #1e1e2e; padding: 16px; border-radius: 8px;">
+        <pre class="mermaid" style="background: transparent;">
+{escaped}
+        </pre>
+        <script type="module">
+            import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
+            mermaid.initialize({{ startOnLoad: true, theme: 'dark' }});
+            mermaid.run();
+        </script>
+    </div>
+    """
+
+
+class RichMermaidDisplay:
+    """Wrapper that displays mermaid diagrams natively in Jupyter."""
+
+    def __init__(self, content: str):
+        self.content = content
+
+    def _repr_html_(self) -> str:
+        return render_mermaid_html(self.content)
+
+    def __str__(self) -> str:
+        return self.content
+
+    def __repr__(self) -> str:
+        return self.content

cartograph/models.py

@@ -0,0 +1,64 @@
+"""Data models and exception classes for Cartograph."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from cartograph._cartograph import (
+    AnalysisError,
+    BoundaryViolation,
+    BusinessRule,
+    CartographError,
+    ComplexityRecord,
+    ComplexityReport,
+    DatabaseError,
+    DeadCodeReport,
+    DeadSymbolItem,
+    DependencyCycle,
+    DiagnosisReport,
+    DiagramResult,
+    Edge,
+    FaultCandidate,
+    GraphStats,
+    GraphStreamer,
+    ImpactResult,
+    ImpactRoot,
+    IndexStats,
+    LintArchReport,
+    LocateResult,
+    LogicReport,
+    Node,
+    RouteTrace,
+    SelectedTest,
+    SymbolNotFoundError,
+    TestSelectorResult,
+)
+
+__all__ = [
+    "AnalysisError",
+    "BoundaryViolation",
+    "BusinessRule",
+    "CartographError",
+    "ComplexityRecord",
+    "ComplexityReport",
+    "DatabaseError",
+    "DeadCodeReport",
+    "DeadSymbolItem",
+    "DependencyCycle",
+    "DiagnosisReport",
+    "DiagramResult",
+    "Edge",
+    "FaultCandidate",
+    "GraphStats",
+    "GraphStreamer",
+    "ImpactResult",
+    "ImpactRoot",
+    "IndexStats",
+    "LintArchReport",
+    "LocateResult",
+    "LogicReport",
+    "Node",
+    "RouteTrace",
+    "SelectedTest",
+    "SymbolNotFoundError",
+    "TestSelectorResult",
+]