Линтер для хранилища

trip2g lint <dir> проверяет папку с markdown-заметками и находит битые викиссылки и другие проблемы. Ни сервер, ни база данных не нужны: укажите директорию и запустите.

Что проверяется

Линтер использует тот же движок разрешения ссылок, что и сервер при публикации хранилища. Он находит:

Битые викиссылки: [[название-заметки]], которое указывает на несуществующую заметку.
Утечки между языками: голая [[ссылка]] в заметке из папки ru/, которая разрешается в страницу из en/ (или наоборот). Обычно это означает, что перевод отсутствует и ссылка незаметно перешла в другой языковой раздел.
Битые изображения: ![[image.png]], где файл изображения отсутствует.
Ошибки рендеринга шаблонов: проблемы в Jet-шаблонах _layouts/, которые проявились бы как сломанные страницы при публикации.

Как читать вывод

Каждая проблема занимает одну строку:

path/to/note.md:0: info broken link: some-slug
path/to/note.md:0: warning cross-language wikilink leak: [[Foo]] resolves to /en/foo (note lang=ru, link lang=en)

Формат: файл:строка: уровень сообщение. Строка всегда 0, потому что разрешение викиссылок не отслеживает позиции символов. Уровень бывает info, warning или critical.

Коды выхода:

Код	Значение
0	Всё чисто или только `info`-находки (информационные)
1	Есть хотя бы одна `warning` или `critical`
2	Ошибка использования или директория не загружена

Находки info выводятся, но не прерывают запуск. warning и выше прерывают.

Базовое использование

trip2g lint ./my-vault

Чистое хранилище не выводит ничего и завершается с кодом 0. При проблемах каждая находка выводится на экран, а код завершения равен 1.

Реальный пример

База знаний из концептуальных заметок содержала 24 ссылки, указывавших на заметки из другого хранилища. Линтер нашёл их все:

concepts/agency.md:0: info broken link: self-organization
concepts/cognition.md:0: info broken link: extended-mind
concepts/memory.md:0: info broken link: situated-cognition
...

Решение: заменить внутренние ссылки на раздел «см. также» с указанием внешнего источника. После правки trip2g lint завершился чисто.

Базовая линия: принять известные проблемы, находить только новые

Если хранилище уже содержит битые ссылки, которые нельзя исправить прямо сейчас, базовая линия позволяет CI проходить на существующих проблемах и падать только при появлении новых.

Шаг 1. Сгенерируйте базовую линию из текущего состояния:

trip2g lint --generate-baseline .lint-baseline ./my-vault

Текущие находки записываются в .lint-baseline, команда завершается с кодом 0. Закоммитьте файл базовой линии.

Шаг 2. В CI передайте базовую линию:

trip2g lint --baseline .lint-baseline ./my-vault

Находки, уже вошедшие в базовую линию, подавляются. Выводятся только новые. Код 1 возвращается только при новых warning.

Когда вы исправляете проблему из базовой линии, пересоздайте её: файл должен уменьшаться. Растущая базовая линия сигналит о накоплении долга.

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

Пример для GitHub Actions:

- name: Lint vault
  run: trip2g lint --baseline .lint-baseline ./docs

Строгий вариант без базовой линии (любая находка означает падение):

- name: Lint vault
  run: trip2g lint ./docs

Pre-commit хук

Чтобы проверять перед коммитом:

# .git/hooks/pre-commit
trip2g lint --baseline .lint-baseline ./docs

Сделайте файл исполняемым: chmod +x .git/hooks/pre-commit.

Предупреждения о изображениях

Линтер не разрешает ассеты изображений: у него нет доступа к объектному хранилищу или локальным папкам с файлами. Любая ссылка ![[image.png]] даст находку уровня info, если файл изображения не является заметкой в той же директории. Уровень info не прерывает запуск. Используйте базовую линию, чтобы подавить ложные срабатывания в вашей конфигурации.