python-checks 0.1.0__py3-none-any.whl

py_checks/checks/hygiene/__init__.py

@@ -0,0 +1,14 @@
+"""Гигиена репозитория.
+
+Зависимость объявляет потолок: без него версию выбирает решатель, а не
+человек. Остальное этой группы закрывается не проверками — `.env.example`
+генерируется из моделей настроек, а `CLAUDE.md` это симлинк на `AGENTS.md`.
+"""
+
+from py_checks.checks.hygiene._dependency_bounds import (
+    DependencyBounds,
+    DependencyBoundsSettings,
+)
+from py_checks.checks.hygiene._marker import MARKER
+
+__all__ = ["MARKER", "DependencyBounds", "DependencyBoundsSettings"]

py_checks/checks/hygiene/_dependency_bounds.py

@@ -0,0 +1,185 @@
+"""У зависимости есть потолок, иначе версию выбирает решатель."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from typing import TYPE_CHECKING, Any, ClassVar, Final
+
+from py_checks.checks.hygiene._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 pathlib import Path
+
+CODE: Final = "dependency-bounds"
+
+MANIFEST: Final = "pyproject.toml"
+MARKERS: Final = ";"
+FIRST: Final = 1
+
+# Имя, за которым идут extras и спецификаторы. `packaging` разобрал бы это
+# правильно и не является зависимостью хуков, а формы, которые встречаются в
+# манифесте, узки настолько, что выражение говорит всё правило целиком.
+REQUIREMENT: Final = re.compile(
+    r"^(?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?(?P<rest>.*)$"
+)
+
+
+class DependencyBoundsSettings(CheckSettings):
+    ceilings: tuple[str, ...] = ("==", "<=", "<", "~=", "===")
+    pins: tuple[str, ...] = ("rev", "tag")
+
+
+class DependencyBounds:
+    """Падает, если зависимость может уехать на версию, которую никто не запускал.
+
+    Требование объявляет потолок одним из двух способов: точной версией
+    (`greenlet==3.5.5`) или парой «пол и потолок» (`pydantic>=2.13.5,<3`,
+    `structlog~=26.1` — то же самое, сказанное иначе).
+
+    Отвергается голый пол — `pre-commit>=4.6.2`. Читается он как минимум, а
+    ведёт себя как «что новее на момент, когда кто-то пересобрал лок», то есть
+    как другой сервис после каждого обновления: выходит мажор, лок двигается, и
+    изменение приезжает в том коммите, который случайно тронул зависимости.
+    Потолок делает этот приезд осознанной правкой, за которой стоит диff и
+    прогон тестов, — единственное место, где ломающее обновление вообще можно
+    прочитать.
+
+    Лок этого не заменяет: `uv.lock` фиксирует то, что стоит сегодня, и он
+    пересобирается — ограничение это то, что переживает пересборку.
+
+    Проверяются все группы: зависимость тестов решает, проходит ли набор, а
+    сборочная — существует ли колесо.
+
+    Исключение одно, и оно несёт свой собственный гвоздь: требование без
+    спецификаторов, чьё имя лежит в `[tool.uv.sources]` с `rev` или `tag`.
+    Коммит — самый тесный потолок, какой бывает.
+
+    Настройки: `ceilings`, `pins`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = DependencyBoundsSettings
+    scope: ClassVar[Scope] = Scope.PROJECT
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        root: Path,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        limits = settings_as(
+            settings=settings,
+            model=DependencyBoundsSettings,
+            code=CODE,
+        )
+        path = root / MANIFEST
+        if not path.is_file():
+            return
+        text = path.read_text(encoding="utf-8")
+        manifest = tomllib.loads(text)
+        exempt = cls._pinned(
+            manifest=manifest,
+            pins=limits.pins,
+        )
+        for where, requirement in cls._requirements(manifest=manifest):
+            if cls._bounded(
+                requirement=requirement,
+                ceilings=limits.ceilings,
+                exempt=exempt,
+            ):
+                continue
+            yield Violation(
+                path=path,
+                line=cls._line(
+                    text=text,
+                    requirement=requirement,
+                ),
+                column=FIRST,
+                code=CODE,
+                message=(
+                    f"{where}: у {requirement!r} нет потолка; закрепи (==) или ограничь "
+                    f"(>=x,<y), иначе версию выберет решатель"
+                ),
+            )
+
+    @classmethod
+    def _bounded(
+        cls,
+        *,
+        requirement: str,
+        ceilings: tuple[str, ...],
+        exempt: frozenset[str],
+    ) -> bool:
+        stated = cls._stated(requirement=requirement)
+        if stated is None:
+            return True
+        if any(ceiling in stated for ceiling in ceilings):
+            return True
+        return not stated and cls._name(requirement=requirement) in exempt
+
+    @staticmethod
+    def _stated(*, requirement: str) -> str | None:
+        """Спецификаторы требования, или None, если это не то, что мы читаем.
+
+        Маркеры отрезаются первыми: `; python_version < "3.13"` несёт свои
+        операторы сравнения и ничего не говорит о том, какая версия встанет.
+        """
+        written = requirement.split(MARKERS, maxsplit=1)[0].strip()
+        found = REQUIREMENT.match(written)
+        return None if found is None else found.group("rest").strip()
+
+    @staticmethod
+    def _name(*, requirement: str) -> str:
+        found = REQUIREMENT.match(requirement.split(MARKERS, maxsplit=1)[0].strip())
+        return "" if found is None else found.group("name").lower().replace("_", "-")
+
+    @staticmethod
+    def _pinned(
+        *,
+        manifest: dict[str, Any],
+        pins: tuple[str, ...],
+    ) -> frozenset[str]:
+        """Имена, чей источник — коммит: это потолок в одну версию."""
+        sources = manifest.get("tool", {}).get("uv", {}).get("sources", {})
+        return frozenset(
+            name.lower().replace("_", "-")
+            for name, source in sources.items()
+            if isinstance(source, dict) and any(pin in source for pin in pins)
+        )
+
+    @staticmethod
+    def _requirements(*, manifest: dict[str, Any]) -> list[tuple[str, str]]:
+        """Каждое требование файла вместе с группой, в которой оно написано."""
+        project = manifest.get("project", {})
+        listed: list[tuple[str, str]] = [
+            ("project.dependencies", one) for one in project.get("dependencies", [])
+        ]
+        for extra, group in project.get("optional-dependencies", {}).items():
+            listed += [(f"project.optional-dependencies.{extra}", one) for one in group]
+        for name, group in manifest.get("dependency-groups", {}).items():
+            # Группа может включать другую группу — это словарь, а не
+            # требование, и ограничивать в нём нечего.
+            listed += [(f"dependency-groups.{name}", one) for one in group if isinstance(one, str)]
+        listed += [
+            ("build-system.requires", one)
+            for one in manifest.get("build-system", {}).get("requires", [])
+        ]
+        return listed
+
+    @staticmethod
+    def _line(
+        *,
+        text: str,
+        requirement: str,
+    ) -> int:
+        """Строка, на которой требование написано: tomllib позиций не отдаёт."""
+        for number, line in enumerate(text.splitlines(), start=FIRST):
+            if requirement in line:
+                return number
+        return FIRST

