normik 0.1.0__py3-none-any.whl

nk/__init__.py

@@ -0,0 +1,3 @@
+"""nk — линтер оформления отчёта о НИР по ГОСТ 7.32-2017 для исходников LaTeX."""
+
+__version__ = "0.1.0"

nk/cli.py

@@ -0,0 +1,331 @@
+"""Команды CLI. Вся логика — в ядре; здесь только разбор аргументов и вывод."""
+
+import sys
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from nk import __version__
+from nk.core.baseline import Baseline, BaselineError
+from nk.core.diagnostics import INTERNAL
+from nk.core.finding import Severity
+from nk.core.fixer import diff, plan, write
+from nk.core.profile import Profile, ProfileError, load_profile
+from nk.core.registry import load_rules, partition_ids, select_rules, validate_profile
+from nk.core.rule import RuleImpl, UnknownRuleError
+from nk.core.runner import RunResult, run
+from nk.parse.tex import parse, parse_findings
+from nk.report import agent, examples, human, rules_docs
+from nk.report import json as json_report
+
+app = typer.Typer(
+    name="nk",
+    help="Линтер оформления отчёта о НИР по ГОСТ 7.32-2017 для исходников LaTeX.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+rules_app = typer.Typer(name="rules", help="Сведения о правилах.", no_args_is_help=True)
+profile_app = typer.Typer(name="profile", help="Сведения о профилях.", no_args_is_help=True)
+app.add_typer(rules_app)
+app.add_typer(profile_app)
+
+console = Console()
+err_console = Console(stderr=True)
+
+EXIT_OK = 0
+EXIT_FOUND_ERRORS = 1
+EXIT_INTERNAL_ERROR = 2
+
+#: Сколько раз перепроверять исходники, применяя найденные правки.
+FIX_PASSES = 5
+
+
+class OutputFormat(StrEnum):
+    HUMAN = "human"
+    AGENT = "agent"
+    JSON = "json"
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    version: bool = typer.Option(False, "--version", help="Показать версию и выйти."),
+) -> None:
+    if version:
+        console.print(f"nk {__version__}")
+        raise typer.Exit()
+
+
+@rules_app.command("list")
+def rules_list() -> None:
+    """Перечень правил: идентификатор, пункт стандарта, уровень, название."""
+    registry = load_rules()
+    if not len(registry):
+        console.print("Правил пока нет.")
+        return
+
+    table = Table(box=None, pad_edge=False)
+    table.add_column("ID")
+    table.add_column("Пункт")
+    table.add_column("Уровень")
+    table.add_column("Название")
+    for impl in registry:
+        table.add_row(impl.id, impl.clause, impl.severity.value, impl.title)
+    console.print(table)
+
+
+@rules_app.command("show")
+def rules_show(rule_id: str = typer.Argument(..., help="Идентификатор правила.")) -> None:
+    """Подробности по правилу."""
+    registry = load_rules()
+    try:
+        impl = registry.get(rule_id)
+    except UnknownRuleError:
+        err_console.print(f"Неизвестное правило: {rule_id}")
+        raise typer.Exit(EXIT_INTERNAL_ERROR) from None
+
+    console.print(f"[bold]{impl.id}[/bold] — {impl.title}")
+    console.print(f"Пункт ГОСТ 7.32-2017: {impl.clause}")
+    console.print(f"Уровень по умолчанию: {impl.severity.value}")
+    console.print(f"Объявлено в: {impl.module}")
+    if impl.description:
+        console.print("")
+        console.print(impl.description)
+        console.print("")
+    if impl.default_params:
+        console.print("Параметры по умолчанию:")
+        for name, value in sorted(impl.default_params.items()):
+            console.print(f"  {name} = {value!r}")
+
+
+@profile_app.command("show")
+def profile_show(
+    profile_source: str = typer.Option(
+        None, "--profile", "-p", help="Имя встроенного профиля либо путь к TOML."
+    ),
+) -> None:
+    """Итоговый набор правил после применения профиля."""
+    registry = load_rules()
+    try:
+        profile = load_profile(profile_source)
+        validate_profile(profile, registry)
+    except ProfileError as error:
+        err_console.print(f"Профиль: {error}")
+        raise typer.Exit(EXIT_INTERNAL_ERROR) from None
+
+    profile = profile.resolve(registry.default_params())
+    active = {impl.id for impl in select_rules(registry, profile=profile)}
+
+    console.print(f"Профиль: [bold]{profile.name}[/bold]")
+    console.print(f"Правил включено: {len(active)} из {len(registry)}")
+    if not len(registry):
+        return
+
+    table = Table(box=None, pad_edge=False)
+    table.add_column("ID")
+    table.add_column("Уровень")
+    table.add_column("Состояние")
+    table.add_column("Параметры")
+    for impl in registry:
+        severity = profile.severity_for(impl.id, impl.severity)
+        changed = "" if severity is impl.severity else f" (было {impl.severity.value})"
+        params = profile.params_for(impl.id)
+        table.add_row(
+            impl.id,
+            f"{severity.value}{changed}",
+            "включено" if impl.id in active else "отключено",
+            ", ".join(f"{k}={v!r}" for k, v in sorted(params.items())),
+        )
+    console.print(table)
+
+
+@app.command("check")
+def check(
+    paths: list[Path] = typer.Argument(..., help="Файлы или каталоги с исходниками .tex."),
+    profile_source: str = typer.Option(
+        None, "--profile", "-p", help="Имя встроенного профиля либо путь к TOML."
+    ),
+    output_format: OutputFormat = typer.Option(
+        OutputFormat.HUMAN, "--format", "-f", help="Формат вывода."
+    ),
+    select: str = typer.Option(
+        None, "--select", help="Запустить только эти правила, через запятую."
+    ),
+    ignore: str = typer.Option(None, "--ignore", help="Исключить эти правила, через запятую."),
+    severity: Severity = typer.Option(
+        Severity.INFO, "--severity", help="Не показывать находки ниже уровня."
+    ),
+    limit: int = typer.Option(
+        agent.DEFAULT_LIMIT, "--limit", help="Предел числа находок в выводе; 0 — без предела."
+    ),
+    fix: bool = typer.Option(False, "--fix", help="Применить правки к исходникам."),
+    show_diff: bool = typer.Option(
+        False, "--diff", help="Показать правки как diff, ничего не записывая."
+    ),
+    baseline_path: Path = typer.Option(
+        None, "--baseline", help="Снимок известных нарушений: показывать только новые."
+    ),
+    write_baseline: Path = typer.Option(
+        None, "--write-baseline", help="Записать снимок текущих находок и выйти."
+    ),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Только код возврата."),
+) -> None:
+    """Проверить исходники отчёта на соответствие ГОСТ 7.32-2017."""
+    missing = [path for path in paths if not path.exists()]
+    if missing:
+        err_console.print("Не найдено: " + ", ".join(str(path) for path in missing))
+        raise typer.Exit(EXIT_INTERNAL_ERROR)
+
+    registry = load_rules()
+    try:
+        profile = load_profile(profile_source)
+        validate_profile(profile, registry)
+        selected_rules, _ = partition_ids(_split(select))
+        ignored_rules, ignored_internal = partition_ids(_split(ignore))
+        rules = select_rules(
+            registry,
+            profile=profile,
+            select=selected_rules,
+            ignore=ignored_rules,
+        )
+        baseline = Baseline.load(baseline_path) if baseline_path is not None else None
+    except (ProfileError, UnknownRuleError, BaselineError) as error:
+        err_console.print(str(error))
+        raise typer.Exit(EXIT_INTERNAL_ERROR) from None
+
+    check_run = _Check(
+        paths=paths,
+        rules=rules,
+        profile=profile.resolve(registry.default_params()),
+        baseline=baseline,
+        ignored=ignored_internal | (profile.disabled & frozenset(INTERNAL)),
+        known_ids=frozenset(impl.id for impl in registry) | frozenset(INTERNAL),
+        # Снимок фиксируется по всем находкам: иначе его содержимое зависело бы
+        # от ключа --severity, с которым его записали.
+        threshold=Severity.INFO if write_baseline is not None else severity,
+    )
+    result = check_run()
+
+    if write_baseline is not None:
+        _write_baseline(write_baseline, result)
+        raise typer.Exit(EXIT_OK)
+
+    if show_diff:
+        sys.stdout.write(_diff(check_run, result))
+        raise typer.Exit(EXIT_OK)
+
+    if fix:
+        result = _apply_fixes(check_run, result)
+
+    if not quiet:
+        _report(result, output_format, limit)
+    raise typer.Exit(EXIT_FOUND_ERRORS if result.has_errors else EXIT_OK)
+
+
+@dataclass(frozen=True, slots=True)
+class _Check:
+    """Один прогон проверки. Ключ ``--fix`` повторяет его после каждой правки."""
+
+    paths: list[Path]
+    rules: tuple[RuleImpl, ...]
+    profile: Profile
+    baseline: Baseline | None
+    ignored: frozenset[str]
+    known_ids: frozenset[str]
+    threshold: Severity
+
+    def __call__(self, overlay: dict[Path, str] | None = None) -> RunResult:
+        parsed = parse(self.paths, self.profile, overlay)
+        return run(
+            parsed.document,
+            self.rules,
+            extra_findings=parse_findings(parsed),
+            threshold=self.threshold,
+            suppressions=parsed.suppressions,
+            baseline=self.baseline,
+            ignored=self.ignored,
+            known_ids=self.known_ids,
+        )
+
+
+def _diff(check_run: _Check, result: RunResult) -> str:
+    """Показать всё, что сделал бы ``--fix``, ничего не записывая."""
+    overlay: dict[Path, str] = {}
+    for _ in range(FIX_PASSES):
+        prepared = plan(result.findings, overlay)
+        if not prepared.applied:
+            break
+        overlay.update({edit.path: edit.text for edit in prepared.edits})
+        result = check_run(overlay)
+    return diff(overlay)
+
+
+def _apply_fixes(check_run: _Check, result: RunResult) -> RunResult:
+    """Применять правки, пока они находятся, и перепроверять исходники.
+
+    Проходов несколько: пересекающиеся правки в один проход не применяются,
+    а исправленное место может открыть следующее нарушение.
+    """
+    applied = 0
+    reported: set[Path] = set()
+    for _ in range(FIX_PASSES):
+        prepared = plan(result.findings)
+        for path in prepared.skipped:
+            if path not in reported:
+                reported.add(path)
+                err_console.print(f"Не удалось прочитать как UTF-8, пропущен: {path}")
+        if not prepared.applied:
+            break
+        applied += write(prepared)
+        result = check_run()
+
+    if applied:
+        console.print(f"Исправлено находок: {applied}.")
+    return result
+
+
+def _write_baseline(path: Path, result: RunResult) -> None:
+    snapshot = Baseline.of(result.findings)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(snapshot.dumps(__version__), encoding="utf-8")
+    console.print(f"Записано находок в снимок: {len(result.findings)} → {path}")
+
+
+def _report(result: RunResult, output_format: OutputFormat, limit: int) -> None:
+    # agent и json пишутся в stdout напрямую: Rich переносил бы длинные строки,
+    # а оба формата копируются и разбираются как есть.
+    if output_format is OutputFormat.JSON:
+        sys.stdout.write(json_report.render(result))
+    elif output_format is OutputFormat.AGENT:
+        command = " ".join(["nk", *sys.argv[1:]])
+        sys.stdout.write(agent.render(result, command=command, limit=limit))
+    else:
+        human.render(result, console)
+
+
+def _split(value: str | None) -> list[str] | None:
+    if value is None:
+        return None
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+@rules_app.command("docs")
+def rules_docs_command(
+    output: Path = typer.Option(
+        Path("docs/rules"), "--output", "-o", help="Каталог, куда записать страницы правил."
+    ),
+    fixtures: Path = typer.Option(
+        examples.DEFAULT_FIXTURES_ROOT,
+        "--fixtures",
+        help="Каталог фикстур, из которых берутся примеры.",
+    ),
+) -> None:
+    """Сгенерировать страницы документации по правилам."""
+    registry = load_rules()
+    written, removed = rules_docs.write_pages(registry, output, fixtures_root=fixtures)
+    console.print(f"Записано страниц: {written} → {output}")
+    if removed:
+        console.print(f"Удалено устаревших: {removed}")

