Files
java-word-pdf/AGENTS.md
T
Pjandro aec4dbffe7 Валидатор: лимиты 5 МиБ и 100 страниц, отказ до рендера и без артефактов
- WordPdfValidator (новый): MAX_INPUT_BYTES/MAX_PAGES, три нижние оценки
  страниц (кэш app.xml недостоверен — реальный кейс <Pages>1</Pages> при
  110 маркерах lastRenderedPageBreak); lightweight zip/StAX-путь.
- convert(Path,Path): неполный PDF удаляется при отказе, но только если
  поток вывода реально открылся (чужой read-only файл не стирается);
  checkPageCount внутри try — finally чистит temp-файлы шрифтов.
- lightweight: continuous-секции не считаются страницами; w:type —
  дочерний элемент, классификация на закрытии sectPr; мёртвый
  атрибутный перегруз startsNewPage удалён.
- Фикстуры too-many-pages.docx (151 страница) и stale-cache.docx
  (кэш 1 при 110 маркерах) + регрессии tooManyPages,
  staleCachePageCountRejectedBeforeRender, inputTooLarge,
  oversizedInputReturnsError, pageCount_continuousSectionsNotCountedLightweight.
- SampleDocxGenerator: точный поиск <w:t (не матчить <w:tbl/<w:tc),
  константа STALE_CACHE_UNMARKED_RUNS вместо литерала.
- AGENTS.md переписан; .gitignore += /diff/ и /word-export.*.

mvn clean verify: 95/95; fat-jar проверен java -jar (код 0/2, артефактов нет).
2026-10-13 15:29:23 +00:00

18 KiB
Raw Blame History

Repository Guidelines

Project Overview

Конвертер .docx → .pdf на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: wordpdf-core (библиотека), wordpdf-cli (fat-jar через maven-shade). Единственный гейт перед git push — mvn clean verify (CI/lint в репозитории нет).

Architecture & Data Flow

