From fe5c7c48b0e0cec4c937ce4d8269434b06093601 Mon Sep 17 00:00:00 2001 From: Pjandro Date: Tue, 29 Sep 2026 21:29:09 +0000 Subject: [PATCH] =?UTF-8?q?AGENTS.md:=20=D0=B8=D0=BD=D1=81=D1=82=D1=80?= =?UTF-8?q?=D1=83=D0=BA=D1=86=D0=B8=D0=B8=20=D0=B4=D0=BB=D1=8F=20OpenCode?= =?UTF-8?q?=20(=D1=81=D0=B1=D0=BE=D1=80=D0=BA=D0=B0,=20=D1=82=D0=B5=D1=81?= =?UTF-8?q?=D1=82=D1=8B,=20=D1=88=D1=80=D0=B8=D1=84=D1=82=D1=8B,=20=D0=BD?= =?UTF-8?q?=D0=B5=D0=BE=D1=87=D0=B5=D0=B2=D0=B8=D0=B4=D0=BD=D1=8B=D0=B5=20?= =?UTF-8?q?=D0=B4=D0=B5=D1=82=D0=B0=D0=BB=D0=B8)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 AGENTS.md 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 не конвертирован хотя бы один файл.