py_checks/checks/hygiene/_marker.py

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

py_checks/checks/imports/__init__.py

@@ -0,0 +1,25 @@
+"""Импорты и границы.
+
+Слои, независимость модулей и импорты в миграциях уехали в import-linter:
+контракты для него собирает `py-checks sync`. Здесь остались два правила,
+которые в контракты ложатся наизнанку — там пришлось бы перечислять все места,
+где пакет запрещён, и дописывать каждое новое.
+
+`confined-imports` смотрит со стороны пакета: где ему можно.
+`sealed-imports` — со стороны места: что можно здесь.
+
+Обе таблицы — проектные: имена слоёв и список фреймворков библиотека знать не
+может. Без настроек оба правила молчат.
+"""
+
+from py_checks.checks.imports._confined import ConfinedImports, ConfinedSettings
+from py_checks.checks.imports._marker import MARKER
+from py_checks.checks.imports._sealed import SealedImports, SealedSettings
+
+__all__ = [
+    "MARKER",
+    "ConfinedImports",
+    "ConfinedSettings",
+    "SealedImports",
+    "SealedSettings",
+]

py_checks/checks/imports/_confined.py

@@ -0,0 +1,93 @@
+"""Пакет живёт там, где ему место."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import place
+from py_checks.checks.imports._marker import MARKER
+from py_checks.checks.imports._statements import imports
+from py_checks.config import CheckSettings
+from py_checks.core import Scope, Violation, settings_as
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from py_checks.checks._location import Place
+    from py_checks.checks.imports._statements import Imported
+    from py_checks.core import ParsedFile
+
+CODE: Final = "confined-imports"
+
+
+class ConfinedSettings(CheckSettings):
+    packages: dict[str, tuple[str, ...]] = {}
+
+
+class ConfinedImports:
+    """Падает, если пакет импортируется вне отведённых ему мест.
+
+    Фреймворк, расползшийся по всем слоям, — это фреймворк, который нельзя
+    заменить: замена превращается в правку всего сервиса. Пока ORM живёт в
+    `infra/database`, а веб-стек на краю, каждый из них меняется в одном месте.
+
+    Где чьё место, знает проект: у сервиса это `infra/database`, у утилиты
+    такого слоя нет вовсе. Список пишется в
+    `[tool.py-checks.confined-imports.packages]`; пустой список значит
+    «нигде» — так держат убранную библиотеку, чтобы она не вернулась. Пакета,
+    которого в списке нет, правило не касается.
+
+    Настройка: `packages`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ConfinedSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        table = settings_as(
+            settings=settings,
+            model=ConfinedSettings,
+            code=CODE,
+        ).packages
+        where = place(file=file)
+        if where is None:
+            return
+        for imported in imports(tree=file.tree):
+            allowed = table.get(imported.top)
+            if allowed is None or any(where.under(prefix=path) for path in allowed):
+                continue
+            yield cls._violation(
+                imported=imported,
+                where=where,
+                allowed=allowed,
+                path=file.path,
+            )
+
+    @staticmethod
+    def _violation(
+        *,
+        imported: Imported,
+        where: Place,
+        allowed: tuple[str, ...],
+        path: Path,
+    ) -> Violation:
+        message = (
+            f"{imported.top} в {where.where}; ему место в {', '.join(allowed)}"
+            if allowed
+            else f"{imported.top} в {where.where}; этот пакет убран, импортировать его негде"
+        )
+        return Violation.from_node(
+            node=imported.node,
+            path=path,
+            code=CODE,
+            message=message,
+        )

