compos-cli 0.0.0__py3-none-any.whl

compos/core/graph.py

@@ -0,0 +1,648 @@
+"""Relationship graph traversal (blast radius, cycle detection)."""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import StrEnum
+
+from compos.schema import (
+    Component,
+    ComposMap,
+    Constraint,
+    ConstraintStatus,
+    Decision,
+    DecisionStatus,
+    ObjectStatus,
+    Relationship,
+    RelationshipPattern,
+    RelationshipType,
+    Risk,
+    RiskStatus,
+)
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class Direction(StrEnum):
+    """Direction for graph traversal."""
+
+    OUTGOING = "outgoing"
+    INCOMING = "incoming"
+    BOTH = "both"
+
+
+class ChangeType(StrEnum):
+    """Type of proposed change — determines blast radius direction."""
+
+    MODIFY = "modify"
+    REMOVE = "remove"
+    REPLACE = "replace"
+
+
+# ---------------------------------------------------------------------------
+# Result dataclasses (frozen, slots)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ComponentContext:
+    """Context around one or more focal components."""
+
+    focal_components: tuple[Component, ...]
+    neighbor_components: tuple[Component, ...]
+    connecting_relationships: tuple[Relationship, ...]
+    applicable_constraints: tuple[Constraint, ...]
+    applicable_risks: tuple[Risk, ...]
+    applicable_decisions: tuple[Decision, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class AffectedComponent:
+    """A component affected by a change, with distance and path info."""
+
+    component: Component
+    hop_distance: int
+    path: tuple[str, ...]
+    relationship_types: frozenset[RelationshipType]
+
+
+@dataclass(frozen=True, slots=True)
+class BlastRadiusResult:
+    """Result of a blast radius analysis."""
+
+    source_component: Component
+    change_type: ChangeType
+    affected: tuple[AffectedComponent, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class CycleInfo:
+    """A detected dependency cycle."""
+
+    component_ids: tuple[str, ...]
+    relationship_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class SPOFInfo:
+    """A single point of failure candidate."""
+
+    component: Component
+    dependent_count: int
+    synchronous_dependents: tuple[Component, ...]
+    has_error_behavior: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ConstraintConflict:
+    """A constraint that may be violated by a proposed change."""
+
+    constraint: Constraint
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class ChangeEvaluation:
+    """Result of evaluating a proposed change."""
+
+    cycles: tuple[CycleInfo, ...]
+    spofs: tuple[SPOFInfo, ...]
+    constraint_conflicts: tuple[ConstraintConflict, ...]
+
+
+# ---------------------------------------------------------------------------
+# RelationshipGraph — pre-indexed adjacency structure
+# ---------------------------------------------------------------------------
+
+
+class RelationshipGraph:
+    """Pre-indexed relationship graph built from a ComposMap.
+
+    Builds adjacency indexes in __init__ by iterating relationships once.
+    All queries are then O(1) lookups or BFS/DFS over the pre-built indexes.
+    """
+
+    def __init__(
+        self, compos_map: ComposMap, *, include_removed: bool = False
+    ) -> None:
+        self._map = compos_map
+
+        # Index components by id, filtering removed unless opted in
+        self._components: dict[str, Component] = {}
+        removed_component_ids: set[str] = set()
+        for comp in compos_map.components:
+            if not include_removed and comp.status == ObjectStatus.REMOVED:
+                removed_component_ids.add(comp.id)
+                continue
+            self._components[comp.id] = comp
+
+        # Index relationships, building adjacency lists in a single pass.
+        # Skip removed relationships and relationships referencing removed components.
+        self._relationships: dict[str, Relationship] = {}
+        self._outgoing: dict[str, list[Relationship]] = defaultdict(list)
+        self._incoming: dict[str, list[Relationship]] = defaultdict(list)
+        self._out_neighbors: dict[str, set[str]] = defaultdict(set)
+        self._in_neighbors: dict[str, set[str]] = defaultdict(set)
+
+        for rel in compos_map.relationships:
+            if not include_removed and rel.status == ObjectStatus.REMOVED:
+                continue
+            if not include_removed and (
+                rel.source in removed_component_ids
+                or rel.target in removed_component_ids
+            ):
+                continue
+            self._relationships[rel.id] = rel
+            self._outgoing[rel.source].append(rel)
+            self._incoming[rel.target].append(rel)
+            self._out_neighbors[rel.source].add(rel.target)
+            self._in_neighbors[rel.target].add(rel.source)
+
+    @property
+    def component_ids(self) -> frozenset[str]:
+        return frozenset(self._components)
+
+    def neighbors(
+        self, component_id: str, *, direction: Direction = Direction.BOTH
+    ) -> frozenset[str]:
+        """Return IDs of neighboring components. Safe for unknown IDs (empty result)."""
+        out = self._out_neighbors.get(component_id, set())
+        inc = self._in_neighbors.get(component_id, set())
+        if direction == Direction.OUTGOING:
+            return frozenset(out)
+        if direction == Direction.INCOMING:
+            return frozenset(inc)
+        return frozenset(out | inc)
+
+    def relationships_of(
+        self, component_id: str, *, direction: Direction = Direction.BOTH
+    ) -> tuple[Relationship, ...]:
+        """Return Relationship objects connected to a component."""
+        out = self._outgoing.get(component_id, [])
+        inc = self._incoming.get(component_id, [])
+        if direction == Direction.OUTGOING:
+            return tuple(out)
+        if direction == Direction.INCOMING:
+            return tuple(inc)
+        # Both: combine, dedup by id (a self-loop would appear in both lists)
+        seen: set[str] = set()
+        result: list[Relationship] = []
+        for rel in (*out, *inc):
+            if rel.id not in seen:
+                seen.add(rel.id)
+                result.append(rel)
+        return tuple(result)
+
+    def relationships_between(
+        self, source_id: str, target_id: str
+    ) -> tuple[Relationship, ...]:
+        """Return all relationships from source_id to target_id (directed)."""
+        return tuple(
+            rel
+            for rel in self._outgoing.get(source_id, [])
+            if rel.target == target_id
+        )
+
+    def reachable(
+        self,
+        component_id: str,
+        *,
+        direction: Direction = Direction.OUTGOING,
+        max_hops: int | None = None,
+    ) -> dict[str, int]:
+        """BFS from component_id, returning {reachable_id: hop_distance}.
+
+        The source component itself is excluded from results.
+        Direction determines which adjacency index to follow.
+        max_hops limits search depth (None = unlimited).
+        """
+        distances: dict[str, int] = {}
+        queue: deque[tuple[str, int]] = deque([(component_id, 0)])
+        visited: set[str] = {component_id}
+
+        while queue:
+            current, depth = queue.popleft()
+            if max_hops is not None and depth >= max_hops:
+                continue
+            for neighbor in self.neighbors(current, direction=direction):
+                if neighbor not in visited:
+                    visited.add(neighbor)
+                    distances[neighbor] = depth + 1
+                    queue.append((neighbor, depth + 1))
+
+        return distances
+
+    def find_cycles(self) -> tuple[CycleInfo, ...]:
+        """Detect all elementary cycles using iterative DFS with coloring.
+
+        WHITE = unvisited, GRAY = on current path, BLACK = fully explored.
+        A back-edge to a GRAY node reveals a cycle. The cycle path is
+        extracted from the DFS stack.
+        """
+        WHITE, GRAY, BLACK = 0, 1, 2
+        color: dict[str, int] = {cid: WHITE for cid in self._components}
+        cycles: list[CycleInfo] = []
+
+        for start in self._components:
+            if color[start] != WHITE:
+                continue
+
+            # Iterative DFS: stack holds (node, iterator_over_outgoing_rels)
+            # path tracks the current DFS path for cycle extraction
+            path: list[str] = []
+            path_set: set[str] = set()
+            # rel_on_path[i] = relationship used to reach path[i] from path[i-1]
+            rel_on_path: list[str] = []
+            stack: list[tuple[str, int]] = [(start, 0)]
+            color[start] = GRAY
+            path.append(start)
+            path_set.add(start)
+
+            while stack:
+                node, idx = stack[-1]
+                out_rels = self._outgoing.get(node, [])
+
+                if idx < len(out_rels):
+                    # Advance iterator
+                    stack[-1] = (node, idx + 1)
+                    rel = out_rels[idx]
+                    neighbor = rel.target
+
+                    if color.get(neighbor) == GRAY and neighbor in path_set:
+                        # Back-edge → cycle found. Extract from path.
+                        cycle_start = path.index(neighbor)
+                        cycle_nodes = path[cycle_start:] + [neighbor]
+                        cycle_rels = rel_on_path[cycle_start:] + [rel.id]
+                        cycles.append(
+                            CycleInfo(
+                                component_ids=tuple(cycle_nodes),
+                                relationship_ids=tuple(cycle_rels),
+                            )
+                        )
+                    elif color.get(neighbor) == WHITE:
+                        color[neighbor] = GRAY
+                        path.append(neighbor)
+                        path_set.add(neighbor)
+                        rel_on_path.append(rel.id)
+                        stack.append((neighbor, 0))
+                else:
+                    # All neighbors explored — backtrack
+                    color[node] = BLACK
+                    stack.pop()
+                    path.pop()
+                    path_set.discard(node)
+                    if rel_on_path:
+                        rel_on_path.pop()
+
+        return tuple(cycles)
+
+
+# ---------------------------------------------------------------------------
+# High-level functions — compose graph primitives with schema lookups
+# ---------------------------------------------------------------------------
+
+
+def get_component_context(
+    compos_map: ComposMap,
+    focal_component_ids: Sequence[str],
+    *,
+    include_removed: bool = False,
+) -> ComponentContext:
+    """Collect one-hop neighborhood + applicable constraints/risks/decisions.
+
+    Raises KeyError if any focal_component_id is not in the graph.
+    """
+    graph = RelationshipGraph(compos_map, include_removed=include_removed)
+
+    # Validate focal IDs exist
+    for cid in focal_component_ids:
+        if cid not in graph._components:
+            msg = f"Component not found: {cid!r}"
+            raise KeyError(msg)
+
+    focal_set = set(focal_component_ids)
+    focal_components = tuple(graph._components[cid] for cid in focal_component_ids)
+
+    # Collect one-hop neighbors (excluding focal components themselves)
+    neighbor_ids: set[str] = set()
+    for cid in focal_component_ids:
+        neighbor_ids |= graph.neighbors(cid, direction=Direction.BOTH)
+    neighbor_ids -= focal_set
+    neighbor_components = tuple(
+        graph._components[nid] for nid in neighbor_ids if nid in graph._components
+    )
+
+    # Collect relationships connecting focal components to their neighbors
+    all_relevant_ids = focal_set | neighbor_ids
+    rel_set: set[str] = set()
+    rels: list[Relationship] = []
+    for cid in focal_component_ids:
+        for rel in graph.relationships_of(cid, direction=Direction.BOTH):
+            if rel.id not in rel_set:
+                rel_set.add(rel.id)
+                rels.append(rel)
+
+    # Filter constraints that apply to any focal or neighbor component
+    constraint_filter = _active_filter(compos_map, include_removed)
+    applicable_constraints = tuple(
+        c
+        for c in constraint_filter.constraints
+        if set(c.applies_to) & all_relevant_ids
+    )
+
+    # Filter risks involving any focal or neighbor component/relationship
+    applicable_risks = tuple(
+        r
+        for r in constraint_filter.risks
+        if set(r.components_involved) & all_relevant_ids
+        or set(r.relationships_involved) & rel_set
+    )
+
+    # Filter decisions affecting any focal or neighbor component/relationship
+    applicable_decisions = tuple(
+        d
+        for d in constraint_filter.decisions
+        if set(d.components_affected) & all_relevant_ids
+        or set(d.relationships_affected) & rel_set
+    )
+
+    return ComponentContext(
+        focal_components=focal_components,
+        neighbor_components=neighbor_components,
+        connecting_relationships=tuple(rels),
+        applicable_constraints=applicable_constraints,
+        applicable_risks=applicable_risks,
+        applicable_decisions=applicable_decisions,
+    )
+
+
+def get_blast_radius(
+    compos_map: ComposMap,
+    component_id: str,
+    change_type: ChangeType,
+    *,
+    include_removed: bool = False,
+    max_hops: int | None = None,
+) -> BlastRadiusResult:
+    """Compute which components are affected by a change.
+
+    Direction is determined by change_type:
+    - MODIFY/REPLACE → outgoing (downstream consumers)
+    - REMOVE → both directions (upstream and downstream)
+
+    Raises KeyError if component_id is not in the graph.
+    """
+    graph = RelationshipGraph(compos_map, include_removed=include_removed)
+
+    if component_id not in graph._components:
+        msg = f"Component not found: {component_id!r}"
+        raise KeyError(msg)
+
+    # Direction depends on change type
+    if change_type == ChangeType.REMOVE:
+        direction = Direction.BOTH
+    else:
+        direction = Direction.OUTGOING
+
+    affected = _bfs_affected(graph, component_id, direction, max_hops)
+
+    return BlastRadiusResult(
+        source_component=graph._components[component_id],
+        change_type=change_type,
+        affected=tuple(sorted(affected, key=lambda a: a.hop_distance)),
+    )
+
+
+def get_constraints_for_components(
+    compos_map: ComposMap,
+    component_ids: Sequence[str],
+    *,
+    include_removed: bool = False,
+) -> tuple[Constraint, ...]:
+    """Return constraints that apply to any of the given component IDs."""
+    target_set = set(component_ids)
+    filtered = _active_filter(compos_map, include_removed)
+    return tuple(
+        c for c in filtered.constraints if set(c.applies_to) & target_set
+    )
+
+
+def evaluate_proposed_change(
+    compos_map: ComposMap,
+    *,
+    proposed_relationships: Sequence[Relationship] = (),
+    include_removed: bool = False,
+) -> ChangeEvaluation:
+    """Evaluate a hypothetical change by merging proposed relationships into the map.
+
+    Builds a temporary map with proposed relationships appended, then runs
+    cycle detection, SPOF analysis, and constraint conflict checks.
+    """
+    # Build hypothetical map with proposed relationships added
+    if proposed_relationships:
+        hypothetical = ComposMap(
+            schema_version=compos_map.schema_version,
+            map_version=compos_map.map_version,
+            generated_at=compos_map.generated_at,
+            git_commit=compos_map.git_commit,
+            parent_version=compos_map.parent_version,
+            produced_by=compos_map.produced_by,
+            project=compos_map.project,
+            components=compos_map.components,
+            relationships=compos_map.relationships + tuple(proposed_relationships),
+            constraints=compos_map.constraints,
+            risks=compos_map.risks,
+            decisions=compos_map.decisions,
+            last_merge=compos_map.last_merge,
+        )
+    else:
+        hypothetical = compos_map
+
+    graph = RelationshipGraph(hypothetical, include_removed=include_removed)
+
+    # Detect cycles in the hypothetical graph
+    cycles = graph.find_cycles()
+
+    # Detect SPOFs
+    spofs = _find_spofs(graph)
+
+    # Detect constraint conflicts: any constraint applying to a component
+    # touched by the proposed relationships
+    constraint_conflicts: list[ConstraintConflict] = []
+    if proposed_relationships:
+        # Collect component IDs touched by proposed relationships
+        touched_ids: set[str] = set()
+        for rel in proposed_relationships:
+            touched_ids.add(rel.source)
+            touched_ids.add(rel.target)
+
+        filtered = _active_filter(hypothetical, include_removed)
+        for con in filtered.constraints:
+            if set(con.applies_to) & touched_ids:
+                constraint_conflicts.append(
+                    ConstraintConflict(
+                        constraint=con,
+                        reason=(
+                            f"Proposed relationship touches constrained "
+                            f"component(s): {set(con.applies_to) & touched_ids}"
+                        ),
+                    )
+                )
+
+    return ChangeEvaluation(
+        cycles=cycles,
+        spofs=spofs,
+        constraint_conflicts=tuple(constraint_conflicts),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class _FilteredObjects:
+    """Typed container for soft-deletion-filtered ancillary objects."""
+
+    constraints: tuple[Constraint, ...]
+    risks: tuple[Risk, ...]
+    decisions: tuple[Decision, ...]
+
+
+def _active_filter(
+    compos_map: ComposMap, include_removed: bool
+) -> _FilteredObjects:
+    """Filter constraints/risks/decisions based on soft-deletion status."""
+    if include_removed:
+        return _FilteredObjects(
+            constraints=compos_map.constraints,
+            risks=compos_map.risks,
+            decisions=compos_map.decisions,
+        )
+    return _FilteredObjects(
+        constraints=tuple(
+            c for c in compos_map.constraints
+            if c.status != ConstraintStatus.REMOVED
+        ),
+        # dismissed risks are still visible — only exclude administratively removed
+        risks=tuple(
+            r for r in compos_map.risks
+            if r.status != RiskStatus.REMOVED
+        ),
+        decisions=tuple(
+            d for d in compos_map.decisions
+            if d.status not in {DecisionStatus.REVERSED, DecisionStatus.REMOVED}
+        ),
+    )
+
+
+def _next_node(rel: Relationship, current: str, direction: Direction) -> str:
+    """Return the neighbor reached by traversing *rel* from *current*."""
+    if direction == Direction.OUTGOING:
+        return rel.target
+    if direction == Direction.INCOMING:
+        return rel.source
+    return rel.target if rel.source == current else rel.source
+
+
+def _bfs_affected(
+    graph: RelationshipGraph,
+    source_id: str,
+    direction: Direction,
+    max_hops: int | None,
+) -> list[AffectedComponent]:
+    """Single-pass BFS that collects distance, path, and all relationship types.
+
+    For each hop in the path, ALL relationships between the pair are inspected
+    so that parallel edges (e.g. CALL + DATA_FLOW between the same components)
+    contribute their types to the result.
+    """
+    # parent: child_id → (parent_id, representative_rel_id)
+    parent: dict[str, tuple[str, str]] = {}
+    distances: dict[str, int] = {}
+    queue: deque[tuple[str, int]] = deque([(source_id, 0)])
+    visited: set[str] = {source_id}
+
+    while queue:
+        current, depth = queue.popleft()
+        if max_hops is not None and depth >= max_hops:
+            continue
+        for rel in graph.relationships_of(current, direction=direction):
+            next_id = _next_node(rel, current, direction)
+            if next_id not in visited:
+                visited.add(next_id)
+                distances[next_id] = depth + 1
+                parent[next_id] = (current, rel.id)
+                queue.append((next_id, depth + 1))
+
+    # Reconstruct paths and collect ALL relationship types per hop
+    result: list[AffectedComponent] = []
+    for comp_id, dist in distances.items():
+        path_ids: list[str] = []
+        rel_types: set[RelationshipType] = set()
+        node = comp_id
+        while node in parent:
+            prev, rep_rel_id = parent[node]
+            path_ids.append(rep_rel_id)
+            # Collect types from ALL relationships between prev and node
+            for rel in graph.relationships_between(prev, node):
+                rel_types.add(rel.type)
+            # For BOTH/INCOMING, also check the reverse direction
+            if direction != Direction.OUTGOING:
+                for rel in graph.relationships_between(node, prev):
+                    rel_types.add(rel.type)
+            node = prev
+        path_ids.reverse()
+        result.append(
+            AffectedComponent(
+                component=graph._components[comp_id],
+                hop_distance=dist,
+                path=tuple(path_ids),
+                relationship_types=frozenset(rel_types),
+            )
+        )
+
+    return result
+
+
+def _find_spofs(graph: RelationshipGraph) -> tuple[SPOFInfo, ...]:
+    """Identify single points of failure in the graph.
+
+    A SPOF candidate is a component with 2+ incoming synchronous relationships.
+    The has_error_behavior flag indicates whether ALL sync dependents define
+    error_behavior — if they do, the SPOF is lower severity but still reported.
+    """
+    spofs: list[SPOFInfo] = []
+
+    for comp_id, comp in graph._components.items():
+        incoming = graph.relationships_of(comp_id, direction=Direction.INCOMING)
+        # Filter to synchronous relationships only
+        sync_rels = [
+            r for r in incoming if r.pattern == RelationshipPattern.SYNCHRONOUS
+        ]
+        if len(sync_rels) < 2:
+            continue
+
+        sync_dependents = tuple(
+            graph._components[r.source]
+            for r in sync_rels
+            if r.source in graph._components
+        )
+        # has_error_behavior is True only if ALL sync rels define it
+        has_error_behavior = all(r.error_behavior is not None for r in sync_rels)
+
+        spofs.append(
+            SPOFInfo(
+                component=comp,
+                dependent_count=len(sync_rels),
+                synchronous_dependents=sync_dependents,
+                has_error_behavior=has_error_behavior,
+            )
+        )
+
+    return tuple(spofs)