python-checks 0.1.0__py3-none-any.whl

py_checks/checks/database/_model_boundary.py

@@ -0,0 +1,236 @@
+"""ORM-модель не выходит за пределы слоя, который её понимает."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import place
+from py_checks.checks._names import name, walked
+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 Iterator
+
+    from py_checks.checks._location import Place
+    from py_checks.core import ParsedFile
+
+CODE: Final = "model-boundary"
+
+PRIVATE: Final = "_"
+DOT: Final = "."
+SEPARATOR: Final = "/"
+
+
+class ModelBoundarySettings(CheckSettings):
+    base: str = "Base"
+    declared: tuple[str, ...] = ()
+    built: tuple[str, ...] = ()
+
+
+class ModelBoundary:
+    """Падает, если ORM-модель объявлена, собрана или отдана не там.
+
+    Модель — это описание таблицы, и три правила держат её описанием.
+
+    Объявляется она там, где объявляются модели: где-то ещё это таблица,
+    которую никто не ждёт по этому адресу, а autogenerate alembic видит только
+    те модели, до которых дотянулись импорты их пакета.
+
+    Собирается она только в репозиториях: собрать модель — значит записать
+    строку, и модель, собранная в другом месте, либо не делает ничего — никто
+    снаружи не держит сессию, чтобы её добавить, — либо это строка, записанная
+    слоем, у которого нет транзакции, чтобы её записать.
+
+    Публичный метод репозитория её не возвращает. Модель уносит с собой
+    сессию: обращение к атрибуту после закрытия транзакции либо падает, либо
+    лезет в базу из слоя, которому туда нельзя, а через связи оттуда достижима
+    половина схемы, и запрос уходит из кода, который ни о каком соединении не
+    просил. Репозитории возвращают DTO, идентификаторы, количества — всё, с чем
+    слой базы уже закончил.
+
+    Модель узнаётся двумя способами, и оба видны в одном файле: объявление —
+    по базе `Base`, использование — по импорту из пакета моделей. Имя ни при
+    чём: `SettingsModel` в настройках и `DeviceModel` в домене — не таблицы.
+
+    Настройки: `base`, `declared`, `built`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ModelBoundarySettings
+    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=ModelBoundarySettings,
+            code=CODE,
+        )
+        where = place(file=file)
+        if where is None or not limits.declared:
+            return
+        models = cls._models(
+            file=file,
+            limits=limits,
+        )
+        found = [
+            *cls._declared(
+                file=file,
+                where=where,
+                limits=limits,
+            ),
+            *cls._built(
+                file=file,
+                where=where,
+                limits=limits,
+                models=models,
+            ),
+            *cls._returned(
+                file=file,
+                where=where,
+                limits=limits,
+                models=models,
+            ),
+        ]
+        yield from sorted(found, key=lambda violation: (violation.line, violation.column))
+
+    @classmethod
+    def _declared(
+        cls,
+        *,
+        file: ParsedFile,
+        where: Place,
+        limits: ModelBoundarySettings,
+    ) -> Iterator[Violation]:
+        """Модель, объявленная не в доме моделей."""
+        if where.anywhere(
+            zones=limits.declared,
+        ):
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            if any(name(node=base) == limits.base for base in node.bases):
+                yield Violation.from_node(
+                    node=node,
+                    path=file.path,
+                    code=CODE,
+                    message=(
+                        f"{node.name} объявлена вне {', '.join(limits.declared)}; "
+                        f"autogenerate видит только модели их пакета"
+                    ),
+                    end_line=node.body[0].lineno,
+                )
+
+    @classmethod
+    def _built(
+        cls,
+        *,
+        file: ParsedFile,
+        where: Place,
+        limits: ModelBoundarySettings,
+        models: frozenset[str],
+    ) -> Iterator[Violation]:
+        """Модель, собранная там, где нечем записать строку."""
+        if where.anywhere(
+            zones=limits.built + limits.declared,
+        ):
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.Call):
+                continue
+            built = name(node=node.func)
+            if built in models:
+                yield Violation.from_node(
+                    node=node,
+                    path=file.path,
+                    code=CODE,
+                    message=(
+                        f"{built}(...) собирается вне {', '.join(limits.built)}; "
+                        f"собрать модель — значит записать строку"
+                    ),
+                )
+
+    @classmethod
+    def _returned(
+        cls,
+        *,
+        file: ParsedFile,
+        where: Place,
+        limits: ModelBoundarySettings,
+        models: frozenset[str],
+    ) -> Iterator[Violation]:
+        """Модель, отданная наружу публичным методом репозитория."""
+        if not where.anywhere(
+            zones=limits.built,
+        ):
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                continue
+            if node.name.startswith(PRIVATE) or node.returns is None:
+                continue
+            returned = cls._named(
+                node=node.returns,
+                models=models,
+            )
+            if returned is None:
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=(
+                    f"{node.name} возвращает {returned}; модель уносит с собой сессию — "
+                    f"отдавай DTO, идентификатор, количество"
+                ),
+                end_line=node.body[0].lineno,
+            )
+
+    @classmethod
+    def _models(
+        cls,
+        *,
+        file: ParsedFile,
+        limits: ModelBoundarySettings,
+    ) -> frozenset[str]:
+        """Имена, пришедшие импортом из пакета моделей."""
+        names: set[str] = set()
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.ImportFrom) or node.module is None:
+                continue
+            if cls._home(
+                module=node.module,
+                zones=limits.declared,
+            ):
+                names.update(alias.asname or alias.name for alias in node.names)
+        return frozenset(names)
+
+    @staticmethod
+    def _home(
+        *,
+        module: str,
+        zones: tuple[str, ...],
+    ) -> bool:
+        path = SEPARATOR.join(module.split(DOT))
+        return any(
+            f"{SEPARATOR}{zone}{SEPARATOR}" in f"{SEPARATOR}{path}{SEPARATOR}" for zone in zones
+        )
+
+    @staticmethod
+    def _named(
+        *,
+        node: ast.expr,
+        models: frozenset[str],
+    ) -> str | None:
+        """Имя модели, названное где-нибудь внутри аннотации."""
+        return next((found for found in walked(node=node) if found in models), None)

