codegraph-brain 0.6.0__py3-none-any.whl

cgis/query/analysis/analyzer.py

@@ -0,0 +1,241 @@
+"""Architectural anti-pattern detector powered by graph traversal algorithms."""
+
+import structlog
+
+from cgis.core.models import Edge, EdgeType, Node, NodeNamespace, NodeType
+from cgis.query.analysis.anomaly import AnomalyType, ArchitecturalAnomaly, ArchitecturalReport
+from cgis.query.drift._scc import build_adjacency, tarjan_scc
+from cgis.storage.sqlite_store import SQLiteStore
+
+log = structlog.getLogger(__name__)
+
+# Thresholds -- tuned for typical Python codebases
+_ZONE_OF_PAIN_DISTANCE = (
+    0.70  # D-distance threshold; Zone of Pain: D > 0.7 AND I <= 0.3 (stable + concrete)
+)
+_ZONE_OF_PAIN_MAX_INSTABILITY = 0.30  # I <= 0.3 means "stable" (more dependents than dependencies)
+_ZONE_OF_PAIN_MIN_AFFERENT = 3  # require >= 3 callers to avoid flagging obscure low-usage classes
+_GOD_OBJECT_MIN_METHODS = 10  # classes below this are too small to qualify regardless of coupling
+_GOD_OBJECT_MIN_EFFERENT = 5  # low coupling means cohesion is still acceptable
+
+
+def _build_method_to_class(nodes: list[Node], edges: list[Edge]) -> dict[str, str]:
+    """Return a mapping of method FQN -> parent class FQN."""
+    method_ids = {n.id for n in nodes if n.type == NodeType.METHOD}
+    result: dict[str, str] = {}
+    for edge in edges:
+        if edge.type in (EdgeType.CONTAINS, EdgeType.DECLARES) and edge.target in method_ids:
+            result[edge.target] = edge.source
+    return result
+
+
+def _compute_class_coupling(
+    internal_classes: set[str],
+    edges: list[Edge],
+    method_to_class: dict[str, str],
+) -> tuple[dict[str, set[str]], dict[str, set[str]]]:
+    """Compute afferent (Ca) and efferent (Ce) coupling per internal class."""
+    ca: dict[str, set[str]] = {fqn: set() for fqn in internal_classes}
+    ce: dict[str, set[str]] = {fqn: set() for fqn in internal_classes}
+    for edge in edges:
+        if edge.type != EdgeType.CALLS:
+            continue
+        src = method_to_class.get(edge.source, edge.source)
+        tgt = method_to_class.get(edge.target, edge.target)
+        if src == tgt:
+            continue
+        if tgt in internal_classes:
+            ca[tgt].add(src)
+        if src in internal_classes:
+            ce[src].add(tgt)
+    return ca, ce
+
+
+def _get_abstract_fqns(internal_classes: set[str], nodes: list[Node]) -> set[str]:
+    """Return FQNs of internal classes that are abstract (metadata only).
+
+    Only metadata-flagged classes qualify; using EXTENDS would misclassify
+    concrete subclasses (e.g. UserService(Base)) as abstract.
+    """
+    return {n.id for n in nodes if n.id in internal_classes and n.metadata.get("is_abstract")}
+
+
+def _build_class_method_map(
+    internal_classes: set[str], nodes: list[Node], edges: list[Edge]
+) -> dict[str, set[str]]:
+    """Return a mapping of class FQN -> set of its method FQNs."""
+    method_ids = {n.id for n in nodes if n.type == NodeType.METHOD}
+    result: dict[str, set[str]] = {fqn: set() for fqn in internal_classes}
+    for edge in edges:
+        if (
+            edge.type in (EdgeType.CONTAINS, EdgeType.DECLARES)
+            and edge.source in internal_classes
+            and edge.target in method_ids
+        ):
+            result[edge.source].add(edge.target)
+    return result
+
+
+class AnalyzerEngine:
+    """Detects architectural anti-patterns from a fully-ingested code graph."""
+
+    def __init__(self, store: SQLiteStore) -> None:
+        """Load all nodes and edges from the store for in-memory analysis."""
+        self._nodes: list[Node] = store.get_all_nodes()
+        self._edges: list[Edge] = store.get_all_edges()
+
+    def detect_cycles(self) -> list[ArchitecturalAnomaly]:
+        """Find circular dependencies using Tarjan's SCC on IMPORTS edges.
+
+        Returns one anomaly per cycle, containing the full cycle as a list
+        in metrics["cycle_members"].
+        """
+        internal_fqns = {
+            n.id
+            for n in self._nodes
+            if n.namespace == NodeNamespace.INTERNAL and n.type in (NodeType.FILE, NodeType.MODULE)
+        }
+        adj = build_adjacency(self._edges, frozenset({EdgeType.IMPORTS}))
+        adj = {
+            k: [v for v in vs if v in internal_fqns] for k, vs in adj.items() if k in internal_fqns
+        }
+
+        anomalies: list[ArchitecturalAnomaly] = []
+        for scc in tarjan_scc(adj):
+            if len(scc) < 2:
+                continue
+            sorted_members = sorted(scc)
+            severity = min(1.0, (len(scc) - 1) / 4)
+            anomalies.append(
+                ArchitecturalAnomaly(
+                    id="cycle_" + "_".join(sorted_members[:3]),
+                    type=AnomalyType.CIRCULAR_DEPENDENCY,
+                    focal_fqn=sorted_members[0],
+                    severity_score=round(severity, 2),
+                    metrics={"cycle_length": len(scc), "cycle_members": sorted_members},
+                    refactoring_hint=(
+                        "Break the cycle with a Mediator, shared abstraction, or by "
+                        "extracting the shared dependency into a third module."
+                    ),
+                )
+            )
+
+        log.info("Cycle detection complete.", cycles_found=len(anomalies))
+        return anomalies
+
+    def detect_zone_of_pain(self) -> list[ArchitecturalAnomaly]:
+        """Detect classes in Uncle Bob's Zone of Pain (stable + concrete).
+
+        Uses afferent/efferent coupling from CALLS edges to compute instability I,
+        and node metadata to determine abstractness A.
+        High stability (I->0) + low abstractness (A=0) means D-distance approaches 1.0.
+        """
+        internal_classes = {
+            n.id
+            for n in self._nodes
+            if n.type == NodeType.CLASS and n.namespace == NodeNamespace.INTERNAL
+        }
+        if not internal_classes:
+            return []
+
+        method_to_class = _build_method_to_class(self._nodes, self._edges)
+        ca, ce = _compute_class_coupling(internal_classes, self._edges, method_to_class)
+        abstract_fqns = _get_abstract_fqns(internal_classes, self._nodes)
+
+        anomalies: list[ArchitecturalAnomaly] = []
+        for fqn in internal_classes:
+            ca_count = len(ca[fqn])
+            ce_count = len(ce[fqn])
+            total = ca_count + ce_count
+            if total == 0 or ca_count < _ZONE_OF_PAIN_MIN_AFFERENT:
+                continue
+            instability = ce_count / total
+            abstractness = 1.0 if fqn in abstract_fqns else 0.0
+            d_distance = abs(abstractness + instability - 1.0)
+            if (
+                d_distance >= _ZONE_OF_PAIN_DISTANCE
+                and instability <= _ZONE_OF_PAIN_MAX_INSTABILITY
+            ):
+                anomalies.append(
+                    ArchitecturalAnomaly(
+                        id=f"zop_{fqn}",
+                        type=AnomalyType.ZONE_OF_PAIN,
+                        focal_fqn=fqn,
+                        severity_score=round(d_distance, 2),
+                        metrics={
+                            "afferent_coupling": ca_count,
+                            "efferent_coupling": ce_count,
+                            "instability": round(instability, 3),
+                            "abstractness": abstractness,
+                            "d_distance": round(d_distance, 3),
+                        },
+                        refactoring_hint=(
+                            "Introduce an Abstract Base Class or Protocol to invert the "
+                            "dependency, making this module stable-and-abstract rather than "
+                            "stable-and-concrete."
+                        ),
+                    )
+                )
+
+        log.info("Zone of Pain detection complete.", found=len(anomalies))
+        return anomalies
+
+    def detect_god_objects(self) -> list[ArchitecturalAnomaly]:
+        """Detect God Objects: classes with too many methods and high efferent coupling."""
+        internal_classes = {
+            n.id
+            for n in self._nodes
+            if n.type == NodeType.CLASS and n.namespace == NodeNamespace.INTERNAL
+        }
+        if not internal_classes:
+            return []
+
+        class_methods = _build_class_method_map(internal_classes, self._nodes, self._edges)
+        method_to_class = {m: cls for cls, methods in class_methods.items() for m in methods}
+        efferent: dict[str, set[str]] = {fqn: set() for fqn in internal_classes}
+        for edge in self._edges:
+            if edge.type != EdgeType.CALLS:
+                continue
+            src_class = method_to_class.get(edge.source)
+            if src_class is None:
+                continue
+            tgt_class = method_to_class.get(edge.target, edge.target)
+            if tgt_class != src_class:
+                efferent[src_class].add(tgt_class)
+
+        anomalies: list[ArchitecturalAnomaly] = []
+        for fqn in internal_classes:
+            m_count = len(class_methods[fqn])
+            e_count = len(efferent[fqn])
+            if m_count < _GOD_OBJECT_MIN_METHODS or e_count < _GOD_OBJECT_MIN_EFFERENT:
+                continue
+            severity = min(
+                1.0,
+                (m_count / _GOD_OBJECT_MIN_METHODS) * (e_count / _GOD_OBJECT_MIN_EFFERENT) / 4,
+            )
+            anomalies.append(
+                ArchitecturalAnomaly(
+                    id=f"god_{fqn}",
+                    type=AnomalyType.GOD_OBJECT,
+                    focal_fqn=fqn,
+                    severity_score=round(severity, 2),
+                    metrics={"method_count": m_count, "efferent_coupling": e_count},
+                    refactoring_hint=(
+                        "Apply Single Responsibility Principle: extract cohesive groups of "
+                        "methods into focused collaborator classes."
+                    ),
+                )
+            )
+
+        log.info("God Object detection complete.", found=len(anomalies))
+        return anomalies
+
+    def run(self) -> ArchitecturalReport:
+        """Run all detectors and return a consolidated health report."""
+        anomalies = self.detect_cycles() + self.detect_zone_of_pain() + self.detect_god_objects()
+        internal_count = sum(1 for n in self._nodes if n.namespace == NodeNamespace.INTERNAL)
+        return ArchitecturalReport(
+            total_nodes_analyzed=internal_count,
+            total_anomalies=len(anomalies),
+            anomalies=tuple(anomalies),
+        )

