codegraph-brain 0.6.0__py3-none-any.whl

cgis/query/drift/drift_service.py

@@ -0,0 +1,217 @@
+"""Drift-analysis orchestration shared by the CLI and the MCP server."""
+
+import dataclasses
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from cgis.core.models import Node
+from cgis.query.drift.drift import DomainConfig, DriftReport, DriftScorer, FitQuality
+from cgis.query.drift.fingerprint import FingerprintExtractor
+from cgis.query.drift.ontology_init import discover_domains
+from cgis.query.drift.quotient import build_quotient
+from cgis.storage.sqlite_store import SQLiteStore
+
+
+@dataclass(frozen=True)
+class DriftAnalysis:
+    """Full drift run: per-domain reports plus the quotient (k=1) layer."""
+
+    reports: list[DriftReport]
+    quotient: list[tuple[DomainConfig, DriftReport]]
+    any_critical: bool
+    # Candidate domain prefixes present in the graph but bound by no project_domain
+    # — code drift silently ignores (#177 coverage roll-up).
+    coverage: list[str] = field(default_factory=list)
+
+
+_ALLOWED_PATTERN_SUFFIXES = {".yaml", ".yml"}
+
+# Fit-quality bands (#177): residual ≤ _GOOD_RESIDUAL is a clean archetype match;
+# residual > max_residual means no template fits (see _fit_quality).
+_GOOD_RESIDUAL = 0.25
+# Statuses whose fingerprint carries a real, fittable shape.
+_FITTABLE_STATUSES = frozenset({"clean", "warning", "critical", "gate_failed"})
+
+
+def _fit_quality(
+    scorer: DriftScorer, report: DriftReport, profile: str, max_residual: float
+) -> FitQuality | None:
+    """Rank the alphabet against one domain's shape and band the closest fit (#177).
+
+    Ranking uses the canonical distance (``fit_templates``); the reported
+    residuals and band use the gate-FREE ``shape_residual`` so a gate breach
+    (e.g. a cycle) never masquerades as "no template fits". Returns None when
+    the alphabet declares no templates (a profiles-only config).
+    """
+    fits = scorer.fit_templates(report.actual, profile)
+    if not fits:
+        return None
+    nearest_name = fits[0][0]
+    nearest_res = scorer.shape_residual(report.actual, profile, nearest_name)
+    if nearest_res is None:
+        # No trusted shape weight (v1 profile / empty census / fully unresolved) —
+        # "no signal to fit" is not a perfect match. Leave fit unset.
+        return None
+    runner_name = fits[1][0] if len(fits) > 1 else None
+    runner_res = scorer.shape_residual(report.actual, profile, runner_name) if runner_name else None
+    # Keep the good-band reachable even when --max-residual is set below it.
+    good_cut = min(_GOOD_RESIDUAL, max_residual)
+    band: Literal["good", "weak", "none"]
+    if nearest_res > max_residual:
+        band = "none"
+    elif nearest_res <= good_cut:
+        band = "good"
+    else:
+        band = "weak"
+    return FitQuality(
+        nearest_template=nearest_name,
+        nearest_residual=nearest_res,
+        runner_up_template=runner_name,
+        runner_up_residual=runner_res,
+        band=band,
+    )
+
+
+def _uncovered_prefixes(nodes: list[Node], domain_prefixes: list[str]) -> list[str]:
+    """Discovered domain candidates that overlap no declared domain prefix (#177).
+
+    A candidate is "covered" when it shares a subtree with a declared domain
+    (either is an ancestor-or-equal of the other). What remains is graph code
+    no ``project_domain`` binds — exactly what drift silently skips.
+    """
+    return sorted(
+        candidate
+        for candidate in discover_domains(nodes)
+        if not any(
+            candidate == d or candidate.startswith(f"{d}.") or d.startswith(f"{candidate}.")
+            for d in domain_prefixes
+        )
+    )
+
+
+def _empty_note(store: SQLiteStore, fqn_prefix: str) -> str:
+    """Return a 'matched 0 nodes' diagnostic with closest-prefix suggestions (spec §2.4).
+
+    Short-circuits on blank prefixes (no DB query). Tries the full prefix as a
+    dot-boundary suffix first, then its last segment; caps at 3 suggestions.
+    """
+    base = f"fqn_prefix '{fqn_prefix}' matched 0 nodes"
+    if not fqn_prefix.strip():
+        return base
+    matches = store.find_nodes_by_suffix(fqn_prefix, limit=3)
+    if not matches:
+        last_segment = fqn_prefix.rsplit(".", maxsplit=1)[-1]
+        if last_segment.strip():
+            matches = store.find_nodes_by_suffix(last_segment, limit=3)
+    if not matches:
+        return base
+    ids = sorted(n.id for n in matches)[:3]
+    return f"{base}; did you mean: {', '.join(ids)}?"
+
+
+def analyze_drift(
+    db_path: str,
+    patterns_path: str,
+    max_drift: float = 0.50,
+    profile: str | None = None,
+    max_residual: float = 0.45,
+) -> DriftAnalysis:
+    """Score every project domain (and the quotient level) against patterns.
+
+    When ``profile`` is set, only domains (and project_level bindings) whose
+    ``binding.profile == profile`` (or ``binding.profile is None``) are scored.
+    Profile-less domains match any filter — they carry language-agnostic hygiene
+    rules that should apply regardless of which language graph is being measured.
+    Omitting ``profile`` retains the score-everything default.
+
+    ``any_critical`` is True when any ENFORCED binding has status in
+    ``{"critical", "gate_failed", "empty"}`` (spec §2.3, #170B).  The
+    per-domain ``drift_tolerance`` determines whether a score yields
+    ``"critical"``; ``max_drift`` is the fallback default tolerance for domains
+    that do not declare their own (``drift_tolerance`` is no longer a global cap).
+    ``"no_signal"`` never trips the gate.  ``enforce: false`` stays observe-only.
+
+    For each ``"empty"`` report, the ``note`` field is decorated with closest-prefix
+    suggestions from the suffix index (spec §2.4).
+
+    Each profiled report with a real shape also carries ``fit`` (#177): the nearest
+    alphabet template + residual, the runner-up, and a ``good|weak|none`` band
+    (``none`` when the nearest residual exceeds ``max_residual`` — no archetype
+    captures the domain). ``DriftAnalysis.coverage`` lists graph prefixes bound by
+    no project_domain (code drift silently ignores).
+
+    Raises:
+        FileNotFoundError: If ``db_path`` does not point to an existing file.
+            Use ``cgis ingest`` to create the graph database first.
+        ValueError: If ``patterns_path`` does not end in ``.yaml`` or ``.yml``.
+        FileNotFoundError: If ``patterns_path`` does not point to an existing file.
+    """
+    if not Path(db_path).is_file():
+        msg = f"Graph database not found: {db_path}"
+        raise FileNotFoundError(msg)
+    resolved = Path(patterns_path).resolve()
+    if resolved.suffix.lower() not in _ALLOWED_PATTERN_SUFFIXES:
+        msg = f"patterns_path must be a .yaml or .yml file, got: {patterns_path!r}"
+        raise ValueError(msg)
+    if not resolved.is_file():
+        msg = f"Patterns file not found: {patterns_path}"
+        raise FileNotFoundError(msg)
+    scorer = DriftScorer(str(resolved))
+    domains = scorer.load_project_domains()
+    if profile is not None:
+        domains = [d for d in domains if d.profile is None or d.profile == profile]
+
+    quotient: list[tuple[DomainConfig, DriftReport]] = []
+    with SQLiteStore(db_path) as store:
+        extractor = FingerprintExtractor(store)
+        reports = [
+            scorer.score(extractor.extract(domain.fqn_prefix), domain, default_tolerance=max_drift)
+            for domain in domains
+        ]
+        reports = [
+            dataclasses.replace(r, note=_empty_note(store, r.fqn_prefix))
+            if r.status == "empty"
+            else r
+            for r in reports
+        ]
+        # Annotate fit-quality for domains with a real shape and a profile (#177).
+        reports = [
+            dataclasses.replace(r, fit=_fit_quality(scorer, r, d.profile, max_residual))
+            if d.profile is not None and r.status in _FITTABLE_STATUSES
+            else r
+            for d, r in zip(domains, reports, strict=True)
+        ]
+        all_nodes = store.get_all_nodes()  # one materialization, reused below (#177 #4)
+        coverage = _uncovered_prefixes(all_nodes, [d.fqn_prefix for d in domains])
+        level_bindings = scorer.load_project_level()
+        if profile is not None:
+            level_bindings = [
+                b for b in level_bindings if b.profile is None or b.profile == profile
+            ]
+        if level_bindings:
+            qnodes, qedges = build_quotient(all_nodes, store.get_all_edges(), domains)
+            q_extractor = FingerprintExtractor.from_graph(qnodes, qedges)
+            quotient = [
+                (b, scorer.score(q_extractor.extract(b.fqn_prefix), b, default_tolerance=max_drift))
+                for b in level_bindings
+            ]
+            quotient = [
+                (b, dataclasses.replace(r, note=_empty_note(store, r.fqn_prefix)))
+                if r.status == "empty"
+                else (b, r)
+                for b, r in quotient
+            ]
+
+    # Gate is now uniformly status-based and enforce-respecting (spec §2.3,
+    # #170B): 'critical' and 'gate_failed' on enforced bindings trip any_critical;
+    # 'empty' on enforced bindings also trips it (broken fqn_prefix must not
+    # silently pass CI). 'no_signal' never trips. enforce:false stays observe-only.
+    any_critical = any(
+        r.status in ("critical", "gate_failed", "empty")
+        for d, r in zip(domains, reports, strict=True)
+        if d.enforce
+    ) or any(r.status in ("critical", "gate_failed", "empty") for b, r in quotient if b.enforce)
+    return DriftAnalysis(
+        reports=reports, quotient=quotient, any_critical=any_critical, coverage=coverage
+    )

