Skip to content

CONFIG.md

Latest commit

 

History

History
195 lines (145 loc) · 12.9 KB

CONFIG.md

File metadata and controls

195 lines (145 loc) · 12.9 KB
Raw

Настройка под проект — .1c-quality-gate.json

Один файл в корне проекта. Задаёт пороги профиля изменения, движок анализатора, архетипы конкретной конфигурации и номер стандарта для часового.

Откуда он берётся

Плагин создаёт его сам при первом взводе гейта — то есть при первой правке .bsl или XML метаданных. Раньше этого момента неизвестно, что проект вообще на 1С, а сорить файлом в чужих репозиториях плагин не должен.

Создание разовое:

  • файл уже есть — не трогаем, содержимое не переписываем никогда;
  • файл создавали и его удалили — повторно не создаём. Удаление читается как отказ от настройки, а не как просьба заводить её на каждой правке. Факт создания помнит маркер .claude/.state/qg-config-init.json;
  • нужен обратно — node "$QG/tools/config.mjs" init (или init --force, чтобы перезаписать своим содержимым эталонный шаблон).

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

Файл — командная настройка, а не рабочее состояние: его коммитят. В .gitignore уходит только .claude/.state/ и .qg-analyzer/.

Что действует прямо сейчас

node "$QG/tools/config.mjs" show          # значения и источник каждого
node "$QG/tools/config.mjs" show --json   # то же машиночитаемо
node "$QG/tools/config.mjs" path          # путь к файлу

В колонке источника — умолчание, файл или окружение. Без неё значение 40 неотличимо от «40, потому что проект так решил», а знать это нужно ровно тогда, когда вердикт гейта в двух проектах разошёлся.

Оркестратор quality-gate выполняет эту команду до расчёта осей: пороги берутся из вывода, а не по памяти.

Настройка попадает в след прогона

Последняя строка вывода — готовое поле записи scope:

В запись scope следа прогона: config=custom:volume+sentinel

default — все пороги умолчаний; custom:<секция>[+<секция>] — перечень переопределённых. Без этого поля гейт не снимается: прогон, не заглянувший в настройку, оставлял бы запись, неотличимую от прогона, который её учёл, а «C1» в проекте с переопределёнными порогами означает не то же, что «C1» в соседнем.

Строку печатает инструмент, и она же переносится в отчёт. Валидатор сверяет её с фактической настройкой проекта — сочинённая по памяти отметка не пройдёт: приписать config=default там, где пороги задраны, не сложнее, чем забыть посмотреть настройку, и последствия те же.

Отсюда следствие: если правка .1c-quality-gate.json попала между прогоном и снятием гейта, след устарел вместе с профилем — прогон надо повторить. При обычном линте (evidence-validator.mjs без --gate) отсутствие поля — только предупреждение: отчёты, собранные до его появления, остаются читаемыми.

Приоритет

переменная окружения  >  .1c-quality-gate.json  >  умолчание плагина

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

Ключи

Все секции и все ключи необязательны. Отсутствующая секция, пустая секция и удалённый ключ — одно и то же: действует умолчание.

analyzer — статический анализатор BSL

Ключ Умолчание Значение Переменная
engine bsl-analyzer движок: bsl-analyzer либо bsl-ls QG_ANALYZER_ENGINE
binary — путь к бинарнику; иначе ищется своя установка и ~/.bsl-analyzer/bin/ QG_ANALYZER_BIN
jar — путь к jar; обязателен для bsl-ls QG_ANALYZER_JAR
version — закреплённая версия; несовпадение останавливает прогон QG_ANALYZER_VERSION
required false true — без анализатора гейт не снимается QG_ANALYZER_REQUIRED
autoInstall true false отключает автоустановку QG_ANALYZER_AUTOINSTALL
config — свой конфиг движка вместо гейтового из состава плагина —

Подробности установки, закрепления версии и диагностики — INSTALL.md.

volume — ось объёма

Ключ Умолчание Значение
c1MaxLines 40 больше изменённых строк — правка перестаёт быть точечной, класс поднимается до C2
c1MaxFiles 1 то же по числу файлов

complexity — ось сложности

Ключ Умолчание Значение
maxNesting 4 вложенность в изменённом методе
maxMethodLines 120 длина изменённого метода
maxParams 7 число параметров

Срабатывание любого поднимает контур code до L2, а arch — до уровня 1.

archetypes.custom — архетипы конкретного проекта

Добавляются к встроенной таблице архетипов и участвуют в правиле разрешения глубины наравне с ней.

{
  "archetypes": {
    "custom": [
      { "name": "exchange", "markers": ["ПланОбмена", "ОбменДанными.Загрузка"], "minCode": "L2", "minArch": "1" }
    ]
  }
}
Поле Обязательно Значение
name да имя архетипа; попадает в поле archetypes записи следа
markers да строки, наличие которых в диффе или в пути файла означает срабатывание
minCode да минимальная глубина контура code: L1 либо L2
minArch нет минимальный уровень контура arch: 1, 2 или 3

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

sentinel — часовой источника стандартов

Ключ Умолчание Значение
id std454 номер заведомо существующего стандарта, которым проверяется живость MCP v8std

Если однажды исчезнет именно эта страница, часовой начнёт падать во всех проектах разом, а отличить исчезновение номера от недоступности сервиса будет нечем. Отсюда и настройка.

artifacts.pairs — свежесть собранных артефактов

{
  "artifacts": {
    "pairs": [
      { "source": "src/xml/МояОбработка", "artifact": "build/МояОбработка.epf" }
    ]
  }
}
Поле Обязательно Значение
source да файл или каталог исходников, путь от корня проекта
artifact да собранный из них артефакт, путь от корня проекта

При снятии гейта (gate.mjs release, любой путь снятия) артефакт сравнивается по mtime с самым свежим файлом своего дерева исходников. Артефакт старше — предупреждение в вывод и в журнал снятий плюс строка следа [qg not_verified: dimension=artifact-freshness, reason=artifact_older_than_sources]. Сценарий, ради которого проверка существует: дефект исправлен в исходниках, а пользователь запустил сборку трёхминутной давности — формально гейт чист, практически прогон потерян.

Только предупреждение, не блок: mtime — приближение (checkout и копирование его меняют). Отсутствующий артефакт находкой не считается — его ещё не собирали. Пустая секция — проверки нет: раскладку репозитория плагин не угадывает, пары называет проект.

Ошибки в файле

Неизвестный ключ не применяется, но и не замалчивается: config.mjs show перечисляет такие ключи отдельной строкой. Опечатка в имени выглядит как настройка, которая не сработала, и без этой строки отличить её от «настройки нет» нечем.

Повреждённый JSON не роняет прогон: действуют умолчания, а show печатает, что файл не разобран и настройка не применена. Молчаливый откат к умолчаниям был бы хуже — проект считал бы, что его пороги в силе.

Чего здесь нет намеренно

Настройки диагностик анализатора. Гейт запускает движок со своим конфигом из assets/analyzer/, проектный (.bsl-language-server.json, bsl-analyzer.toml) продолжает править IDE. Иначе отключённая в проекте диагностика делала бы гейт тише, и об этом никто бы не узнал. Переопределяется только явным analyzer.config.

Отключение контуров. Пропуск проверки — решение конкретного прогона, и он обязан оставлять запись skipped с причиной. Настройка «этот контур у нас не гоняем» выключала бы его молча и навсегда.

$QG — каталог установленного плагина. Как его разрешить — раздел «Путь к инструментам плагина» в навыке quality-gate.