Files
java-word-pdf/AGENTS.md
T

3.7 KiB
Raw Blame History

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 не конвертирован хотя бы один файл.