python-checks 0.1.0__py3-none-any.whl

py_checks/core/_fixer.py

@@ -0,0 +1,55 @@
+"""Наложение правок на файлы."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+from py_checks.core._edit import apply
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from py_checks.core._violation import Violation
+
+
+def fix(*, violations: Sequence[Violation]) -> tuple[list[Path], list[Violation]]:
+    """Исправить, что умеем; вернуть изменённые файлы и то, что осталось.
+
+    Нарушение без правки — не провал автофикса, а честный ответ: `*args`
+    исправить нельзя, имена аргументов придумывает автор. Такие нарушения
+    возвращаются и попадают в отчёт как обычно.
+    """
+    grouped: dict[Path, list[Violation]] = defaultdict(list)
+    for violation in violations:
+        grouped[violation.path].append(violation)
+    changed: list[Path] = []
+    left: list[Violation] = []
+    for path, found in grouped.items():
+        left.extend(violation for violation in found if violation.edit is None)
+        if _rewrite(
+            path=path,
+            found=found,
+        ):
+            changed.append(path)
+    return changed, left
+
+
+def _rewrite(
+    *,
+    path: Path,
+    found: Sequence[Violation],
+) -> bool:
+    edits = [violation.edit for violation in found if violation.edit is not None]
+    if not edits:
+        return False
+    text = path.read_text(encoding="utf-8")
+    fixed = apply(
+        text=text,
+        edits=edits,
+    )
+    if fixed == text:
+        return False
+    path.write_text(fixed, encoding="utf-8")
+    return True

py_checks/core/_format.py

@@ -0,0 +1,30 @@
+"""Форматирование файлов, которые правил автофикс."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+FORMATTER: Final = "ruff"
+
+
+def reformat(*, paths: Sequence[Path]) -> None:
+    """Пройтись форматтером по изменённым файлам.
+
+    Правка ставит символы, а не колонки: после вставки `*` подпись может стать
+    длиннее лимита строки. Раскладывать её руками — работа форматтера, он в
+    проекте всё равно есть. Если его нет, файл остаётся исправленным, просто
+    неотформатированным.
+    """
+    formatter = shutil.which(FORMATTER)
+    if formatter is None or not paths:
+        return
+    subprocess.run(  # noqa: S603 - команда своя, пути берутся из найденных файлов
+        [formatter, "format", "--quiet", *(str(path) for path in paths)],
+        check=False,
+    )

py_checks/core/_markers.py

