python-checks 0.1.0__py3-none-any.whl

py_checks/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from py-checks!"

py_checks/checks/__init__.py

@@ -0,0 +1,20 @@
+"""Реализации правил, по пакету на группу.
+
+Внутри группы — по модулю на проверку. Правила, уехавшие в import-linter,
+ruff и alembic, сюда не переносятся; что и куда ушло, записано в
+`docs/current.md`.
+
+Проверка — это один класс, и всё, чем она разбирает дерево, лежит внутри него:
+помощники не расползаются по модулю, и видно, чьи они. Лист берёт
+`@staticmethod`, помощник, который зовёт другого помощника, — `@classmethod`,
+чтобы звать через `cls`, а не по имени класса.
+
+Внутри класса живёт то, что правилу и принадлежит. Слово языка правилу не
+принадлежит: «как этот узел зовут» — это `_names.py`, «где лежит этот файл» —
+`_location.py`, «что тут объявлено» — `_kind.py`. Шесть одинаковых `_name` по
+классам — это не шесть помощников, а один, забытый в шести местах.
+
+Слово, которым правило снимают с кода, объявлено один раз на группу — в
+`_marker.py` пакета. Оно снимает любую проверку группы; чтобы снять ровно
+одну, есть `# check-ok: <код>: <причина>`.
+"""

py_checks/checks/_kind.py

