archunitpython 1.0.0__py3-none-any.whl

archunitpython/slices/assertion/admissible_edges.py

@@ -0,0 +1,108 @@
+"""Violation gathering for slice-level architecture rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.projection.types import ProjectedEdge
+from archunitpython.slices.uml.generate_rules import Rule
+
+
+@dataclass
+class CoherenceOptions:
+    """Options for architecture coherence checking."""
+
+    ignore_orphan_slices: bool = False
+    ignore_external_slices: bool = False
+
+
+@dataclass
+class ViolatingEdge(Violation):
+    """A slice dependency that violates the architecture rules."""
+
+    rule: Rule | None
+    projected_edge: ProjectedEdge
+    is_negated: bool = False
+
+
+def gather_violations(
+    edges: list[ProjectedEdge],
+    rules: list[Rule],
+) -> list[Violation]:
+    """Check for forbidden dependencies (used with shouldNot).
+
+    Args:
+        edges: Projected dependency edges between slices.
+        rules: Forbidden dependency rules.
+
+    Returns:
+        Violations for any edge that matches a forbidden rule.
+    """
+    violations: list[Violation] = []
+
+    for edge in edges:
+        for rule in rules:
+            if edge.source_label == rule.source and edge.target_label == rule.target:
+                violations.append(
+                    ViolatingEdge(
+                        rule=rule,
+                        projected_edge=edge,
+                        is_negated=True,
+                    )
+                )
+
+    return violations
+
+
+def gather_positive_violations(
+    edges: list[ProjectedEdge],
+    rules: list[Rule],
+    contained_nodes: list[str],
+    coherence_options: CoherenceOptions | None = None,
+) -> list[Violation]:
+    """Check that all dependencies are allowed by rules (used with should).
+
+    Args:
+        edges: Projected dependency edges between slices.
+        rules: Allowed dependency rules from diagram.
+        contained_nodes: All declared component names in the diagram.
+        coherence_options: Options for handling orphan/external slices.
+
+    Returns:
+        Violations for any edge not covered by the rules.
+    """
+    violations: list[Violation] = []
+    opts = coherence_options or CoherenceOptions()
+
+    # Build set of allowed edges (including self-dependencies)
+    allowed = {(r.source, r.target) for r in rules}
+
+    for edge in edges:
+        source = edge.source_label
+        target = edge.target_label
+
+        # Self-dependency is always allowed
+        if source == target:
+            continue
+
+        # Check if source/target are known components
+        source_known = source in contained_nodes
+        target_known = target in contained_nodes
+
+        if not source_known and opts.ignore_orphan_slices:
+            continue
+        if not target_known and opts.ignore_orphan_slices:
+            continue
+
+        # Check if the edge is allowed
+        if (source, target) not in allowed:
+            violations.append(
+                ViolatingEdge(
+                    rule=None,
+                    projected_edge=edge,
+                    is_negated=False,
+                )
+            )
+
+    return violations

archunitpython/slices/fluentapi/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.slices.fluentapi.slices import project_slices
+
+__all__ = ["project_slices"]

archunitpython/slices/fluentapi/slices.py

@@ -0,0 +1,220 @@
+"""Fluent API builder chain for slice-level architecture rules.
+
+Usage:
+    project_slices('src/')
+        .defined_by('src/(**)/')
+        .should()
+        .adhere_to_diagram(puml_content)
+        .check()
+"""
+
+from __future__ import annotations
+
+import re
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.extraction.extract_graph import extract_graph
+from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.projection.project_edges import project_edges
+from archunitpython.common.projection.types import MapFunction
+from archunitpython.slices.assertion.admissible_edges import (
+    CoherenceOptions,
+    gather_positive_violations,
+    gather_violations,
+)
+from archunitpython.slices.projection.slicing_projections import (
+    slice_by_pattern,
+    slice_by_regex,
+)
+from archunitpython.slices.uml.generate_rules import Rule, generate_rule
+
+
+def project_slices(project_path: str | None = None) -> "SliceConditionBuilder":
+    """Entry point for slice-level architecture rules.
+
+    Args:
+        project_path: Root directory of the project to analyze.
+    """
+    return SliceConditionBuilder(project_path)
+
+
+class SliceConditionBuilder:
+    """Initial builder - define how files are grouped into slices."""
+
+    def __init__(self, project_path: str | None = None) -> None:
+        self._project_path = project_path
+        self._pattern: str | None = None
+        self._regex: re.Pattern[str] | None = None
+
+    def defined_by(self, pattern: str) -> "SliceConditionBuilder":
+        """Define slices using a path pattern with (**) placeholder.
+
+        Example: 'src/(**)/' groups files by the directory after src/.
+        """
+        self._pattern = pattern
+        return self
+
+    def defined_by_regex(self, regex: re.Pattern[str]) -> "SliceConditionBuilder":
+        """Define slices using a regex with a capture group."""
+        self._regex = regex
+        return self
+
+    def should(self) -> "PositiveConditionBuilder":
+        """Begin positive assertion (slices SHOULD ...)."""
+        return PositiveConditionBuilder(
+            self._project_path, self._pattern, self._regex
+        )
+
+    def should_not(self) -> "NegativeConditionBuilder":
+        """Begin negative assertion (slices SHOULD NOT ...)."""
+        return NegativeConditionBuilder(
+            self._project_path, self._pattern, self._regex
+        )
+
+
+class PositiveConditionBuilder:
+    """Positive assertion builder for slices."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        pattern: str | None,
+        regex: re.Pattern[str] | None,
+    ) -> None:
+        self._project_path = project_path
+        self._pattern = pattern
+        self._regex = regex
+        self._coherence_options = CoherenceOptions()
+
+    def ignoring_orphan_slices(self) -> "PositiveConditionBuilder":
+        """Ignore slices not declared in the diagram."""
+        self._coherence_options = CoherenceOptions(
+            ignore_orphan_slices=True,
+            ignore_external_slices=self._coherence_options.ignore_external_slices,
+        )
+        return self
+
+    def ignoring_external_slices(self) -> "PositiveConditionBuilder":
+        """Ignore external dependency slices."""
+        self._coherence_options = CoherenceOptions(
+            ignore_orphan_slices=self._coherence_options.ignore_orphan_slices,
+            ignore_external_slices=True,
+        )
+        return self
+
+    def adhere_to_diagram(self, puml_content: str) -> "PositiveSliceCondition":
+        """Assert that slices adhere to a PlantUML diagram."""
+        return PositiveSliceCondition(
+            self._project_path,
+            self._pattern,
+            self._regex,
+            puml_content,
+            self._coherence_options,
+        )
+
+    def adhere_to_diagram_in_file(self, file_path: str) -> "PositiveSliceCondition":
+        """Assert that slices adhere to a diagram loaded from a file."""
+        with open(file_path, "r", encoding="utf-8") as f:
+            puml_content = f.read()
+        return self.adhere_to_diagram(puml_content)
+
+
+class NegativeConditionBuilder:
+    """Negative assertion builder for slices."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        pattern: str | None,
+        regex: re.Pattern[str] | None,
+    ) -> None:
+        self._project_path = project_path
+        self._pattern = pattern
+        self._regex = regex
+        self._forbidden_deps: list[tuple[str, str]] = []
+
+    def contain_dependency(
+        self, source: str, target: str
+    ) -> "NegativeSliceCondition":
+        """Assert that a specific dependency should NOT exist."""
+        return NegativeSliceCondition(
+            self._project_path,
+            self._pattern,
+            self._regex,
+            source,
+            target,
+        )
+
+
+class PositiveSliceCondition:
+    """Checkable that verifies slices adhere to a diagram."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        pattern: str | None,
+        regex: re.Pattern[str] | None,
+        puml_content: str,
+        coherence_options: CoherenceOptions,
+    ) -> None:
+        self._project_path = project_path
+        self._pattern = pattern
+        self._regex = regex
+        self._puml_content = puml_content
+        self._coherence_options = coherence_options
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        graph = extract_graph(self._project_path, options=options)
+        rules, contained_nodes = generate_rule(self._puml_content)
+
+        mapper = self._get_mapper()
+        edges = project_edges(graph, mapper)
+
+        return gather_positive_violations(
+            edges, rules, contained_nodes, self._coherence_options
+        )
+
+    def _get_mapper(self) -> MapFunction:
+        if self._pattern:
+            return slice_by_pattern(self._pattern)
+        elif self._regex:
+            return slice_by_regex(self._regex)
+        from archunitpython.slices.projection.slicing_projections import identity
+
+        return identity()
+
+
+class NegativeSliceCondition:
+    """Checkable that verifies a specific dependency does NOT exist."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        pattern: str | None,
+        regex: re.Pattern[str] | None,
+        source: str,
+        target: str,
+    ) -> None:
+        self._project_path = project_path
+        self._pattern = pattern
+        self._regex = regex
+        self._source = source
+        self._target = target
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        graph = extract_graph(self._project_path, options=options)
+
+        mapper = self._get_mapper()
+        edges = project_edges(graph, mapper)
+
+        forbidden_rule = Rule(source=self._source, target=self._target)
+        return gather_violations(edges, [forbidden_rule])
+
+    def _get_mapper(self) -> MapFunction:
+        if self._pattern:
+            return slice_by_pattern(self._pattern)
+        elif self._regex:
+            return slice_by_regex(self._regex)
+        from archunitpython.slices.projection.slicing_projections import identity
+
+        return identity()

archunitpython/slices/projection/__init__.py

@@ -0,0 +1,8 @@
+from archunitpython.slices.projection.slicing_projections import (
+    identity,
+    slice_by_file_suffix,
+    slice_by_pattern,
+    slice_by_regex,
+)
+
+__all__ = ["identity", "slice_by_file_suffix", "slice_by_pattern", "slice_by_regex"]

archunitpython/slices/projection/slicing_projections.py

@@ -0,0 +1,128 @@
+"""Slicing projection functions that extract slice names from file paths."""
+
+from __future__ import annotations
+
+import re
+
+from archunitpython.common.extraction.graph import Edge
+from archunitpython.common.pattern_matching import normalize_path
+from archunitpython.common.projection.types import MapFunction, MappedEdge
+
+
+def identity() -> MapFunction:
+    """No-op mapper - uses full paths as labels."""
+
+    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
+
+
+def slice_by_pattern(pattern: str) -> MapFunction:
+    """Create a mapper that extracts slice names from paths using a pattern.
+
+    The pattern uses (**) as a placeholder for the slice name.
+    Example: 'src/(**)/' with 'src/auth/service.py' extracts 'auth'.
+
+    Args:
+        pattern: A pattern string containing (**) as the slice capture group.
+    """
+    # Convert the pattern to regex:
+    # - Escape special regex chars except (**)
+    # - Replace (**) with a capture group
+    escaped = _escape_for_regexp(pattern)
+    regex_str = escaped.replace(r"\(\*\*\)", "([^/]+)")
+    # Replace remaining ** with .* and * with [^/]*
+    regex_str = regex_str.replace(r"\*\*", ".*").replace(r"\*", "[^/]*")
+    regex = re.compile(regex_str)
+
+    def mapper(edge: Edge) -> MappedEdge | None:
+        if edge.external or edge.source == edge.target:
+            return None
+
+        source_label = _extract_slice(normalize_path(edge.source), regex)
+        target_label = _extract_slice(normalize_path(edge.target), regex)
+
+        if source_label is None or target_label is None:
+            return None
+        if source_label == target_label:
+            return None
+
+        return MappedEdge(source_label=source_label, target_label=target_label)
+
+    return mapper
+
+
+def slice_by_regex(regexp: re.Pattern[str]) -> MapFunction:
+    """Create a mapper that extracts slice names using a regex with a capture group.
+
+    The first capture group in the regex becomes the slice name.
+    """
+
+    def mapper(edge: Edge) -> MappedEdge | None:
+        if edge.external or edge.source == edge.target:
+            return None
+
+        source_label = _extract_slice(normalize_path(edge.source), regexp)
+        target_label = _extract_slice(normalize_path(edge.target), regexp)
+
+        if source_label is None or target_label is None:
+            return None
+        if source_label == target_label:
+            return None
+
+        return MappedEdge(source_label=source_label, target_label=target_label)
+
+    return mapper
+
+
+def slice_by_file_suffix(labeling: dict[str, str]) -> MapFunction:
+    """Create a mapper that assigns slices based on file name suffixes.
+
+    Args:
+        labeling: Mapping of suffix → slice name.
+            Example: {'_controller': 'controllers', '_service': 'services'}
+    """
+
+    def mapper(edge: Edge) -> MappedEdge | None:
+        if edge.external or edge.source == edge.target:
+            return None
+
+        source_label = _extract_suffix_label(edge.source, labeling)
+        target_label = _extract_suffix_label(edge.target, labeling)
+
+        if source_label is None or target_label is None:
+            return None
+        if source_label == target_label:
+            return None
+
+        return MappedEdge(source_label=source_label, target_label=target_label)
+
+    return mapper
+
+
+def _extract_slice(path: str, regex: re.Pattern[str]) -> str | None:
+    """Extract slice name from path using regex first capture group."""
+    match = regex.search(path)
+    if match and match.groups():
+        return match.group(1)
+    return None
+
+
+def _extract_suffix_label(path: str, labeling: dict[str, str]) -> str | None:
+    """Extract label by matching file suffix."""
+    normalized = normalize_path(path)
+    # Remove extension
+    base = normalized.rsplit(".", 1)[0] if "." in normalized else normalized
+
+    for suffix, label in labeling.items():
+        if base.endswith(suffix):
+            return label
+    return None
+
+
+def _escape_for_regexp(pattern: str) -> str:
+    """Escape special regex characters in a pattern string."""
+    return re.escape(pattern)

archunitpython/slices/uml/__init__.py

@@ -0,0 +1,4 @@
+from archunitpython.slices.uml.export_diagram import export_diagram
+from archunitpython.slices.uml.generate_rules import Rule, generate_rule
+
+__all__ = ["Rule", "export_diagram", "generate_rule"]

archunitpython/slices/uml/export_diagram.py

@@ -0,0 +1,31 @@
+"""Export a projected graph as a PlantUML diagram."""
+
+from __future__ import annotations
+
+from archunitpython.common.projection.types import ProjectedEdge
+
+
+def export_diagram(graph: list[ProjectedEdge]) -> str:
+    """Generate a PlantUML component diagram from projected edges.
+
+    Args:
+        graph: List of projected edges.
+
+    Returns:
+        PlantUML diagram as a string.
+    """
+    components: set[str] = set()
+    lines: list[str] = ["@startuml"]
+
+    for edge in graph:
+        components.add(edge.source_label)
+        components.add(edge.target_label)
+
+    for component in sorted(components):
+        lines.append(f"  component [{component}]")
+
+    for edge in graph:
+        lines.append(f"  [{edge.source_label}] --> [{edge.target_label}]")
+
+    lines.append("@enduml")
+    return "\n".join(lines)

archunitpython/slices/uml/generate_rules.py

@@ -0,0 +1,71 @@
+"""PlantUML diagram parsing and rule generation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Rule:
+    """An allowed dependency relationship between two components."""
+
+    source: str
+    target: str
+
+
+def generate_rule(puml_content: str) -> tuple[list[Rule], list[str]]:
+    """Parse a PlantUML diagram and extract component rules.
+
+    Supports component diagrams with:
+    - component [Name] declarations
+    - [Source] --> [Target] relationships
+    - package grouping (names extracted from components inside)
+
+    Args:
+        puml_content: PlantUML diagram content as a string.
+
+    Returns:
+        Tuple of (rules, contained_nodes):
+        - rules: list of allowed dependency relationships
+        - contained_nodes: list of all declared component names
+    """
+    rules: list[Rule] = []
+    contained_nodes: list[str] = []
+
+    lines = puml_content.strip().splitlines()
+
+    for line in lines:
+        stripped = line.strip()
+
+        # Skip empty lines, comments, @startuml/@enduml
+        if not stripped or stripped.startswith("@") or stripped.startswith("'"):
+            continue
+
+        # Match component declarations: component [Name] or component [Name] #Color
+        comp_match = re.match(
+            r"component\s+\[([^\]]+)\]", stripped
+        )
+        if comp_match:
+            name = comp_match.group(1).strip()
+            if name not in contained_nodes:
+                contained_nodes.append(name)
+            continue
+
+        # Match relationships: [Source] --> [Target] or [Source] -> [Target]
+        rel_match = re.match(
+            r"\[([^\]]+)\]\s*-+>\s*\[([^\]]+)\]", stripped
+        )
+        if rel_match:
+            source = rel_match.group(1).strip()
+            target = rel_match.group(2).strip()
+            rules.append(Rule(source=source, target=target))
+
+            # Ensure both nodes are in contained_nodes
+            if source not in contained_nodes:
+                contained_nodes.append(source)
+            if target not in contained_nodes:
+                contained_nodes.append(target)
+            continue
+
+    return rules, contained_nodes

