Files
java-word-pdf/AGENTS.md
T
Pjandro 2d446d783c Шрифты: restrictToBundled() чистит реестр PhysicalFonts от системных перед load()
Конструктор BundledFontMapper каждый раз заново обнаруживает системные
шрифты; на Windows найденный Calibri покрывает U+2000-U+2EFF, и
RunFontSelector оставляет em-dash на Carlito вместо fallback-DejaVu
(красный ruPlain_emDashEmbeddedNotHelvetica). Очистка реестра после
init() и до load() делает вывод одинаковым на любой ОС; шрифты,
встроенные в docx, регистрируются при load() и остаются в реестре.
2026-10-02 19:51:24 +00:00

38 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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()` (бандл-шрифты регистрируются поверх системных), затем `BundledFonts.restrictToBundled()` (чистит реестр `PhysicalFonts` от системных шрифтов до `load()`; конструктор маппера каждый раз заново добавляет их, и `GlyphCheck` на Windows находит системный Calibri — em-dash остаётся на Carlito, красный `ruPlain_emDashEmbeddedNotHelvetica`). Не менять местами.
- 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 не конвертирован хотя бы один файл.