archunitpython 1.0.0__py3-none-any.whl

archunitpython/common/projection/cycles/cycle_utils.py

@@ -0,0 +1,49 @@
+"""Utility functions for cycle detection."""
+
+from __future__ import annotations
+
+from archunitpython.common.projection.cycles.model import NumberEdge, NumberNode
+
+
+class CycleUtils:
+    @staticmethod
+    def get_outgoing_neighbours(
+        current_node: NumberNode, graph: list[NumberNode]
+    ) -> list[NumberNode]:
+        """Get all nodes that current_node has outgoing edges to."""
+        node_map = {n.node: n for n in graph}
+        result = []
+        for edge in current_node.outgoing:
+            neighbour = node_map.get(edge.to_node)
+            if neighbour is not None:
+                result.append(neighbour)
+        return result
+
+    @staticmethod
+    def transform_edge_data(edges: list[NumberEdge]) -> list[NumberNode]:
+        """Convert a list of edges into a list of nodes with in/out edges."""
+        unique_ids = CycleUtils.find_unique_nodes(edges)
+        nodes = []
+        for node_id in unique_ids:
+            nodes.append(
+                NumberNode(
+                    node=node_id,
+                    incoming=[e for e in edges if e.to_node == node_id],
+                    outgoing=[e for e in edges if e.from_node == node_id],
+                )
+            )
+        return nodes
+
+    @staticmethod
+    def find_unique_nodes(edges: list[NumberEdge]) -> list[int]:
+        """Find all unique node IDs in a list of edges, preserving order."""
+        seen: set[int] = set()
+        result: list[int] = []
+        for edge in edges:
+            if edge.from_node not in seen:
+                seen.add(edge.from_node)
+                result.append(edge.from_node)
+            if edge.to_node not in seen:
+                seen.add(edge.to_node)
+                result.append(edge.to_node)
+        return result

archunitpython/common/projection/cycles/cycles.py

@@ -0,0 +1,26 @@
+"""Orchestrate cycle detection: Tarjan SCC -> Johnson per SCC."""
+
+from __future__ import annotations
+
+from archunitpython.common.projection.cycles.johnsons_apsp import JohnsonsAPSP
+from archunitpython.common.projection.cycles.model import NumberEdge
+from archunitpython.common.projection.cycles.tarjan_scc import TarjanSCC
+
+
+def calculate_cycles(edges: list[NumberEdge]) -> list[list[NumberEdge]]:
+    """Find all simple cycles using Tarjan SCC + Johnson's algorithm.
+
+    1. Find strongly connected components using Tarjan's algorithm
+    2. For each SCC with >1 edge, find all simple cycles using Johnson's
+    """
+    cycles: list[list[NumberEdge]] = []
+
+    tarjan = TarjanSCC()
+    sccs = tarjan.find_strongly_connected_components(edges)
+
+    for scc in sccs:
+        if len(scc) > 1:
+            johnson = JohnsonsAPSP()
+            cycles.extend(johnson.find_simple_cycles(scc))
+
+    return cycles

archunitpython/common/projection/cycles/johnsons_apsp.py

