diff --git a/AGENTS.md b/AGENTS.md index 3ebdebd..56beb7c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -63,7 +63,7 @@ Java2D → PNG 300 dpi (`ChartRenderer.DPI = 300`, `PADDING = 4.0`, растр ## Development Commands ```bash -mvn clean verify # все модули + тесты — обязательный гейт перед push +mvn clean verify # все модули + тесты + PMD (pmd-ruleset.xml) — обязательный гейт перед push mvn -pl wordpdf-app -am package # исполняемый jar бэкенда java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar # :8080, ключ выключен curl -F "file=@doc.docx" http://localhost:8080/api/v1/convert -o doc.pdf @@ -102,6 +102,7 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ - `wordpdf-app/pom.xml` — `spring-boot-maven-plugin` с **явной** execution `repackage` (в 4.1.1 сам не связывается, jar останется тонким); `slf4j-simple` исключён; `spring-boot-starter-webmvc` (Boot 4: переименован из starter-web) + `spring-boot-starter-actuator` (нужен HEALTHCHECK контейнера `/actuator/health`); тест-зависимости: `spring-boot-webmvc-test` (в Boot 4 автоконфиг MockMvc вынесен из starter-test), test-jar core. - `wordpdf-core/pom.xml` — `maven-jar-plugin` execution `test-jar` (публикует фикстуры для app). - Корневой `pom.xml` — все версии зависимостей (в модулях версии не объявлять): docx4j `17.3.2`, slf4j `2.0.20`, JUnit `6.1.3`, PDFBox `3.0.8` (test), POI `5.5.1` (test, только генератор фикстур), Spring Boot `4.1.1` (BOM-import), springdoc `3.1.1`; pluginManagement: compiler `3.16.0`, surefire `3.6.0` с `-Djava.awt.headless=true`, jar `3.5.1`. +- Корневой `pmd-ruleset.xml` — ruleset PMD (см. Testing & QA): `category/java/codestyle.xml` минус opinionated-правила, `MethodNamingConventions` с `junit5TestPattern` под underscore-имена регрессий, `TooManyStaticImports` до 12, XPath-правило `LiteralFirstInEquals`, unused-правила из `bestpractices.xml`. - `wordpdf-core/src/main/resources/slf4j-simple.properties` — без него предупреждение лезет в PDF. - `gateway/nginx.conf` — единственный вход: `/api/`, `/swagger-ui`, `/v3/api-docs`, `/actuator` → `app:8080`, остальное → `web:80`; `client_max_body_size 100m` (без директивы upload режется HTML-413 шлюза вместо JSON-ошибки API). `wordpdf-web/nginx.conf` — чистая статика с SPA-fallback, `/api` НЕ проксирует. - `wordpdf-core/src/test/java/ru/pjandro/wordpdf/SampleDocxGenerator.java` — main()-утилита пересоздания фикстур. @@ -112,12 +113,13 @@ java -cp wordpdf-core/target/test-classes:$(cat /tmp/cp.txt) \ - Java 21 + Maven (обязательны; wrapper `mvnw` нет); UTF-8. Только Maven — никакого Gradle/Ant. - Версии зависимостей — только в корневом `pom.xml` (properties + dependencyManagement); новые зависимости — latest stable. - Фронт: Node `^20.19.0 || >=22.12.0` (engines vite/oxlint из lockfile), npm с закоммиченным `package-lock.json` (`npm ci`); vite `^8.3.0`, React `^19.2`, TS `~6.0` (**`strict` нигде не включён** — `npm run build` не является strict-гейтом), Tailwind `^4.3`, oxlint `^1.81`; podman-сборка web на `node:24-alpine`. -- CI, линтеров, форматтеров, checkstyle для Java — нет; проверка одна: `mvn clean verify`. +- CI, форматтеров, checkstyle для Java — нет; статический линтер — PMD на `verify` (см. Testing & QA); проверка одна: `mvn clean verify`. - Исполняемый jar бэкенда проверять только `java -jar` (тесты идут по classpath и repackage-специфику не видят; `BundledFontsTest#listedFilesCoverAllTtfInResources` требует `file:`-протокол classpath — только surefire, не fat-jar). - Git: origin `git.pjandro.ru:pjandro/java-word-pdf`, `main`/`dev` защищены (правила глобального AGENTS.md; локально только `main`, `dev` нет; на origin висит остаточная смерженная `docs/regenerate-agents-md`). ## Testing & QA +- Гейт `maven-pmd-plugin` 3.28.0 (PMD 7.17) на `verify` для обоих модулей, ruleset `pmd-ruleset.xml` (codestyle без opinionated-правил + unused-правила + XPath `LiteralFirstInEquals` — строковый литерал слева в `equals`/`equalsIgnoreCase`; `junit5TestPattern` разрешает underscore-имена регрессий; `includeTests=true` — тесты сканируются). - 14 тестовых классов / 132 `@Test` (core 11/107, app 3/25). JUnit 6 (`org.junit.jupiter:junit-jupiter`), surefire 3.6.0 с `-Djava.awt.headless=true` в argLine; только `Assertions` (Mockito/AssertJ не использовать, несмотря на test-classpath Boot; в app-тестах допустим inline-Hamcrest `org.hamcrest.Matchers.containsString` в `andExpect`); тестовые классы package-private, зеркалят main-пакеты; только `@Test` (+ единственный `@BeforeAll` — warm-up шрифтов в `GlyphCoverageNormalizerTest`). - **PDF сравнивается текстом, не растеризацией**: PDFBox 3 (`Loader.loadPDF`) — `PDFTextStripper` для текста (пер-странично `setStartPage/setEndPage`), override `processTextPosition` для шрифта конкретного символа (`fontNameOf`), обход ресурсов страниц для встроенных шрифтов (`EAAAAA+Carlito-Bold`) и счётчика картинок (`imageCount`). Негативные маркеры — регрессии: `assertFalse(text.contains("#"))` (.notdef), `assertFalse(font.startsWith("Helvetica"))`. Текст нормализуется по пробелам (`norm`); в `tableImage_tableAndImage` — полное удаление пробелов (docx4j переносит слова в auto-fit таблицах). - Пиксели (BufferedImage) — только в unit-тестах chart-пейнтеров, допуски 6–10% против эталона Word (`PiePainterTest` аспект h/w=0.585, `assertRatio` отклонение <0.06; `Surface3dPainterTest` `assertRange` ±6 pt для центров силуэта + `assertRatio` допуск 0.10 для геометрических отношений; shading — не допуск, а перцентильные коридоры яркости p5∈[0.74,0.90], median∈[0.90,1.10], p95∈[1.02,1.20]). diff --git a/pmd-ruleset.xml b/pmd-ruleset.xml new file mode 100644 index 0000000..544de9b --- /dev/null +++ b/pmd-ruleset.xml @@ -0,0 +1,66 @@ + + + Код-стиль java-word-pdf: codestyle без opinionated-правил + unused-правила + NPE-safe equals + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + 3 + + + + + + + + + + + + + diff --git a/pom.xml b/pom.xml index 5f90257..856c635 100644 --- a/pom.xml +++ b/pom.xml @@ -116,6 +116,28 @@ maven-jar-plugin 3.5.1 + + org.apache.maven.plugins + maven-pmd-plugin + 3.28.0 + + + ${maven.multiModuleProjectDirectory}/pmd-ruleset.xml + + true + true + false + + + + pmd-check + verify + + check + + + + org.springframework.boot spring-boot-maven-plugin @@ -123,5 +145,12 @@ + + + + org.apache.maven.plugins + maven-pmd-plugin + +