py_checks/checks/imports/_marker.py

@@ -0,0 +1,7 @@
+"""Слово, которым снимается любая проверка этой группы."""
+
+from __future__ import annotations
+
+from typing import Final
+
+MARKER: Final = "# import-ok"

py_checks/checks/imports/_sealed.py

@@ -0,0 +1,100 @@
+"""Внутри запечатанной зоны чужих пакетов нет."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._location import place
+from py_checks.checks.imports._marker import MARKER
+from py_checks.checks.imports._statements import imports
+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 = "sealed-imports"
+
+
+class SealedSettings(CheckSettings):
+    zones: tuple[str, ...] = ()
+    allow: dict[str, tuple[str, ...]] = {}
+
+
+class SealedImports:
+    """Падает, если запечатанная зона импортирует чужой пакет.
+
+    Правила и интерфейсы вокруг них не знают ничего, кроме стандартной
+    библиотеки и кода самого сервиса: DTO здесь — dataclass, а не модель
+    фреймворка. Список разрешённого белый, а не чёрный, потому что каждый новый
+    фреймворк иначе попадает внутрь молча.
+
+    Разрешения задаются по слою, а не на всю зону: слой, который руководит,
+    обычно имеет право сказать, что произошло, а слой с правилами не знает
+    ничего.
+
+    Какие зоны запечатаны, знает проект: библиотека не догадывается, что у него
+    называется `modules`. Без `zones` правило молчит.
+
+    Настройки: `zones`, `allow`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = SealedSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        own = settings_as(
+            settings=settings,
+            model=SealedSettings,
+            code=CODE,
+        )
+        where = place(file=file)
+        if where is None or not cls._sealed(
+            where=where,
+            zones=own.zones,
+        ):
+            return
+        allowed = cls._allowed(
+            where=where,
+            allow=own.allow,
+        )
+        for imported in imports(tree=file.tree):
+            if imported.stdlib or imported.top in {where.package, *allowed}:
+                continue
+            yield Violation.from_node(
+                node=imported.node,
+                path=file.path,
+                code=CODE,
+                message=(
+                    f"{imported.top} в {where.where}: запечатанная зона знает "
+                    "только стандартную библиотеку и код сервиса"
+                ),
+            )
+
+    @staticmethod
+    def _sealed(
+        *,
+        where: Place,
+        zones: tuple[str, ...],
+    ) -> bool:
+        return any(part in zones for part in where.parts)
+
+    @staticmethod
+    def _allowed(
+        *,
+        where: Place,
+        allow: dict[str, tuple[str, ...]],
+    ) -> frozenset[str]:
+        """Что можно этому слою: зона у файла одна, а слой внутри неё — свой."""
+        return frozenset(package for part in where.parts for package in allow.get(part, ()))

