python-checks 0.1.0__py3-none-any.whl

py_checks/checks/types/_config_fields.py

@@ -0,0 +1,236 @@
+"""Поле настроек названо целиком: и как приходит, и какие значения допустимы."""
+
+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 walked
+from py_checks.checks.types._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 = "config-fields"
+
+# Классы, которые держат словарь или интерфейс, а не поля настроек.
+NOT_SETTINGS: Final[frozenset[str]] = frozenset(
+    {"Enum", "StrEnum", "IntEnum", "IntFlag", "Flag", "Protocol", "TypedDict"},
+)
+
+# Аннотация, которая говорит, как значение хранится, и ничего — какие значения
+# допустимы. Всё остальное — имя, а имя это место, где правило может жить.
+BOUNDS: Final[dict[str, tuple[str, ...]]] = {
+    "int": ("ge", "gt", "le", "lt"),
+    "float": ("ge", "gt", "le", "lt"),
+    # `max_length` тут отсутствует намеренно: потолок говорит, какой длины
+    # значение может быть, а не что оно вообще есть, — а речь именно о пустой
+    # строке, которой оборачивается неустановленная переменная.
+    "str": ("min_length", "pattern"),
+}
+
+CLASS_VAR: Final = "ClassVar"
+
+# Поле, собранное фабрикой, — это вложенная секция, а не значение: переменной у
+# него нет, её читают поля внутри.
+FACTORY: Final = "default_factory"
+
+
+class ConfigFieldsSettings(ZonedSettings):
+    factory: str = "Field"
+    alias: str | None = None
+    bounds: dict[str, tuple[str, ...]] = BOUNDS
+
+
+class ConfigFields:
+    """Падает, если поле настроек ничем не ограничено.
+
+    Значение приходит текстом из окружения, которое никто не ревьюит, поэтому
+    обе половины объявления обязательны.
+
+    Поле объявляется через `Field(...)`: там живут псевдоним переменной,
+    значение по умолчанию и ограничения, а голое `name: str = "x"` молча
+    роняет все три.
+
+    Поле с голым числом называет границу — `ge`, `gt`, `le`, `lt` — или
+    аннотируется типом, который её несёт. Без этого `POSTGRES_POOL_SIZE=0` и
+    пул на пятьсот принимаются здесь и падают где-то там, где в трейсбеке
+    настроек уже не видно.
+
+    Голая строка — та же дыра с более тихим отказом: неустановленная переменная
+    приходит пустой строкой, и пустой адрес брокера, DSN или имя топика
+    принимаются как настройка. Поле называет `min_length` или `pattern`, либо
+    несёт тип, который это делает.
+
+    Поле называет переменную, из которой читается (`alias`, у pydantic это
+    `validation_alias`). Без неё имя переменной знает один pydantic — он
+    выводит его из имени поля и приставки, — и ни `.env.example`, собранный из
+    этих же классов, ни человек, ищущий, откуда берётся значение, назвать её не
+    могут. Поле, собранное `default_factory`, — исключение: это вложенная
+    секция, а не значение, и переменные читают её собственные поля.
+
+    `ClassVar` — не поле настроек, а константа рядом с ними.
+
+    Настройки: `zones`, `factory`, `alias`, `bounds`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ConfigFieldsSettings
+    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=ConfigFieldsSettings,
+            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.ClassDef) and cls._settings(node=node):
+                yield from cls._fields(
+                    file=file,
+                    node=node,
+                    limits=limits,
+                )
+
+    @classmethod
+    def _fields(
+        cls,
+        *,
+        file: ParsedFile,
+        node: ast.ClassDef,
+        limits: ConfigFieldsSettings,
+    ) -> Iterator[Violation]:
+        for statement in node.body:
+            if not isinstance(statement, ast.AnnAssign):
+                continue
+            if not isinstance(statement.target, ast.Name):
+                continue
+            named = frozenset(walked(node=statement.annotation))
+            if CLASS_VAR in named:
+                continue
+            reason = cls._reason(
+                statement=statement,
+                named=named,
+                limits=limits,
+            )
+            if reason is None:
+                continue
+            yield Violation.from_node(
+                node=statement,
+                path=file.path,
+                code=CODE,
+                message=f"{node.name}.{statement.target.id} {reason}",
+            )
+
+    @classmethod
+    def _reason(
+        cls,
+        *,
+        statement: ast.AnnAssign,
+        named: frozenset[str],
+        limits: ConfigFieldsSettings,
+    ) -> str | None:
+        """Чем поле не закрыто, или `None`, если закрыто."""
+        if not cls._declared(
+            node=statement.value,
+            factory=limits.factory,
+        ):
+            if statement.value is None:
+                return (
+                    f"объявлено без значения; поле настроек объявляют через {limits.factory}(...)"
+                )
+            return f"объявлено не через {limits.factory}(...)"
+        if (
+            limits.alias is not None
+            and not cls._states(
+                node=statement.value,
+                wanted=(FACTORY,),
+            )
+            and not cls._states(
+                node=statement.value,
+                wanted=(limits.alias,),
+            )
+        ):
+            return (
+                f"не называет {limits.alias}=; без него имя переменной знает "
+                f"один pydantic, а `.env.example` собирается из этих же полей"
+            )
+        wanted = cls._wanted(
+            named=named,
+            bounds=limits.bounds,
+        )
+        if wanted and not cls._states(
+            node=statement.value,
+            wanted=wanted,
+        ):
+            return (
+                f"ничем не ограничено; назови одно из {', '.join(wanted)} "
+                f"или аннотируй типом, который несёт это правило"
+            )
+        return None
+
+    @staticmethod
+    def _wanted(
+        *,
+        named: frozenset[str],
+        bounds: dict[str, tuple[str, ...]],
+    ) -> tuple[str, ...]:
+        """Какие ограничения задолжала аннотация.
+
+        `str | None` — это строка, а `int | None` — число: объединение говорит
+        о том, есть ли значение, а не о том, какие значения допустимы. Имя, не
+        попавшее в таблицу, — уже правило: ограничение живёт в нём.
+        """
+        if not named or not named <= frozenset(bounds):
+            return ()
+        listed = [one for name in sorted(named) for one in bounds[name]]
+        return tuple(dict.fromkeys(listed))
+
+    @staticmethod
+    def _declared(
+        *,
+        node: ast.expr | None,
+        factory: str,
+    ) -> bool:
+        match node:
+            case ast.Call(func=ast.Name(id=name) | ast.Attribute(attr=name)):
+                return name == factory
+            case _:
+                return False
+
+    @staticmethod
+    def _states(
+        *,
+        node: ast.expr | None,
+        wanted: tuple[str, ...],
+    ) -> bool:
+        if not isinstance(node, ast.Call):
+            return False
+        return any(keyword.arg in wanted for keyword in node.keywords)
+
+    @staticmethod
+    def _settings(*, node: ast.ClassDef) -> bool:
+        """Класс полей настроек, а не словарь и не интерфейс рядом с ними."""
+        bases = {
+            base.attr if isinstance(base, ast.Attribute) else getattr(base, "id", "")
+            for base in node.bases
+        }
+        return not bases & NOT_SETTINGS

py_checks/checks/types/_confined_types.py

@@ -0,0 +1,117 @@
+"""Тип, которому не место в этой части дерева."""
+
+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 walked
+from py_checks.checks.types._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 = "confined-types"
+
+# Имя, которое говорит, что значение принадлежит классу, а не экземпляру:
+# такое поле — не состояние, переходящее границу, и правило его не касается.
+ASIDE: Final[frozenset[str]] = frozenset({"ClassVar", "Final"})
+
+
+class ConfinedTypesSettings(CheckSettings):
+    zones: dict[str, tuple[str, ...]] = {}
+
+
+class ConfinedTypes:
+    """Падает, если поле в этой части дерева объявлено запрещённым здесь типом.
+
+    Одно правило на два случая, которые раньше писались по отдельности.
+    `float` в домене: двоичная плавающая точка не держит цену, а ошибка
+    округления в хранимом состоянии — это деньги, которые перестают сходиться.
+    Голые `str`, `int`, `Decimal` там, где живут контракты: `int` говорит, что
+    версия может быть −10000, `str` — что тег может быть пустым, `Decimal` —
+    что коэффициент может быть отрицательным или NaN. Ничего из этого про дело
+    не верно, а тип — последнее место, где это можно сказать один раз, а не
+    перепроверять глазами.
+
+    Какие типы где запрещены — дело проекта: в одном сервисе деньги считают
+    везде, в другом `float` в отчёте законен. Без таблицы правило молчит.
+
+    Аннотация просматривается насквозь: `tuple[str, ...]` — та же голая строка
+    этажом ниже. Судятся поля класса; `ClassVar` и `Final` — не поля: они
+    принадлежат классу, а не экземпляру.
+
+    Настройка: `zones` — путь (можно с `*`: `modules/*/domain`) и список имён.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ConfinedTypesSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        zones = settings_as(
+            settings=settings,
+            model=ConfinedTypesSettings,
+            code=CODE,
+        ).zones
+        where = place(file=file)
+        if where is None:
+            return
+        forbidden = cls._forbidden(
+            where=where,
+            zones=zones,
+        )
+        if not forbidden:
+            return
+        for name, statement in cls._fields(tree=file.tree):
+            found = frozenset(walked(node=statement.annotation)) & forbidden
+            if not found:
+                continue
+            yield Violation.from_node(
+                node=statement,
+                path=file.path,
+                code=CODE,
+                message=(
+                    f"{name} объявлено через {', '.join(sorted(found))}; "
+                    f"здесь тип называет, что значение может держать"
+                ),
+            )
+
+    @staticmethod
+    def _forbidden(
+        *,
+        where: Place,
+        zones: dict[str, tuple[str, ...]],
+    ) -> frozenset[str]:
+        """Всё, что запрещено в этом месте: зоны складываются, а не спорят."""
+        return frozenset(
+            name for zone, names in zones.items() if where.holds(path=zone) for name in names
+        )
+
+    @staticmethod
+    def _fields(*, tree: ast.Module) -> Iterator[tuple[str, ast.AnnAssign]]:
+        """Поля классов модуля под именами вида `Класс.поле`."""
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            for statement in node.body:
+                if not isinstance(statement, ast.AnnAssign):
+                    continue
+                if not isinstance(statement.target, ast.Name):
+                    continue
+                if frozenset(walked(node=statement.annotation)) & ASIDE:
+                    continue
+                yield f"{node.name}.{statement.target.id}", statement

