archunitpython 1.0.0__py3-none-any.whl

archunitpython/common/util/declaration_detector.py

@@ -0,0 +1,115 @@
+"""Utility functions for detecting Python declarations in AST."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+
+
+@dataclass
+class DeclarationCounts:
+    """Counts of different declaration types in a Python file."""
+
+    total: int = 0
+    protocols: int = 0
+    abstract_classes: int = 0
+    abstract_methods: int = 0
+    concrete_classes: int = 0
+    functions: int = 0
+    variables: int = 0
+
+
+def is_abstract_class(node: ast.ClassDef) -> bool:
+    """Check if a class inherits from ABC or uses ABCMeta."""
+    for base in node.bases:
+        name = _get_name(base)
+        if name in ("ABC", "ABCMeta"):
+            return True
+    for keyword in node.keywords:
+        if keyword.arg == "metaclass":
+            name = _get_name(keyword.value)
+            if name == "ABCMeta":
+                return True
+    # Also detect by @abstractmethod presence
+    for item in node.body:
+        if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            for dec in item.decorator_list:
+                if _get_name(dec) == "abstractmethod":
+                    return True
+    return False
+
+
+def is_protocol_class(node: ast.ClassDef) -> bool:
+    """Check if a class inherits from typing.Protocol."""
+    for base in node.bases:
+        name = _get_name(base)
+        if name == "Protocol":
+            return True
+    return False
+
+
+def is_abstract_method(node: ast.FunctionDef | ast.AsyncFunctionDef) -> bool:
+    """Check if a method has the @abstractmethod decorator."""
+    for dec in node.decorator_list:
+        if _get_name(dec) == "abstractmethod":
+            return True
+    return False
+
+
+def count_declarations(source: str) -> DeclarationCounts:
+    """Count all declaration types in a Python source string.
+
+    Args:
+        source: Python source code as a string.
+
+    Returns:
+        DeclarationCounts with totals for each declaration type.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return DeclarationCounts()
+
+    counts = DeclarationCounts()
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            counts.total += 1
+            if is_protocol_class(node):
+                counts.protocols += 1
+            elif is_abstract_class(node):
+                counts.abstract_classes += 1
+            else:
+                counts.concrete_classes += 1
+
+            # Count abstract methods
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    if is_abstract_method(item):
+                        counts.abstract_methods += 1
+
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            # Only count module-level functions
+            if _is_module_level(node, tree):
+                counts.total += 1
+                counts.functions += 1
+
+        elif isinstance(node, ast.Assign) and _is_module_level(node, tree):
+            counts.total += 1
+            counts.variables += 1
+
+    return counts
+
+
+def _is_module_level(node: ast.AST, tree: ast.Module) -> bool:
+    """Check if a node is directly in the module body."""
+    return node in tree.body
+
+
+def _get_name(node: ast.expr) -> str:
+    """Extract a name from an AST node."""
+    if isinstance(node, ast.Name):
+        return node.id
+    if isinstance(node, ast.Attribute):
+        return node.attr
+    return ""

archunitpython/common/util/logger.py

@@ -0,0 +1,100 @@
+"""Structured logging for architecture checks."""
+
+from __future__ import annotations
+
+import logging
+import os
+from datetime import datetime
+from pathlib import Path
+
+from archunitpython.common.logging.types import LoggingOptions
+
+_LOG_LEVELS = {
+    "debug": logging.DEBUG,
+    "info": logging.INFO,
+    "warn": logging.WARNING,
+    "error": logging.ERROR,
+}
+
+
+class CheckLogger:
+    """Logger specialized for architecture check operations."""
+
+    def __init__(self) -> None:
+        self._logger = logging.getLogger("archunitpython")
+        self._file_handler: logging.FileHandler | None = None
+        self._logger.setLevel(logging.DEBUG)
+
+    def _should_log(self, options: LoggingOptions | None) -> bool:
+        if options is None:
+            return False
+        return options.enabled
+
+    def _ensure_file_handler(self, options: LoggingOptions) -> None:
+        if not options.log_file:
+            return
+        if self._file_handler is not None:
+            return
+
+        log_dir = Path(os.getcwd()) / "logs"
+        log_dir.mkdir(exist_ok=True)
+
+        timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+        log_path = log_dir / f"archunit-{timestamp}.log"
+
+        mode = "a" if options.append_to_log_file else "w"
+        self._file_handler = logging.FileHandler(str(log_path), mode=mode)
+        self._file_handler.setFormatter(
+            logging.Formatter("[%(levelname)s] %(message)s")
+        )
+        self._logger.addHandler(self._file_handler)
+
+    def _log(self, level: str, options: LoggingOptions | None, message: str) -> None:
+        if not self._should_log(options):
+            return
+        assert options is not None
+        log_level = _LOG_LEVELS.get(options.level, logging.INFO)
+        msg_level = _LOG_LEVELS.get(level, logging.INFO)
+        if msg_level < log_level:
+            return
+        self._ensure_file_handler(options)
+        self._logger.log(msg_level, message)
+
+    def debug(self, options: LoggingOptions | None, message: str) -> None:
+        self._log("debug", options, message)
+
+    def info(self, options: LoggingOptions | None, message: str) -> None:
+        self._log("info", options, message)
+
+    def warn(self, options: LoggingOptions | None, message: str) -> None:
+        self._log("warn", options, message)
+
+    def error(self, options: LoggingOptions | None, message: str) -> None:
+        self._log("error", options, message)
+
+    def start_check(self, rule_name: str, options: LoggingOptions | None) -> None:
+        self.info(options, f"Starting check: {rule_name}")
+
+    def end_check(
+        self, rule_name: str, violation_count: int, options: LoggingOptions | None
+    ) -> None:
+        self.info(
+            options,
+            f"Finished check: {rule_name} - {violation_count} violation(s)",
+        )
+
+    def log_violation(self, violation: object, options: LoggingOptions | None) -> None:
+        self.warn(options, f"Violation: {violation}")
+
+    def log_progress(self, message: str, options: LoggingOptions | None) -> None:
+        self.info(options, message)
+
+    def close(self) -> None:
+        """Remove file handler if present."""
+        if self._file_handler is not None:
+            self._logger.removeHandler(self._file_handler)
+            self._file_handler.close()
+            self._file_handler = None
+
+
+shared_logger = CheckLogger()