py_checks/checks/imports/_statements.py

@@ -0,0 +1,52 @@
+"""Импорты файла в том виде, в каком о них говорят правила."""
+
+from __future__ import annotations
+
+import ast
+import sys
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+STDLIB: Final[frozenset[str]] = frozenset(sys.stdlib_module_names)
+
+
+@dataclass(frozen=True, slots=True)
+class Imported:
+    """Один импорт: узел, полное имя и пакет, которому оно принадлежит."""
+
+    node: ast.stmt
+    module: str
+
+    @property
+    def top(self) -> str:
+        return self.module.split(".", maxsplit=1)[0]
+
+    @property
+    def stdlib(self) -> bool:
+        return self.top in STDLIB
+
+
+def imports(*, tree: ast.Module) -> Iterator[Imported]:
+    """Все импорты модуля, кроме относительных.
+
+    Относительный импорт — это всегда сосед по пакету, то есть код самого
+    проекта: для правил про чужие пакеты он ничего не значит.
+    """
+    for node in ast.walk(tree):
+        match node:
+            case ast.Import(names=names):
+                for name in names:
+                    yield Imported(
+                        node=node,
+                        module=name.name,
+                    )
+            case ast.ImportFrom(module=str(module), level=0):
+                yield Imported(
+                    node=node,
+                    module=module,
+                )
+            case _:
+                continue

py_checks/checks/placement/__init__.py

@@ -0,0 +1,38 @@
+"""Размещение и форма модуля.
+
+Где лежит класс, что допускает директория, какой класс модуль обязан объявить
+первым. Соглашения, привязанные к раскладке директорий: готовых инструментов
+под них нет — семейство ArchUnit для Python занято импортами, а движки образцов
+(Semgrep, ast-grep) умеют запрещать, но не разрешать.
+
+Таблицы проектные: имена `use_cases`, `dto`, `schemas` библиотека знать не
+может. Без них правила молчат.
+"""
+
+from py_checks.checks.placement._class_modules import ClassModules, ClassModulesSettings
+from py_checks.checks.placement._class_placement import (
+    ClassPlacement,
+    ClassPlacementSettings,
+    Rule,
+)
+from py_checks.checks.placement._marker import MARKER
+from py_checks.checks.placement._operation_shape import (
+    Operation,
+    OperationShape,
+    OperationShapeSettings,
+)
+from py_checks.checks.placement._required_class import RequiredClass, RequiredClassSettings
+
+__all__ = [
+    "MARKER",
+    "ClassModules",
+    "ClassModulesSettings",
+    "ClassPlacement",
+    "ClassPlacementSettings",
+    "Operation",
+    "OperationShape",
+    "OperationShapeSettings",
+    "RequiredClass",
+    "RequiredClassSettings",
+    "Rule",
+]