py_checks/checks/types/_constant_annotations.py

@@ -0,0 +1,128 @@
+"""Имя, написанное как константа, обещает неизменность — и говорит это типом."""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._kind import ENUMS
+from py_checks.checks.types._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 = "constant-annotations"
+
+FINAL: Final = "Final"
+CLASS_VAR: Final = "ClassVar"
+
+# Имя — это и есть обещание: строчная привязка на уровне модуля объявляет
+# переменную и говорит об этом прямо, и правилу до неё дела нет.
+NAME: Final = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+class ConstantAnnotationsSettings(CheckSettings):
+    module: str = FINAL
+    inside_class: str = CLASS_VAR
+
+
+class ConstantAnnotations:
+    """Падает, если константа не сказала типом, что она константа.
+
+    Имя `UPPER_SNAKE` — обещание, `Final` — то, что делает обещание
+    проверяемым: без него имя читается как константа, а ведёт себя как
+    переменная, и любой импортировавший модуль волен её перепривязать.
+
+    В теле класса слово другое, и по причине. `Final` там означает, что
+    атрибут нельзя переопределить вообще (PEP 591), а ограниченные примитивы
+    построены ровно на переопределении: `PositiveDecimal.BOUND` заменяет
+    `BOUND`, объявленный базой. `ClassVar` говорит «принадлежит классу, а не
+    экземпляру» и переопределение оставляет открытым — это верно про оба.
+
+    Перечисления не трогаются: член — это словарь, а не константа рядом с ним.
+
+    Настройки: `module`, `inside-class` — какими словами это говорится.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ConstantAnnotationsSettings
+    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=ConstantAnnotationsSettings,
+            code=CODE,
+        )
+        yield from cls._constants(
+            file=file,
+            body=file.tree.body,
+            wanted=limits.module,
+        )
+        for node in ast.walk(file.tree):
+            if isinstance(node, ast.ClassDef) and not cls._enum(node=node):
+                yield from cls._constants(
+                    file=file,
+                    body=node.body,
+                    wanted=limits.inside_class,
+                )
+
+    @classmethod
+    def _constants(
+        cls,
+        *,
+        file: ParsedFile,
+        body: list[ast.stmt],
+        wanted: str,
+    ) -> Iterator[Violation]:
+        for statement in body:
+            name = cls._constant(node=statement)
+            if name is None:
+                continue
+            yield Violation.from_node(
+                node=statement,
+                path=file.path,
+                code=CODE,
+                message=f"{name} названо константой, но не объявлено через {wanted}",
+            )
+
+    @classmethod
+    def _constant(cls, *, node: ast.stmt) -> str | None:
+        """Имя константы, которой не хватает слова; иначе `None`."""
+        match node:
+            case ast.Assign(targets=[ast.Name(id=name)]) if NAME.match(name):
+                return name
+            case ast.AnnAssign(target=ast.Name(id=name), annotation=annotation) if NAME.match(name):
+                return None if cls._says(node=annotation) else name
+            case _:
+                return None
+
+    @staticmethod
+    def _says(*, node: ast.expr) -> bool:
+        """Сказано ли в аннотации то самое слово — голым или с параметром."""
+        outer = node.value if isinstance(node, ast.Subscript) else node
+        match outer:
+            case ast.Name(id=name) | ast.Attribute(attr=name):
+                return name in (FINAL, CLASS_VAR)
+            case _:
+                return False
+
+    @staticmethod
+    def _enum(*, node: ast.ClassDef) -> bool:
+        bases = {
+            base.attr if isinstance(base, ast.Attribute) else getattr(base, "id", "")
+            for base in node.bases
+        }
+        return bool(bases & ENUMS)

py_checks/checks/types/_frozen_dataclasses.py

@@ -0,0 +1,112 @@
+"""dataclass объявлен так, чтобы значение оставалось значением."""
+
+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.types._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 = "frozen-dataclasses"
+
+DECORATOR: Final = "dataclass"
+
+
+class FrozenDataclassesSettings(ZonedSettings):
+    options: tuple[str, ...] = ("frozen", "slots", "kw_only")
+
+
+class FrozenDataclasses:
+    """Падает, если dataclass в зоне объявлен без нужных аргументов.
+
+    Объект дела — это значение: собрали один раз и не меняли, поэтому
+    существующий объект не может исподтишка съехать в недопустимое состояние.
+    `frozen` это покупает, `slots` не даёт опечатке завести атрибут, которого
+    никто не объявлял, а `kw_only` — перепутать местами два поля одного типа:
+    у значения из четырёх строк порядок помнит только автор.
+
+        @dataclass(frozen=True, slots=True, kw_only=True)
+        class Price: ...
+
+    Зона проектная: держать значения неизменяемыми имеет смысл там, где живут
+    правила, а не в конфиге и не в проводке. Без зон правило молчит.
+
+    Настройки: `zones`, `options`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = FrozenDataclassesSettings
+    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=FrozenDataclassesSettings,
+            code=CODE,
+        )
+        where = zoned(
+            file=file,
+            zones=limits.zones,
+        )
+        if where is None:
+            return
+        for node in ast.walk(file.tree):
+            if not isinstance(node, ast.ClassDef):
+                continue
+            decorator = cls._decorator(node=node)
+            if decorator is None:
+                continue
+            missing = tuple(
+                option for option in limits.options if option not in cls._enabled(node=decorator)
+            )
+            if not missing:
+                continue
+            yield Violation.from_node(
+                node=node,
+                path=file.path,
+                code=CODE,
+                message=(
+                    f"dataclass {node.name} объявлен без "
+                    f"{', '.join(f'{option}=True' for option in missing)}"
+                ),
+            )
+
+    @staticmethod
+    def _decorator(*, node: ast.ClassDef) -> ast.expr | None:
+        """Декоратор `@dataclass`, с аргументами или без."""
+        for item in node.decorator_list:
+            called = item.func if isinstance(item, ast.Call) else item
+            if name(node=called) == DECORATOR:
+                return item
+        return None
+
+    @classmethod
+    def _enabled(cls, *, node: ast.expr) -> frozenset[str]:
+        """Аргументы декоратора, выставленные в `True`."""
+        if not isinstance(node, ast.Call):
+            return frozenset()
+        return frozenset(
+            keyword.arg
+            for keyword in node.keywords
+            if keyword.arg is not None and cls._true(node=keyword.value)
+        )
+
+    @staticmethod
+    def _true(*, node: ast.expr) -> bool:
+        return isinstance(node, ast.Constant) and node.value is True