archunitpython/testing/__init__.py

@@ -0,0 +1,3 @@
+from archunitpython.testing.assertion import assert_passes, format_violations
+
+__all__ = ["assert_passes", "format_violations"]

archunitpython/testing/assertion.py

@@ -0,0 +1,47 @@
+"""Testing assertion helpers for architecture rules."""
+
+from __future__ import annotations
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
+from archunitpython.testing.common.violation_factory import ViolationFactory
+
+
+def format_violations(violations: list[Violation]) -> str:
+    """Format violations into a human-readable string.
+
+    Args:
+        violations: List of violations to format.
+
+    Returns:
+        Formatted string describing all violations.
+    """
+    if not violations:
+        return "No violations found."
+
+    lines = [f"Found {len(violations)} architecture violation(s):", ""]
+    for i, violation in enumerate(violations, 1):
+        tv = ViolationFactory.from_violation(violation)
+        lines.append(f"  {i}. {tv.message}")
+        lines.append(f"     {tv.details}")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def assert_passes(
+    checkable: Checkable,
+    options: CheckOptions | None = None,
+) -> None:
+    """Assert that an architecture rule passes (no violations).
+
+    Args:
+        checkable: Any object with a check() method (implements Checkable).
+        options: Optional check options.
+
+    Raises:
+        AssertionError: If the rule has violations.
+    """
+    violations = checkable.check(options)
+    if violations:
+        raise AssertionError(format_violations(violations))

