file-hygiene git:20260901.7cebacaA

Immutable. This exact content is served forever at /api/v1/blob/5eb6740d50a6f84a.

---
name: file-hygiene
description: >-
  Контур гигиены файлов 1С: кодировка, BOM, недопустимые управляющие символы, тире вместо
  ASCII-дефиса, согласованность переводов строк. Дешёвая байтовая проверка, выполняется при
  любом изменении файлов 1С. Вызывается оркестратором quality-gate; напрямую — по запросу
  «проверь кодировки», «почему платформа не принимает файл», «проверь BOM».
license: MIT
---

# file-hygiene — контур гигиены файлов

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

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

## Запуск

```bash
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`.