cgis/query/drift/fingerprint.py

@@ -0,0 +1,255 @@
+"""PatternFingerprint dataclass and FingerprintExtractor."""
+
+from collections import Counter
+from dataclasses import dataclass, field
+
+from cgis.core.models import Edge, EdgeType, Node, NodeType
+from cgis.query.analysis.health import HealthScorer
+from cgis.query.drift._scc import build_adjacency, tarjan_scc
+from cgis.query.drift.triads import ZERO_TRIADS, normalized_census, tangle_mass, triad_census
+from cgis.storage.sqlite_store import SQLiteStore
+
+RAW_CALL_PREFIX = "raw_call:"
+
+_HUB_FAN_IN_THRESHOLD = 2
+_STAR_FAN_OUT_THRESHOLD = 3
+_ROUTER_FAN_OUT_THRESHOLD = 2
+
+
+@dataclass(frozen=True)
+class PatternFingerprint:
+    """Structural fingerprint for a domain: seven v1 counters plus two v2 census vectors."""
+
+    domain: str
+
+    hub_count: int
+    star_count: int
+    chain_len: float
+    dag_depth: int
+    router_count: int
+
+    cycle_ratio: float
+    unresolved_ratio: float
+
+    # Fingerprint v2 (spec §3.2): normalized 13-triad census per layer,
+    # ordered by triads.TRIAD_ORDER. Zero vector = empty layer ("no data").
+    t_imports: tuple[float, ...] = field(default=ZERO_TRIADS)
+    t_calls: tuple[float, ...] = field(default=ZERO_TRIADS)
+
+    # How many graph nodes / intra-domain edges the selector matched.
+    # Defaults are 1 ("hand-built fingerprints are assumed measurable",
+    # spec Amendment 1); only extract() produces real zeros. 0 nodes means
+    # the fqn_prefix selected nothing; 0 edges with >0 nodes means there is
+    # no structure to score (isolated symbols / alias-only matches).
+    node_count: int = 1
+    edge_count: int = 1
+
+    @property
+    def tangle_ratio(self) -> float:
+        """Worst-layer normalized mutual-motif mass, in [0, 1] (spec #186).
+
+        max over the IMPORTS and CALLS census of tangle_mass — a hard hygiene
+        signal: a breach in either layer is a breach. 0 for empty or
+        antisymmetric (no-mutual-dyad) layers.
+
+        The CALLS layer is faded by the confidence discount
+        ``clip(1 - unresolved_ratio)`` before the max (#244), mirroring the
+        drift-distance path (``_clip_discount`` / ``_score_v2``): ``t_calls`` is a
+        census over RESOLVED intra-domain calls only, so a sparse/mostly-unresolved
+        call graph would otherwise over-report calls-tangle and trip the gate on
+        thin evidence. The IMPORTS layer (always resolved) is never discounted.
+        """
+        calls_discount = max(0.0, min(1.0 - self.unresolved_ratio, 1.0))
+        return max(tangle_mass(self.t_imports), calls_discount * tangle_mass(self.t_calls))
+
+
+def _in_domain(fqn: str, prefix: str) -> bool:
+    """Return True iff fqn is the prefix itself or a child of it (segment-boundary aware)."""
+    return fqn == prefix or fqn.startswith(prefix + ".")
+
+
+def _root_depths(domain_ids: set[str], edges: list[Edge], edge_type: EdgeType) -> list[int]:
+    """Longest-path depth from each root node along edges of edge_type within the domain.
+
+    A root is a domain node with outgoing edges of the given type but no incoming ones.
+    Uses memoized DFS (cycle-safe); roots are sorted so results are deterministic.
+    """
+    adj: dict[str, list[str]] = {}
+    has_incoming: set[str] = set()
+    for e in edges:
+        if e.type == edge_type:
+            adj.setdefault(e.source, []).append(e.target)
+            has_incoming.add(e.target)
+
+    roots = sorted(n for n in domain_ids if n not in has_incoming and n in adj)
+    if not roots:
+        return []
+
+    memo: dict[str, int] = {}
+    visiting: set[str] = set()
+
+    def dfs(u: str) -> int:
+        if u in memo:
+            return memo[u]
+        if u in visiting:
+            return 0
+        visiting.add(u)
+        val = max((1 + dfs(v) for v in adj.get(u, [])), default=0)
+        visiting.remove(u)
+        memo[u] = val
+        return val
+
+    return [dfs(root) for root in roots]
+
+
+def _avg_chain_length(domain_ids: set[str], internal_calls: list[Edge]) -> float:
+    """Average longest-path depth from each source node along CALLS edges within the domain."""
+    depths = _root_depths(domain_ids, internal_calls, EdgeType.CALLS)
+    return sum(depths) / len(depths) if depths else 0.0
+
+
+def _max_dag_depth(domain_ids: set[str], internal_edges: list[Edge]) -> int:
+    """Max longest-path depth along IMPORTS edges within the domain (from import-root nodes)."""
+    depths = _root_depths(domain_ids, internal_edges, EdgeType.IMPORTS)
+    return max(depths) if depths else 0
+
+
+def _count_routers(domain_node_ids: set[str], all_edges: list[Edge]) -> int:
+    """Count domain nodes with fan_out > 2 whose CALLS targets don't import them."""
+    imported_by: dict[str, set[str]] = {}
+    calls_by_source: dict[str, list[str]] = {}
+    for e in all_edges:
+        if e.type == EdgeType.IMPORTS:
+            imported_by.setdefault(e.target, set()).add(e.source)
+        elif e.type == EdgeType.CALLS:
+            calls_by_source.setdefault(e.source, []).append(e.target)
+
+    router_count = 0
+    for node_id in domain_node_ids:
+        calls_targets = calls_by_source.get(node_id, [])
+        if len(calls_targets) <= _ROUTER_FAN_OUT_THRESHOLD:
+            continue
+        node_importers = imported_by.get(node_id, set())
+        if not (set(calls_targets) & node_importers):
+            router_count += 1
+
+    return router_count
+
+
+class FingerprintExtractor:
+    """Compute a PatternFingerprint for a given FQN domain prefix from a SQLiteStore."""
+
+    def __init__(self, store: SQLiteStore | None) -> None:
+        """Accept an open SQLiteStore, or None when built via from_graph()."""
+        self._store = store
+        self._cache: tuple[list[Node], list[Edge]] | None = None
+
+    @classmethod
+    def from_graph(cls, nodes: list[Node], edges: list[Edge]) -> "FingerprintExtractor":
+        """Build an extractor over an in-memory graph — no SQLiteStore involved.
+
+        The inputs are copied defensively, so later mutation of the caller's
+        lists cannot change what extract() measures (matches the store path,
+        which returns fresh lists on every fetch).
+        """
+        inst = cls(None)
+        inst._cache = (HealthScorer(nodes, edges).enrich(), list(edges))
+        return inst
+
+    def _loaded(self) -> tuple[list[Node], list[Edge]]:
+        """Return (enriched_nodes, all_edges), fetching from the store once and caching."""
+        if self._cache is None:
+            if self._store is None:
+                msg = "FingerprintExtractor needs a store or a from_graph() preload."
+                raise RuntimeError(msg)
+            all_nodes = self._store.get_all_nodes()
+            all_edges = self._store.get_all_edges()
+            self._cache = (HealthScorer(all_nodes, all_edges).enrich(), all_edges)
+        return self._cache
+
+    def extract(self, fqn_prefix: str) -> PatternFingerprint:
+        """Return the structural fingerprint for all nodes under fqn_prefix."""
+        enriched_all, all_edges = self._loaded()
+
+        domain_nodes = [n for n in enriched_all if _in_domain(n.id, fqn_prefix)]
+        if not domain_nodes:
+            return PatternFingerprint(
+                domain=fqn_prefix,
+                hub_count=0,
+                star_count=0,
+                chain_len=0.0,
+                dag_depth=0,
+                router_count=0,
+                cycle_ratio=0.0,
+                unresolved_ratio=0.0,
+                node_count=0,
+                edge_count=0,
+            )
+
+        domain_ids = {n.id for n in domain_nodes}
+
+        internal_edges = [e for e in all_edges if e.source in domain_ids and e.target in domain_ids]
+        domain_outgoing = [e for e in all_edges if e.source in domain_ids]
+
+        # Fan-in/fan-out over intra-domain CALLS only — external targets
+        # (stdlib, other domains) would otherwise inflate star/hub counts.
+        fan_in = Counter(e.target for e in internal_edges if e.type == EdgeType.CALLS)
+        fan_out = Counter(e.source for e in internal_edges if e.type == EdgeType.CALLS)
+
+        hub_count = sum(
+            1 for n in domain_nodes if fan_in[n.id] > _HUB_FAN_IN_THRESHOLD and fan_out[n.id] == 0
+        )
+        star_count = sum(
+            1 for n in domain_nodes if fan_out[n.id] > _STAR_FAN_OUT_THRESHOLD and fan_in[n.id] <= 1
+        )
+        chain_len = _avg_chain_length(domain_ids, internal_edges)
+        dag_depth = _max_dag_depth(domain_ids, internal_edges)
+        router_count = _count_routers(domain_ids, all_edges)
+
+        cycle_ratio = self._intra_domain_cycle_ratio(domain_nodes, all_edges)
+
+        calls_edges = [e for e in domain_outgoing if e.type == EdgeType.CALLS]
+        raw_calls = [e for e in calls_edges if e.target.startswith(RAW_CALL_PREFIX)]
+        unresolved_ratio = len(raw_calls) / len(calls_edges) if calls_edges else 0.0
+
+        t_imports = normalized_census(triad_census(domain_ids, internal_edges, EdgeType.IMPORTS))
+        t_calls = normalized_census(triad_census(domain_ids, internal_edges, EdgeType.CALLS))
+
+        return PatternFingerprint(
+            domain=fqn_prefix,
+            hub_count=hub_count,
+            star_count=star_count,
+            chain_len=chain_len,
+            dag_depth=dag_depth,
+            router_count=router_count,
+            cycle_ratio=cycle_ratio,
+            unresolved_ratio=unresolved_ratio,
+            t_imports=t_imports,
+            t_calls=t_calls,
+            node_count=len(domain_nodes),
+            edge_count=len(internal_edges),
+        )
+
+    def _intra_domain_cycle_ratio(self, domain_nodes: list[Node], all_edges: list[Edge]) -> float:
+        """Blast radius of the domain's OWN import cycles (spec §2.1, #176).
+
+        Tarjan SCC over IMPORTS edges whose endpoints are both FILE/MODULE
+        nodes of this domain; the ratio counts domain nodes living in files
+        that participate in an intra-domain cycle. Single-file domains are
+        0.0 by construction; cross-domain cycles are the quotient layer's
+        concern and never count here.
+        """
+        file_types = {NodeType.FILE, NodeType.MODULE}
+        domain_files = {n.id for n in domain_nodes if n.type in file_types}
+        if len(domain_files) < 2:
+            return 0.0
+        adj = build_adjacency(all_edges, frozenset({EdgeType.IMPORTS}))
+        adj = {
+            k: [v for v in vs if v in domain_files] for k, vs in adj.items() if k in domain_files
+        }
+        cyclic_files = {n for scc in tarjan_scc(adj) if len(scc) > 1 for n in scc}
+        if not cyclic_files:
+            return 0.0
+        cyclic_paths = {n.file_path for n in domain_nodes if n.id in cyclic_files}
+        cycle_count = sum(1 for n in domain_nodes if n.file_path in cyclic_paths)
+        return cycle_count / len(domain_nodes)