@@ -0,0 +1,220 @@
+"""Маркер, которым строка снимается с проверки.
+
+Форма одна на все правила: `# check-ok: <код>[, <код>]: <причина>`. Правило про
+маркеры не знает ничего — нарушения снимает ядро, поэтому и синтаксис, и
+требование причины у всех проверок одинаковые.
+
+Код обязателен: маркер снимает названное правило, а не всё подряд. Причина
+обязательна по той же причине, по которой её требует `# noqa` в ревью: через
+полгода никто не помнит, чья это библиотека диктует подпись.
+
+У группы правил есть своё короткое слово — `# signature-ok` на весь пакет
+`signatures`. Оно снимает любую проверку группы: человек помнит группу («это
+про подписи»), а не сорок кодов. Канонический `# check-ok: <код>` снимает ровно
+одно правило и работает всегда.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final
+
+from py_checks.core._violation import Violation
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Iterator, Mapping, Sequence
+    from pathlib import Path
+
+    from py_checks.core._source import ParsedFile
+
+MARKER: Final = "# check-ok:"
+
+CODE: Final = "check-ok"
+
+SHAPE: Final = "`# check-ok: <код>: <причина>`"
+
+# Код правила выглядит так и не иначе. Проверка нужна не ради строгости: это
+# же слово стоит в документации и в сообщениях об ошибках, и такая строка не
+# должна читаться как пометка. Всё, что на код не похоже, — просто текст.
+NAME: Final = re.compile(r"[a-z][a-z0-9_-]*")
+
+
+@dataclass(frozen=True, slots=True)
+class Marker:
+    """Что написано в маркере: какие правила он снимает и почему."""
+
+    codes: frozenset[str]
+    reason: str
+    column: int
+
+
+def read(
+    *,
+    line: str,
+    aliases: Mapping[str, frozenset[str]],
+) -> Marker | None:
+    """Маркер из строки, если он там есть.
+
+    Разбор нарочно не падает на кривой записи: маркер без кода или без причины
+    читается и попадает в `complaints`, иначе о нём никто бы не узнал.
+    """
+    if MARKER in line:
+        codes, _, reason = line.split(MARKER, maxsplit=1)[1].partition(":")
+        if not _named(text=codes):
+            return None
+        return Marker(
+            codes=frozenset(_codes(text=codes)),
+            reason=reason.strip(),
+            column=line.index(MARKER) + 1,
+        )
+    for text, codes in aliases.items():
+        if text in line:
+            return Marker(
+                codes=codes,
+                reason=line.split(text, maxsplit=1)[1].removeprefix(":").strip(),
+                column=line.index(text) + 1,
+            )
+    return None
+
+
+def surviving(
+    *,
+    violations: Sequence[Violation],
+    file: ParsedFile,
+    aliases: Mapping[str, frozenset[str]],
+) -> list[Violation]:
+    """Нарушения, которые никто не снял маркером."""
+    return [
+        violation
+        for violation in violations
+        if not _covered(
+            violation=violation,
+            file=file,
+            aliases=aliases,
+        )
+    ]
+
+
+def complaints(
+    *,
+    file: ParsedFile,
+    aliases: Mapping[str, frozenset[str]],
+    known: Collection[str],
+) -> Iterator[Violation]:
+    """Маркер, который ничего не снимает, — молча неработающий маркер.
+
+    Опечатка в коде правила выглядит как отключённая проверка, а на деле
+    проверка работает и просто не видит пометки. Поэтому такой маркер — сам
+    нарушение.
+    """
+    for number, line in enumerate(file.lines, start=1):
+        marker = read(
+            line=line,
+            aliases=aliases,
+        )
+        if marker is None:
+            continue
+        yield from _wrong(
+            marker=marker,
+            path=file.path,
+            line=number,
+            known=known,
+        )
+
+
+def _named(*, text: str) -> bool:
+    """Похоже ли перечисленное на коды правил.
+
+    Пустое место после маркера — тоже пометка, только без кода: о ней скажет
+    `complaints`. А вот `# check-ok: <код>` из документации пометкой не
+    считается, иначе библиотека ловила бы собственный текст.
+    """
+    names = list(_codes(text=text))
+    return not names or all(NAME.fullmatch(name) for name in names)
+
+
+def _codes(*, text: str) -> Iterator[str]:
+    for code in text.split(","):
+        if stripped := code.strip():
+            yield stripped
+
+
+def _covered(
+    *,
+    violation: Violation,
+    file: ParsedFile,
+    aliases: Mapping[str, frozenset[str]],
+) -> bool:
+    for line in _span(
+        violation=violation,
+        file=file,
+    ):
+        marker = read(
+            line=line,
+            aliases=aliases,
+        )
+        if marker is not None and violation.code in marker.codes:
+            return True
+    return False
+
+
+def _span(
+    *,
+    violation: Violation,
+    file: ParsedFile,
+) -> tuple[str, ...]:
+    """Строки, в которых ищем маркер.
+
+    Нарушение указывает на первую строку того, что нашло, а пометке место в
+    конце: подпись в столбик несёт её на последней строке. Поэтому проверка,
+    занимающая несколько строк, говорит `end_line`, и маркер ищется во всех.
+    """
+    last = max(violation.end_line or violation.line, violation.line)
+    return file.lines[violation.line - 1 : last]
+
+
+def _wrong(
+    *,
+    marker: Marker,
+    path: Path,
+    line: int,
+    known: Collection[str],
+) -> Iterator[Violation]:
+    if not marker.codes:
+        yield _complaint(
+            path=path,
+            line=line,
+            column=marker.column,
+            message=f"маркеру нужен код проверки: {SHAPE}",
+        )
+    for code in sorted(marker.codes.difference(known)):
+        yield _complaint(
+            path=path,
+            line=line,
+            column=marker.column,
+            message=f"нет проверки `{code}`, маркер ничего не снимает",
+        )
+    if not marker.reason:
+        yield _complaint(
+            path=path,
+            line=line,
+            column=marker.column,
+            message=f"маркеру нужна причина: {SHAPE}",
+        )
+
+
+def _complaint(
+    *,
+    path: Path,
+    line: int,
+    column: int,
+    message: str,
+) -> Violation:
+    return Violation(
+        path=path,
+        line=line,
+        column=column,
+        code=CODE,
+        message=message,
+    )

py_checks/core/_protocols.py

@@ -0,0 +1,88 @@
+"""Каким библиотека видит правило."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import TYPE_CHECKING, ClassVar, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+    from py_checks.config import CheckSettings
+    from py_checks.core._source import ParsedFile
+    from py_checks.core._violation import Violation
+
+
+class Scope(StrEnum):
+    """Что правилу дают на суд.
+
+    Вид объявляет само правило, а не группа entry points: так автор чужого
+    пакета пишет одну запись, а `list` и `explain` видят все правила разом, не
+    складывая два реестра в один.
+    """
+
+    # Один файл, разобранный ядром: таких правил большинство.
+    FILE = "file"
+
+    # Корень проекта: манифест, согласие двух файлов репозитория между собой.
+    PROJECT = "project"
+
+    # То же, что `PROJECT`, но правилу нужна живая среда — база, сеть, долгий
+    # прогон. В обычный прогон такое не входит: его зовут по имени или в CI,
+    # иначе хук на коммит начинает ждать базу.
+    ENVIRONMENT = "environment"
+
+
+@runtime_checkable
+class FileCheck(Protocol):
+    """Правило, которому хватает одного файла.
+
+    Всё остальное — поиск файлов, разбор, настройки, вывод — делает ядро.
+    Проверка знает только своё условие и возвращает нарушения, ничего не
+    печатая: иначе формат вывода расползётся по сорока правилам.
+    """
+
+    code: ClassVar[str]
+    Settings: ClassVar[type[CheckSettings]]
+    scope: ClassVar[Scope]
+
+    # Слово группы, к которой правило принадлежит: `# signature-ok` снимает
+    # любую проверку из `signatures`. Пишется один раз на пакет, потому что
+    # человек помнит группу («это про подписи»), а не сорок кодов. Канонический
+    # `# check-ok: <код>` работает всегда и снимает ровно одно правило.
+    marker: ClassVar[str]
+
+    def run(
+        self,
+        *,
+        file: ParsedFile,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]: ...
+
+
+@runtime_checkable
+class ProjectCheck(Protocol):
+    """Правило, которому одного файла мало.
+
+    Манифест зависимостей, согласие двух файлов репозитория между собой — то,
+    что живёт не в исходнике, а в проекте. Такое правило вызывается один раз за
+    прогон и само решает, что ему прочитать; ядро даёт ему корень и настройки.
+    """
+
+    code: ClassVar[str]
+    Settings: ClassVar[type[CheckSettings]]
+    scope: ClassVar[Scope]
+    marker: ClassVar[str]
+
+    def run(
+        self,
+        *,
+        root: Path,
+        settings: CheckSettings,
+    ) -> Iterator[Violation]: ...
+
+
+# Правило — это одно из двух: судящее файл или судящее проект. Там, где важно
+# лишь то, что у него есть код и описание (список, объяснение), годится любое.
+type Check = FileCheck | ProjectCheck