@@ -0,0 +1,110 @@
+"""Johnson's algorithm for finding all simple cycles in a directed graph."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.common.projection.cycles.cycle_utils import CycleUtils
+from archunitpython.common.projection.cycles.model import NumberEdge, NumberNode
+
+
+@dataclass
+class _BlockedBy:
+    blocked: NumberNode
+    by: NumberNode
+
+
+class JohnsonsAPSP:
+    """Johnson's algorithm for finding all simple (elementary) cycles."""
+
+    def find_simple_cycles(self, edges: list[NumberEdge]) -> list[list[NumberEdge]]:
+        """Find all simple cycles in the graph defined by edges.
+
+        Should be called on a strongly connected component for efficiency.
+        """
+        self._blocked: list[NumberNode] = []
+        self._stack: list[NumberNode] = []
+        self._blocked_map: list[_BlockedBy] = []
+        self._graph = CycleUtils.transform_edge_data(edges)
+        self._start: NumberNode | None = None
+        self._cycles: list[list[NumberEdge]] = []
+
+        for node in list(self._graph):
+            self._start = node
+            self._stack.append(node)
+            self._blocked.append(node)
+            self._explore_neighbours(node)
+            self._remove_from_graph(node)
+
+        return self._cycles
+
+    def _explore_neighbours(self, current_node: NumberNode) -> None:
+        neighbours = CycleUtils.get_outgoing_neighbours(current_node, self._graph)
+        for neighbour in neighbours:
+            if self._found_cycle(neighbour):
+                self._cycles.append(self._build_cycle())
+            if not self._is_blocked(neighbour):
+                self._stack.append(neighbour)
+                self._blocked.append(neighbour)
+                self._explore_neighbours(neighbour)
+
+        self._stack.pop()
+
+        if self._is_part_of_current_start_cycle(current_node):
+            self._unblock(current_node)
+        else:
+            for neighbour in CycleUtils.get_outgoing_neighbours(
+                current_node, self._graph
+            ):
+                if self._is_blocked(neighbour):
+                    self._blocked_map.append(
+                        _BlockedBy(blocked=current_node, by=neighbour)
+                    )
+
+    def _unblock(self, node: NumberNode) -> None:
+        self._blocked = [n for n in self._blocked if n is not node]
+        to_remove: list[_BlockedBy] = []
+        for blocker in self._blocked_map:
+            if blocker.by is node:
+                self._unblock(blocker.blocked)
+                to_remove.append(blocker)
+        self._blocked_map = [b for b in self._blocked_map if b not in to_remove]
+
+    def _is_part_of_current_start_cycle(self, current_node: NumberNode) -> bool:
+        if self._start is None:
+            return False
+        for cycle in self._cycles:
+            if (
+                cycle[0].from_node == self._start.node
+                and any(e.from_node == current_node.node for e in cycle)
+            ):
+                return True
+        return False
+
+    def _is_blocked(self, node: NumberNode) -> bool:
+        return node in self._blocked
+
+    def _remove_from_graph(self, to_remove: NumberNode) -> None:
+        for node in self._graph:
+            node.incoming = [
+                e
+                for e in node.incoming
+                if e.from_node != to_remove.node and e.to_node != to_remove.node
+            ]
+            node.outgoing = [
+                e
+                for e in node.outgoing
+                if e.from_node != to_remove.node and e.to_node != to_remove.node
+            ]
+
+    def _found_cycle(self, current_node: NumberNode) -> bool:
+        return current_node is self._start
+
+    def _build_cycle(self) -> list[NumberEdge]:
+        node_ids = [n.node for n in self._stack]
+        cycle_edges: list[NumberEdge] = []
+        for i in range(len(node_ids)):
+            from_id = node_ids[i]
+            to_id = node_ids[i + 1] if i + 1 < len(node_ids) else self._start.node  # type: ignore[union-attr]
+            cycle_edges.append(NumberEdge(from_node=from_id, to_node=to_id))
+        return cycle_edges

archunitpython/common/projection/cycles/model.py

@@ -0,0 +1,22 @@
+"""Numeric graph model for cycle detection algorithms."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class NumberEdge:
+    """An edge between two numerically-identified nodes."""
+
+    from_node: int
+    to_node: int
+
+
+@dataclass
+class NumberNode:
+    """A node with incoming and outgoing edges."""
+
+    node: int
+    incoming: list[NumberEdge] = field(default_factory=list)
+    outgoing: list[NumberEdge] = field(default_factory=list)

archunitpython/common/projection/cycles/tarjan_scc.py

@@ -0,0 +1,86 @@
+"""Tarjan's Strongly Connected Components algorithm."""
+
+from __future__ import annotations
+
+from archunitpython.common.projection.cycles.model import NumberEdge
+
+
+class _Vertex:
+    """Internal vertex representation for Tarjan's algorithm."""
+
+    def __init__(self, node_id: int) -> None:
+        self.id = node_id
+        self.index = -1
+        self.lowlink = -1
+        self.neighbours: list[int] = []
+
+
+class TarjanSCC:
+    """Tarjan's algorithm for finding strongly connected components."""
+
+    def find_strongly_connected_components(
+        self, edges: list[NumberEdge]
+    ) -> list[list[NumberEdge]]:
+        """Find all strongly connected components in the graph.
+
+        Returns a list of edge lists, where each inner list contains
+        the edges belonging to one SCC. Only SCCs with edges are returned.
+        """
+        self._graph: dict[int, _Vertex] = {}
+        self._index = 0
+        self._stack: list[_Vertex] = []
+        self._sccs: list[list[NumberEdge]] = []
+        self._edges = edges
+
+        self._init(edges)
+
+        for vertex in self._graph.values():
+            if vertex.index < 0:
+                self._visit(vertex)
+
+        return self._sccs
+
+    def _init(self, edges: list[NumberEdge]) -> None:
+        """Build adjacency representation from edges."""
+        for edge in edges:
+            if edge.from_node not in self._graph:
+                self._graph[edge.from_node] = _Vertex(edge.from_node)
+            if edge.to_node not in self._graph:
+                self._graph[edge.to_node] = _Vertex(edge.to_node)
+
+            v = self._graph[edge.from_node]
+            if edge.to_node not in v.neighbours:
+                v.neighbours.append(edge.to_node)
+
+    def _visit(self, vertex: _Vertex) -> None:
+        """DFS visit for Tarjan's algorithm."""
+        vertex.index = self._index
+        vertex.lowlink = self._index
+        self._index += 1
+        self._stack.append(vertex)
+
+        for neighbour_id in vertex.neighbours:
+            w = self._graph[neighbour_id]
+            if w.index < 0:
+                self._visit(w)
+                vertex.lowlink = min(vertex.lowlink, w.lowlink)
+            elif w in self._stack:
+                vertex.lowlink = min(vertex.lowlink, w.index)
+
+        if vertex.lowlink == vertex.index:
+            scc_vertices: list[_Vertex] = []
+            while True:
+                w = self._stack.pop()
+                scc_vertices.append(w)
+                if w.id == vertex.id:
+                    break
+
+            if scc_vertices:
+                scc_ids = {v.id for v in scc_vertices}
+                scc_edges = [
+                    e
+                    for e in self._edges
+                    if e.from_node in scc_ids and e.to_node in scc_ids
+                ]
+                if scc_edges:
+                    self._sccs.append(scc_edges)

