Report-showcase/.template/development/docs/adr/0009-single-main-and-public-docs.md

ADR-0009: Один main.typ, видимая документация и явная приватная сборка

Дата: 2026-08-31
Статус: Принято

Часть решения об отдельной private build task заменена условным import из ADR-0010. Один main.typ и видимая публичная документация остаются действующими.

Контекст

Проверка шаблона на реальных отчётах показала, что авторы ожидают менять компанию, стадию, режим и список глав в одном файле. Три корневых entrypoint-файла и скрытая пользовательская справка создавали лишний выбор. Одновременно Typst 0.15 не умеет безопасно проверять существование private path.

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

1. Сохранить document.typ и три entrypoints — технически чисто, но пользователь должен понимать разделение ролей четырёх файлов.
2. Один main.typ и tracked private placeholders с заменой — просто, но реальная подпись становится изменением уже отслеживаемого файла.
3. Один main.typ, public docs/, internal placeholders и private task — минимальная поверхность без риска добавить реальный media в Git.

Решение

Выбран третий вариант:

• main.typ содержит company-id, document-mode, metadata и #include;
• docs/ видим и содержит executable examples;
• examples одновременно являются источниками задачи выбора типа;
• обычная сборка использует internal placeholders;
• задача приватной сборки проверяет private-assets.zip, копирует PNG в .private/ и передаёт --input private-assets=true;
• прежний ADR-0007 считается устаревшим.

Последствия

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

Становится сложнее: main-файлы четырёх примеров частично повторяют setup-код; PowerShell tool становится security boundary для ZIP.

Закрывает дверь на: отдельные root entrypoints для режимов, скрытую public-документацию и замену tracked placeholders реальными файлами.