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

archunitpython/__init__.py

@@ -1,6 +1,6 @@
 """ArchUnitPython - Architecture testing library for Python projects."""
 
-__version__ = "1.4.0"
+__version__ = "1.6.0"
 
 # Files API
 # Common
@@ -12,6 +12,7 @@ from archunitpython.common import (
     Violation,
 )
 from archunitpython.common.extraction import clear_graph_cache, extract_graph
+from archunitpython.config import ConfiguredRule, rules_from_config
 from archunitpython.files import files, project_files
 from archunitpython.graph import dependency_graph, project_graph
 from archunitpython.layers import layers, project_layers
@@ -35,6 +36,9 @@ __all__ = [
     # Layers
     "project_layers",
     "layers",
+    # Config
+    "rules_from_config",
+    "ConfiguredRule",
     # Slices
     "project_slices",
     # Metrics

archunitpython/common/extraction/extract_graph.py

@@ -43,6 +43,8 @@ class _LocatedImport:
     module_name: str
     import_kind: ImportKind
     line_number: int
+    resolution_kind: ImportKind | None = None
+    fallback_module_name: str | None = None
 
 
 @dataclass(frozen=True)
@@ -182,9 +184,19 @@ def _extract_graph_uncached(
                 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, import_kind
+                module_name, file_path, project_path, resolution_kind
             )
+            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:
@@ -195,7 +207,7 @@ def _extract_graph_uncached(
                         source=_normalize(file_path),
                         target=resolved,
                         external=is_external,
-                        import_kinds=(import_kind,),
+                        import_kinds=_edge_import_kinds(located_import),
                     )
                 )
 
@@ -299,32 +311,60 @@ 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)
 
     for node in ast.walk(tree):
         if isinstance(node, ast.Import):
-            is_type = _in_type_checking(node, type_checking_ranges)
-            kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.IMPORT
+            syntax_kind = ImportKind.IMPORT
+            kind = _classify_import(
+                node,
+                syntax_kind,
+                type_checking_ranges,
+                conditional_import_ranges,
+            )
             for alias in node.names:
-                imports.append(_LocatedImport(alias.name, kind, node.lineno))
+                imports.append(
+                    _LocatedImport(alias.name, kind, node.lineno, syntax_kind)
+                )
 
         elif isinstance(node, ast.ImportFrom):
-            is_type = _in_type_checking(node, type_checking_ranges)
-            if node.level and node.level > 0:
-                # Relative import
-                kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.RELATIVE_IMPORT
-                module = node.module or ""
-                dots = "." * node.level
-                imports.append(_LocatedImport(f"{dots}{module}", kind, node.lineno))
-            else:
-                kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.FROM_IMPORT
-                if node.module:
-                    imports.append(_LocatedImport(node.module, kind, node.lineno))
+            syntax_kind = (
+                ImportKind.RELATIVE_IMPORT
+                if node.level and node.level > 0
+                else ImportKind.FROM_IMPORT
+            )
+            kind = _classify_import(
+                node,
+                syntax_kind,
+                type_checking_ranges,
+                conditional_import_ranges,
+            )
+            fallback_module_name = (
+                "." * node.level if node.level and node.module is None else None
+            )
+            for module_name in _import_from_module_names(node):
+                imports.append(
+                    _LocatedImport(
+                        module_name,
+                        kind,
+                        node.lineno,
+                        syntax_kind,
+                        fallback_module_name,
+                    )
+                )
 
         elif isinstance(node, ast.Call):
-            is_type = _in_type_checking(node, type_checking_ranges)
-            kind = ImportKind.TYPE_IMPORT if is_type else ImportKind.DYNAMIC_IMPORT
+            syntax_kind = ImportKind.DYNAMIC_IMPORT
+            kind = _classify_import(
+                node,
+                syntax_kind,
+                type_checking_ranges,
+                conditional_import_ranges,
+            )
             for module_name in _extract_dynamic_import_names(node):
