3.3 KiB
ADR-0004: Ранняя валидация и явные fallback-политики
Дата: 2026-08-26 Статус: Принято
Контекст
Ошибки Typst часто проявляются во время layout далеко от места, где пользователь передал неверное значение. Для бизнес-документа особенно опасны тихие fallback: неверная компания, отсутствующая сторона, незаметно пропавшая подпись или citation, не попавшая в список источников.
При этом распространяемый шаблон должен компилироваться без реальных подписей и печатей. Они поставляются отдельным ZIP; PowerShell task проверяет и извлекает архив, после чего запускает main.typ с явным sys.inputs. Typst 0.15 не предоставляет проверки существования файла без попытки загрузки.
Рассматриваемые варианты
- Полагаться только на diagnostics Typst — мало кода, но сообщения не отражают доменный путь поля.
- Всегда аварийно завершаться при любом отсутствующем ресурсе — строго, но шаблон нельзя удобно распространять без подписей.
- Валидировать domain до layout и явно моделировать необязательные ресурсы — больше контрактов, зато ошибки предсказуемы.
Решение
Выбрали раннюю profile-specific валидацию. Каждая ошибка называет профиль, путь поля, фактическое значение и ожидаемое ограничение.
Для подписи, печати и необязательных изображений поддерживаются политики:
hide— не показывать ресурс и не резервировать место;placeholder— показать безопасную графическую заглушку: круг для печати или крест для подписи;reserve-space— оставить место для ручной подписи или печати.
Политика применяется только если поле равно none. Если поле содержит путь, но файл отсутствует, сборка завершается ошибкой.
Последствия
Становится проще: распространение шаблона, поиск причины ошибки и тестирование негативных сценариев.
Становится сложнее: каждый профиль обязан определить required/optional поля и defaults.
Закрывает дверь на: молчаливое игнорирование неверно указанного пути к производственному ресурсу.