archunitpython/testing/common/__init__.py

@@ -0,0 +1,4 @@
+from archunitpython.testing.common.color_utils import ColorUtils
+from archunitpython.testing.common.violation_factory import TestViolation, ViolationFactory
+
+__all__ = ["ColorUtils", "TestViolation", "ViolationFactory"]

archunitpython/testing/common/color_utils.py

@@ -0,0 +1,57 @@
+"""Terminal color utilities for formatted output."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+def _supports_color() -> bool:
+    """Check if the terminal supports ANSI colors."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if not hasattr(sys.stdout, "isatty"):
+        return False
+    return sys.stdout.isatty()
+
+
+def _wrap(code: str, text: str) -> str:
+    if not _supports_color():
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+
+class ColorUtils:
+    """ANSI color utilities for terminal output."""
+
+    @staticmethod
+    def red(text: str) -> str:
+        return _wrap("31", text)
+
+    @staticmethod
+    def green(text: str) -> str:
+        return _wrap("32", text)
+
+    @staticmethod
+    def yellow(text: str) -> str:
+        return _wrap("33", text)
+
+    @staticmethod
+    def blue(text: str) -> str:
+        return _wrap("34", text)
+
+    @staticmethod
+    def magenta(text: str) -> str:
+        return _wrap("35", text)
+
+    @staticmethod
+    def cyan(text: str) -> str:
+        return _wrap("36", text)
+
+    @staticmethod
+    def bold(text: str) -> str:
+        return _wrap("1", text)
+
+    @staticmethod
+    def dim(text: str) -> str:
+        return _wrap("2", text)