graphlens-cli 0.4.0__tar.gz

graphlens_cli-0.4.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: graphlens-cli
+Version: 0.4.0
+Summary: Command-line interface for graphlens code analysis
+Requires-Dist: graphlens
+Requires-Dist: typer[all]>=0.15
+Requires-Dist: graphlens-python ; extra == 'all'
+Requires-Dist: graphlens-typescript ; extra == 'all'
+Requires-Dist: neo4j ; extra == 'all'
+Requires-Dist: neo4j ; extra == 'neo4j'
+Requires-Dist: graphlens-python ; extra == 'python'
+Requires-Dist: graphlens-typescript ; extra == 'typescript'
+Requires-Python: >=3.13
+Provides-Extra: all
+Provides-Extra: neo4j
+Provides-Extra: python
+Provides-Extra: typescript

graphlens_cli-0.4.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "graphlens-cli"
+version = "0.4.0"
+description = "Command-line interface for graphlens code analysis"
+requires-python = ">=3.13"
+dependencies = [
+    "graphlens",
+    "typer[all]>=0.15",
+]
+
+[project.optional-dependencies]
+python = ["graphlens-python"]
+typescript = ["graphlens-typescript"]
+neo4j = ["neo4j"]
+all = ["graphlens-python", "graphlens-typescript", "neo4j"]
+
+[project.scripts]
+graphlens = "graphlens_cli:app"
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+graphlens = { workspace = true }
+graphlens-python = { workspace = true }
+graphlens-typescript = { workspace = true }
+
+[tool.bandit]
+skips = ["B101", "B110", "B107"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["graphlens_cli"]
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "\\.\\.\\.",
+]

graphlens_cli-0.4.0/src/graphlens_cli/__init__.py

@@ -0,0 +1,8 @@
+"""graphlens-cli — command-line interface for graphlens code analysis."""
+
+import graphlens_cli._analyze
+import graphlens_cli._neo4j
+import graphlens_cli._visualize  # noqa: F401  — registers visualize command
+from graphlens_cli._app import app
+
+__all__ = ["app"]

graphlens_cli-0.4.0/src/graphlens_cli/_analyze.py

