adl-toolkit 0.0.0-stage → 0.1.1

package/adl_drift/server/web.py

@@ -0,0 +1,350 @@
+"""Interactive graph visualization server.
+
+Stdlib HTTP server. Serves a Cytoscape.js UI plus JSON endpoints backed by the
+persisted call graph in `cortex.db`. Lazy expansion: the client requests node
+children / neighbors on demand instead of loading the whole graph.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+import time
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import parse_qs, unquote, urlparse
+
+from adl_drift.cli.commands import DriftCommands
+from adl_drift.graph.builder import CallGraphBuilder
+from adl_drift.graph.cluster import detect_communities
+from adl_drift.graph.edges import EdgeType
+from adl_drift.graph.node import NodeType
+
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+class GraphService:
+    """Wraps DriftCommands + version polling for the HTTP layer."""
+
+    VERSION_CACHE_SECONDS = 1.0
+
+    def __init__(self, project_path: Path):
+        self.project_path = project_path
+        self.commands = DriftCommands(project_path)
+        self._lock = threading.Lock()
+        self._builder: Optional[CallGraphBuilder] = None
+        self._version: Tuple[float, int] = (0.0, 0)
+        self._last_version_check = 0.0
+        self._cached_version: Tuple[float, int] = (0.0, 0)
+        self._communities: Dict[str, int] = {}
+
+    # -- public --
+
+    def ensure_graph(self) -> CallGraphBuilder:
+        """Return current graph. Rebuild incrementally if files changed."""
+        with self._lock:
+            current = self._scan_version()
+            if self._builder is None or current != self._version:
+                self._builder = self.commands.build_graph(self.project_path, incremental=True)
+                self._communities = detect_communities(self._builder.graph)
+                self._version = current
+            return self._builder
+
+    def community_of(self, node_id: str) -> int:
+        return self._communities.get(node_id, -1)
+
+    def version(self) -> Dict[str, Any]:
+        with self._lock:
+            v = self._scan_version()
+            return {"mtime": v[0], "files": v[1]}
+
+    # -- internals --
+
+    def _scan_version(self) -> Tuple[float, int]:
+        now = time.time()
+        if now - self._last_version_check < self.VERSION_CACHE_SECONDS:
+            return self._cached_version
+        files = self.commands._find_files(self.project_path)
+        max_mtime = 0.0
+        for f in files:
+            try:
+                m = f.stat().st_mtime
+                if m > max_mtime:
+                    max_mtime = m
+            except OSError:
+                continue
+        self._cached_version = (max_mtime, len(files))
+        self._last_version_check = now
+        return self._cached_version
+
+
+# ---- payload builders ----
+
+def _node_payload(
+    builder: CallGraphBuilder,
+    node_id: str,
+    service: Optional["GraphService"] = None,
+) -> Optional[Dict[str, Any]]:
+    node = builder._nodes.get(node_id)
+    if node is None:
+        return None
+    degree = (
+        builder.graph.in_degree(node_id) + builder.graph.out_degree(node_id)
+        if node_id in builder.graph else 0
+    )
+    return {
+        "id": node.id,
+        "qualified_name": node.qualified_name,
+        "name": node.name,
+        "type": node.node_type.name,
+        "module": node.module,
+        "file": node.file_path,
+        "line": node.line,
+        "column": node.column,
+        "is_async": node.is_async,
+        "is_entry_point": node.is_entry_point,
+        "decorators": list(node.decorators),
+        "signature": node.signature,
+        "docstring": node.docstring,
+        "contained_in": node.contained_in,
+        "calls_count": len(node.calls),
+        "called_by_count": len(node.called_by),
+        "degree": degree,
+        "community": service.community_of(node_id) if service else -1,
+    }
+
+
+def _edge_payload(
+    src: str,
+    dst: str,
+    etype: str,
+    confidence: float = 1.0,
+) -> Dict[str, Any]:
+    return {"source": src, "target": dst, "type": etype, "confidence": float(confidence)}
+
+
+def get_roots(builder: CallGraphBuilder, service: Optional["GraphService"] = None) -> Dict[str, Any]:
+    """Top-level: every MODULE node, with child counts."""
+    nodes: List[Dict[str, Any]] = []
+    for nid, n in builder._nodes.items():
+        if n.node_type != NodeType.MODULE:
+            continue
+        payload = _node_payload(builder, nid, service)
+        if payload is None:
+            continue
+        contains_count = sum(
+            1 for _, _, d in builder.graph.out_edges(nid, data=True)
+            if d.get("type") == EdgeType.CONTAINS.name
+        )
+        payload["children_count"] = contains_count
+        nodes.append(payload)
+    nodes.sort(key=lambda x: x["id"])
+    return {"nodes": nodes, "edges": []}
+
+
+def get_children(
+    builder: CallGraphBuilder,
+    node_id: str,
+    service: Optional["GraphService"] = None,
+) -> Dict[str, Any]:
+    """CONTAINS children of node_id."""
+    if node_id not in builder._nodes:
+        return {"nodes": [], "edges": []}
+    nodes: List[Dict[str, Any]] = []
+    edges: List[Dict[str, Any]] = []
+    for _, tgt, d in builder.graph.out_edges(node_id, data=True):
+        if d.get("type") != EdgeType.CONTAINS.name:
+            continue
+        payload = _node_payload(builder, tgt, service)
+        if payload is None:
+            continue
+        # children count for further expansion
+        child_count = sum(
+            1 for _, _, dd in builder.graph.out_edges(tgt, data=True)
+            if dd.get("type") == EdgeType.CONTAINS.name
+        )
+        payload["children_count"] = child_count
+        nodes.append(payload)
+        edges.append(_edge_payload(
+            node_id, tgt, EdgeType.CONTAINS.name, d.get("confidence", 1.0)
+        ))
+    nodes.sort(key=lambda x: (x["type"], x["name"]))
+    return {"nodes": nodes, "edges": edges}
+
+
+def get_neighbors(
+    builder: CallGraphBuilder,
+    node_id: str,
+    direction: str = "both",
+    service: Optional["GraphService"] = None,
+) -> Dict[str, Any]:
+    """Dependency edges incident to node_id (CALLS / REFERENCES / TYPE_OF /
+    RETURNS) — "callers" includes variable readers and type consumers."""
+    if node_id not in builder._nodes:
+        return {"nodes": [], "edges": []}
+    nodes: Dict[str, Dict[str, Any]] = {}
+    edges: List[Dict[str, Any]] = []
+    wanted = builder.IMPACT_EDGE_TYPES
+
+    if direction in ("callees", "both"):
+        for _, tgt, d in builder.graph.out_edges(node_id, data=True):
+            etype = d.get("type")
+            if etype not in wanted:
+                continue
+            payload = _node_payload(builder, tgt, service)
+            if payload is None:
+                continue
+            nodes[tgt] = payload
+            edges.append(_edge_payload(
+                node_id, tgt, etype, d.get("confidence", 1.0)
+            ))
+
+    if direction in ("callers", "both"):
+        for src, _, d in builder.graph.in_edges(node_id, data=True):
+            etype = d.get("type")
+            if etype not in wanted:
+                continue
+            payload = _node_payload(builder, src, service)
+            if payload is None:
+                continue
+            nodes[src] = payload
+            edges.append(_edge_payload(
+                src, node_id, etype, d.get("confidence", 1.0)
+            ))
+
+    return {"nodes": list(nodes.values()), "edges": edges}
+
+
+def search_nodes(builder: CallGraphBuilder, query: str, limit: int = 50) -> Dict[str, Any]:
+    if not query:
+        return {"matches": []}
+    q = query.lower()
+    matches: List[Dict[str, Any]] = []
+    for nid, n in builder._nodes.items():
+        if q in nid.lower() or q in n.name.lower():
+            matches.append({
+                "id": nid,
+                "name": n.name,
+                "type": n.node_type.name,
+                "module": n.module,
+                "file": n.file_path,
+                "line": n.line,
+            })
+            if len(matches) >= limit:
+                break
+    return {"matches": matches}
+
+
+# ---- HTTP handler ----
+
+class _Handler(BaseHTTPRequestHandler):
+    service: GraphService = None  # type: ignore[assignment]
+
+    def log_message(self, fmt: str, *args: Any) -> None:  # silence default logging
+        return
+
+    def _send_json(self, status: int, body: Any) -> None:
+        data = json.dumps(body, default=str).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(data)
+
+    def _send_file(self, path: Path, content_type: str) -> None:
+        try:
+            data = path.read_bytes()
+        except OSError:
+            self.send_error(HTTPStatus.NOT_FOUND)
+            return
+        self.send_response(HTTPStatus.OK)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        # Node ids contain characters (":", "(", ")", ",") that the client
+        # percent-encodes via encodeURIComponent — decode before matching
+        # against builder._nodes, or every id with such a character 404s.
+        path = unquote(parsed.path)
+        params = parse_qs(parsed.query)
+
+        try:
+            if path == "/" or path == "/index.html":
+                self._send_file(STATIC_DIR / "index.html", "text/html; charset=utf-8")
+                return
+
+            if path == "/api/version":
+                self._send_json(HTTPStatus.OK, self.service.version())
+                return
+
+            if path == "/api/roots":
+                builder = self.service.ensure_graph()
+                self._send_json(HTTPStatus.OK, get_roots(builder, self.service))
+                return
+
+            if path == "/api/stats":
+                builder = self.service.ensure_graph()
+                self._send_json(HTTPStatus.OK, builder.stats())
+                return
+
+            if path == "/api/search":
+                q = params.get("q", [""])[0]
+                builder = self.service.ensure_graph()
+                self._send_json(HTTPStatus.OK, search_nodes(builder, q))
+                return
+
+            if path.startswith("/api/node/"):
+                rest = path[len("/api/node/"):]
+                # /api/node/<id>           details
+                # /api/node/<id>/children  CONTAINS children
+                # /api/node/<id>/neighbors CALLS neighbors
+                if rest.endswith("/children"):
+                    nid = rest[:-len("/children")]
+                    builder = self.service.ensure_graph()
+                    self._send_json(HTTPStatus.OK, get_children(builder, nid, self.service))
+                    return
+                if rest.endswith("/neighbors"):
+                    nid = rest[:-len("/neighbors")]
+                    direction = params.get("direction", ["both"])[0]
+                    builder = self.service.ensure_graph()
+                    self._send_json(HTTPStatus.OK, get_neighbors(builder, nid, direction, self.service))
+                    return
+                # plain details
+                builder = self.service.ensure_graph()
+                payload = _node_payload(builder, rest, self.service)
+                if payload is None:
+                    self._send_json(HTTPStatus.NOT_FOUND, {"error": "not found", "id": rest})
+                    return
+                self._send_json(HTTPStatus.OK, payload)
+                return
+
+            self.send_error(HTTPStatus.NOT_FOUND)
+        except Exception as e:  # noqa: BLE001
+            self._send_json(HTTPStatus.INTERNAL_SERVER_ERROR, {"error": str(e)})
+
+
+def serve(project_path: Path, host: str = "127.0.0.1", port: int = 8765) -> None:
+    """Block and serve. Triggers initial graph build."""
+    service = GraphService(project_path)
+    # Warm the graph so the first browser request is fast
+    service.ensure_graph()
+
+    handler_cls = type("Handler", (_Handler,), {"service": service})
+    httpd = ThreadingHTTPServer((host, port), handler_cls)
+    url = f"http://{host}:{port}/"
+    print(f"ADL Drift graph viz listening on {url}")
+    print(f"Project: {project_path}")
+    print("Ctrl-C to stop.")
+    try:
+        httpd.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopping...")
+    finally:
+        httpd.server_close()

package/adl_drift/utils/__init__.py

@@ -0,0 +1 @@
+"""Shared utilities."""

package/adl_drift/utils/config.py

@@ -0,0 +1,77 @@
+"""Project configuration & framework auto-detection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set, Tuple
+
+
+PROJECT_ROOT_MARKERS = (
+    "pyproject.toml",
+    "pom.xml",
+    "build.gradle",
+    "build.gradle.kts",
+    "settings.gradle",
+    "settings.gradle.kts",
+    ".git",
+    "setup.py",
+    "setup.cfg",
+)
+
+
+def find_project_root(start: Path) -> Optional[Path]:
+    """Return the nearest directory containing a supported project marker."""
+    start = Path(start)
+    if start.is_file():
+        start = start.parent
+    for path in (start, *start.parents):
+        if any((path / marker).exists() for marker in PROJECT_ROOT_MARKERS):
+            return path
+    return None
+
+
+FRAMEWORK_MARKERS = {
+    "flask": ["flask"],
+    "fastapi": ["fastapi"],
+    "django": ["django"],
+    "sqlalchemy": ["sqlalchemy"],
+    "pydantic": ["pydantic"],
+    "pytest": ["pytest"],
+    "celery": ["celery"],
+}
+
+
+class ProjectConfig:
+    """Auto-detects project frameworks from pyproject.toml / requirements.txt."""
+
+    def __init__(self, project_path: Path):
+        self.project_path = Path(project_path)
+        self.frameworks: List[str] = []
+        # Dependency files read, with (st_mtime_ns, st_size) at read time —
+        # see JavaProjectConfig.build_file_stats.
+        self.build_file_stats: Dict[str, Tuple[int, int]] = {}
+        self._detect()
+
+    def _detect(self) -> None:
+        text = self._read_dep_text().lower()
+        found: Set[str] = set()
+        for fw, markers in FRAMEWORK_MARKERS.items():
+            if any(m in text for m in markers):
+                found.add(fw)
+        self.frameworks = sorted(found)
+
+    def _read_dep_text(self) -> str:
+        chunks: List[str] = []
+        for fname in ("pyproject.toml", "requirements.txt", "setup.py", "Pipfile"):
+            fpath = self.project_path / fname
+            if fpath.is_file():
+                try:
+                    stat = fpath.stat()
+                    chunks.append(fpath.read_text(encoding="utf-8", errors="ignore"))
+                    self.build_file_stats[str(fpath)] = (stat.st_mtime_ns, stat.st_size)
+                except OSError:
+                    pass
+        return "\n".join(chunks)
+
+    def has_framework(self, name: str) -> bool:
+        return name.lower() in self.frameworks