nk/core/__init__.py

@@ -0,0 +1 @@
+"""Ядро: контракты находки, правила, документа и профиля."""

nk/core/baseline.py

@@ -0,0 +1,94 @@
+"""Снимок известных нарушений.
+
+Линтер, включённый на готовой работе, выдаёт сотни находок сразу. Снимок фиксирует
+текущее состояние, и дальше показываются только новые нарушения: работа чинится
+постепенно, а не «когда-нибудь потом».
+
+Находка опознаётся не номером строки, а содержимым строки нарушения: отчёт растёт
+весь семестр, и вставка абзаца выше не должна воскрешать все находки ниже. Если же
+саму строку правили — находка всплывёт снова, и это правильно.
+"""
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from hashlib import sha256
+from pathlib import Path
+from typing import Any
+
+from nk.core.finding import Finding
+
+SCHEMA_VERSION = "1.0"
+TOOL_NAME = "nk"
+FINGERPRINT_LENGTH = 16
+
+#: Путь, ключ и отпечаток строки нарушения.
+Key = tuple[str, str, str]
+
+
+class BaselineError(ValueError):
+    """Снимок не читается или испорчен."""
+
+
+@dataclass(frozen=True, slots=True)
+class Baseline:
+    counts: dict[Key, int] = field(default_factory=dict)
+
+    @classmethod
+    def of(cls, findings: tuple[Finding, ...]) -> "Baseline":
+        return cls(dict(Counter(fingerprint(finding) for finding in findings)))
+
+    @classmethod
+    def load(cls, path: Path) -> "Baseline":
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except OSError as error:
+            raise BaselineError(f"не удалось прочитать снимок {path}: {error}") from error
+        except json.JSONDecodeError as error:
+            raise BaselineError(f"снимок {path} испорчен: {error}") from error
+
+        version = data.get("schema_version")
+        if version != SCHEMA_VERSION:
+            raise BaselineError(
+                f"снимок {path} версии {version!r}, поддерживается {SCHEMA_VERSION!r}"
+            )
+        try:
+            counts = {
+                (entry["path"], entry["rule_id"], entry["fingerprint"]): int(entry["count"])
+                for entry in data["entries"]
+            }
+        except (KeyError, TypeError, ValueError) as error:
+            raise BaselineError(f"снимок {path}: неожиданная структура записи ({error})") from error
+        return cls(counts)
+
+    def dumps(self, version: str) -> str:
+        entries = [
+            {"path": path, "rule_id": rule_id, "fingerprint": digest, "count": count}
+            for (path, rule_id, digest), count in sorted(self.counts.items())
+        ]
+        payload: dict[str, Any] = {
+            "schema_version": SCHEMA_VERSION,
+            "tool": {"name": TOOL_NAME, "version": version},
+            "entries": entries,
+        }
+        return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+
+    def filter(self, findings: tuple[Finding, ...]) -> tuple[tuple[Finding, ...], int]:
+        """Отсеять находки, уже учтённые снимком."""
+        remaining = dict(self.counts)
+        kept: list[Finding] = []
+        for finding in findings:
+            key = fingerprint(finding)
+            available = remaining.get(key, 0)
+            if available:
+                remaining[key] = available - 1
+                continue
+            kept.append(finding)
+        return tuple(kept), len(findings) - len(kept)
+
+
+def fingerprint(finding: Finding) -> Key:
+    """Ключ находки, устойчивый к сдвигу строк."""
+    excerpt = " ".join((finding.excerpt or "").split())
+    digest = sha256(excerpt.encode("utf-8")).hexdigest()[:FINGERPRINT_LENGTH]
+    return (str(finding.path), finding.rule_id, digest)

