codegraph-brain 0.6.0__py3-none-any.whl

cgis/query/drift/triads.py

@@ -0,0 +1,234 @@
+"""13-class connected triad census and total-variation distance (spec ss3.1-3.3).
+
+Classification uses the Batagelj-Mrvar tricode: the 6 possible directed edges
+among an ordered triple form a 6-bit code; a 64-entry table maps each code to
+one of the 16 MAN triad types. We count only the 13 *connected* types -- the
+unit tests pin one hand-built graph per class, which is the correctness anchor
+for the table.
+"""
+
+from collections.abc import Iterator
+
+from cgis.core.models import Edge, EdgeType
+
+#: The 13 connected triad classes, canonical vector order for fingerprints.
+TRIAD_ORDER: tuple[str, ...] = (
+    "021D",
+    "021U",
+    "021C",
+    "111D",
+    "111U",
+    "030T",
+    "030C",
+    "201",
+    "120D",
+    "120U",
+    "120C",
+    "210",
+    "300",
+)
+
+#: All 16 MAN types in Batagelj-Mrvar order; the first three are disconnected.
+_TRIAD_NAMES: tuple[str, ...] = (
+    "003",
+    "012",
+    "102",
+    "021D",
+    "021U",
+    "021C",
+    "111D",
+    "111U",
+    "030T",
+    "030C",
+    "201",
+    "120D",
+    "120U",
+    "120C",
+    "210",
+    "300",
+)
+
+#: Batagelj-Mrvar TRICODES: maps each 6-bit edge code to a 1-based MAN index.
+_TRICODES: tuple[int, ...] = (
+    1,
+    2,
+    2,
+    3,
+    2,
+    4,
+    6,
+    8,
+    2,
+    6,
+    5,
+    7,
+    3,
+    8,
+    7,
+    11,
+    2,
+    6,
+    4,
+    8,
+    5,
+    9,
+    9,
+    13,
+    6,
+    10,
+    9,
+    14,
+    7,
+    14,
+    12,
+    15,
+    2,
+    5,
+    6,
+    7,
+    6,
+    9,
+    10,
+    14,
+    4,
+    9,
+    9,
+    12,
+    8,
+    13,
+    14,
+    15,
+    3,
+    7,
+    8,
+    11,
+    7,
+    12,
+    14,
+    15,
+    8,
+    14,
+    13,
+    15,
+    11,
+    15,
+    15,
+    16,
+)
+
+#: Zero vector, the default for fingerprints of empty domains.
+ZERO_TRIADS: tuple[float, ...] = (0.0,) * len(TRIAD_ORDER)
+
+
+def _classify(succ: dict[str, set[str]], v: str, u: str, w: str) -> str:
+    """Return the MAN class name for the ordered triple (v, u, w)."""
+    code = (
+        (1 if u in succ[v] else 0)
+        + (2 if v in succ[u] else 0)
+        + (4 if w in succ[v] else 0)
+        + (8 if v in succ[w] else 0)
+        + (16 if w in succ[u] else 0)
+        + (32 if u in succ[w] else 0)
+    )
+    return _TRIAD_NAMES[_TRICODES[code] - 1]
+
+
+def _adjacency(
+    node_ids: set[str], edges: list[Edge], edge_type: EdgeType
+) -> tuple[dict[str, set[str]], dict[str, set[str]]]:
+    """Build (successor, undirected-neighbor) maps over intra-set edges of edge_type.
+
+    Self-loops and edges touching nodes outside node_ids are ignored.
+    """
+    succ: dict[str, set[str]] = {n: set() for n in node_ids}
+    nbrs: dict[str, set[str]] = {n: set() for n in node_ids}
+    for e in edges:
+        if e.type != edge_type or e.source == e.target:
+            continue
+        if e.source in succ and e.target in succ:
+            succ[e.source].add(e.target)
+            nbrs[e.source].add(e.target)
+            nbrs[e.target].add(e.source)
+    return succ, nbrs
+
+
+def _connected_triples(
+    node_ids: set[str], nbrs: dict[str, set[str]]
+) -> Iterator[tuple[str, str, str]]:
+    """Yield each connected unordered triple exactly once, as a sorted 3-tuple."""
+    seen: set[tuple[str, str, str]] = set()
+    for v in node_ids:
+        for u in nbrs[v]:
+            for w in nbrs[v] | nbrs[u]:
+                if w in (v, u):
+                    continue
+                a, b, c = sorted((v, u, w))
+                if (a, b, c) not in seen:
+                    seen.add((a, b, c))
+                    yield a, b, c
+
+
+def triad_census(node_ids: set[str], edges: list[Edge], edge_type: EdgeType) -> dict[str, int]:
+    """Count connected triads over intra-set edges of edge_type.
+
+    Each unordered triple is counted exactly once. O(Σ deg(v)²) — fine at
+    our scale (spec §3.6.3).
+    """
+    succ, nbrs = _adjacency(node_ids, edges, edge_type)
+    counts: dict[str, int] = dict.fromkeys(TRIAD_ORDER, 0)
+    # Every yielded triple has v-u adjacent and w adjacent to one of them,
+    # so it is connected and the class is always one of the 13.
+    for a, b, c in _connected_triples(node_ids, nbrs):
+        counts[_classify(succ, a, b, c)] += 1
+    return counts
+
+
+def normalized_census(counts: dict[str, int]) -> tuple[float, ...]:
+    """Return the census as a 13-tuple in TRIAD_ORDER, normalized to sum 1.
+
+    An empty census normalizes to the all-zero vector ("no data", not NaN).
+    """
+    total = sum(counts.values())
+    if total == 0:
+        return ZERO_TRIADS
+    return tuple(counts[name] / total for name in TRIAD_ORDER)
+
+
+def tv_distance(
+    t: tuple[float, ...],
+    ideal: tuple[float, ...],
+    weights: tuple[float, ...],
+) -> tuple[float, list[tuple[str, float]]]:
+    """Weighted total variation 0.5*sum(wi*|ti-ideali|) with per-triad decomposition.
+
+    Returns (tv, contributions) where contributions pairs each TRIAD_ORDER
+    name with its 0.5*wi*|ti-ideali| term (spec ss3.3: violations fall out of
+    the metric instead of being approximated from it).
+    """
+    contribs = [
+        (name, 0.5 * w * abs(a - b))
+        for name, a, b, w in zip(TRIAD_ORDER, t, ideal, weights, strict=True)
+    ]
+    return sum((c for _, c in contribs), 0.0), contribs
+
+
+#: MAN mutual-dyad count (M, the first digit of the MAN code) for each class,
+#: aligned index-for-index with TRIAD_ORDER. Transpose-fixed mutual mass is the
+#: anti-pattern signal (spec: health = acyclicity + antisymmetry).
+_TANGLE_WEIGHTS: tuple[int, ...] = (0, 0, 0, 1, 1, 0, 0, 2, 1, 1, 1, 2, 3)
+
+#: Max single-class weight (pure 300), used to normalize tangle into [0, 1].
+_TANGLE_MAX_M = 3.0
+
+
+def tangle_mass(census: tuple[float, ...]) -> float:
+    """Normalized transpose-fixed (mutual) motif mass of a census, in [0, 1].
+
+    Weights each normalized triad fraction by its MAN mutual-dyad count M and
+    divides by the maximal M (3, pure 300). An antisymmetric graph — no mutual
+    dyads, i.e. only 021*/030T/030C (cycles included; acyclicity is cycle_ratio's
+    job, orthogonal to tangle) — scores 0; a pure mutual mesh (300) scores 1.
+    The empty census scores 0.
+    """
+    weighted = sum(w * t for w, t in zip(_TANGLE_WEIGHTS, census, strict=True))
+    return weighted / _TANGLE_MAX_M

