Контракт¶

Что в ОТК стабильно в пределах 1.x — на это можно опираться в хуках, CI и инструкциях агентов. В контракте поля, значения, ключи и флаги только добавляются; переименование или удаление — только в 2.0.

Что входит¶

Входит	Не входит (может меняться в 1.x)
команды и флаги `otk`, коды выхода	текст вывода в консоль и журналов
ключи `otk.toml` / `otk.local.toml`, переменные `OTK_*`	текст `summary.md` и `summary.html`
`summary.json`, `junit.xml`, `summary.sarif`, `problems.txt`	`static.json`, `run.json`, `designer.json`, `designer-check.json`
итоги `otk gate --json`, `otk doctor --json`	журналы `logs/`, состояние копии ИБ `otk-state.json`
план `otk.json` (`otk collect --out`)	модули Python пакета `otk_1c` (API — это команда `otk`)
коды причин (`reasonCode`) и правила находок (`rule`)	тексты сообщений и `remediation`

Внутренний файл JSON первым полем несёт $comment — формат меняется без предупреждения, править вручную не нужно.

Схемы¶

Каждый файл JSON начинается с schema — имя и версия формата (otk.summary.v1, otk.gate-result.v1, otk.doctor-result.v1, otk.plan.v1) — и version — версия ОТК, которая его записала. Схемы лежат в пакете (src/otk_1c/schema/) и на сайте документации по адресу из $id, например https://cmapnep-tools.github.io/otk-1c/schema/gate-result.v1.json.

Правила чтения:

незнакомое поле — пропустить: в v1 поля только добавляются, схемы контракта его допускают;
незнакомое значение открытого перечисления — как неизвестное: код причины — как other (действовать по remediation), status итога — по коду выхода; открытые перечисления в схеме — anyOf из известных значений и строки;
закрыты (новых значений в 1.x не будет): код выхода code, важность severity (error, warning), режим проверки (on, auto, off);
другое имя или версия в schema — другой формат: otk.summary.v2 читатель v1 не разбирает.

Имена¶

Поля JSON и ключи настроек — camelCase (reasonCode, summaryPath, bslAnalyzerTimeout, [designerCheck]).
Значения перечислений, имена проверок и анализаторов, команды и флаги — kebab-case (not-checked, ib-busy, platform-api, bsl-analyzer, otk platform-help); имена проверок и анализаторов — и там, где они ключи ([checks] platform-api, [analyzerSeverity] bsl-analyzer).
Имена из чужих словарей — как есть: контексты и виды модулей платформы (Server, CommonModule), варианты встроенного языка (Russian), статусы git (A, M, D, R).
Важность находки — error или warning везде: файлы прогона, [analyzerSeverity], [smoke] severity, SARIF, JUnit.

Коды выхода¶

Для всех команд:

Код	Значит
0	успех: проверка прошла, команда выполнена
1	найдены дефекты в проверяемом коде (`gate`, `report`, `static`, `run`, `designer-check`), контрольный дефект не пойман (`controls`), ошибка в запросе (`console check`)
2	окружение, настройка, вызов или сбой самой ОТК: нет платформы, база занята, обязательная проверка недоступна (`doctor`), битый `otk.toml`, неизвестная команда

Команды без проверяемого кода (collect, doctor, scaffold, availability, tj, mcp, platform-help, help) возвращают только 0 и 2; console — тоже, кроме console check (1 — ошибка в запросе). build — 1, если выгрузка не загрузилась в копию ИБ. ci, hook run и pt возвращают код запущенной проверки.

Настройки и переменные¶

Значение настройки берётся по порядку: аргумент командной строки, переменная OTK_*, otk.local.toml, otk.toml, умолчание. Список переменных и ключей — «Настройки». Неизвестный раздел или ключ — предупреждение (doctor, примечания сводки), прогон продолжается. Что взято из переменных, показывает otk doctor (fromEnv в doctor --json).

Причины «не проверено» и сбоев¶

Код причины (reasonCode) задаёт место, где причина возникла: ОТК не выводит его из своего текста сообщения. По тексту распознаются только сообщения внешних программ (платформа, Конфигуратор, ibcmd); не распознано — other. Список кодов и что делать — «ИИ-агенты».