cgis/query/analysis/anomaly.py

@@ -0,0 +1,34 @@
+"""Pydantic models for architectural anomaly reporting."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class AnomalyType(StrEnum):
+    """Categories of architectural anti-patterns detectable from the code graph."""
+
+    CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY"
+    ZONE_OF_PAIN = "ZONE_OF_PAIN"
+    GOD_OBJECT = "GOD_OBJECT"
+
+
+class ArchitecturalAnomaly(BaseModel, frozen=True):
+    """A single detected architectural anti-pattern with supporting metrics."""
+
+    id: str = Field(..., description="Unique anomaly identifier (deterministic)")
+    type: AnomalyType
+    focal_fqn: str = Field(..., description="FQN of the primary node violating the pattern")
+    severity_score: float = Field(..., ge=0.0, le=1.0, description="Normalised severity 0-1")
+    metrics: dict[str, float | int | list[str]] = Field(
+        ..., description="Raw computed metrics supporting this finding"
+    )
+    refactoring_hint: str = Field(..., description="Suggested untangling strategy")
+
+
+class ArchitecturalReport(BaseModel, frozen=True):
+    """Full architectural health report for a codebase snapshot."""
+
+    total_nodes_analyzed: int
+    total_anomalies: int
+    anomalies: tuple[ArchitecturalAnomaly, ...]

cgis/query/analysis/cohesion.py

@@ -0,0 +1,277 @@
+"""Package-cohesion analysis: community detection over a package's file graph (#242).
+
+Pure logic, no I/O. The intra-package file graph is undirected and weighted; edge
+reconciliation is done in-memory by dot-boundary FQN suffix so the result does not
+depend on the ingest root (src/ vs src/cgis/ — the #242 load-bearing fix).
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from cgis.core.models import Edge, EdgeType, Node, NodeType
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable, Mapping
+
+_FILE_TYPES = frozenset({NodeType.FILE, NodeType.MODULE})
+
+
+@dataclass(frozen=True)
+class FileGraph:
+    """Undirected, weighted intra-package file graph.
+
+    ``files`` lists every file under the package prefix (sorted, including
+    isolated leaves). ``adj`` is a symmetric weighted adjacency: ``adj[a][b]``
+    == ``adj[b][a]`` is the aggregated import (and optionally call) weight
+    between two files. Isolated files have no ``adj`` entry.
+    """
+
+    files: tuple[str, ...]
+    adj: dict[str, dict[str, float]]
+
+
+def _under(fqn: str, prefix: str) -> bool:
+    """Return True iff fqn is the prefix itself or a dot-boundary child of it.
+
+    An empty prefix matches nothing — the service normalizes a missing/blank
+    prefix to a no_signal report before this is ever reached.
+    """
+    return bool(prefix) and (fqn == prefix or fqn.startswith(prefix + "."))
+
+
+def _build_suffix_index(file_ids: list[str]) -> dict[str, str]:
+    """Map every dot-boundary suffix of each file id to that id.
+
+    A suffix shared by two files maps to the sentinel ``""`` (ambiguous — never
+    reconcile to it). Used to link an import target written with a different
+    root (``cgis.p.b``) back to the in-graph file (``p.b``).
+    """
+    index: dict[str, str] = {}
+    for fid in file_ids:
+        parts = fid.split(".")
+        for i in range(len(parts)):
+            suffix = ".".join(parts[i:])
+            index[suffix] = "" if suffix in index and index[suffix] != fid else fid
+    return index
+
+
+def _resolve_to_file(node_id: str, file_set: set[str], suffix_index: dict[str, str]) -> str | None:
+    """Resolve an edge endpoint to a file under the prefix, or None.
+
+    Exact membership wins; otherwise the longest dot-boundary suffix of
+    ``node_id`` that uniquely names a file. Ambiguous or absent → None.
+    """
+    if node_id in file_set:
+        return node_id
+    parts = node_id.split(".")
+    for i in range(len(parts)):
+        hit = suffix_index.get(".".join(parts[i:]))
+        if hit:
+            return hit
+    return None
+
+
+def build_file_graph(
+    nodes: list[Node], edges: list[Edge], prefix: str, with_calls: bool
+) -> FileGraph:
+    """Build the undirected weighted file graph for the package at ``prefix``.
+
+    Files = FILE/MODULE nodes under ``prefix``. Edges = IMPORTS (and CALLS when
+    ``with_calls``) whose BOTH endpoints reconcile to distinct files under the
+    prefix; weights aggregate. Endpoints are reconciled by dot-boundary suffix
+    so a target written with a different root still links (root-agnostic, #242).
+    """
+    file_ids = sorted(n.id for n in nodes if n.type in _FILE_TYPES and _under(n.id, prefix))
+    file_set = set(file_ids)
+    suffix_index = _build_suffix_index(file_ids)
+    wanted = {EdgeType.IMPORTS} | ({EdgeType.CALLS} if with_calls else set())
+
+    adj: dict[str, dict[str, float]] = {}
+    for e in edges:
+        if e.type not in wanted:
+            continue
+        a = _resolve_to_file(e.source, file_set, suffix_index)
+        b = _resolve_to_file(e.target, file_set, suffix_index)
+        if a is None or b is None or a == b:
+            continue
+        adj.setdefault(a, {})[b] = adj.setdefault(a, {}).get(b, 0.0) + e.weight
+        adj.setdefault(b, {})[a] = adj.setdefault(b, {}).get(a, 0.0) + e.weight
+    return FileGraph(files=tuple(file_ids), adj=adj)
+
+
+_MIN_GAIN = 1e-12  # ignore non-positive / floating-noise merges
+
+
+def _modularity(
+    graph: FileGraph,
+    communities: list[list[str]],
+    deg: dict[str, float],
+    m2: float,
+) -> float:
+    """Newman modularity Q for a partition (m2 == 2m == sum of weighted degrees)."""
+    q = 0.0
+    for c in communities:
+        members = set(c)
+        l_c = sum(w for f in c for g, w in graph.adj.get(f, {}).items() if g in members)
+        d_c = sum(deg[f] for f in c)
+        q += l_c / m2 - (d_c / m2) ** 2
+    return q
+
+
+def _best_merge(
+    graph: FileGraph,
+    members: dict[str, set[str]],
+    deg: dict[str, float],
+    m2: float,
+) -> tuple[str, str] | None:
+    """Return the (c1, c2) pair with the highest positive delta-Q, or None.
+
+    Iterates sorted label pairs for lexicographic tie-breaking (deterministic).
+    Returns None when no merge would improve modularity by more than _MIN_GAIN.
+    """
+    best_gain: float = _MIN_GAIN
+    best_pair: tuple[str, str] | None = None
+    labels = sorted(members)
+    # Precompute each community's normalized degree once (O(V)) rather than
+    # re-summing it inside the O(K²) pair scan.
+    a_of = {c: sum(deg[f] for f in members[c]) / m2 for c in labels}
+    for i, c1 in enumerate(labels):
+        for c2 in labels[i + 1 :]:
+            # Sum edge weight between c1 and c2 over c1's actual neighbours
+            # (sparse, O(deg)) rather than a |c1|*|c2| Cartesian scan.
+            e_ij = (
+                sum(
+                    w
+                    for f in members[c1]
+                    for g, w in graph.adj.get(f, {}).items()
+                    if g in members[c2]
+                )
+                / m2
+            )
+            if e_ij <= 0.0:  # disconnected (weights are non-negative); merging can't raise Q
+                continue
+            dq = 2 * (e_ij - a_of[c1] * a_of[c2])
+            if dq > best_gain:
+                best_gain, best_pair = dq, (c1, c2)
+    return best_pair
+
+
+def greedy_modularity(graph: FileGraph) -> tuple[list[list[str]], float]:
+    """Greedy (Clauset-Newman-Moore) community detection; returns (communities, Q).
+
+    Each file starts in its own community; the connected pair with the maximum
+    positive delta-Q = 2*(e_ij - a_i*a_j) is merged until no merge improves Q.
+    Ties break on the lexicographically smallest label pair (deterministic).
+    Isolated files stay singletons and contribute 0 to Q. Communities are
+    returned sorted (members sorted, then the list sorted).
+    """
+    files = list(graph.files)
+    if not files:
+        return [], 0.0
+    deg = {f: sum(graph.adj.get(f, {}).values()) for f in files}
+    m2 = sum(deg.values())
+    if m2 <= 0.0:  # all isolated (degree sum is non-negative)
+        return [[f] for f in files], 0.0
+
+    members: dict[str, set[str]] = {f: {f} for f in files}
+    while len(members) > 1:
+        best_pair = _best_merge(graph, members, deg, m2)
+        if best_pair is None:
+            break
+        c1, c2 = best_pair
+        members[c1] |= members.pop(c2)
+
+    communities = sorted(sorted(s) for s in members.values())
+    return communities, _modularity(graph, communities, deg, m2)
+
+
+Direction = Literal["under_split", "over_split", "matched"]
+
+
+def _entropy(labels: Mapping[str, Hashable]) -> float:
+    """Shannon entropy (nats) of a partition's label distribution."""
+    n = len(labels)
+    counts = Counter(labels.values())
+    return -sum((c / n) * math.log(c / n) for c in counts.values())
+
+
+def _mutual_information(a: Mapping[str, Hashable], b: Mapping[str, Hashable]) -> float:
+    """Mutual information (nats) between two partitions over the same key set."""
+    n = len(a)
+    ca, cb = Counter(a.values()), Counter(b.values())
+    joint = Counter((a[k], b[k]) for k in a)
+    mi = 0.0
+    for (x, y), nxy in joint.items():
+        p_xy = nxy / n
+        mi += p_xy * math.log(p_xy / ((ca[x] / n) * (cb[y] / n)))
+    return mi
+
+
+def partition_divergence(p_comm: Mapping[str, Hashable], p_dir: Mapping[str, Hashable]) -> float:
+    """1 - NMI between two partitions of the same file set, in [0, 1].
+
+    NMI = I(X;Y) / mean(H(X), H(Y)); defined as 1.0 (so D = 0) when both
+    partitions are trivial (single cluster each). A non-trivial partition
+    against a trivial one has MI 0 -> NMI 0 -> D = 1 (the flat-package case).
+    """
+    h_a, h_b = _entropy(p_comm), _entropy(p_dir)
+    if h_a <= 0.0 and h_b <= 0.0:  # both trivial (entropy is non-negative; -0.0 counts)
+        return 0.0
+    nmi = _mutual_information(p_comm, p_dir) / ((h_a + h_b) / 2)
+    return 1.0 - nmi
+
+
+def layout_direction(p_comm: Mapping[str, Hashable], p_dir: Mapping[str, Hashable]) -> Direction:
+    """Direction of the layout/community mismatch by distinct-group count.
+
+    ``under_split`` when the directory layout is flatter than the communities
+    (fewer dir groups than communities); ``over_split`` when finer; ``matched``
+    when equal.
+    """
+    n_dir, n_comm = len(set(p_dir.values())), len(set(p_comm.values()))
+    if n_dir < n_comm:
+        return "under_split"
+    if n_dir > n_comm:
+        return "over_split"
+    return "matched"
+
+
+Verdict = Literal["split", "consolidate", "aligned", "leave", "borderline", "no_signal"]
+
+#: Default thresholds. ``split``/``leave`` are cross-validated for Q; ``divergence``
+#: is provisional (#242 spec). ``min_connected`` is the minimum fraction of files
+#: with an intra-package edge before a split/borderline verdict is trusted —
+#: modularity Q is unreliable on a near-disconnected graph, where a single tiny
+#: cluster inflates Q on a package of otherwise-independent files (calibrated on
+#: owner-api/utils 0.42 vs cgis.query 0.68 — see #242 follow-up).
+THRESHOLDS: dict[str, float] = {
+    "split": 0.35,
+    "leave": 0.25,
+    "divergence": 0.2,
+    "min_connected": 0.5,
+}
+
+
+def classify_verdict(
+    *, q: float, d: float, direction: Direction, thresholds: Mapping[str, float]
+) -> Verdict:
+    """Verdict from modularity Q, divergence D, and mismatch direction.
+
+    ``no_signal`` is decided upstream (no files / no edges); this maps a scored
+    package. Gated on BOTH Q (structure is real) and D (layout disagrees), with
+    direction disambiguating split (flatter layout) from consolidate (finer).
+    """
+    if q < thresholds["leave"]:
+        return "leave"
+    if d < thresholds["divergence"]:
+        return "aligned"
+    if q >= thresholds["split"]:
+        if direction == "under_split":
+            return "split"
+        if direction == "over_split":
+            return "consolidate"
+    return "borderline"

cgis/query/analysis/health.py

@@ -0,0 +1,128 @@
+"""Per-node health metrics: fan_in, fan_out, depth, in_cycle."""
+
+from collections import deque
+from dataclasses import dataclass
+
+from cgis.core.models import Edge, EdgeType, Node, NodeType
+from cgis.query.drift._scc import build_adjacency, tarjan_scc
+
+_BEHAVIORAL = frozenset({EdgeType.CALLS, EdgeType.IMPORTS, EdgeType.REFERENCES, EdgeType.USES})
+_STRUCTURAL = frozenset({EdgeType.CONTAINS, EdgeType.DECLARES})
+
+
+@dataclass(frozen=True)
+class NodeHealth:
+    """Health metrics for a single node."""
+
+    fan_in: int
+    fan_out: int
+    depth: int
+    in_cycle: bool
+
+
+class HealthScorer:
+    """Compute health metrics for every node in a graph snapshot."""
+
+    def __init__(self, nodes: list[Node], edges: list[Edge]) -> None:
+        """Accept the full node/edge lists from an ingestion run."""
+        self._nodes = nodes
+        self._edges = edges
+
+    def _compute_fan_counts(self) -> tuple[dict[str, int], dict[str, int]]:
+        """Count incoming and outgoing behavioral edges (CALLS, IMPORTS, REFERENCES, USES) per node.
+
+        Returns fan_in and fan_out dicts keyed by node ID.
+        """
+        fan_in: dict[str, int] = {n.id: 0 for n in self._nodes}
+        fan_out: dict[str, int] = {n.id: 0 for n in self._nodes}
+        for edge in self._edges:
+            if edge.type not in _BEHAVIORAL:
+                continue
+            if edge.source in fan_out:
+                fan_out[edge.source] += 1
+            if edge.target in fan_in:
+                fan_in[edge.target] += 1
+        return fan_in, fan_out
+
+    def _compute_depths(self) -> dict[str, int]:
+        """BFS from FILE nodes via CONTAINS/DECLARES to assign structural depth."""
+        children: dict[str, list[str]] = {}
+        for edge in self._edges:
+            if edge.type in _STRUCTURAL:
+                children.setdefault(edge.source, []).append(edge.target)
+
+        file_ids = {n.id for n in self._nodes if n.type == NodeType.FILE}
+        depths: dict[str, int] = {}
+        queue: deque[tuple[str, int]] = deque((fid, 0) for fid in file_ids)
+        while queue:
+            node_id, d = queue.popleft()
+            if node_id in depths:
+                continue
+            depths[node_id] = d
+            for child_id in children.get(node_id, []):
+                if child_id not in depths:
+                    queue.append((child_id, d + 1))
+        return depths
+
+    def _compute_cycles(self) -> set[str]:
+        """Return the set of FILE/MODULE node IDs that participate in IMPORTS cycles."""
+        target_types = {NodeType.FILE, NodeType.MODULE}
+        file_and_module_ids = {n.id for n in self._nodes if n.type in target_types}
+        adj = build_adjacency(self._edges, frozenset({EdgeType.IMPORTS}))
+        adj = {
+            k: [v for v in vs if v in file_and_module_ids]
+            for k, vs in adj.items()
+            if k in file_and_module_ids
+        }
+        cyclic: set[str] = set()
+        for scc in tarjan_scc(adj):
+            if len(scc) > 1:
+                cyclic.update(scc)
+        return cyclic
+
+    def _compute_file_ancestors(self) -> dict[str, str]:
+        """Map every descendant node ID to the FILE or MODULE root it belongs to (transitive)."""
+        children: dict[str, list[str]] = {}
+        for edge in self._edges:
+            if edge.type in _STRUCTURAL:
+                children.setdefault(edge.source, []).append(edge.target)
+
+        root_types = {NodeType.FILE, NodeType.MODULE}
+        file_ids = {n.id for n in self._nodes if n.type in root_types}
+        ancestor: dict[str, str] = {}
+        queue: deque[tuple[str, str]] = deque((fid, fid) for fid in file_ids)
+        while queue:
+            node_id, root_file = queue.popleft()
+            if node_id in ancestor:
+                continue
+            ancestor[node_id] = root_file
+            for child_id in children.get(node_id, []):
+                if child_id not in ancestor:
+                    queue.append((child_id, root_file))
+        return ancestor
+
+    def enrich(self) -> list[Node]:
+        """Return a new list of Nodes with health metrics merged into `metadata`."""
+        fan_in, fan_out = self._compute_fan_counts()
+        depths = self._compute_depths()
+        cyclic_file_ids = self._compute_cycles()
+        file_ancestor = self._compute_file_ancestors()
+
+        result: list[Node] = []
+        for node in self._nodes:
+            ancestor_file = file_ancestor.get(node.id, node.id)
+            in_cycle = ancestor_file in cyclic_file_ids
+            result.append(
+                node.model_copy(
+                    update={
+                        "metadata": {
+                            **node.metadata,
+                            "fan_in": fan_in.get(node.id, 0),
+                            "fan_out": fan_out.get(node.id, 0),
+                            "depth": depths.get(node.id, 0),
+                            "in_cycle": in_cycle,
+                        }
+                    }
+                )
+            )
+        return result