py_checks/core/_registry.py

@@ -0,0 +1,77 @@
+"""Какие проверки существуют и как их находят."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import cache
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING
+
+from py_checks.core._constants import GROUP
+from py_checks.core._errors import UnknownCheckError
+from py_checks.core._protocols import Scope
+
+if TYPE_CHECKING:
+    from collections.abc import Collection
+
+    from py_checks.core._protocols import Check, FileCheck, ProjectCheck
+
+
+@dataclass(frozen=True, slots=True)
+class Checks:
+    """Правила, разобранные по тому, что им дают: файл или корень проекта.
+
+    Один и тот же вид описывает и всё, что установлено, и то, что выбрали на
+    этот прогон, — поэтому выбор не превращается в развилку у каждого, кто его
+    получает: прогон, список и объяснение говорят об одном и том же наборе.
+    """
+
+    files: dict[str, FileCheck]
+    project: dict[str, ProjectCheck]
+
+    @property
+    def listed(self) -> dict[str, Check]:
+        """Все правила по коду, независимо от вида."""
+        return {**self.files, **self.project}
+
+    def only(self, *, codes: Collection[str]) -> Checks:
+        """Тот же набор, суженный до названных кодов."""
+        return Checks(
+            files={code: check for code, check in self.files.items() if code in codes},
+            project={code: check for code, check in self.project.items() if code in codes},
+        )
+
+
+@cache
+def available() -> Checks:
+    """Все проверки, объявленные через entry points.
+
+    Так проект или команда добавляет своё правило: ставит рядом свой пакет с
+    записью в этой же группе, а библиотеку форкать не нужно. Вид правила —
+    файл ему дают или корень проекта — объявляет оно само.
+
+    Читается один раз: загрузка означает импорт каждого объявленного модуля, а
+    спрашивают реестр и прогон, и выбор, и объяснение.
+    """
+    files: dict[str, FileCheck] = {}
+    project: dict[str, ProjectCheck] = {}
+    for entry in sorted(entry_points(group=GROUP), key=lambda entry: entry.name):
+        check = entry.load()()
+        if check.scope is Scope.FILE:
+            files[check.code] = check
+        else:
+            project[check.code] = check
+    return Checks(
+        files=files,
+        project=project,
+    )
+
+
+def get(*, code: str) -> Check:
+    checks = available().listed
+    if code not in checks:
+        raise UnknownCheckError(
+            code=code,
+            known=tuple(sorted(checks)),
+        )
+    return checks[code]

py_checks/core/_report.py

@@ -0,0 +1,45 @@
+"""Вывод нарушений."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+
+from py_checks.core._constants import EXIT_OK, EXIT_VIOLATION
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from py_checks.core._violation import Violation
+
+
+def report(
+    *,
+    violations: Sequence[Violation],
+    root: Path,
+    checked: int,
+    console: Console | None = None,
+) -> int:
+    """Печатает нарушения и возвращает код выхода.
+
+    Нарушения идут в stderr обычными строками: их читают редактор и CI, и
+    подсветка не должна мешать разбирать строку. Цвета `rich` отключает сам,
+    когда вывод идёт не в терминал, — а под pre-commit это всегда так.
+    """
+    console = console or Console(
+        stderr=True,
+        soft_wrap=True,
+    )
+    for violation in violations:
+        console.print(
+            violation.render(root=root),
+            markup=False,
+            highlight=False,
+        )
+    if violations:
+        console.print(f"\n{len(violations)} нарушени(й) в {checked} файл(ах)", markup=False)
+        return EXIT_VIOLATION
+    console.print(f"ok: проверено файлов — {checked}", markup=False)
+    return EXIT_OK