@@ -0,0 +1,80 @@
+"""graphlens analyze — print graph statistics."""
+
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from graphlens import NodeKind, RelationKind
+
+from graphlens_cli._app import app, resolve_langs, run_analysis
+
+
+@app.command()
+def analyze(
+    root: Annotated[
+        Path,
+        typer.Argument(
+            help="Project root to analyse",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ],
+    lang: Annotated[
+        str,
+        typer.Option(
+            help=(
+                "Adapter(s) to use: auto | python | typescript"
+                " | python,typescript"
+            ),
+            show_default=True,
+        ),
+    ] = "auto",
+) -> None:
+    """Print node and relation statistics for a project."""
+    langs = resolve_langs(lang, root)
+    typer.echo(f"Analysing {root}  [lang={', '.join(langs)}]\n")
+
+    graph, elapsed = run_analysis(root, langs)
+    nodes = graph.nodes
+
+    typer.echo(
+        f"{len(nodes)} nodes  ·  "
+        f"{len(graph.relations)} relations  ·  "
+        f"{elapsed:.2f}s\n"
+    )
+
+    by_kind = Counter(n.kind.value for n in nodes.values())
+    typer.echo("Nodes by kind:")
+    for k, c in by_kind.most_common():
+        typer.echo(f"  {k:<20} {c}")
+
+    by_rel = Counter(r.kind.value for r in graph.relations)
+    typer.echo("\nRelations by kind:")
+    for k, c in by_rel.most_common():
+        typer.echo(f"  {k:<20} {c}")
+
+    ext_origin = Counter(
+        str(n.metadata.get("origin", "?"))
+        for n in nodes.values()
+        if n.kind == NodeKind.EXTERNAL_SYMBOL
+    )
+    if ext_origin:
+        typer.echo("\nExternal symbols by origin:")
+        for o, c in ext_origin.most_common():
+            typer.echo(f"  {o:<20} {c}")
+
+    caller_counts: Counter[str] = Counter()
+    for r in graph.relations:
+        if r.kind == RelationKind.CALLS:
+            caller_counts[r.source_id] += 1
+
+    if caller_counts:
+        typer.echo("\nTop callers (by outgoing CALLS):")
+        for nid, count in caller_counts.most_common(10):
+            n = nodes.get(nid)
+            name = n.qualified_name if n else nid
+            typer.echo(f"  {count:>4}  {name}")

graphlens_cli-0.4.0/src/graphlens_cli/_app.py

@@ -0,0 +1,113 @@
+"""graphlens CLI — typer app and shared analysis helpers."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+import typer
+from graphlens import GraphLens, adapter_registry
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from graphlens.contracts import LanguageAdapter
+
+app = typer.Typer(
+    name="graphlens",
+    help="Polyglot code graph analysis and export.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+)
+
+
+def resolve_langs(lang: str, root: Path) -> list[str]:
+    """
+    Expand the *lang* value to a concrete list of adapter names.
+
+    ``"auto"`` queries the adapter registry and filters by ``can_handle``.
+    Any other value is split on commas and returned as-is.
+    """
+    if lang != "auto":
+        return [s.strip() for s in lang.split(",") if s.strip()]
+
+    available = adapter_registry.available()
+    if not available:
+        msg = (
+            "No graphlens adapters installed. "
+            "Install graphlens-python or graphlens-typescript."
+        )
+        raise typer.BadParameter(msg)
+
+    matched: list[str] = []
+    for name in available:
+        try:
+            if adapter_registry.load(name)().can_handle(root):
+                matched.append(name)
+        except Exception:
+            pass
+    if not matched:
+        msg = (
+            f"No adapter can handle {root}. "
+            f"Available: {available}. "
+            "Use --lang to specify explicitly."
+        )
+        raise typer.BadParameter(msg)
+    return matched
+
+
+def load_adapter(lang: str) -> LanguageAdapter:
+    """
+    Return an initialised adapter for *lang*.
+
+    Tries the registry first; falls back to direct import for adapters that
+    may not yet be registered via entry points.
+    """
+    try:
+        return adapter_registry.load(lang)()
+    except Exception:
+        pass
+
+    if lang == "python":
+        from graphlens_python import PythonAdapter
+
+        return PythonAdapter()
+    if lang == "typescript":
+        from graphlens_typescript import TypescriptAdapter
+
+        return TypescriptAdapter()
+
+    msg = f"Unknown or unavailable adapter: {lang!r}"
+    raise typer.BadParameter(msg)
+
+
+def merge_graph(target: GraphLens, source: GraphLens) -> None:
+    """Merge *source* into *target* in-place, skipping duplicate node IDs."""
+    for nid, node in source.nodes.items():
+        if nid not in target.nodes:
+            target.add_node(node)
+    for rel in source.relations:
+        target.add_relation(rel)
+
+
+def run_analysis(
+    root: Path,
+    langs: list[str],
+    *,
+    verbose: bool = True,
+) -> tuple[GraphLens, float]:
+    """Analyse *root* with each adapter; return merged graph and elapsed."""
+    combined = GraphLens()
+    t0 = time.monotonic()
+    for lang in langs:
+        if verbose:
+            typer.echo(f"  [{lang}] analysing {root} …")
+        adapter = load_adapter(lang)
+        g = adapter.analyze(root)
+        if verbose:
+            typer.echo(
+                f"  [{lang}] {len(g.nodes)} nodes,"
+                f" {len(g.relations)} relations"
+            )
+        merge_graph(combined, g)
+    return combined, time.monotonic() - t0

graphlens_cli-0.4.0/src/graphlens_cli/_neo4j.py

@@ -0,0 +1,214 @@
+"""graphlens neo4j — export a code graph to Neo4j."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterator
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated, Any
+
+import typer
+
+from graphlens_cli._app import app, resolve_langs, run_analysis
+
+if TYPE_CHECKING:
+    from neo4j import Driver
+
+# ---------------------------------------------------------------------------
+# Serialisation helpers
+# ---------------------------------------------------------------------------
+
+_SIMPLE_TYPES = (str, int, float, bool)
+
+_CONSTRAINT_CYPHER = """\
+CREATE CONSTRAINT code_node_id IF NOT EXISTS
+FOR (n:Code) REQUIRE n.id IS UNIQUE
+"""
+
+_WIPE_CYPHER = "MATCH (n:Code) DETACH DELETE n"
+
+_NODE_CYPHER = """\
+UNWIND $batch AS props
+MERGE (n:Code {{id: props.id}})
+SET n += props, n:{label}
+"""
+
+_REL_CYPHER = """\
+UNWIND $batch AS row
+MATCH (src:Code {{id: row.source_id}})
+MATCH (dst:Code {{id: row.target_id}})
+MERGE (src)-[r:{rel_type}]->(dst)
+SET r += row.props
+"""
+
+
+def _node_props(node: Any) -> dict[str, Any]:
+    """Flatten a graphlens Node into Neo4j-safe scalar properties."""
+    props: dict[str, Any] = {
+        "id": node.id,
+        "kind": node.kind.value,
+        "name": node.name,
+        "qualified_name": node.qualified_name,
+    }
+    if node.file_path is not None:
+        props["file_path"] = node.file_path
+    if node.span is not None:
+        props["span_start_line"] = node.span.start_line
+        props["span_start_col"] = node.span.start_col
+        props["span_end_line"] = node.span.end_line
+        props["span_end_col"] = node.span.end_col
+    for k, v in node.metadata.items():
+        if isinstance(v, _SIMPLE_TYPES):
+            props[f"meta_{k}"] = v
+    return props
+
+
+def _rel_props(rel: Any) -> dict[str, Any]:
+    """Flatten relation metadata into Neo4j-safe scalar properties."""
+    return {
+        f"meta_{k}": v
+        for k, v in rel.metadata.items()
+        if isinstance(v, _SIMPLE_TYPES)
+    }
+
+
+def _node_label(node: Any) -> str:
+    """Map NodeKind to a PascalCase Neo4j label (e.g. ExternalSymbol)."""
+    return node.kind.value.replace("_", " ").title().replace(" ", "")
+
+
+def _batches(items: list[Any], size: int) -> Iterator[list[Any]]:
+    """Yield successive *size*-length slices of *items*."""
+    for i in range(0, len(items), size):
+        yield items[i : i + size]
+
+
+def _import_nodes(driver: Driver, nodes: list[Any], batch_size: int) -> int:
+    """Merge all *nodes* into Neo4j; return the total count written."""
+    by_label: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for n in nodes:
+        by_label[_node_label(n)].append(_node_props(n))
+
+    total = 0
+    with driver.session() as session:
+        for lbl, props_list in by_label.items():
+            cypher = _NODE_CYPHER.format(label=lbl)
+            for batch in _batches(props_list, batch_size):
+                session.run(cypher, batch=batch)
+                total += len(batch)
+    return total
+
+
+def _import_relations(
+    driver: Driver, relations: list[Any], batch_size: int
+) -> int:
+    """Merge all *relations* into Neo4j grouped by type; return count."""
+    by_type: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for r in relations:
+        by_type[r.kind.value.upper()].append({
+            "source_id": r.source_id,
+            "target_id": r.target_id,
+            "props": _rel_props(r),
+        })
+
+    total = 0
+    with driver.session() as session:
+        for rel_type, rows in by_type.items():
+            cypher = _REL_CYPHER.format(rel_type=rel_type)
+            for batch in _batches(rows, batch_size):
+                session.run(cypher, batch=batch)
+                total += len(batch)
+    return total
+
+
+# ---------------------------------------------------------------------------
+# CLI command
+# ---------------------------------------------------------------------------
+
+@app.command()
+def neo4j(
+    root: Annotated[
+        Path,
+        typer.Argument(
+            help="Project root to analyse",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ],
+    lang: Annotated[
+        str,
+        typer.Option(
+            help="Adapter(s): auto | python | typescript | python,typescript",
+            show_default=True,
+        ),
+    ] = "auto",
+    uri: Annotated[
+        str,
+        typer.Option(help="Neo4j Bolt URI", show_default=True),
+    ] = "bolt://localhost:7687",
+    user: Annotated[
+        str,
+        typer.Option(help="Neo4j username", show_default=True),
+    ] = "neo4j",
+    password: Annotated[
+        str,
+        typer.Option(help="Neo4j password", show_default=True),
+    ] = "password",
+    wipe: Annotated[
+        bool,
+        typer.Option("--wipe/--no-wipe", help="Wipe :Code nodes first"),
+    ] = False,
+    batch_size: Annotated[
+        int,
+        typer.Option("--batch-size", help="Items per Cypher batch", min=1),
+    ] = 500,
+) -> None:
+    """Export a code graph to a running Neo4j instance."""
+    try:
+        from neo4j import GraphDatabase
+    except ImportError:
+        typer.echo(
+            "neo4j driver not installed. Run:  pip install neo4j",
+            err=True,
+        )
+        raise typer.Exit(1) from None
+
+    langs = resolve_langs(lang, root)
+    typer.echo(f"Analysing {root}  [lang={', '.join(langs)}]")
+    graph, elapsed = run_analysis(root, langs)
+    typer.echo(
+        f"  {len(graph.nodes)} nodes, {len(graph.relations)} relations"
+        f"  ({elapsed:.2f}s)\n"
+    )
+
+    typer.echo(f"Connecting to {uri} …")
+    driver = GraphDatabase.driver(uri, auth=(user, password))
+    try:
+        driver.verify_connectivity()
+    except Exception as exc:
+        typer.echo(f"error: cannot connect to Neo4j: {exc}", err=True)
+        driver.close()
+        raise typer.Exit(1) from exc
+
+    with driver.session() as session:
+        session.run(_CONSTRAINT_CYPHER)
+        if wipe:
+            result = session.run(_WIPE_CYPHER)
+            deleted = result.consume().counters.nodes_deleted
+            typer.echo(f"  wiped {deleted} existing :Code nodes\n")
+
+    import time as _time
+
+    typer.echo("Importing nodes …")
+    t1 = _time.monotonic()
+    n_nodes = _import_nodes(driver, list(graph.nodes.values()), batch_size)
+    typer.echo(f"  {n_nodes} nodes  ({_time.monotonic() - t1:.2f}s)")
+
+    typer.echo("Importing relations …")
+    t2 = _time.monotonic()
+    n_rels = _import_relations(driver, graph.relations, batch_size)
+    typer.echo(f"  {n_rels} relations  ({_time.monotonic() - t2:.2f}s)")
+
+    driver.close()
+    typer.echo("\nDone.  Explore at http://localhost:7474")

graphlens_cli-0.4.0/src/graphlens_cli/_visualize.py

@@ -0,0 +1,631 @@
+"""graphlens visualize — interactive HTML code-graph viewer."""
+
+from __future__ import annotations
+
+import json
+import webbrowser
+from collections import defaultdict
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from graphlens import GraphLens, NodeKind, RelationKind
+
+from graphlens_cli._app import app, resolve_langs, run_analysis
+
+# ---------------------------------------------------------------------------
+# Visual style constants
+# ---------------------------------------------------------------------------
+
+_NODE_COLOR: dict[str, str] = {
+    "project":         "#FFD700",
+    "module":          "#4A90D9",
+    "file":            "#7BB3E0",
+    "class":           "#5CB85C",
+    "function":        "#F0A830",
+    "method":          "#F5C842",
+    "parameter":       "#AAAAAA",
+    "import":          "#9B59B6",
+    "external_symbol": "#888888",
+    "dependency":      "#FF6B9D",
+    "variable":        "#7FC97F",
+    "attribute":       "#A8D8A8",
+    "type_alias":      "#DDA0DD",
+}
+
+_ORIGIN_COLOR: dict[str, str] = {
+    "stdlib":      "#606060",
+    "third_party": "#994444",
+    "internal":    "#3A6080",
+    "unknown":     "#555555",
+}
+
+_EDGE_COLOR: dict[str, str] = {
+    "contains":      "#444466",
+    "declares":      "#444466",
+    "calls":         "#E74C3C",
+    "references":    "#E67E22",
+    "inherits_from": "#8E44AD",
+    "has_type":      "#2980B9",
+    "imports":       "#27AE60",
+    "resolves_to":   "#1A7A40",
+    "depends_on":    "#FF6B9D",
+}
+
+_NODE_SHAPE: dict[NodeKind, str] = {
+    NodeKind.PROJECT:         "star",
+    NodeKind.MODULE:          "box",
+    NodeKind.FILE:            "box",
+    NodeKind.CLASS:           "ellipse",
+    NodeKind.FUNCTION:        "dot",
+    NodeKind.METHOD:          "dot",
+    NodeKind.PARAMETER:       "triangle",
+    NodeKind.IMPORT:          "diamond",
+    NodeKind.EXTERNAL_SYMBOL: "square",
+    NodeKind.DEPENDENCY:      "hexagon",
+    NodeKind.VARIABLE:        "triangleDown",
+    NodeKind.ATTRIBUTE:       "triangleDown",
+    NodeKind.TYPE_ALIAS:      "diamond",
+}
+
+_STRUCTURAL = {RelationKind.CONTAINS, RelationKind.DECLARES}
+
+# ---------------------------------------------------------------------------
+# Graph → vis.js data
+# ---------------------------------------------------------------------------
+
+
+def build_vis_data(
+    graph: GraphLens,
+    *,
+    show_external: bool = False,
+    show_structure: bool = False,
+    max_nodes: int = 1500,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """
+    Convert a *graph* into vis.js-compatible node/edge dicts.
+
+    Nodes above *max_nodes* are pruned by degree (lowest first), but
+    PROJECT/MODULE/FILE nodes are always kept.
+    """
+    nodes_map = graph.nodes
+
+    degree: dict[str, int] = defaultdict(int)
+    for r in graph.relations:
+        degree[r.source_id] += 1
+        degree[r.target_id] += 1
+
+    candidate_ids: set[str] = set()
+    for nid, node in nodes_map.items():
+        if node.kind == NodeKind.EXTERNAL_SYMBOL and not show_external:
+            continue
+        candidate_ids.add(nid)
+
+    if len(candidate_ids) > max_nodes:
+        pinned = {
+            nid
+            for nid in candidate_ids
+            if nodes_map[nid].kind
+            in (NodeKind.PROJECT, NodeKind.MODULE, NodeKind.FILE)
+        }
+        others = sorted(
+            candidate_ids - pinned,
+            key=lambda nid: degree[nid],
+            reverse=True,
+        )
+        cap = max(0, max_nodes - len(pinned))
+        candidate_ids = pinned | set(others[:cap])
+
+    vis_nodes: list[dict[str, Any]] = []
+    for nid in candidate_ids:
+        node = nodes_map[nid]
+        kind = node.kind.value
+
+        if node.kind == NodeKind.EXTERNAL_SYMBOL:
+            origin = str(node.metadata.get("origin", "unknown"))
+            bg = _ORIGIN_COLOR.get(origin, "#555555")
+        else:
+            bg = _NODE_COLOR.get(kind, "#888888")
+
+        meta_skip = {"name_span"}
+        meta_lines = "".join(
+            f"<br/><span style='color:#aaa'>{k}:</span> {v}"
+            for k, v in node.metadata.items()
+            if k not in meta_skip
+        )
+        is_callable = node.kind in (NodeKind.FUNCTION, NodeKind.METHOD)
+        callers_btn = (
+            "<br/><br/>"
+            "<button onclick=\"showCallers('"
+            + nid
+            + "',this)\" "
+            "style='background:#1f2937;border:1px solid #e94560;color:#ff7b7b;"
+            "padding:4px 10px;border-radius:4px;cursor:pointer;font-size:11px'>"
+            "Show callers</button>"
+        ) if is_callable else ""
+
+        tooltip = (
+            "<div style='font-family:monospace;max-width:320px'>"
+            f"<b style='color:#FFD700'>{node.qualified_name}</b>"
+            f"<br/><i style='color:#aaa'>{kind}</i>"
+            f"{meta_lines}"
+            f"{callers_btn}"
+            "</div>"
+        )
+
+        label = node.name or node.qualified_name.split(".")[-1] or kind
+        vis_nodes.append({
+            "id":    nid,
+            "label": label,
+            "title": tooltip,
+            "color": {
+                "background": bg,
+                "border":     "#222",
+                "highlight":  {"background": bg, "border": "#fff"},
+                "hover":      {"background": bg, "border": "#eee"},
+            },
+            "group": kind,
+            "shape": _NODE_SHAPE.get(node.kind, "dot"),
+            "font":  {"size": 12, "color": "#e0e0e0"},
+        })
+
+    vis_edges: list[dict[str, Any]] = []
+    for idx, rel in enumerate(graph.relations):
+        if (
+            rel.source_id not in candidate_ids
+            or rel.target_id not in candidate_ids
+        ):
+            continue
+        if rel.kind in _STRUCTURAL and not show_structure:
+            continue
+        kind = rel.kind.value
+        color = _EDGE_COLOR.get(kind, "#666666")
+        is_structural = rel.kind in _STRUCTURAL
+        vis_edges.append({
+            "id":     idx,
+            "from":   rel.source_id,
+            "to":     rel.target_id,
+            "_kind":  kind,
+            "title":  kind,
+            "color":  {
+                "color":     color,
+                "highlight": color,
+                "hover":     "#ffffff",
+                "opacity":   0.75,
+            },
+            "arrows": "to",
+            "width":  1 if is_structural else 2,
+            "dashes": is_structural,
+        })
+
+    return vis_nodes, vis_edges
+
+
+# ---------------------------------------------------------------------------
+# HTML rendering
+# ---------------------------------------------------------------------------
+
+
+def render_html(
+    project_name: str,
+    vis_nodes: list[dict[str, Any]],
+    vis_edges: list[dict[str, Any]],
+    stats: dict[str, Any],
+) -> str:
+    """Render a self-contained vis.js HTML page for the given graph data."""
+    nodes_json = json.dumps(vis_nodes, ensure_ascii=False)
+    edges_json = json.dumps(vis_edges, ensure_ascii=False)
+
+    node_kinds = sorted({n["group"] for n in vis_nodes})
+    edge_kinds = sorted({e["_kind"] for e in vis_edges})
+
+    def node_filter_row(k: str) -> str:
+        color = _NODE_COLOR.get(k, "#888")
+        return (
+            f'<label class="filter-row">'
+            f'<input type="checkbox" class="nf" value="{k}" checked>'
+            f'<span class="chip" style="background:{color}"></span>'
+            f"{k}</label>"
+        )
+
+    def edge_filter_row(k: str) -> str:
+        color = _EDGE_COLOR.get(k, "#666")
+        return (
+            f'<label class="filter-row">'
+            f'<input type="checkbox" class="ef" value="{k}" checked>'
+            f'<span class="chip" style="background:{color}"></span>'
+            f"{k}</label>"
+        )
+
+    node_filters = "\n".join(node_filter_row(k) for k in node_kinds)
+    edge_filters = "\n".join(edge_filter_row(k) for k in edge_kinds)
+    is_pruned = len(vis_nodes) < stats.get("total_nodes", 0)
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>graphlens — {project_name}</title>
+<script src="https://unpkg.com/vis-network@9.1.9/standalone/umd/vis-network.min.js"></script>
+<style>
+* {{ box-sizing: border-box; margin: 0; padding: 0; }}
+body {{ display: flex; height: 100vh; font-family: -apple-system,system-ui,sans-serif;
+       background: #0d1117; color: #c9d1d9; overflow: hidden; }}
+#sidebar {{
+  width: 220px; min-width: 220px; background: #161b22;
+  border-right: 1px solid #30363d; display: flex; flex-direction: column;
+  overflow: hidden;
+}}
+#sidebar-header {{ padding: 12px; border-bottom: 1px solid #30363d; flex-shrink: 0; }}
+#sidebar-header h2 {{ font-size: 11px; text-transform: uppercase; letter-spacing: 1px;
+                      color: #e94560; margin-bottom: 4px; }}
+#project-name {{ font-size: 13px; font-weight: 600; color: #FFD700;
+                 word-break: break-all; line-height: 1.3; }}
+#sidebar-body {{ flex: 1; overflow-y: auto; padding: 10px; display: flex;
+                 flex-direction: column; gap: 12px; }}
+.stats-grid {{ display: grid; grid-template-columns: 1fr auto; gap: 2px 8px; font-size: 11px; }}
+.stats-grid .k {{ color: #8b949e; }}
+.stats-grid .v {{ color: #e6edf3; font-weight: 600; text-align: right; }}
+.section-title {{ font-size: 10px; text-transform: uppercase; letter-spacing: 0.8px;
+                  color: #8b949e; margin-bottom: 4px; }}
+.filter-section {{ display: flex; flex-direction: column; gap: 1px; }}
+.filter-row {{ display: flex; align-items: center; gap: 6px; font-size: 11px;
+               cursor: pointer; padding: 2px 3px; border-radius: 3px; }}
+.filter-row:hover {{ background: #21262d; }}
+.filter-row input {{ cursor: pointer; accent-color: #58a6ff; }}
+.chip {{ width: 8px; height: 8px; border-radius: 2px; flex-shrink: 0; }}
+.btn-group {{ display: flex; flex-direction: column; gap: 4px; }}
+.btn {{
+  background: #21262d; border: 1px solid #30363d; color: #c9d1d9;
+  padding: 5px 8px; border-radius: 6px; cursor: pointer; font-size: 11px;
+  text-align: left; transition: background 0.15s;
+}}
+.btn:hover {{ background: #30363d; }}
+.btn.primary {{ border-color: #e94560; color: #ff7b7b; }}
+.btn.primary:hover {{ background: #e94560; color: #fff; }}
+#search {{ width: 100%; background: #0d1117; border: 1px solid #30363d; color: #c9d1d9;
+           padding: 5px 8px; border-radius: 6px; font-size: 11px; }}
+#search::placeholder {{ color: #484f58; }}
+#search:focus {{ outline: none; border-color: #58a6ff; }}
+#callers-panel {{ display: none; flex-direction: column; gap: 4px; }}
+#callers-list {{ display: flex; flex-direction: column; gap: 1px;
+                 max-height: 300px; overflow-y: auto; }}
+.caller-row {{
+  font-size: 11px; padding: 3px 6px; border-radius: 3px; cursor: pointer;
+  color: #c9d1d9; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}}
+.caller-row:hover {{ background: #21262d; }}
+.caller-row .caller-kind {{ color: #E74C3C; font-size: 10px; margin-right: 4px; }}
+#graph-wrap {{ flex: 1; display: flex; flex-direction: column; position: relative; }}
+#focus-bar {{
+  display: none; align-items: center; gap: 10px;
+  padding: 7px 14px; background: #1c2128; border-bottom: 1px solid #e94560;
+  flex-shrink: 0;
+}}
+#focus-bar .back-btn {{
+  background: none; border: 1px solid #e94560; color: #ff7b7b;
+  padding: 3px 10px; border-radius: 4px; cursor: pointer; font-size: 11px;
+}}
+#focus-bar .back-btn:hover {{ background: #e94560; color: #fff; }}
+#focus-label {{ font-size: 12px; color: #c9d1d9; }}
+#focus-count {{ font-size: 11px; color: #8b949e; margin-left: auto; }}
+#graph {{ flex: 1; position: relative; }}
+#info-panel {{
+  position: absolute; bottom: 16px; right: 16px;
+  background: #161b22; border: 1px solid #30363d; border-radius: 8px;
+  padding: 12px 14px; max-width: 380px; font-size: 12px;
+  display: none; z-index: 10; box-shadow: 0 4px 20px rgba(0,0,0,0.5);
+  max-height: 50vh; overflow-y: auto;
+}}
+#info-panel b {{ color: #FFD700; }}
+#info-close {{ float: right; cursor: pointer; color: #8b949e; font-size: 14px; line-height: 1; }}
+#info-close:hover {{ color: #fff; }}
+#pruned-warning {{
+  position: absolute; top: 10px; right: 10px;
+  background: #3d1f00; border: 1px solid #e67e22; border-radius: 6px;
+  padding: 6px 10px; font-size: 11px; color: #e67e22; z-index: 10;
+  display: {"block" if is_pruned else "none"};
+}}
+</style>
+</head>
+<body>
+<div id="sidebar">
+  <div id="sidebar-header">
+    <h2>graphlens</h2>
+    <div id="project-name">{project_name}</div>
+  </div>
+  <div id="sidebar-body">
+    <div>
+      <div class="section-title">Visible</div>
+      <div class="stats-grid">
+        <span class="k">Nodes</span><span class="v" id="s-nodes">{len(vis_nodes)}</span>
+        <span class="k">Edges</span><span class="v" id="s-edges">{len(vis_edges)}</span>
+      </div>
+    </div>
+    <div>
+      <div class="section-title">Total (analysed)</div>
+      <div class="stats-grid">
+        <span class="k">Nodes</span><span class="v">{stats.get("total_nodes", 0)}</span>
+        <span class="k">Edges</span><span class="v">{stats.get("total_relations", 0)}</span>
+        <span class="k">Lang</span><span class="v">{stats.get("lang", "?")}</span>
+        <span class="k">Time</span><span class="v">{stats.get("elapsed", 0):.2f}s</span>
+      </div>
+    </div>
+    <div>
+      <div class="section-title">Search</div>
+      <input id="search" type="text" placeholder="Filter by label…"/>
+    </div>
+    <div id="normal-filters">
+      <div>
+        <div class="section-title">Node kinds</div>
+        <div class="filter-section" id="node-filters">
+{node_filters}
+        </div>
+      </div>
+      <div>
+        <div class="section-title">Edge kinds</div>
+        <div class="filter-section" id="edge-filters">
+{edge_filters}
+        </div>
+      </div>
+    </div>
+    <div id="callers-panel">
+      <div class="section-title" id="callers-title">Callers</div>
+      <div id="callers-list"></div>
+    </div>
+    <div>
+      <div class="section-title">Controls</div>
+      <div class="btn-group">
+        <button class="btn primary" onclick="network.fit()">Fit to screen</button>
+        <button class="btn" id="physics-btn" onclick="togglePhysics()">Disable physics</button>
+        <button class="btn" onclick="selectAll(true)">Check all</button>
+        <button class="btn" onclick="selectAll(false)">Uncheck all</button>
+      </div>
+    </div>
+  </div>
+</div>
+<div id="graph-wrap">
+  <div id="focus-bar">
+    <button class="back-btn" onclick="exitFocus()">← Back</button>
+    <span id="focus-label"></span>
+    <span id="focus-count"></span>
+  </div>
+  <div id="graph">
+    <div id="pruned-warning">
+      ⚠ Showing {len(vis_nodes)} / {stats.get("total_nodes", 0)} nodes (--max-nodes to adjust)
+    </div>
+  </div>
+</div>
+<div id="info-panel">
+  <span id="info-close" onclick="closeInfo()">✕</span>
+  <div id="info-body"></div>
+</div>
+<script>
+var ALL_NODES = {nodes_json};
+var ALL_EDGES = {edges_json};
+var nodesDS = new vis.DataSet(ALL_NODES);
+var edgesDS = new vis.DataSet(ALL_EDGES);
+var options = {{
+  nodes: {{ borderWidth: 1, size: 14, font: {{ size: 12, color: "#c9d1d9" }} }},
+  edges: {{
+    smooth: {{ type: "dynamic" }},
+    font: {{ size: 10, color: "#8b949e", align: "middle" }},
+    selectionWidth: 3,
+  }},
+  physics: {{
+    enabled: true,
+    stabilization: {{ iterations: 200, fit: true }},
+    barnesHut: {{
+      gravitationalConstant: -4000, springConstant: 0.04,
+      springLength: 130, damping: 0.09,
+    }},
+  }},
+  interaction: {{
+    tooltipDelay: 150, hideEdgesOnDrag: true, multiselect: true, hover: true,
+  }},
+  layout: {{ improvedLayout: false }},
+}};
+var container = document.getElementById("graph");
+var network = new vis.Network(container, {{ nodes: nodesDS, edges: edgesDS }}, options);
+var physicsEnabled = true;
+var inFocusMode = false;
+var searchVal = "";
+var nodeById = {{}};
+ALL_NODES.forEach(function(n) {{ nodeById[n.id] = n; }});
+network.on("click", function(params) {{
+  if (params.nodes.length === 1) {{
+    var node = nodeById[params.nodes[0]];
+    if (node) showInfo(node);
+  }} else if (!params.nodes.length && !params.edges.length) {{
+    closeInfo();
+    if (inFocusMode) exitFocus();
+  }}
+}});
+function showInfo(node) {{
+  document.getElementById("info-body").innerHTML = node.title || node.label;
+  document.getElementById("info-panel").style.display = "block";
+}}
+function closeInfo() {{ document.getElementById("info-panel").style.display = "none"; }}
+function showCallers(nodeId) {{
+  var target = nodeById[nodeId];
+  if (!target) return;
+  var CALLER_KINDS = new Set(["calls", "references"]);
+  var inEdges = ALL_EDGES.filter(function(e) {{
+    return e.to === nodeId && CALLER_KINDS.has(e._kind);
+  }});
+  var callerIds = new Set(inEdges.map(function(e) {{ return e.from; }}));
+  callerIds.add(nodeId);
+  var focusNodes = ALL_NODES.filter(function(n) {{ return callerIds.has(n.id); }});
+  nodesDS.clear(); nodesDS.add(focusNodes);
+  edgesDS.clear(); edgesDS.add(inEdges);
+  document.getElementById("s-nodes").textContent = focusNodes.length;
+  document.getElementById("s-edges").textContent = inEdges.length;
+  network.fit();
+  document.getElementById("normal-filters").style.display = "none";
+  document.getElementById("callers-panel").style.display = "flex";
+  document.getElementById("callers-title").textContent = "Callers of " + target.label;
+  var list = document.getElementById("callers-list");
+  list.innerHTML = "";
+  var callerCount = 0;
+  inEdges.forEach(function(e) {{
+    var caller = nodeById[e.from];
+    if (!caller) return;
+    callerCount++;
+    var row = document.createElement("div");
+    row.className = "caller-row";
+    row.title = caller.label;
+    row.innerHTML = "<span class='caller-kind'>[" + e._kind + "]</span>" + caller.label;
+    row.onclick = function() {{ network.selectNodes([e.from]); showInfo(caller); }};
+    list.appendChild(row);
+  }});
+  document.getElementById("focus-bar").style.display = "flex";
+  document.getElementById("focus-label").textContent = target.label + " (" + target.group + ")";
+  document.getElementById("focus-count").textContent =
+    callerCount + " caller" + (callerCount !== 1 ? "s" : "");
+  inFocusMode = true;
+  closeInfo();
+}}
+function exitFocus() {{
+  inFocusMode = false;
+  document.getElementById("focus-bar").style.display = "none";
+  document.getElementById("callers-panel").style.display = "none";
+  document.getElementById("normal-filters").style.display = "block";
+  applyFilters();
+}}
+function togglePhysics() {{
+  physicsEnabled = !physicsEnabled;
+  network.setOptions({{ physics: {{ enabled: physicsEnabled }} }});
+  document.getElementById("physics-btn").textContent =
+    physicsEnabled ? "Disable physics" : "Enable physics";
+}}
+function applyFilters() {{
+  if (inFocusMode) return;
+  var activeNodeKinds = new Set();
+  document.querySelectorAll(".nf:checked").forEach(function(cb) {{ activeNodeKinds.add(cb.value); }});
+  var activeEdgeKinds = new Set();
+  document.querySelectorAll(".ef:checked").forEach(function(cb) {{ activeEdgeKinds.add(cb.value); }});
+  var q = searchVal.toLowerCase();
+  var visNodes = ALL_NODES.filter(function(n) {{
+    if (!activeNodeKinds.has(n.group)) return false;
+    if (q && n.label.toLowerCase().indexOf(q) === -1) return false;
+    return true;
+  }});
+  var visIds = new Set(visNodes.map(function(n) {{ return n.id; }}));
+  var visEdges = ALL_EDGES.filter(function(e) {{
+    return visIds.has(e.from) && visIds.has(e.to) && activeEdgeKinds.has(e._kind);
+  }});
+  nodesDS.clear(); nodesDS.add(visNodes);
+  edgesDS.clear(); edgesDS.add(visEdges);
+  document.getElementById("s-nodes").textContent = visNodes.length;
+  document.getElementById("s-edges").textContent = visEdges.length;
+}}
+function selectAll(checked) {{
+  document.querySelectorAll(".nf, .ef").forEach(function(cb) {{ cb.checked = checked; }});
+  applyFilters();
+}}
+document.querySelectorAll(".nf, .ef").forEach(function(cb) {{
+  cb.addEventListener("change", applyFilters);
+}});
+var searchTimer;
+document.getElementById("search").addEventListener("input", function(e) {{
+  searchVal = e.target.value;
+  clearTimeout(searchTimer);
+  if (inFocusMode) exitFocus();
+  searchTimer = setTimeout(applyFilters, 200);
+}});
+network.on("stabilizationIterationsDone", function() {{
+  if (physicsEnabled) {{
+    network.setOptions({{ physics: {{ enabled: false }} }});
+    physicsEnabled = false;
+    document.getElementById("physics-btn").textContent = "Enable physics";
+  }}
+}});
+</script>
+</body>
+</html>"""
+
+
+# ---------------------------------------------------------------------------
+# CLI command
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def visualize(
+    root: Annotated[
+        Path,
+        typer.Argument(
+            help="Project root to analyse",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ],
+    lang: Annotated[
+        str,
+        typer.Option(
+            help="Adapter(s): auto | python | typescript | python,typescript",
+            show_default=True,
+        ),
+    ] = "auto",
+    output: Annotated[
+        Path | None,
+        typer.Option("--output", "-o", help="Output HTML file (default: graph-<name>.html)"),
+    ] = None,
+    no_open: Annotated[
+        bool,
+        typer.Option("--no-open", help="Do not open the browser automatically"),
+    ] = False,
+    show_external: Annotated[
+        bool,
+        typer.Option("--show-external", help="Include stdlib/third_party external symbol nodes"),
+    ] = False,
+    show_structure: Annotated[
+        bool,
+        typer.Option("--show-structure", help="Include CONTAINS/DECLARES structural edges"),
+    ] = False,
+    max_nodes: Annotated[
+        int,
+        typer.Option("--max-nodes", help="Prune low-degree nodes above this count", min=1),
+    ] = 1500,
+) -> None:
+    """Build an interactive HTML code-graph visualisation."""
+    langs = resolve_langs(lang, root)
+    typer.echo(f"Analysing {root}  [lang={', '.join(langs)}]")
+    graph, elapsed = run_analysis(root, langs)
+    typer.echo(
+        f"  {len(graph.nodes)} nodes, {len(graph.relations)} relations"
+        f"  ({elapsed:.2f}s)"
+    )
+
+    vis_nodes, vis_edges = build_vis_data(
+        graph,
+        show_external=show_external,
+        show_structure=show_structure,
+        max_nodes=max_nodes,
+    )
+    typer.echo(f"  rendering {len(vis_nodes)} nodes, {len(vis_edges)} edges")
+
+    project_nodes = [n for n in graph.nodes.values() if n.kind == NodeKind.PROJECT]
+    project_name = (
+        " + ".join(sorted({n.name for n in project_nodes}))
+        if project_nodes
+        else root.name
+    )
+
+    stats: dict[str, Any] = {
+        "total_nodes":     len(graph.nodes),
+        "total_relations": len(graph.relations),
+        "lang":            ", ".join(langs),
+        "elapsed":         elapsed,
+    }
+
+    html = render_html(project_name, vis_nodes, vis_edges, stats)
+
+    out_name = project_name.replace(" + ", "-").replace(" ", "_")
+    out = output or Path(f"graph-{out_name}.html")
+    out.write_text(html, encoding="utf-8")
+    typer.echo(f"  written → {out.resolve()}")
+
+    if not no_open:
+        webbrowser.open(out.resolve().as_uri())