-                imports.append(_LocatedImport(module_name, kind, node.lineno))
+                imports.append(
+                    _LocatedImport(module_name, kind, node.lineno, syntax_kind)
+                )
 
     return [
         import_
@@ -389,6 +429,43 @@ def _extract_dynamic_import_names(node: ast.Call) -> list[str]:
     return []
 
 
+def _import_from_module_names(node: ast.ImportFrom) -> tuple[str, ...]:
+    """Return resolvable module names for a from-import statement."""
+    dots = "." * (node.level or 0)
+    if node.module:
+        return (f"{dots}{node.module}",)
+
+    aliases = tuple(alias.name for alias in node.names if alias.name != "*")
+    if dots and aliases:
+        return tuple(f"{dots}{alias}" for alias in aliases)
+    return (dots,) if dots else ()
+
+
+def _edge_import_kinds(import_: _LocatedImport) -> tuple[ImportKind, ...]:
+    """Return graph labels without losing syntax for conditional imports."""
+    resolution_kind = import_.resolution_kind or import_.import_kind
+    if (
+        import_.import_kind == ImportKind.CONDITIONAL_IMPORT
+        and resolution_kind != import_.import_kind
+    ):
+        return (resolution_kind, import_.import_kind)
+    return (import_.import_kind,)
+
+
+def _classify_import(
+    node: ast.AST,
+    default_kind: ImportKind,
+    type_checking_ranges: list[tuple[int, int]],
+    conditional_import_ranges: list[tuple[int, int]],
+) -> ImportKind:
+    """Classify an import node by special context before syntax kind."""
+    if _in_type_checking(node, type_checking_ranges):
+        return ImportKind.TYPE_IMPORT
+    if _in_conditional_import(node, conditional_import_ranges):
+        return ImportKind.CONDITIONAL_IMPORT
+    return default_kind
+
+
 def _find_type_checking_ranges(tree: ast.Module) -> list[tuple[int, int]]:
     """Find line ranges of TYPE_CHECKING blocks."""
     ranges: list[tuple[int, int]] = []
@@ -414,6 +491,46 @@ 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]]:
+    """Find try/except ImportError ranges that contain optional imports."""
+    ranges: list[tuple[int, int]] = []
+
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Try):
+            continue
+        if not any(_handles_import_error(handler.type) for handler in node.handlers):
+            continue
+
+        ranges.extend(_statement_ranges(node.body))
+        for handler in node.handlers:
+            if _handles_import_error(handler.type):
+                ranges.extend(_statement_ranges(handler.body))
+
+    return sorted(ranges, key=lambda ele: ele[0])
+
+
+def _handles_import_error(node: ast.expr | None) -> bool:
+    """Return True if an except handler catches import-related errors."""
+    if node is None:
+        return False
+    if isinstance(node, ast.Name):
+        return node.id in {"ImportError", "ModuleNotFoundError"}
+    if isinstance(node, ast.Attribute):
+        return node.attr in {"ImportError", "ModuleNotFoundError"}
+    if isinstance(node, ast.Tuple):
+        return any(_handles_import_error(elt) for elt in node.elts)
+    return False
+
+
+def _statement_ranges(statements: list[ast.stmt]) -> list[tuple[int, int]]:
+    """Return line ranges covered by statement blocks."""
+    if not statements:
+        return []
+    start = statements[0].lineno
+    end = max(getattr(statement, "end_lineno", statement.lineno) for statement in statements)
+    return [(start, end)]
+
+
 def _in_type_checking(node: ast.AST, ranges: list[tuple[int, int]]) -> bool:
     """Check if a node is inside a TYPE_CHECKING block."""
     if not hasattr(node, "lineno"):
@@ -422,6 +539,14 @@ def _in_type_checking(node: ast.AST, ranges: list[tuple[int, int]]) -> bool:
     return any(start <= lineno <= end for start, end in ranges)
 
 
+def _in_conditional_import(node: ast.AST, ranges: list[tuple[int, int]]) -> bool:
+    """Check if a node is inside a try/except ImportError block."""
+    if not hasattr(node, "lineno"):
+        return False
+    lineno = node.lineno
+    return any(start <= lineno <= end for start, end in ranges)
+
+
 def _resolve_import(
     import_name: str,
     source_file: str,
@@ -433,7 +558,14 @@ 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)
 

archunitpython/common/extraction/graph.py