@@ -0,0 +1,184 @@
+"""Что объявлено в модуле: класс, порт, dataclass, алиас.
+
+Правила размещения говорят о видах объявлений, а не о синтаксисе: «в `dto/`
+лежат dataclass-ы», «в `ports/` — протоколы». Вид узнаётся один раз здесь, и
+этим же знанием пользуются все правила группы.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Final
+
+from py_checks.checks._names import name, names
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+ABSTRACT: Final[frozenset[str]] = frozenset({"Protocol", "ABC"})
+ABSTRACT_METACLASS: Final = "ABCMeta"
+MODEL: Final = "BaseModel"
+DATACLASS: Final = "dataclass"
+ENUMS: Final[frozenset[str]] = frozenset(
+    {"Enum", "StrEnum", "IntEnum", "Flag", "IntFlag", "ReprEnum"}
+)
+
+ERROR_BASES: Final[frozenset[str]] = frozenset({"Exception", "BaseException"})
+
+# Исключение проекта наследуется от своего же корня (`class NotFound(DomainError)`),
+# а не от `Exception`, — но имя корня кончается так же, и по нему вид узнаётся,
+# не читая чужой модуль.
+ERROR_SUFFIXES: Final[tuple[str, ...]] = ("Error", "Exception")
+
+# Присваивание, которым объявляют имя для типа, а не значение.
+ALIAS_ANNOTATION: Final = "TypeAlias"
+ALIAS_FACTORIES: Final[frozenset[str]] = frozenset(
+    {"TypeVar", "NewType", "ParamSpec", "TypeAliasType"},
+)
+ALIAS_CONSTRUCTORS: Final[frozenset[str]] = frozenset(
+    {
+        "dict",
+        "list",
+        "set",
+        "tuple",
+        "frozenset",
+        "type",
+        "Union",
+        "Optional",
+        "Literal",
+        "Callable",
+    },
+)
+
+
+class Kind(StrEnum):
+    """Виды объявлений, о которых говорят правила размещения."""
+
+    CLASS = "class"
+    PORT = "port"
+    DATACLASS = "dataclass"
+    MODEL = "model"
+    ALIAS = "alias"
+    ENUM = "enum"
+    ERROR = "error"
+    FUNCTION = "function"
+
+    @property
+    def said(self) -> str:
+        """Как вид называется в сообщении: `str.title` занят самим `str`."""
+        return NAMES[self]
+
+
+NAMES: Final[dict[Kind, str]] = {
+    Kind.CLASS: "класс",
+    Kind.PORT: "порт",
+    Kind.DATACLASS: "dataclass",
+    Kind.MODEL: "модель",
+    Kind.ALIAS: "алиас",
+    Kind.ENUM: "перечисление",
+    Kind.ERROR: "исключение",
+    Kind.FUNCTION: "функция",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Declaration:
+    """Объявление верхнего уровня: имя, вид и узел.
+
+    `kind` пуст, когда вид по одному файлу не виден: класс с базой из другого
+    модуля. Имя у такого всё равно есть, и правило, которое смотрит на суффикс,
+    им пользуется.
+    """
+
+    name: str
+    kind: Kind | None
+    node: ast.stmt
+
+
+def declarations(*, tree: ast.Module) -> Iterator[Declaration]:
+    """Всё, что модуль объявляет.
+
+    Импорты, константы, блоки `if TYPE_CHECKING` и докстринг сюда не попадают:
+    они разрешены везде, и правилам размещения о них говорить нечего.
+    """
+    for node in tree.body:
+        match node:
+            case ast.ClassDef(name=name):
+                yield Declaration(
+                    name=name,
+                    kind=_class(node=node),
+                    node=node,
+                )
+            case ast.FunctionDef(name=name) | ast.AsyncFunctionDef(name=name):
+                yield Declaration(
+                    name=name,
+                    kind=Kind.FUNCTION,
+                    node=node,
+                )
+            case ast.AnnAssign(target=ast.Name(id=name)) | ast.Assign(targets=[ast.Name(id=name)]):
+                if _alias(node=node):
+                    yield Declaration(
+                        name=name,
+                        kind=Kind.ALIAS,
+                        node=node,
+                    )
+            case _:
+                continue
+
+
+def _class(*, node: ast.ClassDef) -> Kind | None:
+    """Вид класса; `None`, если по одному файлу его не видно.
+
+    База, объявленная в другом модуле, — это вид, которого отсюда не видно:
+    `class CodeMismatchResponse(ErrorResponse)` — pydantic-модель, но узнать
+    это можно только прочитав тот модуль. Про такой класс правило молчит:
+    заблудившийся хелпер, ради которого оно написано, базы обычно не имеет.
+    """
+    bases = frozenset(names(nodes=node.bases))
+    if bases & ABSTRACT or _metaclass(node=node):
+        return Kind.PORT
+    if MODEL in bases:
+        return Kind.MODEL
+    if bases & ENUMS:
+        return Kind.ENUM
+    if DATACLASS in frozenset(names(nodes=node.decorator_list)):
+        return Kind.DATACLASS
+    if _error(bases=bases):
+        return Kind.ERROR
+    if bases:
+        return None
+    return Kind.CLASS
+
+
+def _error(*, bases: frozenset[str]) -> bool:
+    return bool(bases & ERROR_BASES) or any(base.endswith(ERROR_SUFFIXES) for base in bases)
+
+
+def _metaclass(*, node: ast.ClassDef) -> bool:
+    return any(
+        keyword.arg == "metaclass" and name(node=keyword.value) == ABSTRACT_METACLASS
+        for keyword in node.keywords
+    )
+
+
+def _alias(*, node: ast.AnnAssign | ast.Assign) -> bool:
+    """Присваивание, объявляющее имя для типа.
+
+    Три вида: с аннотацией `TypeAlias`, вызов фабрики вроде `NewType`, и голое
+    `Row = dict[str, int]` — имя для формы, а не значение.
+    """
+    if isinstance(node, ast.AnnAssign) and name(node=node.annotation) == ALIAS_ANNOTATION:
+        return True
+    if node.value is None:
+        return False
+    match node.value:
+        case ast.Call(func=function):
+            return name(node=function) in ALIAS_FACTORIES
+        case ast.Subscript(value=value):
+            return name(node=value) in ALIAS_CONSTRUCTORS
+        case ast.BinOp(op=ast.BitOr()):
+            return True
+        case _:
+            return False

py_checks/checks/_location.py

@@ -0,0 +1,172 @@
+"""Где файл лежит внутри своего пакета.
+
+Правило про импорты говорит о месте: «sqlalchemy живёт в `infra/database`».
+Место считается от корня исходников, который известен ядру из настроек.
+Угадывать его по `__init__.py` нельзя: папка без него встречается и посреди
+пакета — в одном из сервисов так лежит половина репозиториев.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+
+from py_checks.config import CheckSettings
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+    from pathlib import Path
+
+    from py_checks.core import ParsedFile
+
+INIT: Final = "__init__"
+
+SEPARATOR: Final = "/"
+
+# Один любой кусок пути: `modules/*/domain` — домен любого модуля.
+ANY: Final = "*"
+
+# Пакет и хотя бы один шаг внутри него: файл, лежащий прямо в корне исходников,
+# ни в каком пакете не находится, и говорить о его месте нечего.
+INSIDE: Final = 2
+
+
+@dataclass(frozen=True, slots=True)
+class Place:
+    """Корневой пакет файла и его адрес внутри этого пакета."""
+
+    package: str
+    parts: tuple[str, ...]
+
+    @property
+    def where(self) -> str:
+        return "/".join(self.parts)
+
+    def under(self, *, prefix: str) -> bool:
+        """Лежит ли файл под этим путём; пустой путь не разрешает ничего."""
+        if not prefix:
+            return False
+        wanted = tuple(prefix.split(SEPARATOR))
+        return self.parts[: len(wanted)] == wanted
+
+    def anywhere(self, *, zones: Iterable[str]) -> bool:
+        """Лежит ли файл хоть в одной из этих зон.
+
+        Зоны складываются, а не спорят: правило работает там, где его о том
+        попросили, и молчит везде остальном.
+        """
+        return any(self.holds(path=zone) for zone in zones)
+
+    def holds(self, *, path: str) -> bool:
+        """Идут ли эти куски адреса подряд где угодно внутри него.
+
+        Адрес включает имя модуля, поэтому `exceptions` подходит и как
+        директория, и как файл `exceptions.py`: для словаря отказов это одно и
+        то же место.
+        """
+        return (
+            _run(
+                parts=self.parts,
+                wanted=path,
+            )
+            is not None
+        )
+
+    def within(self, *, directory: str) -> int | None:
+        """Где кончается самое глубокое вхождение этих директорий, или `None`.
+
+        Имя файла в счёт не идёт: речь о директории, а не о модуле. Конец, а не
+        начало, потому что сравнивать вложенность двух ключей разной длины
+        можно только по тому, где они кончаются, — глубже тот, кто кончается
+        позже.
+        """
+        return _run(
+            parts=self.parts[:-1],
+            wanted=directory,
+        )
+
+
+class ZonedSettings(CheckSettings):
+    """Настройки правила, которое работает не везде.
+
+    `zones` — места, где правило судит; пустой список означает, что правило
+    молчит. Молчит, а не судит всюду: соглашение про репозитории неверно для
+    сценариев, и правило, которому забыли назвать зону, лучше не скажет ничего,
+    чем скажет неправду по всему дереву.
+    """
+
+    zones: tuple[str, ...] = ()
+
+
+def zoned(
+    *,
+    file: ParsedFile,
+    zones: Iterable[str],
+) -> Place | None:
+    """Адрес файла, если он в одной из зон; иначе `None` — правилу тут нечего сказать."""
+    where = place(file=file)
+    if where is None or not where.anywhere(zones=zones):
+        return None
+    return where
+
+
+def place(*, file: ParsedFile) -> Place | None:
+    """Адрес файла; `None`, если корень исходников неизвестен или файл вне его."""
+    if file.source is None:
+        return None
+    relative = _relative(
+        path=file.path,
+        source=file.source,
+    )
+    if relative is None or len(relative) < INSIDE:
+        return None
+    parts = relative[1:]
+    if parts[-1] == INIT:
+        parts = parts[:-1]
+    return Place(
+        package=relative[0],
+        parts=parts,
+    )
+
+
+def _relative(
+    *,
+    path: Path,
+    source: Path,
+) -> tuple[str, ...] | None:
+    try:
+        inside = path.resolve().relative_to(source.resolve())
+    except ValueError:
+        return None
+    return inside.with_suffix("").parts
+
+
+def _run(
+    *,
+    parts: tuple[str, ...],
+    wanted: str,
+) -> int | None:
+    """Конец последнего вхождения подряд идущих кусков пути.
+
+    `*` подходит любому одному куску: `modules/*/domain` — это домен любого
+    модуля, и перечислять модули по именам не нужно.
+    """
+    needle = tuple(wanted.split(SEPARATOR))
+    span = len(needle)
+    ends = [
+        start + span
+        for start in range(len(parts) - span + 1)
+        if _same(
+            found=parts[start : start + span],
+            needle=needle,
+        )
+    ]
+    return max(ends) if ends else None
+
+
+def _same(
+    *,
+    found: tuple[str, ...],
+    needle: tuple[str, ...],
+) -> bool:
+    return all(wanted in (ANY, part) for part, wanted in zip(found, needle, strict=True))

