From 72252a1c04fb40c2ce780aab29ed4e4b3f5d8a87 Mon Sep 17 00:00:00 2001 From: Wolf Date: Wed, 30 Sep 2026 15:52:38 +0200 Subject: [PATCH] Hold plugins/readers/ to its contract, helpers, the standard library, httpx and pydantic Co-Authored-By: Claude Fable 5.1 --- tests/test_architecture.py | 68 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/tests/test_architecture.py b/tests/test_architecture.py index 58d46d7..5440c6f 100644 --- a/tests/test_architecture.py +++ b/tests/test_architecture.py @@ -12,6 +12,11 @@ file holds `app`'s own layers. there the door is the tool: `desk.tools.`, one level, no deeper. 3. **Plugins.** A file under `plugins/` imports `desk` and nothing else from these trees. A plugin is app-agnostic; it never sees `app`. +4. **Readers.** A file of `plugins/readers/` imports the standard library, + `httpx`, `pydantic`, `desk` through its doors and, within the package, + `._contract`, `._shared` and `._countries` only: a reader shares no code + with another reader, nor with `_runner`, which reads the readers and so + alone may import the package's registry, `plugins.readers`. Tests are held to none of this. """ @@ -21,6 +26,7 @@ from __future__ import annotations import ast import importlib import importlib.util +import sys from pathlib import Path import pytest @@ -88,6 +94,13 @@ def _package(path: Path) -> str: APP_FILES = sorted(p for p in (ROOT / APP).rglob("*.py") if "__pycache__" not in p.parts) PLUGIN_FILES = sorted((ROOT / "plugins").glob("*.py")) +READER_FILES = sorted((ROOT / "plugins" / "readers").glob("*.py")) + +#: What a reader may import beside the standard library and `desk`. +READER_THIRD_PARTY = frozenset({"httpx", "pydantic"}) + +#: The package's own modules a reader may import. +READER_SIBLINGS = frozenset({"_contract", "_shared", "_countries"}) def _outside(here: str, source: str): @@ -120,6 +133,38 @@ def plugin_violations(source: str) -> list[str]: return wrong +def reader_violations(source: str, registry: bool = False) -> list[str]: + """Every import in a file of `plugins/readers/` outside rule 4; + `registry` allows `from plugins import readers`, for `_runner`.""" + wrong = [] + for node in ast.walk(ast.parse(source)): + if registry and isinstance(node, ast.ImportFrom) and node.level == 0 \ + and node.module == "plugins" and [a.name for a in node.names] == ["readers"]: + continue + if isinstance(node, ast.Import): + tops = [(a.name.split(".")[0], a.name) for a in node.names] + elif isinstance(node, ast.ImportFrom) and node.level == 0: + tops = [((node.module or "").split(".")[0], node.module or "")] + elif isinstance(node, ast.ImportFrom): + names = {node.module} if node.module else {a.name for a in node.names} + if node.level != 1 or not names <= READER_SIBLINGS: + wrong.append(f"line {node.lineno}: {'.' * node.level}{node.module or ''} " + f"{sorted(names)} (a reader imports {', '.join(sorted(READER_SIBLINGS))})") + continue + else: + continue + for top, module in tops: + if top == "desk": + if isinstance(node, ast.ImportFrom) and ( + reason := _door_violation(module, [a.name for a in node.names + if not _is_module(f"{module}.{a.name}")])): + wrong.append(f"line {node.lineno}: {module} ({reason})") + elif top not in sys.stdlib_module_names and top not in READER_THIRD_PARTY: + wrong.append(f"line {node.lineno}: {module} (a reader imports the standard " + f"library, httpx, pydantic and desk)") + return wrong + + @pytest.mark.parametrize("path", APP_FILES, ids=lambda p: str(p.relative_to(ROOT))) def test_a_package_imports_only_from_below_it(path: Path) -> None: wrong = direction_violations(_package(path), path.read_text(encoding="utf-8")) @@ -141,6 +186,12 @@ def test_a_plugin_knows_only_desk(path: Path) -> None: assert not wrong, "\n".join(wrong) +@pytest.mark.parametrize("path", READER_FILES, ids=lambda p: p.name) +def test_a_reader_knows_only_its_contract_and_helpers(path: Path) -> None: + wrong = reader_violations(path.read_text(encoding="utf-8"), path.name == "_runner.py") + assert not wrong, "\n".join(wrong) + + def test_the_rules_catch_what_they_are_for() -> None: """The checker itself, on sources that break each rule.""" assert plugin_violations("from app.storage import Store") @@ -148,6 +199,23 @@ def test_the_rules_catch_what_they_are_for() -> None: assert plugin_violations("from desk.sources.base import Source") assert not plugin_violations("from desk.sources import Source, Item") + assert reader_violations("from plugins import ats") + assert reader_violations("from plugins import readers") + assert not reader_violations("from plugins import readers", registry=True) + assert reader_violations("from plugins import ats", registry=True) + assert reader_violations("from app.prep import words") + assert reader_violations("from . import _runner") + assert reader_violations("from ._runner import fetch") + assert reader_violations("from .lever import parse") + assert reader_violations("from .. import ats") + assert reader_violations("import requests") + assert reader_violations("from desk.sources.base import Source") + assert not reader_violations("import json\nfrom urllib.parse import quote\nimport httpx\n" + "from pydantic import ConfigDict\n" + "from desk.sources import strip_html\n" + "from . import _contract\nfrom ._shared import only\n" + "from ._countries import code_of") + assert direction_violations("storage", "from app.web import TABS") assert direction_violations("web", "from app.main import create_app") assert not direction_violations("main", "from app.web import pages_router")