Пайплайн WordPdfConverter.convertToStream — порядок шагов фиксирован, менять местами нельзя:

  1. new BundledFontMapper() → BundledFonts.init() → BundledFonts.restrictToBundled(). Конструктор маппера каждый раз заново добавляет системные шрифты в реестр PhysicalFonts; бандл регистрируется поверх; чистка реестра — до load(). Ключ реестра — имя шрифта, addPhysicalFont(URI) НЕ перезаписывает занятый ключ → BundledFonts.init() вызывает dropNonBundled() (иначе системный DejaVuSerif.ttf блокирует наш DejaVuSerif-Regular.ttf).
  2. Нормализация байтов docx до JAXB-загрузки (цепочка byte[] → byte[], порядок значим): DocxOnOffNormalizer (w:val="off"/"on" → false/true; docx4j 17.x теряет on/off при разборе) → SymbolFontNormalizer (маркеры списков из PUA U+F0xx в Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица SymbolMapper сгенерирована, руками не менять) → FieldNormalizer (сложные поля fldChar PAGE/NUMPAGES/SECTIONPAGES → w:fldSimple, иначе во всех колонтитулах печатается один закэшированный номер; штатный FieldsCombiner docx4j не заходит внутрь w:sdt) → GlyphCoverageNormalizer (шаг 2.4: режет ран по покрытию глифов и пишет семейство в w:rFonts; трогает только раны с одним w:t и явным w:rFonts; покрытие — java.awt.Font.canDisplay через BundledFonts.awtFont, не GlyphCheck — тот логирует на каждый глиф).
  3. WordprocessingMLPackage.load(байты) → WordPdfValidator.checkPageCount(pkg) — до рендера.
  4. pkg.setFontMapper(mapper) → DrawingPreRenderer.run(pkg) (шаг 3.5: c:chart/dgm:relIds docx2fo.xslt не умеет и молча выбрасывает — свой Java2D-движок internal/chart/* рендерит их в PNG 300 dpi и подменяет на pic:pic; после setFontMapper, до FOSettings) → new FOSettings(pkg) + FopFallbackFonts.declare (декларирует в FOP-конфиге все бандл-семейства — FOP встраивает только задекларированные) → FORendererApacheFOP / FOUserAgent (заголовок PDF = имя файла) → Docx4J.toFO(..., FLAG_EXPORT_PREFER_XSL).
  5. finally: deleteEmbeddedFontTempFiles() (в 17.x OpcPackage.close() нет).

Критические инварианты (нарушение = битый вывод)

  • docx4j.convert.out.fo.gsubFeatures=false — ставится в статическом блоке WordPdfConverter. Иначе docx4j навешивает fox:gsub-features без объявления префикса → FO невалиден → WordLayoutFixups молча отказывается от всех фиксов → FOP падает на docx4j-baseline. Без фиксов нет колонок и колонок таблиц.
  • ServicesResourceTransformer в maven-shade (wordpdf-cli) обязателен: META-INF/services/org.apache.fop.fo.ElementMapping дублируется в docx4j-fo-renderer-core и docx4j-export-fo; без слияния FOP падает на UnknownXMLObj cannot be cast to Root. В fat-jar из тестов не видно — проверять java -jar.
  • Не убирать shade-фильтры META-INF/*.SF|*.DSA|*.RSA — подписанные jar ломают fat-jar.
  • slf4j-simple обязателен: без него docx4j пишет «TO HIDE THESE MESSAGES» прямо в выходной PDF (регрессия noLoggingWarningInPdf).
  • JAXB-обход обязан раскрывать JAXBElement (иначе таблицы/раны молча пропускаются — оценка «1» вместо 121). Рекурсия через ContentAccessor из org.docx4j.wml (НЕ org.docx4j.contentcontrol — в 17.x его нет). Тип секции — SectPr$Type.getVal(); маркер — R.LastRenderedPageBreak (CTLastRenderedPageBreak в 17.x отсутствует).
  • FOP — форк org.docx4j:docx4j-fo-renderer* 2.11-docx4j.2 (пакеты org.apache.fop.*), умеет хинты docx4j:baseline/docx4j:line-box. Fop.Renderers.getRenderer() возвращает список — FopFallbackFonts.rendererFonts ищет application/pdf.
  • docx2fo.xslt в репозитория нет — он в jar docx4j-export-fo. WordLayoutFixups (включён по умолчанию в 17.x) постобработкой DOM FO даёт реальные колонки w:cols/@w:num и колонки таблиц; побочный эффект — авто-ширины колонок без tblGrid/tcW стали уже (слово может перенестись в ячейке).
  • Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — глифов нет ни в одном OFL-шрифте бандла, остаются .notdef (GNU FreeSerif GPL — не добавляем намеренно).

Шрифты (30 TTF в wordpdf-core/src/main/resources/fonts/, SIL OFL)

Алиасы MS→open-source (BundledFontMapper): Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans. Новый шрифт = файл + запись в BundledFonts.ENTRIES (синхрон проверяет BundledFontsTest). Noto Naskh Arabic / Noto Sans Armenian (только regular, ради глифов U+07B1–08FF и U+058D/E) в BundledFontMapper не регистрируются — FontFallback.selectCovering перебирает весь реестр PhysicalFonts сам. У них только regular-начертание: BundledFonts.families() это учитывает, BundledFontsTest.allFamiliesHaveAllVariants их не проверяет. Символы U+2000–U+2EFF: RunFontSelector.symbolBlockFont оставляет шрифт ранa, если глиф есть, иначе виртуальный «Segoe UI Symbol» → fallback (как в Word; регрессия ruPlain_emDashEmbeddedNotHelvetica).

Валидация входа (WordPdfValidator)

MAX_INPUT_BYTES = 5 MiB, MAX_PAGES = 100. Страницы = максимум трёх нижних оценок: (1) кэш docProps/app.xml <Pages> — недостоверен (реальный кейс: <Pages>1</Pages> при 110 маркерах); (2) явные разрывы w:br type="page" / pageBreakBefore / межсекционные sectPr (кроме continuous); (3) w:lastRenderedPageBreak + 1. Lightweight-путь (zip/StAX, без docx4j) согласован с JAXB: sectPr в body — «все минус 1»; sectPr в pPr не считается; колонтитулы — по содержимому zip. Расхождение допустимо только в завышение. При отказе convert(Path,Path) удаляет уже открытый PDF (регрессия staleCachePageCountRejectedBeforeRender проверяет отсутствие артефакта).

Chart-движок (internal/chart, package-private кроме DrawingPreRenderer.run)

Свой Java2D-рендер DrawingML. Калибровка surface3D зафиксирована тестами, эталон — стр. 3 gitignored word-export.pdf (экспорт Word, pdftoppm -r 300): CAMERA_DISTANCE = 2.36 (perspective — НЕ угол FOV; fov≈49°), DEPTH_RATIO = 0.705, HEIGHT_RATIO = 0.664, поля 0.1485/0.116/0.146 от области построения, rotY берётся как -Math.toRadians(...) (знак обратный правому правилу), Lambert 0.92 + 0.88·dot кламп [0.80; 1.25], свет (0.83, 0.48, 0.28). Цели: силуэт 314,9×65,3 pt центр (227,3; 82,3), уклон передней кромки 0.1282, аспект 0.207, шаги осей 0.0504/0.1176. Триангуляция ячейки — диагональ с большей суммой значений (седло; фиксированная диагональ даёт невидимую щепку); клиппинг полос — по треугольникам. w01 = z[r+1][c], w10 = z[r][c+1] — перестановка закручивает квад в бабочку. ChartRenderer.axisBounds без явного c:min поднимает нижнюю границу до 0. Пустой c:title + autoTitleDeleted val="0" → автозаголовок Chart Title (для pie/pie3D/doughnut — имя ряда). Границы калибровки менять только вместе с тестами Surface3dPainterTest/PiePainterTest.

В DrawingPreRenderer rels части берутся через part.getRelationshipsPart() (Base), а не getOwningRelationshipPart() — у document.xml последнее указывает на пакетный .rels. Обход pkg.getParts() — только по снимку списка: createImagePart докидывает части в тот же реестр (живой обход → ConcurrentModificationException).

Key Directories

Путь Назначение
wordpdf-core/src/main/java/ru/pjandro/wordpdf/ публичный API: WordPdfConverter, WordPdfValidator, ConversionException
…/wordpdf/fonts/ BundledFonts (реестр/выгрузка TTF), BundledFontMapper (алиасы MS→open-source)
…/wordpdf/internal/ 4 байтовых нормализатора + FopFallbackFonts
…/wordpdf/internal/chart/ Java2D-рендер диаграмм/SmartArt в PNG
wordpdf-core/src/main/resources/fonts/ 30 TTF + лицензии — бинарные фикстуры, часть jar
wordpdf-core/src/test/resources/samples/ 11 закоммиченных .docx-фикстур (единственные фикстуры)
wordpdf-cli/src/main/java/…/cli/ WordPdfCli (fat-jar)
references/ эталон Word 365 (word.docx + word.pdf) — ручное сравнение, не фикстуры, в тесты/jar не подключать
diff/, корневые word-export.* gitignored артефакты ручной калибровки

Development Commands

mvn clean verify                        # все модули + тесты — обязательный гейт перед push
mvn -pl wordpdf-cli package             # fat-jar (из корня); из каталога cli — только с -am
java -jar wordpdf-cli/target/wordpdf-cli-1.0.0.jar in.docx [out.pdf]
mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#pageNumbers_recomputedNotCached   # один тест

CLI: 1 аргумент → PDF рядом с исходником; 2-й .pdf → явный выход; два .docx = пакетная конвертация. Коды возврата: 0 успех, 1 ошибка использования, 2 не сконвертирован хотя бы один файл.

dependency-reduced-pom.xml — артефакт shade, не коммитить.

Пересоздать 10 фикстур (POI, test scope; charts-smartart.docx НЕ генерируется — исключение):

mvn -pl wordpdf-core test-compile -Dmdep.outputFile=/tmp/cp.txt dependency:build-classpath -q
java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \
    ru.pjandro.wordpdf.SampleDocxGenerator wordpdf-core/src/test/resources/samples

Code Conventions & Common Patterns

  • Классы final, приватный конструктор, только static (stateless, DI нет; конфигурация — Docx4jProperties + classpath-ресурсы). Исключения — экземпляры по природе docx4j: BundledFontMapper (наследник BestMatchingMapper), DrawMlColor (палитра темы).
  • Нормализаторы — единая сигнатура public static byte[] normalize(byte[] docx) throws IOException с флагом changed: нечего менять → вернуть тот же массив (assertSame в тестах); package-private хук static String rewrite(String xml) для юнит-тестов.
  • Ошибки публичного API — только ConversionException extends RuntimeException; внутренние IOException/IllegalStateException оборачиваются на границе. В chart — деградация вместо падения: неизвестный пресет → прямоугольник + лог.
  • Javadoc на русском, объясняет «почему» и ссылается на регрессию и фикстуру (формат: Регрессия — WordPdfConverterTest#имя, фикстура samples/….docx) — новый фикс оформлять так же.
  • Константы UPPER_SNAKE с числовыми эталонными значениями (CAMERA_DISTANCE, MAX_PAGES); начертания V_REGULAR/V_BOLD/...; модели — record; размеры в chart — в пунктах, растр × DPI/72.
  • Внутренние API package-private; наружу из internal торчат только normalize/declare/DrawingPreRenderer.run.
  • WordPdfCli.main тонко обёртывает public static int run(String[]) — CLI тестируется без System.exit.

Important Files

  • wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java — точка входа библиотеки + static-блок gsubFeatures.
  • wordpdf-cli/pom.xml — shade: Main-Class, ServicesResourceTransformer, фильтры подписей.
  • Корневой pom.xml — все версии зависимостей (в модулях версии не объявлять): docx4j 17.3.0, slf4j 2.0.17, JUnit 5.12.2, PDFBox 3.0.7 (test), POI 5.5.1 (test, только генератор фикстур); форки FOP/jeuclid приходят транзитивно с docx4j-export-fo, пинить не надо.
  • wordpdf-core/src/main/resources/slf4j-simple.properties — без него предупреждение лезет в PDF.
  • wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java — main()-утилита пересоздания фикстур (команда в javadoc).

Runtime & Tooling Preferences

  • Java 17 + Maven (обязательны; wrapper mvnw нет). UTF-8.
  • Только Maven (никакого Gradle/Ant); новые зависимости — latest stable, версии только в корневой dependencyManagement.
  • CI, линтеров, форматтеров, checkstyle — нет; проверка одна: mvn clean verify.
  • Fat-jar проверять только java -jar (тесты идут по classpath и shade-проблем не видят).

Testing & QA

  • JUnit 5, surefire c -Djava.awt.headless=true; только Assertions (без Mockito/AssertJ), package-private тесты в mirror-пакетах.
  • PDF сравнивается текстом, не растеризацией: PDFBox PDFTextStripper для текста, override processTextPosition для шрифта конкретного символа (fontNameOf), обход ресурсов страницы для встроенных шрифтов (EAAAAA+Carlito-Bold) и счётчика картинок. Негативные маркеры — регрессии: assertFalse(text.contains("#")) (.notdef), assertFalse(font.startsWith("Helvetica")). Пиксели — только в unit-тестах chart-пейнтеров (там сам код — Java2D); допуски 6–10%.
  • Текст нормализуется по пробелам (tableImage_tableAndImage — полное удаление пробелов: docx4j переносит слова в auto-fit таблицах).
  • Фикстуры — закоммиченные samples/*.docx (не генерировать в тестах); classpath → временный файл (extractSample/extractToTemp). In-memory docx — ZipOutputStream из литеральных XML или POI в byte[] (WordPdfValidatorTest).
  • Юниты нормализаторов работают строками (rewrite) и проверяют контракт «нечего менять → null / тот же массив» и неприкосновенность [Content_Types].xml.
  • Тесты wordpdf-cli берут фикстуры из test-jar core (classifier tests) → -pl wordpdf-cli без -am не соберётся; проверять коды возврата WordPdfCli.run.
  • Каждый фикс бага docx4j/FOP сопровождается: байтовый нормализатор/pre-renderer + регрессионный тест с фикстурой + javadoc-ссылка. Проверенные пары: DocxOnOffNormalizerTest/ruPlain_regularRunsUseRegularFont, FieldNormalizerTest/pageNumbers_recomputedNotCached, SymbolFontNormalizerTest/symbolFonts_bulletsAreNotHash, GlyphCoverageNormalizerTest/exoticGlyphs_drawnNotHash, WordPdfValidatorTest/staleCachePageCountRejectedBeforeRender, BundledFontsTest/noLoggingWarningInPdf, Surface3dPainterTest/chartsSmartArt_drawingsBecomeImages.