cgis/query/engine.py

@@ -0,0 +1,170 @@
+"""Implement query engine for code graph."""
+
+from collections.abc import Callable
+
+from cgis.core.models import Edge, EdgeType, Node, NodeNamespace
+from cgis.storage.sqlite_store import SQLiteStore
+
+STRUCTURAL_EDGE_TYPES: frozenset[EdgeType] = frozenset({EdgeType.CONTAINS, EdgeType.DECLARES})
+BEHAVIORAL_EDGE_TYPES: frozenset[EdgeType] = frozenset(
+    t for t in EdgeType if t not in STRUCTURAL_EDGE_TYPES
+)
+
+
+def _reachable_from(
+    start_id: str,
+    edges: list[Edge],
+    get_neighbor_id: Callable[[Edge], str],
+) -> set[str]:
+    """DFS reachability from start_id through filtered edges."""
+    adj: dict[str, list[str]] = {}
+    for e in edges:
+        nbr = get_neighbor_id(e)
+        frm = e.source if nbr == e.target else e.target
+        adj.setdefault(frm, []).append(nbr)
+    reachable: set[str] = {start_id}
+    queue: list[str] = [start_id]
+    while queue:
+        curr = queue.pop()
+        for nbr in adj.get(curr, []):
+            if nbr not in reachable:
+                reachable.add(nbr)
+                queue.append(nbr)
+    return reachable
+
+
+def _prune_external(
+    start_id: str,
+    nodes: list[Node],
+    visited_edges: dict[str, Edge],
+    get_neighbor_id: Callable[[Edge], str],
+) -> tuple[list[Node], list[Edge]]:
+    """Remove non-INTERNAL nodes and prune internal nodes disconnected after that removal."""
+    nodes = [n for n in nodes if n.namespace == NodeNamespace.INTERNAL or n.id == start_id]
+    internal_ids = {n.id for n in nodes} | {start_id}
+    filtered_edges = [
+        e for e in visited_edges.values() if e.source in internal_ids and e.target in internal_ids
+    ]
+    reachable = _reachable_from(start_id, filtered_edges, get_neighbor_id)
+    nodes = [n for n in nodes if n.id in reachable]
+    return nodes, [e for e in filtered_edges if e.source in reachable and e.target in reachable]
+
+
+def _edge_accepted(
+    edge: Edge,
+    allowed_edge_types: frozenset[EdgeType] | None,
+    min_confidence: float | None,
+) -> bool:
+    """True when an edge passes the traversal filters: type allow-list and confidence floor."""
+    if allowed_edge_types is not None and edge.type not in allowed_edge_types:
+        return False
+    return not (min_confidence is not None and edge.confidence < min_confidence)
+
+
+class QueryEngine:
+    """
+    Performs graph traversals over the SQLite Code Graph.
+    Enables Impact Analysis (upstream) and Flow Tracing (downstream).
+    """
+
+    def __init__(self, store: SQLiteStore) -> None:
+        """Bind the query engine to an open SQLiteStore instance."""
+        self.store = store
+
+    def get_impact_graph(
+        self,
+        target_node_id: str,
+        max_depth: int = 5,
+        allowed_edge_types: frozenset[EdgeType] | None = None,
+        show_external: bool = True,
+        min_confidence: float | None = None,
+    ) -> tuple[list[Node], list[Edge]]:
+        """
+        Transitive upstream traversal (who calls me?).
+        If target_node_id changes, what else is impacted?
+        """
+        return self._bfs_traverse(
+            target_node_id,
+            self.store.get_incoming_edges_batch,
+            lambda e: e.source,
+            max_depth,
+            allowed_edge_types=allowed_edge_types,
+            show_external=show_external,
+            min_confidence=min_confidence,
+        )
+
+    def get_flow_graph(
+        self,
+        start_node_id: str,
+        max_depth: int = 5,
+        allowed_edge_types: frozenset[EdgeType] | None = None,
+        show_external: bool = True,
+        min_confidence: float | None = None,
+    ) -> tuple[list[Node], list[Edge]]:
+        """
+        Transitive downstream traversal (who do I call?).
+        Traces execution path starting from start_node_id.
+        """
+        return self._bfs_traverse(
+            start_node_id,
+            self.store.get_outgoing_edges_batch,
+            lambda e: e.target,
+            max_depth,
+            allowed_edge_types=allowed_edge_types,
+            show_external=show_external,
+            min_confidence=min_confidence,
+        )
+
+    def get_structural_graph(
+        self, target_id: str, max_depth: int = 5
+    ) -> tuple[list[Node], list[Edge]]:
+        """
+        Structural hierarchy rooted at target_id (FILE → CLASS → METHOD).
+        Traverses only CONTAINS and DECLARES edges — no call-graph noise.
+        Delegates to a single recursive CTE query in the store.
+        """
+        return self.store.get_structural_subgraph(target_id, max_depth)
+
+    def _bfs_traverse(
+        self,
+        start_id: str,
+        get_edges_batch: Callable[[list[str]], list[Edge]],
+        get_neighbor_id: Callable[[Edge], str],
+        max_depth: int,
+        allowed_edge_types: frozenset[EdgeType] | None = None,
+        show_external: bool = True,
+        min_confidence: float | None = None,
+    ) -> tuple[list[Node], list[Edge]]:
+        """
+        Level-by-level BFS. Fetches edges for the entire frontier in one
+        batch query per level — O(depth) DB roundtrips instead of O(nodes).
+
+        ``min_confidence`` prunes edges below the given confidence (e.g.
+        unresolved ``raw_call:`` edges at 0.1) so the traversal never crosses
+        them — low-confidence neighbours stay out of the result.
+        """
+        discovered_ids: set[str] = {start_id}
+        visited_edges: dict[str, Edge] = {}
+        current_frontier = [start_id]
+        depth = 0
+
+        while current_frontier and depth < max_depth:
+            edges = get_edges_batch(current_frontier)
+            next_frontier: list[str] = []
+            for edge in edges:
+                if not _edge_accepted(edge, allowed_edge_types, min_confidence):
+                    continue
+                visited_edges[edge.id] = edge
+                neighbor_id = get_neighbor_id(edge)
+                if neighbor_id not in discovered_ids:
+                    discovered_ids.add(neighbor_id)
+                    next_frontier.append(neighbor_id)
+            current_frontier = next_frontier
+            depth += 1
+
+        nodes = self.store.get_nodes(list(discovered_ids))
+
+        if not show_external:
+            return _prune_external(start_id, nodes, visited_edges, get_neighbor_id)
+
+        return nodes, list(visited_edges.values())

