archunitpython 1.6.0__py3-none-any.whl → 1.8.1__py3-none-any.whl

archunitpython/__init__.py

@@ -1,12 +1,13 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.6.0"
+__version__ = "1.8.1"
 
 # Files API
 # Common
 from archunitpython.common import (
     CheckOptions,
     EmptyTestViolation,
+    LoggingOptions,
     TechnicalError,
     UserError,
     Violation,
@@ -50,6 +51,7 @@ __all__ = [
     "Violation",
     "EmptyTestViolation",
     "CheckOptions",
+    "LoggingOptions",
     "TechnicalError",
     "UserError",
     "extract_graph",

archunitpython/common/extraction/extract_graph.py

@@ -5,10 +5,13 @@ from __future__ import annotations
 import ast
 import os
 import re
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 
 from archunitpython.common.extraction.graph import Edge, Graph, ImportKind
 from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.logging.inspection import debug, debug_enabled
+from archunitpython.common.pattern_matching import matches_all_patterns
+from archunitpython.common.types import Filter
 
 GraphCacheKey = tuple[str, tuple[str, ...], bool]
 
@@ -45,6 +48,7 @@ class _LocatedImport:
     line_number: int
     resolution_kind: ImportKind | None = None
     fallback_module_name: str | None = None
+    aliases: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -56,15 +60,28 @@ class _IgnoreDirective:
         if not self.modules:
             return True
         return any(
-            import_.module_name == module
-            or import_.module_name.startswith(f"{module}.")
+            import_.module_name == module or import_.module_name.startswith(f"{module}.")
             for module in self.modules
         )
 
 
+@dataclass
+class _ExtractionSession:
+    project_path: str
+    py_files: list[str]
+    normalized_py_file_set: set[str]
+    ignore_type_checking_imports: bool
+    edges_by_file: dict[str, list[Edge]] = field(default_factory=dict)
+    selected_files: dict[tuple[Filter, ...], list[str]] = field(default_factory=dict)
+
+
+_extraction_sessions: dict[GraphCacheKey, _ExtractionSession] = {}
+
+
 def clear_graph_cache(options: CheckOptions | None = None) -> None:
     """Clear the cached dependency graphs."""
     _graph_cache.clear()
+    _extraction_sessions.clear()
 
 
 def extract_graph(
@@ -96,21 +113,128 @@ def extract_graph(
     ignore_type_checking_imports = bool(options and options.ignore_type_checking_imports)
     cache_key = _build_cache_key(project_path, excludes, ignore_type_checking_imports)
 
+    debug(
+        "Extraction root: %s; excludes: %s; ignore type-only imports: %s",
+        project_path,
+        excludes,
+        ignore_type_checking_imports,
+    )
     if options and options.clear_cache:
+        debug("Clearing graph and extraction-session caches for %s", project_path)
         _graph_cache.pop(cache_key, None)
+        _extraction_sessions.pop(cache_key, None)
 
     if cache_key in _graph_cache:
+        debug("Graph cache hit: %d edges", len(_graph_cache[cache_key]))
+        _inspect_graph(_graph_cache[cache_key])
         return _graph_cache[cache_key]
+    debug("Graph cache miss")
+
+    session = _get_extraction_session(
+        cache_key, project_path, excludes, ignore_type_checking_imports
+    )
+    result = _extract_graph_from_files(session, session.py_files)
+    _inspect_graph(result)
+    _graph_cache[cache_key] = result
+    return result
+
+
+def extract_graph_for_sources(
+    project_path: str | None,
+    source_filters: list[Filter],
+    *,
+    options: CheckOptions | None = None,
+) -> Graph:
+    """Extract edges from files selected by a direct file-dependency rule.
 
-    result = _extract_graph_uncached(
+    All project files are inventoried to classify imported targets correctly.
+    Parsed edges are reused by later rules and full-graph checks in this process.
+    """
+    if not source_filters:
+        return extract_graph(project_path, options=options)
+
+    if project_path is None:
+        project_path = os.getcwd()
+    project_path = os.path.abspath(project_path)
+    excludes = _resolve_exclude_patterns(project_path, None)
+    ignore_type_checking_imports = bool(options and options.ignore_type_checking_imports)
+    cache_key = _build_cache_key(project_path, excludes, ignore_type_checking_imports)
+    debug(
+        "Extraction root: %s; excludes: %s; ignore type-only imports: %s",
         project_path,
         excludes,
-        ignore_type_checking_imports=ignore_type_checking_imports,
+        ignore_type_checking_imports,
     )
-    _graph_cache[cache_key] = result
+    if options and options.clear_cache:
+        debug("Clearing graph and extraction-session caches for %s", project_path)
+        _graph_cache.pop(cache_key, None)
+        _extraction_sessions.pop(cache_key, None)
+
+    session = _get_extraction_session(
+        cache_key, project_path, excludes, ignore_type_checking_imports
+    )
+    filter_key = tuple(source_filters)
+    if filter_key not in session.selected_files:
+        session.selected_files[filter_key] = [
+            path for path in session.py_files if matches_all_patterns(path, source_filters)
+        ]
+    selected_files = session.selected_files[filter_key]
+    if debug_enabled():
+        debug(
+            "Selected-source extraction: %d of %d files", len(selected_files), len(session.py_files)
+        )
+        if selected_files:
+            cached_files = sum(path in session.edges_by_file for path in selected_files)
+            if cached_files == len(selected_files):
+                cache_status = "hit"
+            elif cached_files:
+                cache_status = "partial hit"
+            else:
+                cache_status = "miss"
+            debug(
+                "Selected-source edge cache %s: %d/%d files cached",
+                cache_status,
+                cached_files,
+                len(selected_files),
+            )
+    result = _extract_graph_from_files(session, selected_files)
+    _inspect_graph(result)
     return result
 
 
+def _get_extraction_session(
+    cache_key: GraphCacheKey,
+    project_path: str,
+    excludes: list[str],
+    ignore_type_checking_imports: bool,
+) -> _ExtractionSession:
+    session = _extraction_sessions.get(cache_key)
+    if session is None:
+        py_files = _find_python_files(project_path, excludes)
+        session = _ExtractionSession(
+            project_path=project_path,
+            py_files=py_files,
+            normalized_py_file_set={_normalize(path) for path in py_files},
+            ignore_type_checking_imports=ignore_type_checking_imports,
+        )
+        _extraction_sessions[cache_key] = session
+    return session
+
+
+def _inspect_graph(graph: Graph) -> None:
+    if not debug_enabled():
+        return
+    debug("Extracted graph: %d edges (including self-edges)", len(graph))
+    for edge in graph:
+        debug(
+            "Dependency: %s -> %s; external=%s; kinds=%s",
+            edge.source,
+            edge.target,
+            edge.external,
+            edge.import_kinds,
+        )
+
+
 def _build_cache_key(
     project_path: str,
     exclude_patterns: list[str],
@@ -152,66 +276,59 @@ def _load_archignore_patterns(project_path: str) -> list[str]:
     return patterns
 
 
-def _extract_graph_uncached(
-    project_path: str,
-    exclude_patterns: list[str],
-    *,
-    ignore_type_checking_imports: bool = False,
-) -> Graph:
-    """Extract graph without caching."""
-    py_files = _find_python_files(project_path, exclude_patterns)
-
+def _extract_graph_from_files(session: _ExtractionSession, files: list[str]) -> Graph:
+    """Assemble a graph from cached or newly parsed file edges."""
     edges: list[Edge] = []
-    py_files_set = set(py_files)
-    normalized_py_file_set = {_normalize(f) for f in py_files_set}
-
-    for file_path in py_files:
-        # Add self-referencing edge (ensures the file appears as a node)
-        edges.append(
-            Edge(
-                source=_normalize(file_path),
-                target=_normalize(file_path),
-                external=False,
-            )
+    for file_path in files:
+        edges.extend(_extract_file_edges(session, file_path))
+    return _merge_edges(edges)
+
+
+def _extract_file_edges(session: _ExtractionSession, file_path: str) -> list[Edge]:
+    cached = session.edges_by_file.get(file_path)
+    if cached is not None:
+        return cached
+
+    debug("Processing file: %s", file_path)
+    source_label = _normalize(file_path)
+    edges = [
+        Edge(
+            source=source_label,
+            target=source_label,
+            external=False,
         )
+    ]
 
-        imports = _extract_located_imports(file_path)
-        for located_import in imports:
-            module_name = located_import.module_name
-            import_kind = located_import.import_kind
-            if (
-                ignore_type_checking_imports
-                and import_kind == ImportKind.TYPE_IMPORT
-            ):
-                continue
-            resolution_kind = located_import.resolution_kind or import_kind
-            resolved, is_external = _resolve_import(
-                module_name, file_path, project_path, resolution_kind
+    for located_import in _extract_located_imports(file_path):
+        if (
+            session.ignore_type_checking_imports
+            and located_import.import_kind == ImportKind.TYPE_IMPORT
+        ):
+            debug(
+                "Skipped type-only import: %s:%s -> %s",
+                file_path,
+                located_import.line_number,
+                located_import.module_name,
             )
-            if is_external and located_import.fallback_module_name is not None:
-                fallback, fallback_is_external = _resolve_import(
-                    located_import.fallback_module_name,
-                    file_path,
-                    project_path,
-                    resolution_kind,
-                )
-                if fallback and not fallback_is_external:
-                    resolved, is_external = fallback, False
-            if resolved and resolved != _normalize(file_path):
-                # Check if the resolved path is in our project
-                if not is_external and resolved not in normalized_py_file_set:
+            continue
+        for resolved, is_external in _resolve_import_targets(
+            located_import, file_path, session.project_path
+        ):
+            if resolved and resolved != source_label:
+                if not is_external and resolved not in session.normalized_py_file_set:
+                    debug("Skipped excluded dependency: %s -> %s", file_path, resolved)
                     continue
-
                 edges.append(
                     Edge(
-                        source=_normalize(file_path),
+                        source=source_label,
                         target=resolved,
                         external=is_external,
                         import_kinds=_edge_import_kinds(located_import),
                     )
                 )
 
-    return _merge_edges(edges)
+    session.edges_by_file[file_path] = edges
+    return edges
 
 
 def _normalize(path: str) -> str:
@@ -223,6 +340,9 @@ def _find_python_files(root: str, exclude: list[str]) -> list[str]:
     """Recursively find all .py files, excluding specified patterns."""
     py_files: list[str] = []
     root = os.path.abspath(root)
+    # Defaults can only match directory names, never a .py filename. Keep
+    # checking user patterns against files, including .archignore entries.
+    file_excludes = [pattern for pattern in exclude if pattern not in _DEFAULT_EXCLUDE]
     for dirpath, dirnames, filenames in os.walk(root):
         # Filter out excluded directories in-place
         dirnames[:] = [
@@ -233,10 +353,11 @@ def _find_python_files(root: str, exclude: list[str]) -> list[str]:
 
         for filename in filenames:
             full_path = os.path.join(dirpath, filename)
-            if filename.endswith(".py") and not _should_exclude_path(
-                full_path, root, exclude, is_dir=False
+            if filename.endswith(".py") and not (
+                file_excludes and _should_exclude_path(full_path, root, file_excludes, is_dir=False)
             ):
                 py_files.append(os.path.abspath(full_path))
+                debug("Discovered file: %s", full_path)
 
     return py_files
 
@@ -310,10 +431,11 @@ def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
 
     imports: list[_LocatedImport] = []
     ignore_directives = _find_ignore_directives(source)
-    type_checking_ranges = _find_type_checking_ranges(tree)
-    conditional_import_ranges = _find_conditional_import_ranges(tree)
+    nodes = list(ast.walk(tree))
+    type_checking_ranges = _find_type_checking_ranges(nodes)
+    conditional_import_ranges = _find_conditional_import_ranges(nodes)
 
-    for node in ast.walk(tree):
+    for node in nodes:
         if isinstance(node, ast.Import):
             syntax_kind = ImportKind.IMPORT
             kind = _classify_import(
@@ -323,9 +445,7 @@ def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
                 conditional_import_ranges,
             )
             for alias in node.names:
-                imports.append(
-                    _LocatedImport(alias.name, kind, node.lineno, syntax_kind)
-                )
+                imports.append(_LocatedImport(alias.name, kind, node.lineno, syntax_kind))
 
         elif isinstance(node, ast.ImportFrom):
             syntax_kind = (
@@ -339,17 +459,17 @@ def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
                 type_checking_ranges,
                 conditional_import_ranges,
             )
-            fallback_module_name = (
-                "." * node.level if node.level and node.module is None else None
-            )
+            fallback_module_name = "." * node.level if node.level and node.module is None else None
+            aliases = _module_aliases(node) if node.module else ()
             for module_name in _import_from_module_names(node):
                 imports.append(
                     _LocatedImport(
-                        module_name,
-                        kind,
-                        node.lineno,
-                        syntax_kind,
-                        fallback_module_name,
+                        module_name=module_name,
+                        import_kind=kind,
+                        line_number=node.lineno,
+                        resolution_kind=syntax_kind,
+                        fallback_module_name=fallback_module_name,
+                        aliases=aliases,
                     )
                 )
 
@@ -362,15 +482,9 @@ def _extract_located_imports(file_path: str) -> list[_LocatedImport]:
                 conditional_import_ranges,
             )
             for module_name in _extract_dynamic_import_names(node):
-                imports.append(
-                    _LocatedImport(module_name, kind, node.lineno, syntax_kind)
-                )
+                imports.append(_LocatedImport(module_name, kind, node.lineno, syntax_kind))
 
-    return [
-        import_
-        for import_ in imports
-        if not _is_ignored_import(import_, ignore_directives)
-    ]
+    return [import_ for import_ in imports if not _is_ignored_import(import_, ignore_directives)]
 
 
 def _find_ignore_directives(source: str) -> dict[int, _IgnoreDirective]:
@@ -429,6 +543,11 @@ def _extract_dynamic_import_names(node: ast.Call) -> list[str]:
     return []
 
 
+def _module_aliases(node: ast.ImportFrom) -> tuple[str, ...]:
+    """Return aliases that may refer to imported submodules."""
+    return tuple(alias.name for alias in node.names if alias.name != "*")
+
+
 def _import_from_module_names(node: ast.ImportFrom) -> tuple[str, ...]:
     """Return resolvable module names for a from-import statement."""
     dots = "." * (node.level or 0)
@@ -466,11 +585,11 @@ def _classify_import(
     return default_kind
 
 
-def _find_type_checking_ranges(tree: ast.Module) -> list[tuple[int, int]]:
+def _find_type_checking_ranges(nodes: list[ast.AST]) -> list[tuple[int, int]]:
     """Find line ranges of TYPE_CHECKING blocks."""
     ranges: list[tuple[int, int]] = []
 
-    for node in ast.walk(tree):
+    for node in nodes:
         if isinstance(node, ast.If):
             # Check for `if TYPE_CHECKING:` pattern
             test = node.test
@@ -491,11 +610,11 @@ def _find_type_checking_ranges(tree: ast.Module) -> list[tuple[int, int]]:
     return sorted(ranges, key=lambda ele: ele[0])
 
 
-def _find_conditional_import_ranges(tree: ast.Module) -> list[tuple[int, int]]:
+def _find_conditional_import_ranges(nodes: list[ast.AST]) -> list[tuple[int, int]]:
     """Find try/except ImportError ranges that contain optional imports."""
     ranges: list[tuple[int, int]] = []
 
-    for node in ast.walk(tree):
+    for node in nodes:
         if not isinstance(node, ast.Try):
             continue
         if not any(_handles_import_error(handler.type) for handler in node.handlers):
@@ -558,14 +677,10 @@ def _resolve_import(
     Returns (resolved_path, is_external).
     The path is normalized with forward slashes.
     """
-    if (
-        kind
-        in (
-            ImportKind.RELATIVE_IMPORT,
-            ImportKind.TYPE_IMPORT,
-        )
-        and import_name.startswith(".")
-    ):
+    if kind in (
+        ImportKind.RELATIVE_IMPORT,
+        ImportKind.TYPE_IMPORT,
+    ) and import_name.startswith("."):
         # Relative import
         return _resolve_relative_import(import_name, source_file, project_root)
 
@@ -573,6 +688,58 @@ def _resolve_import(
     return _resolve_absolute_import(import_name, project_root)
 
 
+def _resolve_import_targets(
+    import_: _LocatedImport,
+    source_file: str,
+    project_root: str,
+) -> list[tuple[str, bool]]:
+    """Resolve an import, including namespace-package submodule aliases."""
+    resolution_kind = import_.resolution_kind or import_.import_kind
+    resolved, is_external = _resolve_import(
+        import_.module_name,
+        source_file,
+        project_root,
+        resolution_kind,
+    )
+    if is_external and import_.fallback_module_name is not None:
+        fallback, fallback_is_external = _resolve_import(
+            import_.fallback_module_name,
+            source_file,
+            project_root,
+            resolution_kind,
+        )
+        if fallback and not fallback_is_external:
+            resolved, is_external = fallback, False
+    if not is_external or not import_.aliases:
+        return [(resolved, is_external)]
+
+    alias_targets: list[tuple[str, bool]] = []
+    found_internal_alias = False
+    for alias in import_.aliases:
+        alias_module = _join_import_alias(import_.module_name, alias)
+        alias_resolved, alias_is_external = _resolve_import(
+            alias_module,
+            source_file,
+            project_root,
+            resolution_kind,
+        )
+        alias_targets.append((alias_resolved, alias_is_external))
+        found_internal_alias = found_internal_alias or not alias_is_external
+
+    if found_internal_alias:
+        return alias_targets
+    return [(resolved, is_external)]
+
+
+def _join_import_alias(module_name: str, alias: str) -> str:
+    """Join a from-import module name with a candidate submodule alias."""
+    if not module_name:
+        return alias
+    if set(module_name) == {"."}:
+        return f"{module_name}{alias}"
+    return f"{module_name}.{alias}"
+
+
 def _resolve_relative_import(
     import_name: str,
     source_file: str,

archunitpython/common/fluentapi/inspection.py

@@ -0,0 +1,79 @@
+"""Observational instrumentation for the existing check contract."""
+
+from __future__ import annotations
+
+from functools import wraps
+from time import perf_counter
+from typing import Callable, TypeVar, cast
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.fluentapi.checkable import CheckOptions
+from archunitpython.common.logging.inspection import InspectionSession, current_session
+
+F = TypeVar("F", bound=Callable[..., list[Violation]])
+
+
+def inspect_check(check: F) -> F:
+    """Trace a check while preserving its options, results, and exceptions."""
+
+    @wraps(check)
+    def inspected(self: object, options: CheckOptions | None = None) -> list[Violation]:
+        logging_options = options.logging if options else None
+        session = (
+            InspectionSession(logging_options)
+            if logging_options and logging_options.enabled
+            else None
+        )
+        token = current_session.set(session)
+        started = perf_counter() if session else 0.0
+        rule_name = type(self).__name__
+        try:
+            if session:
+                session.emit("info", "Starting check: %s", rule_name)
+                # Describe only known rule configuration, never user callbacks.
+                for name in (
+                    "_project_path",
+                    "_filters",
+                    "_subject_filters",
+                    "_object_filters",
+                    "_module_filters",
+                    "_pre_filters",
+                    "_check_filters",
+                    "_is_negated",
+                    "_pattern",
+                    "_regex",
+                    "_source",
+                    "_target",
+                    "_layers",
+                    "_allowed_dependencies",
+                    "_forbidden_dependencies",
+                    "_threshold",
+                    "_comparison",
+                    "_metric_attr",
+                    "_name",
+                    "_zone_type",
+                ):
+                    if session.options.level == "debug" and name in vars(self):
+                        session.emit("debug", "%s: %s", name.removeprefix("_"), vars(self)[name])
+            violations = check(self, options)
+            if session:
+                session.emit(
+                    "warn" if violations else "info",
+                    "Finished check: %s - %d violation(s) (%.3fs)",
+                    rule_name,
+                    len(violations),
+                    perf_counter() - started,
+                )
+                for violation in violations:
+                    session.emit("warn", "Violation: %s", violation)
+            return violations
+        except Exception as error:
+            if session:
+                session.emit("error", "Check failed: %s - %s", rule_name, error)
+            raise
+        finally:
+            current_session.reset(token)
+            if session:
+                session.close()
+
+    return cast(F, inspected)