- 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, артефактов нет).
18 KiB
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 — порядок шагов фиксирован, менять местами нельзя:
new BundledFontMapper()→BundledFonts.init()→BundledFonts.restrictToBundled(). Конструктор маппера каждый раз заново добавляет системные шрифты в реестрPhysicalFonts; бандл регистрируется поверх; чистка реестра — доload(). Ключ реестра — имя шрифта,addPhysicalFont(URI)НЕ перезаписывает занятый ключ →BundledFonts.init()вызываетdropNonBundled()(иначе системныйDejaVuSerif.ttfблокирует нашDejaVuSerif-Regular.ttf).- Нормализация байтов 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(сложные поляfldCharPAGE/NUMPAGES/SECTIONPAGES →w:fldSimple, иначе во всех колонтитулах печатается один закэшированный номер; штатныйFieldsCombinerdocx4j не заходит внутрьw:sdt) →GlyphCoverageNormalizer(шаг 2.4: режет ран по покрытию глифов и пишет семейство вw:rFonts; трогает только раны с однимw:tи явнымw:rFonts; покрытие —java.awt.Font.canDisplayчерезBundledFonts.awtFont, неGlyphCheck— тот логирует на каждый глиф). WordprocessingMLPackage.load(байты)→WordPdfValidator.checkPageCount(pkg)— до рендера.pkg.setFontMapper(mapper)→DrawingPreRenderer.run(pkg)(шаг 3.5:c:chart/dgm:relIdsdocx2fo.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).finally:deleteEmbeddedFontTempFiles()(в 17.xOpcPackage.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в репозитория нет — он в jardocx4j-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— все версии зависимостей (в модулях версии не объявлять): docx4j17.3.0, slf4j2.0.17, JUnit5.12.2, PDFBox3.0.7(test), POI5.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для текста, overrideprocessTextPositionдля шрифта конкретного символа (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 (classifiertests) →-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.