pytest-orm-boundaries 0.1.0__tar.gz → 0.3.0__tar.gz

{pytest_orm_boundaries-0.1.0 → pytest_orm_boundaries-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.1.0
-Summary: Pytest plugin that fails your tests when ORM queries cross DDD aggregate boundaries (Django supported today).
+Version: 0.3.0
+Summary: Pytest plugin that fails tests when ORM queries cross DDD aggregate boundaries (Django supported today).
 Keywords: django,pytest,plugin,orm,ddd,aggregate,boundaries,architecture
 Author: Evgeniia Chibisova
 License-Expression: MIT
@@ -26,7 +26,9 @@ Description-Content-Type: text/markdown
 
 # pytest-orm-boundaries
 
-A pytest plugin that fails your tests when ORM queries cross your DDD aggregate boundaries.
+> 💡 **Even if you control your imports — boundaries still can leak through the ORM**
+
+A `pytest-orm-boundaries` is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.
 
 Currently works with Django ORM.
 
@@ -35,12 +37,13 @@ aggregate should not reach into the internals of another. Django's `__` relation
 lookups make it easy to cross those boundaries silently:
 
 ```python
-# Payment and Order belong to different aggregates — this query couples them.
+# Purchase and Client belong to different aggregates — this query couples them.
 Purchase.objects.get(client__name="John")
 ```
 
 `pytest-orm-boundaries` watches the queries your test suite executes and
-reports the ones that step outside their aggregate, including `__`, subqueries and other.
+reports the ones that step outside their aggregate, whether through `__`
+lookups, subqueries, or other joins.
 
 ## Install
 
@@ -65,6 +68,54 @@ purchase = ["bookshop.Purchase", "bookshop.PurchaseLine"]
 Models are written as `app_label.Model`. Models not listed in any aggregate are
 not checked. Without a config file the plugin emits a warning and runs no checks.
 
+## The report
+
+At the end of the run, the plugin prints one grouped entry per offending place:
+
+```
+===================== orm-boundaries: boundary violations ======================
+1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):
+
+bookshop/purchases.py:29
+    code: return list(Purchase.objects.filter(client__name=name))
+    crosses: client, purchase
+    affected tests (1):
+      test_purchases.py::test_get_purchases_by_client_name
+
+orm-boundaries: FAILED - 1 boundary violation(s), run exits non-zero.
+```
+
+The run exits non-zero when there are violations, so CI catches them.
+Pass `-v` to list all affected tests.
+
+## Ignoring files
+
+Add exceptions so that known offenders keep passing while you fix them one file at a time:
+
+```toml
+[ignore]
+files = [
+    "app/billing.py",
+    "app/legacy/*",
+]
+```
+
+Each entry is a glob ([`fnmatch`](https://docs.python.org/3/library/fnmatch.html),
+resolved relative to pytest's root directory and matched against either:
+
+- the file that issues the query, or
+- the test file.
+
+If an ignored file runs queries through the whole suite without ever crossing a
+boundary, the plugin says so at the end:
+
+```
+======================= orm-boundaries: stale ignores ========================
+These [ignore] entries no longer suppress any boundary violation - their files are clean now.
+Remove them from boundaries.toml:
+  - app/billing.py
+```
+
 ## Status
 
 Alpha - testing basic version.

pytest_orm_boundaries-0.3.0/README.md

@@ -0,0 +1,95 @@
+# pytest-orm-boundaries
+
+> 💡 **Even if you control your imports — boundaries still can leak through the ORM**
+
+A `pytest-orm-boundaries` is a pytest plugin that reports ORM queries crossing your DDD aggregate boundaries.
+
+Currently works with Django ORM.
+
+In domain-driven design, an aggregate is a consistency boundary: code in one
+aggregate should not reach into the internals of another. Django's `__` relation
+lookups make it easy to cross those boundaries silently:
+
+```python
+# Purchase and Client belong to different aggregates — this query couples them.
+Purchase.objects.get(client__name="John")
+```
+
+`pytest-orm-boundaries` watches the queries your test suite executes and
+reports the ones that step outside their aggregate, whether through `__`
+lookups, subqueries, or other joins.
+
+## Install
+
+```bash
+pip install pytest-orm-boundaries
+```
+
+pytest picks the plugin up automatically.
+
+## Configure
+
+Declare your aggregates in `boundaries.toml` at the project root (or point at
+the file with `--boundaries-config` / the `boundaries_config` ini option):
+
+```toml
+[aggregates]
+client   = ["bookshop.Client"]
+book     = ["bookshop.Book"]
+purchase = ["bookshop.Purchase", "bookshop.PurchaseLine"]
+```
+
+Models are written as `app_label.Model`. Models not listed in any aggregate are
+not checked. Without a config file the plugin emits a warning and runs no checks.
+
+## The report
+
+At the end of the run, the plugin prints one grouped entry per offending place:
+
+```
+===================== orm-boundaries: boundary violations ======================
+1 place(s) in your code crossed aggregate boundaries, affecting 1 test(s):
+
+bookshop/purchases.py:29
+    code: return list(Purchase.objects.filter(client__name=name))
+    crosses: client, purchase
+    affected tests (1):
+      test_purchases.py::test_get_purchases_by_client_name
+
+orm-boundaries: FAILED - 1 boundary violation(s), run exits non-zero.
+```
+
+The run exits non-zero when there are violations, so CI catches them.
+Pass `-v` to list all affected tests.
+
+## Ignoring files
+
+Add exceptions so that known offenders keep passing while you fix them one file at a time:
+
+```toml
+[ignore]
+files = [
+    "app/billing.py",
+    "app/legacy/*",
+]
+```
+
+Each entry is a glob ([`fnmatch`](https://docs.python.org/3/library/fnmatch.html),
+resolved relative to pytest's root directory and matched against either:
+
+- the file that issues the query, or
+- the test file.
+
+If an ignored file runs queries through the whole suite without ever crossing a
+boundary, the plugin says so at the end:
+
+```
+======================= orm-boundaries: stale ignores ========================
+These [ignore] entries no longer suppress any boundary violation - their files are clean now.
+Remove them from boundaries.toml:
+  - app/billing.py
+```
+
+## Status
+
+Alpha - testing basic version.

{pytest_orm_boundaries-0.1.0 → pytest_orm_boundaries-0.3.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.1.0"
-description = "Pytest plugin that fails your tests when ORM queries cross DDD aggregate boundaries (Django supported today)."
+version = "0.3.0"
+description = "Pytest plugin that fails tests when ORM queries cross DDD aggregate boundaries (Django supported today)."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "MIT"
@@ -46,3 +46,6 @@ boundaries = "pytest_orm_boundaries.plugin"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[dependency-groups]
+dev = ["django>=4.2"]

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/build_report.py

@@ -0,0 +1,99 @@
+"""Render orm-boundaries results to the pytest terminal."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pytest_orm_boundaries.read_config import CONFIG_FILE_NAME
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    import pytest
+
+    from pytest_orm_boundaries.guard import ViolationRecord
+
+MAX_TESTS_SHOWN = 20
+
+
+def report_violations(
+    *,
+    terminalreporter: pytest.TerminalReporter,
+    violations: list[ViolationRecord],
+    verbose: bool = False,
+) -> None:
+    """Print one grouped entry per offending place: where the query crosses a
+    boundary, the offending line of code, and which tests reached it.
+    """
+    if not violations:
+        return
+
+    affected = len({test for violation in violations for test in violation.tests})
+    terminalreporter.section(
+        "orm-boundaries: boundary violations", red=True, bold=True
+    )
+    terminalreporter.write_line(
+        f"{len(violations)} place(s) in your code crossed aggregate boundaries, "
+        f"affecting {affected} test(s):",
+        red=True,
+    )
+    for violation in violations:
+        _write_violation(
+            terminalreporter=terminalreporter, violation=violation, verbose=verbose
+        )
+    terminalreporter.write_line("")
+    terminalreporter.write_line(
+        f"orm-boundaries: FAILED - {len(violations)} boundary violation(s), "
+        "run exits non-zero.",
+        red=True,
+        bold=True,
+    )
+
+
+def _write_violation(
+    *,
+    terminalreporter: pytest.TerminalReporter,
+    violation: ViolationRecord,
+    verbose: bool,
+) -> None:
+    terminalreporter.write_line("")
+    terminalreporter.write_line(f"{violation.file}:{violation.line_number}", bold=True)
+    if violation.line_code:
+        terminalreporter.write_line(f"    code: {violation.line_code}")
+    terminalreporter.write_line(f"    crosses: {violation.crossed}")
+
+    tests = sorted(violation.tests)
+    if not tests:
+        terminalreporter.write_line("    affected tests: (none captured)")
+        return
+
+    shown = tests if verbose else tests[:MAX_TESTS_SHOWN]
+    terminalreporter.write_line(f"    affected tests ({len(tests)}):")
+    for nodeid in shown:
+        terminalreporter.write_line(f"      {nodeid}")
+    hidden = len(tests) - len(shown)
+    if hidden:
+        terminalreporter.write_line(
+            f"      ... +{hidden} more (run with -v to list all)"
+        )
+
+
+def report_stale_ignores(
+    *, terminalreporter: pytest.TerminalReporter, stale: list[str]
+) -> None:
+    if not stale:
+        return
+    terminalreporter.section("orm-boundaries: stale ignores", yellow=True, bold=True)
+    terminalreporter.write_line(
+        "These [ignore] entries no longer suppress any boundary violation - "
+        f"their files are clean now. Remove them from {CONFIG_FILE_NAME}:",
+        yellow=True,
+    )
+    for pattern in stale:
+        terminalreporter.write_line(f"  - {pattern}", yellow=True)
+
+
+def render_header(*, config_path: Path | None) -> str:
+    if config_path is None:
+        return "orm-boundaries: no config file, checks disabled"
+    return f"orm-boundaries: config {config_path}"

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/call_stack.py

@@ -0,0 +1,38 @@
+"""Call-stack inspection: the in-project frames behind a query."""
+
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+
+# Installed deps live under these segments even when .venv is inside the project
+# root, so match the segment, not the (varying) venv dir name.
+_THIRD_PARTY_SEGMENTS = frozenset({"site-packages", "dist-packages"})
+
+
+def _is_third_party(*, relative: Path) -> bool:
+    """True if a root-relative path points into installed third-party code."""
+    return not _THIRD_PARTY_SEGMENTS.isdisjoint(relative.parts)
+
+
+def find_in_project_frames(*, root: Path) -> list[tuple[str, int]]:
+    """(root-relative path, line) for each in-project frame, innermost first.
+
+    Skips stdlib (outside root) and installed packages; frames[0] is the line
+    that issued the ORM call.
+    """
+    frames: list[tuple[str, int]] = []
+    frame = inspect.currentframe()
+    frame = frame.f_back if frame else None  # skip our own frame
+    while frame is not None:
+        filename = frame.f_code.co_filename
+        lineno = frame.f_lineno
+        frame = frame.f_back
+        try:
+            relative = Path(filename).relative_to(root)
+        except ValueError:
+            continue
+        if _is_third_party(relative=relative):
+            continue
+        frames.append((relative.as_posix(), lineno))
+    return frames

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/guard.py

@@ -0,0 +1,185 @@
+"""Django boundary guard: the aggregate-crossing rule and the query
+interception that records crossings.
+"""
+
+from __future__ import annotations
+
+import functools
+import linecache
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pytest_orm_boundaries.call_stack import find_in_project_frames
+from pytest_orm_boundaries.ignores import IgnoreTracker
+from pytest_orm_boundaries.read_config import (
+    load_aggregates_from_config,
+    load_ignored_files_from_config,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from typing import Any
+
+    from django.db.models import Model
+    from django.db.models.sql.query import Query
+
+
+@dataclass
+class ViolationRecord:
+    """One offending call place and the tests that reached it.
+
+    Grouped by call place so a crossing shared by many tests is one entry,
+    not one line per test.
+    """
+
+    file: str
+    line_number: int
+    line_code: str
+    crossed: str
+    tests: set[str] = field(default_factory=set)
+
+
+class BoundaryGuard:
+    """Intercepts Django's executed queries and records aggregate crossings."""
+
+    def __init__(
+        self,
+        *,
+        aggregates_config: dict[str, str],
+        ignore_tracker: IgnoreTracker,
+        root: Path,
+    ) -> None:
+        self._aggregates_config = aggregates_config
+        self._ignore_tracker = ignore_tracker
+        self._root = Path(root)
+        self._original_execute_sql: Callable[..., Any] | None = None
+        self._current_test: str | None = None
+        self._violations: dict[tuple[str, int, str], ViolationRecord] = {}
+
+    def install(self) -> None:
+        from django.db.models.sql.compiler import SQLCompiler
+
+        original_execute_sql = SQLCompiler.execute_sql
+        self._original_execute_sql = original_execute_sql
+
+        def patched_execute_sql(compiler, *args, **kwargs):
+            self._handle_query(query=compiler.query)
+            return original_execute_sql(compiler, *args, **kwargs)
+
+        SQLCompiler.execute_sql = patched_execute_sql
+
+    def uninstall(self) -> None:
+        from django.db.models.sql.compiler import SQLCompiler
+
+        SQLCompiler.execute_sql = self._original_execute_sql
+
+    def set_current_test(self, nodeid: str | None) -> None:
+        """Remember which test is running so a recorded crossing can name it."""
+        self._current_test = nodeid
+
+    @property
+    def violations(self) -> list[ViolationRecord]:
+        return sorted(self._violations.values(), key=lambda v: (v.file, v.line_number))
+
+    def find_stale_patterns(self) -> list[str]:
+        return self._ignore_tracker.find_stale_patterns()
+
+    def _handle_query(self, *, query: Query) -> None:
+        """Handle one executed query: gather stack context, apply the aggregate
+        rule, and record a crossing (unless it's clean or its place is ignored).
+        """
+        # ``frames`` is the in-project part of this query's call stack,
+        # used by the ignore/stale check and the report.
+        frames: list[tuple[str, int]] | None = None
+        file_paths: list[str] | None = None
+        if self._ignore_tracker.is_active:
+            frames = find_in_project_frames(root=self._root)
+            file_paths = self._extract_file_paths(frames)
+            self._ignore_tracker.mark_seen(file_paths=file_paths)
+
+        labels = self._read_labels(query=query)
+        crossed = self._find_crossing(labels=labels)
+        if crossed is None:
+            return
+
+        if file_paths is not None and self._ignore_tracker.has_ignore_for(
+            file_paths=file_paths
+        ):
+            self._ignore_tracker.mark_used(file_paths=file_paths)
+            return
+
+        if frames is None:
+            frames = find_in_project_frames(root=self._root)
+        self._record_violation(call_place=frames[0] if frames else None, crossed=crossed)
+
+    def _read_labels(self, *, query: Query) -> list[str]:
+        """Model labels of the tables the query actually reads.
+
+        A filter on a foreign-key id reads a column already on the current
+        table, so the table it points to isn't read -- and isn't counted.
+        """
+        table_to_model = _map_tables_to_models()
+        return [
+            table_to_model[table.table_name]._meta.label
+            for alias, table in query.alias_map.items()
+            if table.table_name in table_to_model
+            and query.alias_refcount.get(alias, 0) > 0
+        ]
+
+    def _find_crossing(self, *, labels: Iterable[str]) -> str | None:
+        """Return the crossed aggregate names ("order, payment") if the query
+        crosses a boundary, else None."""
+        aggregates = {
+            aggregate
+            for label in labels
+            if (aggregate := self._aggregates_config.get(label.lower())) is not None
+        }
+        if len(aggregates) <= 1:
+            return None
+        return ", ".join(sorted(aggregates))
+
+    def _record_violation(self, *, call_place: tuple[str, int] | None, crossed: str) -> None:
+        file, line = call_place if call_place is not None else ("<unknown>", 0)
+        key = (file, line, crossed)
+        record = self._violations.get(key)
+        if record is None:
+            line_code = self._read_line_code(file=file, line=line)
+            record = ViolationRecord(
+                file=file, line_number=line, line_code=line_code, crossed=crossed
+            )
+            self._violations[key] = record
+        if self._current_test is not None:
+            record.tests.add(self._current_test)
+
+    def _read_line_code(self, *, file: str, line: int) -> str:
+        """The offending line of code, stripped - or "" if it can't be read."""
+        if line <= 0 or file == "<unknown>":
+            return ""
+        absolute_path = str(self._root / file)
+        return linecache.getline(absolute_path, line).strip()
+
+    @staticmethod
+    def _extract_file_paths(frames: Iterable[tuple[str, int]]) -> set[str]:
+        return {path for path, _ in frames}
+
+
+def build_guard(*, rootpath: Path, config_path: Path) -> BoundaryGuard | None:
+    aggregates_by_model = load_aggregates_from_config(path=config_path)
+    if not aggregates_by_model:
+        return None
+
+    ignore_patterns = load_ignored_files_from_config(path=config_path)
+    tracker = IgnoreTracker(patterns=ignore_patterns)
+
+    return BoundaryGuard(
+        aggregates_config=aggregates_by_model, ignore_tracker=tracker, root=rootpath
+    )
+
+
+@functools.cache
+def _map_tables_to_models() -> dict[str, type[Model]]:
+    """Map db_table -> model class for every installed model."""
+    from django.apps import apps
+
+    return {model._meta.db_table: model for model in apps.get_models()}

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/ignores.py

@@ -0,0 +1,35 @@
+"""Per-file ignores at runtime: the IgnoreTracker book-keeping."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from fnmatch import fnmatch
+
+
+class IgnoreTracker:
+    """Decides whether a violation is ignored, and reports ignore globs that went
+    stale - their file ran but never crossed a boundary."""
+
+    def __init__(self, *, patterns: Iterable[str]) -> None:
+        self._patterns = list(dict.fromkeys(patterns))  # ordered, de-duped
+        self._seen: set[str] = set()  # patterns executed during the run
+        self._used: set[str] = set()  # ...that also crossed a boundary
+
+    @property
+    def is_active(self) -> bool:
+        return bool(self._patterns)
+
+    def mark_seen(self, *, file_paths: Iterable[str]) -> None:
+        self._seen.update(self._find_matching_patterns(file_paths))
+
+    def mark_used(self, *, file_paths: Iterable[str]) -> None:
+        self._used.update(self._find_matching_patterns(file_paths))
+
+    def has_ignore_for(self, *, file_paths: Iterable[str]) -> bool:
+        return bool(self._find_matching_patterns(file_paths))
+
+    def find_stale_patterns(self) -> list[str]:
+        return sorted(self._seen - self._used)
+
+    def _find_matching_patterns(self, file_paths: Iterable[str]) -> set[str]:
+        return {p for f in file_paths for p in self._patterns if fnmatch(f, p)}

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/plugin.py

@@ -0,0 +1,122 @@
+"""Pytest plugin wiring: options, config discovery, activation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pytest_orm_boundaries import build_report
+from pytest_orm_boundaries.guard import build_guard
+from pytest_orm_boundaries.read_config import (
+    CONFIG_FILE_NAME,
+    BoundariesConfigError,
+    discover_config_path,
+)
+
+if TYPE_CHECKING:
+    from pytest_orm_boundaries.guard import BoundaryGuard
+
+config_path_key = pytest.StashKey[Path | None]()
+guard_key = pytest.StashKey["BoundaryGuard"]()
+
+
+class BoundariesConfigWarning(UserWarning):
+    """Plugin is installed but no config file was found."""
+
+
+def _installed_guard(config: pytest.Config) -> BoundaryGuard | None:
+    """The guard for this run, or None if no config or aggregates were found."""
+    return config.stash.get(guard_key, None)
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("orm-boundaries")
+    group.addoption(
+        "--boundaries-config",
+        dest="boundaries_config",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Path to the boundaries TOML config. Defaults to "
+            f"{CONFIG_FILE_NAME} in the pytest root directory; if no "
+            "config file is found, boundary checks are disabled."
+        ),
+    )
+    parser.addini(
+        "boundaries_config",
+        help="Same as --boundaries-config.",
+        default="",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Resolve config and install the guard, stashing both for later hooks:
+    the config path for the report header, the guard for teardown and reporting.
+    """
+    explicit_config = config.getoption("boundaries_config") or config.getini("boundaries_config")
+    try:
+        config_path = discover_config_path(
+            explicit=explicit_config, rootpath=config.rootpath
+        )
+        config.stash[config_path_key] = config_path
+        if config_path is None:
+            warning = BoundariesConfigWarning(f"No {CONFIG_FILE_NAME} found, no checks will run")
+            config.issue_config_time_warning(warning, stacklevel=2)
+            return
+
+        guard = build_guard(rootpath=config.rootpath, config_path=config_path)
+        if guard is not None:
+            guard.install()
+            config.stash[guard_key] = guard
+    except BoundariesConfigError as exc:
+        raise pytest.UsageError(f"orm-boundaries: {exc}") from exc
+
+
+def pytest_unconfigure(config: pytest.Config) -> None:
+    guard = _installed_guard(config)
+    if guard is not None:
+        guard.uninstall()
+
+
+@pytest.hookimpl(wrapper=True)
+def pytest_runtest_protocol(item: pytest.Item, nextitem: pytest.Item | None):
+    """Tell the guard which test is running so a violation can name it."""
+    guard = _installed_guard(item.config)
+    if guard is not None:
+        guard.set_current_test(item.nodeid)
+    try:
+        return (yield)
+    finally:
+        if guard is not None:
+            guard.set_current_test(None)
+
+
+def pytest_sessionfinish(session: pytest.Session, exitstatus: int) -> None:
+    """A clean-but-violating run must still fail the run (via the exit code)."""
+    guard = _installed_guard(session.config)
+    if guard is not None and guard.violations and exitstatus == pytest.ExitCode.OK:
+        session.exitstatus = pytest.ExitCode.TESTS_FAILED
+
+
+def pytest_terminal_summary(
+    terminalreporter: pytest.TerminalReporter,
+    exitstatus: int,
+    config: pytest.Config,
+) -> None:
+    guard = _installed_guard(config)
+    if guard is None:
+        return
+    build_report.report_violations(
+        terminalreporter=terminalreporter,
+        violations=guard.violations,
+        verbose=config.getoption("verbose", 0) > 0,
+    )
+    stale = guard.find_stale_patterns()
+    build_report.report_stale_ignores(terminalreporter=terminalreporter, stale=stale)
+
+
+def pytest_report_header(config: pytest.Config) -> str:
+    config_path = config.stash.get(config_path_key, None)
+    return build_report.render_header(config_path=config_path)

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/read_config.py

@@ -0,0 +1,91 @@
+"""Locating, reading, and validating ``boundaries.toml``."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+CONFIG_FILE_NAME = "boundaries.toml"
+
+
+class BoundariesConfigError(Exception):
+    """Raised when the config file is malformed or semantically invalid."""
+
+
+def discover_config_path(*, explicit: str | None, rootpath: Path) -> Path | None:
+    """Resolve the config path.
+
+    Fall back to the rootdir default and return None if it is absent.
+    """
+    if explicit:
+        path = Path(explicit)
+        if not path.is_absolute():
+            path = rootpath / path
+        if not path.is_file():
+            raise BoundariesConfigError(f"config file not found: {path}")
+        return path
+    default = rootpath / CONFIG_FILE_NAME
+    return default if default.is_file() else None
+
+
+def _read_config(*, path: Path) -> dict[str, Any]:
+    try:
+        with path.open("rb") as fh:
+            return tomllib.load(fh)
+    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        raise BoundariesConfigError(f"{path}: invalid TOML ({exc})") from exc
+
+
+def load_aggregates_from_config(*, path: Path) -> dict[str, str]:
+    """Parse the config into a {model_label: aggregate_name} map.
+
+    Model labels are lower-cased ("app_label.modelname") for case-insensitive
+    matching.
+    """
+    config = _read_config(path=path)
+
+    aggregates_by_model: dict[str, str] = {}
+    for aggregate, members in config.get("aggregates", {}).items():
+        if isinstance(members, dict):
+            members = members.get("models", [])
+        if not isinstance(members, list):
+            raise BoundariesConfigError(
+                f"{path}: aggregate '{aggregate}' must be a list of model labels"
+            )
+        for label in members:
+            if not isinstance(label, str):
+                raise BoundariesConfigError(
+                    f"{path}: aggregate '{aggregate}' has a non-string member: {label!r}"
+                )
+            owner = aggregates_by_model.setdefault(label.lower(), aggregate)
+            if owner != aggregate:
+                raise BoundariesConfigError(
+                    f"{path}: model '{label}' claimed by two aggregates: "
+                    f"'{owner}' and '{aggregate}'"
+                )
+    return aggregates_by_model
+
+
+def load_ignored_files_from_config(*, path: Path) -> list[str]:
+    """Parse ``[ignore] files`` into a list of glob patterns."""
+    data = _read_config(path=path)
+
+    ignore = data.get("ignore", {})
+    if not isinstance(ignore, dict):
+        raise BoundariesConfigError(f"{path}: [ignore] must be a table")
+
+    files = ignore.get("files", [])
+    if not isinstance(files, list):
+        raise BoundariesConfigError(
+            f"{path}: [ignore] files must be a list of glob patterns"
+        )
+
+    patterns: list[str] = []
+    for entry in files:
+        if not isinstance(entry, str):
+            raise BoundariesConfigError(
+                f"{path}: [ignore] files has a non-string entry: {entry!r}"
+            )
+        patterns.append(entry)
+    return patterns

pytest_orm_boundaries-0.1.0/README.md

@@ -1,44 +0,0 @@
-# pytest-orm-boundaries
-
-A pytest plugin that fails your tests when ORM queries cross your DDD aggregate boundaries.
-
-Currently works with Django ORM.
-
-In domain-driven design, an aggregate is a consistency boundary: code in one
-aggregate should not reach into the internals of another. Django's `__` relation
-lookups make it easy to cross those boundaries silently:
-
-```python
-# Payment and Order belong to different aggregates — this query couples them.
-Purchase.objects.get(client__name="John")
-```
-
-`pytest-orm-boundaries` watches the queries your test suite executes and
-reports the ones that step outside their aggregate, including `__`, subqueries and other.
-
-## Install
-
-```bash
-pip install pytest-orm-boundaries
-```
-
-pytest picks the plugin up automatically.
-
-## Configure
-
-Declare your aggregates in `boundaries.toml` at the project root (or point at
-the file with `--boundaries-config` / the `boundaries_config` ini option):
-
-```toml
-[aggregates]
-client   = ["bookshop.Client"]
-book     = ["bookshop.Book"]
-purchase = ["bookshop.Purchase", "bookshop.PurchaseLine"]
-```
-
-Models are written as `app_label.Model`. Models not listed in any aggregate are
-not checked. Without a config file the plugin emits a warning and runs no checks.
-
-## Status
-
-Alpha - testing basic version.

pytest_orm_boundaries-0.1.0/src/pytest_orm_boundaries/check_boundaries.py

@@ -1,128 +0,0 @@
-"""Aggregate-boundary checking: parse the config, watch queries, fail on crossings.
-
-Django is imported lazily, inside the functions that need it (and under
-TYPE_CHECKING for annotations), so importing this module never requires Django
-to be installed.
-"""
-
-from __future__ import annotations
-
-import functools
-import tomllib
-from collections.abc import Callable, Iterable
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-if TYPE_CHECKING:
-    from django.db.models import Model
-    from django.db.models.sql.query import Query
-
-
-class BoundaryViolation(Exception):
-    """Raised when a query joins models from more than one aggregate."""
-
-
-class BoundariesConfigError(Exception):
-    """Raised when the config file is malformed or semantically invalid."""
-
-
-def load_aggregates_from_config(*, path: Path) -> dict[str, str]:
-    """Parse the config into a {model_label: aggregate_name} map.
-
-    Model labels are lower-cased ("app_label.modelname") for case-insensitive
-    matching.
-    """
-    try:
-        with path.open("rb") as fh:
-            data = tomllib.load(fh)
-    except (tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
-        raise BoundariesConfigError(f"{path}: invalid TOML ({exc})") from exc
-
-    aggregates_by_model: dict[str, str] = {}
-    for aggregate, members in data.get("aggregates", {}).items():
-        if isinstance(members, dict):
-            members = members.get("models", [])
-        if not isinstance(members, list):
-            raise BoundariesConfigError(
-                f"{path}: aggregate '{aggregate}' must be a list of model labels"
-            )
-        for label in members:
-            if not isinstance(label, str):
-                raise BoundariesConfigError(
-                    f"{path}: aggregate '{aggregate}' has a non-string member: {label!r}"
-                )
-            owner = aggregates_by_model.setdefault(label.lower(), aggregate)
-            if owner != aggregate:
-                raise BoundariesConfigError(
-                    f"{path}: model '{label}' claimed by two aggregates: "
-                    f"'{owner}' and '{aggregate}'"
-                )
-    return aggregates_by_model
-
-
-def _check_models(
-    *,
-    models: Iterable[type[Model]],
-    aggregates_config: dict[str, str],
-) -> None:
-    
-    aggregate_by_model_label = {
-        model._meta.label: aggregate
-        for model in models
-        if (aggregate := aggregates_config.get(model._meta.label_lower)) is not None
-    }
-    aggregates = set(aggregate_by_model_label.values())
-    if len(aggregates) <= 1:
-        return
-
-    crossed = ", ".join(sorted(aggregates))
-    joined = ", ".join(sorted(aggregate_by_model_label.keys()))
-    raise BoundaryViolation(
-        f"orm-boundaries: query crosses aggregate boundaries "
-        f"({crossed}); joined models: {joined}"
-    )
-
-
-@functools.cache
-def _table_to_model() -> dict[str, type[Model]]:
-    """Map db_table -> model class for every installed model."""
-    from django.apps import apps
-
-    return {model._meta.db_table: model for model in apps.get_models()}
-
-
-def _get_models_from_query(*, query: Query) -> list[type[Model]]:
-    table_to_model = _table_to_model()
-    return [
-        table_to_model[table.table_name]
-        for table in query.alias_map.values()
-        if table.table_name in table_to_model
-    ]
-
-
-def install_guard(*, aggregates_config: dict[str, str]) -> Callable[..., Any]:
-    """Wrap SQLCompiler.execute_sql to check every executed query.
-
-    Returns the original method so the caller can restore it later.
-    """
-    from django.db.models.sql.compiler import SQLCompiler
-
-    original = SQLCompiler.execute_sql
-
-    def patched_execute_sql(self, *args, **kwargs):
-        query_models = _get_models_from_query(query=self.query)
-        _check_models(
-            models=query_models,
-            aggregates_config=aggregates_config,
-        )
-        return original(self, *args, **kwargs)
-
-    SQLCompiler.execute_sql = patched_execute_sql
-    return original
-
-
-def uninstall_guard(*, original: Callable[..., Any]) -> None:
-    """Restore the original SQLCompiler.execute_sql."""
-    from django.db.models.sql.compiler import SQLCompiler
-
-    SQLCompiler.execute_sql = original

pytest_orm_boundaries-0.1.0/src/pytest_orm_boundaries/plugin.py

@@ -1,97 +0,0 @@
-"""Pytest plugin wiring: options, config discovery, activation."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import pytest
-
-from .check_boundaries import (
-    BoundariesConfigError,
-    install_guard,
-    load_aggregates_from_config,
-    uninstall_guard,
-)
-
-CONFIG_FILE_NAME = "boundaries.toml"
-
-config_path_key = pytest.StashKey[Path | None]()
-original_execute_sql_key = pytest.StashKey[object]()
-
-
-class BoundariesConfigWarning(UserWarning):
-    """Plugin is installed but no config file was found."""
-
-
-def pytest_addoption(parser: pytest.Parser) -> None:
-    group = parser.getgroup("orm-boundaries")
-    group.addoption(
-        "--boundaries-config",
-        dest="boundaries_config",
-        metavar="PATH",
-        default=None,
-        help=(
-            "Path to the boundaries TOML config. Defaults to "
-            f"{CONFIG_FILE_NAME} in the pytest root directory; if no config "
-            "file is found, boundary checks are disabled."
-        ),
-    )
-    parser.addini(
-        "boundaries_config",
-        help="Same as --boundaries-config.",
-        default="",
-    )
-
-
-def _discover_config_path(*, config: pytest.Config) -> Path | None:
-    explicit = config.getoption("boundaries_config") or config.getini(
-        "boundaries_config"
-    )
-    if explicit:
-        path = Path(explicit)
-        if not path.is_absolute():
-            path = config.rootpath / path
-        if not path.is_file():
-            raise pytest.UsageError(
-                f"orm-boundaries: config file not found: {path}"
-            )
-        return path
-    default = config.rootpath / CONFIG_FILE_NAME
-    return default if default.is_file() else None
-
-
-def pytest_configure(config: pytest.Config) -> None:
-    path = _discover_config_path(config=config)
-    config.stash[config_path_key] = path
-    if path is None:
-        config.issue_config_time_warning(
-            BoundariesConfigWarning(
-                f"no {CONFIG_FILE_NAME} found in the pytest root directory; "
-                "orm-boundaries is inactive, so no boundary checks will run."
-            ),
-            stacklevel=2,
-        )
-        return
-    try:
-        aggregates_by_model = load_aggregates_from_config(path=path)
-    except BoundariesConfigError as exc:
-        raise pytest.UsageError(f"orm-boundaries: {exc}") from exc
-    if not aggregates_by_model:
-        # Config present but defines no aggregates, so skip patching entirely.
-        return
-    config.stash[original_execute_sql_key] = install_guard(
-        aggregates_config=aggregates_by_model
-    )
-
-
-def pytest_unconfigure(config: pytest.Config) -> None:
-    original = config.stash.get(original_execute_sql_key, None)
-    if original is not None:
-        uninstall_guard(original=original)
-
-
-def pytest_report_header(config: pytest.Config) -> str:
-    path = config.stash.get(config_path_key, None)
-    if path is None:
-        return "orm-boundaries: no config file, checks disabled"
-    return f"orm-boundaries: config {path}"