archunitpython/files/__init__.py

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

archunitpython/files/assertion/__init__.py

@@ -0,0 +1,28 @@
+from archunitpython.files.assertion.custom_file_logic import (
+    CustomFileCondition,
+    CustomFileViolation,
+    FileInfo,
+    gather_custom_file_violations,
+)
+from archunitpython.files.assertion.cycle_free import ViolatingCycle, gather_cycle_violations
+from archunitpython.files.assertion.depend_on_files import (
+    ViolatingFileDependency,
+    gather_depend_on_file_violations,
+)
+from archunitpython.files.assertion.matching_files import (
+    ViolatingNode,
+    gather_regex_matching_violations,
+)
+
+__all__ = [
+    "CustomFileCondition",
+    "CustomFileViolation",
+    "FileInfo",
+    "ViolatingCycle",
+    "ViolatingFileDependency",
+    "ViolatingNode",
+    "gather_custom_file_violations",
+    "gather_cycle_violations",
+    "gather_depend_on_file_violations",
+    "gather_regex_matching_violations",
+]

archunitpython/files/assertion/custom_file_logic.py

@@ -0,0 +1,107 @@
+"""Custom file condition logic and FileInfo type."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Callable
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.pattern_matching import matches_pattern
+from archunitpython.common.projection.types import ProjectedNode
+from archunitpython.common.types import Filter
+
+
+@dataclass(frozen=True)
+class FileInfo:
+    """Information about a file, provided to custom conditions."""
+
+    path: str
+    name: str  # filename without extension
+    extension: str
+    directory: str
+    content: str
+    lines_of_code: int
+
+
+CustomFileCondition = Callable[[FileInfo], bool]
+
+
+@dataclass
+class CustomFileViolation(Violation):
+    """A file that violates a custom condition."""
+
+    message: str
+    file_info: FileInfo
+
+
+def _build_file_info(file_path: str) -> FileInfo:
+    """Build a FileInfo from a file path."""
+    basename = os.path.basename(file_path)
+    name, ext = os.path.splitext(basename)
+    directory = os.path.dirname(file_path)
+
+    try:
+        with open(file_path, "r", encoding="utf-8", errors="replace") as f:
+            content = f.read()
+    except (OSError, IOError):
+        content = ""
+
+    lines = [line for line in content.splitlines() if line.strip()]
+
+    return FileInfo(
+        path=file_path,
+        name=name,
+        extension=ext,
+        directory=directory,
+        content=content,
+        lines_of_code=len(lines),
+    )
+
+
+def gather_custom_file_violations(
+    nodes: list[ProjectedNode],
+    condition: CustomFileCondition,
+    message: str,
+    is_negated: bool,
+    pre_filters: list[Filter],
+) -> list[Violation]:
+    """Evaluate a custom condition on files matching pre_filters.
+
+    Args:
+        nodes: All projected nodes.
+        condition: Custom function that returns True if the file passes.
+        message: Message to include in violation.
+        is_negated: If False (should adhere), violation when condition returns False.
+                    If True (shouldNot adhere), violation when condition returns True.
+        pre_filters: Filters to apply before checking the condition.
+
+    Returns:
+        List of CustomFileViolation violations.
+    """
+    violations: list[Violation] = []
+
+    for node in nodes:
+        # Check if node matches all pre-filters
+        if pre_filters and not all(
+            matches_pattern(node.label, f) for f in pre_filters
+        ):
+            continue
+
+        file_info = _build_file_info(node.label)
+        result = condition(file_info)
+
+        if is_negated:
+            # shouldNot: violation if condition IS True
+            if result:
+                violations.append(
+                    CustomFileViolation(message=message, file_info=file_info)
+                )
+        else:
+            # should: violation if condition is NOT True
+            if not result:
+                violations.append(
+                    CustomFileViolation(message=message, file_info=file_info)
+                )
+
+    return violations

archunitpython/files/assertion/cycle_free.py

@@ -0,0 +1,29 @@
+"""Violation gathering for cycle-free rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.projection.types import ProjectedEdge
+
+
+@dataclass
+class ViolatingCycle(Violation):
+    """A circular dependency detected between files."""
+
+    cycle: list[ProjectedEdge]
+
+
+def gather_cycle_violations(
+    cycles: list[list[ProjectedEdge]],
+) -> list[Violation]:
+    """Convert detected cycles into violations.
+
+    Args:
+        cycles: List of cycles, each being a list of edges forming the cycle.
+
+    Returns:
+        List of ViolatingCycle violations.
+    """
+    return [ViolatingCycle(cycle=cycle) for cycle in cycles]

