Building/.template/development/docs/adr/0007-author-workspace.md

ADR-0007: Минимальный корень и три режима одного документа

Дата: 2026-08-31 Статус: Устарело — заменено ADR-0009

Контекст

Этот ADR сохраняется как история промежуточного решения. Три entrypoint-файла были удалены после проверки на реальных отчётах: пользователю удобнее выбирать режим в одном main.typ.

В текущем корне служебные каталоги конкурируют с chapters/ и assets/, а main.typ смешивает демонстрационные данные, настройку и сборку. Автору после форка нужен короткий маршрут без изучения DDD-слоёв, тестов и примеров.

Одновременно должны поддерживаться три выпуска одного содержания и четыре вида документов. Обратная совместимость со старыми путями не требуется.

Рассматриваемые варианты

1. Оставить служебные каталоги в корне — удобно разработчику, но перегружает основной сценарий автора.
2. Удалить тесты и документацию — очищает корень, но делает шаблон хрупким и плохо сопровождаемым.
3. Перенести внутреннее устройство в .template/ — сохраняет разработку и визуально отделяет её от пользовательских файлов.
4. Создать отдельный entrypoint для каждого типа и режима — явно, но приводит минимум к двенадцати корневым файлам и дублированию конфигурации.

Решение

Выбрали один скрытый каталог .template/, общий document.typ и три корневые точки входа:

• main.typ передаёт mode: "final";
• draft.typ передаёт mode: "draft";
• clean-copy.typ передаёт mode: "clean-copy".

Все entrypoints импортируют render(mode:) из document.typ. Report, letter, commercial-offer и contract starters реализуют одинаковый контракт, поэтому выбор типа документа не меняет entrypoints.

В starter явно записываются все семантически важные параметры, включая осознанные none, false и (). Низкоуровневые параметры layout остаются внутри библиотеки.

Последствия

Становится проще: первый fork, переключение режима, выбор starter и обновление внутренней реализации.

Становится сложнее: document.typ является обязательным стабильным контрактом, а каждый starter должен проходить contract-tests.

Закрывает дверь на: compatibility-файлы в корне и отдельные копии полной конфигурации для каждого режима.