py_checks/checks/placement/_class_modules.py

@@ -0,0 +1,106 @@
+"""Директория объявляет, что в ней живёт."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Final
+
+from py_checks.checks._kind import Kind, declarations
+from py_checks.checks._location import place
+from py_checks.checks.placement._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 = "class-modules"
+
+
+class ClassModulesSettings(CheckSettings):
+    policies: dict[str, tuple[Kind, ...]] = {}
+
+
+class ClassModules:
+    """Падает, если в модуле лежит то, чего его директория не допускает.
+
+    Директория называет, что в ней живёт, и рядом не садится ничего другого.
+    Хелпер, заехавший в модуль use case, — либо часть класса, и тогда он
+    статический метод внутри, либо общий, и тогда ему место там, где лежит
+    остальное общее. Перечисление, забредшее в `dto/`, — та же история.
+
+    Импорты, константы, блоки `if TYPE_CHECKING` и докстринг разрешены везде:
+    правило про то, что модуль объявляет, а не про то, чем он пользуется.
+
+    Ключ политики — путь, а не имя директории, и это важно: `application/
+    services` держит класс-оркестратор, а `domain/services` — функции, правила,
+    сравнивающие два факта. Одно слово, два разных зверя. Директории, которой
+    в таблице нет, правило не касается.
+
+    Настройка: `policies`.
+    """
+
+    code: ClassVar[str] = CODE
+    Settings: ClassVar[type[CheckSettings]] = ClassModulesSettings
+    scope: ClassVar[Scope] = Scope.FILE
+    marker: ClassVar[str] = MARKER
+
+    @classmethod
+    def run(
+        cls,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]:
+        policies = settings_as(
+            settings=settings,
+            model=ClassModulesSettings,
+            code=CODE,
+        ).policies
+        where = place(file=file)
+        if where is None:
+            return
+        policy = cls._policy(
+            where=where,
+            policies=policies,
+        )
+        if policy is None:
+            return
+        directory, allowed = policy
+        for declared in declarations(tree=file.tree):
+            # Вид не виден — судить не о чем: это класс с базой из другого модуля.
+            if declared.kind is None or declared.kind in allowed:
+                continue
+            yield Violation.from_node(
+                node=declared.node,
+                path=file.path,
+                code=CODE,
+                message=(
+                    f"{declared.name} — {declared.kind.said}; в {directory} держат "
+                    f"{', '.join(sorted(one.said for one in allowed))}"
+                ),
+            )
+
+    @staticmethod
+    def _policy(
+        *,
+        where: Place,
+        policies: dict[str, tuple[Kind, ...]],
+    ) -> tuple[str, tuple[Kind, ...]] | None:
+        """Политика самой внутренней из совпавших директорий.
+
+        Побеждает самая глубокая: `modules/betslip/application/services`
+        важнее, чем `application`. При равной глубине — более длинный ключ:
+        путь говорит о месте больше, чем одно имя.
+        """
+        matched = [
+            (depth, directory, allowed)
+            for directory, allowed in policies.items()
+            if (depth := where.within(directory=directory)) is not None
+        ]
+        if not matched:
+            return None
+        deepest = max(matched, key=lambda policy: (policy[0], len(policy[1])))
+        return deepest[1], deepest[2]