diff --git a/AGENTS.md b/AGENTS.md index 977a79a..03ed09d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,7 @@ | 3 | `pkg.setFontMapper(mapper)` | Привязка шрифтов документа к физическим TTF | | 3.5 | `DrawingPreRenderer.run(pkg, options)` | `c:chart`/`dgm:relIds` → PNG 300 dpi → `pic:pic` (docx2fo.xslt их не умеет) | | 4 | `new FOSettings(pkg)` + `FopFallbackFonts.declare(foSettings)` | В FOP-конфиг добавляются **все** бандл-семейства: FOP встраивает только задекларированные | +| 4.5 | `foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES)` | Стилист — вендорный `xslt/docx2fo.xslt` (копия docx4j-export-fo + AUDIT-FIX-патч `w:rPr/w:position`→`baseline-shift`); `Templates` компилируется один раз — `getTemplates` кастит значение в `Templates` | | 5 | `FORendererApacheFOP.getFopFactoryBuilder` + `getFOUserAgent` | Непустой `title` → заголовок PDF | | 6 | `Docx4J.toFO(foSettings, os, FLAG_EXPORT_PREFER_XSL)` | XSL-FO → PDF | | 7 | `finally` → `getFontTablePart().deleteEmbeddedFontTempFiles()` | В docx4j 17.x `OpcPackage.close()` нет — пакет в памяти | @@ -37,7 +38,7 @@ Контракт: `byte[] normalize(byte[]) throws IOException`; нечего менять → вернуть **тот же массив** (`assertSame` в тестах). Каждый выставляет константу `STEP` (`public static final DocxNormalizer`). Правила 1–6 применяет `internal/DocxRewritePipeline` — **один zip-проход**: к каждой записи `word/*.xml` рерайты цепляются в фиксированном порядке Strict→OnOff→Symbol→Field→Invisible→GlyphCoverage (каждое правило работает только содержимым одной части — по-частная цепочка эквивалентна последовательным полным проходам); неизменённые записи переносятся raw-копией сжатых байтов (без inflate/deflate); нигде не поменялось → тот же массив. `OleObjectNormalizer` — второй условный проход (меняет части, а не XML). Индивидуальные `normalize()` шести нормализаторов сохранены (контракт юнит-тестов), но `WordPdfConverter` их не вызывает — его `normalizers(options)` = `DocxRewritePipeline.STEP` + лямбда OLE. Порядок правил значим: -1. `StrictOoxmlNormalizer` — strict-OOXML → transitional: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`; элементы `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml); значения `w:val="start"/"end"` у `w:jc` (только strict) и `w:tab` (всегда). Strict-ность части определяется наличием `http://purl.oclc.org` (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). **Guard сосуществования форм**: атрибут `w:start`/`w:end` не переименовывается, если в том же открывающем теге уже есть `w:left`/`w:right` (дубль атрибута ломает well-formedness — регрессии `indCoexistLeftStartUntouched`, `indCoexistForms_convertsNotRejected`); элементы `w:start`/`w:end` в strict-части переименовываются глобально, в transitional — только внутри `w:tcMar`/`w:tblCellMar` без одноимённого соседа (`maxOccurs=1` на left). Ничего не поменялось → `rewrite` вернул `null` → исходный массив (`StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray`). +1. `StrictOoxmlNormalizer` — strict-OOXML → transitional: `a:`-проценты и `w14:fillToRect` → тысячные ×1000, текст `wp14:pctWidth`/`pctHeight`; элементы `w:start`/`w:end` → `w:left`/`w:right` (кроме `w:lvl/w:start` в numbering.xml); значения `w:val="start"/"end"` у `w:jc` и `w:tab` правятся **всегда** (docx4j `Justification.setXslFO` знает только left/center/right/both, для END `fo:text-align` не пишет вовсе — `jc="end"` рендерился по левому краю; Part 4 §14.11.2: left≡start, right≡end, RTL вне контура — FOP без complex-script). Strict-ность части определяется наличием `http://purl.oclc.org` (не «transitional-URI в документе» — mixed-документ трактуется по каждой части). **Guard сосуществования форм**: атрибут `w:start`/`w:end` не переименовывается, если в том же открывающем теге уже есть `w:left`/`w:right` (дубль атрибута ломает well-formedness — регрессии `indCoexistLeftStartUntouched`, `indCoexistForms_convertsNotRejected`); элементы `w:start`/`w:end` в strict-части переименовываются глобально, в transitional — только внутри `w:tcMar`/`w:tblCellMar` без одноимённого соседа (`maxOccurs=1` на left). Ничего не поменялось → `rewrite` вернул `null` → исходный массив (`StrictOoxmlNormalizerTest#transitionalCoexistReturnsOriginalArray`). 2. `DocxOnOffNormalizer` — `w:val="off"/"on"` → `"false"/"true"`; якорь по тегу, правится только атрибут `w:val`, текст между тегами не трогается. 3. `SymbolFontNormalizer` — PUA U+F000–U+F0FF (Symbol/Wingdings/Webdings) → Unicode + DejaVu Sans; переписывает ``, правит `w:lvl` в numbering.xml; 5 карт по 256 слотов (таблица `SymbolMapper` из docx4j 17.x). 4. `FieldNormalizer` — `fldChar` PAGE/NUMPAGES/SECTIONPAGES → `w:fldSimple` (кэш страниц в PDF не попадает); вложенные/битые поля пропускаются. @@ -84,12 +85,14 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр ### Критические инварианты (нарушение = битый вывод, не исключение) - `docx4j.convert.out.fo.gsubFeatures=false` — static-блок `WordPdfConverter`. Иначе FO невалиден → `WordLayoutFixups` молча отказывает всем фиксам → FOP падает на `docx4j-baseline`. +- Единственный XSL-FO-стилист — вендорный `wordpdf-core/src/main/resources/xslt/docx2fo.xslt` (копия `docx2fo.xslt` из docx4j-export-fo 17.3.2 + AUDIT-FIX-патч `w:rPr/w:position` → `baseline-shift`, полупункты, Part 4 §17.3.2.24 — docx4j position игнорирует). Дрейф-гейт `WordPdfConverterTest#vendoredXsltTracksJarCopy` (SHA-256 стилиста из jar'а): при апгрейде docx4j — перевендорить и перенести патч. `setCustomXsltTemplates` принимает предкомпилированный `Templates` (`getTemplates` кастит Object→Templates, поток кидает CCE). - `slf4j-simple` обязателен в ядре: без SLF4J-провайдера docx4j пишет «TO HIDE THESE MESSAGES» прямо в PDF (регрессия `noLoggingWarningInPdf`). Приложение исключает его из зависимости ядра — логи ведёт logback. -- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo` 17.3.2, в pom не пинится; пакеты `org.apache.fop.*`). `w:renderers` в docx4j 17.x содержит несколько `w:renderer` (по mime) — `FopFallbackFonts` берёт тот, у которого mime `application/pdf`, иначе первый со шрифтами. `docx2fo.xslt` в репозитории нет — он в jar `docx4j-export-fo`. +- FOP — форк `org.docx4j:docx4j-fo-renderer*` 2.11-docx4j.6 (транзитив от `docx4j-export-fo` 17.3.2, в pom не пинится; пакеты `org.apache.fop.*`). `w:renderers` в docx4j 17.x содержит несколько `w:renderer` (по mime) — `FopFallbackFonts` берёт тот, у которого mime `application/pdf`, иначе первый со шрифтами. Оригинал `docx2fo.xslt` — в jar `docx4j-export-fo`, в конвейере используется вендорная копия (см. выше). - Порядок инициализации шрифтов: `new BundledFontMapper()` → `BundledFonts.init()` → `restrictToBundled()` — **до** `load()`. `BundledFonts.init()` идемпотентен и `synchronized`, распаковывает TTF во временный каталог `wordpdf-fonts-*` (`deleteOnExit` на файлы и на каталог). `dropNonBundled()` чистит глобальный реестр `PhysicalFonts` от всего, что вне бандла. - `PhysicalFonts` — глобальный и мутируемый → ядро не потокобезопасно; приложение сериализует конвертации одним воркером. - Страницы в валидаторе = `max(кэш docProps/app.xml, явные разрывы, lastRenderedPageBreak+1)`; explicit = межсекционные `w:sectPr` в body + `w:br type="page"` + `pageBreakBefore` (включая таблицы и `w:sdt`). Единственный путь — lightweight (StAX по zip, secure-ридер без DTD/external entities; `WordPdfValidator` не зависит от docx4j): атрибуты — по локальному имени (`attrLocal`, не по transitional-URI: иначе в strict-документе `w:br type="page"` не засчитываются); `sectPr` внутри `pPr` не считает, последнюю body-direct секцию не считает, `continuous`-секции не считает, в колонтитуках — только `w:br type="page"`, `pageBreakBefore` — только внутри `pPr` вне `sectPr` (truthy `val`: `null|true|1|on`). На не-zip молчит — подпись проверяет вызывающий. `checkPageCount` — один стриминговый проход `ZipInputStream` без буферизации частей (хелпер `noClose` глушит `close()` сканеров): потребление O(одной части) вместо O(суммы XML-частей). - Известный остаток эталона: U+2188/U+218A — глифов нет в OFL-шрифтах бандла, остаются `.notdef` (GNU FreeSerif GPL — не добавляем намеренно). +- Аудит раскладки по ECMA-376 (2026-10) — известные нечинимые ограничения FOP/docx4j (Java-слой): `w:jc="distribute"` рендерится как left (XSLT-обходки невозможны: FOP не джаститифицирует истинно последнюю строку блока, `text-align-last` работает только перед форсированным разрывом); `w:suff` (nothing/space) и `w:lvlJc` игнорируются (numbering-лейбл всегда через hanging-tab); `w:tblInd` при `w:jc`≠left игнорируется (буквально по §17.4.50; Word не игнорирует — MS-OI29500 §2.1.155); высота строки `lineRule="auto"` калибрована docx4j на Word-single (~13.9pt@11pt), не на natural-высоту FOP (15.44pt); кернинг применяется без порога `w:kern`. - Внимание: комментарии в `WordPdfConverter`/`DocxOnOffNormalizer` говорят «docx4j 11.x» — устаревшее число, фактически 17.3.2 (описанное поведение верно). ### Шрифты (30 TTF + 3 лицензии, SIL OFL, `wordpdf-core/src/main/resources/fonts/`) @@ -105,6 +108,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр | `…/wordpdf/internal/` | 7 нормализаторов + `DocxRewritePipeline` (один zip-проход правил 1–6, raw-копия неизменённых записей) + интерфейс `DocxNormalizer` + `FopFallbackFonts` + `DependencyGuard` (проверка commons-compress, шаг 0). Классы `public` (иначе родительский пакет не вызвал бы), публичные члены наружу только `normalize`/`STEP`/`declare`/`DependencyGuard.check`; `OleObjectNormalizer` — многочастный, публичный `normalize(byte[], boolean)`, бросает `DrawingFoundException(OLE)` | | `…/wordpdf/internal/chart/` | 17 классов Java2D-рендера диаграмм/SmartArt в PNG (public только `DrawingPreRenderer.run`) | | `wordpdf-core/src/main/resources/fonts/` | 30 TTF + 3 лицензии — бинарные фикстуры, часть jar | +| `wordpdf-core/src/main/resources/xslt/` | `docx2fo.xslt` — вендорный XSL-FO-стилист (копия docx4j-export-fo + AUDIT-FIX-патч), часть jar | | `wordpdf-core/src/test/resources/samples/` | 13 закоммиченных `.docx`-фикстур (единственные .docx-фикстуры), все проходят `docs/standards/validate-fixtures.py` | | `wordpdf-core/src/test/resources/geom/` | `presetShapeDefinitions.xml` — копия приложения ECMA-376, синхрон таблицы `PresetGeometry` (только в тестах, в jar не попадает) | | `wordpdf-app/src/main/java/ru/pjandro/wordpdf/app/` | REST API (10 классов): `WordPdfApplication` (единственный public), `ConvertController`, `ConversionService` (очередь), `ApiExceptionHandler`, `ApiKeyFilter`, `OpenApiConfig` (`@SecurityScheme` X-API-Key) + 4 класса исключений | @@ -198,12 +202,12 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ - Гейт `maven-pmd-plugin` 3.28.0 на `verify` для обоих модулей, ruleset `pmd-ruleset.xml`, `includeTests=true`. Версия PMD-движка в pom не пинится (тянется плагином). - Гейт JaCoCo `0.8.15`: `jacoco:check` (правило BUNDLE, LINE COVEREDRATIO `0.90` — обоих модулей; в `wordpdf-core/pom.xml` execution `check` переопределён и добавляет BRANCH COVEREDRATIO `0.85` — только для core) на `verify`; агент подключается в surefire через `argLine` = `@{argLine} -Djava.awt.headless=true` (свойство `argLine` в корневом pom по умолчанию пусто и перезаписывается `prepare-agent` — `mvn test -Djacoco.skip=true` без агента работоспособно); `report` и `check` оба на `verify`, report раньше — при провале порога отчёт уже на диске; отчёты `target/site/jacoco/` (html+xml, xml нужен CI-сводке). Плотность покрытия держат тесты, а не заглушки: промахи в основном недостижимые IOException/catch-ветки (`GlyphFont`, `BundledFonts`) и защитные ветви сканеров нормализаторов/валидатора. -- 35 тестовых классов / 535 `@Test` (core 29/493, app 6/42: ConvertController 22 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 4 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`). +- 35 тестовых классов / 538 `@Test` (core 29/496, app 6/42: ConvertController 22 + ApiKeyFilter 8 + ConversionService 5 + ApiExceptionHandler 4 + ConvertLimits 2 + ConversionTimeout 1). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true`; только `Assertions` (Mockito/AssertJ не использовать; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`), тестовые классы package-private, зеркалят main-пакеты; только `@Test` + два `@BeforeAll` (warm-up шрифтов в `GlyphCoverageNormalizerTest` и `BundledFonts.init()` в `BundledFontsTest`) + `@AfterEach drainWorker` в `ConversionTimeoutTest` (дренировать отменённый FOP-рендер до следующего класса — гонка глобального `PhysicalFonts`). - **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчик картинок (`imageCount`/`distinctImageCount` — SMask игнорируется). Негативные маркеры: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров: безразмерные отношения к эталону Word (экспорт 300 dpi, числа зашиты в тесты), допуски `assertRatio` <0.06 (`PiePainterTest`, `CartesianPainterTest`) / <0.10 (`Surface3dPainterTest`, + `assertRange` ±6 pt для центров силуэта); пороги залитых px, перцентильные коридоры яркости, «серый» px — разброс каналов `GRAY_MAX_SPREAD=25`; исключение — структурная проверка чернил в `GlyphFontTest`. Эталонные файлы — `develop/`, вне git. Хелперы chart-тестов (`render`, `countColor`, `assertRatio`, `paint`) продублированы по классам — общего test-util нет. - `GlyphFont` (fontbox): метрики пиксельно-метрически эквивалентны AWT (ascent/descent/leading/advance совпадают до 4-го знака, кернинг-дрейф 0.0000 — DejaVu Sans, Carlito). Приёмочный стенд без-fontconfig: контейнер без `libfontconfig.so.1*` и `/etc/fonts`, `mvn verify` + `java -jar` (до перехода на GlyphFont там падали `GlyphCoverageNormalizerTest` 12 / `CartesianPainterTest` 3 / `PiePainterTest` 2 / chart-тесты `WordPdfConverterTest` 4, chart-рендер молча деградировал). `GlyphFontTest` написан без единого `java.awt.Font` — обязан проходить на хосте без fontconfig. - Фикстуры — закоммиченные `samples/*.docx` (13; в тестах не генерировать; все ECMA-conformant по `docs/standards/validate-fixtures.py` — фикстура невалидна, правится фикстура, не код): core грузит classpath-ресурсом → `byte[]`, PDF для PDFBox — временный файл; app читает `/samples/…` из **test-jar core** (classifier `tests`) → `mvn -pl wordpdf-app` без `-am` не соберётся. In-memory docx — `ZipOutputStream` из литеральных XML или POI в `byte[]`. Ключевые: `too-many-pages` (150 явных разрывов → 151), `stale-cache` (кэш `1` + 110 `lastRenderedPageBreak`), `charts-smartart` (4 растра; SmartArt-одиночка = ровно 2 Image XObject), `ole-embedded` (осиротевший bin с ложным `Default bin→footer+xml` + настоящий `w:object` с честным `Override → oleObject` и VML-плейсхолдером `media/fallback.png` — ручная, генератором не перезаписывать), `chart-types` (14 графиков: 9 типов + ofPie-pie + lineChart stacked + `c:wireframe` + combo barChart+lineChart на вторичной `c:valAx` pos="r"; пересоздание — `ChartTypesDocxGenerator`). - Юниты нормализаторов работают строками (`rewrite`) + zip'ами из `ZipOutputStream`; обязательные контракты: «нечего менять → тот же массив» (`assertSame`) и неприкосновенность частей вне `word/*.xml` (`[Content_Types].xml`). Тесты бьют и в package-private API (`GlyphCoverageNormalizer.split(text, family)`, `ChartSpec.readTitle`). Исключение — `OleObjectNormalizerTest`: многочастный нормализатор без `rewrite`-хука, тесты только через `normalize` на in-memory zip. - App-тесты: `@SpringBootTest` + `@AutoConfigureMockMvc` (Boot 4: `org.springframework.boot.webmvc.test.autoconfigure`); три контекста — `ConvertControllerTest` (пустой ключ), `ApiKeyFilterTest` (`properties = "wordpdf.api-key=…"`), `ConvertLimitsTest`/`ConversionTimeoutTest` (`@TestPropertySource` — отдельные классы, не `@Nested`: `@Nested` + `@TestPropertySource` не даёт отдельного контекста). -- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight`; юниты `indCoexistLeftStartUntouched`/`tcMarCoexistKept`/`tcBordersElementsKeptTransitional`/`jcStartKeptTransitional`/`tabStartRenamedTransitional`/`transitionalCoexistReturnsOriginalArray`), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `InvisibleCharNormalizerTest`↔`invisibleChars_noEmptyLines`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `OleObjectNormalizerTest`↔`oleObjects_removedAndConverted`/`drawingErrors_errorFlagRejectsOle` (+app `errorFlagOle_rejected`/`oleObjects_removedByDefault`; юниты `objectWithImagedata_placeholderKept`/`objectWithoutImage_removed`/`objectWithDrawing_reusedVerbatim`/`controlBlockRemoved`/`sizeFromDxaOrig`/`styleUnits_allConvertToEmu`/`objectWithoutBin_stillRewritten`/`externalOleLinkRelRemoved`), `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `cachedPagesUnreadableFallsBackToZero`, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`/`validate_plainZipRejected`/`validate_xlsxRenamedRejected`/`validate_zipBombRejected`/`validate_tooManyEntriesRejected`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `PresetGeometryTest`↔`chartsSmartArt_drawingsBecomeImages` (`tableMatchesEcmaXml`), chart-пейнтеры↔`chartTypes_allTypesRenderAsImages`, `ChartSpecTest`↔автозаголовки/комбо/DoS (`hugePointIndex_rejectedNotOom`, `hugePtCount_rejectedNotOom`, `hugeCategoryIndex_rejectedNotOom`, `nonFiniteScalingBounds_dropped`, `overlayLegend_keepsPositionAndFlag`, `deletedTitleWithText_notShown`, `deletedTitleValOmitted_notShown`, `multiSeriesDoughnut_placeholderNotSeriesName`, `multiParagraphTitle_joinedWithNewlines`), `Surface3dPainterTest`↔`axisBounds_tinyMajorUnit_fallsBackToNiceUnit`/`axisBounds_zeroMajorUnit_fallsBackToNiceUnit`, `ChartRendererTest`↔`axisBounds_explicitHugeRange_reunitsToMaxTicks`/`axisBounds_infiniteSpan_fallsBackToData`/`stackedCumulative_*`/`stackedRange_coversNegativeSums`/`overlayLegend_drawnOverPlot`/`wireframeSurfaceLegend_hollowMarkers`, `DrawMlTextTest`↔`hugeWord_wrapsLinearly`/`fallbackFamilyAliasedToBundle`/`lineSpacingPct_compactsLines`, `DrawMlColorTest`↔`invalidSrgbHexFallsBackToOfficeDefault`, `SmartArtRendererTest`↔`normAutofitShrinksToFit`/`missingAutofitKeepsDeclaredSize`/`emptyTxBody_noPlaceholderInk`, `CartesianPainterTest`↔`stackedLine_seriesStackCumulatively`/`percentStackedLine_topSeriesFlatAtHundred`/`areaFill_closesToBaseline`/`combo_barsAndLineOnSecondary_bothDrawn`, `GlyphCoverageNormalizerTest`↔`multipleTextNodes_runLeftUntouched`/`nestedRunInTextBox_innerSplit`, `SymbolFontNormalizerTest`↔`nestedRunInTextBox_innerNormalized`, `WordPdfConverterTest`↔`noLoggingWarningInPdf`/`pdfTitle_comesFromParameter`/`hostileChartAxis_convertsNotHangs`/`hugeExtentChart_removedNotOom`/`chartWithoutExtent_errorFlagRejects`. App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`. +- Регрессивные пары (фикс = нормализатор/pre-renderer + юнит + конвертер-тест с фикстурой): `StrictOoxmlNormalizerTest`↔`strictOoxml_convertsNotRejected` (+`pageCount_strictBreaksCountedLightweight`; юниты `indCoexistLeftStartUntouched`/`tcMarCoexistKept`/`tcBordersElementsKeptTransitional`/`jcStartRenamedTransitional`/`tabStartRenamedTransitional`/`transitionalCoexistReturnsOriginalArray`), `DocxOnOffNormalizerTest`↔`ruPlain_regularRunsUseRegularFont`, `SymbolFontNormalizerTest`↔`symbolFonts_bulletsAreNotHash`, `FieldNormalizerTest`↔`pageNumbers_recomputedNotCached`, `InvisibleCharNormalizerTest`↔`invisibleChars_noEmptyLines`, `GlyphCoverageNormalizerTest`↔`exoticGlyphs_drawnNotHash`, `OleObjectNormalizerTest`↔`oleObjects_removedAndConverted`/`drawingErrors_errorFlagRejectsOle` (+app `errorFlagOle_rejected`/`oleObjects_removedByDefault`; юниты `objectWithImagedata_placeholderKept`/`objectWithoutImage_removed`/`objectWithDrawing_reusedVerbatim`/`controlBlockRemoved`/`sizeFromDxaOrig`/`styleUnits_allConvertToEmu`/`objectWithoutBin_stillRewritten`/`externalOleLinkRelRemoved`), `WordPdfValidatorTest`↔`staleCachePageCountRejectedBeforeRender` (+`checkPageCount_limitBoundary` 99/100/101, `cachedPagesUnreadableFallsBackToZero`, `pageCount_breaksInsideTablesAreCounted`, `pageCount_continuousSectionsNotCountedLightweight`, `validate_notAZip`/`validate_plainZipRejected`/`validate_xlsxRenamedRejected`/`validate_zipBombRejected`/`validate_tooManyEntriesRejected`), `BundledFontsTest`↔`ruPlain_emDashEmbeddedNotHelvetica`, `PresetGeometryTest`↔`chartsSmartArt_drawingsBecomeImages` (`tableMatchesEcmaXml`), chart-пейнтеры↔`chartTypes_allTypesRenderAsImages`, `ChartSpecTest`↔автозаголовки/комбо/DoS (`hugePointIndex_rejectedNotOom`, `hugePtCount_rejectedNotOom`, `hugeCategoryIndex_rejectedNotOom`, `nonFiniteScalingBounds_dropped`, `overlayLegend_keepsPositionAndFlag`, `deletedTitleWithText_notShown`, `deletedTitleValOmitted_notShown`, `multiSeriesDoughnut_placeholderNotSeriesName`, `multiParagraphTitle_joinedWithNewlines`), `Surface3dPainterTest`↔`axisBounds_tinyMajorUnit_fallsBackToNiceUnit`/`axisBounds_zeroMajorUnit_fallsBackToNiceUnit`, `ChartRendererTest`↔`axisBounds_explicitHugeRange_reunitsToMaxTicks`/`axisBounds_infiniteSpan_fallsBackToData`/`stackedCumulative_*`/`stackedRange_coversNegativeSums`/`overlayLegend_drawnOverPlot`/`wireframeSurfaceLegend_hollowMarkers`, `DrawMlTextTest`↔`hugeWord_wrapsLinearly`/`fallbackFamilyAliasedToBundle`/`lineSpacingPct_compactsLines`, `DrawMlColorTest`↔`invalidSrgbHexFallsBackToOfficeDefault`, `SmartArtRendererTest`↔`normAutofitShrinksToFit`/`missingAutofitKeepsDeclaredSize`/`emptyTxBody_noPlaceholderInk`, `CartesianPainterTest`↔`stackedLine_seriesStackCumulatively`/`percentStackedLine_topSeriesFlatAtHundred`/`areaFill_closesToBaseline`/`combo_barsAndLineOnSecondary_bothDrawn`, `GlyphCoverageNormalizerTest`↔`multipleTextNodes_runLeftUntouched`/`nestedRunInTextBox_innerSplit`, `SymbolFontNormalizerTest`↔`nestedRunInTextBox_innerNormalized`, `WordPdfConverterTest`↔`noLoggingWarningInPdf`/`pdfTitle_comesFromParameter`/`hostileChartAxis_convertsNotHangs`/`hugeExtentChart_removedNotOom`/`chartWithoutExtent_errorFlagRejects`/`jcEndTransitional_rightAligned`/`rPrPosition_raisesBaseline`/`vendoredXsltTracksJarCopy` (аудит раскладки ECMA-376). App-регрессии: `requestLimitParams_areIgnored`, `nonPositiveLimits_failStartup`, `unknownPath_notFound`, `concurrentRequests_bothSucceed`, `corruptNotAZip_rejected`, `plainZipNotDocx_rejected`, `junkInsideValidZip_conversionError` (500 на валидном .docx-контейнере с мусором), `nonDocxFilename_rejected`, `oversizedOverCoreLimit_rejected`, `drawingsAlwaysRendered`, `cyrillicAndPathInFilename_sanitizedResponseName`, `docsOpenWithoutKey`/`forwardedPrefix_healthStaysOpen`/`forwardedPrefix_docsOpenWithoutKey`, `dotSegmentOpenPrefix_rejected`, `errorFlagNotBoolean_rejected`, `methodNotSupportedReturns405`/`badContentTypeReturns415`. - UI-тестов нет; гейт SPA — `npm run build` (tsc -b) + `npm run lint` (oxlint, `.oxlintrc.json`: rules-of-hooks error, only-export-components warn). Прод-автотесты (pytest 9.1.1 + requests 2.34.2, 21 проверка — 17 под маркером `needs_key` (SKIP без ключа), 4 открытых: health/SPA-root/swagger/spec; env-конфиг, `mise exec -- python -m pytest -q .` из `prod-autotests/`) гоняются CI после deploy против живого прода. diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java index f55296b..38564ce 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/WordPdfConverter.java @@ -4,6 +4,7 @@ import org.apache.fop.apps.FOUserAgent; import org.apache.fop.apps.FopFactory; import org.apache.fop.apps.FopFactoryBuilder; import org.docx4j.Docx4J; +import org.docx4j.XmlUtils; import org.docx4j.Docx4jProperties; import org.docx4j.convert.out.FOSettings; import org.docx4j.convert.out.fo.renderers.FORendererApacheFOP; @@ -19,6 +20,9 @@ import ru.pjandro.wordpdf.internal.FopFallbackFonts; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; +import javax.xml.transform.Templates; +import javax.xml.transform.stream.StreamSource; +import java.io.InputStream; import java.io.OutputStream; import java.util.List; @@ -168,6 +172,11 @@ public final class WordPdfConverter { // семейство — декларируем его, чтобы FOP встроил подмножество FopFallbackFonts.declare(foSettings); + // 4.5 Вендорный xslt/docx2fo.xslt = копия из docx4j-export-fo + + // AUDIT-FIX-патч (w:rPr position) — стилист jar'а не + // используется. + foSettings.setCustomXsltTemplates(VendoredXslt.TEMPLATES); + // 5. Метаданные PDF: заголовок — из параметра title FopFactoryBuilder builder = FORendererApacheFOP.getFopFactoryBuilder(foSettings); FopFactory fopFactory = builder.build(); @@ -208,4 +217,26 @@ public final class WordPdfConverter { // (OleObjectNormalizer); второй проход, т.к. меняет части, а не XML bytes -> OleObjectNormalizer.normalize(bytes, options.errorOnOle())); } + + /** + * Вендорный docx2fo.xslt (копия из docx4j-export-fo + AUDIT-FIX-патч). + * {@code AbstractXsltExporterDelegate.getTemplates} кастит значение + * {@code setCustomXsltTemplates} в {@code Templates} — компилируем заранее; + * {@code Templates} неизменяем и потокобезопасен, один экземпляр на процесс. + */ + private static final class VendoredXslt { + + private static final Templates TEMPLATES = compile(); + + private static Templates compile() { + try (InputStream xslt = WordPdfConverter.class.getResourceAsStream("/xslt/docx2fo.xslt")) { + if (xslt == null) { + throw new ConversionException("Ресурс xslt/docx2fo.xslt не найден"); + } + return XmlUtils.getTransformerFactory().newTemplates(new StreamSource(xslt)); + } catch (Exception e) { + throw new ConversionException("Не удалось скомпилировать xslt/docx2fo.xslt", e); + } + } + } } diff --git a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizer.java b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizer.java index 1550b59..3a34810 100644 --- a/wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizer.java +++ b/wordpdf-core/src/main/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizer.java @@ -62,11 +62,14 @@ import java.util.zip.ZipOutputStream; * {@code w:tblCellMar} и лишь при отсутствии одноимённого {@code w:left}/ * {@code w:right}-ребёнка (transitional-схема допускает обе пары детей, * {@code maxOccurs=1} на left — дубль ломает JAXB); - *
  • значения {@code start}/{@code end} у {@code w:jc} правятся только в - * strict: transitional {@code JcEnumeration} docx4j их содержит, экспортёр - * пишет {@code fo:text-align} как есть, а FOP разрешает start/end по - * направлению абзаца (FO 1.1) — замена на left ломала RTL; значения - * {@code w:tab} правятся всегда (enum без start/end).
  • + *
  • значения {@code start}/{@code end} у {@code w:jc} правятся всегда + * (как и у {@code w:tab}): docx4j {@code Justification.setXslFO} знает только + * left/center/right/both, для start/end {@code fo:text-align} не пишет вовсе — + * {@code jc="end"} рендерился по левому краю. Замена законна: Part 4 §14.11.2 + * (left≡start, right≡end); RTL вне контура конвейера (FOP без complex-script, + * direction docx4j не выставляет — start и так рендерился как left).
  • + *
  • значения {@code start}/{@code end} у {@code w:tab} правятся всегда + * (enum без start/end).
  • * * * Регрессия — WordPdfConverterTest#strictOoxml_convertsNotRejected. @@ -104,8 +107,7 @@ public final class StrictOoxmlNormalizer { */ private static final Pattern MAR_BLOCK = Pattern.compile( "<(w:tcMar|w:tblCellMar)\\b[^>]*>.*?", Pattern.DOTALL); - - /** Значения {@code start}/{@code end} у {@code w:jc} (правятся только в strict). */ + /** Значения {@code start}/{@code end} у {@code w:jc} (правятся всегда, см. javadoc класса). */ private static final Pattern JC_VALUE = Pattern.compile( "(]*?w:val=\")(start|end)\""); @@ -182,8 +184,8 @@ public final class StrictOoxmlNormalizer { * @param renameStartEnd переименовывать ли элементы {@code w:start}/ * {@code w:end} (false для word/numbering.xml) * @param strict strict-часть (URI {@code http://purl.oclc.org}): - * глобальный рерайт элементов и значений {@code w:jc}; - * в transitional — только guard-правила + * глобальное переименование элементов {@code w:start}/ + * {@code w:end}; в transitional — только guard-правила * @return новая строка либо null, если правок не было */ static String rewrite(String xml, boolean renameStartEnd, boolean strict) { @@ -206,9 +208,7 @@ public final class StrictOoxmlNormalizer { r = renameStartEndAttrs(r); } if (r.contains("w:val=\"start\"") || r.contains("w:val=\"end\"")) { - if (strict) { - r = renameValues(r, JC_VALUE); - } + r = renameValues(r, JC_VALUE); r = renameValues(r, TAB_VALUE); } return r.equals(xml) ? null : r; diff --git a/wordpdf-core/src/main/resources/xslt/docx2fo.xslt b/wordpdf-core/src/main/resources/xslt/docx2fo.xslt new file mode 100644 index 0000000..dbe74c1 --- /dev/null +++ b/wordpdf-core/src/main/resources/xslt/docx2fo.xslt @@ -0,0 +1,1165 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TODO: handle w:pict containing other than ./v:shape/v:imagedata + + + + + + + + + + + + + + + + + + + TODO: handle w:object containing other than ./v:shape/v:imagedata + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + sectPr ignored + + + + + + + ­ + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java index e133b04..f3970f8 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/WordPdfConverterTest.java @@ -698,6 +698,94 @@ class WordPdfConverterTest { } } + /** + * w:jc val="end" в transitional-документе: docx4j Justification.setXslFO + * знает только left/center/right/both, для END {@code fo:text-align} не + * пишет вовсе — абзац рендерился по левому краю. StrictOoxmlNormalizer + * теперь переименовывает end→right всегда (Part 4 §14.11.2: right≡end). + * Регрессия — аудит раскладки (матрица J2). + */ + @Test + void jcEndTransitional_rightAligned() throws Exception { + byte[] endDocx = minimalDocx("" + + "ENDTEXT"); + byte[] rightDocx = minimalDocx("" + + "ENDTEXT"); + double end = maxRight(convertPdf(endDocx, "t")); + double right = maxRight(convertPdf(rightDocx, "t")); + assertEquals(right, end, 0.75, "jc=end должен рендериться как jc=right"); + assertTrue(right > 300, "sanity: jc=right прижимает текст к правому краю, got " + right); + } + + /** + * w:rPr/w:position=8 (полупункты, положительное поднимает; Part 4 + * §17.3.2.24): docx4j createBlockForRPr position игнорирует — вендорный + * xslt/docx2fo.xslt (AUDIT-FIX-патч) превращает его в baseline-shift. + * Регрессия — аудит раскладки (матрица R3). + */ + @Test + void rPrPosition_raisesBaseline() throws Exception { + byte[] docx = minimalDocx("" + + "P" + + "Q" + + ""); + Path pdf = convertPdf(docx, "t"); + // YDirAdj мерится от верха страницы: поднятая базовая линия — меньше + assertEquals(4.0, yOfMarker(pdf, 'P') - yOfMarker(pdf, 'Q'), 0.75, + "w:position=8 должен поднимать базовую линию на 4pt"); + } + + /** + * Дрейф-гейт: вендорный xslt/docx2fo.xslt = копия + * org/docx4j/convert/out/fo/docx2fo.xslt из docx4j-export-fo + + * AUDIT-FIX-патч (w:rPr position). При апгрейде docx4j стилист jar'а + * меняется — тест заставляет перевендорить его и перенести патч. + */ + @Test + void vendoredXsltTracksJarCopy() throws Exception { + try (InputStream jar = WordPdfConverterTest.class.getResourceAsStream( + "/org/docx4j/convert/out/fo/docx2fo.xslt")) { + assertNotNull(jar, "нет docx2fo.xslt в docx4j-export-fo"); + java.security.MessageDigest digest = + java.security.MessageDigest.getInstance("SHA-256"); + StringBuilder hex = new StringBuilder(); + for (byte b : digest.digest(jar.readAllBytes())) { + hex.append(String.format("%02x", b)); + } + assertEquals("cff420cb1bd7ad5d96211c16479db0f7d3a01fec4bf56d01d1bbc7ee4041dda7", + hex.toString(), "docx2fo.xslt в docx4j-export-fo изменился:" + + " перевендорить xslt/docx2fo.xslt и перенести AUDIT-FIX-патч"); + } + try (InputStream vendored = WordPdfConverterTest.class.getResourceAsStream( + "/xslt/docx2fo.xslt")) { + assertNotNull(vendored, "нет вендорного xslt/docx2fo.xslt"); + assertTrue(new String(vendored.readAllBytes(), StandardCharsets.UTF_8) + .contains("AUDIT-FIX position"), + "вендорный стилист потерял position-патч"); + } + } + + /** Правый край (X+ширина) самой правой глифы первой страницы. */ + private static double maxRight(Path pdf) throws IOException { + try (PDDocument doc = Loader.loadPDF(pdf.toFile())) { + double[] found = {0}; + PDFTextStripper stripper = new PDFTextStripper() { + @Override + protected void processTextPosition( + org.apache.pdfbox.text.TextPosition position) { + found[0] = Math.max(found[0], + position.getXDirAdj() + position.getWidth()); + super.processTextPosition(position); + } + }; + stripper.setStartPage(1); + stripper.setEndPage(1); + stripper.getText(doc); + assertTrue(found[0] > 0, "на странице 1 нет текста"); + return found[0]; + } + } + /** Строка из кодовых точек (невидимые литералы в исходнике нечитаемы). */ private static String invisible(int... cps) { StringBuilder sb = new StringBuilder(); diff --git a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizerTest.java b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizerTest.java index a668930..734acf4 100644 --- a/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizerTest.java +++ b/wordpdf-core/src/test/java/ru/pjandro/wordpdf/internal/StrictOoxmlNormalizerTest.java @@ -289,13 +289,16 @@ class StrictOoxmlNormalizerTest { } /** - * w:jc val="start" в transitional — JcEnumeration docx4j содержит START/END, - * FOP разрешает их по направлению (FO 1.1): рерайт ломал RTL, значение - * остаётся как есть. + * w:jc val="start" в transitional правится всегда: docx4j Justification.setXslFO + * знает только left/center/right/both, для start/end fo:text-align не пишет + * вовсе — jc="end" рендерился по левому краю (Part 4 §14.11.2: left≡start, + * right≡end; регрессия WordPdfConverterTest#jcEndTransitional_rightAligned). */ @Test - void jcStartKeptTransitional() { - assertNull(StrictOoxmlNormalizer.rewrite("", true, false)); + void jcStartRenamedTransitional() { + String r = StrictOoxmlNormalizer.rewrite("", true, false); + assertNotNull(r); + assertTrue(r.contains(""), r); } /** А w:tab val="start" правится всегда: STTabJc docx4j 17.3.2 — только left/right. */