polycodegraph 0.1.0__py3-none-any.whl

codegraph/viz/html.py

@@ -0,0 +1,115 @@
+"""Interactive pyvis HTML renderer."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, cast
+
+import networkx as nx
+
+from codegraph.viz._style import EDGE_STYLE, KIND_COLOR, kind_str
+
+_DEFAULT_HEIGHT = "780px"
+_DEFAULT_WIDTH = "100%"
+
+
+def _shape_for_kind(kind: str) -> str:
+    if kind in ("FILE", "MODULE"):
+        return "box"
+    if kind == "CLASS":
+        return "ellipse"
+    if kind == "TEST":
+        return "diamond"
+    return "dot"
+
+
+def _node_title(attrs: dict[str, Any]) -> str:
+    parts = [
+        f"<b>{attrs.get('name') or attrs.get('qualname') or ''}</b>",
+        f"kind: {kind_str(attrs.get('kind'))}",
+        f"qualname: {attrs.get('qualname') or '-'}",
+        f"file: {attrs.get('file') or '-'}:"
+        f"{attrs.get('line_start') or '?'}",
+        f"language: {attrs.get('language') or '-'}",
+    ]
+    sig = attrs.get("signature")
+    if sig:
+        parts.append(f"signature: {sig}")
+    return "<br>".join(str(p) for p in parts)
+
+
+def render_html(
+    graph: nx.MultiDiGraph,
+    output: Path,
+    *,
+    height: str = _DEFAULT_HEIGHT,
+    width: str = _DEFAULT_WIDTH,
+    notebook: bool = False,
+) -> Path:
+    """Render an interactive HTML visualization with pyvis.
+
+    Returns the path that was written. Pyvis is a required dependency, so
+    this function will only fail if the user has uninstalled it manually.
+    """
+    try:
+        from pyvis.network import Network
+    except ImportError as exc:  # pragma: no cover - pyvis is a hard dep
+        raise RuntimeError(
+            "pyvis is required for HTML output: pip install pyvis"
+        ) from exc
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    net = Network(
+        height=height,
+        width=width,
+        directed=True,
+        notebook=notebook,
+        cdn_resources="in_line",
+        bgcolor="#0f172a",
+        font_color="#f1f5f9",
+    )
+    net.barnes_hut(
+        gravity=-8000,
+        central_gravity=0.3,
+        spring_length=120,
+        spring_strength=0.04,
+    )
+
+    for nid, attrs in graph.nodes(data=True):
+        kind = kind_str(attrs.get("kind"))
+        color = KIND_COLOR.get(kind, "#94a3b8")
+        label = str(attrs.get("name") or attrs.get("qualname") or nid[:8])
+        net.add_node(
+            nid,
+            label=label,
+            color=color,
+            shape=_shape_for_kind(kind),
+            title=_node_title(cast(dict[str, Any], attrs)),
+            group=kind or "OTHER",
+        )
+
+    seen: set[tuple[str, str, str]] = set()
+    for src, dst, data in graph.edges(data=True):
+        if src not in graph.nodes or dst not in graph.nodes:
+            continue
+        ek = kind_str(data.get("kind"))
+        key = (src, dst, ek)
+        if key in seen:
+            continue
+        seen.add(key)
+        style = EDGE_STYLE.get(ek, "solid")
+        dashes = style in ("dashed", "dotted")
+        width_n = 3 if style == "bold" else 1
+        net.add_edge(
+            src,
+            dst,
+            label=ek,
+            arrows="to",
+            dashes=dashes,
+            width=width_n,
+            title=ek,
+        )
+
+    html = cast(str, net.generate_html(notebook=notebook))
+    output.write_text(html, encoding="utf-8")
+    return output

codegraph/viz/mermaid.py

@@ -0,0 +1,111 @@
+"""Mermaid renderer with file-clustering and per-kind coloring."""
+from __future__ import annotations
+
+import re
+from collections import defaultdict
+
+import networkx as nx
+
+from codegraph.viz._style import EDGE_STYLE, KIND_CLASS, kind_str
+
+_SAFE_RE = re.compile(r"[^a-zA-Z0-9_]+")
+
+
+def _safe_id(node_id: str, prefix: str = "n_") -> str:
+    return prefix + _SAFE_RE.sub("_", node_id)[:32]
+
+
+def _safe_subgraph_id(name: str) -> str:
+    return "g_" + _SAFE_RE.sub("_", name)[:48]
+
+
+def _label(attrs: dict[str, object]) -> str:
+    raw = str(attrs.get("name") or "")
+    if not raw:
+        raw = str(attrs.get("qualname") or "?")
+    return raw.replace('"', "'").replace("[", "(").replace("]", ")")
+
+
+def render_mermaid(
+    graph: nx.MultiDiGraph,
+    *,
+    cluster_by_file: bool = True,
+    show_legend: bool = True,
+) -> str:
+    """Return a Mermaid ``flowchart LR`` diagram of ``graph``.
+
+    Nodes are colored by NodeKind; edges by EdgeKind. When
+    ``cluster_by_file`` is True, nodes that share a file path are grouped
+    into a Mermaid subgraph.
+    """
+    lines: list[str] = ["flowchart LR"]
+
+    classes = {
+        "file": "stroke:#475569,fill:#e2e8f0,color:#1e293b",
+        "module": "stroke:#3730a3,fill:#e0e7ff,color:#1e1b4b",
+        "klass": "stroke:#b45309,fill:#fef3c7,color:#451a03",
+        "func": "stroke:#047857,fill:#d1fae5,color:#022c22",
+        "method": "stroke:#15803d,fill:#dcfce7,color:#052e16",
+        "var": "stroke:#4b5563,fill:#f3f4f6,color:#111827",
+        "param": "stroke:#6b7280,fill:#f9fafb,color:#111827",
+        "imp": "stroke:#0369a1,fill:#e0f2fe,color:#082f49",
+        "test": "stroke:#be185d,fill:#fce7f3,color:#500724",
+    }
+    for cls, style in classes.items():
+        lines.append(f"    classDef {cls} {style};")
+
+    by_file: dict[str, list[tuple[str, dict[str, object]]]] = defaultdict(list)
+    free: list[tuple[str, dict[str, object]]] = []
+    for nid, attrs in graph.nodes(data=True):
+        file_path = attrs.get("file")
+        if cluster_by_file and isinstance(file_path, str) and file_path:
+            by_file[file_path].append((nid, attrs))
+        else:
+            free.append((nid, attrs))
+
+    safe_map: dict[str, str] = {}
+
+    def _emit_node(nid: str, attrs: dict[str, object], indent: str) -> None:
+        sid = _safe_id(nid)
+        safe_map[nid] = sid
+        kind = kind_str(attrs.get("kind"))
+        cls = KIND_CLASS.get(kind, "var")
+        label = f"{kind}: {_label(attrs)}"
+        lines.append(f'{indent}{sid}["{label}"]:::{cls}')
+
+    for file_path, members in sorted(by_file.items()):
+        sg_id = _safe_subgraph_id(file_path)
+        lines.append(f'    subgraph {sg_id}["{file_path}"]')
+        for nid, attrs in members:
+            _emit_node(nid, attrs, "        ")
+        lines.append("    end")
+    for nid, attrs in free:
+        _emit_node(nid, attrs, "    ")
+
+    seen: set[tuple[str, str, str]] = set()
+    for src, dst, data in graph.edges(data=True):
+        if src not in safe_map or dst not in safe_map:
+            continue
+        ek = kind_str(data.get("kind"))
+        key = (src, dst, ek)
+        if key in seen:
+            continue
+        seen.add(key)
+        style = EDGE_STYLE.get(ek, "solid")
+        arrow = "-->" if style != "dotted" else "-.->"
+        if style == "bold":
+            arrow = "==>"
+        lines.append(
+            f"    {safe_map[src]} {arrow}|{ek}| {safe_map[dst]}"
+        )
+
+    if show_legend:
+        lines.append("    %% legend")
+        lines.append('    legend_file["FILE"]:::file')
+        lines.append('    legend_module["MODULE"]:::module')
+        lines.append('    legend_class["CLASS"]:::klass')
+        lines.append('    legend_func["FUNCTION"]:::func')
+        lines.append('    legend_method["METHOD"]:::method')
+        lines.append('    legend_test["TEST"]:::test')
+
+    return "\n".join(lines) + "\n"

codegraph/viz/svg.py

@@ -0,0 +1,77 @@
+"""Optional Graphviz SVG renderer (no-op if `dot` binary is missing)."""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+import networkx as nx
+
+from codegraph.viz._style import EDGE_STYLE, KIND_COLOR, kind_str
+
+
+class GraphvizUnavailableError(RuntimeError):
+    """Raised when the graphviz Python package or `dot` binary is missing."""
+
+
+def _ensure_graphviz() -> Any:
+    try:
+        import graphviz as _graphviz
+    except ImportError as exc:
+        raise GraphvizUnavailableError(
+            "graphviz Python package not installed. "
+            "Install with: pip install polycodegraph[viz]"
+        ) from exc
+    if shutil.which("dot") is None:
+        raise GraphvizUnavailableError(
+            "Graphviz `dot` binary not found in PATH. "
+            "Install Graphviz from https://graphviz.org/download/"
+        )
+    return _graphviz
+
+
+def render_svg(graph: nx.MultiDiGraph, output: Path) -> Path:
+    """Render an SVG of ``graph`` to ``output``.
+
+    Raises ``GraphvizUnavailableError`` if the toolchain is missing so the
+    CLI can degrade gracefully.
+    """
+    gv = _ensure_graphviz()
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    dot = gv.Digraph(format="svg")
+    dot.attr(rankdir="LR", bgcolor="white", fontname="Helvetica")
+    dot.attr("node", style="filled", fontname="Helvetica", fontsize="11")
+    dot.attr("edge", fontname="Helvetica", fontsize="9", color="#475569")
+
+    for nid, attrs in graph.nodes(data=True):
+        kind = kind_str(attrs.get("kind"))
+        color = KIND_COLOR.get(kind, "#94a3b8")
+        label = str(attrs.get("name") or attrs.get("qualname") or nid[:8])
+        dot.node(
+            nid,
+            label=f"{kind}\\n{label}",
+            fillcolor=color,
+            color="#1e293b",
+            fontcolor="#0f172a",
+        )
+
+    seen: set[tuple[str, str, str]] = set()
+    for src, dst, data in graph.edges(data=True):
+        ek = kind_str(data.get("kind"))
+        key = (src, dst, ek)
+        if key in seen:
+            continue
+        seen.add(key)
+        style = EDGE_STYLE.get(ek, "solid")
+        dot.edge(src, dst, label=ek, style=style)
+
+    rendered_path = dot.render(
+        filename=output.with_suffix("").name,
+        directory=str(output.parent),
+        cleanup=True,
+    )
+    rendered = Path(rendered_path)
+    if rendered != output:
+        rendered.replace(output)
+    return output

codegraph/web/__init__.py

@@ -0,0 +1,4 @@
+"""HTTP server + static assets for the codegraph dashboard."""
+from codegraph.web.server import DashboardState, serve
+
+__all__ = ["DashboardState", "serve"]

codegraph/web/server.py

@@ -0,0 +1,165 @@
+"""Lightweight stdlib HTTP server for the codegraph dashboard."""
+from __future__ import annotations
+
+import datetime as dt
+import importlib.resources as resources
+import json
+import logging
+import mimetypes
+import threading
+import webbrowser
+from collections.abc import Callable
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+import networkx as nx
+
+from codegraph.viz.dashboard import build_dashboard_payload
+
+logger = logging.getLogger(__name__)
+
+_STATIC_PKG = "codegraph.web.static"
+
+
+def _read_static(name: str) -> bytes:
+    return (resources.files(_STATIC_PKG) / name).read_bytes()
+
+
+class DashboardState:
+    """Holds the rebuildable graph + cached payload."""
+
+    def __init__(
+        self,
+        repo_root: Path,
+        explore_dir: Path,
+        graph_loader: Callable[[], nx.MultiDiGraph],
+        rebuild: Callable[[], nx.MultiDiGraph] | None = None,
+    ) -> None:
+        self.repo_root = repo_root
+        self.explore_dir = explore_dir
+        self._graph_loader = graph_loader
+        self._rebuild = rebuild
+        self._lock = threading.Lock()
+        self._payload: dict[str, Any] | None = None
+
+    def payload(self) -> dict[str, Any]:
+        with self._lock:
+            if self._payload is None:
+                self._payload = self._build_payload(self._graph_loader())
+            return self._payload
+
+    def rebuild(self) -> dict[str, Any]:
+        with self._lock:
+            graph = (
+                self._graph_loader() if self._rebuild is None else self._rebuild()
+            )
+            self._payload = self._build_payload(graph)
+            return self._payload
+
+    def _build_payload(self, graph: nx.MultiDiGraph) -> dict[str, Any]:
+        payload = build_dashboard_payload(graph)
+        payload["repo"] = self.repo_root.name
+        payload["built_at"] = dt.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        return payload
+
+
+class _Handler(BaseHTTPRequestHandler):
+    state: DashboardState  # set per-instance via factory
+
+    def log_message(self, format: str, *args: Any) -> None:
+        logger.debug("%s - %s", self.address_string(), format % args)
+
+    # ---- helpers ----
+    def _send_bytes(
+        self, body: bytes, content_type: str, status: int = 200
+    ) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _send_json(self, data: dict[str, Any], status: int = 200) -> None:
+        body = json.dumps(data).encode("utf-8")
+        self._send_bytes(body, "application/json; charset=utf-8", status)
+
+    def _not_found(self) -> None:
+        self._send_bytes(b"not found", "text/plain", HTTPStatus.NOT_FOUND)
+
+    # ---- routes ----
+    def do_GET(self) -> None:
+        path = urlparse(self.path).path
+        if path == "/" or path == "/index.html":
+            self._send_bytes(_read_static("index.html"),
+                             "text/html; charset=utf-8")
+            return
+        if path == "/api/data.json":
+            self._send_json(self.state.payload())
+            return
+        if path.startswith("/static/"):
+            name = path[len("/static/"):]
+            try:
+                data = _read_static(name)
+            except (FileNotFoundError, ModuleNotFoundError):
+                self._not_found()
+                return
+            ctype, _ = mimetypes.guess_type(name)
+            self._send_bytes(data, ctype or "application/octet-stream")
+            return
+        # Anything else: try the explore dir for pyvis pages.
+        candidate = self.state.explore_dir / path.lstrip("/")
+        try:
+            candidate = candidate.resolve()
+            candidate.relative_to(self.state.explore_dir.resolve())
+        except (ValueError, OSError):
+            self._not_found()
+            return
+        if candidate.is_file():
+            ctype, _ = mimetypes.guess_type(str(candidate))
+            self._send_bytes(candidate.read_bytes(),
+                             ctype or "application/octet-stream")
+            return
+        self._not_found()
+
+    def do_POST(self) -> None:
+        path = urlparse(self.path).path
+        if path == "/api/rebuild":
+            try:
+                self.state.rebuild()
+            except Exception as exc:
+                logger.exception("rebuild failed")
+                self._send_json({"error": str(exc)}, status=500)
+                return
+            self._send_json({"ok": True})
+            return
+        self._not_found()
+
+
+def serve(
+    state: DashboardState,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    open_browser: bool = True,
+) -> None:
+    """Block on the dashboard HTTP server."""
+    handler_cls = type("_BoundHandler", (_Handler,), {"state": state})
+    server = ThreadingHTTPServer((host, port), handler_cls)
+    url = f"http://{host}:{port}/"
+    print(f"\n  codegraph dashboard ready at \033[36m{url}\033[0m")
+    print("  press Ctrl+C to stop\n")
+    if open_browser:
+        threading.Timer(0.5, lambda: webbrowser.open(url)).start()
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\n  shutting down...")
+    finally:
+        server.shutdown()
+
+
+__all__ = ["DashboardState", "serve"]