py_checks/checks/database/_model_columns.py

@@ -0,0 +1,241 @@
+"""Из чего собрана колонка модели."""
+
+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 = "model-columns"
+
+MAPPED: Final = "Mapped"
+AWARE: Final = "timezone"
+NULLABLE: Final = "nullable"
+
+
+class ModelColumnsSettings(ZonedSettings):
+    factories: tuple[str, ...] = ("mapped_column", "Column")
+    types: dict[str, str] = {}
+    homes: dict[str, str] = {}
+    defaults: tuple[str, ...] = ()
+    unruled: tuple[str, ...] = ()
+    aware: tuple[str, ...] = ()
+    nullable: bool = True
+
+
+class ModelColumns:
+    """Падает, если колонка собрана не из того материала.
+
+    Пять правил на одну таблицу настроек.
+
+    `types` — материал, которому в колонке не место, и что писать вместо.
+    Голый `Enum` — нативный тип Postgres: каждый новый член требует `ALTER
+    TYPE`, а словари здесь чужие и расти будут. `Float` не держит цену точно, а
+    колонка — это состояние, и ошибка округления копится с каждой записью.
+    Голый `JSONB` — форма, которую никто не объявил: что положил писатель, то и
+    получит каждый читатель, а разбор, поймавший бы пропущенный ключ, случается
+    в каждом отдельно или нигде.
+
+    `homes` — модуль, которому этот материал называть можно: там живёт обёртка
+    над ним, и правило его не касается.
+
+    `defaults` — все способы, которыми колонка заполняет себя сама. Значение по
+    умолчанию — это значение, которого никто не писал: писатель пропустил
+    колонку, строка всё равно получила число, и пропуск, который на пропущенном
+    аргументе конструктора поймал бы проверяльщик типов, превращается в
+    правдоподобную строку.
+
+    `unruled` — встроенные типы в `Mapped[...]`. Такая колонка говорит, какой
+    у значения вид, и ничего — какие значения допустимы, так что правило
+    приходится помнить каждому писателю.
+
+    `aware` — типы времени, которым нужен `timezone=True`: без него колонка
+    хранит наивную метку, те самые настенные часы писателя, без подписи.
+
+    `nullable` — аннотация и ключевое слово обязаны совпадать. SQLAlchemy
+    разрешает им разойтись, и тогда аннотация лжёт: pyright рассуждает по ней,
+    база держит ключевое слово, и одно из двух неверно на каждой строке.
+
+    Настройки: `zones`, `factories`, `types`, `homes`, `defaults`, `unruled`,
+    `aware`, `nullable`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ModelColumnsSettings
+    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=ModelColumnsSettings,
+            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._material(
+                    file=file,
+                    node=node,
+                    limits=limits,
+                )
+            if isinstance(node, ast.AnnAssign):
+                yield from cls._annotation(
+                    file=file,
+                    node=node,
+                    limits=limits,
+                )
+
+    @classmethod
+    def _material(
+        cls,
+        *,
+        file: ParsedFile,
+        node: ast.Call,
+        limits: ModelColumnsSettings,
+    ) -> Iterator[Violation]:
+        """Материал и то, чем колонка заполняет себя сама."""
+        written = name(node=node.func)
+        if written in limits.types and limits.homes.get(written) != file.path.stem:
+            yield cls._says(
+                file=file,
+                node=node,
+                message=limits.types[written],
+            )
+        if written in limits.aware and not cls._said(
+            node=node,
+            named=AWARE,
+        ):
+            yield cls._says(
+                file=file,
+                node=node,
+                message=(
+                    f"{written} без timezone=True хранит наивную метку времени; скажи timezone=True"
+                ),
+            )
+        if written not in limits.factories:
+            return
+        for keyword in node.keywords:
+            if keyword.arg in limits.defaults:
+                yield cls._says(
+                    file=file,
+                    node=node,
+                    message=(
+                        f"{keyword.arg}= заполняет колонку за писателя, который её не написал; "
+                        f"передай значение в запросе"
+                    ),
+                )
+
+    @classmethod
+    def _annotation(
+        cls,
+        *,
+        file: ParsedFile,
+        node: ast.AnnAssign,
+        limits: ModelColumnsSettings,
+    ) -> Iterator[Violation]:
+        """Аннотация колонки: встроенный тип и согласие с `nullable=`."""
+        inner = cls._mapped(node=node.annotation)
+        if inner is None:
+            return
+        written, optional = inner
+        if written in limits.unruled:
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=(f"{written} говорит вид, а не правило; возьми примитив с его границей"),
+            )
+        if not limits.nullable:
+            return
+        said = cls._nullable(
+            node=node.value,
+            limits=limits,
+        )
+        if said is not None and said != optional:
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=(
+                    "аннотация и nullable= расходятся; во время работы побеждает то, "
+                    "чего проверяльщик типов не видит"
+                ),
+            )
+
+    @staticmethod
+    def _nullable(
+        *,
+        node: ast.expr | None,
+        limits: ModelColumnsSettings,
+    ) -> bool | None:
+        """Что сказано в `nullable=`, если вообще сказано."""
+        if not isinstance(node, ast.Call) or name(node=node.func) not in limits.factories:
+            return None
+        for keyword in node.keywords:
+            if keyword.arg == NULLABLE and isinstance(keyword.value, ast.Constant):
+                return bool(keyword.value.value)
+        return None
+
+    @classmethod
+    def _mapped(cls, *, node: ast.expr) -> tuple[str, bool] | None:
+        """Имя внутри `Mapped[...]` и то, допускает ли оно `None`."""
+        if not isinstance(node, ast.Subscript) or name(node=node.value) != MAPPED:
+            return None
+        match node.slice:
+            case ast.Name(id=inside) | ast.Attribute(attr=inside):
+                return inside, False
+            case ast.BinOp(left=ast.Name(id=inside), op=ast.BitOr(), right=right):
+                return inside, cls._none(node=right)
+            case _:
+                return None
+
+    @staticmethod
+    def _none(*, node: ast.expr) -> bool:
+        return isinstance(node, ast.Constant) and node.value is None
+
+    @staticmethod
+    def _said(
+        *,
+        node: ast.Call,
+        named: str,
+    ) -> bool:
+        return any(
+            keyword.arg == named and keyword.value != ast.Constant(value=False)
+            for keyword in node.keywords
+        )
+
+    @staticmethod
+    def _says(
+        *,
+        file: ParsedFile,
+        node: ast.Call,
+        message: str,
+    ) -> Violation:
+        return Violation.from_node(
+            node=node,
+            path=file.path,
+            code=CODE,
+            message=message,
+        )

py_checks/checks/database/_raw_sql.py

@@ -0,0 +1,108 @@
+"""SQL, написанный строкой там, где хватило бы выражения."""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._names import name
+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 Iterator
+
+    from py_checks.core import ParsedFile
+
+CODE: Final = "raw-sql"
+
+# Вызов — и то, что пишут вместо строки. Каждый берёт SQL первым позиционным.
+CALLS: Final[dict[str, str]] = {
+    "CheckConstraint": "выражение по колонке, например and_(margin >= NOTHING, margin < WHOLE)",
+    "text": "select()/insert(), собранный из атрибутов модели",
+    "literal_column": "сама маппед-колонка",
+    "column": "сама маппед-колонка",
+}
+
+
+class RawSqlSettings(CheckSettings):
+    calls: dict[str, str] = CALLS
+
+
+class RawSql:
+    """Падает, если SQL написан строкой там, где хватило бы выражения.
+
+    CHECK, записанный как `"margin >= 0 AND margin < 1"`, — это второе
+    определение правила, которое домен уже сформулировал, на языке, который в
+    репозитории никто не проверяет. Переименуй колонку — строка по-прежнему
+    компилируется; сдвинь границу — строка по-прежнему называет старое число, и
+    расхождение всплывает нарушением ограничения на строке, которая была верна
+    по всем правилам, известным коду.
+
+    Записанное выражением — `CheckConstraint(and_(margin >= NOTHING, margin <
+    WHOLE))` — оно состоит из атрибута, который pyright и так проверяет, и
+    констант, которыми сущность отказывает, так что разъехаться им негде.
+
+    То же про `text()`, `literal_column()` и `column()`: запрос, собранный
+    строкой, — запрос, который никто не проверяет, а собранный из значения,
+    пришедшего откуда угодно, — инъекция, ждущая забывчивого вызывающего.
+
+    Где выражения честно нет — `SELECT 1` для пробы живости, чтение служебной
+    таблицы alembic, — на строке пишут причину:
+    `# db-ok: raw-sql: проба живости, формы ORM нет`. Пометка снимается с любой
+    строки самого вызова и не достаёт дальше него: пометка на объемлющей
+    инструкции извиняет её, а не SQL внутри.
+
+    Миграции правилу не подсудны: миграция — это история, она может не иметь
+    права импортировать те самые константы, поэтому её SQL выписан словами и
+    заморожен в день рождения. Это `exclude` проекта, а не дело правила.
+
+    Настройка: `calls`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = RawSqlSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        calls = settings_as(
+            settings=settings,
+            model=RawSqlSettings,
+            code=CODE,
+        ).calls
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.Call) or not node.args:
+                continue
+            written = name(node=node.func)
+            if written not in calls or not cls._sql(node=node.args[0]):
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                # Пометка снимается с любой строки самого вызова.
+                end_line=node.end_lineno or node.lineno,
+                message=f"{written}(...) со строкой SQL; вместо неё — {calls[written]}",
+            )
+
+    @staticmethod
+    def _sql(*, node: ast.expr) -> bool:
+        """Строковый литерал или строка, собранная из литералов."""
+        match node:
+            case ast.Constant(value=str()):
+                return True
+            case ast.JoinedStr() | ast.BinOp(op=ast.Add() | ast.Mod()):
+                return any(
+                    isinstance(part, ast.Constant) and isinstance(part.value, str)
+                    for part in ast.walk(node)
+                )
+            case _:
+                return False