diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..47866a9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +Конвертер docx → PDF на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-cli` (fat-jar через maven-shade). + +## Сборка + +- `mvn clean verify` — все модули + тесты; единственный гейт перед `git push` (lint/typecheck/CI в репозитории нет). +- `mvn -pl wordpdf-cli package` — только fat-jar `wordpdf-cli/target/wordpdf-cli-1.0.0.jar`. +- `dependency-reduced-pom.xml` — артефакт shade, уже в .gitignore, не коммитить. + +## Тесты + +- JUnit 5, без внешних сервисов, headless (surefire уже задаёт `-Djava.awt.headless=true`). +- Один тест: `mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#ruPlain_regularRunsUseRegularFont`. +- Тесты `wordpdf-cli` зависят от test-jar `wordpdf-core` (classifier `tests`): сборка `-pl wordpdf-cli` без `-am` не пройдёт — либо строить из корня, либо `-am`. +- Тестовые `.docx` коммитятся в `wordpdf-core/src/test/resources/samples/`; тесты их не генерируют. + Пересоздать — одноразовой утилитой `SampleDocxGenerator` (команда в javadoc класса); POI — только test scope. +- `BundledFontsTest` проверяет синхронность списка `ENTRIES` с реальными TTF в `resources/fonts/`: новый шрифт = файл + `Entry`, иначе тест красный. + +## Шрифты (важно при изменениях) + +- 28 TTF в `wordpdf-core/src/main/resources/fonts/` — бинарные фикстуры, часть jar; не удалять/переименовывать без обновления маппинга. +- Алиасы MS→open-source: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans. +- `slf4j-simple` обязателен: без него docx4j печатает предупреждение прямо в выходной PDF (регрессионный тест `noLoggingWarningInPdf`). +- Символы U+2000–U+2EFF (em-dash, кавычки, многоточие) рендерятся DejaVu Sans, а не шрифтом ранa — по дизайну; виртуальный «Segoe UI Symbol» мапится на fallback. + +## Архитектура (неочевидное) + +- Пайплайн: байты docx → `DocxOnOffNormalizer` → docx4j → XSL-FO (XSLT) → FOP → PDF. +- Порядок инициализации в `WordPdfConverter.convertToStream` важен: сначала `new BundledFontMapper()`, потом `BundledFonts.init()` (бандл-шрифты регистрируются поверх системных). Не менять местами. +- docx4j 11.x теряет атрибуты `w:val="off"/"on"` при JAXB-разборе — поэтому нужна нормализация байтов до загрузки (регрессионный тест `ruPlain_regularRunsUseRegularFont`). +- Не убирать shade-фильтры `META-INF/*.SF|*.DSA|*.RSA` — подписанные jar-файлы зависимостей ломают fat-jar. + +## Точка входа + +- Библиотека: `WordPdfConverter.convert(Path)` / `convert(Path, Path)` — статический stateless-класс; ошибки — `ConversionException`. +- CLI: `WordPdfCli` (fat-jar, Main-Class в манифесте). Коды возврата: 0 успех, 1 ошибка использования, 2 не конвертирован хотя бы один файл.