codebrain 0.1.0__py3-none-any.whl

codebrain/comprehension.py

@@ -0,0 +1,1939 @@
+"""Multi-resolution comprehension engine.
+
+Generates layered views of a codebase at different zoom levels:
+  - System level:  what is this codebase, what are its parts
+  - Module level:  what does this file do, what does it depend on
+  - Symbol level:  full context for a single function/class
+  - Risk level:    where are the hotspots, what is fragile
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from collections import Counter, defaultdict
+
+from codebrain.graph.query import QueryEngine
+from codebrain.graph.store import GraphStore
+from codebrain.utils import is_test_file
+
+# Generic names that are too common for bare-name matching in hotspot scoring.
+# Without this filter, e.g. ``MyCache.get`` would collect ALL ``.get()`` callers
+# across the entire codebase, producing wildly inflated risk scores.
+_GENERIC_NAMES = frozenset({
+    "get", "set", "delete", "update", "create", "save", "load", "run",
+    "put", "post", "patch", "read", "write", "send", "close", "open",
+    "add", "remove", "pop", "push", "clear", "reset", "start", "stop",
+    "execute", "call", "apply", "handle", "process", "validate",
+    "init", "setup", "teardown", "configure",
+    "__init__", "__str__", "__repr__", "__eq__", "__hash__",
+    "__enter__", "__exit__", "__call__", "__getattr__", "__setattr__",
+    "__len__", "__iter__", "__next__", "__contains__",
+})
+
+
+class ComprehensionEngine:
+    """Produces deterministic, multi-resolution comprehension views."""
+
+    def __init__(self, store: GraphStore) -> None:
+        self.store = store
+        self.engine = QueryEngine(store)
+
+    # ------------------------------------------------------------------
+    # Unified zoom interface
+    # ------------------------------------------------------------------
+    def zoom(self, target: str | None = None) -> dict:
+        """Multi-resolution zoom — like Google Maps for architecture.
+
+        - No target: system level (what is this codebase?)
+        - Package name target: package level (what files are in this package?)
+        - File path target: module level (what does this file do?)
+        - Symbol name target: symbol level (full context for one symbol)
+
+        Each level includes navigation hints to drill down or zoom out.
+        """
+        if target is None:
+            return self._zoom_system()
+
+        # Check if target looks like a file path
+        all_nodes = self.store.get_all_nodes()
+        file_paths = {n["file_path"] for n in all_nodes}
+        normalized = target.replace("\\", "/")
+        if normalized in file_paths or target in file_paths:
+            return self._zoom_module(normalized)
+
+        # Check if target is a package (directory prefix matching indexed files)
+        pkg_prefix = normalized.rstrip("/") + "/"
+        pkg_files = [fp for fp in file_paths if fp.startswith(pkg_prefix)]
+        if pkg_files:
+            return self._zoom_package(normalized.rstrip("/"), all_nodes)
+
+        # Also check if target matches a top-level package name exactly
+        top_packages = set()
+        for fp in file_paths:
+            parts = fp.split("/")
+            if len(parts) > 1:
+                top_packages.add(parts[0])
+        if normalized in top_packages:
+            return self._zoom_package(normalized, all_nodes)
+
+        # Try as symbol name
+        return self._zoom_symbol(target, all_nodes)
+
+    def _zoom_system(self) -> dict:
+        """System-level zoom: overview + narrative + drill-down hints."""
+        narrative = self.system_narrative()
+        overview = self.system_overview()
+
+        # Discover packages with symbol counts for drill-down hints
+        all_nodes = self.store.get_all_nodes()
+        pkg_symbol_counts: dict[str, int] = {}
+        pkg_file_counts: dict[str, set[str]] = {}
+        for n in all_nodes:
+            parts = n["file_path"].split("/")
+            pkg = parts[0] if len(parts) > 1 else "(root)"
+            if n["type"] != "file":
+                pkg_symbol_counts[pkg] = pkg_symbol_counts.get(pkg, 0) + 1
+            if pkg not in pkg_file_counts:
+                pkg_file_counts[pkg] = set()
+            pkg_file_counts[pkg].add(n["file_path"])
+
+        top_packages = sorted(pkg_symbol_counts.items(), key=lambda x: -x[1])[:10]
+
+        return {
+            "level": "system",
+            "narrative": narrative,
+            "drill_down": [
+                {
+                    "target": pkg,
+                    "symbols": count,
+                    "files": len(pkg_file_counts.get(pkg, set())),
+                    "hint": f"zoom('{pkg}')",
+                }
+                for pkg, count in top_packages
+            ],
+            "stats": overview.get("stats", {}),
+            "zoom_out": None,
+        }
+
+    def _zoom_package(self, package_name: str, all_nodes: list[dict] | None = None) -> dict:
+        """Package-level zoom: files in a package with roles and stats."""
+        if all_nodes is None:
+            all_nodes = self.store.get_all_nodes()
+
+        pkg_prefix = package_name.rstrip("/") + "/"
+
+        # Collect files that belong to this package (direct children only)
+        file_nodes: dict[str, dict] = {}
+        file_symbols: dict[str, list[dict]] = defaultdict(list)
+        for n in all_nodes:
+            if not n["file_path"].startswith(pkg_prefix):
+                continue
+            # Check it's a direct child or one level deeper (sub-package __init__)
+            remainder = n["file_path"][len(pkg_prefix):]
+            if n["type"] == "file":
+                file_nodes[n["file_path"]] = n
+            else:
+                file_symbols[n["file_path"]].append(n)
+
+        if not file_nodes:
+            return {"level": "package", "error": f"No package: {package_name}"}
+
+        # Build file summaries
+        file_summaries = []
+        for fp, fnode in file_nodes.items():
+            syms = file_symbols.get(fp, [])
+            role = self._infer_module_role(fp, syms, 0, 0)
+            file_summaries.append({
+                "file_path": fp,
+                "role": role,
+                "symbol_count": len(syms),
+                "line_count": fnode.get("line_end", 0),
+                "drill_down": f"zoom('{fp}')",
+            })
+
+        file_summaries.sort(key=lambda x: x["symbol_count"], reverse=True)
+
+        # Detect sub-packages (directories within this package)
+        sub_packages: set[str] = set()
+        for fp in file_nodes:
+            remainder = fp[len(pkg_prefix):]
+            parts = remainder.split("/")
+            if len(parts) > 1:
+                sub_packages.add(package_name + "/" + parts[0])
+
+        # External dependencies: other packages this one depends on
+        all_edges = self.store.get_all_edges()
+        node_ids_in_pkg = set()
+        for fp in file_nodes:
+            for n in all_nodes:
+                if n["file_path"] == fp:
+                    node_ids_in_pkg.add(n["id"])
+
+        ext_deps: set[str] = set()
+        int_deps: list[dict] = []
+        for e in all_edges:
+            if e["type"] not in ("IMPORTS", "CALLS"):
+                continue
+            src_fp = e.get("file_path", "")
+            if not src_fp.startswith(pkg_prefix):
+                continue
+            # Resolve target to a file path
+            tgt_fp = self._resolve_edge_target_file(e["target"], all_nodes)
+            if tgt_fp is None:
+                continue
+            if tgt_fp.startswith(pkg_prefix):
+                if src_fp != tgt_fp:
+                    int_deps.append({"from": src_fp, "to": tgt_fp})
+            else:
+                tgt_parts = tgt_fp.split("/")
+                tgt_pkg = tgt_parts[0] if len(tgt_parts) > 1 else "(root)"
+                ext_deps.add(tgt_pkg)
+
+        return {
+            "level": "package",
+            "package": package_name,
+            "file_count": len(file_nodes),
+            "files": file_summaries,
+            "sub_packages": sorted(sub_packages),
+            "external_dependencies": sorted(ext_deps),
+            "internal_dependencies": int_deps[:50],  # cap to avoid huge output
+            "zoom_out": {"hint": "zoom()"},
+            "drill_down": [
+                {"target": f["file_path"], "hint": f"zoom('{f['file_path']}')"} for f in file_summaries[:10]
+            ],
+        }
+
+    def _resolve_edge_target_file(self, target: str, all_nodes: list[dict]) -> str | None:
+        """Resolve an edge target (node ID, name, or qualified name) to a file path."""
+        for n in all_nodes:
+            if n["id"] == target or n["qualified_name"] == target:
+                return n["file_path"]
+        for n in all_nodes:
+            if n["name"] == target:
+                return n["file_path"]
+        return None
+
+    def _zoom_module(self, file_path: str) -> dict:
+        """Module-level zoom: module narrative + symbol list + zoom hints."""
+        narrative = self.module_narrative(file_path)
+        view = self.module_view(file_path)
+
+        symbols = []
+        for s in view.get("symbols", []):
+            symbols.append({
+                "name": s.get("name", ""),
+                "type": s.get("type", ""),
+                "line": s.get("line_start", 0),
+                "hint": f"zoom('{s.get('name', '')}')",
+            })
+
+        # Derive the package from the file path for zoom_out
+        parts = file_path.split("/")
+        if len(parts) > 1:
+            pkg = "/".join(parts[:-1])
+            zoom_out = {"target": pkg, "hint": f"zoom('{pkg}')"}
+        else:
+            zoom_out = {"hint": "zoom()"}
+
+        return {
+            "level": "module",
+            "file": file_path,
+            "narrative": narrative,
+            "symbols": symbols,
+            "zoom_out": zoom_out,
+            "drill_down": [
+                {"target": s["name"], "hint": s["hint"]} for s in symbols[:10]
+            ],
+            "dependencies": view.get("dependencies", []),
+            "dependents": view.get("dependents", []),
+        }
+
+    def _zoom_symbol(self, name: str, all_nodes: list[dict] | None = None) -> dict:
+        """Symbol-level zoom: full context + narrative."""
+        if all_nodes is None:
+            all_nodes = self.store.get_all_nodes()
+
+        # Find the symbol
+        matches = [n for n in all_nodes if n["name"] == name or n["id"] == name]
+        if not matches:
+            return {"level": "symbol", "error": f"Symbol '{name}' not found"}
+
+        node = matches[0]
+        narrative = self.symbol_narrative(node["id"])
+
+        # Get callers and callees for navigation
+        callers = self.engine.impact_of_change(node["id"], max_depth=1)
+        callees = self.engine.get_call_chain(node["id"], max_depth=1)
+
+        return {
+            "level": "symbol",
+            "name": node["name"],
+            "type": node["type"],
+            "file": node["file_path"],
+            "line": node.get("line_start", 0),
+            "narrative": narrative,
+            "callers": [{"name": c.get("name", c["node_id"]), "hint": f"zoom('{c.get('name', c['node_id'])}')"} for c in callers[:10]],
+            "callees": [{"name": c.get("name", c["node_id"]), "hint": f"zoom('{c.get('name', c['node_id'])}')"} for c in callees[:10]],
+            "zoom_out": {"target": node["file_path"], "hint": f"zoom('{node['file_path']}')"},
+        }
+
+    # ------------------------------------------------------------------
+    # System level
+    # ------------------------------------------------------------------
+    def system_overview(self) -> dict:
+        """Top-level view of the entire codebase."""
+        stats = self.store.get_stats()
+        all_nodes = self.store.get_all_nodes()
+
+        # Discover packages (top-level directories)
+        packages: dict[str, dict] = {}
+        for node in all_nodes:
+            parts = node["file_path"].split("/")
+            pkg = parts[0] if len(parts) > 1 else "(root)"
+            if pkg not in packages:
+                packages[pkg] = {"files": set(), "docstring": "", "node_count": 0}
+            packages[pkg]["files"].add(node["file_path"])
+            if node["type"] != "file":
+                packages[pkg]["node_count"] += 1
+
+        # Get package docstrings from __init__.py nodes (already in all_nodes)
+        for node in all_nodes:
+            if node["type"] == "file" and node["docstring"] and node["file_path"].endswith("__init__.py"):
+                parts = node["file_path"].split("/")
+                pkg = parts[0] if len(parts) > 1 else "(root)"
+                if pkg in packages:
+                    packages[pkg]["docstring"] = node["docstring"]
+
+        # Entry points: functions named main, or in __main__.py
+        entry_points: list[dict] = []
+        for node in all_nodes:
+            if node["name"] == "main" and node["type"] == "function":
+                entry_points.append({
+                    "id": node["id"],
+                    "file_path": node["file_path"],
+                    "line": node["line_start"],
+                })
+            elif "__main__" in node["file_path"] and node["type"] == "file":
+                entry_points.append({
+                    "id": node["id"],
+                    "file_path": node["file_path"],
+                    "line": 1,
+                })
+
+        # Dependency flow between packages — use IMPORTS + CALLS edges
+        # Build node lookup for resolving targets to packages
+        node_by_id = {n["id"]: n for n in all_nodes}
+        nodes_by_name: dict[str, list[dict]] = defaultdict(list)
+        for n in all_nodes:
+            nodes_by_name[n["name"]].append(n)
+            if n["qualified_name"] != n["name"]:
+                nodes_by_name[n["qualified_name"]].append(n)
+
+        all_edges = self.store.get_all_edges()
+        pkg_deps: dict[str, set[str]] = defaultdict(set)
+        for e in all_edges:
+            if e["type"] not in ("IMPORTS", "CALLS"):
+                continue
+            src_parts = e["file_path"].split("/")
+            src_pkg = src_parts[0] if len(src_parts) > 1 else "(root)"
+
+            # Resolve target to a package
+            target_pkgs: set[str] = set()
+            # Try exact node ID
+            t_node = node_by_id.get(e["target"])
+            if t_node:
+                tp = t_node["file_path"].split("/")
+                target_pkgs.add(tp[0] if len(tp) > 1 else "(root)")
+            # Try name/qname lookup
+            for m in nodes_by_name.get(e["target"], []):
+                tp = m["file_path"].split("/")
+                target_pkgs.add(tp[0] if len(tp) > 1 else "(root)")
+            # Try dotted import prefix
+            if "." in e["target"]:
+                first = e["target"].split(".")[0]
+                if first in packages:
+                    target_pkgs.add(first)
+
+            for target_pkg in target_pkgs:
+                if target_pkg != src_pkg and target_pkg in packages:
+                    pkg_deps[src_pkg].add(target_pkg)
+
+        return {
+            "stats": stats,
+            "packages": {
+                name: {
+                    "file_count": len(info["files"]),
+                    "node_count": info["node_count"],
+                    "docstring": info["docstring"],
+                    "depends_on": sorted(pkg_deps.get(name, set())),
+                }
+                for name, info in sorted(packages.items())
+            },
+            "entry_points": entry_points,
+        }
+
+    # ------------------------------------------------------------------
+    # Package level
+    # ------------------------------------------------------------------
+    def package_view(self, package_name: str) -> dict:
+        """View of a single package (directory).
+
+        Bridges system_overview -> module_view.
+        Lists all files in the package with their roles, symbol counts,
+        dependencies, and which files are the most important.
+        """
+        all_nodes = self.store.get_all_nodes()
+        return self._zoom_package(package_name, all_nodes)
+
+    # ------------------------------------------------------------------
+    # Module level
+    # ------------------------------------------------------------------
+    def module_view(self, file_path: str) -> dict:
+        """Detailed view of a single file/module."""
+        nodes = self.store.get_nodes_by_file(file_path)
+        if not nodes:
+            return {"error": f"No indexed file: {file_path}"}
+
+        file_node = None
+        symbols: list[dict] = []
+        for n in nodes:
+            if n["type"] == "file":
+                file_node = n
+            else:
+                symbols.append({
+                    "name": n["name"],
+                    "type": n["type"],
+                    "line_start": n["line_start"],
+                    "line_end": n["line_end"],
+                    "signature": n["signature"],
+                    "is_exported": bool(n["is_exported"]),
+                    "docstring": n["docstring"],
+                })
+
+        # What does this module import?
+        imports = self.engine.get_file_dependencies(file_path)
+
+        # What imports this module? — batch fetch all incoming edges for all nodes in this file
+        node_ids = {n["id"] for n in nodes}
+        node_names = {n["name"] for n in nodes}
+        node_qnames = {n["qualified_name"] for n in nodes}
+        # Use a single query to find all edges targeting any node in this file
+        all_edges = self.store.get_all_edges()
+        imported_by_set: set[str] = set()
+
+        # Detect language to filter cross-language false positives
+        _py = (".py",)
+        _js = (".ts", ".tsx", ".js", ".jsx")
+        fp_ext = os.path.splitext(file_path)[1].lower() if file_path else ""
+        fp_lang = "python" if fp_ext in _py else ("js" if fp_ext in _js else "other")
+
+        for e in all_edges:
+            if e["type"] in ("CALLS", "IMPORTS") and e["file_path"] != file_path:
+                # Match by node ID or qualified name (always safe)
+                if e["target"] in node_ids or e["target"] in node_qnames:
+                    matched = True
+                elif e["target"] in node_names and e["target"] not in _GENERIC_NAMES:
+                    # Bare-name match — skip generic names to avoid over-counting
+                    matched = True
+                else:
+                    matched = False
+                if matched:
+                    # Skip cross-language false positives (Python <-> JS/TS)
+                    e_ext = os.path.splitext(e["file_path"])[1].lower() if e["file_path"] else ""
+                    e_lang = "python" if e_ext in _py else ("js" if e_ext in _js else "other")
+                    if fp_lang != "other" and e_lang != "other" and fp_lang != e_lang:
+                        continue
+                    imported_by_set.add(e["file_path"])
+
+        # Coupling score: how many other files reference this one
+        coupling_in = len(imported_by_set)
+        coupling_out = len(imports)
+
+        # Infer role
+        role = self._infer_module_role(file_path, symbols, coupling_in, coupling_out)
+
+        return {
+            "file_path": file_path,
+            "docstring": file_node["docstring"] if file_node else "",
+            "line_count": file_node["line_end"] if file_node else 0,
+            "role": role,
+            "symbols": symbols,
+            "exports": [s["name"] for s in symbols if s["is_exported"]],
+            "imports": imports,
+            "imported_by": sorted(imported_by_set),
+            "coupling": {
+                "incoming": coupling_in,
+                "outgoing": coupling_out,
+                "score": coupling_in + coupling_out,
+            },
+        }
+
+    # ------------------------------------------------------------------
+    # Risk hotspots
+    # ------------------------------------------------------------------
+    def risk_hotspots(self, top_n: int = 20) -> list[dict]:
+        """Find the most structurally risky nodes in the codebase.
+
+        Risk = number of transitive dependents * centrality.
+        High-risk nodes are those where a change would cascade widely.
+        """
+        all_nodes = self.store.get_all_nodes()
+        all_edges = self.store.get_all_edges()
+
+        # Preload reverse index for bulk impact_of_change() calls
+        self.engine.preload_reverse_index()
+
+        # Build reverse index: target -> list of edges (for incoming lookups)
+        incoming_by_target: dict[str, list[dict]] = defaultdict(list)
+        for e in all_edges:
+            incoming_by_target[e["target"]].append(e)
+
+        # Build node lookup for resolving impacted node files
+        node_by_id = {n["id"]: n for n in all_nodes}
+
+        # Also index by name and qualified_name for edge target resolution
+        nodes_by_name: dict[str, list[dict]] = defaultdict(list)
+        for n in all_nodes:
+            nodes_by_name[n["name"]].append(n)
+            if n["qualified_name"] != n["name"]:
+                nodes_by_name[n["qualified_name"]].append(n)
+
+        # Phase 1: Compute direct dependents for all nodes (cheap, in-memory)
+        candidates: list[tuple[dict, int, int]] = []  # (node, direct, external)
+
+        for node in all_nodes:
+            if node["type"] == "file":
+                continue
+
+            # Skip test files and test functions/classes
+            if is_test_file(node["file_path"]):
+                continue
+            if node["name"].startswith("test_") or node["name"].startswith("Test"):
+                continue
+
+            # Count direct incoming references using pre-built index
+            callers: list[dict] = []
+            for e in incoming_by_target.get(node["id"], []):
+                if e["type"] in ("CALLS", "IMPORTS"):
+                    callers.append(e)
+            # Skip bare-name matching for generic names to avoid inflated scores
+            # (e.g. MyCache.get collecting ALL .get() callers across the codebase)
+            if node["name"] not in _GENERIC_NAMES:
+                for e in incoming_by_target.get(node["name"], []):
+                    if e["type"] in ("CALLS", "IMPORTS"):
+                        callers.append(e)
+            if node["qualified_name"] != node["name"]:
+                for e in incoming_by_target.get(node["qualified_name"], []):
+                    if e["type"] in ("CALLS", "IMPORTS"):
+                        callers.append(e)
+
+            # Filter out callers from test files
+            callers = [e for e in callers if not is_test_file(e.get("file_path", ""))]
+
+            # Deduplicate by (source, target, line)
+            seen = set()
+            unique_callers = []
+            for e in callers:
+                key = (e["source"], e["target"], e["line"])
+                if key not in seen:
+                    seen.add(key)
+                    unique_callers.append(e)
+
+            direct_dependents = len(unique_callers)
+            if direct_dependents == 0:
+                continue
+
+            external_dependents = len([e for e in unique_callers if e["file_path"] != node["file_path"]])
+            candidates.append((node, direct_dependents, external_dependents))
+
+        # Phase 2: Sort by direct dependents (proxy for risk), take top candidates
+        # Only compute expensive transitive impact for top candidates
+        candidate_limit = max(top_n * 4, 100)
+        candidates.sort(key=lambda x: x[1] + x[2] * 2, reverse=True)
+        candidates = candidates[:candidate_limit]
+
+        hotspots: list[dict] = []
+        for node, direct_dependents, external_dependents in candidates:
+            # Transitive impact (limit depth for performance)
+            impacted = self.engine.impact_of_change(node["id"], max_depth=3)
+            transitive_count = len(impacted)
+
+            # Affected files — use node_by_id lookup instead of per-node DB query
+            affected_files = set()
+            for entry in impacted:
+                target = node_by_id.get(entry["node_id"])
+                if target:
+                    affected_files.add(target["file_path"])
+            affected_files.discard(node["file_path"])
+
+            risk_score = (
+                direct_dependents * 1.0
+                + external_dependents * 2.0
+                + transitive_count * 0.5
+                + len(affected_files) * 3.0
+            )
+
+            hotspots.append({
+                "node_id": node["id"],
+                "name": node["name"],
+                "type": node["type"],
+                "file_path": node["file_path"],
+                "line_start": node["line_start"],
+                "direct_dependents": direct_dependents,
+                "external_dependents": external_dependents,
+                "transitive_impact": transitive_count,
+                "affected_files": len(affected_files),
+                "risk_score": round(risk_score, 1),
+            })
+
+        hotspots.sort(key=lambda h: h["risk_score"], reverse=True)
+        return hotspots[:top_n]
+
+    # ------------------------------------------------------------------
+    # Health score
+    # ------------------------------------------------------------------
+    def health_score(self, hotspots: list[dict] | None = None) -> dict:
+        """Compute codebase health metrics with individual scores per dimension.
+
+        Returns separate scores for each dimension rather than a single
+        misleading number. Each dimension is 0-100 (higher is better).
+        Pass pre-computed *hotspots* to avoid redundant computation.
+        """
+        stats = self.store.get_stats()
+        total_nodes = stats.get("nodes", 0)
+        total_files = stats.get("files", 0)
+
+        # Dead code analysis
+        dead = self.engine.find_dead_code()
+        dead_ratio = len(dead) / max(total_nodes, 1)
+        dead_score = max(0, int(100 - dead_ratio * 200))  # 50% dead = 0
+
+        # Cycle analysis
+        cycles = self.engine.detect_cycles()
+        cycle_ratio = len(cycles) / max(total_files, 1)
+        cycle_score = max(0, int(100 - cycle_ratio * 500))  # 20% cyclic = 0
+
+        # Hotspot concentration
+        if hotspots is None:
+            hotspots = self.risk_hotspots(top_n=50)
+        high_risk = [h for h in hotspots if h["risk_score"] > 20]
+        hotspot_ratio = len(high_risk) / max(total_files, 1)
+        coupling_score = max(0, int(100 - hotspot_ratio * 300))
+
+        # Overall is weighted average (not a penalty system)
+        overall = int(dead_score * 0.3 + cycle_score * 0.3 + coupling_score * 0.4)
+
+        if overall >= 80:
+            grade = "A"
+        elif overall >= 60:
+            grade = "B"
+        elif overall >= 40:
+            grade = "C"
+        elif overall >= 20:
+            grade = "D"
+        else:
+            grade = "F"
+
+        return {
+            "score": overall,
+            "grade": grade,
+            "dimensions": {
+                "dead_code": {
+                    "score": dead_score,
+                    "count": len(dead),
+                    "ratio": round(dead_ratio, 3),
+                },
+                "import_cycles": {
+                    "score": cycle_score,
+                    "count": len(cycles),
+                },
+                "coupling": {
+                    "score": coupling_score,
+                    "high_risk_hotspots": len(high_risk),
+                },
+            },
+            "details": {
+                "total_nodes": total_nodes,
+                "total_files": total_files,
+                "dead_code_count": len(dead),
+                "dead_code_ratio": round(dead_ratio, 3),
+                "import_cycles": len(cycles),
+                "high_risk_hotspots": len(high_risk),
+            },
+        }
+
+    # ------------------------------------------------------------------
+    # Dependency map
+    # ------------------------------------------------------------------
+    def dependency_map(self) -> dict:
+        """File-level dependency graph for the entire codebase."""
+        file_nodes = self.store.get_all_nodes(type_filter="file")
+        all_nodes = self.store.get_all_nodes()
+        all_edges = self.store.get_all_edges()
+
+        # Build multiple lookup indices to resolve edge targets
+        node_by_id: dict[str, dict] = {}
+        nodes_by_name: dict[str, list[dict]] = defaultdict(list)
+        nodes_by_qname: dict[str, list[dict]] = defaultdict(list)
+        for n in all_nodes:
+            node_by_id[n["id"]] = n
+            nodes_by_name[n["name"]].append(n)
+            if n["qualified_name"] != n["name"]:
+                nodes_by_qname[n["qualified_name"]].append(n)
+
+        # Also map dotted import targets (e.g. "codebrain.indexer.full_index")
+        # to file paths by converting dots to path separators
+        file_paths = {n["file_path"] for n in file_nodes}
+
+        def _resolve_target_files(target: str) -> list[str]:
+            """Resolve an edge target to file path(s)."""
+            # 1. Exact node ID
+            node = node_by_id.get(target)
+            if node:
+                return [node["file_path"]]
+            # 2. Qualified name
+            matches = nodes_by_qname.get(target)
+            if matches:
+                return [m["file_path"] for m in matches]
+            # 3. Simple name (may match multiple nodes)
+            matches = nodes_by_name.get(target)
+            if matches:
+                return [m["file_path"] for m in matches]
+            # 4. Dotted import path → try converting to file path
+            #    e.g. "codebrain.indexer.full_index" → check "codebrain/indexer.py"
+            parts = target.split(".")
+            for i in range(len(parts), 0, -1):
+                candidate = "/".join(parts[:i]) + ".py"
+                if candidate in file_paths:
+                    return [candidate]
+                # Also try as package __init__.py
+                candidate_pkg = "/".join(parts[:i]) + "/__init__.py"
+                if candidate_pkg in file_paths:
+                    return [candidate_pkg]
+            return []
+
+        # Build edges-by-source for IMPORTS/CALLS
+        edges_by_file: dict[str, set[str]] = defaultdict(set)
+        for e in all_edges:
+            if e["type"] in ("IMPORTS", "CALLS"):
+                src_file = e["file_path"]
+                for target_file in _resolve_target_files(e["target"]):
+                    if target_file != src_file:
+                        edges_by_file[src_file].add(target_file)
+
+        deps: dict[str, list[str]] = {}
+        for fn in file_nodes:
+            deps[fn["file_path"]] = sorted(edges_by_file.get(fn["file_path"], set()))
+
+        return {"file_dependencies": deps}
+
+    # ------------------------------------------------------------------
+    # Change impact summary
+    # ------------------------------------------------------------------
+    def change_summary(self, file_path: str) -> dict:
+        """If this file changes, what is the blast radius?"""
+        nodes = self.store.get_nodes_by_file(file_path)
+        all_affected: set[str] = set()
+        all_impacted_nodes: list[dict] = []
+
+        # Pre-fetch all nodes for ID->file resolution
+        all_nodes_list = self.store.get_all_nodes()
+        node_by_id = {n["id"]: n for n in all_nodes_list}
+
+        for node in nodes:
+            if node["type"] == "file":
+                continue
+            impacted = self.engine.impact_of_change(node["id"], max_depth=5)
+            for entry in impacted:
+                target = node_by_id.get(entry["node_id"])
+                if target and target["file_path"] != file_path:
+                    all_affected.add(target["file_path"])
+                    all_impacted_nodes.append({
+                        "node_id": entry["node_id"],
+                        "depth": entry["depth"],
+                        "via": entry["via"],
+                    })
+
+        return {
+            "file_path": file_path,
+            "affected_file_count": len(all_affected),
+            "affected_files": sorted(all_affected),
+            "impacted_nodes": all_impacted_nodes,
+        }
+
+    # ------------------------------------------------------------------
+    # Narrative generation
+    # ------------------------------------------------------------------
+    def system_narrative(self) -> dict:
+        """Generate a natural language narrative for the entire codebase.
+
+        Combines system_overview, health_score, and risk_hotspots into
+        human-readable summaries with relative comparisons.
+        """
+        overview = self.system_overview()
+        hotspots = self.risk_hotspots(top_n=50)
+        health = self.health_score(hotspots=hotspots)
+
+        stats = overview["stats"]
+        packages = overview["packages"]
+        pkg_names = sorted(packages.keys())
+        total_files = stats.get("files", 0)
+
+        # Size characterization
+        if total_files < 20:
+            size = "small"
+        elif total_files < 200:
+            size = "medium-sized"
+        else:
+            size = "large"
+
+        summary = (
+            f"This is a {size} project with {total_files} files "
+            f"and {stats.get('nodes', 0)} symbols across "
+            f"{len(pkg_names)} package{'s' if len(pkg_names) != 1 else ''}"
+            f" ({', '.join(pkg_names)})."
+        )
+
+        # Architecture: identify the largest package
+        arch_parts = []
+        if packages:
+            largest_pkg = max(packages.items(), key=lambda x: x[1]["node_count"])
+            for pkg_name in pkg_names:
+                pkg = packages[pkg_name]
+                part = f"{pkg_name} ({pkg['file_count']} files, {pkg['node_count']} symbols)"
+                if pkg_name == largest_pkg[0] and len(pkg_names) > 1:
+                    part += " — the largest package"
+                arch_parts.append(part)
+        architecture = ". ".join(arch_parts) + "." if arch_parts else ""
+
+        # Backbone: top 3 most-depended-on files from hotspots
+        backbone = []
+        if hotspots:
+            top = hotspots[:3]
+            backbone_names = [h["file_path"].rsplit("/", 1)[-1] for h in top]
+            summary += (
+                f" The backbone modules are {', '.join(backbone_names)}"
+                " — most of the codebase depends on them."
+            )
+
+        # Health summary with relative context
+        grade = health["grade"]
+        score = health["score"]
+        details = health["details"]
+        dims = health.get("dimensions", {})
+        health_parts = [f"Health: {score}/100 (grade {grade})."]
+        dead_ratio = details.get("dead_code_ratio", 0)
+        if dead_ratio > 0.1:
+            health_parts.append(
+                f"Dead code is {dead_ratio:.0%} of symbols — higher than ideal (aim for <5%)."
+            )
+        elif dead_ratio > 0:
+            health_parts.append(f"Dead code is low at {dead_ratio:.0%} — good hygiene.")
+        cycles = details.get("import_cycles", 0)
+        if cycles > 0:
+            health_parts.append(f"{cycles} import cycle(s) — consider refactoring to improve layering.")
+        hotspot_count = details.get("high_risk_hotspots", 0)
+        if hotspot_count > 3:
+            health_parts.append(
+                f"{hotspot_count} high-risk hotspots — more than typical. Reduce coupling where possible."
+            )
+        health_summary = " ".join(health_parts)
+
+        # Key components with why
+        key_components = []
+        for h in hotspots[:5]:
+            risk_level = "high" if h["risk_score"] > 20 else ("medium" if h["risk_score"] > 5 else "low")
+            pct = h["affected_files"] / max(total_files, 1) * 100
+            key_components.append({
+                "name": h["name"],
+                "role": h["type"],
+                "risk": risk_level,
+                "why": (
+                    f"{h['direct_dependents']} dependents, affects {h['affected_files']} files "
+                    f"({pct:.0f}% of codebase)"
+                ),
+            })
+
+        # Recommendations
+        recommendations = []
+        if details["dead_code_count"] > 5:
+            recommendations.append(
+                f"Remove or document {details['dead_code_count']} potentially unused symbols."
+            )
+        if details.get("import_cycles", 0) > 0:
+            recommendations.append(
+                f"Resolve {details['import_cycles']} import cycle(s) to improve layering."
+            )
+        if hotspot_count > 3:
+            recommendations.append(
+                "Reduce coupling on high-risk hotspots to lower change risk."
+            )
+        if not recommendations:
+            recommendations.append("Codebase is in good shape. Keep monitoring hotspots.")
+
+        return {
+            "summary": summary,
+            "architecture": architecture,
+            "health_summary": health_summary,
+            "key_components": key_components,
+            "recommendations": recommendations,
+        }
+
+    def module_narrative(self, file_path: str) -> dict:
+        """Generate a natural language narrative for a single module.
+
+        Uses relative comparisons to codebase averages for context.
+        """
+        view = self.module_view(file_path)
+        if "error" in view:
+            return view
+
+        role = view.get("role", "module")
+        symbols = view.get("symbols", [])
+        imports = view.get("imports", [])
+        imported_by = view.get("imported_by", [])
+        exports = view.get("exports", [])
+        coupling = view.get("coupling", {})
+
+        # Compute codebase baselines for relative comparisons
+        all_nodes = self.store.get_all_nodes()
+        symbols_per_file: dict[str, int] = {}
+        for n in all_nodes:
+            fp = n.get("file_path", "")
+            if fp and n["type"] != "file":
+                symbols_per_file[fp] = symbols_per_file.get(fp, 0) + 1
+        avg_symbols = sum(symbols_per_file.values()) / max(len(symbols_per_file), 1)
+        this_count = len(symbols)
+
+        file_name = file_path.split("/")[-1]
+        classes = [s for s in symbols if s["type"] == "class"]
+        functions = [s for s in symbols if s["type"] in ("function", "method")]
+
+        # Summary with relative size
+        ratio = this_count / max(avg_symbols, 1)
+        if ratio > 2:
+            size_note = f" — {ratio:.1f}x the codebase average ({avg_symbols:.0f})"
+        elif ratio < 0.5 and avg_symbols > 0:
+            size_note = f" — lightweight (codebase average: {avg_symbols:.0f})"
+        else:
+            size_note = ""
+        summary = (
+            f"{file_name} is a {role.replace('_', ' ')} module with "
+            f"{this_count} symbols ({len(classes)} classes, {len(functions)} functions){size_note}."
+        )
+
+        # Importance with rank
+        incoming = coupling.get("incoming", 0)
+        all_incoming = sorted(
+            [v.get("coupling", {}).get("incoming", 0)
+             for v in [self.module_view(fp) for fp in list(symbols_per_file.keys())[:50]]
+             if "error" not in v],
+            reverse=True,
+        )
+        rank = (all_incoming.index(incoming) + 1) if incoming in all_incoming else len(all_incoming)
+        total_modules = len(symbols_per_file)
+
+        if rank == 1 and incoming > 0:
+            importance = f"Most depended-on file — {incoming} files depend on it. Changes here have the highest blast radius."
+        elif rank <= 3 and incoming > 0:
+            importance = f"Ranked #{rank} by dependents — {incoming} files depend on it. This is load-bearing infrastructure."
+        elif incoming > 0:
+            importance = f"{incoming} file(s) depend on it (ranked #{rank} of {total_modules})."
+        else:
+            importance = "No other files depend on this module. Changes here are low-risk."
+
+        # Dependencies narrative
+        if imports:
+            dep_str = f"Imports: {', '.join(imports[:10])}"
+            if len(imports) > 10:
+                dep_str += f" (+{len(imports) - 10} more)"
+        else:
+            dep_str = "No imports."
+        if imported_by:
+            dep_str += f". Imported by: {', '.join(imported_by[:10])}"
+            if len(imported_by) > 10:
+                dep_str += f" (+{len(imported_by) - 10} more)"
+        dependencies = dep_str + "."
+
+        # Exports summary
+        if exports:
+            exports_summary = f"Exports {len(exports)} symbols: {', '.join(exports[:10])}."
+        else:
+            exports_summary = "No exported symbols."
+
+        # Risks with context
+        risks = []
+        if incoming > 10:
+            risks.append(f"High coupling: {incoming} dependents — more than 90% of modules.")
+        if coupling.get("score", 0) > 20:
+            risks.append(f"High total coupling score ({coupling['score']}). Consider splitting this module.")
+        if not risks:
+            risks.append("No significant structural risks.")
+
+        top_callers = ", ".join(imported_by[:5]) if imported_by else "None"
+
+        return {
+            "summary": summary,
+            "importance": importance,
+            "dependencies": dependencies,
+            "exports_summary": exports_summary,
+            "risks": risks,
+            "top_callers": top_callers,
+        }
+
+    def symbol_narrative(self, node_id: str) -> dict:
+        """Generate a natural language narrative for a single symbol.
+
+        Includes blast radius as percentage of codebase and relative comparisons.
+        """
+        node = self.store.get_node(node_id)
+        if not node:
+            # Try resolving by name
+            resolved = self.engine.resolve_node(node_id)
+            if resolved:
+                node = resolved[0]
+                node_id = node["id"]
+            else:
+                return {"error": f"Symbol not found: {node_id}"}
+
+        name = node["name"]
+        sym_type = node["type"]
+
+        # Get callers
+        reverse_deps = self.engine.get_reverse_dependencies(node_id)
+        callers = [d for d in reverse_deps if d["edge_type"] == "CALLS"]
+        importers = [d for d in reverse_deps if d["edge_type"] == "IMPORTS"]
+
+        # Impact + blast radius percentage
+        impacted = self.engine.impact_of_change(node_id, max_depth=3)
+        affected_files = {e.get("node_id", "").split("::")[0] for e in impacted}
+        affected_files.discard("")
+        affected_files.discard(node["file_path"])
+
+        all_nodes = self.store.get_all_nodes()
+        total_files = len({n["file_path"] for n in all_nodes if n.get("file_path")})
+        blast_pct = len(affected_files) / max(total_files, 1) * 100
+
+        # Summary
+        summary = f"{name} is a {sym_type} defined in {node['file_path']}."
+        if node.get("docstring"):
+            summary += f" {node['docstring'].split(chr(10))[0]}"
+
+        # Importance with blast radius percentage
+        total_deps = len(callers) + len(importers)
+        if total_deps > 5:
+            importance = (
+                f"High — {total_deps} direct dependents, affects {len(affected_files)} files "
+                f"({blast_pct:.0f}% of codebase)."
+            )
+            if blast_pct > 30:
+                importance += " This is a foundational symbol — modify with extreme care."
+        elif total_deps > 0:
+            importance = f"Moderate — {total_deps} direct dependent(s), affects {blast_pct:.0f}% of codebase."
+        else:
+            importance = "Low — no known dependents. Changes here are safe."
+
+        # Usage
+        caller_files = {c["file_path"] for c in callers}
+        if caller_files:
+            usage = f"Called from {len(callers)} location(s) across {len(caller_files)} file(s)."
+        else:
+            usage = "No known call sites."
+
+        # Callers summary — group by file with counts
+        callers_by_file: dict[str, int] = defaultdict(int)
+        for c in callers:
+            callers_by_file[c["file_path"]] += 1
+        top_caller_files = sorted(callers_by_file.items(), key=lambda x: -x[1])[:5]
+
+        if top_caller_files:
+            caller_detail = [f"{fp} ({count}x)" for fp, count in top_caller_files]
+            callers_summary = f"Called by: {', '.join(caller_detail)}."
+            if len(callers) > 5:
+                callers_summary += f" (+{len(callers) - 5} more)"
+        else:
+            callers_summary = "No known callers."
+
+        caller_files_list = [{"file": fp, "count": ct} for fp, ct in top_caller_files]
+
+        # Dependencies
+        outgoing = self.store.get_edges_from(node_id)
+        call_targets = [e["target"] for e in outgoing if e["type"] == "CALLS"]
+        if call_targets:
+            dependencies = f"Calls: {', '.join(call_targets[:10])}."
+        else:
+            dependencies = "No outgoing calls."
+
+        return {
+            "summary": summary,
+            "importance": importance,
+            "usage": usage,
+            "callers_summary": callers_summary,
+            "caller_files": caller_files_list,
+            "dependencies": dependencies,
+        }
+
+    # ------------------------------------------------------------------
+    # Codebase anatomy
+    # ------------------------------------------------------------------
+    def codebase_anatomy(self) -> dict:
+        """Subsystem map for new developers — the 'truck parts' view.
+
+        Groups files into named subsystems with descriptions, importance
+        rankings, and inter-subsystem connections.
+        """
+        overview = self.system_overview()
+        all_nodes = self.store.get_all_nodes()
+        all_edges = self.store.get_all_edges()
+        hotspots = self.risk_hotspots(top_n=50)
+
+        subsystems = self._group_into_subsystems(all_nodes, overview)
+        connections = self._compute_subsystem_connections(subsystems, all_nodes, all_edges)
+        self._score_subsystem_importance(subsystems, hotspots, connections)
+
+        for sub in subsystems:
+            sub["description"] = self._describe_subsystem(sub, connections)
+
+        purpose = self._derive_purpose(overview, subsystems)
+
+        return {
+            "purpose": purpose,
+            "subsystems": subsystems,
+            "connections": connections,
+            "entry_points": overview.get("entry_points", []),
+            "stats": overview.get("stats", {}),
+        }
+
+    # ------------------------------------------------------------------
+    # Anatomy helpers (private)
+    # ------------------------------------------------------------------
+
+    # Known directory → display name mappings
+    _KNOWN_NAMES: dict[str, str] = {
+        "graph": "Graph Engine",
+        "parser": "Parser System",
+        "web": "Web UI",
+        "api": "REST API",
+        "cli": "CLI Interface",
+        "mcp": "MCP Server",
+        "tests": "Test Suite",
+        "test": "Test Suite",
+    }
+
+    def _group_into_subsystems(
+        self, all_nodes: list[dict], overview: dict
+    ) -> list[dict]:
+        """Group files into subsystems using a 3-tier algorithm."""
+        # Build per-file info: file_path → list of non-file nodes
+        file_nodes: dict[str, list[dict]] = defaultdict(list)
+        for node in all_nodes:
+            fp = node.get("file_path", "")
+            if not fp:
+                continue
+            if node["type"] == "file":
+                # ensure the file key exists even with no symbols
+                if fp not in file_nodes:
+                    file_nodes[fp] = []
+            else:
+                file_nodes[fp].append(node)
+
+        # Tier 1: directory-based grouping by parent directory at depth 2
+        dir_groups: dict[str, list[str]] = defaultdict(list)
+        for fp in file_nodes:
+            parts = fp.split("/")
+            # Use the directory path (excluding filename), capped at depth 2
+            dir_parts = parts[:-1] if len(parts) > 1 else []
+            if len(dir_parts) >= 2:
+                key = "/".join(dir_parts[:2])
+            elif dir_parts:
+                key = dir_parts[0]
+            else:
+                key = "(root)"
+            dir_groups[key].append(fp)
+
+        # Tier 4: separate test files into a single group
+        test_files: list[str] = []
+        non_test_groups: dict[str, list[str]] = {}
+        for key, files in dir_groups.items():
+            test = [f for f in files if is_test_file(f)]
+            non_test = [f for f in files if not is_test_file(f)]
+            if test:
+                test_files.extend(test)
+            if non_test:
+                non_test_groups[key] = non_test
+            elif not test:
+                # Key with no files left (shouldn't happen, but safe)
+                non_test_groups[key] = files
+        dir_groups = non_test_groups
+
+        # Tier 2: merge small groups (<2 files) into role-based buckets
+        role_merge: dict[str, list[str]] = defaultdict(list)
+        final_groups: dict[str, list[str]] = {}
+        for key, files in dir_groups.items():
+            if len(files) < 2:
+                for fp in files:
+                    syms = file_nodes.get(fp, [])
+                    sym_dicts = [{"name": s["name"], "type": s["type"]} for s in syms]
+                    role = self._infer_module_role(fp, sym_dicts, 0, 0)
+                    role_merge[role].append(fp)
+            else:
+                final_groups[key] = files
+
+        # Tier 3: singleton promotion — large files get their own subsystem
+        # First, handle role-merged files
+        for role, files in role_merge.items():
+            for fp in files:
+                sym_count = len(file_nodes.get(fp, []))
+                if sym_count >= 5:
+                    final_groups[fp] = [fp]
+                else:
+                    final_groups.setdefault("_utilities", []).append(fp)
+
+        # Also promote large files from big groups (>5 files) that have
+        # many symbols (>= 15) — these are major modules worthy of their own subsystem
+        PROMOTE_THRESHOLD = 15
+        for key in list(final_groups.keys()):
+            files = final_groups[key]
+            if key.startswith("_") or len(files) <= 3:
+                continue
+            promoted = []
+            kept = []
+            for fp in files:
+                sym_count = len(file_nodes.get(fp, []))
+                if sym_count >= PROMOTE_THRESHOLD:
+                    promoted.append(fp)
+                else:
+                    kept.append(fp)
+            if promoted and kept:
+                final_groups[key] = kept
+                for fp in promoted:
+                    final_groups[fp] = [fp]
+
+        if test_files:
+            final_groups["_tests"] = test_files
+
+        # Cap at ~15 subsystems: merge smallest (by symbol count) into "Other"
+        MAX_SUBSYSTEMS = 15
+        if len(final_groups) > MAX_SUBSYSTEMS:
+            by_weight = sorted(
+                final_groups.items(),
+                key=lambda x: sum(len(file_nodes.get(f, [])) for f in x[1]),
+            )
+            keep = dict(by_weight[-(MAX_SUBSYSTEMS - 1):])
+            other_files: list[str] = []
+            for key, files in by_weight[:len(by_weight) - MAX_SUBSYSTEMS + 1]:
+                other_files.extend(files)
+            if other_files:
+                keep["_other"] = other_files
+            final_groups = keep
+
+        # Build subsystem dicts
+        subsystems: list[dict] = []
+        for key, files in sorted(final_groups.items()):
+            slug = self._subsystem_slug(key)
+            name = self._subsystem_name(key)
+
+            # Collect symbols in this subsystem
+            symbols: list[dict] = []
+            for fp in files:
+                symbols.extend(file_nodes.get(fp, []))
+
+            # Determine dominant role
+            roles = Counter()
+            for fp in files:
+                sym_dicts = [{"name": s["name"], "type": s["type"]} for s in file_nodes.get(fp, [])]
+                r = self._infer_module_role(fp, sym_dicts, 0, 0)
+                roles[r] += 1
+            dominant_role = roles.most_common(1)[0][0] if roles else "module"
+
+            # Map role to category
+            ROLE_MAP = {
+                "core_library": "core",
+                "domain_model": "core",
+                "data_model": "core",
+                "orchestrator": "interface",
+                "entry_point": "interface",
+                "configuration": "infrastructure",
+                "utility": "infrastructure",
+                "package_init": "infrastructure",
+                "test": "peripheral",
+            }
+            role_cat = ROLE_MAP.get(dominant_role, "peripheral")
+
+            # Top symbols by name
+            top_syms = sorted(
+                [s for s in symbols if s["type"] in ("class", "function")],
+                key=lambda s: s["name"],
+            )[:5]
+
+            # Find entry points in this subsystem
+            eps = [
+                ep for ep in overview.get("entry_points", [])
+                if ep.get("file_path") in set(files)
+            ]
+
+            subsystems.append({
+                "name": name,
+                "slug": slug,
+                "packages": sorted(set(
+                    "/".join(fp.split("/")[:2]) if "/" in fp else fp
+                    for fp in files
+                )),
+                "files": sorted(files),
+                "file_count": len(files),
+                "symbol_count": len(symbols),
+                "role": role_cat,
+                "importance": 0.0,
+                "importance_label": "peripheral",
+                "description": "",
+                "depends_on": [],
+                "depended_by": [],
+                "entry_points": eps,
+                "top_symbols": [s["name"] for s in top_syms],
+                "risk_score": 0.0,
+            })
+
+        return subsystems
+
+    @staticmethod
+    def _subsystem_slug(key: str) -> str:
+        """Derive a URL-safe slug from a grouping key."""
+        if key == "_utilities":
+            return "utilities"
+        if key == "_tests":
+            return "tests"
+        if key == "_other":
+            return "other"
+        # Use last path segment, lowercase
+        return key.split("/")[-1].removesuffix(".py").lower().replace(" ", "-")
+
+    def _subsystem_name(self, key: str) -> str:
+        """Derive a human-readable name from a grouping key."""
+        if key == "_utilities":
+            return "Utilities"
+        if key == "_tests":
+            return "Test Suite"
+        if key == "_other":
+            return "Other"
+
+        last = key.split("/")[-1].removesuffix(".py")
+        # Check known mappings
+        if last.lower() in self._KNOWN_NAMES:
+            return self._KNOWN_NAMES[last.lower()]
+        # Title case
+        return last.replace("_", " ").replace("-", " ").title()
+
+    def _compute_subsystem_connections(
+        self,
+        subsystems: list[dict],
+        all_nodes: list[dict],
+        all_edges: list[dict],
+    ) -> list[dict]:
+        """Count inter-subsystem edges to build connection list."""
+        # Map file_path → subsystem slug
+        file_to_slug: dict[str, str] = {}
+        for sub in subsystems:
+            for fp in sub["files"]:
+                file_to_slug[fp] = sub["slug"]
+
+        # Map node id/name/qname → file_path for target resolution
+        node_file: dict[str, str] = {}
+        for n in all_nodes:
+            fp = n.get("file_path", "")
+            if fp:
+                node_file[n["id"]] = fp
+                node_file[n["name"]] = fp
+                if n["qualified_name"] != n["name"]:
+                    node_file[n["qualified_name"]] = fp
+
+        # Count edges between subsystems
+        edge_counts: dict[tuple[str, str], int] = Counter()
+        for e in all_edges:
+            if e["type"] not in ("CALLS", "IMPORTS"):
+                continue
+            src_file = e.get("file_path", "")
+            src_slug = file_to_slug.get(src_file)
+            if not src_slug:
+                continue
+            tgt_file = node_file.get(e["target"], "")
+            tgt_slug = file_to_slug.get(tgt_file)
+            if not tgt_slug or tgt_slug == src_slug:
+                continue
+            edge_counts[(src_slug, tgt_slug)] += 1
+
+        # Build depends_on / depended_by on subsystems
+        slug_lookup = {s["slug"]: s for s in subsystems}
+        for (from_slug, to_slug), count in edge_counts.items():
+            if to_slug not in slug_lookup.get(from_slug, {}).get("depends_on", []):
+                slug_lookup[from_slug]["depends_on"].append(to_slug)
+            if from_slug not in slug_lookup.get(to_slug, {}).get("depended_by", []):
+                slug_lookup[to_slug]["depended_by"].append(from_slug)
+
+        # Sort depends_on / depended_by
+        for sub in subsystems:
+            sub["depends_on"] = sorted(set(sub["depends_on"]))
+            sub["depended_by"] = sorted(set(sub["depended_by"]))
+
+        connections = [
+            {
+                "from": from_slug,
+                "to": to_slug,
+                "strength": count,
+                "label": f"{count} calls + imports",
+            }
+            for (from_slug, to_slug), count in sorted(
+                edge_counts.items(), key=lambda x: -x[1]
+            )
+        ]
+        return connections
+
+    def _score_subsystem_importance(
+        self,
+        subsystems: list[dict],
+        hotspots: list[dict],
+        connections: list[dict],
+    ) -> None:
+        """Score each subsystem's importance (0.0–1.0) and assign labels."""
+        total_subsystems = max(len(subsystems), 1)
+
+        # Build hotspot risk per file
+        risk_by_file: dict[str, float] = defaultdict(float)
+        for h in hotspots:
+            risk_by_file[h["file_path"]] += h["risk_score"]
+
+        raw_scores: list[float] = []
+        for sub in subsystems:
+            incoming = len(sub.get("depended_by", []))
+            risk_agg = sum(risk_by_file.get(fp, 0.0) for fp in sub["files"])
+            sub["risk_score"] = round(risk_agg, 1)
+            sym_count = sub["symbol_count"]
+            has_entry = 1.0 if sub.get("entry_points") else 0.0
+            conn_count = len(sub.get("depends_on", [])) + len(sub.get("depended_by", []))
+            centrality = conn_count / max(total_subsystems, 1)
+
+            score = (
+                incoming * 0.4
+                + risk_agg * 0.25
+                + sym_count * 0.15
+                + has_entry * 0.1
+                + centrality * 0.1
+            )
+            raw_scores.append(score)
+
+        # Normalize to 0.0–1.0
+        max_raw = max(raw_scores) if raw_scores else 1.0
+        if max_raw == 0:
+            max_raw = 1.0
+
+        for sub, raw in zip(subsystems, raw_scores):
+            normalized = round(raw / max_raw, 2)
+            sub["importance"] = normalized
+            if normalized >= 0.75:
+                sub["importance_label"] = "critical"
+            elif normalized >= 0.50:
+                sub["importance_label"] = "important"
+            elif normalized >= 0.25:
+                sub["importance_label"] = "supporting"
+            else:
+                sub["importance_label"] = "peripheral"
+
+    def _describe_subsystem(self, subsystem: dict, connections: list[dict]) -> str:
+        """Generate a deterministic one-liner description for a subsystem."""
+        # Try __init__.py docstring from the files
+        for fp in subsystem["files"]:
+            if fp.endswith("__init__.py"):
+                nodes = self.store.get_nodes_by_file(fp)
+                for n in nodes:
+                    if n["type"] == "file" and n.get("docstring"):
+                        return n["docstring"].split("\n")[0]
+
+        role = subsystem["role"].replace("_", " ").title()
+        sym_count = subsystem["symbol_count"]
+        top = subsystem["top_symbols"][:3]
+        dep_count = len(subsystem.get("depended_by", []))
+
+        top_str = ", ".join(top) if top else "no public symbols"
+        dep_str = f"Depended on by {dep_count} other subsystem{'s' if dep_count != 1 else ''}." if dep_count else "No dependents."
+
+        return f"{role} providing {sym_count} symbols including {top_str}. {dep_str}"
+
+    def _derive_purpose(self, overview: dict, subsystems: list[dict]) -> str:
+        """Generate a one-line codebase purpose statement."""
+        stats = overview.get("stats", {})
+        file_count = stats.get("files", 0)
+        sub_count = len(subsystems)
+
+        # Find the most important non-utility subsystem
+        real_subs = [s for s in subsystems if s["slug"] not in ("other", "tests", "utilities")]
+        top_sub = max(real_subs, key=lambda s: s["importance"]) if real_subs else (
+            max(subsystems, key=lambda s: s["importance"]) if subsystems else None
+        )
+        center = top_sub["name"] if top_sub else "unknown"
+
+        # Detect dominant language from file extensions
+        all_files = []
+        for sub in subsystems:
+            all_files.extend(sub["files"])
+        py_count = sum(1 for f in all_files if f.endswith(".py"))
+        ts_count = sum(1 for f in all_files if f.endswith((".ts", ".tsx", ".js", ".jsx")))
+        if py_count > ts_count:
+            lang = "Python"
+        elif ts_count > py_count:
+            lang = "TypeScript"
+        elif py_count and ts_count:
+            lang = "Python + TypeScript"
+        else:
+            lang = "source"
+
+        return (
+            f"A {lang} project with {file_count} files organized into "
+            f"{sub_count} subsystem{'s' if sub_count != 1 else ''}, "
+            f"centered around {center}."
+        )
+
+    # ------------------------------------------------------------------
+    # Ask: natural language question answering
+    # ------------------------------------------------------------------
+
+    # Order matters: more specific patterns first, broad ones (overview) last.
+    _INTENT_PATTERNS = {
+        "risk":       r"\b(risk\w*|dangerous|fragile|hotspot)\b",
+        "health":     r"\b(health|score|grade|quality)\b",
+        "dead_code":  r"\b(dead|unused|unreachable)\b",
+        "cycles":     r"\b(cycle|circular|import loop)\b",
+        "impact":     r"\b(impact|affect|change|break|depends?)\b.*\b(\w+)\b",
+        "module":     r"\b(module|file|package)\b.*\b(does?|about|role|purpose)\b",
+        "anatomy":    r"\b(anatomy|subsystem|parts?|structure|how.*organized)\b",
+        "symbol":     r"\b(function|class|method|symbol)\b.*\b(does?|what|where|who)\b",
+        "overview":   r"\b(overview|summary|what is|describe|about|main parts?|main packages?|main modules?)\b",
+    }
+
+    _STOP_WORDS = frozenset({
+        "what", "does", "how", "the", "this", "that", "with", "from",
+        "about", "which", "where", "when", "would", "could", "should",
+        "have", "been", "being", "will", "they", "them", "their",
+        "most", "more", "some", "each", "every", "there", "here",
+        "into", "between", "through", "after", "before", "these",
+        "those", "other", "than", "very", "just", "only",
+    })
+
+    _SUGGESTIONS: dict[str, list[str]] = {
+        "overview": [
+            "What are the riskiest parts of the codebase?",
+            "What's the health score?",
+            "How is the codebase organized?",
+        ],
+        "module": [
+            "What are the riskiest files?",
+            "What's the health score?",
+        ],
+        "risk": [
+            "What would break if I changed the riskiest symbol?",
+            "What's the health score?",
+            "Are there any import cycles?",
+        ],
+        "health": [
+            "What are the riskiest files?",
+            "What dead code should I clean up?",
+            "Are there any import cycles?",
+        ],
+        "impact": [
+            "What are the riskiest parts of the codebase?",
+            "How is the codebase organized?",
+        ],
+        "anatomy": [
+            "What are the main parts of this codebase?",
+            "What are the riskiest files?",
+            "What's the health score?",
+        ],
+        "dead_code": [
+            "What's the health score?",
+            "What are the riskiest files?",
+        ],
+        "cycles": [
+            "What's the health score?",
+            "How is the codebase organized?",
+        ],
+        "symbol": [
+            "What are the riskiest parts of the codebase?",
+            "What's the health score?",
+        ],
+        "general": [
+            "What are the main parts of this codebase?",
+            "What's the health score?",
+            "What are the riskiest files?",
+        ],
+    }
+
+    @staticmethod
+    def _extract_keywords(question: str) -> list[str]:
+        """Extract meaningful keywords from a question (stop-word filtered + bigrams)."""
+        words = re.findall(r"[a-z_]+", question.lower())
+        words = [w for w in words if len(w) > 3 and w not in ComprehensionEngine._STOP_WORDS]
+        bigrams = [f"{words[i]} {words[i+1]}" for i in range(len(words) - 1)]
+        return (words + bigrams)[:5]
+
+    def answer_question(self, question: str) -> dict:
+        """Answer a natural language question about the codebase.
+
+        Uses regex intent detection to route the question to the right
+        structural data source. Fully deterministic — no LLM call.
+
+        Returns:
+            {
+                "question": str,
+                "intent": str,
+                "answer": str,
+                "data": dict | list,
+                "sources": list[str],
+                "suggestions": list[str],
+            }
+        """
+        q_lower = question.lower()
+
+        # Detect intent
+        intent = "general"
+        for name, pattern in self._INTENT_PATTERNS.items():
+            if re.search(pattern, q_lower):
+                intent = name
+                break
+
+        answer = ""
+        data: dict | list = {}
+        sources: list[str] = []
+
+        if intent == "overview":
+            overview = self.system_overview()
+            stats = overview["stats"]
+            pkgs = sorted(overview["packages"].keys())
+            answer = (
+                f"This codebase has {stats.get('files', 0)} files and "
+                f"{stats.get('nodes', 0)} symbols across "
+                f"{len(pkgs)} package{'s' if len(pkgs) != 1 else ''}: "
+                f"{', '.join(pkgs)}."
+            )
+            data = overview
+            sources = ["system_overview"]
+
+        elif intent == "module":
+            # Try to extract a module/file name from the question
+            mod_name = self._extract_module_name(question)
+            if mod_name:
+                view = self.module_view(mod_name)
+                if "error" not in view:
+                    narrative = self.module_narrative(mod_name)
+                    answer = narrative.get("summary", f"Module {mod_name} found.")
+                    data = view
+                    sources = ["module_view", "module_narrative"]
+                else:
+                    answer = f"Could not find module '{mod_name}'. Try using the full file path."
+                    data = {"error": view["error"]}
+                    sources = ["module_view"]
+            else:
+                answer = "Please specify a module or file name in your question."
+                data = {}
+                sources = []
+
+        elif intent == "risk":
+            hotspots = self.risk_hotspots(top_n=10)
+            if hotspots:
+                lines = []
+                for i, h in enumerate(hotspots[:5], 1):
+                    lines.append(
+                        f"  {i}. {h['name']} ({h['file_path']}) — "
+                        f"risk: {h['risk_score']}, {h['direct_dependents']} dependents, "
+                        f"{h['affected_files']} affected files"
+                    )
+                answer = "Top risk hotspots:\n" + "\n".join(lines)
+            else:
+                answer = "No significant risk hotspots found."
+            data = hotspots
+            sources = ["risk_hotspots"]
+
+        elif intent == "health":
+            health = self.health_score()
+            d = health["details"]
+            answer = (
+                f"Health score: {health['score']}/100 (grade {health['grade']}). "
+                f"Dead code: {d['dead_code_count']} symbols ({d['dead_code_ratio']:.0%}). "
+                f"Import cycles: {d['import_cycles']}. "
+                f"High-risk hotspots: {d['high_risk_hotspots']}."
+            )
+            data = health
+            sources = ["health_score"]
+
+        elif intent == "impact":
+            # Try to find a file path first (e.g. "store.py")
+            file_path_match = self._extract_module_name(question)
+            # Extract a symbol name from the question.
+            # Prefer CamelCase / capitalised names (likely real symbols)
+            # over lowercase verbs like "depends", "change", "break".
+            symbol_name = self._extract_symbol_name(question)
+            # Also extract keywords and try each until one resolves
+            keywords = self._extract_keywords(question)
+            candidates = []
+            if symbol_name:
+                candidates.append(symbol_name)
+            candidates.extend(keywords)
+
+            node = None
+            tried_name = None
+            for candidate in candidates:
+                nodes = self.engine.resolve_node(candidate)
+                if nodes:
+                    node = nodes[0]
+                    tried_name = candidate
+                    break
+                tried_name = candidate
+
+            if node is not None:
+                impacted = self.engine.impact_of_change(node["id"], max_depth=5)
+                affected_files: set[str] = set()
+                all_nodes_list = self.store.get_all_nodes()
+                node_by_id = {n["id"]: n for n in all_nodes_list}
+                for entry in impacted:
+                    t = node_by_id.get(entry["node_id"])
+                    if t:
+                        affected_files.add(t["file_path"])
+                answer = (
+                    f"Changing {node['name']} ({node['file_path']}) would impact "
+                    f"{len(impacted)} symbols across {len(affected_files)} files."
+                )
+                data = {"target": node["id"], "impacted_count": len(impacted),
+                        "affected_files": sorted(affected_files)}
+                sources = ["impact_of_change"]
+            elif file_path_match:
+                # Fall back to change_summary for file-based impact
+                summary = self.change_summary(file_path_match)
+                answer = (
+                    f"Changing {file_path_match} would affect "
+                    f"{summary['affected_file_count']} files."
+                )
+                data = summary
+                sources = ["change_summary"]
+            elif tried_name:
+                answer = f"No symbol found matching '{tried_name}'."
+                data = {}
+                sources = ["resolve_node"]
+            else:
+                answer = "Please mention a symbol name to analyze impact."
+                data = {}
+                sources = []
+
+        elif intent == "anatomy":
+            anatomy = self.codebase_anatomy()
+            sub_lines = []
+            for sub in anatomy.get("subsystems", []):
+                sub_lines.append(
+                    f"  - {sub['name']} ({sub['file_count']} files, "
+                    f"{sub['symbol_count']} symbols, {sub['importance_label']})"
+                )
+            answer = (
+                anatomy.get("purpose", "Unknown purpose.") + "\n\n"
+                "Subsystems:\n" + "\n".join(sub_lines)
+            )
+            data = anatomy
+            sources = ["codebase_anatomy"]
+
+        elif intent == "dead_code":
+            dead = self.engine.find_dead_code()
+            if dead:
+                sample = dead[:5]
+                lines = [f"  - {d['name']} ({d['type']}) in {d['file_path']}" for d in sample]
+                answer = (
+                    f"Found {len(dead)} potentially unused symbols.\n"
+                    + "\n".join(lines)
+                )
+                if len(dead) > 5:
+                    answer += f"\n  ... and {len(dead) - 5} more."
+            else:
+                answer = "No dead code detected."
+            data = dead
+            sources = ["find_dead_code"]
+
+        elif intent == "cycles":
+            cycles = self.engine.detect_cycles()
+            if cycles:
+                lines = []
+                for c in cycles[:5]:
+                    path = " -> ".join(c) if isinstance(c, list) else str(c)
+                    lines.append(f"  - {path}")
+                answer = f"Found {len(cycles)} import cycle(s):\n" + "\n".join(lines)
+                if len(cycles) > 5:
+                    answer += f"\n  ... and {len(cycles) - 5} more."
+            else:
+                answer = "No import cycles detected."
+            data = cycles
+            sources = ["detect_cycles"]
+
+        elif intent == "symbol":
+            keywords = self._extract_keywords(question)
+            symbol_name = keywords[0] if keywords else None
+            if symbol_name:
+                nodes = self.engine.resolve_node(symbol_name)
+                if nodes:
+                    node = nodes[0]
+                    narrative = self.symbol_narrative(node["id"])
+                    answer = narrative.get("summary", f"Found {node['name']}.")
+                    data = narrative
+                    sources = ["symbol_narrative"]
+                else:
+                    answer = f"No symbol found matching '{symbol_name}'."
+                    data = {}
+                    sources = ["resolve_node"]
+            else:
+                answer = "Please mention a symbol name in your question."
+                data = {}
+                sources = []
+
+        else:
+            # General: keyword search + overview stats
+            keywords = self._extract_keywords(question)
+            search_results = []
+            for kw in keywords[:5]:
+                results = self.engine.search_nodes(kw, limit=5)
+                search_results.extend(results)
+            # Deduplicate by id
+            seen_ids: set[str] = set()
+            unique_results: list[dict] = []
+            for r in search_results:
+                if r["id"] not in seen_ids:
+                    seen_ids.add(r["id"])
+                    unique_results.append(r)
+
+            overview = self.system_overview()
+            stats = overview["stats"]
+            if unique_results:
+                lines = [f"  - {r['name']} ({r['type']}) in {r['file_path']}" for r in unique_results[:5]]
+                answer = (
+                    f"Found {len(unique_results)} matching symbols "
+                    f"(in a codebase with {stats.get('files', 0)} files):\n"
+                    + "\n".join(lines)
+                )
+            else:
+                pkgs = sorted(overview["packages"].keys())
+                answer = (
+                    f"No specific matches found. This codebase has "
+                    f"{stats.get('files', 0)} files and {stats.get('nodes', 0)} symbols "
+                    f"across packages: {', '.join(pkgs)}."
+                )
+            data = {"search_results": unique_results[:15], "stats": stats}
+            sources = ["search_nodes", "system_overview"]
+
+        suggestions = self._SUGGESTIONS.get(intent, self._SUGGESTIONS["general"])
+
+        return {
+            "question": question,
+            "intent": intent,
+            "answer": answer,
+            "data": data,
+            "sources": sources,
+            "suggestions": suggestions,
+        }
+
+    def _extract_module_name(self, question: str) -> str | None:
+        """Try to extract a file/module path from the question."""
+        # Look for explicit file paths (e.g. "mypackage/core.py")
+        path_match = re.search(r"[\w/\\]+\.(?:py|ts|tsx|js|jsx)", question)
+        if path_match:
+            return path_match.group(0).replace("\\", "/")
+
+        # Look for quoted names
+        quoted = re.search(r'["\']([^"\']+)["\']', question)
+        if quoted:
+            return quoted.group(1)
+
+        # Look for module-like words after "module" or "file"
+        mod_match = re.search(r"\b(?:module|file)\s+(\w[\w./]*)", question, re.IGNORECASE)
+        if mod_match:
+            return mod_match.group(1)
+
+        return None
+
+    @staticmethod
+    def _extract_symbol_name(question: str) -> str | None:
+        """Extract a likely symbol name from the question.
+
+        Prefers CamelCase identifiers (e.g. GraphStore, DataProcessor) or
+        names inside quotes. Falls back to ``None`` so the caller can try
+        keyword extraction instead.
+        """
+        # Quoted names first
+        quoted = re.search(r'["\']([^"\']+)["\']', question)
+        if quoted:
+            return quoted.group(1)
+
+        # CamelCase identifiers (at least two uppercase letters)
+        camel = re.findall(r"\b([A-Z][a-z]+(?:[A-Z][a-z]*)+)\b", question)
+        if camel:
+            return camel[0]
+
+        # Single capitalised word that is NOT a sentence starter
+        # e.g. "What depends on Store?" -> "Store"
+        caps = re.findall(r"(?<!\.\s)(?<!^)\b([A-Z][a-z]{2,})\b", question)
+        if caps:
+            return caps[0]
+
+        return None
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+    def _extract_module_name_from_impact(self, question: str) -> str | None:
+        """Extract a file path from an impact-style question."""
+        path_match = re.search(r"[\w/\\]+\.(?:py|ts|tsx|js|jsx)", question)
+        if path_match:
+            return path_match.group(0).replace("\\", "/")
+        return None
+
+    def _infer_module_role(
+        self, file_path: str, symbols: list[dict], coupling_in: int, coupling_out: int
+    ) -> str:
+        """Infer the architectural role of a module from its structure and coupling.
+
+        Uses a combination of filename conventions, symbol composition, and
+        coupling patterns. Returns a role string. When multiple signals conflict,
+        coupling-based signals take precedence over filename-based ones.
+        """
+        name = file_path.split("/")[-1]
+        # Remove extension (.py, .ts, .tsx, .js, .jsx)
+        stem = name.rsplit(".", 1)[0] if "." in name else name
+
+        # Unambiguous filename matches
+        if stem == "__init__":
+            return "package_init"
+        if stem == "__main__":
+            return "entry_point"
+        if stem.startswith("test_") or stem.endswith("_test") or stem.endswith(".test"):
+            return "test"
+
+        classes = [s for s in symbols if s["type"] == "class"]
+        functions = [s for s in symbols if s["type"] == "function"]
+        methods = [s for s in symbols if s["type"] == "method"]
+
+        # Coupling-based roles (structural evidence, more reliable than name)
+        if coupling_in > coupling_out * 2 and coupling_in > 3:
+            return "core_library"
+        if coupling_out > coupling_in * 3 and coupling_out > 3:
+            return "orchestrator"
+        if coupling_in == 0 and coupling_out == 0:
+            return "isolated"
+
+        # Filename hints (only for common conventions)
+        if stem in ("config", "settings", "constants", "conf"):
+            return "configuration"
+        if stem in ("utils", "helpers", "util", "common"):
+            return "utility"
+        if stem in ("models", "schemas", "types", "entities"):
+            return "data_model"
+
+        # Composition-based roles
+        if len(classes) > len(functions) and classes:
+            return "domain_model"
+        if functions and not classes:
+            if coupling_in > 0:
+                return "function_library"
+            return "script"
+
+        return "module"