archunitpython 1.0.0__py3-none-any.whl

archunitpython/files/fluentapi/files.py

@@ -0,0 +1,403 @@
+"""Fluent API builder chain for file-level architecture rules.
+
+Usage:
+    project_files('src/')
+        .in_folder('**/services/**')
+        .should()
+        .have_no_cycles()
+        .check()
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from archunitpython.common.assertion.violation import EmptyTestViolation, Violation
+from archunitpython.common.extraction.extract_graph import extract_graph
+from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.pattern_matching import matches_all_patterns
+from archunitpython.common.projection.edge_projections import per_internal_edge
+from archunitpython.common.projection.project_cycles import project_cycles
+from archunitpython.common.projection.project_edges import project_edges
+from archunitpython.common.projection.project_nodes import project_to_nodes
+from archunitpython.common.projection.types import ProjectedNode
+from archunitpython.common.regex_factory import RegexFactory
+from archunitpython.common.types import Filter, Pattern
+from archunitpython.files.assertion.custom_file_logic import (
+    CustomFileCondition,
+    gather_custom_file_violations,
+)
+from archunitpython.files.assertion.cycle_free import gather_cycle_violations
+from archunitpython.files.assertion.depend_on_files import gather_depend_on_file_violations
+from archunitpython.files.assertion.matching_files import gather_regex_matching_violations
+
+
+def project_files(project_path: str | None = None) -> "FileConditionBuilder":
+    """Entry point for file-level architecture rules.
+
+    Args:
+        project_path: Root directory of the project to analyze.
+            Defaults to current working directory.
+    """
+    return FileConditionBuilder(project_path)
+
+
+# Alias
+files = project_files
+
+
+class FileConditionBuilder:
+    """Initial builder for file rules - select files to apply rules to."""
+
+    def __init__(self, project_path: str | None = None) -> None:
+        self._project_path = project_path
+        self._filters: list[Filter] = []
+
+    def with_name(self, name: Pattern) -> "FilesShouldCondition":
+        """Filter files by filename pattern."""
+        self._filters.append(RegexFactory.filename_matcher(name))
+        return FilesShouldCondition(self._project_path, list(self._filters))
+
+    def in_folder(self, folder: Pattern) -> "FilesShouldCondition":
+        """Filter files by folder pattern."""
+        self._filters.append(RegexFactory.folder_matcher(folder))
+        return FilesShouldCondition(self._project_path, list(self._filters))
+
+    def in_path(self, path: Pattern) -> "FilesShouldCondition":
+        """Filter files by full path pattern."""
+        self._filters.append(RegexFactory.path_matcher(path))
+        return FilesShouldCondition(self._project_path, list(self._filters))
+
+    def should(self) -> "PositiveMatchPatternFileConditionBuilder":
+        """Begin positive assertion (files SHOULD ...)."""
+        return PositiveMatchPatternFileConditionBuilder(
+            self._project_path, list(self._filters)
+        )
+
+    def should_not(self) -> "NegatedMatchPatternFileConditionBuilder":
+        """Begin negative assertion (files SHOULD NOT ...)."""
+        return NegatedMatchPatternFileConditionBuilder(
+            self._project_path, list(self._filters)
+        )
+
+
+class FilesShouldCondition:
+    """Intermediate builder that allows adding more filters or moving to assertions."""
+
+    def __init__(self, project_path: str | None, filters: list[Filter]) -> None:
+        self._project_path = project_path
+        self._filters = filters
+
+    def with_name(self, name: Pattern) -> "FilesShouldCondition":
+        """Add a filename pattern filter."""
+        self._filters.append(RegexFactory.filename_matcher(name))
+        return self
+
+    def in_folder(self, folder: Pattern) -> "FilesShouldCondition":
+        """Add a folder pattern filter."""
+        self._filters.append(RegexFactory.folder_matcher(folder))
+        return self
+
+    def in_path(self, path: Pattern) -> "FilesShouldCondition":
+        """Add a full path pattern filter."""
+        self._filters.append(RegexFactory.path_matcher(path))
+        return self
+
+    def should(self) -> "PositiveMatchPatternFileConditionBuilder":
+        """Begin positive assertion (files SHOULD ...)."""
+        return PositiveMatchPatternFileConditionBuilder(
+            self._project_path, list(self._filters)
+        )
+
+    def should_not(self) -> "NegatedMatchPatternFileConditionBuilder":
+        """Begin negative assertion (files SHOULD NOT ...)."""
+        return NegatedMatchPatternFileConditionBuilder(
+            self._project_path, list(self._filters)
+        )
+
+
+class PositiveMatchPatternFileConditionBuilder:
+    """Positive assertion builder - files SHOULD have certain properties."""
+
+    def __init__(self, project_path: str | None, filters: list[Filter]) -> None:
+        self._project_path = project_path
+        self._filters = filters
+
+    def have_no_cycles(self) -> "CycleFreeFileCondition":
+        """Assert that files have no circular dependencies."""
+        return CycleFreeFileCondition(self._project_path, self._filters)
+
+    def depend_on_files(self) -> "DependOnFileConditionBuilder":
+        """Begin dependency assertion - files SHOULD depend on ..."""
+        return DependOnFileConditionBuilder(
+            self._project_path, self._filters, is_negated=False
+        )
+
+    def be_in_folder(self, folder: Pattern) -> "MatchPatternFileCondition":
+        """Assert that files are in a certain folder."""
+        return MatchPatternFileCondition(
+            self._project_path,
+            self._filters,
+            [RegexFactory.folder_matcher(folder)],
+            is_negated=False,
+        )
+
+    def have_name(self, name: Pattern) -> "MatchPatternFileCondition":
+        """Assert that files match a name pattern."""
+        return MatchPatternFileCondition(
+            self._project_path,
+            self._filters,
+            [RegexFactory.filename_matcher(name)],
+            is_negated=False,
+        )
+
+    def be_in_path(self, path: Pattern) -> "MatchPatternFileCondition":
+        """Assert that files match a path pattern."""
+        return MatchPatternFileCondition(
+            self._project_path,
+            self._filters,
+            [RegexFactory.path_matcher(path)],
+            is_negated=False,
+        )
+
+    def adhere_to(
+        self, condition: CustomFileCondition, message: str
+    ) -> "CustomFileCheckableCondition":
+        """Assert that files satisfy a custom condition."""
+        return CustomFileCheckableCondition(
+            self._project_path, self._filters, condition, message, is_negated=False
+        )
+
+
+class NegatedMatchPatternFileConditionBuilder:
+    """Negative assertion builder - files SHOULD NOT have certain properties."""
+
+    def __init__(self, project_path: str | None, filters: list[Filter]) -> None:
+        self._project_path = project_path
+        self._filters = filters
+
+    def depend_on_files(self) -> "DependOnFileConditionBuilder":
+        """Begin dependency assertion - files SHOULD NOT depend on ..."""
+        return DependOnFileConditionBuilder(
+            self._project_path, self._filters, is_negated=True
+        )
+
+    def be_in_folder(self, folder: Pattern) -> "MatchPatternFileCondition":
+        """Assert that files are NOT in a certain folder."""
+        return MatchPatternFileCondition(
+            self._project_path,
+            self._filters,
+            [RegexFactory.folder_matcher(folder)],
+            is_negated=True,
+        )
+
+    def have_name(self, name: Pattern) -> "MatchPatternFileCondition":
+        """Assert that files do NOT match a name pattern."""
+        return MatchPatternFileCondition(
+            self._project_path,
+            self._filters,
+            [RegexFactory.filename_matcher(name)],
+            is_negated=True,
+        )
+
+    def be_in_path(self, path: Pattern) -> "MatchPatternFileCondition":
+        """Assert that files do NOT match a path pattern."""
+        return MatchPatternFileCondition(
+            self._project_path,
+            self._filters,
+            [RegexFactory.path_matcher(path)],
+            is_negated=True,
+        )
+
+    def adhere_to(
+        self, condition: CustomFileCondition, message: str
+    ) -> "CustomFileCheckableCondition":
+        """Assert that files do NOT satisfy a custom condition."""
+        return CustomFileCheckableCondition(
+            self._project_path, self._filters, condition, message, is_negated=True
+        )
+
+
+class DependOnFileConditionBuilder:
+    """Configure dependency target patterns."""
+
+    def __init__(
+        self, project_path: str | None, filters: list[Filter], is_negated: bool
+    ) -> None:
+        self._project_path = project_path
+        self._filters = filters
+        self._is_negated = is_negated
+        self._object_filters: list[Filter] = []
+
+    def with_name(self, name: Pattern) -> "DependOnFileCondition":
+        """Target files matching a name pattern."""
+        self._object_filters.append(RegexFactory.filename_matcher(name))
+        return DependOnFileCondition(
+            self._project_path,
+            self._filters,
+            list(self._object_filters),
+            self._is_negated,
+        )
+
+    def in_folder(self, folder: Pattern) -> "DependOnFileCondition":
+        """Target files in a folder pattern."""
+        self._object_filters.append(RegexFactory.folder_matcher(folder))
+        return DependOnFileCondition(
+            self._project_path,
+            self._filters,
+            list(self._object_filters),
+            self._is_negated,
+        )
+
+    def in_path(self, path: Pattern) -> "DependOnFileCondition":
+        """Target files matching a path pattern."""
+        self._object_filters.append(RegexFactory.path_matcher(path))
+        return DependOnFileCondition(
+            self._project_path,
+            self._filters,
+            list(self._object_filters),
+            self._is_negated,
+        )
+
+
+def _get_filtered_nodes(
+    project_path: str | None,
+    filters: list[Filter],
+    options: CheckOptions | None,
+) -> list[ProjectedNode]:
+    """Extract graph and get nodes matching filters."""
+    graph = extract_graph(project_path, options=options)
+    nodes = project_to_nodes(graph)
+    if not filters:
+        return nodes
+    return [n for n in nodes if matches_all_patterns(n.label, filters)]
+
+
+def _check_empty_test(
+    filtered_items: Sequence[object],
+    filters: list[Filter],
+    is_negated: bool,
+    options: CheckOptions | None,
+) -> list[Violation] | None:
+    """Check for empty test condition."""
+    if not filtered_items and not (options and options.allow_empty_tests):
+        return [
+            EmptyTestViolation(
+                filters=filters,
+                message="No files found matching the specified patterns",
+                is_negated=is_negated,
+            )
+        ]
+    return None
+
+
+class CycleFreeFileCondition:
+    """Checkable that verifies no cycles exist among filtered files."""
+
+    def __init__(self, project_path: str | None, filters: list[Filter]) -> None:
+        self._project_path = project_path
+        self._filters = filters
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        graph = extract_graph(self._project_path, options=options)
+        edges = project_edges(graph, per_internal_edge())
+
+        # Filter edges to only those involving our filtered files
+        if self._filters:
+            edges = [
+                e
+                for e in edges
+                if matches_all_patterns(e.source_label, self._filters)
+                and matches_all_patterns(e.target_label, self._filters)
+            ]
+
+        empty = _check_empty_test(edges, self._filters, False, options)
+        if empty is not None:
+            return empty
+
+        cycles = project_cycles(edges)
+        return gather_cycle_violations(cycles)
+
+
+class DependOnFileCondition:
+    """Checkable that verifies file dependency rules."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        subject_filters: list[Filter],
+        object_filters: list[Filter],
+        is_negated: bool,
+    ) -> None:
+        self._project_path = project_path
+        self._subject_filters = subject_filters
+        self._object_filters = object_filters
+        self._is_negated = is_negated
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        graph = extract_graph(self._project_path, options=options)
+        edges = project_edges(graph, per_internal_edge())
+
+        return gather_depend_on_file_violations(
+            edges,
+            self._subject_filters,
+            self._object_filters,
+            self._is_negated,
+        )
+
+
+class MatchPatternFileCondition:
+    """Checkable that verifies files match/don't match patterns."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        pre_filters: list[Filter],
+        check_filters: list[Filter],
+        is_negated: bool,
+    ) -> None:
+        self._project_path = project_path
+        self._pre_filters = pre_filters
+        self._check_filters = check_filters
+        self._is_negated = is_negated
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        nodes = _get_filtered_nodes(self._project_path, self._pre_filters, options)
+
+        empty = _check_empty_test(nodes, self._pre_filters, self._is_negated, options)
+        if empty is not None:
+            return empty
+
+        return gather_regex_matching_violations(
+            nodes, self._check_filters, self._is_negated
+        )
+
+
+class CustomFileCheckableCondition:
+    """Checkable that evaluates a custom condition on files."""
+
+    def __init__(
+        self,
+        project_path: str | None,
+        filters: list[Filter],
+        condition: CustomFileCondition,
+        message: str,
+        is_negated: bool,
+    ) -> None:
+        self._project_path = project_path
+        self._filters = filters
+        self._condition = condition
+        self._message = message
+        self._is_negated = is_negated
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        graph = extract_graph(self._project_path, options=options)
+        nodes = project_to_nodes(graph)
+
+        return gather_custom_file_violations(
+            nodes,
+            self._condition,
+            self._message,
+            self._is_negated,
+            self._filters,
+        )

archunitpython/metrics/__init__.py

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

archunitpython/metrics/assertion/metric_thresholds.py

@@ -0,0 +1,51 @@
+"""Metric threshold violations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.metrics.common.types import MetricComparison
+
+
+@dataclass
+class MetricViolation(Violation):
+    """A class metric that exceeds its threshold."""
+
+    class_name: str
+    file_path: str
+    metric_name: str
+    metric_value: float
+    threshold: float
+    comparison: MetricComparison
+
+
+@dataclass
+class FileCountViolation(Violation):
+    """A file-level metric that exceeds its threshold."""
+
+    file_path: str
+    metric_name: str
+    metric_value: float
+    threshold: float
+    comparison: MetricComparison
+
+
+def check_threshold(
+    value: float, threshold: float, comparison: MetricComparison
+) -> bool:
+    """Check if a value violates a threshold.
+
+    Returns True if the value is a VIOLATION.
+    """
+    if comparison == "below":
+        return value >= threshold
+    elif comparison == "above":
+        return value <= threshold
+    elif comparison == "equal":
+        return abs(value - threshold) > 1e-9
+    elif comparison == "below_equal":
+        return value > threshold
+    elif comparison == "above_equal":
+        return value < threshold
+    return False

