codebase-index 1.6.0__py3-none-any.whl

codebase_index/graph/builder.py

@@ -0,0 +1,160 @@
+"""Global graph pass: resolve unresolved edges against the whole repo and
+denormalize symbol degrees.
+
+Runs once after all files are indexed (it needs the complete symbol/file tables).
+Symbol-target edges (call/reference/extends/implements) resolve only on an
+UNAMBIGUOUS name match — if two definitions share a name, the edge is left
+unresolved rather than guessed. Import edges resolve their module path to a file
+by POSIX path-suffix match (e.g. 'auth.token' -> '%/auth/token.py').
+
+The pass is batched: one query for globally-unique symbol names, one for file
+paths (expanded into an in-memory suffix map), one executemany for the updates.
+The per-edge variant did an indexed lookup per symbol edge and up to ~20
+full-table LIKE scans per import edge, which dominated large builds.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from typing import Optional
+
+from ..storage import repo
+
+_SYMBOL_EDGE_TYPES = {"call", "reference", "extends", "implements"}
+
+
+def build_graph(conn: sqlite3.Connection) -> dict[str, int]:
+    resolved = resolve_edges(conn)
+    repo.recompute_degrees(conn)
+    # Everything still unresolved that names a target is, by definition, a target we
+    # could not pin to a unique node — record it as 'ambiguous' for the honesty trail.
+    repo.mark_ambiguous_edges(conn)
+    total_unresolved = len(repo.unresolved_edges(conn))
+    # Architecture analytics (communities / god nodes / surprising bridges) are a
+    # derived view of the graph. Compute once per build and cache the JSON in meta so
+    # the `architecture` command and the HTML export read it instantly. Never let an
+    # analysis failure fail the build — the graph itself is already written.
+    try:
+        from . import analysis
+
+        analysis.refresh_analysis(conn)
+    except Exception:  # pragma: no cover - defensive; analytics are best-effort
+        pass
+    return {"resolved": resolved, "unresolved": total_unresolved}
+
+
+def resolve_edges(conn: sqlite3.Connection) -> int:
+    edges = repo.unresolved_edges(conn)
+    if not edges:
+        return 0
+
+    unique_symbols = repo.unique_symbol_ids_by_name(conn)
+    suffix_map = _path_suffix_map(repo.all_file_ids_with_paths(conn))
+
+    # (dst_kind, dst_id, edge_id, confidence). A repo-unique symbol name is an exact
+    # hit -> 'extracted'; an import resolved only by path-suffix matching is a best-
+    # effort heuristic -> 'inferred'.
+    resolutions: list[tuple[str, int, int, str]] = []
+    for edge in edges:
+        name = edge["dst_name"]
+        if edge["edge_type"] == "import":
+            file_id = _module_to_file_id(suffix_map, name, lang=edge["lang"])
+            if file_id is not None:
+                resolutions.append(("file", file_id, edge["id"], "inferred"))
+        elif edge["edge_type"] in _SYMBOL_EDGE_TYPES:
+            sym_id = unique_symbols.get(name)
+            if sym_id is not None:
+                resolutions.append(("symbol", sym_id, edge["id"], "extracted"))
+
+    repo.resolve_edges_bulk(conn, resolutions)
+    return len(resolutions)
+
+
+def _path_suffix_map(rows: list[sqlite3.Row]) -> dict[str, Optional[int]]:
+    """Map every '/'-aligned path suffix to its file id, or None when ambiguous.
+
+    Mirrors files_with_suffix(path = suffix OR path LIKE '%/suffix') semantics:
+    a suffix shared by several files resolves to None (like a multi-row result),
+    and matching is case-insensitive the way SQLite LIKE folds ASCII.
+    """
+    mapping: dict[str, Optional[int]] = {}
+    for row in rows:
+        parts = row["path"].lower().split("/")
+        for i in range(len(parts)):
+            suffix = "/".join(parts[i:])
+            mapping[suffix] = None if suffix in mapping else int(row["id"])
+    return mapping
+
+
+def _lang_suffixes(lang: Optional[str], base: str, rust_base: str, go_pkg: str) -> list[str]:
+    """Import-path suffixes specific to one language, most-specific first."""
+    return {
+        "python": [f"{base}.py", f"{base}/__init__.py"],
+        "typescript": [f"{base}.ts", f"{base}.tsx", f"{base}/index.ts", f"{base}/index.tsx"],
+        "javascript": [f"{base}.js", f"{base}/index.js"],
+        "java": [f"{base}.java"],
+        "kotlin": [f"{base}.kt"],
+        "go": [f"{go_pkg}.go"],
+        "rust": [
+            f"{rust_base}.rs", f"{rust_base}/mod.rs",
+            f"src/{rust_base}.rs", f"src/{rust_base}/mod.rs",
+        ],
+        "csharp": [f"{base}.cs"],
+        "ruby": [f"{base}.rb"],
+        "php": [f"{base}.php"],
+    }.get(lang or "", [])
+
+
+def _module_to_file_id(
+    suffix_map: dict[str, Optional[int]], module: str, lang: Optional[str] = None
+) -> Optional[int]:
+    """Resolve a module/import path to a unique file id, or None.
+
+    Handles Python, TypeScript/JavaScript, Java/Kotlin/Scala, Rust (:: separator),
+    Go (last path segment), C#, Ruby, and PHP import conventions. The importing
+    file's `lang` is tried first so that, in a polyglot repo, `import './base'` from
+    a .ts file resolves to base.ts rather than a same-named base.py earlier in the
+    fixed fallback order. The fallback order is unchanged, so single-language repos
+    and the lang-unknown path behave exactly as before.
+    """
+    base = module.lower().replace(".", "/").strip("/")
+    rust_base = module.lower().replace("::", "/").strip("/")
+    if not base:
+        return None
+    # Last segment used for Go package-level resolution
+    go_pkg = base.rsplit("/", 1)[-1] if "/" in base else base
+
+    fallback = (
+        # Python
+        f"{base}.py",
+        f"{base}/__init__.py",
+        # TypeScript / JavaScript
+        f"{base}.ts",
+        f"{base}.tsx",
+        f"{base}.js",
+        f"{base}/index.ts",
+        f"{base}/index.tsx",
+        f"{base}/index.js",
+        # Java / Kotlin / Scala (dot-to-slash already done above)
+        f"{base}.java",
+        f"{base}.kt",
+        f"{base}.scala",
+        # Go: resolve last path segment to a .go file of the same name
+        f"{go_pkg}.go",
+        # Rust: :: separator mapped to /; also try under src/
+        f"{rust_base}.rs",
+        f"{rust_base}/mod.rs",
+        f"src/{rust_base}.rs",
+        f"src/{rust_base}/mod.rs",
+        # C#
+        f"{base}.cs",
+        # Ruby
+        f"{base}.rb",
+        # PHP
+        f"{base}.php",
+    )
+    for suffix in (*_lang_suffixes(lang, base, rust_base, go_pkg), *fallback):
+        file_id = suffix_map.get(suffix)
+        if file_id is not None:
+            return file_id
+    return None

codebase_index/graph/expand.py

@@ -0,0 +1,136 @@
+"""Impact analysis: bounded BFS over the resolved edge graph.
+
+Direction semantics:
+  up   -> dependents (who is affected if the target changes): incoming edges.
+  down -> dependencies (what the target relies on): outgoing edges.
+  both -> union of the two.
+
+Target resolution: an exact file path -> a file node (seeded together with all
+symbols defined in that file, so importers AND subclassers surface). Otherwise a
+symbol name -> all symbol nodes with that name. A path suffix is the last resort.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from collections import deque
+from typing import Optional
+
+from ..models import GraphCoverage, ImpactNode, ImpactResponse, IndexFreshness
+from ..storage import repo
+
+
+def _freshness(conn: sqlite3.Connection) -> IndexFreshness:
+    return IndexFreshness(
+        exists=True,
+        stale=False,
+        built_at=repo.get_meta(conn, "built_at"),
+        head_commit=repo.get_meta(conn, "head_commit"),
+    )
+
+
+def _seed_nodes(conn: sqlite3.Connection, target: str) -> list[tuple[str, int]]:
+    """Resolve a target string to one or more (kind, id) start nodes."""
+    frow = repo.file_by_path(conn, target)
+    if frow is not None:
+        seeds = [("file", int(frow["id"]))]
+        seeds += [("symbol", int(s["id"])) for s in repo.symbols_in_file(conn, int(frow["id"]))]
+        return seeds
+
+    sym_rows = repo.symbols_by_name(conn, target, exact=True)
+    if sym_rows:
+        return [("symbol", int(r["id"])) for r in sym_rows]
+
+    suffix = repo.files_with_suffix(conn, target)
+    if len(suffix) == 1:
+        fid = int(suffix[0]["id"])
+        return [("file", fid)] + [
+            ("symbol", int(s["id"])) for s in repo.symbols_in_file(conn, fid)
+        ]
+    return []
+
+
+def _neighbors(conn, kind, node_id, direction):
+    """Yield (next_kind, next_id, edge_type, confidence) for the requested direction(s)."""
+    if direction in ("up", "both"):
+        for e in repo.incoming_edges(conn, kind, node_id):
+            yield e["src_kind"], int(e["src_id"]), e["edge_type"], e["confidence"]
+    if direction in ("down", "both"):
+        for e in repo.outgoing_edges(conn, kind, node_id):
+            if e["dst_id"] is not None:
+                yield e["dst_kind"], int(e["dst_id"]), e["edge_type"], e["confidence"]
+
+
+def _node_meta(conn, kind, node_id) -> Optional[ImpactNode]:
+    if kind == "file":
+        row = conn.execute("SELECT path FROM files WHERE id = ?", (node_id,)).fetchone()
+        if row is None:
+            return None
+        return ImpactNode(kind="file", path=row["path"], distance=0)
+    row = conn.execute(
+        "SELECT s.name AS name, s.line_start AS line_start, f.path AS path "
+        "FROM symbols s JOIN files f ON f.id = s.file_id WHERE s.id = ?",
+        (node_id,),
+    ).fetchone()
+    if row is None:
+        return None
+    return ImpactNode(kind="symbol", path=row["path"], name=row["name"],
+                      line_start=row["line_start"], distance=0)
+
+
+def walk_impact(
+    conn: sqlite3.Connection, target: str, *, depth: int, direction: str
+) -> list[ImpactNode]:
+    seeds = _seed_nodes(conn, target)
+    if not seeds:
+        return []
+    visited: set[tuple[str, int]] = set(seeds)
+    queue: deque[tuple[str, int, int]] = deque((k, i, 0) for k, i in seeds)
+    out: list[ImpactNode] = []
+
+    while queue:
+        kind, node_id, dist = queue.popleft()
+        if dist >= depth:
+            continue
+        for nk, nid, etype, conf in _neighbors(conn, kind, node_id, direction):
+            if (nk, nid) in visited:
+                continue
+            visited.add((nk, nid))
+            meta = _node_meta(conn, nk, nid)
+            if meta is None:
+                continue
+            meta.distance = dist + 1
+            meta.via_edge = etype
+            meta.via_confidence = conf
+            out.append(meta)
+            queue.append((nk, nid, dist + 1))
+    return out
+
+
+def _target_paths(conn: sqlite3.Connection, target: str) -> list[str]:
+    """The file path(s) the target resolves to, for coverage classification."""
+    if repo.file_by_path(conn, target) is not None:
+        return [target]
+    sym_rows = repo.symbols_by_name(conn, target, exact=True)
+    if sym_rows:
+        return [r["path"] for r in sym_rows]
+    suffix = repo.files_with_suffix(conn, target)
+    if len(suffix) == 1:
+        return [suffix[0]["path"]]
+    return []
+
+
+def impact_lookup(
+    conn: sqlite3.Connection, target: str, *, depth: int, direction: str
+) -> ImpactResponse:
+    nodes = walk_impact(conn, target, depth=depth, direction=direction)
+    best: dict[str, int] = {}
+    for n in nodes:
+        if n.path not in best or n.distance < best[n.path]:
+            best[n.path] = n.distance
+    files = sorted(best, key=lambda p: (best[p], p))
+    return ImpactResponse(
+        target=target, direction=direction, depth=depth,
+        index=_freshness(conn), nodes=nodes, files=files,
+        coverage=GraphCoverage.for_paths(_target_paths(conn, target)),
+    )

