Использование¶

Проверка исходников¶

nk check принимает файлы и каталоги; каталог обходится рекурсивно по .tex.

nk check chapters
nk check report.tex chapters/method.tex

Часть правил — состав и порядок структурных элементов, ссылки на приложения — имеет смысл только на полном документе. На отдельной главе они молчат: судить по фрагменту о том, что в отчёте нет заключения, нельзя.

Порядок отчёта задают включения из главного файла: обход каталога начинается с файла, где есть \begin{document}, и дальше идёт по \input и \include. Файлы, которые главный документ не включает, проверяются после него.

Заголовки, набранные макросом шаблона¶

Шаблоны кафедр обычно прячут заголовок за собственным макросом:

\newcommand{\ssr}[1]{\section*{\centering #1}}
...
\ssr{ВВЕДЕНИЕ}

Такие макросы разбираются по их объявлению: если макрос передаёт свой параметр команде рубрикации, линтер считает его заголовком того же уровня. Разбираются формы \newcommand, \renewcommand, \providecommand, \DeclareRobustCommand и \def, в том числе через промежуточный макрос.

Команду рубрикации такой макрос зовёт не всегда — часто заголовок набирают вручную, а в содержание пишут его сами:

\newcommand{\ssr}[1]{\begin{center}
\LARGE\bfseries{#1}
\end{center} \addcontentsline{toc}{chapter}{#1}}

Запись в содержание уровня главы или раздела — такой же признак заголовка, как и \chapter; номера у него нет, поэтому рубрика считается ненумерованной. Не опознаются макросы из .sty, объявленные через \@startsection, и макросы с намертво вписанным названием заголовка: подставить его текст в находку нечем.

Ключи `check`¶

Ключ	Назначение
`--profile PATH`	TOML-профиль; без ключа профиль ищется рядом с исходниками
`--format {human,agent,json}`	формат вывода, по умолчанию `human`
`--select ID,...`	запустить только указанные правила
`--ignore ID,...`	исключить правила
`--severity LEVEL`	не показывать находки ниже уровня
`--limit N`	предел числа находок в выводе; по умолчанию 50, `0` — без предела
`--fix`	применить правки к исходникам
`--diff`	показать правки как diff, ничего не записывая
`--baseline PATH`	снимок известных нарушений: показывать только новые
`--write-baseline PATH`	записать снимок текущих находок и выйти
`--quiet`	только код возврата

Неизвестный идентификатор в --select или --ignore — ошибка, а не молчаливый пропуск: иначе опечатка выключала бы проверку незаметно.

Коды возврата¶

Код	Значение
`0`	находок уровня `error` нет
`1`	есть находки уровня `error`
`2`	внутренняя ошибка: не найден файл, битый профиль, неизвестное или упавшее правило

Уровни warning и info на код возврата не влияют. Чтобы сборка падала и на предупреждениях, поднимите им уровень профилем.

Правило, упавшее с исключением, пропускается и даёт код 2 даже при чистом отчёте и с ключами --diff и --write-baseline: часть проверок не выполнилась, и зелёный прогон в CI был бы обманом. Снимок при этом не записывается: он навсегда скрыл бы находки пропущенных проверок.

Форматы вывода¶

`human`¶

Разметка для чтения в терминале: находки сгруппированы по файлам, вокруг каждой показан контекст, строка с нарушением помечена стрелкой. Если нарушение в конкретном знаке — лишнем пробеле, дефисе вместо тире, — под ним ставится указатель. В конце — сводка по уровням и, если правки есть, их число вместе с командой, которая их применит.

Идентификатор правила в этом формате — ссылка на его страницу в документации: если находка непонятна, пример нарушения и правки открывается щелчком по идентификатору. Терминалы без поддержки ссылок покажут просто идентификатор.

$ nk check chapters
chapters/method.tex
  8:3  error  figure-caption-dot
    Нарушение: Наименование рисунка заканчивается точкой.
    Требуется: Наименование рисунка приводят с прописной буквы без точки в конце.
    Исправить: \caption{Схема экспериментальной установки}
      6 |   \centering
      7 |   \includegraphics[width=0.8\textwidth]{img/setup.png}
    > 8 |   \caption{Схема экспериментальной установки.}
      9 | \end{figure}

Итого: 1 error, 0 warning, 0 info.
Исправимо ключом --fix: 1
Другие форматы: --format json | agent

`agent`¶

Тот же текст без разметки Rich, с шапкой из команды и профиля и с путём в каждой строке. Предназначен для передачи агенту: вывод копируется целиком, без пояснений от человека.

$ nk check chapters --format agent
Команда: nk check chapters --format agent
Профиль: base, файлов проверено: 12

chapters/method.tex:8:3  error  figure-caption-dot
  Нарушение: Наименование рисунка заканчивается точкой.
  Требуется: Наименование рисунка приводят с прописной буквы без точки в конце.
  Исправить: \caption{Схема экспериментальной установки}
  Контекст:
    6 |   \centering
    7 |   \includegraphics[width=0.8\textwidth]{img/setup.png}
    8 |   \caption{Схема экспериментальной установки.}
    9 | \end{figure}

Итого: 1 error, 0 warning, 0 info.
Исправимо ключом --fix: 1

Число находок в этом формате ограничено: длинный вывод вытесняет из контекста агента сам отчёт. Предел снимается ключом --limit 0.

`json`¶

Машинный формат с полем schema_version: для своих отчётов, дашбордов и аннотаций в CI.

$ nk check chapters --format json
{
  "schema_version": "1.4",
  "tool": { "name": "nk", "version": "0.3.0" },
  "profile": "base",
  "summary": { "error": 4, "warning": 0, "info": 0, "files_checked": 12, "fixable": 3 },
  "suppressed": { "inline": 3, "baseline": 12 },
  "findings": [ ... ],
  "failed_rules": []
}

У каждой находки есть признак fixable, в сводке — их число: по нему сборка решает, стоит ли гонять --fix, не разбирая находки по одной.

Автоисправление¶

Часть нарушений чинится механически: точка в конце наименования, номер, вписанный вручную, строчная буква в начале, двоеточие после «где». Такие правила помечены на своих страницах как исправимые, а nk умеет применить правку сам. Сколько находок из выданных чинится автоматически, сказано в конце вывода.

Сначала посмотреть, что изменится:

nk check chapters --diff

Затем применить:

nk check chapters --fix

$ nk check chapters --fix

Итого: 3 error, 0 warning, 0 info (исправлено 12).

Правится только то, для чего замена однозначна. «Перенести подпись ниже рисунка», «добавить ссылку в текст», «заменить «рис.» на «рисунок»» — это не правки: в первых двух нужно решение о структуре, в третьем — согласование падежа. Такие находки остаются в выводе после --fix, и код возврата их учитывает.

Проходов делается несколько: на одной подписи может быть сразу четыре нарушения, а пересекающиеся правки за один проход не применяются. --diff показывает итог всех проходов, как если бы --fix уже отработал.

Warning

--fix переписывает файлы на месте. Прогоняйте его на исходниках под контролем версий, а перед первым запуском посмотрите --diff.

Правки уважают подавления: заглушенная находка не чинится. Переводы строк и кодировка файла сохраняются; файл не в UTF-8 пропускается с сообщением.

Подавление отдельных находок¶

Иногда нарушение осознанное: на кафедре принято иначе, конструкция вынужденная, или правило ошибается на конкретном месте. Такое место заглушается комментарием в самом исходнике.

\caption{Схема установки.}   % nk: ignore
\caption{Схема установки.}   % nk: ignore figure-caption-dot
\caption{Схема установки.}   % nk: ignore figure-caption-dot -- вынужденно, см. ТЗ

Без перечня идентификаторов подавляются все находки на этой строке; с перечнем — только названные. Через -- пишется причина: она нужна тому, кто через полгода будет разбираться, почему тут заглушка.

Директива действует на строку, где стоит. Если конструкция занимает несколько строк, ставьте её туда, куда указывает находка, — то есть на начало команды:

\caption{Зависимость погрешности от числа % nk: ignore figure-caption-dot
измерений.}

Для всего файла — ignore-file, в любом его месте, но по традиции первой строкой:

% nk: ignore-file figure-reference-word -- на кафедре принято «рис.»

Линтер следит и за самими директивами: подавление, которое ничего не подавило, даёт NK-IGNORE-001, а ссылающееся на несуществующее правило — NK-IGNORE-002. Иначе заглушки переживают исправленные нарушения и копятся годами.

Снимок известных нарушений¶

Запущенный на готовой работе линтер выдаёт сотни находок сразу, и его перестают запускать. Снимок фиксирует текущее состояние, дальше показываются только новые нарушения.

nk check chapters --write-baseline .nk-baseline.json

Файл кладётся в репозиторий рядом с исходниками. Дальше:

nk check chapters --baseline .nk-baseline.json

Находка опознаётся не номером строки, а содержимым строки нарушения. Поэтому вставка абзаца выше не воскрешает все находки ниже, а правка самой строки — воскрешает, и это правильно: раз строку трогали, её пора привести в порядок.

Снимок пишется по полному набору находок, независимо от --severity: иначе его содержимое зависело бы от ключа, с которым его записали. Исправив часть работы, перезапишите снимок той же командой.

Внутренние диагностики¶

Кроме правил линтер выдаёт собственные замечания: они не проверяют требований стандарта, не имеют пункта и начинаются с NK-.

Код	Уровень	Когда
`NK-PARSE-001`	`info`	Включаемый файл не найден
`NK-PARSE-002`	`info`	Циклическое включение файла
`NK-PARSE-003`	`info`	Окружение не закрыто
`NK-PARSE-004`	`info`	\end без парного \begin
`NK-PARSE-005`	`info`	Не закрыта скобка аргумента
`NK-PARSE-006`	`info`	Файл не в UTF-8
`NK-IGNORE-001`	`warning`	Подавление ничего не подавило
`NK-IGNORE-002`	`warning`	Подавление ссылается на неизвестное правило

Отключаются как обычные правила — ключом --ignore или в disable профиля.

Сведения о правилах¶

nk rules list             # перечень: идентификатор, категория, уровень, название
nk rules show RULE_ID     # подробности: источник требования, пункты, параметры
nk profile show -p PATH   # итоговый набор правил после применения профиля

nk rules docs пересобирает раздел Правила этой документации — команда для разработки, не для проверки отчёта.