nk/core/diagnostics.py

@@ -0,0 +1,44 @@
+"""Внутренние диагностики линтера.
+
+Это не правила: они не проверяют требований стандарта, не имеют пункта и фикстур.
+Но отключать их профилем и ключом ``--ignore`` нужно так же, как правила, поэтому
+их идентификаторы перечислены здесь.
+"""
+
+from dataclasses import dataclass
+
+from nk.core.finding import Severity
+
+#: Диагностики не ссылаются на пункт стандарта.
+NO_CLAUSE = ""
+
+INPUT_MISSING = "NK-PARSE-001"
+INPUT_CYCLE = "NK-PARSE-002"
+ENVIRONMENT_UNCLOSED = "NK-PARSE-003"
+ENVIRONMENT_ORPHAN_END = "NK-PARSE-004"
+GROUP_UNCLOSED = "NK-PARSE-005"
+ENCODING_FALLBACK = "NK-PARSE-006"
+IGNORE_UNUSED = "NK-IGNORE-001"
+IGNORE_UNKNOWN = "NK-IGNORE-002"
+
+
+@dataclass(frozen=True, slots=True)
+class Diagnostic:
+    code: str
+    severity: Severity
+    title: str
+
+
+INTERNAL: dict[str, Diagnostic] = {
+    item.code: item
+    for item in (
+        Diagnostic(INPUT_MISSING, Severity.INFO, "Включаемый файл не найден"),
+        Diagnostic(INPUT_CYCLE, Severity.INFO, "Циклическое включение файла"),
+        Diagnostic(ENVIRONMENT_UNCLOSED, Severity.INFO, "Окружение не закрыто"),
+        Diagnostic(ENVIRONMENT_ORPHAN_END, Severity.INFO, "\\end без парного \\begin"),
+        Diagnostic(GROUP_UNCLOSED, Severity.INFO, "Не закрыта скобка аргумента"),
+        Diagnostic(ENCODING_FALLBACK, Severity.INFO, "Файл не в UTF-8"),
+        Diagnostic(IGNORE_UNUSED, Severity.WARNING, "Подавление ничего не подавило"),
+        Diagnostic(IGNORE_UNKNOWN, Severity.WARNING, "Подавление ссылается на неизвестное правило"),
+    )
+}