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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pytest-orm-boundaries
-Version: 0.3.0
+Version: 0.4.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
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
 Requires-Dist: pytest>=8
+Requires-Dist: sqlglot>=30,<31
 Requires-Python: >=3.11
 Project-URL: Homepage, https://github.com/evchibisova/pytest-orm-boundaries
 Project-URL: Repository, https://github.com/evchibisova/pytest-orm-boundaries
@@ -41,9 +42,9 @@ lookups make it easy to cross those boundaries silently:
 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.
+`pytest-orm-boundaries` watches the SQL your test suite executes and reports the
+queries that step outside their aggregate — whether through `__` lookups,
+`select_related`, subqueries, or hand-written `.raw()` SQL.
 
 ## Install
 
@@ -68,6 +69,50 @@ 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.
 
+## What it catches
+
+The plugin works from the SQL your suite actually executes, so it flags any
+single statement that reads tables from two different aggregates - however the
+query was written. Each example below joins the `purchase` and `client` aggregates:
+
+- `__` relation lookups:
+
+  ```python
+  Purchase.objects.get(client__name="John")
+  ```
+
+- `select_related`
+
+  ```python
+  Purchase.objects.select_related("client")
+  ```
+
+- Subqueries - a table reached through a subquery still counts:
+
+  ```python
+  berlin_clients = Client.objects.filter(city="Berlin").values("id")
+  Purchase.objects.filter(client_id__in=berlin_clients)
+  ```
+
+- Hand-written `.raw()` SQL:
+
+  ```python
+  Purchase.objects.raw(
+      "SELECT p.id FROM bookshop_purchase p "
+      "JOIN bookshop_client c ON p.client_id = c.id"
+  )
+  ```
+
+- Bare `cursor.execute()` - the same join reached through a raw cursor.
+
+Queries that don't actually join across the boundary are **not** flagged — for
+example a foreign-key lookup by id, which Django resolves without a join:
+
+```python
+Purchase.objects.filter(client_id=42)     # reads one table
+Purchase.objects.filter(client__pk=42)    # Django trims the join
+```
+
 ## The report
 
 At the end of the run, the plugin prints one grouped entry per offending place:
@@ -76,17 +121,18 @@ 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
+bookshop/reports.py:13
+    crossed aggregates: client ↔ purchase
+    models: bookshop.Client, bookshop.Purchase
+    1 test(s) affected:
+      test_purchases.py::test_list_purchases_with_client
 
 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.
+Each entry names the aggregates the query crossed and the models it joined.
+Places are ordered by how many tests they affect. Pass `-v` to see every affected test
+(otherwise the list is capped at 5 per place).
 
 ## Ignoring files
 
@@ -116,6 +162,10 @@ Remove them from boundaries.toml:
   - app/billing.py
 ```
 
+## Known gaps
+
+- `prefetch_related` loads doesn't detected in current version.
+
 ## Status
 
 Alpha - testing basic version.

{pytest_orm_boundaries-0.3.0 → pytest_orm_boundaries-0.4.0}/README.md

@@ -15,9 +15,9 @@ lookups make it easy to cross those boundaries silently:
 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.
+`pytest-orm-boundaries` watches the SQL your test suite executes and reports the
+queries that step outside their aggregate — whether through `__` lookups,
+`select_related`, subqueries, or hand-written `.raw()` SQL.
 
 ## Install
 
@@ -42,6 +42,50 @@ 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.
 
+## What it catches
+
+The plugin works from the SQL your suite actually executes, so it flags any
+single statement that reads tables from two different aggregates - however the
+query was written. Each example below joins the `purchase` and `client` aggregates:
+
+- `__` relation lookups:
+
+  ```python
+  Purchase.objects.get(client__name="John")
+  ```
+
+- `select_related`
+
+  ```python
+  Purchase.objects.select_related("client")
+  ```
+
+- Subqueries - a table reached through a subquery still counts:
+
+  ```python
+  berlin_clients = Client.objects.filter(city="Berlin").values("id")
+  Purchase.objects.filter(client_id__in=berlin_clients)
+  ```
+
+- Hand-written `.raw()` SQL:
+
+  ```python
+  Purchase.objects.raw(
+      "SELECT p.id FROM bookshop_purchase p "
+      "JOIN bookshop_client c ON p.client_id = c.id"
+  )
+  ```
+
+- Bare `cursor.execute()` - the same join reached through a raw cursor.
+
+Queries that don't actually join across the boundary are **not** flagged — for
+example a foreign-key lookup by id, which Django resolves without a join:
+
+```python
+Purchase.objects.filter(client_id=42)     # reads one table
+Purchase.objects.filter(client__pk=42)    # Django trims the join
+```
+
 ## The report
 
 At the end of the run, the plugin prints one grouped entry per offending place:
@@ -50,17 +94,18 @@ 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
+bookshop/reports.py:13
+    crossed aggregates: client ↔ purchase
+    models: bookshop.Client, bookshop.Purchase
+    1 test(s) affected:
+      test_purchases.py::test_list_purchases_with_client
 
 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.
+Each entry names the aggregates the query crossed and the models it joined.
+Places are ordered by how many tests they affect. Pass `-v` to see every affected test
+(otherwise the list is capped at 5 per place).
 
 ## Ignoring files
 
@@ -90,6 +135,10 @@ Remove them from boundaries.toml:
   - app/billing.py
 ```
 