codebase_index/graph/export.py

@@ -0,0 +1,381 @@
+"""HTML graph export for the indexed call/import/reference graph."""
+
+from __future__ import annotations
+
+import json
+import math
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .expand import impact_lookup
+
+
+def _edge_rows(
+    conn: sqlite3.Connection,
+    *,
+    target: str | None,
+    depth: int,
+    direction: str,
+    limit: int,
+) -> list[sqlite3.Row]:
+    params: list[Any] = []
+    where = "WHERE e.resolved = 1"
+    if target:
+        impact = impact_lookup(conn, target, depth=depth, direction=direction)
+        paths = set(impact.files)
+        if "/" in target or "\\" in target:
+            paths.add(target.replace("\\", "/"))
+        if paths:
+            placeholders = ",".join("?" for _ in paths)
+            where += (
+                f" AND (src_file.path IN ({placeholders}) "
+                f"OR src_sym_file.path IN ({placeholders}) "
+                f"OR dst_file.path IN ({placeholders}) "
+                f"OR dst_sym_file.path IN ({placeholders}))"
+            )
+            ordered = sorted(paths)
+            params.extend(ordered)
+            params.extend(ordered)
+            params.extend(ordered)
+            params.extend(ordered)
+
+    params.append(limit)
+    return conn.execute(
+        f"""
+        SELECT e.edge_type, e.resolved, e.line, e.dst_name, e.confidence,
+               e.src_kind, e.dst_kind,
+               src_file.path AS src_file_path,
+               src_sym_file.path AS src_symbol_file_path,
+               src_sym.name AS src_symbol_name,
+               src_sym.kind AS src_symbol_kind,
+               dst_file.path AS dst_file_path,
+               dst_sym.name AS dst_symbol_name,
+               dst_sym.kind AS dst_symbol_kind,
+               dst_sym_file.path AS dst_symbol_file_path
+        FROM edges e
+        LEFT JOIN files src_file ON e.src_kind = 'file' AND src_file.id = e.src_id
+        LEFT JOIN symbols src_sym ON e.src_kind = 'symbol' AND src_sym.id = e.src_id
+        LEFT JOIN files src_sym_file ON src_sym_file.id = src_sym.file_id
+        LEFT JOIN files dst_file ON e.dst_kind = 'file' AND dst_file.id = e.dst_id
+        LEFT JOIN symbols dst_sym ON e.dst_kind = 'symbol' AND dst_sym.id = e.dst_id
+        LEFT JOIN files dst_sym_file ON dst_sym_file.id = dst_sym.file_id
+        {where}
+        ORDER BY e.edge_type, COALESCE(src_file.path, src_sym_file.path), e.line
+        LIMIT ?
+        """,
+        params,
+    ).fetchall()
+
+
+def _node_key(kind: str, path: str, name: str | None = None) -> str:
+    return f"{kind}:{path}:{name or ''}"
+
+
+def _graph_data(rows: list[sqlite3.Row]) -> dict[str, Any]:
+    from collections import Counter, defaultdict
+
+    from .analysis import detect_communities, weighted_degree
+
+    nodes: dict[str, dict[str, Any]] = {}
+    edges: list[dict[str, Any]] = []
+    adj: dict[str, Counter] = defaultdict(Counter)
+    for row in rows:
+        src_path = row["src_file_path"] or row["src_symbol_file_path"] or ""
+        src_name = row["src_symbol_name"]
+        src_kind = row["src_symbol_kind"] or "file"
+        dst_path = row["dst_file_path"] or row["dst_symbol_file_path"] or ""
+        dst_name = row["dst_symbol_name"]
+        dst_kind = row["dst_symbol_kind"] or row["dst_kind"] or "file"
+        if not src_path or not dst_path:
+            continue
+
+        src_key = _node_key("symbol" if src_name else "file", src_path, src_name)
+        dst_key = _node_key("symbol" if dst_name else "file", dst_path, dst_name)
+        nodes.setdefault(
+            src_key,
+            {"id": src_key, "path": src_path, "name": src_name, "kind": src_kind},
+        )
+        nodes.setdefault(
+            dst_key,
+            {"id": dst_key, "path": dst_path, "name": dst_name, "kind": dst_kind},
+        )
+        edges.append(
+            {
+                "source": src_key,
+                "target": dst_key,
+                "type": row["edge_type"],
+                "line": row["line"],
+                "confidence": row["confidence"] if "confidence" in row.keys() else "extracted",
+            }
+        )
+        if src_key != dst_key:
+            adj[src_key][dst_key] += 1
+            adj[dst_key][src_key] += 1
+
+    # Colour by module and size by centrality, computed on the displayed subgraph.
+    # The analysis functions are generic over the node key type, so string keys work.
+    communities = detect_communities(adj)
+    degree = weighted_degree(adj)
+    for key, node in nodes.items():
+        node["community"] = communities.get(key, -1)
+        node["degree"] = degree.get(key, 0)
+    return {"nodes": list(nodes.values()), "edges": edges}
+
+
+def _layout(nodes: list[dict[str, Any]], width: int = 1200, height: int = 760) -> None:
+    radius = min(width, height) * 0.38
+    cx = width / 2
+    cy = height / 2
+    count = max(1, len(nodes))
+    for idx, node in enumerate(nodes):
+        angle = 2 * math.pi * idx / count
+        node["x"] = round(cx + radius * math.cos(angle), 2)
+        node["y"] = round(cy + radius * math.sin(angle), 2)
+
+
+def export_graph_html(
+    conn: sqlite3.Connection,
+    output: Path,
+    *,
+    target: str | None = None,
+    depth: int = 2,
+    direction: str = "both",
+    limit: int = 500,
+) -> dict[str, int]:
+    rows = _edge_rows(conn, target=target, depth=depth, direction=direction, limit=limit)
+    data = _graph_data(rows)
+    _layout(data["nodes"])
+    payload = json.dumps(data).replace("</", "<\\/")
+    title = "codebase-index graph" + (f" - {target}" if target else "")
+    html = f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{title}</title>
+<style>
+body {{ margin:0; font:14px system-ui, Segoe UI, sans-serif; color:#1f2937; background:#f8fafc; }}
+header {{ padding:14px 18px; border-bottom:1px solid #d1d5db; background:#fff; display:flex; gap:14px; align-items:center; }}
+h1 {{ font-size:18px; margin:0; font-weight:650; }}
+input {{ width:320px; max-width:40vw; padding:8px 10px; border:1px solid #cbd5e1; border-radius:6px; }}
+main {{ display:grid; grid-template-columns:minmax(0,1fr) 420px; min-height:calc(100vh - 58px); }}
+svg {{ width:100%; height:calc(100vh - 58px); background:#fff; }}
+aside {{ border-left:1px solid #d1d5db; overflow:auto; background:#f8fafc; }}
+table {{ width:100%; border-collapse:collapse; font-size:12px; }}
+th,td {{ text-align:left; padding:8px; border-bottom:1px solid #e5e7eb; vertical-align:top; }}
+th {{ position:sticky; top:0; background:#f1f5f9; z-index:1; }}
+.edge {{ stroke:#94a3b8; stroke-width:1.3; }}
+.edge.inferred {{ stroke-dasharray:5 3; }}            /* heuristic-resolved */
+.edge.ambiguous {{ stroke:#ef4444; stroke-dasharray:2 3; }}  /* unresolved target */
+.node {{ cursor:pointer; }}
+.node circle {{ stroke:#1f2937; stroke-width:1.5; }}
+.node.file circle {{ stroke-width:2.5; }}
+.node text {{ font-size:11px; fill:#111827; }}
+.dim {{ opacity:.12; }}
+.selected circle {{ stroke:#111827; stroke-width:3; }}
+.legend {{ font-size:11px; color:#475569; display:flex; gap:14px; align-items:center; flex-wrap:wrap; }}
+.legend b {{ color:#1f2937; }}
+.legend svg {{ width:34px; height:8px; vertical-align:middle; }}
+</style>
+</head>
+<body>
+<header>
+<h1>codebase-index graph</h1>
+<input id="filter" placeholder="Filter nodes or edges">
+<span id="counts"></span>
+<span class="legend">
+  <span><b>colour</b> = module</span>
+  <span><b>size</b> = connectivity</span>
+  <span><svg><line x1="0" y1="4" x2="34" y2="4" stroke="#94a3b8" stroke-width="1.3"/></svg> extracted</span>
+  <span><svg><line x1="0" y1="4" x2="34" y2="4" stroke="#94a3b8" stroke-width="1.3" stroke-dasharray="5 3"/></svg> inferred</span>
+  <span><svg><line x1="0" y1="4" x2="34" y2="4" stroke="#ef4444" stroke-width="1.3" stroke-dasharray="2 3"/></svg> ambiguous</span>
+</span>
+</header>
+<main>
+<svg id="graph" viewBox="0 0 1200 760" role="img" aria-label="code graph"></svg>
+<aside>
+<table>
+<thead><tr><th>type</th><th>source</th><th>target</th><th>line</th></tr></thead>
+<tbody id="edgeRows"></tbody>
+</table>
+</aside>
+</main>
+<script id="graph-data" type="application/json">{payload}</script>
+<script>
+const data = JSON.parse(document.getElementById('graph-data').textContent);
+const svg = document.getElementById('graph');
+const rows = document.getElementById('edgeRows');
+const counts = document.getElementById('counts');
+const byId = new Map(data.nodes.map(n => [n.id, n]));
+// Stable, readable categorical palette; community id indexes into it.
+const PALETTE = ['#2563eb','#059669','#d97706','#7c3aed','#db2777','#0891b2',
+                 '#65a30d','#dc2626','#4f46e5','#ca8a04','#0d9488','#9333ea'];
+function colorFor(n) {{
+  const c = n.community;
+  if (c === undefined || c < 0) return '#cbd5e1';
+  return PALETTE[c % PALETTE.length];
+}}
+function radiusFor(n) {{ return (n.name ? 8 : 11) + Math.min(14, Math.sqrt(n.degree || 0) * 2); }}
+function label(n) {{ return n.name ? `${{n.name}} (${{n.path}})` : n.path; }}
+function draw(filter = '') {{
+  svg.textContent = '';
+  rows.textContent = '';
+  const q = filter.toLowerCase();
+  const visibleNode = n => !q || label(n).toLowerCase().includes(q);
+  const visibleEdge = e => {{
+    const s = byId.get(e.source), t = byId.get(e.target);
+    return !q || e.type.toLowerCase().includes(q) || label(s).toLowerCase().includes(q) || label(t).toLowerCase().includes(q);
+  }};
+  for (const e of data.edges.filter(visibleEdge)) {{
+    const s = byId.get(e.source), t = byId.get(e.target);
+    const line = document.createElementNS('http://www.w3.org/2000/svg', 'line');
+    line.setAttribute('x1', s.x); line.setAttribute('y1', s.y);
+    line.setAttribute('x2', t.x); line.setAttribute('y2', t.y);
+    line.setAttribute('class', 'edge ' + (e.confidence || 'extracted'));
+    svg.appendChild(line);
+    const tr = document.createElement('tr');
+    for (const val of [e.type, label(s), label(t), e.line || '']) {{
+      const td = document.createElement('td'); td.textContent = val; tr.appendChild(td);
+    }}
+    rows.appendChild(tr);
+  }}
+  for (const n of data.nodes.filter(visibleNode)) {{
+    const g = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+    g.setAttribute('class', `node ${{n.name ? 'symbol' : 'file'}}`);
+    g.setAttribute('transform', `translate(${{n.x}},${{n.y}})`);
+    const c = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
+    c.setAttribute('r', radiusFor(n));
+    c.setAttribute('fill', colorFor(n));
+    c.setAttribute('fill-opacity', '0.85');
+    const txt = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+    txt.setAttribute('x', 18); txt.setAttribute('y', 4);
+    txt.textContent = n.name || n.path.split('/').pop();
+    g.appendChild(c); g.appendChild(txt);
+    g.addEventListener('click', () => document.getElementById('filter').value = n.name || n.path);
+    svg.appendChild(g);
+  }}
+  counts.textContent = `${{data.nodes.length}} nodes / ${{data.edges.length}} edges`;
+}}
+document.getElementById('filter').addEventListener('input', e => draw(e.target.value));
+draw();
+</script>
+</body>
+</html>
+"""
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(html, encoding="utf-8")
+    return {"nodes": len(data["nodes"]), "edges": len(data["edges"])}
+
+
+# ---------------------------------------------------------------------------
+# Interop exports — GraphML (Gephi/yEd), DOT (Graphviz), Cypher (Neo4j).
+# All reuse _edge_rows + _graph_data, so they carry the same community/degree/
+# confidence enrichment as the HTML view. Pure-stdlib, zero dependencies.
+# ---------------------------------------------------------------------------
+
+def _collect(conn, *, target, depth, direction, limit) -> dict[str, Any]:
+    return _graph_data(_edge_rows(conn, target=target, depth=depth, direction=direction, limit=limit))
+
+
+def _write(output: Path, text: str) -> None:
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(text, encoding="utf-8")
+
+
+def export_graph_graphml(
+    conn: sqlite3.Connection, output: Path, *,
+    target: str | None = None, depth: int = 2, direction: str = "both", limit: int = 500,
+) -> dict[str, int]:
+    """GraphML for Gephi / yEd / NetworkX. Node ids are dense (n0, n1, …)."""
+    from xml.sax.saxutils import escape, quoteattr
+
+    data = _collect(conn, target=target, depth=depth, direction=direction, limit=limit)
+    ids = {n["id"]: f"n{i}" for i, n in enumerate(data["nodes"])}
+    lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<graphml xmlns="http://graphml.graphdrawing.org/xmlns">',
+    ]
+    for k, ty in (("kind", "string"), ("name", "string"), ("path", "string"),
+                  ("community", "long"), ("degree", "long")):
+        lines.append(f'  <key id="{k}" for="node" attr.name="{k}" attr.type="{ty}"/>')
+    for k in ("edge_type", "confidence"):
+        lines.append(f'  <key id="{k}" for="edge" attr.name="{k}" attr.type="string"/>')
+    lines.append('  <graph edgedefault="directed">')
+    for n in data["nodes"]:
+        lines.append(f'    <node id={quoteattr(ids[n["id"]])}>')
+        lines.append(f'      <data key="kind">{escape(n.get("kind") or "")}</data>')
+        lines.append(f'      <data key="name">{escape(n.get("name") or "")}</data>')
+        lines.append(f'      <data key="path">{escape(n.get("path") or "")}</data>')
+        lines.append(f'      <data key="community">{int(n.get("community", -1))}</data>')
+        lines.append(f'      <data key="degree">{int(n.get("degree", 0))}</data>')
+        lines.append("    </node>")
+    for i, e in enumerate(data["edges"]):
+        s = ids.get(e["source"])
+        t = ids.get(e["target"])
+        if s is None or t is None:
+            continue
+        lines.append(f'    <edge id="e{i}" source={quoteattr(s)} target={quoteattr(t)}>')
+        lines.append(f'      <data key="edge_type">{escape(e["type"])}</data>')
+        lines.append(f'      <data key="confidence">{escape(e.get("confidence") or "")}</data>')
+        lines.append("    </edge>")
+    lines += ["  </graph>", "</graphml>", ""]
+    _write(output, "\n".join(lines))
+    return {"nodes": len(data["nodes"]), "edges": len(data["edges"])}
+
+
+def export_graph_dot(
+    conn: sqlite3.Connection, output: Path, *,
+    target: str | None = None, depth: int = 2, direction: str = "both", limit: int = 500,
+) -> dict[str, int]:
+    """Graphviz DOT. Edge style encodes confidence (solid/dashed/dotted)."""
+    data = _collect(conn, target=target, depth=depth, direction=direction, limit=limit)
+    ids = {n["id"]: f"n{i}" for i, n in enumerate(data["nodes"])}
+    style = {"extracted": "solid", "inferred": "dashed", "ambiguous": "dotted"}
+
+    def esc(s: str) -> str:
+        return s.replace("\\", "\\\\").replace('"', '\\"')
+
+    lines = ["digraph codebase_index {", "  rankdir=LR;", '  node [shape=box, fontsize=10];']
+    for n in data["nodes"]:
+        lbl = esc(f'{n["name"]}\n{n["path"]}' if n.get("name") else (n.get("path") or ""))
+        lines.append(f'  {ids[n["id"]]} [label="{lbl}"];')
+    for e in data["edges"]:
+        s = ids.get(e["source"])
+        t = ids.get(e["target"])
+        if s is None or t is None:
+            continue
+        st = style.get(e.get("confidence") or "extracted", "solid")
+        lines.append(f'  {s} -> {t} [label="{esc(e["type"])}", style={st}];')
+    lines += ["}", ""]
+    _write(output, "\n".join(lines))
+    return {"nodes": len(data["nodes"]), "edges": len(data["edges"])}
+
+
+def export_graph_neo4j(
+    conn: sqlite3.Connection, output: Path, *,
+    target: str | None = None, depth: int = 2, direction: str = "both", limit: int = 500,
+) -> dict[str, int]:
+    """Cypher script (MERGE statements) to load the graph into Neo4j / FalkorDB."""
+    data = _collect(conn, target=target, depth=depth, direction=direction, limit=limit)
+
+    def lit(s: str) -> str:
+        return "'" + (s or "").replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+    lines = ["// codebase-index graph export for Neo4j / FalkorDB"]
+    for n in data["nodes"]:
+        node_label = "Symbol" if n.get("name") else "File"
+        lines.append(
+            f"MERGE (:{node_label} {{key:{lit(n['id'])}, name:{lit(n.get('name') or '')}, "
+            f"path:{lit(n.get('path') or '')}, community:{int(n.get('community', -1))}, "
+            f"degree:{int(n.get('degree', 0))}}});"
+        )
+    for e in data["edges"]:
+        rel = (e["type"] or "edge").upper()
+        lines.append(
+            f"MATCH (a {{key:{lit(e['source'])}}}), (b {{key:{lit(e['target'])}}}) "
+            f"MERGE (a)-[:{rel} {{confidence:{lit(e.get('confidence') or 'extracted')}}}]->(b);"
+        )
+    lines.append("")
+    _write(output, "\n".join(lines))
+    return {"nodes": len(data["nodes"]), "edges": len(data["edges"])}