archunitpython/common/projection/edge_projections.py

@@ -0,0 +1,36 @@
+"""Built-in MapFunction implementations for edge projection."""
+
+from __future__ import annotations
+
+from archunitpython.common.extraction.graph import Edge
+from archunitpython.common.projection.types import MapFunction, MappedEdge
+
+
+def per_internal_edge() -> MapFunction:
+    """Create a mapper that only passes internal (non-external) edges.
+
+    Self-referencing edges (source == target) are also filtered out.
+    """
+
+    def mapper(edge: Edge) -> MappedEdge | None:
+        if edge.external:
+            return None
+        if edge.source == edge.target:
+            return None
+        return MappedEdge(source_label=edge.source, target_label=edge.target)
+
+    return mapper
+
+
+def per_edge() -> MapFunction:
+    """Create a mapper that passes all edges (including external).
+
+    Self-referencing edges are still filtered out.
+    """
+
+    def mapper(edge: Edge) -> MappedEdge | None:
+        if edge.source == edge.target:
+            return None
+        return MappedEdge(source_label=edge.source, target_label=edge.target)
+
+    return mapper

archunitpython/common/projection/project_cycles.py

@@ -0,0 +1,85 @@
+"""High-level cycle detection on projected graphs."""
+
+from __future__ import annotations
+
+from archunitpython.common.extraction.graph import Edge
+from archunitpython.common.projection.cycles.cycles import calculate_cycles
+from archunitpython.common.projection.cycles.model import NumberEdge
+from archunitpython.common.projection.edge_projections import per_internal_edge
+from archunitpython.common.projection.project_edges import project_edges
+from archunitpython.common.projection.types import ProjectedEdge
+
+ProjectedCycles = list[list[ProjectedEdge]]
+
+
+def project_internal_cycles(graph: list[Edge]) -> ProjectedCycles:
+    """Find cycles among internal edges of a raw graph."""
+    edges = project_edges(graph, per_internal_edge())
+    return project_cycles(edges)
+
+
+def project_cycles(edges: list[ProjectedEdge]) -> ProjectedCycles:
+    """Find cycles in a list of projected edges."""
+    return _CycleProcessor().find_cycles(edges)
+
+
+class _CycleProcessor:
+    """Converts between string labels and numeric IDs for cycle detection."""
+
+    def __init__(self) -> None:
+        self._label_to_id: dict[str, int] = {}
+        self._id_to_label: dict[int, str] = {}
+        self._source_edges: list[ProjectedEdge] = []
+
+    def find_cycles(self, edges: list[ProjectedEdge]) -> ProjectedCycles:
+        domain_edges = self._to_domain(edges)
+        cycles = calculate_cycles(domain_edges)
+        return self._from_domain(cycles)
+
+    def _to_domain(self, edges: list[ProjectedEdge]) -> list[NumberEdge]:
+        self._source_edges = edges
+        self._label_to_id = {}
+        self._id_to_label = {}
+        index = 0
+
+        for e in edges:
+            if e.source_label not in self._label_to_id:
+                self._label_to_id[e.source_label] = index
+                self._id_to_label[index] = e.source_label
+                index += 1
+            if e.target_label not in self._label_to_id:
+                self._label_to_id[e.target_label] = index
+                self._id_to_label[index] = e.target_label
+                index += 1
+
+        return [
+            NumberEdge(
+                from_node=self._label_to_id[e.source_label],
+                to_node=self._label_to_id[e.target_label],
+            )
+            for e in edges
+        ]
+
+    def _from_domain(self, cycles: list[list[NumberEdge]]) -> ProjectedCycles:
+        result: ProjectedCycles = []
+
+        for cycle in cycles:
+            projected_cycle: list[ProjectedEdge] = []
+            for e in cycle:
+                source_label = self._id_to_label[e.from_node]
+                target_label = self._id_to_label[e.to_node]
+                found = next(
+                    (
+                        se
+                        for se in self._source_edges
+                        if se.source_label == source_label
+                        and se.target_label == target_label
+                    ),
+                    None,
+                )
+                if found:
+                    projected_cycle.append(found)
+            if projected_cycle:
+                result.append(projected_cycle)
+
+        return result