package/adl_drift/utils/fswalk.py

@@ -0,0 +1,52 @@
+"""Directory traversal shared by source discovery and backend detection.
+
+MCP_GRAPH_CACHE_PLAN.md Lớp 2. ``Path.rglob`` and ``os.walk`` both cost one
+extra ``lstat`` per directory on Python 3.10 (``os.walk`` re-checks
+``islink(new_path)`` before descending — see CPython issue 23605 — and
+``rglob`` resolves nothing but visits the tree once per pattern). On a slow
+filesystem that syscall dominates a no-op MCP query, so this walker takes
+every type/symlink answer from ``os.DirEntry`` (``d_type``) and touches the
+kernel exactly once per directory.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator, List, Tuple
+
+
+def iter_tree(top: str) -> Iterator[Tuple[str, List[os.DirEntry], List[os.DirEntry]]]:
+    """Depth-first walk of ``top`` that never follows directory symlinks —
+    the traversal ``Path.rglob`` and ``os.walk(followlinks=False)`` perform.
+
+    Yields ``(dirpath, dirs, others)``:
+
+    * ``dirs`` — real subdirectories. The consumer may prune this list in
+      place before the next iteration to skip subtrees.
+    * ``others`` — every other entry ``rglob`` would have yielded as a
+      match candidate: regular files, symlinks to files, dangling symlinks
+      **and** symlinks to directories (which are listed but never entered).
+
+    Unreadable or vanished directories are skipped silently, as ``rglob``
+    and ``os.walk`` skip them.
+    """
+    stack = [top]
+    while stack:
+        dirpath = stack.pop()
+        try:
+            with os.scandir(dirpath) as scandir_it:
+                entries = list(scandir_it)
+        except OSError:
+            continue
+        dirs: List[os.DirEntry] = []
+        others: List[os.DirEntry] = []
+        for entry in entries:
+            try:
+                if entry.is_dir(follow_symlinks=False):
+                    dirs.append(entry)
+                else:
+                    others.append(entry)
+            except OSError:
+                continue
+        yield dirpath, dirs, others
+        stack.extend(entry.path for entry in dirs)