CONTRIBUTING.md

Участие в разработке

Спасибо за интерес к плагину. Ниже — что нужно знать, прежде чем открывать issue или PR.

Что здесь особенно ценно

Ложные срабатывания. Находка на коде, который на самом деле корректен, вреднее пропущенного дефекта: она провоцирует переделку работающего механизма и подрывает доверие ко всем остальным проверкам. Если контур придрался к нормальному коду — это баг высокого приоритета. В issue приведите фрагмент (обезличенный) и объясните, почему такая форма законна: скорее всего, у признака не хватает контр-сигнала.

Пропущенные антипаттерны кода, написанного моделью. Файлы ai-antipatterns.md и ai-antipatterns-arch.md — самая ценная часть плагина, и они пополняются из практики. Если вы переписывали за агентом код и заметили повторяющуюся ошибку, которой нет в типовых сводах, — это отличный вклад.

Неточности в правилах платформы. Плагин утверждает вещи о поведении 1С (что проверяет загрузка конфигурации, что делает запись набора с отбором, где допустимы символы). Если утверждение неверно или устарело — поправьте со ссылкой на проверяемый факт.

Чего здесь не будет

Тексты стандартов разработки. Плагин публикует только ссылки и номера; тексты запрашиваются через MCP v8std во время работы. PR, добавляющий скопированные тексты, принят не будет — это лицензионное ограничение.

Проектные данные. Имена систем, модулей, полей внешних контрактов, пути машин. Правила формулируются обезличенно. Проверяется автоматически.

Правила без сигнала. «Так писать некрасиво» не является находкой. У каждой проверки должен быть измеримый признак и порог, иначе спорить с ней нечем, и её справедливо проигнорируют.

Требования к изменениям

Перед отправкой PR:

node tests/run-tests.mjs             # тесты программных проверок
node tools/validate-package.mjs      # целостность пакета, ссылки, отсутствие утечек
node tools/gen-signs-map-md.mjs      # если менялся signs-map.json

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

CI гоняет то же самое плюс компиляцию Python-валидаторов XML и сверку производной карты признаков с источником. Валидаторам нужен lxml (pip install lxml): без него их тесты локально пропускаются с явной пометкой, а в CI прогон падает — пропуск там запрещён.

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

Новый признак архитектуры добавляется в signs-map.json (источник истины), после чего signs-map.md перегенерируется скриптом. Правка производного файла руками рассинхронизирует его с источником — CI это поймает.

Структура коммитов

Conventional Commits на русском: <тип>(<область>): описание.

Типы: feat, fix, docs, refactor, chore, test. Область — имя контура или компонента (контур-кода, гейт, контур-архитектуры). Описание — в повелительном наклонении, без точки.

В теле коммита полезно объяснить почему, а не только что: правила этого плагина часто неочевидны, и через полгода причина забывается.

Лицензия

Вклад принимается на условиях MIT — той же лицензии, под которой распространяется плагин.