archunitpython/files/assertion/depend_on_files.py

@@ -0,0 +1,67 @@
+"""Violation gathering for file dependency rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.pattern_matching import matches_pattern
+from archunitpython.common.projection.types import ProjectedEdge
+from archunitpython.common.types import Filter
+
+
+@dataclass
+class ViolatingFileDependency(Violation):
+    """A file dependency that violates a rule."""
+
+    dependency: ProjectedEdge
+    is_negated: bool = False
+
+
+def gather_depend_on_file_violations(
+    edges: list[ProjectedEdge],
+    subject_filters: list[Filter],
+    object_filters: list[Filter],
+    is_negated: bool,
+) -> list[Violation]:
+    """Check if files have/don't have certain dependencies.
+
+    Args:
+        edges: Projected dependency edges.
+        subject_filters: Patterns for the source files (subject of the rule).
+        object_filters: Patterns for the target files (dependency targets).
+        is_negated: If False (should), files matching subject MUST depend on
+                    files matching object.
+                    If True (shouldNot), files matching subject must NOT
+                    depend on files matching object.
+
+    Returns:
+        List of violations.
+    """
+    violations: list[Violation] = []
+
+    for edge in edges:
+        source_matches = all(
+            matches_pattern(edge.source_label, f) for f in subject_filters
+        )
+        if not source_matches:
+            continue
+
+        target_matches = all(
+            matches_pattern(edge.target_label, f) for f in object_filters
+        )
+
+        if is_negated:
+            # shouldNot: violation if dependency EXISTS
+            if target_matches:
+                violations.append(
+                    ViolatingFileDependency(dependency=edge, is_negated=True)
+                )
+        else:
+            # should: violation if dependency does NOT match
+            if not target_matches:
+                violations.append(
+                    ViolatingFileDependency(dependency=edge, is_negated=False)
+                )
+
+    return violations

archunitpython/files/assertion/matching_files.py

@@ -0,0 +1,64 @@
+"""Violation gathering for file pattern matching rules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.pattern_matching import matches_pattern
+from archunitpython.common.projection.types import ProjectedNode
+from archunitpython.common.types import Filter
+
+
+@dataclass
+class ViolatingNode(Violation):
+    """A file that violates a pattern matching rule."""
+
+    check_pattern: Filter
+    projected_node: ProjectedNode
+    is_negated: bool = False
+
+
+def gather_regex_matching_violations(
+    nodes: list[ProjectedNode],
+    check_filters: list[Filter],
+    is_negated: bool,
+) -> list[Violation]:
+    """Check if files match/don't match given patterns.
+
+    Args:
+        nodes: Files to check.
+        check_filters: Patterns to match against.
+        is_negated: If False (should), files MUST match all patterns.
+                    If True (shouldNot), files must NOT match any pattern.
+
+    Returns:
+        List of violations.
+    """
+    violations: list[Violation] = []
+
+    for node in nodes:
+        for filter_ in check_filters:
+            matched = matches_pattern(node.label, filter_)
+            if is_negated:
+                # shouldNot: violation if file DOES match
+                if matched:
+                    violations.append(
+                        ViolatingNode(
+                            check_pattern=filter_,
+                            projected_node=node,
+                            is_negated=True,
+                        )
+                    )
+            else:
+                # should: violation if file does NOT match
+                if not matched:
+                    violations.append(
+                        ViolatingNode(
+                            check_pattern=filter_,
+                            projected_node=node,
+                            is_negated=False,
+                        )
+                    )
+
+    return violations

archunitpython/files/fluentapi/__init__.py

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