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.