Валидатор: лимиты 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, артефактов нет).
This commit is contained in:
Pjandro
2026-10-13 15:29:23 +00:00
parent ae31f27a27
commit aec4dbffe7
18 changed files with 1264 additions and 76 deletions
+3
View File
@@ -15,3 +15,6 @@ dependency-reduced-pom.xml
Thumbs.db Thumbs.db
# Локальные примеры и выгрузки в корне # Локальные примеры и выгрузки в корне
# Артефакты ручной калибровки диаграмм
/diff/
+104 -57
View File
@@ -1,70 +1,117 @@
# AGENTS.md # Repository Guidelines
Конвертер docx → PDF на чистом Java (docx4j + Apache FOP, без LibreOffice/Aspose). Java 17, только Maven. Модули: `wordpdf-core` (библиотека), `wordpdf-cli` (fat-jar через maven-shade). ## 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 в репозитории нет).
- `mvn clean verify` — все модули + тесты; единственный гейт перед `git push` (lint/typecheck/CI в репозитории нет). ## Architecture & Data Flow
- `mvn -pl wordpdf-cli package` — только fat-jar `wordpdf-cli/target/wordpdf-cli-1.0.0.jar`.
- `dependency-reduced-pom.xml` — артефакт shade, уже в .gitignore, не коммитить.
## Тесты Пайплайн `WordPdfConverter.convertToStream` — порядок шагов фиксирован, менять местами нельзя:
- JUnit 5, без внешних сервисов, headless (surefire уже задаёт `-Djava.awt.headless=true`). 1. `new BundledFontMapper()` → `BundledFonts.init()` → `BundledFonts.restrictToBundled()`. Конструктор маппера каждый раз заново добавляет системные шрифты в реестр `PhysicalFonts`; бандл регистрируется поверх; чистка реестра — **до** `load()`. Ключ реестра — имя шрифта, `addPhysicalFont(URI)` НЕ перезаписывает занятый ключ → `BundledFonts.init()` вызывает `dropNonBundled()` (иначе системный `DejaVuSerif.ttf` блокирует наш `DejaVuSerif-Regular.ttf`).
- Один тест: `mvn -pl wordpdf-core test -Dtest=WordPdfConverterTest#ruPlain_regularRunsUseRegularFont`. 2. Нормализация байтов docx до JAXB-загрузки (цепочка `byte[] → byte[]`, порядок значим):
- Тесты `wordpdf-cli` зависят от test-jar `wordpdf-core` (classifier `tests`): сборка `-pl wordpdf-cli` без `-am` не пройдёт — либо строить из корня, либо `-am`. `DocxOnOffNormalizer` (`w:val="off"/"on"` → `false`/`true`; docx4j 17.x теряет on/off при разборе)
- Тестовые `.docx` коммитятся в `wordpdf-core/src/test/resources/samples/`; тесты их не генерируют. → `SymbolFontNormalizer` (маркеры списков из PUA U+F0xx в Symbol/Wingdings/Webdings → Unicode + DejaVu Sans; таблица `SymbolMapper` сгенерирована, руками не менять)
Пересоздать — одноразовой утилитой `SampleDocxGenerator` (команда в javadoc класса); POI — только test scope. → `FieldNormalizer` (сложные поля `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple`, иначе во всех колонтитулах печатается один закэшированный номер; штатный `FieldsCombiner` docx4j не заходит внутрь `w:sdt`)
- `BundledFontsTest` проверяет синхронность списка `ENTRIES` с реальными TTF в `resources/fonts/`: новый шрифт = файл + `Entry`, иначе тест красный. → `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()` нет).
## Эталон в references/ ### Критические инварианты (нарушение = битый вывод)
- 11-страничный документ (текст, таблицы, колонтитулы, 3 диаграммы + SmartArt, формулы) со своим эталонным PDF, экспортированным из Word 365: - **`docx4j.convert.out.fo.gsubFeatures=false`** — ставится в статическом блоке `WordPdfConverter`. Иначе docx4j навешивает `fox:gsub-features` без объявления префикса → FO невалиден → `WordLayoutFixups` молча отказывается от всех фиксов → FOP падает на `docx4j-baseline`. Без фиксов нет колонок и колонок таблиц.
`word.docx` + `word.pdf` — Transitional OOXML (`schemas.openxmlformats.org/.../2006/...`). - **`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`.
- `references/` — материалы для ручного сравнения с Word, не тестовые фикстуры: в тесты и в jar их не подключать (фикстуры — `wordpdf-core/src/test/resources/samples/`). - **Не убирать 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)
- 30 TTF в `wordpdf-core/src/main/resources/fonts/` — бинарные фикстуры, часть jar; не удалять/переименовывать без обновления маппинга. Алиасы 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`).
- Алиасы MS→open-source: Calibri→Carlito, Cambria→Caladea, Arial→Arimo, Times New Roman→Tinos, Courier New→Cousine; fallback — DejaVu Sans.
- Noto Naskh Arabic и Noto Sans Armenian (OFL, 278 КБ) добавлены ради глифов, которых нет больше ни в одном шрифте бандла (арабские дополнения U+07B1–U+08FF, армянские U+058D/U+058E). Регистрировать их в `BundledFontMapper` не требуется: `FontFallback.selectCovering` перебирает **весь** реестр `PhysicalFonts` и находит их сам — достаточно `BundledFonts.ENTRIES`. У них только regular-начертание (`BundledFonts.families()` это учитывает, `allFamiliesHaveAllVariants` их не проверяет).
- `FopFallbackFonts.declare` декларирует в FOP-конфиге **все** бандл-семейства, а не один fallback: FOP умеет встраивать только задекларированные, а `font-family` в FO может запросить любой из них.
- `slf4j-simple` обязателен: без него docx4j печатает предупреждение прямо в выходной PDF (регрессионный тест `noLoggingWarningInPdf`).
- Символы U+2000–U+2EFF (em-dash, кавычки, многоточие): `RunFontSelector.symbolBlockFont` оставляет шрифт ранa, если в нём есть этот глиф, и только иначе подставляет виртуальный «Segoe UI Symbol» (маппится на fallback DejaVu Sans, см. `BundledFontMapper`). Так же делает Word: в `references/word.pdf` em-dash нарисован Calibri/Times, DejaVu там нет вообще. Регрессия — `ruPlain_emDashEmbeddedNotHelvetica` (проверяет, что глиф рисует **вшитый** шрифт, а не базовый Helvetica).
## Архитектура (неочевидное) ### Валидация входа (`WordPdfValidator`)
- Пайплайн: байты docx → `DocxOnOffNormalizer` → `SymbolFontNormalizer` → `FieldNormalizer` → `GlyphCoverageNormalizer` → docx4j → XSL-FO (XSLT) → FOP → PDF. `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` проверяет отсутствие артефакта).
- Поля страниц: Word пишет `PAGE`/`NUMPAGES` сложным полем (`fldChar begin` → `instrText` → `separate` → кэш → `end`). Экспорт docx4j в FO `w:instrText` внутри такого поля игнорирует и печатает кэш docx — во всех колонтитулах одно число (в эталоне «2» вместо 1, 2, 3 …). `FieldNormalizer` разворачивает поле в `w:fldSimple` (его обрабатывает `FldSimpleWriter` из docx4j-export-fo: PAGE → `fo:page-number`, есть также NUMPAGES/SECTIONPAGES/PAGEREF), сохраняя внутри закэшированные ран — они дают шрифт/размер. Штатный `FieldsCombiner` docx4j делает то же, но не заходит внутрь `w:sdt`, а Word держит нумерацию именно в контентном контроле («Page Numbers (Top of Page)»). Трогаются только инструкции, для которых есть обработчик; вложенные поля пропускаются. Регрессия — `WordPdfConverterTest#pageNumbers_recomputedNotCached`, фикстура `samples/page-numbers.docx`.
- Покрытие глифов: знак без глифа в шрифте ранa FOP рисует `.notdef` («#»). Docx4j 17.x сам ищет покрывающий шрифт (`FontFallback.selectCovering` по реестру `PhysicalFonts`), но с двумя дырами: `needsCoverage` возвращает false для «латинской» группы (поэтому U+2150–U+218F — римские цифры и дроби — остаются на Tinos навсегда), а `RunFontSelector.fallbackByScript` кэширует фолбэк **на всю группу Юникода** (обычные армянские «ՊՌՋտ» покрываются DejaVu Serif, и найденный DejaVu Serif подставляется следующим за ними U+058D/U+058E). `GlyphCoverageNormalizer` (шаг 2.4, тоже байты до JAXB) режет ран по покрытию и пишет семейство в `w:rFonts` (имя — `BundledFontMapper.documentFontName`, обратное к `bundledFamily`). Покрытие меряется `java.awt.Font.canDisplay` через `BundledFonts.awtFont` (не `GlyphCheck` — тот логирует INFO на каждый отсутствующий глиф). Трогаются только раны с одним `w:t` и с явным `w:rFonts`; если знака нет ни в одном бандл-шрифте, ран не меняется. Регрессия — `WordPdfConverterTest#exoticGlyphs_drawnNotHash`, unit — `GlyphCoverageNormalizerTest`, фикстура `samples/exotic-glyphs.docx`.
- Известный остаток эталона: U+2188 (ↈ) и U+218A (↊) — есть только в GNU FreeSerif (GPL-3+ с Font Exception), которого в бандле нет намеренно (весь бандл — SIL OFL). В `references/word.pdf` на их месте у нас две решётки; ради них OFL не меняют.
- Символьные шрифты: Word хранит маркеры списков и спецсимволы кодами из PUA (U+F0xx), глиф выбирается по имени шрифта (`Symbol`, `Wingdings`, `Webdings`). Экспорт docx4j в FO этих шрифтов не знает: код уходит в fallback, глифа нет, FOP рисует `.notdef` — в PDF решётка «#». `SymbolFontNormalizer` (шаг 1.6, тоже правит байты до JAXB) меняет код на Unicode, а имя шрифта — на `DejaVu Sans`. Таблица кодов — `SymbolMapper` из docx4j 17.x, отфильтрована по наличию глифа в DejaVu; константы сгенерированы, менять руками нельзя. Обрабатываются `w:lvl` (numbering.xml), `w:r` и `w:sym`; ран с `w:sym` разрезается, т.к. у символа собственный `w:font`. Регрессия — `WordPdfConverterTest#symbolFonts_bulletsAreNotHash`, фикстура `samples/symbol-bullets.docx`.
- Порядок инициализации в `WordPdfConverter.convertToStream` важен: сначала `new BundledFontMapper()`, потом `BundledFonts.init()`, затем `BundledFonts.restrictToBundled()` (чистит реестр `PhysicalFonts` от системных шрифтов до `load()`; конструктор маппера каждый раз заново добавляет их). Не менять местами.
- docx4j 17.x по-прежнему теряет атрибуты `w:val="off"/"on"` при JAXB-разборе — нормализация байтов до загрузки (`DocxOnOffNormalizer`) нужна и на 17.x (проверялось отключением: красный `ruPlain_regularRunsUseRegularFont`).
- Ключ реестра `PhysicalFonts` — имя шрифта, и `addPhysicalFont(URI)` **не перезаписывает** занятый ключ. Системный `DejaVuSerif.ttf` занимает «dejavu serif», и наш `DejaVuSerif-Regular.ttf` (то же имя) не добавился бы — `BundledFonts.init()` перед регистрацией вызывает `dropNonBundled()`.
- **`docx4j.convert.out.fo.gsubFeatures=false`** ставится в статическом блоке `WordPdfConverter` — критично. Иначе docx4j навешивает на `fo:inline` атрибут `fox:gsub-features`, не объявляя префикс `fox`; FO становится некорректным XML, `WordLayoutFixups` не может его разобрать, молча отказывается от всех фикс и оставляет хинты `docx4j-baseline`, которые FOP отвергает (`Invalid property encountered on "fo:block": docx4j-baseline`). Без фиксов нет ни колонок, ни колонок таблиц.
- `WordLayoutFixups` (включён по умолчанию в 17.x) — постобработка DOM XSL-FO: `columnBreaks` (реально работают `w:cols/@w:num`, 2 колонки на стр. 9–11 эталона), `disregardBaselineShifts`, `lineBoxAttributes`, `stripHints` и др. Побочный эффект: авто-ширины колонок таблиц без `tblGrid`/`tcW` стали уже (слово может перенестись внутри ячейки) — в `tableImage_tableAndImage` сравнение нормализовано по пробелам.
- Формулы OMML (`m:oMath`) рисует `jeuclid-fop`, который в 17.x пришёл вместе с `docx4j-export-fo` — отдельного кода не требуется (в 11.5.3 формула молча исчезала).
- **`ServicesResourceTransformer` в maven-shade (`wordpdf-cli`) обязателен**: `META-INF/services/org.apache.fop.fo.ElementMapping` лежит и в `docx4j-fo-renderer-core`, и в `docx4j-export-fo`; без слияния второй перезаписывает первый, FOP не узнаёт namespace `fo:` и падает на `UnknownXMLObj cannot be cast to Root`. В fat-jar это не видно из тестов — тесты идут по classpath, проверять `java -jar`.
- FOP в 17.x — форк `org.docx4j:docx4j-fo-renderer*` (пакеты `org.apache.fop.*`), он знает хинты `docx4j:baseline`/`docx4j:line-box` через `WordLayoutElementMapping`. `Fop.Renderers.getRenderer()` теперь возвращает **список** `w:renderer` (по mime) — `FopFallbackFonts.rendererFonts` ищет `application/pdf`.
- Диаграммы: `docx2fo.xslt` умеет только `a:graphicData/pic:pic`, для `c:chart` и `dgm:relIds` там `notImplemented` (объект молча исчезает). Поэтому `DrawingPreRenderer.run(pkg)` (шаг 3.5 в `convertToStream`, после `setFontMapper` и до `FOSettings`) рендерит их своим Java2D-движком в PNG 300 dpi (`internal/chart/*`) и подменяет на `pic:pic`. Тест `chartsSmartArt_drawingsBecomeImages`, фикстура `samples/charts-smartart.docx`.
- В `DrawingPreRenderer` нужны собственные rels части — `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()`: у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр.
- SmartArt рисуется из `word/diagrams/drawing1.xml` (кэш разложенной Word-ом схемы: абсолютные позиции + `prstGeom`); текст-заполнители (`[Текст]`) лежат в `data1.xml` на `dgm:pt type="node"`, а формы ссылаются на `dgm:pt type="pres"` — связь через `dgm:cxn type="presOf"`.
- `surface3D` (`Surface3dPainter`): перспективная проекция (`c:view3D/perspective`, по умолчанию 30°, и `depth`), грани — ровно ячейки сетки по 2 треугольника без передискретизации, цвет из `c:bandFmts` затемняется по нормали грани (Lambert). Грани рисуются в модельно-экранных координатах уже умноженными на `scale/off` — забыть масштаб значит нарисовать поверхность в субпиксельный ноль.
- Знак `rotY` в DrawingML обратный правому правилу вокруг вертикали: в `Surface3dPainter.paint` он берётся как `-Math.toRadians(spec.rotY)`. Иначе передняя кромка категорий идёт вверх вправо, а ось рядов — вниз вправо (зеркально Word).
- `c:view3D/perspective` — НЕ угол обзора камеры. Расстояние камеры в `Surface3dPainter` = `CAMERA_DISTANCE * (30/perspective)`, где `CAMERA_DISTANCE = 2.36` (эффективный `fov ≈ 49°`, подобран фитом по эталону Word). При наивном `fov = perspective` перспектива слишком слабая: ось рядов уходит вправо вместо почти вертикального ухода в глубину, лента выглядит плоской, а левый край схлопывается в точку.
- Пропорции «коробки» surface3D (`DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`): глубина = 0.705 ширины (от неё `c:view3D/depth`), высота значений = `0.664 * availH/availW`, вписывание в область построения — равномерным масштабом. Раздельный масштаб x/y (или куб 1×1×1) даёт вертикальную гору вместо плоской ленты.
- Поля вокруг коробки — доли области построения `GUTTER_LEFT = GUTTER_RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`; `offX`/`offY` обязаны включать левое и верхнее поле (без `topGutter` поверхность сидела на 22 pt выше эталона). Коробка занимает ~70% ширины: при полях «на глаз» поверхность растягивалась на 82% и лезла на подписи оси значений.
- Калибровка камеры, коробки и полей зафиксирована тестами `Surface3dPainterTest.cameraMatchesWordReference` и `surfaceSilhouetteMatchesWordPlacement`. Эталон — стр. 3 `word-export.pdf` (экспорт Word), растеризованная `pdftoppm -r 300`; цели замеряются по **связному блоку граней** (серые грани в силуэт входят, по одной лишь насыщенности силуэт недомерен на 7%), пунктиру переднего ребра пола и подписям осей: уклон передней кромки 0,1282, аспект силуэта 0,207, шаг оси значений 0,0504, вертикальный шаг оси рядов 0,1176 (все — относительно ширины силуэта); сам силуэт 314,9×65,3 pt с центром в (227,3; 82,3). Замеры по скриншотам давали вдвое завышенную ось рядов и раздували глубину.
- Нормаль грани считается в той же метрике, что и проекция: `v` умножается на `depthScale`, `w` уже умножен на `hScale`. Без масштаба в нормали поверхность кажется положе и все грани уходят в светлую часть Lambert.
- Затенение граней surface3D — Lambert `0.92 + 0,88·dot` с клампом `[0,80; 1,25]` и боковым светом `LIGHT = (0,83, 0,48, 0,28)`. Дискретные множители эталона (гистограмма цветов граней, 300 dpi) — 0,40 / 0,75 / 0,85 / 1,04 / 1,06 / 1,10; группа 0,40 — узкая полоска underside под передним краем, и разгон Lambert до неё (отрицательные dot) по всем граням ухудшает совпадение с эталоном (17,2 → 17,6 средних расхождений на пиксель), поэтому нижний кламп 0,80. Направление света перебрано по 120 направлениям — текущее лучшее. Тест `shadingMatchesWordRange`.
- Триангуляция ячейки — диагональ с **большей суммой значений** (`z[r][c] + z[r+1][c+1] >= z[r+1][c] + z[r][c+1]` → `w00–w11`, иначе `w01–w10`), то есть верхняя огибающая седла. Фиксированная диагональ невозможна: у седловой ячейки одна вершина попадает внутрь треугольника остальных трёх, и при «не той» диагонали второй треугольник становится невидимой щепкой, а видимая грань окрашивается не той полосой. Проверено по эталону (стр. 3 `word-export.pdf`, 300 dpi, сравнение полос по пикселям; ячейка Ряд 1→2 / Категория 2→3): верхняя огибающая 92,3 % совпадений полос, фиксированная `w00–w11` — 81,6 %, фиксированная `w01–w10` — 57,9 %, окраска целого квада без разрезки — 74,1 %, билинейная tessellation 3×3/6×6 — 67,8 %/66,0 %. Регрессия — `Surface3dPainterTest.saddleCellUsesHigherDiagonal` (нижняя кромка силуэта в окне 0,42…0,55 его ширины обязана быть полосы 3–4). Клиппинг полос — по треугольникам, не по кваду.
- Пустой `c:title` при `c:autoTitleDeleted val="0"` даёт автозаголовок `Chart Title` (`ChartSpec.AUTO_TITLE`); для круговых (`pie`/`pie3D`/`doughnut`) вместо него — имя ряда. Тесты `ChartSpecTest`.
- В кваде ячейки `w01` обязан быть `z[r+1][c]`, а `w10` — `z[r][c+1]` (u=категория, v=ряд). Перестановка закручивает квад в «бабочку»: дыры и самопересечения граней.
- `ChartRenderer.axisBounds` для линейной оси значений без явного `c:min` всегда поднимает нижнюю границу до 0 (как Word); от этого зависит и легенда полос surface3D (`0-1 … 4-5`, а не `1-2 … 4-5`). Юнит-тесты — `Surface3dPainterTest`.
- Не убирать shade-фильтры `META-INF/*.SF|*.DSA|*.RSA` — подписанные jar-файлы зависимостей ломают fat-jar.
## Точка входа ### Chart-движок (`internal/chart`, package-private кроме `DrawingPreRenderer.run`)
- Библиотека: `WordPdfConverter.convert(Path)` / `convert(Path, Path)` — статический stateless-класс; ошибки — `ConversionException`. Свой 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`.
- CLI: `WordPdfCli` (fat-jar, Main-Class в манифесте). Коды возврата: 0 успех, 1 ошибка использования, 2 не конвертирован хотя бы один файл.
В `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
```bash
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` НЕ генерируется — исключение):
```bash
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`.
@@ -1,6 +1,7 @@
package ru.pjandro.wordpdf.cli; package ru.pjandro.wordpdf.cli;
import org.junit.jupiter.api.Test; import org.junit.jupiter.api.Test;
import ru.pjandro.wordpdf.WordPdfValidator;
import java.io.InputStream; import java.io.InputStream;
import java.nio.charset.StandardCharsets; import java.nio.charset.StandardCharsets;
@@ -29,6 +30,28 @@ class WordPdfCliTest {
assertEquals(2, WordPdfCli.run(new String[]{"/tmp/no-such-file-xyz.docx"})); assertEquals(2, WordPdfCli.run(new String[]{"/tmp/no-such-file-xyz.docx"}));
} }
/**
* Превышение 5 MiB на входе: CLI должен вернуть код 2 (ошибка конвертации)
* — валидатор бросает {@code ConversionException}, CLI ловит и печатает
* в stderr.
*/
@Test
void oversizedInputReturnsError() throws Exception {
Path tooBig = Files.createTempFile("cli-too-big-", ".docx");
try {
Files.write(tooBig,
new byte[(int) WordPdfValidator.MAX_INPUT_BYTES + 1]);
assertEquals(2, WordPdfCli.run(new String[]{tooBig.toString()}),
"превышение лимита должно давать код 2");
} finally {
// при регрессии guard'а CLI написал бы PDF рядом со входом —
// убирать и его, чтобы тест не оставлял артефактов
Files.deleteIfExists(tooBig);
Files.deleteIfExists(Path.of(
tooBig.toString().replaceFirst("\\.docx$", "") + ".pdf"));
}
}
@Test @Test
void convertsSampleWithExplicitOutput() throws Exception { void convertsSampleWithExplicitOutput() throws Exception {
// Сэмпл из test-jar wordpdf-core // Сэмпл из test-jar wordpdf-core
@@ -18,10 +18,10 @@ import ru.pjandro.wordpdf.internal.FopFallbackFonts;
import ru.pjandro.wordpdf.internal.SymbolFontNormalizer; import ru.pjandro.wordpdf.internal.SymbolFontNormalizer;
import java.io.ByteArrayInputStream; import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.OutputStream; import java.io.OutputStream;
import java.nio.file.Files; import java.nio.file.Files;
import java.nio.file.Path; import java.nio.file.Path;
import java.util.Locale;
/** /**
* Конвертер docx -> PDF на базе docx4j + Apache FOP * Конвертер docx -> PDF на базе docx4j + Apache FOP
@@ -56,10 +56,12 @@ public final class WordPdfConverter {
* *
* @param docxIn входной .docx * @param docxIn входной .docx
* @return путь к созданному PDF * @return путь к созданному PDF
* @throws ConversionException при ошибке (не .docx, файл не найден и т.п.) * @throws ConversionException при ошибке (не .docx, файл не найден,
* размер больше {@link WordPdfValidator#MAX_INPUT_BYTES},
* результат длиннее {@link WordPdfValidator#MAX_PAGES} страниц и т.п.)
*/ */
public static Path convert(Path docxIn) throws ConversionException { public static Path convert(Path docxIn) throws ConversionException {
validateInput(docxIn); WordPdfValidator.checkInput(docxIn);
String name = docxIn.getFileName().toString(); String name = docxIn.getFileName().toString();
int dot = name.lastIndexOf('.'); int dot = name.lastIndexOf('.');
String base = dot > 0 ? name.substring(0, dot) : name; String base = dot > 0 ? name.substring(0, dot) : name;
@@ -72,17 +74,38 @@ public final class WordPdfConverter {
* Конвертирует {@code docxIn} в {@code pdfOut}. * Конвертирует {@code docxIn} в {@code pdfOut}.
* Родительские каталоги {@code pdfOut} при необходимости создаются. * Родительские каталоги {@code pdfOut} при необходимости создаются.
* *
* <p>Число страниц проверяется по самому .docx (см.
* {@link WordPdfValidator#checkPageCount}) до рендеринга — при
* превышении лимита PDF не создаётся.
*
* @throws ConversionException при ошибке * @throws ConversionException при ошибке
*/ */
public static void convert(Path docxIn, Path pdfOut) throws ConversionException { public static void convert(Path docxIn, Path pdfOut) throws ConversionException {
validateInput(docxIn); WordPdfValidator.checkInput(docxIn);
try { try {
Path parent = pdfOut.toAbsolutePath().getParent(); Path parent = pdfOut.toAbsolutePath().getParent();
if (parent != null) { if (parent != null) {
Files.createDirectories(parent); Files.createDirectories(parent);
} }
boolean opened = false;
try (OutputStream os = Files.newOutputStream(pdfOut)) { try (OutputStream os = Files.newOutputStream(pdfOut)) {
opened = true;
convertToStream(docxIn, os); convertToStream(docxIn, os);
} catch (Exception e) {
// валидация числа страниц срабатывает уже внутри
// convertToStream — пустой/неполный PDF убирать, чтобы
// отказ не оставлял артефакт рядом со входом. Удаляем
// только если поток реально открылся: при неудачном
// открытии (read-only/locked цель) ничего не писали и
// чужой файл трогать нельзя
if (opened) {
try {
Files.deleteIfExists(pdfOut);
} catch (IOException ignored) {
// вторичная ошибка не должна затенять основную
}
}
throw e;
} }
} catch (ConversionException e) { } catch (ConversionException e) {
throw e; throw e;
@@ -123,6 +146,12 @@ public final class WordPdfConverter {
WordprocessingMLPackage pkg = WordprocessingMLPackage.load( WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new ByteArrayInputStream(docxBytes)); new ByteArrayInputStream(docxBytes));
try { try {
// 2.5 Проверка числа страниц по самому .docx: кэш Word
// (docProps/app.xml <Pages>) или нижняя оценка по явным
// разрывам. Делается до рендера, чтобы не тратить время на
// заведомо длинный документ; внутри try — чтобы и на отказе
// отработал finally с чисткой temp-файлов встроенных шрифтов.
WordPdfValidator.checkPageCount(pkg);
// 3. Привязка маппера: docx4j сопоставляет шрифты документа // 3. Привязка маппера: docx4j сопоставляет шрифты документа
// с физическими TTF (учитывая и шрифты, встроенные в docx) // с физическими TTF (учитывая и шрифты, встроенные в docx)
pkg.setFontMapper(mapper); pkg.setFontMapper(mapper);
@@ -158,21 +187,6 @@ public final class WordPdfConverter {
} }
} }
/** Проверяет входной файл: существует, это .docx (не .doc). */
private static void validateInput(Path docxIn) throws ConversionException {
if (docxIn == null) {
throw new ConversionException("Не указан входной файл");
}
if (!Files.isRegularFile(docxIn)) {
throw new ConversionException("Файл не найден: " + docxIn);
}
String name = docxIn.getFileName().toString().toLowerCase(Locale.ROOT);
if (!name.endsWith(".docx")) {
throw new ConversionException(
"Поддерживается только .docx (без .doc): " + docxIn);
}
}
/** Имя файла без расширения (для PDF-заголовка). */ /** Имя файла без расширения (для PDF-заголовка). */
private static String baseName(Path p) { private static String baseName(Path p) {
String name = p.getFileName().toString(); String name = p.getFileName().toString();
@@ -0,0 +1,573 @@
package ru.pjandro.wordpdf;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.docx4j.wml.Br;
import org.docx4j.wml.ContentAccessor;
import org.docx4j.wml.P;
import org.docx4j.wml.R;
import org.docx4j.wml.SectPr;
import org.docx4j.wml.STBrType;
import jakarta.xml.bind.JAXBElement;
import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Deque;
import java.util.List;
import java.util.Locale;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
import java.util.zip.ZipInputStream;
/**
* Валидатор ограничений на входной .docx:
* размер файла и число страниц.
*
* <p>Конвертер {@link WordPdfConverter} вызывает валидатор автоматически,
* но им можно пользоваться и напрямую — например, проверить байты
* документа, полученного из сети или БД, до того, как сохранять во временный
* файл и вызывать {@code convert}.
*
* <p>Лимиты:
* <ul>
* <li>{@link #MAX_INPUT_BYTES} — максимальный размер входного .docx (5 MiB);</li>
* <li>{@link #MAX_PAGES} — максимально допустимое число страниц (100).</li>
* </ul>
*
* <p>Число страниц берётся из самого .docx как максимум трёх нижних
* оценок: кэша Word в {@code docProps/app.xml} ({@code <Pages>}),
* явных разрывов страниц ({@code w:br type="page"},
* {@code w:pageBreakBefore}, межсекционные {@code w:sectPr}) и маркеров
* {@code w:lastRenderedPageBreak} — границ страниц, которые Word записал
* при последнем рендере. Кэш сам по себе недостоверен: Word может
* сохранить {@code <Pages>1</Pages>} в документе на 110 страниц
* (регрессия — фикстура {@code samples/stale-cache.docx}).
*
* <p>Проверка делается <b>до</b> рендера — это позволяет отсекать слишком
* длинные документы, не тратя время на конвертацию.
*
* <p>Все ошибки — {@link ConversionException}.
*/
public final class WordPdfValidator {
/** 5 MiB = 5 × 1024 × 1024. */
public static final long MAX_INPUT_BYTES = 5L * 1024 * 1024;
/** Документ длиннее — ошибка. */
public static final int MAX_PAGES = 100;
private WordPdfValidator() {
}
/**
* Проверяет входной файл: существует, это .docx, размер не превышает
* {@link #MAX_INPUT_BYTES}.
*
* @throws ConversionException при любом нарушении
*/
public static void checkInput(Path docxIn) throws ConversionException {
if (docxIn == null) {
throw new ConversionException("Не указан входной файл");
}
if (!Files.isRegularFile(docxIn)) {
throw new ConversionException("Файл не найден: " + docxIn);
}
String name = docxIn.getFileName().toString().toLowerCase(Locale.ROOT);
if (!name.endsWith(".docx")) {
throw new ConversionException(
"Поддерживается только .docx (без .doc): " + docxIn);
}
long size;
try {
size = Files.size(docxIn);
} catch (IOException e) {
throw new ConversionException("Не удалось прочитать размер файла: " + docxIn, e);
}
if (size > MAX_INPUT_BYTES) {
throw new ConversionException("Файл больше 5 МБ: " + size
+ " байт > " + MAX_INPUT_BYTES + " байт (" + docxIn + ")");
}
}
/**
* Проверяет размер байтов входа (для документа, полученного из сети/БД).
*
* @throws ConversionException при {@code null} или превышении лимита
*/
public static void checkInput(byte[] docxBytes) throws ConversionException {
if (docxBytes == null) {
throw new ConversionException("Не указаны байты входного файла");
}
if (docxBytes.length > MAX_INPUT_BYTES) {
throw new ConversionException("Файл больше 5 МБ: " + docxBytes.length
+ " байт > " + MAX_INPUT_BYTES + " байт");
}
}
/**
* Считает страницы .docx и проверяет лимит.
*
* @throws ConversionException при ошибке загрузки или превышении {@link #MAX_PAGES}
*/
public static void checkPageCount(Path docxIn) throws ConversionException {
if (docxIn == null) {
throw new ConversionException("Не указан путь к .docx");
}
WordprocessingMLPackage pkg;
try {
pkg = WordprocessingMLPackage.load(docxIn.toFile());
} catch (Exception e) {
throw new ConversionException("Не удалось загрузить .docx: " + docxIn, e);
}
checkPageCount(pkg);
}
/**
* Проверяет число страниц без загрузки документа в docx4j: .docx
* читается как zip напрямую (StAX по {@code word/document.xml},
* всем {@code word/header*.xml}, {@code word/footer*.xml} и кэшу
* {@code docProps/app.xml}). Дешёвый путь для проверки байтов из
* сети/БД до любой работы с библиотекой.
*
* <p>Оценка согласована с {@link #checkPageCount(WordprocessingMLPackage)}
* по всем источникам; на границе лимита оба пути дают одинаковый ответ
* (регрессия — {@code checkPageCountLightweight_agreesWithJaxbPath},
* включая 99/100/101 разрывов). Lightweight-путь дополнительно считает
* разрывы в колонтитулах — он консервативнее, расхождение возможно
* только в сторону завышения.
*
* @throws ConversionException при {@code null}, битом zip или превышении {@link #MAX_PAGES}
*/
public static void checkPageCountLightweight(Path docxIn) throws ConversionException {
if (docxIn == null) {
throw new ConversionException("Не указан путь к .docx");
}
if (!Files.isRegularFile(docxIn)) {
throw new ConversionException("Файл не найден: " + docxIn);
}
int pages;
try (ZipFile zip = new ZipFile(docxIn.toFile())) {
List<String> headerFooter = new ArrayList<>();
var entries = zip.entries();
while (entries.hasMoreElements()) {
String n = entries.nextElement().getName();
if (isHeaderFooterPart(n)) {
headerFooter.add(n);
}
}
pages = pageCountOfZip(name -> {
ZipEntry e = zip.getEntry(name);
return e == null ? null : zip.getInputStream(e);
}, headerFooter);
} catch (IOException | RuntimeException e) {
throw new ConversionException("Не удалось разобрать .docx: " + docxIn, e);
}
if (pages > MAX_PAGES) {
throw new ConversionException("Документ длиннее " + MAX_PAGES
+ " страниц: получено не менее " + pages);
}
}
/**
* То же, что {@link #checkPageCountLightweight(Path)}, для байтов .docx.
*
* @throws ConversionException при {@code null}, битом zip или превышении лимита
*/
public static void checkPageCountLightweight(byte[] docxBytes) throws ConversionException {
if (docxBytes == null) {
throw new ConversionException("Не указаны байты входного .docx");
}
int pages;
try (ZipInputStream zip = new ZipInputStream(new ByteArrayInputStream(docxBytes))) {
java.util.Map<String, byte[]> parts = new java.util.HashMap<>();
List<String> headerFooter = new ArrayList<>();
ZipEntry entry;
while ((entry = zip.getNextEntry()) != null) {
String n = entry.getName();
if (n.equals("docProps/app.xml") || n.equals("word/document.xml")
|| isHeaderFooterPart(n)) {
parts.put(n, zip.readAllBytes());
if (isHeaderFooterPart(n)) {
headerFooter.add(n);
}
}
}
pages = pageCountOfZip(name -> {
byte[] b = parts.get(name);
return b == null ? null : new ByteArrayInputStream(b);
}, headerFooter);
} catch (IOException | RuntimeException e) {
throw new ConversionException("Не удалось разобрать байты .docx", e);
}
if (pages > MAX_PAGES) {
throw new ConversionException("Документ длиннее " + MAX_PAGES
+ " страниц: получено не менее " + pages);
}
}
/**
* Считает страницы .docx в байтах и проверяет лимит.
*
* @throws ConversionException при {@code null}, ошибке загрузки или превышении лимита
*/
public static void checkPageCount(byte[] docxBytes) throws ConversionException {
if (docxBytes == null) {
throw new ConversionException("Не указаны байты входного .docx");
}
WordprocessingMLPackage pkg;
try {
pkg = WordprocessingMLPackage.load(new ByteArrayInputStream(docxBytes));
} catch (Exception e) {
throw new ConversionException("Не удалось разобрать байты .docx", e);
}
checkPageCount(pkg);
}
/**
* Считает страницы уже загруженного .docx и проверяет лимит.
*
* <p>Число страниц — максимум трёх нижних оценок:
* <ol>
* <li>Кэш Word в {@code docProps/app.xml} ({@code <Pages>}).
* Сам по себе недостоверен: Word может сохранить устаревшее
* значение (в регрессной фикстуре {@code stale-cache.docx}
* кэш равен 1 при 110 границах страниц).</li>
* <li>Явные разрывы: {@code w:br[@w:type='page']},
* {@code w:pageBreakBefore} и {@code w:sectPr} прямо в
* {@code w:body}. Абзацы ищутся не только прямо в {@code w:body},
* но и внутри таблиц, контентных контролов {@code w:sdt}
* (Word держит нумерацию именно в контентном контроле) и
* прочего содержимого, реализующего {@link ContentAccessor}.</li>
* <li>Маркеры {@code w:lastRenderedPageBreak} — границы страниц,
* которые Word записал при последнем рендере. Единственный
* источник оценки для документов без явных разрывов, порванных
* по заполнению.</li>
* </ol>
*
* <p>Оценка остаётся нижней: документ без явных разрывов и без
* маркеров (никогда не открывался в Word) оценивается в 1 страницу
* независимо от фактической длины — такие документы лимит не отсекают.
*
* @throws ConversionException при превышении {@link #MAX_PAGES}
*/
public static void checkPageCount(WordprocessingMLPackage pkg) throws ConversionException {
if (pkg == null) {
throw new ConversionException("Не указан загруженный .docx");
}
int pages = pageCountOf(pkg);
if (pages > MAX_PAGES) {
throw new ConversionException("Документ длиннее " + MAX_PAGES
+ " страниц: получено не менее " + pages);
}
}
/**
* Возвращает число страниц: максимум кэша {@code <Pages>}, оценки по
* явным разрывам и оценки по {@code w:lastRenderedPageBreak}.
* Виден только из тестов и пакета.
*/
static int pageCountOf(WordprocessingMLPackage pkg) {
int cached = 0;
try {
if (pkg.getDocPropsExtendedPart() != null) {
org.docx4j.docProps.extended.Properties ext =
pkg.getDocPropsExtendedPart().getContents();
if (ext != null && ext.getPages() != null && ext.getPages() > 0) {
cached = ext.getPages();
}
}
} catch (Exception ignored) {
// docPropsExtended может быть не полностью инициализирован —
// тогда остаётся оценка по разрывам.
}
var body = pkg.getMainDocumentPart().getJaxbElement().getBody();
var content = body.getContent();
int explicit = 1; // сам документ — минимум одна страница
for (Object child : content) {
// В JAXB-модели в body.getContent() лежат только межсекционные
// sectPr; финальная секция — в body.getSectPr(), её здесь нет.
if (child instanceof SectPr sect && startsNewPage(sect)) {
explicit++;
}
}
explicit += walkForPageBreaks(content);
int lastRendered = countLastRendered(content);
return Math.max(Math.max(cached, explicit), lastRendered + 1);
}
/**
* Обход содержимого на явные разрывы: абзацы ищутся рекурсивно —
* прямо в {@code w:body}, в ячейках таблиц, в контентных контролах
* {@code w:sdt} и прочем содержимом, реализующем {@link ContentAccessor}.
* Элементы модели приходят и напрямую, и обёрнутыми в
* {@link JAXBElement} (например {@code w:tbl} в {@code w:body}) —
* обёртка раскрывается через {@link #unwrap}.
* Считаются {@code w:br type="page"} и {@code pageBreakBefore}
* (по одному на абзац), как и в lightweight-пути.
*/
private static int walkForPageBreaks(List<?> content) {
int count = 0;
for (Object raw : content) {
Object item = unwrap(raw);
if (item instanceof P p) {
if (p.getPPr() != null
&& p.getPPr().getPageBreakBefore() != null
&& p.getPPr().getPageBreakBefore().isVal()) {
count++;
}
for (Object runChild : p.getContent()) {
if (unwrap(runChild) instanceof org.docx4j.wml.R r) {
for (Object innerRaw : r.getContent()) {
if (unwrap(innerRaw) instanceof Br br
&& br.getType() == STBrType.PAGE) {
count++;
}
}
}
}
} else if (item instanceof ContentAccessor ca) {
// w:tbl / w:tr / w:tc / w:sdt / w:sdtContent и т.п.
count += walkForPageBreaks(ca.getContent());
}
}
return count;
}
/** Подсчёт маркеров {@code w:lastRenderedPageBreak} в содержимом. */
private static int countLastRendered(List<?> content) {
int count = 0;
for (Object raw : content) {
Object item = unwrap(raw);
if (item instanceof R.LastRenderedPageBreak) {
count++;
} else if (item instanceof ContentAccessor ca) {
count += countLastRendered(ca.getContent());
}
}
return count;
}
/** Раскрывает обёртку {@link JAXBElement} (docx4j так отдаёт tbl и часть содержимого). */
private static Object unwrap(Object item) {
return item instanceof JAXBElement<?> je ? je.getValue() : item;
}
/** Секция, начинающая новую страницу (continuous — нет). */
private static boolean startsNewPage(SectPr sect) {
return sect.getType() == null
|| sect.getType().getVal() == null
|| !sect.getType().getVal().equals("continuous");
}
/** Поставщик потока по имени части zip; null — части нет. */
private interface PartStream {
InputStream open(String name) throws IOException;
}
/** {@code word/headerN.xml} / {@code word/footerN.xml} (не .rels). */
private static boolean isHeaderFooterPart(String name) {
return (name.startsWith("word/header") || name.startsWith("word/footer"))
&& name.endsWith(".xml");
}
/**
* Лёгкий расчёт числа страниц прямо по zip-пакету .docx, без docx4j.
* Та же логика, что у {@link #pageCountOf(WordprocessingMLPackage)}:
* максимум кэша {@code docProps/app.xml <Pages>}, явных разрывов и
* {@code w:lastRenderedPageBreak}. Считаются все колонтитулы
* ({@code word/header*.xml}, {@code word/footer*.xml}) — там Word тоже
* держит {@code w:br type="page"}.
*/
private static int pageCountOfZip(PartStream parts, List<String> headerFooterParts)
throws IOException {
int cached = cachedPageCount(parts.open("docProps/app.xml"));
BreakScan scan = scanDocument(parts.open("word/document.xml"));
int explicit = 1 + scan.breaks(); // сам документ — минимум одна страница
for (String part : headerFooterParts) {
explicit += countBreaksInFlat(parts.open(part));
}
return Math.max(Math.max(cached, explicit), scan.lastRendered() + 1);
}
/** Результат разбора word/document.xml: явные разрывы и маркеры. */
private record BreakScan(int breaks, int lastRendered) {
}
/** Кэш Word &lt;Pages&gt; из docProps/app.xml; 0 — части/значения нет. */
private static int cachedPageCount(InputStream in) throws IOException {
if (in == null) {
return 0;
}
try {
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
while (xr.hasNext()) {
if (xr.next() == XMLStreamReader.START_ELEMENT
&& xr.getLocalName().equals("Pages")) {
String text = xr.getElementText().trim();
return Math.max(0, Integer.parseInt(text));
}
}
return 0;
} catch (XMLStreamException | NumberFormatException e) {
return 0;
} finally {
in.close();
}
}
/**
* Нижняя оценка по {@code word/document.xml}: {@code w:br type="page"},
* {@code w:pageBreakBefore}, {@code w:sectPr} прямо в {@code body} и
* маркеры {@code w:lastRenderedPageBreak}. Обход плоский (StAX),
* вложенность не нужна — считаем события.
*
* <p>Согласованность с JAXB-путём:
* <ul>
* <li>{@code sectPr} внутри {@code pPr} не считается: в StAX-виде
* там и финальная секция, и межсекционные — неразличимы, а
* JAXB-путь их не видит (в {@code body.getContent()} лежат только
* межсекционные). Такие документы покрываются кэшем
* {@code <Pages>} и маркерами {@code lastRenderedPageBreak};</li>
* <li>{@code sectPr} прямо в {@code body}: в StAX-виде их на один
* больше, чем в JAXB-виде (финальная секция — это JAXB
* {@code body.getSectPr()}, вне {@code getContent()}), поэтому
* последнюю не считаем, а среди остальных считаем только
* начинающие новую страницу;</li>
* <li>непрерывные секции ({@code type="continuous"}) не считаются —
* ровно как в JAXB-пути, где их отсекает {@code startsNewPage}.</li>
* </ul>
*/
private static BreakScan scanDocument(InputStream in) throws IOException {
if (in == null) {
return new BreakScan(0, 0);
}
int breaks = 0;
int lastRendered = 0;
int bodyDirectSectPr = 0;
// w:type — ДОЧЕРНИЙ элемент (<w:type w:val="continuous"/>), а не
// атрибут sectPr, поэтому body-direct секция классифицируется на
// её закрытии; последняя body-direct — финальная секция, не
// считается, так что при закрытии новой секции считаем предыдущую
boolean inBodySectPr = false;
String sectTypeVal = null;
boolean pendingNewPageSection = false;
try {
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
// стек имён START_ELEMENT: «внутри ли w:p/w:pPr/sectPr» и
// родитель текущего элемента (для sectPr).
Deque<String> path = new ArrayDeque<>();
while (xr.hasNext()) {
int ev = xr.next();
if (ev == XMLStreamReader.START_ELEMENT) {
String name = xr.getLocalName();
String parent = path.peek();
path.push(name);
switch (name) {
case "br" -> {
if (isPageBreak(xr) && inside(path, "p")) {
breaks++;
}
}
case "lastRenderedPageBreak" -> {
if (inside(path, "p")) {
lastRendered++;
}
}
case "pageBreakBefore" -> {
if (truthy(xr) && inside(path, "pPr") && !inside(path, "sectPr")) {
breaks++;
}
}
case "sectPr" -> {
if ("body".equals(parent)) {
inBodySectPr = true;
sectTypeVal = null;
}
// sectPr внутри pPr — не считаем (StAX не
// различает финальную и межсекционные)
}
case "type" -> {
if (inBodySectPr && "sectPr".equals(parent)) {
sectTypeVal = xr.getAttributeValue(WML_NS, "val");
}
}
default -> {
}
}
} else if (ev == XMLStreamReader.END_ELEMENT) {
if ("sectPr".equals(xr.getLocalName()) && inBodySectPr) {
if (pendingNewPageSection) {
bodyDirectSectPr++;
}
pendingNewPageSection =
!"continuous".equals(sectTypeVal);
inBodySectPr = false;
}
if (!path.isEmpty()) {
path.pop();
}
}
}
} catch (XMLStreamException e) {
throw new IOException("Некорректный XML в word/document.xml", e);
} finally {
in.close();
}
// последняя body-direct секция не внесена — это финальная секция
breaks += bodyDirectSectPr;
return new BreakScan(breaks, lastRendered);
}
/** Оценка по колонтитулам: только {@code w:br type="page"} (там нет body/sectPr). */
private static int countBreaksInFlat(InputStream in) throws IOException {
if (in == null) {
return 0;
}
int count = 0;
try {
XMLStreamReader xr = newSecureReader().createXMLStreamReader(in);
while (xr.hasNext()) {
if (xr.next() == XMLStreamReader.START_ELEMENT
&& xr.getLocalName().equals("br") && isPageBreak(xr)) {
count++;
}
}
} catch (XMLStreamException e) {
throw new IOException("Некорректный XML в колонтитуле", e);
} finally {
in.close();
}
return count;
}
private static XMLInputFactory newSecureReader() {
XMLInputFactory f = XMLInputFactory.newInstance();
f.setProperty(XMLInputFactory.SUPPORT_DTD, false);
f.setProperty(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES, false);
return f;
}
private static boolean isPageBreak(XMLStreamReader xr) {
return "page".equals(xr.getAttributeValue(WML_NS, "type"));
}
private static boolean truthy(XMLStreamReader xr) {
String v = xr.getAttributeValue(WML_NS, "val");
return v == null || v.equals("true") || v.equals("1") || v.equals("on");
}
private static boolean inside(Deque<String> path, String ancestor) {
return path.contains(ancestor);
}
private static final String WML_NS =
"http://schemas.openxmlformats.org/wordprocessingml/2006/main";
}
@@ -27,6 +27,7 @@ import javax.imageio.ImageIO;
import java.awt.Color; import java.awt.Color;
import java.awt.Graphics2D; import java.awt.Graphics2D;
import java.awt.image.BufferedImage; import java.awt.image.BufferedImage;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream; import java.io.ByteArrayOutputStream;
import java.io.File; import java.io.File;
import java.io.FileOutputStream; import java.io.FileOutputStream;
@@ -68,6 +69,8 @@ public final class SampleDocxGenerator {
symbolBullets(dir.resolve("symbol-bullets.docx")); symbolBullets(dir.resolve("symbol-bullets.docx"));
pageNumbers(dir.resolve("page-numbers.docx")); pageNumbers(dir.resolve("page-numbers.docx"));
exoticGlyphs(dir.resolve("exotic-glyphs.docx")); exoticGlyphs(dir.resolve("exotic-glyphs.docx"));
tooManyPages(dir.resolve("too-many-pages.docx"));
staleCache(dir.resolve("stale-cache.docx"));
System.out.println("Готово: " + dir.toAbsolutePath()); System.out.println("Готово: " + dir.toAbsolutePath());
} }
@@ -326,6 +329,108 @@ public final class SampleDocxGenerator {
} }
} }
/**
* Документ длиннее лимита страниц: 150 абзацев с принудительным
* {@code w:br type="page"} → нижняя оценка по явным разрывам
* = 1 + 150 = 151 > 100. Используется как фикстура для проверки
* постраничного лимита в {@code WordPdfValidator}.
*/
private static void tooManyPages(Path out) throws Exception {
try (XWPFDocument doc = new XWPFDocument()) {
heading(doc, "Слишком много страниц", "Times New Roman");
for (int i = 1; i <= 150; i++) {
XWPFParagraph p = doc.createParagraph();
run(p, "Страница " + i, "Times New Roman", false, false);
p.createRun().addBreak(org.apache.poi.xwpf.usermodel.BreakType.PAGE);
}
save(doc, out);
}
}
/**
* Документ с устаревшим кэшем страниц — как Word сохраняет файл,
* доработанный другим редактором: 111 абзацев, разделённых маркерами
* {@code w:lastRenderedPageBreak} (110 границ страниц, то есть
* ~111 страница), и при этом в {@code docProps/app.xml} записан кэш
* {@code <Pages>1</Pages>}. Явных разрывов нет ни одного.
*
* <p>Регрессия для {@code WordPdfValidator}: кэш больше не приоритетный
* источник, оценка по маркерам (111) должна победить кэш (1) и
* документ должен быть отвергнут до рендера.
*/
private static void staleCache(Path out) throws Exception {
try (XWPFDocument doc = new XWPFDocument()) {
doc.getProperties().getExtendedProperties()
.getUnderlyingProperties().setPages(1);
heading(doc, "Устаревший кэш страниц", "Calibri");
for (int i = 1; i <= 110; i++) {
XWPFParagraph p = doc.createParagraph();
run(p, "Абзац " + i, "Calibri", false, false);
}
ByteArrayOutputStream bos = new ByteArrayOutputStream();
doc.write(bos);
insertLastRenderedMarkers(bos.toByteArray(), out);
}
}
/**
* Переупаковывает .docx, вставляя {@code w:lastRenderedPageBreak}
* перед каждым текстовым тегом {@code w:t} в {@code word/document.xml},
* кроме первых {@value #STALE_CACHE_UNMARKED_RUNS} (первый абзац
* остаётся без маркера). Тег ищется точно ({@code <w:t>} /
* {@code <w:t }): префикс {@code <w:t} — это также {@code w:tab},
* {@code w:tbl}, {@code w:tc}, маркеры в которые недопустимы по схеме
* (вне CT_R → невалидный docx). Позиция корректна по схеме CT_R:
* rPr, затем маркер, затем текст.
*/
private static void insertLastRenderedMarkers(byte[] docx, Path out) throws Exception {
final int unmarked = STALE_CACHE_UNMARKED_RUNS;
try (java.util.zip.ZipInputStream zin =
new java.util.zip.ZipInputStream(new ByteArrayInputStream(docx));
java.util.zip.ZipOutputStream zout =
new java.util.zip.ZipOutputStream(new FileOutputStream(out.toFile()))) {
java.util.zip.ZipEntry e;
while ((e = zin.getNextEntry()) != null) {
byte[] data = zin.readAllBytes();
if (e.getName().equals("word/document.xml")) {
String xml = new String(data, java.nio.charset.StandardCharsets.UTF_8);
StringBuilder sb = new StringBuilder(xml.length() + 4096);
int i = 0;
int seen = 0;
while (true) {
int at = xml.indexOf("<w:t", i);
if (at < 0) {
sb.append(xml, i, xml.length());
break;
}
sb.append(xml, i, at);
int end = at + "<w:t".length();
char next = end < xml.length() ? xml.charAt(end) : '<';
if (next != '>' && next != ' ') {
// <w:tab/<w:tbl/<w:tc/... — не текстовый тег
sb.append(xml, at, end);
i = end;
continue;
}
if (seen >= unmarked) {
sb.append("<w:lastRenderedPageBreak/>");
}
seen++;
sb.append(xml, at, end);
i = end;
}
data = sb.toString().getBytes(java.nio.charset.StandardCharsets.UTF_8);
}
zout.putNextEntry(new java.util.zip.ZipEntry(e.getName()));
zout.write(data);
zout.closeEntry();
}
}
}
/** Сколько {@code w:t} в фикстуре stale-cache остаются без маркера. */
private static final int STALE_CACHE_UNMARKED_RUNS = 1;
// ================== Вспомогательные ================== // ================== Вспомогательные ==================
/** Абзац-заголовок: POI 5.5 не имеет createHeading, поэтому /** Абзац-заголовок: POI 5.5 не имеет createHeading, поэтому
@@ -378,4 +378,74 @@ class WordPdfConverterTest {
assertEquals(expected, out); assertEquals(expected, out);
assertTrue(Files.isRegularFile(out), "PDF не создан: " + out); assertTrue(Files.isRegularFile(out), "PDF не создан: " + out);
} }
/**
* Лимит на размер входного .docx: больше 5 MiB — отказ до рендера.
* Проверяется через обе формы convert.
*/
@Test
void inputTooLarge() throws Exception {
Path tooBig = Files.createTempFile("too-big-", ".docx");
Path out = Files.createTempFile("too-big-out-", ".pdf");
try {
// Пишем чуть больше лимита (5 MiB + 1 байт)
byte[] filler = new byte[(int) WordPdfValidator.MAX_INPUT_BYTES + 1];
Files.write(tooBig, filler);
assertThrows(ConversionException.class,
() -> WordPdfConverter.convert(tooBig));
assertFalse(Files.exists(Path.of(
tooBig.toString().replaceFirst("\\.docx$", "") + ".pdf")),
"отказ по размеру не должен создавать PDF рядом со входом");
assertThrows(ConversionException.class,
() -> WordPdfConverter.convert(tooBig, out));
assertEquals(0L, Files.size(out),
"отказ по размеру — до открытия потока вывода, "
+ "выходной файл не должен быть затронут");
} finally {
Files.deleteIfExists(tooBig);
Files.deleteIfExists(out);
}
}
/**
* Лимит на число страниц: документ с 150 явными разрывами страниц
* (фикстура too-many-pages.docx, нижняя оценка 151) должен
* отвергаться до рендеринга. PDF не создаётся — в том числе пустой
* файл-артефакт от уже открытого потока вывода.
*/
@Test
void tooManyPages() throws Exception {
Path in = extractSample("too-many-pages.docx");
Path out = Files.createTempFile("too-many-out-", ".pdf");
Files.deleteIfExists(out);
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfConverter.convert(in, out));
assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage());
assertFalse(Files.exists(out),
"отказ по страницам не должен оставлять PDF: " + out);
}
/**
* Документ с устаревшим кэшем {@code <Pages>1</Pages>} и 110 маркерами
* {@code w:lastRenderedPageBreak} (фикстура stale-cache.docx — модель
* реального документа пользователя «110 страниц.docx»): конвертер
* обязан отвергнуть его до рендера и не оставить PDF.
*/
@Test
void staleCachePageCountRejectedBeforeRender() throws Exception {
Path in = extractSample("stale-cache.docx");
Path out = Files.createTempFile("stale-cache-out-", ".pdf");
Files.deleteIfExists(out);
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfConverter.convert(in, out));
assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage());
assertFalse(Files.exists(out),
"отказ по страницам не должен оставлять PDF: " + out);
}
} }
@@ -0,0 +1,353 @@
package ru.pjandro.wordpdf;
import org.apache.poi.xwpf.usermodel.BreakType;
import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.apache.poi.xwpf.usermodel.XWPFTable;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.junit.jupiter.api.Test;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import static org.junit.jupiter.api.Assertions.*;
/**
* Юнит-тесты валидатора: размер (Path и byte[]) и число страниц
* (Path, byte[] и уже загруженный пакет).
*/
class WordPdfValidatorTest {
private static Path bigDocx(long size) throws IOException {
Path tmp = Files.createTempFile("validator-", ".docx");
Files.write(tmp, new byte[(int) size]);
return tmp;
}
private static byte[] docxWithPageBreaks(int count) throws Exception {
try (XWPFDocument doc = new XWPFDocument()) {
for (int i = 0; i < count; i++) {
XWPFParagraph p = doc.createParagraph();
p.createRun().setText("p" + i);
p.createRun().addBreak(BreakType.PAGE);
}
ByteArrayOutputStream bos = new ByteArrayOutputStream();
doc.write(bos);
return bos.toByteArray();
}
}
@Test
void checkInput_pathWithinLimit() throws IOException {
Path p = bigDocx(1024);
try {
assertDoesNotThrow(() -> WordPdfValidator.checkInput(p));
} finally {
Files.deleteIfExists(p);
}
}
@Test
void checkInput_pathOverLimit() throws IOException {
Path p = bigDocx(WordPdfValidator.MAX_INPUT_BYTES + 1);
try {
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkInput(p));
assertTrue(ex.getMessage().contains("5 МБ"),
"сообщение должно упоминать лимит: " + ex.getMessage());
} finally {
Files.deleteIfExists(p);
}
}
@Test
void checkInput_pathNull() {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkInput((Path) null));
}
@Test
void checkInput_bytesWithinLimit() {
assertDoesNotThrow(() ->
WordPdfValidator.checkInput(new byte[1024]));
}
@Test
void checkInput_bytesOverLimit() {
byte[] big = new byte[(int) WordPdfValidator.MAX_INPUT_BYTES + 1];
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkInput(big));
assertTrue(ex.getMessage().contains("5 МБ"),
"сообщение должно упоминать лимит: " + ex.getMessage());
}
@Test
void checkInput_bytesNull() {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkInput((byte[]) null));
}
@Test
void checkPageCount_pkgWithinLimit() throws Exception {
byte[] bytes = docxWithPageBreaks(5); // 1 + 5 = 6 страниц по оценке
WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new java.io.ByteArrayInputStream(bytes));
assertDoesNotThrow(() -> WordPdfValidator.checkPageCount(pkg));
}
@Test
void checkPageCount_pkgOverLimit() throws Exception {
byte[] bytes = docxWithPageBreaks(120); // 1 + 120 = 121
WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new java.io.ByteArrayInputStream(bytes));
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCount(pkg));
assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage());
}
@Test
void checkPageCount_bytesOverLimit() throws Exception {
byte[] bytes = docxWithPageBreaks(120);
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCount(bytes));
assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage());
}
@Test
void checkPageCount_bytesNull() {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCount((byte[]) null));
}
@Test
void checkPageCount_pkgNull() {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCount((WordprocessingMLPackage) null));
}
// ---- lightweight (zip/StAX, без docx4j) ----
@Test
void checkPageCountLightweight_bytesWithinLimit() throws Exception {
byte[] bytes = docxWithPageBreaks(5);
assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(bytes));
}
@Test
void checkPageCountLightweight_bytesOverLimit() throws Exception {
byte[] bytes = docxWithPageBreaks(120);
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight(bytes));
assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage());
}
@Test
void checkPageCountLightweight_pathOverLimit() throws Exception {
Path tmp = Files.createTempFile("validator-lw-", ".docx");
Files.write(tmp, docxWithPageBreaks(120));
try {
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight(tmp));
assertTrue(ex.getMessage().contains("100"),
"сообщение должно упоминать лимит: " + ex.getMessage());
} finally {
Files.deleteIfExists(tmp);
}
}
@Test
void checkPageCountLightweight_agreesWithJaxbPath() throws Exception {
// на фикстурах без кэша Pages оба пути обязаны совпадать,
// включая границу лимита: 99 разрывов = 100 страниц (проходит),
// 100/101 = 101/102 (отказ)
for (int breaks : new int[]{0, 3, 99, 100, 101}) {
byte[] bytes = docxWithPageBreaks(breaks);
WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new java.io.ByteArrayInputStream(bytes));
int jaxb = WordPdfValidator.pageCountOf(pkg);
// lightweight-путь приватный; проверяем через границу лимита:
// 1+breaks совпадает с оценкой JAXB
assertEquals(1 + breaks, jaxb, "JAXB-оценка для " + breaks + " разрывов");
if (breaks < 100) {
assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(bytes));
} else {
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight(bytes));
assertTrue(ex.getMessage().contains("не менее " + (1 + breaks)),
"оценка lightweight должна совпадать с JAXB: " + ex.getMessage());
}
}
}
/**
* Секция {@code type="continuous"} по OOXML новую страницу не
* начинает — lightweight-путь (zip/StAX) не обязан её считать, а
* последняя body-direct секция (финальная) не считается никогда.
* Случай A: 100 {@code nextPage} + финальная {@code continuous} —
* 101 страница, отказ (старый код считал «все минус одна» без
* учёта типа: 101−1=100 и пропускал). Случай B: 101
* {@code continuous} + финальная {@code nextPage} — 1 страница,
* проходит (старый код раздувал до 102 и отвергал). В JAXB-модели
* body-direct sectPr не видны (docx4j оставляет только финальную
* в {@code body.getSectPr()}, {@code getContent()} пуст), поэтому
* расхождение lightweight здесь — допустимое завышение.
* Регрессия — WordPdfValidator#scanDocument.
*/
@Test
void pageCount_continuousSectionsNotCountedLightweight() throws Exception {
java.util.List<String> typesA = new java.util.ArrayList<>();
for (int i = 0; i < 100; i++) {
typesA.add("nextPage");
}
typesA.add("continuous"); // финальная секция — непрерывная
byte[] overLimit = docxWithBodySections(typesA);
ConversionException exLwA = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight(overLimit));
assertTrue(exLwA.getMessage().contains("не менее 101"),
"оценка = 1 + 100 межсекционных nextPage: " + exLwA.getMessage());
java.util.List<String> typesB = new java.util.ArrayList<>();
for (int i = 0; i < 101; i++) {
typesB.add("continuous");
}
typesB.add("nextPage"); // финальная секция
byte[] ok = docxWithBodySections(typesB);
assertDoesNotThrow(() -> WordPdfValidator.checkPageCountLightweight(ok),
"continuous-границы не страницы");
}
/**
* docx от POI, в {@code word/document.xml} которого перед закрытием
* {@code w:body} вставлены {@code w:sectPr} прямо в {@code body} с
* указанными {@code w:type} (последняя из них — финальная секция;
* POI сам финальный sectPr не пишет).
*/
private static byte[] docxWithBodySections(java.util.List<String> types)
throws Exception {
byte[] base = docxWithPageBreaks(0);
ByteArrayOutputStream out = new ByteArrayOutputStream();
try (java.util.zip.ZipInputStream zin = new java.util.zip.ZipInputStream(
new java.io.ByteArrayInputStream(base));
java.util.zip.ZipOutputStream zout = new java.util.zip.ZipOutputStream(out)) {
java.util.zip.ZipEntry e;
while ((e = zin.getNextEntry()) != null) {
byte[] data = zin.readAllBytes();
if (e.getName().equals("word/document.xml")) {
String xml = new String(data, java.nio.charset.StandardCharsets.UTF_8);
StringBuilder sb = new StringBuilder();
for (String t : types) {
sb.append("<w:sectPr><w:type w:val=\"").append(t)
.append("\"/></w:sectPr>");
}
// POI не пишет финальный sectPr — последняя вставленная
// секция и есть финальная (в JAXB уйдёт в body.getSectPr());
// пустой body сериализуется самозакрывающимся тегом
int at = xml.indexOf("</w:body>");
if (at >= 0) {
xml = xml.substring(0, at) + sb + xml.substring(at);
} else {
at = xml.indexOf("<w:body/>");
assertTrue(at >= 0, "в document.xml нет w:body");
xml = xml.substring(0, at) + "<w:body>" + sb + "</w:body>"
+ xml.substring(at + "<w:body/>".length());
}
data = xml.getBytes(java.nio.charset.StandardCharsets.UTF_8);
}
zout.putNextEntry(new java.util.zip.ZipEntry(e.getName()));
zout.write(data);
zout.closeEntry();
}
}
return out.toByteArray();
}
// ---- устаревший кэш <Pages> ----
private static byte[] staleCacheFixture() throws Exception {
try (java.io.InputStream in = WordPdfValidatorTest.class.getClassLoader()
.getResourceAsStream("samples/stale-cache.docx")) {
assertNotNull(in, "Нет фикстуры samples/stale-cache.docx");
return in.readAllBytes();
}
}
/**
* Кэш Word {@code <Pages>1</Pages>} в документе с 110 маркерами
* {@code w:lastRenderedPageBreak}: кэш больше не приоритетный источник,
* оценка по маркерам (111) обязана победить и документ — быть
* отвергнутым. Это регрессия на реальном документе пользователя
* («110 страниц.docx»: кэш 1, маркеров 110, явных разрывов 0).
*/
@Test
void pageCount_staleCacheLosesToLastRenderedMarkers() throws Exception {
byte[] bytes = staleCacheFixture();
WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new java.io.ByteArrayInputStream(bytes));
assertEquals(111, WordPdfValidator.pageCountOf(pkg),
"оценка = max(кэш 1, разрывы 1, маркеры 110+1)");
ConversionException ex = assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCount(pkg));
assertTrue(ex.getMessage().contains("100"), ex.getMessage());
// lightweight-путь обязан согласовать тот же отказ
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight(bytes));
}
/**
* Явные разрывы внутри таблиц и контентных контролов тоже считаются:
* раньше обходил только прямой контент body, и документ с разрывами в
* ячейках оценивался в 1 страницу.
*/
@Test
void pageCount_breaksInsideTablesAreCounted() throws Exception {
byte[] bytes;
try (XWPFDocument doc = new XWPFDocument()) {
XWPFTable table = doc.createTable(2, 1);
for (int i = 0; i < 120; i++) {
XWPFParagraph p = table.getRow(0).getCell(0).getParagraphs().get(0);
p.createRun().setText("t" + i);
p.createRun().addBreak(BreakType.PAGE);
}
java.io.ByteArrayOutputStream bos = new java.io.ByteArrayOutputStream();
doc.write(bos);
bytes = bos.toByteArray();
}
WordprocessingMLPackage pkg = WordprocessingMLPackage.load(
new java.io.ByteArrayInputStream(bytes));
assertEquals(121, WordPdfValidator.pageCountOf(pkg),
"разрывы в ячейке таблицы должны считаться");
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCount(bytes));
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight(bytes));
}
@Test
void checkPageCountLightweight_bytesNull() {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight((byte[]) null));
}
@Test
void checkPageCountLightweight_pathNull() {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight((Path) null));
}
@Test
void checkPageCountLightweight_notAZip() throws IOException {
Path tmp = Files.createTempFile("validator-lw-bad-", ".docx");
Files.write(tmp, "not a zip at all".getBytes());
try {
assertThrows(ConversionException.class,
() -> WordPdfValidator.checkPageCountLightweight(tmp));
} finally {
Files.deleteIfExists(tmp);
}
}
}