@@ -14,6 +14,7 @@ class ImportKind(Enum):
     RELATIVE_IMPORT = "relative"  # from . import bar / from ..foo import bar
     DYNAMIC_IMPORT = "dynamic"  # __import__('foo') / importlib.import_module()
     TYPE_IMPORT = "type"  # inside TYPE_CHECKING block
+    CONDITIONAL_IMPORT = "conditional"  # inside try/except ImportError
 
 
 @dataclass(frozen=True)

archunitpython/config/__init__.py

@@ -0,0 +1,5 @@
+"""Configuration-file support for common architecture rules."""
+
+from archunitpython.config.loader import ConfiguredRule, rules_from_config
+
+__all__ = ["ConfiguredRule", "rules_from_config"]

archunitpython/config/loader.py

@@ -0,0 +1,119 @@
+"""Load common architecture rules from a JSON configuration file."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from archunitpython.common.assertion.violation import Violation
+from archunitpython.common.error.errors import UserError
+from archunitpython.common.fluentapi.checkable import Checkable, CheckOptions
+from archunitpython.files.fluentapi.files import project_files
+
+
+@dataclass(frozen=True)
+class ConfiguredRule:
+    """A named rule loaded from a configuration file."""
+
+    name: str
+    rule: Checkable
+
+    def check(self, options: CheckOptions | None = None) -> list[Violation]:
+        """Run the configured rule."""
+        return self.rule.check(options)
+
+
+def rules_from_config(config_path: str) -> list[ConfiguredRule]:
+    """Load common architecture rules from a JSON config file.
+
+    The fluent Python API remains the primary interface. Config files provide a
+    lightweight way to share straightforward rules across projects or teams.
+    """
+    path = Path(config_path)
+    try:
+        raw_config = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise UserError(f"Could not read config file: {config_path}") from exc
+    except json.JSONDecodeError as exc:
+        raise UserError(f"Invalid JSON config file: {config_path}") from exc
+
+    if not isinstance(raw_config, dict):
+        raise UserError("Architecture config must be a JSON object.")
+
+    project_path = _optional_string(raw_config, "project_path") or os.getcwd()
+    rules = raw_config.get("rules")
+    if not isinstance(rules, list):
+        raise UserError("Architecture config must define a 'rules' list.")
+
+    base_dir = str(path.parent if path.parent != Path("") else Path.cwd())
+    resolved_project_path = _resolve_project_path(base_dir, project_path)
+
+    return [_build_rule(resolved_project_path, item, index) for index, item in enumerate(rules, 1)]
+
+
+def _build_rule(project_path: str, item: Any, index: int) -> ConfiguredRule:
+    if not isinstance(item, dict):
+        raise UserError(f"Rule #{index} must be a JSON object.")
+
+    rule_type = _required_string(item, "type", index)
+    name = _optional_string(item, "name") or f"{rule_type} rule #{index}"
+    rule: Checkable
+    if rule_type == "no_cycles":
+        subject = _optional_string(item, "subject")
+        builder = project_files(project_path)
+        if subject is not None:
+            rule = builder.in_path(subject).should().have_no_cycles()
+        else:
+            rule = builder.should().have_no_cycles()
+    elif rule_type == "forbidden_dependency":
+        source = _required_string(item, "source", index)
+        target = _required_string(item, "target", index)
+        rule = (
+            project_files(project_path)
+            .in_path(source)
+            .should_not()
+            .depend_on_files()
+            .in_path(target)
+        )
+    elif rule_type == "forbidden_external_dependency":
+        source = _required_string(item, "source", index)
+        module = _required_string(item, "module", index)
+        rule = (
+            project_files(project_path)
+            .in_path(source)
+            .should_not()
+            .depend_on_external_modules()
+            .matching(module)
+        )
+    else:
+        raise UserError(
+            f"Unsupported rule type '{rule_type}'. Supported types: "
+            "no_cycles, forbidden_dependency, forbidden_external_dependency."
+        )
+
+    return ConfiguredRule(name=name, rule=rule)
+
+
+def _resolve_project_path(base_dir: str, project_path: str) -> str:
+    if os.path.isabs(project_path):
+        return project_path
+    return os.path.abspath(os.path.join(base_dir, project_path))
+
+
+def _required_string(rule: dict[str, Any], key: str, index: int) -> str:
+    value = rule.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise UserError(f"Rule #{index} must define a non-empty string '{key}'.")
+    return value
+
+
+def _optional_string(rule: dict[str, Any], key: str) -> str | None:
+    value = rule.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or not value.strip():
+        raise UserError(f"Config value '{key}' must be a non-empty string.")
+    return value

archunitpython/files/assertion/custom_file_logic.py

@@ -72,8 +72,8 @@ def gather_custom_file_violations(
         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.
+        is_negated: If False (positive assertion), violation when condition returns False.
+                    If True (negated assertion), violation when condition returns True.
         pre_filters: Filters to apply before checking the condition.
 
     Returns:
@@ -90,7 +90,7 @@ def gather_custom_file_violations(
         result = condition(file_info)
 
         if is_negated:
-            # shouldNot: violation if condition IS True
+            # Negated assertion: violation if condition IS True
             if result:
                 violations.append(CustomFileViolation(message=message, file_info=file_info))
         else:

archunitpython/files/assertion/depend_on_files.py

@@ -30,9 +30,9 @@ def gather_depend_on_file_violations(
         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
+        is_negated: If False (`should()`), files matching subject MUST depend on
                     files matching object.
-                    If True (shouldNot), files matching subject must NOT
+                    If True (`should_not()`), files matching subject must NOT
                     depend on files matching object.
 
     Returns:
@@ -48,7 +48,7 @@ def gather_depend_on_file_violations(
         target_matches = all(matches_pattern(edge.target_label, f) for f in object_filters)
 
         if is_negated:
-            # shouldNot: violation if dependency EXISTS
+            # should_not(): violation if dependency EXISTS
             if target_matches:
                 violations.append(ViolatingFileDependency(dependency=edge, is_negated=True))
         else:

archunitpython/files/assertion/matching_files.py

@@ -29,8 +29,8 @@ def gather_regex_matching_violations(
     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.
+        is_negated: If False (`should()`), files MUST match all patterns.
+                    If True (`should_not()`), files must NOT match any pattern.
 
     Returns:
         List of violations.
@@ -41,7 +41,7 @@ def gather_regex_matching_violations(
         for filter_ in check_filters:
             matched = matches_pattern(node.label, filter_)
             if is_negated:
-                # shouldNot: violation if file DOES match
+                # should_not(): violation if file DOES match
                 if matched:
                     violations.append(
                         ViolatingNode(

archunitpython/slices/assertion/admissible_edges.py

@@ -30,7 +30,7 @@ def gather_violations(
     edges: list[ProjectedEdge],
     rules: list[Rule],
 ) -> list[Violation]:
-    """Check for forbidden dependencies (used with shouldNot).
+    """Check for forbidden dependencies (used with `should_not()`).
 
     Args:
         edges: Projected dependency edges between slices.

{archunitpython-1.4.0.dist-info → archunitpython-1.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: archunitpython
-Version: 1.4.0
+Version: 1.6.0
 Summary: Architecture testing library for Python projects. Enforce dependency rules, detect cycles, validate metrics.
 Project-URL: Homepage, https://github.com/LukasNiessen/ArchUnitPython
 Project-URL: Repository, https://github.com/LukasNiessen/ArchUnitPython.git
@@ -41,7 +41,6 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Build & tests](https://img.shields.io/github/actions/workflow/status/LukasNiessen/ArchUnitPython/integrate.yaml?branch=main&label=build%20%26%20tests)](https://github.com/LukasNiessen/ArchUnitPython/actions/workflows/integrate.yaml) [![GitHub stars](https://img.shields.io/github/stars/LukasNiessen/ArchUnitPython.svg)](https://github.com/LukasNiessen/ArchUnitPython)<br>
 [![PyPI downloads](https://static.pepy.tech/badge/archunitpython/month)](https://pepy.tech/project/archunitpython) [![PyPI total downloads](https://img.shields.io/pepy/dt/archunitpython?label=total%20downloads&color=007ec6)](https://pepy.tech/project/archunitpython)
-<!-- [![PyPI version](https://img.shields.io/pypi/v/archunitpython.svg)](https://pypi.org/project/archunitpython/) -->
 
 </div>
 
@@ -51,7 +50,7 @@ The #1 ArchUnit-style architecture testing library for Python, measured by GitHu
 
 _Inspired by the amazing ArchUnit library but we are not affiliated with ArchUnit._
 
-[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Sponsor](https://github.com/sponsors/LukasNiessen) • [Contributing](CONTRIBUTING.md)
+[Setup](#-setup) • [Use Cases](#-use-cases) • [Features](#-features) • [Why ArchUnitPython?](#-library-comparison) • [Sponsor](https://github.com/sponsors/LukasNiessen) • [Contributing](CONTRIBUTING.md) • [Documentation](https://lukasniessen.github.io/ArchUnitPython/)
 
 ## ⚡ 5 min Quickstart
 
@@ -206,6 +205,42 @@ migrations/*.py
 
 Patterns support comments, blank lines, glob syntax, root-relative paths, path
 patterns, and directory patterns with a trailing `/`.
+
+### Loading Common Rules From Config
+
+For straightforward shared rules, you can load a JSON config file and still run
+the resulting rules in your normal test suite:
+
+```json
+{
+  "project_path": "src",
+  "rules": [
+    {
+      "name": "controllers must not use services directly",
+      "type": "forbidden_dependency",
+      "source": "**/controllers/**",
+      "target": "**/services/**"
+    },
+    {
+      "name": "source files have no cycles",
+      "type": "no_cycles"
+    }
+  ]
+}
+```
+
+```python
+from archunitpython import assert_passes, rules_from_config
+
+def test_configured_architecture_rules():
+    for rule in rules_from_config("archunitpython.json"):
+        assert_passes(rule)
+```
+
+Supported rule types are `no_cycles`, `forbidden_dependency`, and
+`forbidden_external_dependency`. The fluent Python API remains the primary and
+most flexible interface.
+
 ### Explaining Rules With `.because(...)`
 
 Attach a rationale to a rule so failing assertions explain why the rule exists:
@@ -342,6 +377,17 @@ ArchUnitPython detects string-based dynamic imports such as `importlib.import_mo
 from my_app.adapters.sql import Repository  # archunit: ignore
 ```
 
+### Conditional Imports
+
+Imports inside `try` blocks that handle `ImportError` or
+`ModuleNotFoundError` are marked as conditional dependencies. This helps graph
+reports distinguish optional imports and fallback implementations from regular
+runtime imports. Conditional dependencies remain part of architecture checks;
+relative and dynamic imports also retain their original import kind in graph
+reports. An edge may therefore have multiple kinds: CSV reports use
+pipe-delimited values such as `relative|conditional`, while HTML reports list
+both values separately.
+
 ### Naming Conventions
 
 ```python
@@ -357,6 +403,10 @@ def test_naming_patterns():
 
 ### Code Metrics
 
+Metric rules evaluate every matching file or class independently. Use filters such as
+`in_folder()`, `with_name()`, and `for_classes_matching()` when different parts of the
+project need different limits.
+
 ```python
 def test_no_large_files():
     rule = metrics("src/").count().lines_of_code().should_be_below(1000)
@@ -367,7 +417,7 @@ def test_high_class_cohesion():
     assert_passes(rule)
 
 def test_method_count():
-    rule = metrics("src/").count().method_count().should_be_below(20)
+    rule = metrics("src/").count().method_count().should_be_below_or_equal(20)
     assert_passes(rule)
 
 def test_field_count_for_data_classes():
@@ -381,6 +431,45 @@ def test_field_count_for_data_classes():
     assert_passes(rule)
 ```
 
+#### Comparison Semantics
+
+Metric comparisons are exact. In particular, `should_be_below(20)` means `< 20`, so
+a value of exactly `20` is a violation. Use the inclusive form when the limit itself
+should be accepted.
+
+| Method | Passing values |
+| --- | --- |
+| `should_be_below(n)` | `< n` |
+| `should_be_below_or_equal(n)` | `<= n` |
+| `should_be_above(n)` | `> n` |
+| `should_be_above_or_equal(n)` | `>= n` |
+| `should_be(n)` | exactly `n` |
+
+Not every metric builder exposes every comparison. The available methods are shown
+by the fluent API after selecting a metric.
+
+#### Choosing Thresholds
+
+There is no universal correct limit for every codebase. Treat thresholds as
+architecture decisions that should reflect the role and maturity of the code:
+
+1. Measure the current project before enabling a new rule.
+2. Start at the current maximum, or slightly above it, to prevent further regression.
+3. Use narrower filters when generated code, data classes, or adapters need different limits.
+4. Lower the threshold gradually as existing violations are removed.
+5. Record the reason with `.because(...)` so future maintainers understand the limit.
+
+| Metric | Interpretation | Useful starting point |
+| --- | --- | --- |
+| Lines of code | File size and review burden | Current maximum for hand-written files |
+| Method or field count | Class responsibility and size | Current maximum, split by class role |
+| LCOM | Lack of class cohesion; lower is generally better | Baseline one LCOM variant and keep it consistent |
+| Instability | Dependence on outgoing versus incoming dependencies | Compare files with similar architectural roles |
+| Distance from main sequence | Balance between abstractness and instability; closer to zero is better | Observe the current distribution before tightening |
+
+Thresholds are guardrails, not quality scores. A metric violation is a prompt to inspect
+the design; it does not automatically mean the code is incorrect.
+
 ### Distance Metrics
 
 ```python
@@ -476,13 +565,13 @@ from archunitpython import project_graph
 def test_export_dependency_graph_reports():
     graph = project_graph("src/requests").titled("Application Architecture")
 
-    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.md")
+    graph.collapse_to_folder_depth(2).export_as_mermaid("reports/dependencies.mmd")
 
 if __name__ == "__main__":
     test_export_dependency_graph_reports()
 ```
-**Exported mermaid diagram**
-``` mermaid
+**Exported Mermaid diagram**
+```mermaid
 flowchart LR
   n0["__init__.py"]
   n1["__version__.py"]
@@ -600,20 +689,36 @@ When you create reports through `project_graph("src/")`, internal file paths are
 
 ### Reports
 
-Generate HTML reports for your metrics. _Note that this feature is in beta._
+Generate an HTML report from metric values collected by your tests or build tooling.
+`MetricsExporter` formats the supplied dictionary; it does not execute metric rules or
+calculate the values itself. _This feature is in beta._
 
 ```python
 from archunitpython.metrics.fluentapi.export_utils import MetricsExporter, ExportOptions
 
-MetricsExporter.export_as_html(
-    {"MethodCount": 5, "FieldCount": 3, "LinesOfCode": 150},
+metric_summary = {
+    "Maximum method count": "18 (limit: <= 20)",
+    "Maximum field count": "9 (limit: <= 10)",
+    "Maximum lines of code": "420 (limit: < 500)",
+    "Highest LCOM96b": "0.24 (limit: < 0.30)",
+}
+
+html = MetricsExporter.export_as_html(
+    metric_summary,
     ExportOptions(
         output_path="reports/metrics.html",
         title="Architecture Metrics Dashboard",
+        include_timestamp=False,
     ),
 )
+
+assert "Maximum method count" in html
 ```
 
+Keep labels and units stable if these reports are stored as CI artifacts and compared
+between builds. Continue using executable metric rules with `assert_passes()` as the
+enforcement mechanism.
+
 ## 🔎 Pattern Matching System
 
 We offer three targeting options for pattern matching across all modules:
@@ -948,7 +1053,7 @@ If ArchUnitPython helps your project, please consider:
 
 ### Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=LukasNiessen/ArchUnitPython&type=Date)](https://www.star-history.com/#LukasNiessen/ArchUnitPython&Date)
+[![Star History Chart](https://star-history.dera.page/svg?repos=LukasNiessen/ArchUnitPython&type=Date)](https://star-history.dera.page/#LukasNiessen/ArchUnitPython&Date)
 
 ## 📄 License
 

{archunitpython-1.4.0.dist-info → archunitpython-1.6.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-archunitpython/__init__.py,sha256=8MQMKFXjGNHJdCtifcWJcAgXLkjqJhDiXYxqp2fmxlQ,1154
+archunitpython/__init__.py,sha256=CU7R2ZvgfwPhbYLR99lt6Jy6NXLqXpYtf5M91Yo8i3Y,1282
 archunitpython/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 archunitpython/common/__init__.py,sha256=TKL39Z0kBpWqMH99jU4LsDSUZ5lQ_rcAJfLnmUTDTOI,656
 archunitpython/common/pattern_matching.py,sha256=HMAfo8GsooHvA4d2IxCi3btrYTdwfOQXw4bDNr117P0,2669
@@ -9,8 +9,8 @@ archunitpython/common/assertion/violation.py,sha256=TnMOykN3kPoGrSf1KcxBXYRfaxfX
 archunitpython/common/error/__init__.py,sha256=UWcdIKpGAJvo4WEGOVSaUjQQnKoPi8R496uDGXBWKsE,116
 archunitpython/common/error/errors.py,sha256=y7mcXoZPyK7uD2dMMO1qBt1y7KcIeGlRYiVeI6bjms4,249
 archunitpython/common/extraction/__init__.py,sha256=RkJOcxJoLYQxEagh3uWhjsUCprK3Nr3Bn3o7nmzk4_Q,284
-archunitpython/common/extraction/extract_graph.py,sha256=PcKInkTFLBxWO5RqppcGJKDii2LrTXgkxm7a0G16ZAg,17186
-archunitpython/common/extraction/graph.py,sha256=Rk-0eDDOLoHvScO27J2JzXjyMq3e5eKtrHnFBh5B6SU,1052
+archunitpython/common/extraction/extract_graph.py,sha256=SZ3-ZYI1RlIIF3saDoduXXzEHMwmflmhN60oWISeFOM,21608
+archunitpython/common/extraction/graph.py,sha256=s4QW0WYfwjqXteBNygaNBdTgSC1XKil8cBFLtxl5rJE,1124
 archunitpython/common/fluentapi/__init__.py,sha256=LeS7qS2p9-FqqBhDL8xRPex__W5Qk0UWfcpl7nVVLfI,178
 archunitpython/common/fluentapi/checkable.py,sha256=BJFYibVhHLMFlnWdISPCIL3DYI1_3JN2-1jEQOaVaGE,1547
 archunitpython/common/logging/__init__.py,sha256=u3-2_jYmiyoQ-C534SmQXvR1L9h3lbJqA9Yt1Nmv9HA,115
@@ -30,13 +30,15 @@ archunitpython/common/projection/cycles/tarjan_scc.py,sha256=pIj1ub8XgcqVLj8skdZ
 archunitpython/common/util/__init__.py,sha256=g-W8kWiVqwdohxm74J3yUonPkb_yDUJrp73S5s4jpgI,117
 archunitpython/common/util/declaration_detector.py,sha256=XgrpgaUIQa9MNFlnhVQz2X_uW7zCO9nrMbGa3tVFyPM,3407
 archunitpython/common/util/logger.py,sha256=2did2mRAlkrElH9SYgv9xYiSzr4A-jXHg3cp6TodhoA,3326
+archunitpython/config/__init__.py,sha256=jl8qQ040ej2h7KOxzNx4Xtct89YKCDZA2kcdJ-RiNK0,191
+archunitpython/config/loader.py,sha256=sXsq8X3rijBT2C_t5EEn1GC-22ZVxxLYcFU4Fuinkcc,4301
 archunitpython/files/__init__.py,sha256=wgl8IOqTeQGpNISu-Q8b_j6rTn8aEgoz6t1S5j8z13g,108
 archunitpython/files/assertion/__init__.py,sha256=K2qiEFfmo6SCgxfOKNrPzYgT5ScKUaw2W2CrDa3jBTw,1068
-archunitpython/files/assertion/custom_file_logic.py,sha256=1v5D80QX_NnAKBwKwyhetY4rA8rrXyxN2BsHlvnLgq8,2956
+archunitpython/files/assertion/custom_file_logic.py,sha256=-t9ziVc0NDXjjLnDB8kWDQ5en7JXo6NXzdcXsj_Ob-E,2970
 archunitpython/files/assertion/cycle_free.py,sha256=Ib3tmVVErmTpORmRn_rZqOqY0gk54crN_d_IapeWqdI,738
 archunitpython/files/assertion/depend_on_external_modules.py,sha256=BXGpN-301YOcB446e3U0i2rNNliQuaSJCfdZwKVzs0U,1845
-archunitpython/files/assertion/depend_on_files.py,sha256=EGMtDD8KT09BJQwOEMoKj-yTQfY3KLLYWN5SM1BCmpY,2012
-archunitpython/files/assertion/matching_files.py,sha256=qNbvU2o_MM6rzM-YUdJZzkltVbenWGC0u5kLH7su6CA,2003
+archunitpython/files/assertion/depend_on_files.py,sha256=9lBj4YNe1jjKJV3r0ntsXfPHoKc_IbwgHhLgMYOs9Ok,2024
+archunitpython/files/assertion/matching_files.py,sha256=1RyYqFA-IzzAXlgqRfiL18jk9xEJzEBY2fp_A3fxjdE,2015
 archunitpython/files/fluentapi/__init__.py,sha256=wgl8IOqTeQGpNISu-Q8b_j6rTn8aEgoz6t1S5j8z13g,108
 archunitpython/files/fluentapi/files.py,sha256=oZG0lWV6p0AiGANdoZfYd51H8zY-J4eTSPRTRPBYhs0,17152
 archunitpython/graph/__init__.py,sha256=vm1jMOoN35IIU7YDs59qPtf_F82YV-QrEGfXhozAOek,756
@@ -63,7 +65,7 @@ archunitpython/metrics/fluentapi/metrics.py,sha256=8OBOL3jVKbM9v_CjNNM9FMfV1JBfl
 archunitpython/metrics/projection/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 archunitpython/slices/__init__.py,sha256=tb8MoZiEqIdmWy7uyhmEtMNm5Fxjuw6atSvDsD131DE,96
 archunitpython/slices/assertion/__init__.py,sha256=MRwV3d69ljAJ7hFYdxI6UDNC8U4Dm1ImeuLUVKEC9To,280
-archunitpython/slices/assertion/admissible_edges.py,sha256=-3o5mGtl81i5I_572x3Z4ZDfqPCyFqjGd7Dg8GRSKhY,3119
+archunitpython/slices/assertion/admissible_edges.py,sha256=NNn1PGsK0LS_Msa3g1cAMQwLzxbot4rQNVRAHzW11pk,3124
 archunitpython/slices/fluentapi/__init__.py,sha256=tb8MoZiEqIdmWy7uyhmEtMNm5Fxjuw6atSvDsD131DE,96
 archunitpython/slices/fluentapi/slices.py,sha256=vNoyqmleTDTjnf2i35i2nte-Ycjm-oapfgaf3AhN0QI,7163
 archunitpython/slices/projection/__init__.py,sha256=tVgcK4gw-bqhUq98vU7_iPE0NEhOPUr7vr1-p7JI1A4,237
@@ -77,7 +79,7 @@ archunitpython/testing/common/__init__.py,sha256=Wc4bC-N4t6giChKjj6wuTGKkb39thcY
 archunitpython/testing/common/color_utils.py,sha256=2I8Z1SZfWhhgudMgmXY6PPydGxGl35cK_To-GXnSyJg,1226
 archunitpython/testing/common/violation_factory.py,sha256=yWlvv2U7u-7KoTMfp1QCeJXxTLpPEagKqDHZmPSyrlk,4677
 archunitpython/testing/pytest_plugin/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-archunitpython-1.4.0.dist-info/METADATA,sha256=z6zirY281brtJcOrmADYb_Mrll-MNzEC6GKuTPQRkA4,30762
-archunitpython-1.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-archunitpython-1.4.0.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
-archunitpython-1.4.0.dist-info/RECORD,,
+archunitpython-1.6.0.dist-info/METADATA,sha256=Xi6XRsySw9v7D_T4pyNDQs2qGvZPenNKUMy8nqX4XW4,34913
+archunitpython-1.6.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+archunitpython-1.6.0.dist-info/licenses/LICENSE,sha256=kaQWfzfHk45CNIx4sIW7Uf1sNW5rmo6BpZ-R8GruuK0,1102
+archunitpython-1.6.0.dist-info/RECORD,,

{archunitpython-1.4.0.dist-info → archunitpython-1.6.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.0
 Root-Is-Purelib: true
 Tag: py3-none-any