cgis/query/fqn.py

@@ -0,0 +1,65 @@
+"""Suffix-based FQN resolution shared by CLI commands and MCP tools.
+
+Fixes the prefix-mismatch UX wart (#145): a graph ingested from ``src``
+holds ``cgis.*`` FQNs while users (and agents) often pass ``src.cgis.*``
+or bare names. A unique dot-boundary suffix match resolves silently;
+ambiguity surfaces the candidates instead of a bare "not found".
+"""
+
+from dataclasses import dataclass, field
+
+from cgis.storage.sqlite_store import SQLiteStore
+
+_CANDIDATE_LIMIT = 10
+_PROBE_LIMIT = _CANDIDATE_LIMIT + 1  # one extra to detect truncation
+
+
+@dataclass(frozen=True)
+class FqnResolution:
+    """Outcome of resolving a possibly-partial FQN against the graph.
+
+    ``resolved`` is set when there is exactly one match (exact or suffix).
+    ``candidates`` lists up to ``_CANDIDATE_LIMIT`` alternatives when the
+    suffix is ambiguous. ``via_suffix`` is True when the caller passed a
+    partial name that was matched by dot-boundary suffix search.
+    ``truncated`` is True when the candidate list was capped because more
+    than ``_CANDIDATE_LIMIT`` nodes matched; in that case the caller should
+    prompt the user to refine the name.
+    """
+
+    resolved: str | None
+    candidates: list[str] = field(default_factory=list)
+    via_suffix: bool = False
+    truncated: bool = False
+
+
+def resolve_fqn(store: SQLiteStore, fqn: str) -> FqnResolution:
+    """Resolve ``fqn`` exactly, or by unique dot-boundary suffix match.
+
+    Exact hit resolves as-is (``via_suffix=False``); a single suffix hit
+    resolves to the full FQN with ``via_suffix=True``; several hits return
+    ``candidates`` (capped at ``_CANDIDATE_LIMIT``); no hit returns an empty
+    resolution.  When the result set is larger than ``_CANDIDATE_LIMIT`` the
+    ``truncated`` flag is set to signal that the listing is incomplete.
+
+    Empty or whitespace-only input returns an unresolved ``FqnResolution``
+    immediately without touching the store.
+
+    Exact-match policy lives here, not in ``SQLiteStore.find_nodes_by_suffix``,
+    so the storage layer stays a pure suffix search with no intra-domain call
+    chain (enforced by the pure_utility self-drift guardrail, #145).
+    """
+    fqn = fqn.strip()
+    if not fqn:
+        return FqnResolution(resolved=None)
+    exact = store.get_node(fqn)
+    if exact:
+        return FqnResolution(resolved=fqn)
+    matches = store.find_nodes_by_suffix(fqn, limit=_PROBE_LIMIT)
+    if not matches:
+        return FqnResolution(resolved=None)
+    if len(matches) == 1:
+        return FqnResolution(resolved=matches[0].id, via_suffix=True)
+    truncated = len(matches) > _CANDIDATE_LIMIT
+    candidates = [n.id for n in matches[:_CANDIDATE_LIMIT]]
+    return FqnResolution(resolved=None, candidates=candidates, truncated=truncated)