py_checks/checks/_names.py

@@ -0,0 +1,86 @@
+"""Имена: как их читают в дереве и как сверяют с записанным в настройках.
+
+Правила говорят именами: «база называется `Base`», «эта колонка объявлена
+`mapped_column`», «`datetime.now` берут портом». Спросить у узла, как его
+зовут, — не дело каждого правила: способ один на язык, и живёт он здесь.
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+DOT: Final = "."
+ANY: Final = "*"
+
+
+def name(*, node: ast.expr) -> str:
+    """Как это зовут; пустая строка, если именем это не назвать.
+
+    Строковая аннотация (`-> "Order"`) — это имя, написанное буквами:
+    отличать её от обычной незачем, автор имел в виду то же самое. А вот вызов
+    и подписанное выражение именем не считаются: `tuple(...)[:1]` — это срез
+    списка, и правило про формы типов не должно принять его за объявление.
+    Развернуть их просит тот, кто читает базы и декораторы, — `names`.
+    """
+    match node:
+        case ast.Name(id=found) | ast.Attribute(attr=found) | ast.Constant(value=str() as found):
+            return found
+        case _:
+            return ""
+
+
+def names(*, nodes: Iterable[ast.expr]) -> Iterator[str]:
+    """Имена перечисленного: баз класса, декораторов.
+
+    Здесь имя и правда стоит за вызовом и за подстановкой: `@dataclass(frozen=True)`
+    — это `dataclass`, `Generic[T]` — это `Generic`.
+    """
+    for node in nodes:
+        if found := name(node=_head(node=node)):
+            yield found
+
+
+def _head(*, node: ast.expr) -> ast.expr:
+    """Из чего сделано выражение: с кого начали, прежде чем звать и подставлять."""
+    match node:
+        case ast.Call(func=inner) | ast.Subscript(value=inner):
+            return _head(node=inner)
+        case _:
+            return node
+
+
+def walked(*, node: ast.expr) -> Iterator[str]:
+    """Все имена внутри выражения, на любой глубине и в порядке написания.
+
+    `dict[str, Order | None]` — это `dict`, `str`, `Order`: правило про
+    аннотации смотрит на то, что в ней названо, а не на её форму. Имя, взятое
+    в кавычки, — такое же имя: ссылка вперёд написана строкой не по смыслу, а
+    потому что в этом месте класса ещё нет.
+    """
+    for child in ast.walk(node):
+        if isinstance(child, ast.Name | ast.Attribute | ast.Constant) and (
+            found := name(node=child)
+        ):
+            yield found
+
+
+def matches(
+    *,
+    called: str,
+    pattern: str,
+) -> bool:
+    """Хвост имени: `datetime.now` — это и `datetime.datetime.now`.
+
+    `random.*` подходит любому вызову модуля целиком: важен не последний
+    кусок, а то, у кого его взяли.
+    """
+    parts = called.split(DOT)
+    wanted = pattern.split(DOT)
+    if wanted[-1] == ANY:
+        head = wanted[:-1]
+        return len(parts) > len(head) and parts[-len(head) - 1 : -1] == head
+    return len(parts) >= len(wanted) and parts[-len(wanted) :] == wanted

py_checks/checks/api/__init__.py

@@ -0,0 +1,13 @@
+"""API и события.
+
+Маршрут объявляет в декораторе всё, чем он будет описан в схеме: механизм у
+фреймворка есть, требования писать — нет.
+"""
+
+from py_checks.checks.api._endpoint_declarations import (
+    EndpointDeclarations,
+    EndpointDeclarationsSettings,
+)
+from py_checks.checks.api._marker import MARKER
+
+__all__ = ["MARKER", "EndpointDeclarations", "EndpointDeclarationsSettings"]

py_checks/checks/api/_endpoint_declarations.py

@@ -0,0 +1,204 @@
+"""Маршрут объявляет в декораторе всё, чем он будет описан в схеме."""
+
+from __future__ import annotations
+
+import ast
+from http import HTTPStatus
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks.api._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 = "endpoint-declarations"
+
+PATH: Final = "path"
+STATUS: Final = "status_code"
+
+
+class EndpointDeclarationsSettings(CheckSettings):
+    methods: tuple[str, ...] = ()
+    required: tuple[str, ...] = ()
+    body: str | None = None
+    bodiless: tuple[int, ...] = ()
+    exempt: str | None = None
+
+
+class EndpointDeclarations:
+    """Падает, если маршрут не сказал, чем он отвечает.
+
+    Декоратор маршрута — это контракт. Кто читает сгенерированную схему —
+    соседний сервис, человек, пишущий клиент, — читает только то, что объявил
+    декоратор, и поле, которого там нет, для него не существует, что бы ни
+    возвращало тело функции.
+
+    Механизм у фреймворка есть, требования писать — нет. Маршрут без `summary`
+    попадёт в схему с именем функции вместо описания, а с пустым `responses` —
+    с обещанием, что отказов у него не бывает: успех из подписи выводится,
+    отказы — нет, и ничто в ней не говорит, что этот маршрут отвечает 409.
+
+    Путь пишется словом `path=`: позиционный первый аргумент — единственное в
+    декораторе, чей смысл зависит от позиции.
+
+    Тело объявляется отдельно от прочего и не требуется там, где его не
+    бывает: 204, 205 и 304 — это статусы без тела, и модель ответа рядом с
+    ними обещает то, что протокол запрещает. Статус, записанный не числом и не
+    членом `HTTPStatus`, читается как неизвестный, а неизвестный считается
+    имеющим тело: проверка, сработавшая зря, снимается пометкой, а
+    промолчавшая — это контракт, которого никто не хватится.
+
+    Маршрут, выведенный из схемы (`include_in_schema=False`), правило не
+    трогает: схема — это то, что оно защищает, а такого маршрута в ней нет.
+
+    Настройки: `methods`, `required`, `body`, `bodiless`, `exempt`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = EndpointDeclarationsSettings
+    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=EndpointDeclarationsSettings,
+            code=CODE,
+        )
+        if not limits.methods:
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+                continue
+            for decorator in node.decorator_list:
+                if not isinstance(decorator, ast.Call):
+                    continue
+                if not cls._route(
+                    node=decorator,
+                    methods=limits.methods,
+                ):
+                    continue
+                yield from cls._judged(
+                    route=decorator,
+                    file=file,
+                    limits=limits,
+                )
+
+    @classmethod
+    def _judged(
+        cls,
+        *,
+        route: ast.Call,
+        file: ParsedFile,
+        limits: EndpointDeclarationsSettings,
+    ) -> Iterator[Violation]:
+        if cls._unpublished(
+            route=route,
+            exempt=limits.exempt,
+        ):
+            return
+        named = cls._name(route=route)
+        declared = {keyword.arg for keyword in route.keywords}
+        if route.args:
+            yield cls._violation(
+                route=route,
+                file=file,
+                message=f"{named} передаёт путь позиционно; напиши {PATH}=",
+            )
+        for wanted in limits.required:
+            if wanted in declared or (wanted == PATH and route.args):
+                continue
+            yield cls._violation(
+                route=route,
+                file=file,
+                message=f"{named} не объявляет {wanted}=",
+            )
+        if limits.body is None or limits.body in declared:
+            return
+        if cls._status(route=route) in limits.bodiless:
+            return
+        yield cls._violation(
+            route=route,
+            file=file,
+            message=(
+                f"{named} не объявляет {limits.body}= и отвечает телом; "
+                f"без него отвечают {', '.join(str(status) for status in limits.bodiless)}"
+            ),
+        )
+
+    @staticmethod
+    def _violation(
+        *,
+        route: ast.Call,
+        file: ParsedFile,
+        message: str,
+    ) -> Violation:
+        return Violation.from_node(
+            node=route,
+            path=file.path,
+            code=CODE,
+            message=message,
+        )
+
+    @staticmethod
+    def _route(
+        *,
+        node: ast.Call,
+        methods: tuple[str, ...],
+    ) -> bool:
+        """Декоратор вида `<что-то>.<метод>(...)`, а не `@app.middleware(...)`."""
+        return isinstance(node.func, ast.Attribute) and node.func.attr in methods
+
+    @staticmethod
+    def _unpublished(
+        *,
+        route: ast.Call,
+        exempt: str | None,
+    ) -> bool:
+        """Маршрут сказал, что в схеме его нет."""
+        return exempt is not None and any(
+            keyword.arg == exempt
+            and isinstance(keyword.value, ast.Constant)
+            and keyword.value.value is False
+            for keyword in route.keywords
+        )
+
+    @staticmethod
+    def _name(*, route: ast.Call) -> str:
+        """`POST '/tickets'` — как бы путь ни был записан.
+
+        Путь читается и из слова, и из первого аргумента: сообщение обязано
+        назвать маршрут и в том файле, где слова как раз нет, — «GET не
+        объявляет summary» в модуле с шестью GET не называет ничего.
+        """
+        attribute = route.func
+        method = attribute.attr.upper() if isinstance(attribute, ast.Attribute) else ""
+        written = [keyword.value for keyword in route.keywords if keyword.arg == PATH]
+        path = route.args[:1] + written
+        return f"{method} {ast.unparse(path[0])}" if path else method
+
+    @staticmethod
+    def _status(*, route: ast.Call) -> int | None:
+        """Статус, если он записан так, что его видно по файлу."""
+        for keyword in route.keywords:
+            if keyword.arg != STATUS:
+                continue
+            match keyword.value:
+                case ast.Constant(value=int() as status):
+                    return status
+                case ast.Attribute(value=ast.Name(id="HTTPStatus"), attr=name):
+                    found = getattr(HTTPStatus, name, None)
+                    return None if found is None else int(found)
+                case _:
+                    return None
+        return None