Initial commit

.template/development/docs/adr/0006-visual-regression.md

@@ -0,0 +1,32 @@
+# ADR-0006: Трёхуровневая стратегия регрессионного тестирования
+
+**Дата**: 2026-08-26
+**Статус**: Принято
+
+## Контекст
+
+Шаблон содержит хрупкую пагинацию, сложные таблицы, подписи, формулы, кириллическую нумерацию и show rules. Успешная компиляция не обнаруживает тихий перенос строки, наложение печати или изменение количества страниц. Чистый pixel-perfect diff, в свою очередь, слишком чувствителен к версии renderer и системным шрифтам.
+
+## Рассматриваемые варианты
+
+1. **Проверять только exit code компилятора** — быстро, но не защищает макет.
+2. **Использовать только pixel-perfect snapshots** — ловит всё, но создаёт шум при допустимых изменениях окружения.
+3. **Совместить unit, semantic и visual проверки** — больше инфраструктуры, зато дефекты классифицируются точнее.
+
+## Решение
+
+Выбрали **три уровня тестов**:
+
+1. Domain unit tests через `typst eval` и `assert`.
+2. Compile/semantic tests: exit code, diagnostics, A4, количество страниц, наличие обязательных текстовых маркеров и PDF metadata.
+3. Visual regression: rasterize через Poppler, сравнивать контрольные области и полный perceptual diff с документированным порогом.
+
+Snapshots создаются только из синтетического `test-company`; реальные подписи и печати не включаются в публичные тестовые изображения. Новая версия Typst всегда проверяется отдельным прогоном до обновления snapshots.
+
+## Последствия
+
+**Становится проще**: находить как логические, так и визуальные регрессии и безопасно менять отдельные profiles.
+
+**Становится сложнее**: требуется Python/Poppler test runtime и процедура осознанного обновления эталонов.
+
+**Закрывает дверь на**: автоматическое принятие новых snapshots при обычном тестовом запуске.