archunitpython/common/projection/project_edges.py

@@ -0,0 +1,43 @@
+"""Project a raw graph into labeled edges with edge aggregation."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from archunitpython.common.extraction.graph import Edge
+from archunitpython.common.projection.types import MapFunction, ProjectedEdge
+
+
+def project_edges(
+    graph: list[Edge],
+    mapper: MapFunction,
+) -> list[ProjectedEdge]:
+    """Apply a mapper to raw edges and group by (source_label, target_label).
+
+    Edges that map to the same (source_label, target_label) are cumulated.
+    Edges for which the mapper returns None are filtered out.
+
+    Args:
+        graph: Raw edge list.
+        mapper: Function that maps Edge → MappedEdge or None.
+
+    Returns:
+        List of ProjectedEdge objects with cumulated raw edges.
+    """
+    groups: dict[tuple[str, str], list[Edge]] = defaultdict(list)
+
+    for edge in graph:
+        mapped = mapper(edge)
+        if mapped is None:
+            continue
+        key = (mapped.source_label, mapped.target_label)
+        groups[key].append(edge)
+
+    return [
+        ProjectedEdge(
+            source_label=source_label,
+            target_label=target_label,
+            cumulated_edges=edges,
+        )
+        for (source_label, target_label), edges in groups.items()
+    ]

archunitpython/common/projection/project_nodes.py

@@ -0,0 +1,49 @@
+"""Project a raw graph into nodes with incoming/outgoing edges."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+from archunitpython.common.extraction.graph import Edge
+from archunitpython.common.projection.types import ProjectedNode
+
+
+def project_to_nodes(
+    graph: list[Edge],
+    *,
+    include_externals: bool = False,
+) -> list[ProjectedNode]:
+    """Group edges into nodes with incoming and outgoing edge lists.
+
+    Args:
+        graph: Raw edge list.
+        include_externals: If True, include nodes for external dependencies.
+
+    Returns:
+        List of ProjectedNode objects.
+    """
+    incoming: dict[str, list[Edge]] = defaultdict(list)
+    outgoing: dict[str, list[Edge]] = defaultdict(list)
+    all_labels: set[str] = set()
+
+    for edge in graph:
+        if edge.external and not include_externals:
+            # Still record the source (internal file)
+            all_labels.add(edge.source)
+            outgoing[edge.source].append(edge)
+            continue
+
+        all_labels.add(edge.source)
+        all_labels.add(edge.target)
+        outgoing[edge.source].append(edge)
+        if edge.source != edge.target:  # Don't count self-edges as incoming
+            incoming[edge.target].append(edge)
+
+    return [
+        ProjectedNode(
+            label=label,
+            incoming=incoming.get(label, []),
+            outgoing=[e for e in outgoing.get(label, []) if e.source != e.target],
+        )
+        for label in sorted(all_labels)
+    ]

archunitpython/common/projection/types.py