+## Known gaps
+
+- `prefetch_related` loads doesn't detected in current version.
+
 ## Status
 
 Alpha - testing basic version.

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pytest-orm-boundaries"
-version = "0.3.0"
+version = "0.4.0"
 description = "Pytest plugin that fails tests when ORM queries cross DDD aggregate boundaries (Django supported today)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -33,7 +33,7 @@ classifiers = [
     "Topic :: Software Development :: Quality Assurance",
     "Topic :: Software Development :: Testing",
 ]
-dependencies = ["pytest>=8"]
+dependencies = ["pytest>=8", "sqlglot>=30,<31"]
 
 [project.urls]
 Homepage = "https://github.com/evchibisova/pytest-orm-boundaries"
@@ -44,6 +44,9 @@ Changelog = "https://github.com/evchibisova/pytest-orm-boundaries/blob/main/CHAN
 [project.entry-points.pytest11]
 boundaries = "pytest_orm_boundaries.plugin"
 
+[tool.uv]
+exclude-newer = "2 weeks"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/call_stack.py → pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/callstack.py

@@ -15,7 +15,7 @@ def _is_third_party(*, relative: Path) -> bool:
     return not _THIRD_PARTY_SEGMENTS.isdisjoint(relative.parts)
 
 
-def find_in_project_frames(*, root: Path) -> list[tuple[str, int]]:
+def find_frames_inside_project(*, 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

pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/guard.py

@@ -0,0 +1,193 @@
+"""Django boundary guard: applies the aggregate-crossing rule to the queries a
+test suite executes and records the crossings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from pytest_orm_boundaries.callstack import find_frames_inside_project
+from pytest_orm_boundaries.config import (
+    load_aggregates_from_config,
+    load_ignored_files_from_config,
+)
+from pytest_orm_boundaries.ignores import IgnoreTracker
+from pytest_orm_boundaries.model_resolution import resolve_labels
+from pytest_orm_boundaries.sql_parsing import extract_table_names, looks_like_data_query
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from django.db.backends.base.base import BaseDatabaseWrapper
+
+
+@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
+    crossed_aggregates: tuple[str, ...]  # ("order", "payment")
+    joined_models: tuple[str, ...]  # ("order.Invoice", "payrolls.IncomePayment")
+    tests: set[str] = field(default_factory=set)
+
+
+class BoundaryGuard:
+    """Records aggregate crossings in the queries a test suite executes."""
+
+    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 = Path(root)
+        self._current_test: str | None = None
+        self._violations: dict[tuple[str, int, tuple[str, ...]], ViolationRecord] = {}
+        self._attached_connections: list[BaseDatabaseWrapper] = []
+
+    def install(self) -> None:
+        """Attach to every DB connection: those open now and any opened later
+        (each new connection fires ``connection_created``).
+        """
+        from django.db import connections
+        from django.db.backends.signals import connection_created
+
+        connection_created.connect(self._handle_connection_created, weak=False)
+        for connection in connections.all(initialized_only=True):
+            self._attach_wrapper(connection)
+
+    def uninstall(self) -> None:
+        from django.db.backends.signals import connection_created
+
+        connection_created.disconnect(self._handle_connection_created)
+        for connection in self._attached_connections:
+            try:
+                connection.execute_wrappers.remove(self._execute_wrapper)
+            except ValueError:
+                pass
+        self._attached_connections.clear()
+
+    def _handle_connection_created(
+        self, *, connection: BaseDatabaseWrapper, **_
+    ) -> None:
+        self._attach_wrapper(connection)
+
+    def _attach_wrapper(self, connection: BaseDatabaseWrapper) -> None:
+        if self._execute_wrapper not in connection.execute_wrappers:
+            connection.execute_wrappers.append(self._execute_wrapper)
+            self._attached_connections.append(connection)
+
+    def _execute_wrapper(self, execute, sql, params, many, context):
+        if looks_like_data_query(sql):
+            self._check_violations_in_query(sql, context["connection"].vendor)
+        return execute(sql, params, many, context)
+
+    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]:
+        """Recorded crossings, most-affecting first (then by call place)."""
+        return sorted(
+            self._violations.values(),
+            key=lambda v: (-len(v.tests), v.file, v.line_number),
+        )
+
+    def find_stale_patterns(self) -> list[str]:
+        return self._ignore_tracker.find_stale_patterns()
+
+    def _check_violations_in_query(self, sql: str, vendor: str) -> None:
+        """Handle one executed data query: gather stack context, apply the
+        aggregate rule, and record a crossing (unless it's clean or 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: set[str] | None = None
+        if self._ignore_tracker.is_active:
+            frames = find_frames_inside_project(root=self._root_path)
+            file_paths = {path for path, _ in frames}
+            self._ignore_tracker.mark_seen(file_paths=file_paths)
+
+        table_names = extract_table_names(sql, vendor)
+        if table_names is None:  # unparseable data query -- skip it (see ROADMAP)
+            return
+        labels = resolve_labels(table_names)
+        crossing = self._find_crossing(labels=labels)
+        if crossing 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_frames_inside_project(root=self._root_path)
+        self._record_violation(
+            call_place=frames[0] if frames else None, crossing=crossing
+        )
+
+    def _find_crossing(
+        self, *, labels: Iterable[str]
+    ) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
+        """Return ``(crossed aggregate names, joined model labels)`` if the query
+        crosses a boundary, else None.
+
+        e.g. ``(("order", "payment"), ("order.Invoice", "payrolls.IncomePayment"))``.
+        """
+        aggregate_by_label = {
+            label: aggregate
+            for label in labels
+            if (aggregate := self._aggregates_config.get(label.lower())) is not None
+        }
+        aggregates = set(aggregate_by_label.values())
+        if len(aggregates) <= 1:
+            return None
+        return tuple(sorted(aggregates)), tuple(sorted(aggregate_by_label.keys()))
+
+    def _record_violation(
+        self,
+        *,
+        call_place: tuple[str, int] | None,
+        crossing: tuple[tuple[str, ...], tuple[str, ...]],
+    ) -> None:
+        crossed_aggregates, joined_models = crossing
+        file, line = call_place if call_place is not None else ("<unknown>", 0)
+        key = (file, line, crossed_aggregates)
+        record = self._violations.get(key)
+        if record is None:
+            record = ViolationRecord(
+                file=file,
+                line_number=line,
+                crossed_aggregates=crossed_aggregates,
+                joined_models=joined_models,
+            )
+            self._violations[key] = record
+        if self._current_test is not None:
+            record.tests.add(self._current_test)
+
+
+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
+    )

pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/model_resolution.py

@@ -0,0 +1,29 @@
+"""Resolve Django model labels for the table names a query reads."""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from django.db.models import Model
+
+
+def resolve_labels(table_names: Iterable[str]) -> list[str]:
+    """Resolve model labels for the given table names, dropping unmapped names."""
+    table_to_model = map_tables_to_models()
+    return [
+        table_to_model[table]._meta.label
+        for table in table_names
+        if table in table_to_model
+    ]
+
+
+@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 → pytest_orm_boundaries-0.4.0}/src/pytest_orm_boundaries/plugin.py