archunitpython/metrics/calculation/count.py

@@ -0,0 +1,148 @@
+"""Count metrics: method count, field count, lines of code, etc."""
+
+from __future__ import annotations
+
+import ast
+
+from archunitpython.metrics.common.types import ClassInfo
+
+
+class MethodCountMetric:
+    """Number of methods in a class."""
+
+    name = "MethodCount"
+    description = "Number of methods in a class"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        return float(len(class_info.methods))
+
+
+class FieldCountMetric:
+    """Number of fields in a class."""
+
+    name = "FieldCount"
+    description = "Number of fields in a class"
+
+    def calculate(self, class_info: ClassInfo) -> float:
+        return float(len(class_info.fields))
+
+
+class LinesOfCodeMetric:
+    """Number of non-blank, non-comment lines in a file."""
+
+    name = "LinesOfCode"
+    description = "Number of non-blank, non-comment lines"
+
+    def calculate_from_file(self, file_path: str) -> float:
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                lines = f.readlines()
+        except (OSError, IOError):
+            return 0.0
+
+        count = 0
+        for line in lines:
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#"):
+                count += 1
+        return float(count)
+
+
+class StatementCountMetric:
+    """Number of AST statements in a file."""
+
+    name = "StatementCount"
+    description = "Number of statements in a file"
+
+    def calculate_from_file(self, file_path: str) -> float:
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                source = f.read()
+        except (OSError, IOError):
+            return 0.0
+
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return 0.0
+
+        count = 0
+        for node in ast.walk(tree):
+            if isinstance(node, ast.stmt):
+                count += 1
+        return float(count)
+
+
+class ImportCountMetric:
+    """Number of import statements in a file."""
+
+    name = "ImportCount"
+    description = "Number of import statements in a file"
+
+    def calculate_from_file(self, file_path: str) -> float:
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                source = f.read()
+        except (OSError, IOError):
+            return 0.0
+
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return 0.0
+
+        count = 0
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.Import, ast.ImportFrom)):
+                count += 1
+        return float(count)
+
+
+class ClassCountMetric:
+    """Number of class definitions in a file."""
+
+    name = "ClassCount"
+    description = "Number of class definitions in a file"
+
+    def calculate_from_file(self, file_path: str) -> float:
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                source = f.read()
+        except (OSError, IOError):
+            return 0.0
+
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return 0.0
+
+        count = 0
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ClassDef):
+                count += 1
+        return float(count)
+
+
+class FunctionCountMetric:
+    """Number of top-level function definitions in a file."""
+
+    name = "FunctionCount"
+    description = "Number of top-level function definitions in a file"
+
+    def calculate_from_file(self, file_path: str) -> float:
+        try:
+            with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+                source = f.read()
+        except (OSError, IOError):
+            return 0.0
+
+        try:
+            tree = ast.parse(source)
+        except SyntaxError:
+            return 0.0
+
+        count = 0
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                count += 1
+        return float(count)