@@ -0,0 +1,40 @@
+"""Types for graph projections."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from archunitpython.common.extraction.graph import Edge
+
+
+@dataclass
+class ProjectedNode:
+    """A node in a projected graph with its incoming/outgoing edges."""
+
+    label: str
+    incoming: list[Edge] = field(default_factory=list)
+    outgoing: list[Edge] = field(default_factory=list)
+
+
+@dataclass
+class MappedEdge:
+    """An edge after label mapping."""
+
+    source_label: str
+    target_label: str
+
+
+@dataclass
+class ProjectedEdge:
+    """An edge between two labeled nodes, aggregating underlying raw edges."""
+
+    source_label: str
+    target_label: str
+    cumulated_edges: list[Edge] = field(default_factory=list)
+
+
+MapFunction = Callable[[Edge], MappedEdge | None]
+"""A function that maps a raw Edge to a MappedEdge (or None to filter it out)."""
+
+ProjectedGraph = list[ProjectedEdge]

archunitpython/common/regex_factory.py

@@ -0,0 +1,76 @@
+"""Factory for creating Filter objects from glob patterns or regex."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+
+from archunitpython.common.types import Filter, Pattern, PatternMatchingOptions
+
+
+def _glob_to_regex(pattern: str) -> re.Pattern[str]:
+    """Convert a glob pattern to a compiled regex.
+
+    Uses fnmatch.translate() which converts shell-style wildcards to regex.
+    """
+    regex_str = fnmatch.translate(pattern)
+    return re.compile(regex_str)
+
+
+def _escape_regex(s: str) -> str:
+    """Escape special regex characters in a string."""
+    return re.escape(s)
+
+
+def _pattern_to_regex(pattern: Pattern) -> re.Pattern[str]:
+    """Convert a Pattern (str glob or compiled regex) to a compiled regex."""
+    if isinstance(pattern, re.Pattern):
+        return pattern
+    return _glob_to_regex(pattern)
+
+
+class RegexFactory:
+    """Factory for creating Filter objects from patterns."""
+
+    @staticmethod
+    def filename_matcher(name: Pattern) -> Filter:
+        """Create a filter that matches against the filename only (no directory)."""
+        return Filter(
+            regexp=_pattern_to_regex(name),
+            options=PatternMatchingOptions(target="filename"),
+        )
+
+    @staticmethod
+    def classname_matcher(name: Pattern) -> Filter:
+        """Create a filter that matches against class names."""
+        return Filter(
+            regexp=_pattern_to_regex(name),
+            options=PatternMatchingOptions(target="classname"),
+        )
+
+    @staticmethod
+    def folder_matcher(folder: Pattern) -> Filter:
+        """Create a filter that matches against the directory path (no filename)."""
+        return Filter(
+            regexp=_pattern_to_regex(folder),
+            options=PatternMatchingOptions(target="path-no-filename"),
+        )
+
+    @staticmethod
+    def path_matcher(path: Pattern) -> Filter:
+        """Create a filter that matches against the full file path."""
+        return Filter(
+            regexp=_pattern_to_regex(path),
+            options=PatternMatchingOptions(target="path"),
+        )
+
+    @staticmethod
+    def exact_file_matcher(file_path: str) -> Filter:
+        """Create a filter that matches an exact file path."""
+        normalized = file_path.replace("\\", "/")
+        escaped = _escape_regex(normalized)
+        regexp = re.compile(f"^{escaped}$")
+        return Filter(
+            regexp=regexp,
+            options=PatternMatchingOptions(target="path"),
+        )

archunitpython/common/types.py

@@ -0,0 +1,29 @@
+"""Core type definitions for pattern matching and filtering."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Literal, Union
+
+Pattern = Union[str, re.Pattern[str]]
+"""A pattern can be a glob string or a compiled regex."""
+
+MatchTarget = Literal["filename", "path", "path-no-filename", "classname"]
+MatchType = Literal["exact", "partial"]
+
+
+@dataclass(frozen=True)
+class PatternMatchingOptions:
+    """Options controlling how a pattern is matched against file paths."""
+
+    target: MatchTarget = "path"
+    matching: MatchType = "partial"
+
+
+@dataclass(frozen=True)
+class Filter:
+    """A compiled regex filter with matching options."""
+
+    regexp: re.Pattern[str]
+    options: PatternMatchingOptions

archunitpython/common/util/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.common.util.logger import CheckLogger, shared_logger
+
+__all__ = ["CheckLogger", "shared_logger"]