Romandredan file-hygiene — контур гигиены файлов
Самый дешёвый контур: читает байты изменённых файлов. Выполняется при любом классе изменения, включая косметический, потому что стоимость околонулевая, а ловит он класс дефектов, который проявляется позже всего и объясняется хуже всего.
Типичная картина: файл выглядит правильно в редакторе, проходит все остальные проверки, а платформа его не принимает — либо принимает, но ведёт себя не так. Причина невидима глазом.
Запуск
node "$QG/tools/hygiene-check.mjs" <файл> [<файл> ...]
Только по явному списку изменённых файлов. Обход всего дерева выгрузки занимает минуты и в гейте недопустим.
Коды возврата: 0 — чисто, 1 — предупреждения, 2 — ошибки.
Что проверяется
| Проверка | Уровень | Почему это важно |
|---|---|---|
| Валидность UTF-8 | 🔴 | запись в однобайтовой кодировке ломает кириллицу необратимо |
| Наличие BOM у модулей и XML | 🟠 | выгрузка 1С хранит их с BOM; без него возможны проблемы с кириллицей |
| Управляющие символы | 🔴 | попадают при программной записи, невидимы в редакторе, ломают разбор |
| Тире вместо ASCII-дефиса | 🟡 | платформа считает недопустимым символом в тексте модуля |
| Смешанные переводы строк | 🟡 | сравнение версий показывает изменённым весь файл |
Про тире — важная тонкость
Проверка различает контекст: тире ищется в коде и комментариях, но не в строковых литералах. В текстах, предназначенных пользователю, длинное тире уместно и встречается даже в типовых модулях конфигураций — правило без различения контекста дало бы сотни ложных находок на первом же прогоне, и контур справедливо отключили бы.
Разбор литералов приближённый: полноценный парсер здесь избыточен, а цена ошибки низкая — находка этого уровня не блокирует вердикт.
Про управляющие символы
Отдельно стоит знать про символ-разделитель группы (U+001D). Он встречается в задачах маркировки как разделитель полей кода, и инструменты записи файлов могут вставить его буквально вместо экранированной последовательности. Глазом он неотличим от отсутствия символа, а разбор ломает. Именно поэтому проверка идёт по байтам, а не по тексту.
Записи следа
[qg applied: layer=hygiene, scope=file-encoding, ids=[qg:HYG-BOM,qg:HYG-CTRL,qg:HYG-DASH,qg:HYG-ENCODING,qg:HYG-EOL], verdict=clean]
[qg applied: layer=hygiene, scope=file-encoding, ids=[qg:HYG-DASH], verdict=violation:qg:HYG-DASH]
Эти строки печатает сам hygiene-check.mjs — переноси его вывод, не составляй запись по
прочтении находок. Инструмент отмечается в журнале прогонов, и валидатор следа сверяет с ним:
вердикт без прогона снятие гейта не пройдёт. Чистый прогон перечисляет все пять правил,
прогон с находками — по записи на сработавшее.
Формат — ../quality-gate/references/evidence-format.md.
Автофикс
В режиме --fix безопасно исправляются: добавление BOM, приведение переводов строк к
единому виду, замена тире на ASCII-дефис вне строковых литералов.
Не исправляются автоматически: управляющие символы (нужно понять, откуда они взялись — возможно, сломан сам генератор) и невалидная кодировка (перекодировка вслепую портит данные сильнее исходной ошибки).
$QG— каталог установленного плагина. Как его разрешить (переменнаяCLAUDE_PLUGIN_ROOTв оболочке пуста) — см. раздел «Путь к инструментам плагина» в навыкеquality-gate.