py_checks/checks/types/_marker.py

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

py_checks/cli/__init__.py

@@ -0,0 +1,10 @@
+"""Командная строка.
+
+Точка входа, через которую проверки вызывает pre-commit, и команды для ручного
+запуска: прогнать проверки, показать список, объяснить правило.
+"""
+
+from py_checks.cli._app import app, main
+from py_checks.cli._protocols import Registrar
+
+__all__ = ["Registrar", "app", "main"]

py_checks/cli/_app.py

@@ -0,0 +1,21 @@
+"""Приложение командной строки."""
+
+from __future__ import annotations
+
+import typer
+
+from py_checks.cli.commands import REGISTRARS
+
+app = typer.Typer(
+    no_args_is_help=True,
+    add_completion=False,
+    help="Проверки архитектурных соглашений проекта.",
+)
+
+for register in REGISTRARS:
+    register(app=app)
+
+
+def main() -> None:
+    """Точка входа консольной команды `py-checks`."""
+    app()

py_checks/cli/_protocols.py

@@ -0,0 +1,19 @@
+"""Каким приложение видит команду."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    import typer
+
+
+class Registrar(Protocol):
+    """Функция, которая вешает команду на приложение.
+
+    Только так `_app` и знает о командах: имя, опции и справка остаются в
+    модуле команды, а приложение получает готовую регистрацию. Подпись одна и
+    та же и для `app.command(...)`, и для `app.add_typer(...)`.
+    """
+
+    def __call__(self, *, app: typer.Typer) -> None: ...

py_checks/cli/commands/__init__.py

@@ -0,0 +1,23 @@
+"""Команды, по модулю на команду.
+
+Модуль команды сам знает своё имя и свои опции: `_app` только собирает
+приложение из их `register`. Когда у команды появятся подкоманды, её `register`
+вызовет `add_typer`, и собирающий код это не заметит.
+"""
+
+from typing import Final
+
+from py_checks.cli._protocols import Registrar
+from py_checks.cli.commands._explain import register as register_explain
+from py_checks.cli.commands._list import register as register_list
+from py_checks.cli.commands._run import register as register_run
+from py_checks.cli.commands._sync import register as register_sync
+
+REGISTRARS: Final[tuple[Registrar, ...]] = (
+    register_run,
+    register_list,
+    register_explain,
+    register_sync,
+)
+
+__all__ = ["REGISTRARS", "Registrar"]