srekit doctor¶

Показывает состояние, которое srekit резолвит до того, как отрендерит хоть байт: какой конфиг реально читается (и не затенён ли второй), куда резолвится директория шаблонов и парсятся ли ещё её артефакты, резолвится ли вообще author identity, есть ли git в PATH.

srekit doctor                                   # полный отчёт
srekit doctor --quiet                           # только то, что требует внимания
srekit doctor --json | jq -e '.status != "error"'   # гейт в CI

doctor только читает. Он ничего не создаёт, не меняет и не чинит — если объект проверки отсутствует, это сообщается, а не создаётся. Сетевых запросов нет вообще, включая проверку новых релизов srekit. git — единственная внешняя программа, которую он ищет.

Флаги¶

Флаг	Эффект
`--json`	отдать находки как JSON-документ вместо таблицы
`--config FILE`	наследуется от корневой команды; меняет, какой конфиг инспектируется
`--templates-dir DIR`	наследуется от корневой команды; меняет, какая директория шаблонов инспектируется
`--quiet` / `-q`	печатать только находки `warn` и `error`, без итоговой строки

Флагов --out, --stdout, --force и --dry-run нет: doctor ничего не пишет, а флага, который команда молча игнорирует, существовать не должно.

Статусы и код возврата¶

Статус	Значение
`ok`	делать нечего
`warn`	srekit работает, но что-то игнорируется, устарело или скоро сломается
`error`	генератор в этом окружении упадёт или выдаст неверный результат

Код возврата — 1, если хотя бы одна проверка дала error, иначе 0. warn никогда не роняет прогон, поэтому команду можно взять в CI, не завися от advisory-находок. --quiet код возврата не меняет: в здоровом окружении srekit doctor --quiet не печатает ничего и выходит с 0, то есть тишина означает «всё в порядке».

Проверка, которая не смогла проинспектировать свой объект (нечитаемая директория, не стартующий подпроцесс), сообщает об этом собственной находкой. Выполняются всегда все проверки: одна сломанная не прячет остальные.

Проверки¶

Идентификаторы проверок — стабильный публичный контракт: на них строят гейты в CI, поэтому переименование считается breaking change.

`config`¶

Идентификатор	Что сообщает
`config.file`	Конфиг, который реально будет прочитан, и есть ли он — с указанием XDG- или legacy-локации либо явного `--config`. Отсутствие файла на свежей установке — задокументированный дефолт, а не дефект, поэтому это `ok`.
`config.parse`	Парсится ли этот файл. Битый конфиг — `warn`, не `error`: он никогда не роняет команду, которой из него ничего не нужно, — именно поэтому больше нигде о нём не сообщается.
`config.shadowed`	`warn`, когда существуют одновременно `~/.srekit.yaml` и `$XDG_CONFIG_HOME/srekit/config.yaml`: называет, какой из них побеждает, а какой не читается никогда.
`config.writable`	Доступна ли на запись директория, в которой лежит резолвнутый путь конфига, — чтобы узнать об этом до запуска `config init`, а не после.
`config.env`	Все переменные окружения с префиксом `SREKIT_`, действующие сейчас, по именам.
`config.templates-dir`	Резолвнутая директория шаблонов, источник значения (`--templates-dir`, `SREKIT_TEMPLATES_DIR`, конфиг или встроенный дефолт), существует ли путь и директория ли это. Настроенная, но отсутствующая директория — `warn`: генерация продолжает работать на embedded-наборе, но ваши override'ы молча не применяются.
`config.templates-shadowed`	`warn`, когда существуют одновременно `~/.srekit/templates` и `$XDG_CONFIG_HOME/srekit/templates`: называет, с какой из них работают подкоманды `templates`.
`config.identity`	Резолвятся ли вообще имя и email автора и из какого источника пришло каждое значение. `error`, если не резолвится хоть одно, — каждый генератор, который штампует автора, в таком окружении упадёт. Значения печатаются как есть: они и так попадают в каждый сгенерированный артефакт, а редактирование сделало бы проверку бесполезной для разбора «почему в RFC не тот автор».

`templates`¶

Все три сообщают ok с embedded-only summary, если директория шаблонов не настроена или настроенная не существует.

Идентификатор	Что сообщает
`templates.parse`	Сколько артефактов в директории не парсится, с именем каждого файла и его ошибкой парсинга. Любая ошибка парсинга — `error`: стоящий за артефактом генератор не сможет отрендерить ничего. Используется тот же парсер, что и в `srekit templates validate`.
`templates.legacy`	Сколько в директории файлов шаблонов формата до v1.0 (`.tmpl`, `.sections.yaml`), с их именами. `warn`, лечится `srekit templates migrate`.
`templates.drift`	Сколько артефактов отличается от embedded-версии этого бинаря и сколько embedded-артефактов в директории отсутствует. `warn`, если хотя бы один счётчик ненулевой; лечится `srekit templates diff` и `srekit templates upgrade`. Используется та же классификация, что и в `srekit templates list`, поэтому разойтись они не могут.

`dependencies`¶

Идентификатор Что сообщает

dependencies.git Есть ли git в PATH, и если есть — его резолвнутый путь и версия, которую он печатает. Отсутствие git — warn, а не error: метаданные автора и repository slug для changelog фолбэчатся на флаги и конфиг, поэтому большая часть генерации продолжает работать.

Текстовый вывод¶

CONFIG
  ok     config.file                no config file at /home/u/.config/srekit/config.yaml (XDG location); flags, environment and defaults supply everything
  warn   config.templates-dir       /home/u/tpl (from SREKIT_TEMPLATES_DIR) cannot be read: no such file or directory; generation is falling back to the embedded templates
                                    fix: run 'srekit templates init /home/u/tpl', or point SREKIT_TEMPLATES_DIR somewhere that exists
  ...

DEPENDENCIES
  ok     dependencies.git           /usr/bin/git (git version 2.51.0)

12 checks: 11 ok, 1 warn, 0 error

Находки сгруппированы по категориям и всегда идут в одном и том же порядке, так что два прогона по неизменному окружению дают одинаковый вывод. Каждый warn и error несёт remedy с именем команды или настройки, которая это чинит, — отдельной строкой-продолжением. Последняя строка — счётчики по статусам.

Статус передаётся самим словом, поэтому вывод остаётся читаемым в пайпе. Цвет включается, только когда stdout — терминал, и подавляется, если переменная NO_COLOR установлена и непустая.

JSON-вывод¶

--json печатает в stdout один документ с отступами, завершённый переводом строки, и больше ничего. Ключи — camelCase. Код возврата тот же, что и у текстового вывода, поэтому --json можно отдать парсеру и всё равно использовать как гейт в CI.

{
  "status": "warn",
  "checks": [
    {
      "id": "config.file",
      "category": "config",
      "status": "ok",
      "summary": "reading /home/u/.srekit.yaml (legacy location)"
    },
    {
      "id": "dependencies.git",
      "category": "dependencies",
      "status": "warn",
      "summary": "git is not on PATH; author name and email fall back to --author/--email and the config file, and 'srekit changelog' cannot detect the repository slug",
      "remedy": "install git, or pass --author/--email and --repo OWNER/REPO explicitly"
    }
  ]
}

status — худший статус среди находок. remedy присутствует всегда, когда статус warn или error.

На --json флаг --quiet не влияет: это документ с данными, и потребитель, который попросил полную структуру и получил её подмножество, получил баг, а не удобство.

См. также¶

Конфигурация — правила резолва, о которых отчитывается doctor.
srekit templates — команды, на которые указывает большинство remedy категории templates.
srekit config init — лечение нерезолвящегося author identity.