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

118 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```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`.