py_checks/core/_runner.py

@@ -0,0 +1,178 @@
+"""Прогон проверок по файлам."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING, Final
+
+from py_checks.core import _registry
+from py_checks.core._errors import ParseError
+from py_checks.core._markers import complaints, surviving
+from py_checks.core._source import ParsedFile
+from py_checks.core._violation import Violation
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Mapping, Sequence
+    from pathlib import Path
+
+    from py_checks.config import CheckSettings, Config
+    from py_checks.core._protocols import Check, FileCheck, ProjectCheck
+    from py_checks.core._registry import Checks
+
+SYNTAX: Final = "syntax"
+
+
+def survey(
+    *,
+    chosen: Checks,
+    files: Sequence[Path],
+    config: Config,
+    root: Path,
+) -> list[Violation]:
+    """Все нарушения выбранных правил: файловых — по файлам, проектных — по корню.
+
+    Разделение сделано один раз здесь, потому что вид правила виден только по
+    тому, что ему дают: у судящего файл и у судящего проект разные `run`, и
+    складывать их в один цикл нечестно.
+    """
+    return [
+        *inspect(
+            files=files,
+            checks=list(chosen.files.values()),
+            config=config,
+            root=root,
+        ),
+        *examine(
+            checks=list(chosen.project.values()),
+            config=config,
+            root=root,
+        ),
+    ]
+
+
+def inspect(
+    *,
+    files: Sequence[Path],
+    checks: Sequence[FileCheck],
+    config: Config,
+    root: Path | None = None,
+) -> list[Violation]:
+    """Все нарушения по всем файлам.
+
+    Внешний цикл по файлам, а не по проверкам: файл читается и разбирается один
+    раз, а проверок на него много.
+    """
+    settings = {
+        check.code: config.settings_for(
+            code=check.code,
+            model=check.Settings,
+        )
+        for check in checks
+    }
+    registered = _registry.available().listed
+    aliases = _aliases(registered=registered)
+    source = root / config.src if root is not None else None
+    violations: list[Violation] = []
+    for path in files:
+        violations.extend(
+            _inspect_file(
+                path=path,
+                checks=checks,
+                settings=settings,
+                source=source,
+                aliases=aliases,
+                known=frozenset(registered),
+            )
+        )
+    return violations
+
+
+def examine(
+    *,
+    checks: Sequence[ProjectCheck],
+    config: Config,
+    root: Path,
+) -> list[Violation]:
+    """Нарушения правил, которым нужен проект целиком.
+
+    Каждое зовётся один раз: что прочитать — манифест, пару файлов, дерево, —
+    решает оно само.
+    """
+    return [
+        violation
+        for check in checks
+        for violation in check.run(
+            root=root,
+            settings=config.settings_for(
+                code=check.code,
+                model=check.Settings,
+            ),
+        )
+    ]
+
+
+def _aliases(*, registered: Mapping[str, Check]) -> dict[str, frozenset[str]]:
+    """Слово группы и все правила, которые оно снимает.
+
+    Слово у группы одно на всех, поэтому `# signature-ok` снимает любую
+    проверку из `signatures`: человек помнит группу, а не сорок кодов. Когда
+    нужно снять ровно одно правило, для этого есть `# check-ok: <код>`.
+    """
+    groups: dict[str, set[str]] = defaultdict(set)
+    for code, check in registered.items():
+        groups[check.marker].add(code)
+    return {marker: frozenset(codes) for marker, codes in groups.items()}
+
+
+def _inspect_file(
+    *,
+    path: Path,
+    checks: Sequence[FileCheck],
+    settings: Mapping[str, CheckSettings],
+    source: Path | None,
+    aliases: Mapping[str, frozenset[str]],
+    known: Collection[str],
+) -> list[Violation]:
+    file = ParsedFile.from_path(
+        path=path,
+        source=source,
+    )
+    found: list[Violation] = []
+    for check in checks:
+        try:
+            found.extend(
+                check.run(
+                    file=file,
+                    settings=settings[check.code],
+                )
+            )
+        except ParseError as error:
+            return [_broken(error=error)]
+    kept = surviving(
+        violations=found,
+        file=file,
+        aliases=aliases,
+    )
+    return [
+        *kept,
+        *complaints(
+            file=file,
+            aliases=aliases,
+            known=known,
+        ),
+    ]
+
+
+def _broken(*, error: ParseError) -> Violation:
+    """Сломанный файл — это одно нарушение, а не падение всего прогона.
+
+    Иначе один файл с недописанным синтаксисом прячет нарушения во всех
+    остальных.
+    """
+    return Violation(
+        path=error.path,
+        line=error.error.lineno or 1,
+        column=error.error.offset or 1,
+        code=SYNTAX,
+        message=error.error.msg,
+    )