cgis/query/render/graph_json.py

@@ -0,0 +1,42 @@
+"""Serialize a (nodes, edges) subgraph into a machine-readable JSON payload.
+
+Mermaid output (``mermaid.py``) is for human eyes; this is the joinable,
+agent/CI-facing view of the same subgraph. FQNs are emitted verbatim — no
+display hashes — so results from separate queries can be combined with plain
+set operations (e.g. authz-coverage or dead-code sweeps). See issue #171.
+"""
+
+from typing import Any
+
+from cgis.core.models import Edge, Node
+
+
+def graph_to_json(root: str, nodes: list[Node], edges: list[Edge]) -> dict[str, Any]:
+    """Build the JSON shape ``{root, nodes, edges}`` for a traversal result.
+
+    ``root`` is the resolved FQN the traversal started from. Node entries carry
+    ``fqn``/``type``/``file``/``line``; edge entries carry ``src``/``dst``/
+    ``type``/``confidence``. Unresolved targets keep their ``raw_call:`` prefix
+    so consumers can tell a resolved edge from a dangling one.
+    """
+    return {
+        "root": root,
+        "nodes": [
+            {
+                "fqn": node.id,
+                "type": node.type.value,
+                "file": node.file_path,
+                "line": node.start_line,
+            }
+            for node in nodes
+        ],
+        "edges": [
+            {
+                "src": edge.source,
+                "dst": edge.target,
+                "type": edge.type.value,
+                "confidence": edge.confidence,
+            }
+            for edge in edges
+        ],
+    }