@@ -7,13 +7,13 @@ 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 (
+from pytest_orm_boundaries import report
+from pytest_orm_boundaries.config import (
     CONFIG_FILE_NAME,
     BoundariesConfigError,
     discover_config_path,
 )
+from pytest_orm_boundaries.guard import build_guard
 
 if TYPE_CHECKING:
     from pytest_orm_boundaries.guard import BoundaryGuard
@@ -108,15 +108,15 @@ def pytest_terminal_summary(
     guard = _installed_guard(config)
     if guard is None:
         return
-    build_report.report_violations(
+    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)
+    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)
+    return report.render_header(config_path=config_path)

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/build_report.py → pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/report.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from pytest_orm_boundaries.read_config import CONFIG_FILE_NAME
+from pytest_orm_boundaries.config import CONFIG_FILE_NAME
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -13,7 +13,7 @@ if TYPE_CHECKING:
 
     from pytest_orm_boundaries.guard import ViolationRecord
 
-MAX_TESTS_SHOWN = 20
+MAX_TESTS_SHOWN = 5
 
 
 def report_violations(
@@ -22,8 +22,8 @@ def report_violations(
     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.
+    """Print one grouped entry per offending call place: which aggregates the
+    query crossed, the models it joined, and which tests reached it.
     """
     if not violations:
         return
@@ -58,23 +58,26 @@ def _write_violation(
 ) -> 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}")
+    aggregates = " ↔ ".join(violation.crossed_aggregates)
+    terminalreporter.write_line(
+        f"    crossed aggregates: {aggregates}", yellow=True, bold=True
+    )
+    models = ", ".join(violation.joined_models)
+    terminalreporter.write_line(f"    models: {models}")
 
     tests = sorted(violation.tests)
     if not tests:
-        terminalreporter.write_line("    affected tests: (none captured)")
+        terminalreporter.write_line("    tests affected: (none captured)", light=True)
         return
 
     shown = tests if verbose else tests[:MAX_TESTS_SHOWN]
-    terminalreporter.write_line(f"    affected tests ({len(tests)}):")
+    terminalreporter.write_line(f"    {len(tests)} test(s) affected:", light=True)
     for nodeid in shown:
-        terminalreporter.write_line(f"      {nodeid}")
+        terminalreporter.write_line(f"      {nodeid}", light=True)
     hidden = len(tests) - len(shown)
     if hidden:
         terminalreporter.write_line(
-            f"      ... +{hidden} more (run with -v to list all)"
+            f"      ... +{hidden} more (-v to list all)", light=True
         )
 
 

pytest_orm_boundaries-0.4.0/src/pytest_orm_boundaries/sql_parsing.py

@@ -0,0 +1,58 @@
+"""Read the tables a SQL statement touches by parsing the SQL text."""
+
+from __future__ import annotations
+
+import functools
+import re
+
+import sqlglot
+from sqlglot import expressions as exp
+from sqlglot.errors import SqlglotError
+
+# Decreasing amount of work - only these statements read tables,
+# transaction control, PRAGMA and DDL are ignored before we bother parsing.
+_DATA_QUERY = re.compile(
+    r"\s*(?:WITH|SELECT|INSERT|UPDATE|DELETE|REPLACE|MERGE)\b", re.IGNORECASE
+)
+
+# Django backend vendor -> sqlglot dialect; unmapped vendors parse dialect-free.
+_DIALECT_BY_VENDOR = {
+    "sqlite": "sqlite",
+    "postgresql": "postgres",
+    "mysql": "mysql",
+    "oracle": "oracle",
+}
+
+
+def looks_like_data_query(sql: str) -> bool:
+    """Whether the statement is one that can read tables (worth parsing)."""
+    return _DATA_QUERY.match(sql) is not None
+
+
+def _blank_placeholders(sql: str) -> str:
+    """Replace ``%s`` / ``%(name)s`` placeholders with a literal so the SQL parses,
+    leaving any placeholder-looking text inside quoted strings untouched.
+    """
+    placeholder = re.compile(r"""('(?:[^']|'')*')|("(?:[^"]|"")*")|(%\(\w+\)s|%s)""")
+
+    return placeholder.sub(
+        lambda match: "NULL" if match.group(3) else match.group(0), sql
+    )
+
+
+@functools.lru_cache(maxsize=4096)
+def extract_table_names(sql: str, vendor: str) -> frozenset[str] | None:
+    """Names of the tables the statement reads, or None if it could not be parsed."""
+    dialect = _DIALECT_BY_VENDOR.get(vendor)
+    blanked_sql = _blank_placeholders(sql)
+    try:
+        tree = sqlglot.parse_one(blanked_sql, dialect=dialect)
+    except (SqlglotError, RecursionError):
+        return None
+    if tree is None:
+        return frozenset()
+    # common table expression - can be named as an existed table, but it is not a table
+    # e.g. `report` in ` WITH report AS (SELECT id FROM orders WHERE created > '2026-01-01')
+    cte_names = {cte.alias_or_name for cte in tree.find_all(exp.CTE)}
+    tables = {table.name for table in tree.find_all(exp.Table)}
+    return frozenset(tables - cte_names)

pytest_orm_boundaries-0.3.0/src/pytest_orm_boundaries/guard.py

@@ -1,185 +0,0 @@
-"""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()}