python-checks 0.1.0__py3-none-any.whl

py_checks/checks/database/_schema_drift.py

@@ -0,0 +1,271 @@
+"""Схема, которую строят миграции, и схема, которую описывают модели."""
+
+from __future__ import annotations
+
+import os
+import subprocess  # noqa: S404 — правило состоит в том, чтобы позвать alembic
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks.database._marker import MARKER
+from py_checks.config import CheckSettings
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterator, Sequence
+
+CODE: Final = "schema-drift"
+
+# Чем alembic отвечает, когда дописывать нечего.
+IN_STEP: Final = "No new upgrade operations detected"
+
+# Так выходит удавшаяся команда; к коду выхода самой библиотеки это отношения
+# не имеет.
+DONE: Final = 0
+
+DATABASE: Final = "drift.db"
+
+
+class SchemaDriftSettings(CheckSettings):
+    versions: Path = Path("migrations/versions")
+    models: str = "src/*/infra/database/models"
+    variable: str = "DATABASE_URL"
+    url: str = "sqlite+aiosqlite:///{path}"
+    alembic: tuple[str, ...] = ("alembic",)
+
+
+class DriftError(RuntimeError):
+    """Правило не дошло до вердикта.
+
+    Своя ошибка, чтобы «не удалось посмотреть» никогда не читалось как
+    «смотреть не на что»: молчание правила означает, что расхождения нет.
+    """
+
+
+class SchemaDrift:
+    """Падает, если модели и миграции описывают уже разные схемы.
+
+    Модель поменяли, ревизию не написали — и дальше всё зависит от того, где
+    код встретится со схемой. Тесты на своей базе, поднятой из метаданных,
+    зелены; прод поднят миграциями и не знает о колонке, которой модель уже
+    пользуется. Расхождение всплывает не в ревью, а в первом запросе после
+    выкатки.
+
+    Статикой это не видно: одна схема написана декларациями, вторая — историей
+    правок, и сравнивает их только тот, кто умеет обе выполнить. Поэтому
+    правило поднимает свою пустую базу во временной директории, накатывает её
+    до `head` и спрашивает `alembic check`, что он дописал бы сам. Своя, а не
+    база разработчика: та стоит на ревизии, на которой её оставили, — ровно то
+    состояние, которому правило и не верит.
+
+    Живая база и запуск alembic — причина, по которой правило объявлено
+    `ENVIRONMENT`: в хуке на коммит ему не место. Его зовут в CI —
+    `py-checks run --all` или `--select schema-drift`.
+
+    Две оговорки. `env.py` проекта обязан читать адрес базы из переменной
+    окружения (`variable`): если он берёт его из своих настроек, правило
+    подсунуть пустую базу не может и накатит миграции на ту, что найдёт.
+    Адрес по умолчанию — SQLite, а ему нужен установленный `aiosqlite`; где
+    его нет, в `url` пишут адрес одноразовой базы CI.
+
+    Настройки: `versions`, `models`, `variable`, `url`, `alembic`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = SchemaDriftSettings
+    scope: ClassVar[Scope] = Scope.ENVIRONMENT
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        root: Path,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=SchemaDriftSettings,
+            code=CODE,
+        )
+        revisions = cls._revisions(
+            root=root,
+            limits=limits,
+        )
+        models = cls._models(
+            root=root,
+            limits=limits,
+        )
+        if not revisions and not models:
+            return
+        try:
+            found = cls._compared(
+                root=root,
+                limits=limits,
+            )
+        except DriftError as broken:
+            yield cls._violation(
+                root=root,
+                limits=limits,
+                message=str(broken),
+            )
+            return
+        if found is not None:
+            yield cls._violation(
+                root=root,
+                limits=limits,
+                message=cls._joined(
+                    lines=(
+                        "модели описывают схему, которую миграции не строят",
+                        found,
+                        "напиши ревизию: `alembic revision --autogenerate`, "
+                        "потом прочитай, что она пишет",
+                    ),
+                ),
+            )
+
+    @classmethod
+    def _compared(
+        cls,
+        *,
+        root: Path,
+        limits: SchemaDriftSettings,
+    ) -> str | None:
+        """Что alembic дописал бы к истории, или `None`, когда дописывать нечего."""
+        with cls._database() as path:
+            url = limits.url.format(path=path)
+            cls._migrated(
+                root=root,
+                url=url,
+                limits=limits,
+            )
+            return cls._behind(
+                root=root,
+                url=url,
+                limits=limits,
+            )
+
+    @staticmethod
+    def _revisions(
+        *,
+        root: Path,
+        limits: SchemaDriftSettings,
+    ) -> Sequence[Path]:
+        versions = root / limits.versions
+        if not versions.is_dir():
+            return ()
+        return sorted(path for path in versions.rglob("*.py") if path.name != "__init__.py")
+
+    @staticmethod
+    def _models(
+        *,
+        root: Path,
+        limits: SchemaDriftSettings,
+    ) -> Sequence[Path]:
+        return sorted(
+            path
+            for directory in root.glob(limits.models)
+            for path in directory.rglob("*.py")
+            if path.name != "__init__.py"
+        )
+
+    @staticmethod
+    @contextmanager
+    def _database() -> Generator[Path]:
+        try:
+            with tempfile.TemporaryDirectory() as directory:
+                yield Path(directory) / DATABASE
+        except OSError as unwritable:
+            raise DriftError(f"негде держать базу: {unwritable}") from unwritable
+
+    @classmethod
+    def _migrated(
+        cls,
+        *,
+        root: Path,
+        url: str,
+        limits: SchemaDriftSettings,
+    ) -> None:
+        """Поднять пустую базу до `head` или сказать, почему не вышло."""
+        upgraded = cls._finished(
+            command=(*limits.alembic, "upgrade", "head"),
+            root=root,
+            url=url,
+            limits=limits,
+        )
+        if upgraded.returncode != DONE:
+            raise DriftError(
+                cls._joined(
+                    lines=(
+                        f"`alembic upgrade head` вышел с {upgraded.returncode}",
+                        cls._said(finished=upgraded),
+                    ),
+                )
+            )
+
+    @classmethod
+    def _behind(
+        cls,
+        *,
+        root: Path,
+        url: str,
+        limits: SchemaDriftSettings,
+    ) -> str | None:
+        checked = cls._finished(
+            command=(*limits.alembic, "check"),
+            root=root,
+            url=url,
+            limits=limits,
+        )
+        if checked.returncode == DONE or IN_STEP in checked.stdout:
+            return None
+        return cls._said(finished=checked)
+
+    @staticmethod
+    def _finished(
+        *,
+        command: tuple[str, ...],
+        root: Path,
+        url: str,
+        limits: SchemaDriftSettings,
+    ) -> subprocess.CompletedProcess[str]:
+        """alembic зовётся тем же именем, что и в окружении вызвавшего.
+
+        Прогон уже идёт из окружения проекта, и второй `uv run` внутри него
+        пересобрал бы это окружение посреди проверки.
+        """
+        return subprocess.run(  # noqa: S603 — список аргументов собран здесь же
+            command,
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=False,
+            env=os.environ | {limits.variable: url},
+        )
+
+    @staticmethod
+    def _said(*, finished: subprocess.CompletedProcess[str]) -> str:
+        return finished.stderr.strip() or finished.stdout.strip()
+
+    @staticmethod
+    def _joined(*, lines: tuple[str, ...]) -> str:
+        """Строки сообщения без пустых: молчаливый alembic не должен добавлять пустую."""
+        return "\n".join(line for line in lines if line)
+
+    @staticmethod
+    def _violation(
+        *,
+        root: Path,
+        limits: SchemaDriftSettings,
+        message: str,
+    ) -> Violation:
+        """Нарушение указывает на папку ревизий: там же и починка — новой ревизией."""
+        return Violation(
+            path=root / limits.versions,
+            line=1,
+            column=1,
+            code=CODE,
+            message=message,
+        )

py_checks/checks/database/_statement_keys.py

@@ -0,0 +1,169 @@
+"""Запрос называет колонку атрибутом, а не строкой, и ходит в базу один раз."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import ZonedSettings, zoned
+from py_checks.checks._names import name
+from py_checks.checks.database._marker import MARKER
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from py_checks.config import CheckSettings
+    from py_checks.core import ParsedFile
+
+CODE: Final = "statement-keys"
+
+SAID: Final = "называет колонку строкой; маппед-атрибут переезжает вместе с ней"
+
+
+class StatementKeysSettings(ZonedSettings):
+    lists: tuple[str, ...] = ("index_elements",)
+    mappings: tuple[str, ...] = ("set_",)
+    calls: tuple[str, ...] = ("from_select",)
+    loops: tuple[str, ...] = ("execute",)
+
+
+class StatementKeys:
+    """Падает, если запрос называет колонку строкой или ходит в базу в цикле.
+
+    Строки собираются через модели, поэтому список колонок держит pyright:
+    пропущенная колонка — пропущенный аргумент, переименованная — неожиданное
+    ключевое слово. Строковый ключ в `index_elements=[...]`, `set_={...}` или
+    `from_select` открывает дыру заново: он ничего не совпадает во время
+    проверки и либо падает, либо молча перестаёт совпадать на той строке, что
+    выполняется.
+
+    `index_elements` и `set_` вместе — это `ON CONFLICT DO UPDATE`, то есть
+    inbox и каждый upsert. Строка, переставшая там совпадать, не поднимает
+    исключения: конфликт просто не находится, дубль вставляется второй раз, и
+    идемпотентность — то, ради чего inbox и существует, — тихо кончается.
+
+    Второе правило: `execute(...)` внутри цикла — это поход в базу на итерацию,
+    форма N+1. Сто ставок — сто поездок туда и обратно там, где хватило бы
+    одного запроса по всему множеству. Иногда цикл честен — три константы, и
+    одного запроса, говорящего то же самое, не существует, — поэтому правило
+    снимается пометкой на строке цикла или самого вызова, а не отсутствует.
+
+    Настройки: `zones`, `lists`, `mappings`, `calls`, `loops`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = StatementKeysSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=StatementKeysSettings,
+            code=CODE,
+        )
+        where = zoned(
+            file=file,
+            zones=limits.zones,
+        )
+        if where is None:
+            return
+        for node in ast.walk(file.tree):
+            if isinstance(node, ast.Call):
+                yield from cls._keys(
+                    file=file,
+                    node=node,
+                    limits=limits,
+                )
+            if isinstance(node, ast.For | ast.AsyncFor | ast.While):
+                yield from cls._loop(
+                    file=file,
+                    node=node,
+                    limits=limits,
+                )
+
+    @classmethod
+    def _keys(
+        cls,
+        *,
+        file: ParsedFile,
+        node: ast.Call,
+        limits: StatementKeysSettings,
+    ) -> Iterator[Violation]:
+        for keyword in node.keywords:
+            if keyword.arg in limits.lists:
+                yield from cls._strings(
+                    file=file,
+                    written=keyword.arg,
+                    nodes=cls._elements(node=keyword.value),
+                )
+            if keyword.arg in limits.mappings:
+                yield from cls._strings(
+                    file=file,
+                    written=keyword.arg,
+                    nodes=cls._keyed(node=keyword.value),
+                )
+        if name(node=node.func) in limits.calls and node.args:
+            yield from cls._strings(
+                file=file,
+                written=name(node=node.func),
+                nodes=cls._elements(node=node.args[0]),
+            )
+
+    @staticmethod
+    def _loop(
+        *,
+        file: ParsedFile,
+        node: ast.For | ast.AsyncFor | ast.While,
+        limits: StatementKeysSettings,
+    ) -> Iterator[Violation]:
+        """Поход в базу на каждой итерации."""
+        for child in ast.walk(node):
+            if not isinstance(child, ast.Call) or name(node=child.func) not in limits.loops:
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                # Пометка снимается со строки цикла или с любой строки вызова:
+                # причина принадлежит тому месту, где автор её и пишет.
+                end_line=child.end_lineno or child.lineno,
+                message=(
+                    f"{name(node=child.func)}() внутри цикла — поход в базу на итерацию; "
+                    f"один запрос по всему множеству говорит то же самое"
+                ),
+            )
+
+    @staticmethod
+    def _strings(
+        *,
+        file: ParsedFile,
+        written: str,
+        nodes: Iterator[ast.expr],
+    ) -> Iterator[Violation]:
+        for node in nodes:
+            if not isinstance(node, ast.Constant) or not isinstance(node.value, str):
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=f"{written}: {SAID}",
+            )
+
+    @staticmethod
+    def _elements(*, node: ast.expr) -> Iterator[ast.expr]:
+        if isinstance(node, ast.List | ast.Tuple | ast.Set):
+            yield from node.elts
+
+    @staticmethod
+    def _keyed(*, node: ast.expr) -> Iterator[ast.expr]:
+        if isinstance(node, ast.Dict):
+            yield from (key for key in node.keys if key is not None)

py_checks/checks/effects/__init__.py

@@ -0,0 +1,19 @@
+"""Эффекты: что код берёт у мира и что он о мире говорит.
+
+Часы, случайность и новый идентификатор берутся портом, а не глобальной
+функцией: иначе один и тот же вход даёт разный выход, и тест либо замораживает
+мир мокой, либо не утверждает ничего. Строка лога называет событие членом
+перечисления: это имя читает не человек, а счётчик и алерт.
+"""
+
+from py_checks.checks.effects._determinism import Determinism, DeterminismSettings
+from py_checks.checks.effects._log_events import LogEvents, LogEventsSettings
+from py_checks.checks.effects._marker import MARKER
+
+__all__ = [
+    "MARKER",
+    "Determinism",
+    "DeterminismSettings",
+    "LogEvents",
+    "LogEventsSettings",
+]

py_checks/checks/effects/_determinism.py

@@ -0,0 +1,105 @@
+"""Часы, случайность и новый идентификатор берутся портом, а не глобально."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import ZonedSettings, zoned
+from py_checks.checks._names import matches
+from py_checks.checks.effects._marker import MARKER
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from py_checks.config import CheckSettings
+    from py_checks.core import ParsedFile
+
+CODE: Final = "determinism"
+
+
+class DeterminismSettings(ZonedSettings):
+    sources: dict[str, str] = {}  # noqa: RUF012 — pydantic копирует значение по умолчанию
+
+
+class Determinism:
+    """Падает, если код сам читает часы, случайность или новый идентификатор.
+
+    `datetime.now()`, `uuid4()` и `random.random()` делают сценарий
+    непроверяемым: один и тот же вход даёт разный выход, и тест либо
+    замораживает мир мокой, либо не утверждает ничего. Бизнес-код берёт их
+    зависимостью — `self._clock.now()`, идентификатор, выданный на краю, — и
+    вызов через порт правило не трогает: оно судит глобальные источники.
+
+    Репозитории закрыты той же зоной, и там источник пишется на SQL:
+    `func.gen_random_uuid()` внутри INSERT — то же решение этажом ниже, где его
+    ещё хуже видно. В тесте о нём нечего утверждать, слой хранения становится
+    автором идентификатора, о котором ему ничего не передавали, а среди uuid7
+    появляется uuid4 — случайный там, где все остальные упорядочены, и
+    упорядоченность — то, ради чего индекс по ним чего-то стоит.
+
+    Имя сверяется с хвостом: `datetime.now` подходит и записи
+    `datetime.datetime.now`, а `random.*` — любому вызову модуля целиком.
+
+    Настройки: `zones`, `sources`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = DeterminismSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=DeterminismSettings,
+            code=CODE,
+        )
+        where = zoned(
+            file=file,
+            zones=limits.zones,
+        )
+        if where is None or not limits.sources:
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.Call):
+                continue
+            called = ast.unparse(node.func)
+            said = cls._source(
+                called=called,
+                sources=limits.sources,
+            )
+            if said is None:
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=f"{called}() не детерминирован; {said}",
+            )
+
+    @staticmethod
+    def _source(
+        *,
+        called: str,
+        sources: dict[str, str],
+    ) -> str | None:
+        """Причина, по которой такой вызов запрещён, если он в таблице."""
+        return next(
+            (
+                said
+                for pattern, said in sources.items()
+                if matches(
+                    called=called,
+                    pattern=pattern,
+                )
+            ),
+            None,
+        )

py_checks/checks/effects/_log_events.py

@@ -0,0 +1,120 @@
+"""Строка лога называет событие членом перечисления, а не фразой."""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING, ClassVar, Final, Self
+
+from pydantic import model_validator
+
+from py_checks.checks.effects._marker import MARKER
+from py_checks.config import CheckSettings
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from py_checks.core import ParsedFile
+
+CODE: Final = "log-events"
+
+LEVELS: Final = ("debug", "info", "warning", "warn", "error", "exception", "critical")
+
+
+class LogEventsSettings(CheckSettings):
+    enum: str = "LogEvent"
+    levels: tuple[str, ...] = LEVELS
+    receiver: str = r"(^|_)log(ger)?$"
+
+    @model_validator(mode="after")
+    def _readable(self) -> Self:
+        try:
+            re.compile(self.receiver)
+        except re.error as broken:
+            message = f"receiver — регулярное выражение: {broken}"
+            raise ValueError(message) from broken
+        return self
+
+
+class LogEvents:
+    """Падает, если событие в логе названо чем-то кроме члена перечисления.
+
+    Имя события читает не человек: процессор в цепочке structlog превращает
+    `consumer.message.handled` в счётчик, а алерт джойнится по этой строке.
+    Литерал, написанный на месте вызова, определения не имеет, и код, который
+    имя ИЗДАЁТ, ничем не связан с кодом, который его ловит: опечатка не ломает
+    ни одного теста, она просто перестаёт совпадать, и метрика тихо читает
+    ноль.
+
+    Правило читает ФОРМУ `LogEvent.SOMETHING` и члена не ищет: имени, которого
+    в перечислении нет, pyright откажет, а без него это `AttributeError` на
+    первом же запуске — собирать члены значило бы ловить пойманное дважды.
+
+    Чужой логгер — библиотечный или тот, чьим словарём владеет другой проект, —
+    снимается пометкой: `# effect-ok: log-events: не наш логгер`.
+
+    Настройки: `enum`, `levels`, `receiver`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = LogEventsSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=LogEventsSettings,
+            code=CODE,
+        )
+        receiver = re.compile(limits.receiver)
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
+                continue
+            if node.func.attr not in limits.levels or not node.args:
+                continue
+            if not receiver.search(cls._receiver(node=node.func.value)):
+                continue
+            if cls._member(
+                node=node.args[0],
+                enum=limits.enum,
+            ):
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=(
+                    f"{ast.unparse(node.func)}({ast.unparse(node.args[0])}...): "
+                    f"имя события — член {limits.enum}, а не фраза; по нему джойнятся "
+                    f"счётчик и алерт"
+                ),
+            )
+
+    @staticmethod
+    def _receiver(*, node: ast.expr) -> str:
+        """Чей это метод: `logger`, `log`, `self._logger`, `_LOGGER`."""
+        match node:
+            case ast.Name(id=name) | ast.Attribute(attr=name):
+                return name
+            case _:
+                return ""
+
+    @staticmethod
+    def _member(
+        *,
+        node: ast.expr,
+        enum: str,
+    ) -> bool:
+        return (
+            isinstance(node, ast.Attribute)
+            and isinstance(node.value, ast.Name)
+            and node.value.id == enum
+        )

py_checks/checks/effects/_marker.py

@@ -0,0 +1,5 @@
+"""Слово группы для пометок: `# effect-ok: <код>: <причина>`."""
+
+from typing import Final
+
+MARKER: Final = "# effect-ok"