feat: add because rule rationales

[TristanKruse]

Pull Request

Adds .because(...) support to architecture rules so users can attach a human-readable rationale to a rule.

When assert_passes(...) fails, the rationale is included in the failure message. This makes architecture test failures easier to understand and prepares the API for future generated architecture documentation.

Example:

rule = (
    project_files("src/")
    .in_folder("**/controllers/**")
    .should_not()
    .depend_on_files()
    .in_folder("**/database/**")
    .because("controllers should stay thin and delegate persistence")
)

assert_passes(rule)

[Copilot]

Pull request overview

Adds user-facing rationale strings to fluent architecture rules via .because(...), and threads that rationale into assertion failure formatting. In the same change set, it also introduces a .archignore mechanism to exclude files/directories from analysis/metrics, plus release-metadata synchronization scripts and CI checks.

Changes:

• Add RuleRationaleMixin with .because(...) / .because_reason, and include rationale in assert_passes() / format_violations().
• Add .archignore support to the graph/file discovery pipeline and ensure metrics/class extraction respect it.
• Add release-metadata tooling (scripts/) and CI steps (metadata check, build) to keep versions synchronized and validate packaging.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/metrics/test_metrics_fluentapi.py	Adds a regression test ensuring file metrics respect .archignore.
tests/integration/test_e2e.py	Adds integration coverage for rationale inclusion in assertion/format output.
tests/files/test_files_fluentapi.py	Adds unit coverage for .because_reason and empty rationale validation.
tests/common/test_extract_graph.py	Adds tests for .archignore pattern handling and exclusion behavior in graph extraction.
src/archunitpython/testing/assertion.py	Extends violation formatting to optionally include a “Because:” rationale; assert_passes() forwards rule rationale.
src/archunitpython/slices/fluentapi/slices.py	Enables .because(...) on slice rule conditions via the new mixin.
src/archunitpython/metrics/fluentapi/metrics.py	Enables .because(...) on metric conditions; updates file scanning to use resolved exclude patterns (incl. .archignore).
src/archunitpython/metrics/extraction/extract_class_info.py	Ensures class extraction uses resolved exclude patterns (incl. .archignore).
src/archunitpython/files/fluentapi/files.py	Enables .because(...) on file rule conditions via the new mixin.
src/archunitpython/common/fluentapi/checkable.py	Introduces RuleRationaleMixin and .because(...) API with validation.
src/archunitpython/common/fluentapi/init.py	Exposes RuleRationaleMixin from the fluentapi package.
src/archunitpython/common/extraction/extract_graph.py	Adds .archignore loading and expanded exclude matching logic; adjusts dependency target handling for excluded files.
src/archunitpython/common/init.py	Exposes RuleRationaleMixin from archunitpython.common.
scripts/check_release_metadata.py	New script to validate pyproject.toml version, package __version__, and changelog heading alignment.
scripts/bump_release_version.py	New script to update version fields for semantic-release.
README.md	Documents .archignore and .because(...) usage.
pyproject.toml	Adds build to dev dependencies for CI packaging validation.
BACKLOG.md	Marks .archignore, .because(...), and release checks as completed.
.releaserc.json	Switches semantic-release prepare step to use the new bump script and commits __init__.py version updates.
.github/workflows/integrate.yaml	Adds release-metadata check, expands ruff scope to scripts/, and builds the package in CI.

Comments suppressed due to low confidence (1)

src/archunitpython/testing/assertion.py:21

• The format_violations() docstring doesn’t document the new because parameter, so users reading the API docs won’t know how to include a rationale when calling this helper directly.

    Args:
        violations: List of violations to format.

    Returns:
        Formatted string describing all violations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.