PMD codestyle на verify + исправление всех предупреждений #13

Merged
pjandro merged 2 commits from chore/pmd-codestyle into main 2026-10-20 01:56:22 +03:00
3 changed files with 99 additions and 2 deletions
Showing only changes of commit bcfabfb0e9 - Show all commits
+4 -2
View File
@@ -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]).
+66
View File
@@ -0,0 +1,66 @@
<?xml version="1.0"?>
<ruleset name="WordPDF code style" xmlns="http://pmd.sourceforge.net/ruleset/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 https://pmd.sourceforge.io/ruleset_2_0_0.xsd">
<description>Код-стиль java-word-pdf: codestyle без opinionated-правил + unused-правила + NPE-safe equals</description>
<rule ref="category/java/codestyle.xml">
<!-- opinionated/шумные, намеренно выключены -->
<exclude name="AtLeastOneConstructor"/>
<exclude name="CallSuperInConstructor"/>
<exclude name="CommentDefaultAccessModifier"/>
<exclude name="ConfusingTernary"/>
<exclude name="FieldDeclarationsShouldBeAtStartOfClass"/>
<exclude name="LocalVariableCouldBeFinal"/>
<exclude name="LongVariable"/>
<exclude name="MethodArgumentCouldBeFinal"/>
<exclude name="OnlyOneReturn"/>
<exclude name="PrematureDeclaration"/>
<exclude name="ShortMethodName"/>
<exclude name="ShortVariable"/>
<exclude name="UseExplicitTypes"/>
<exclude name="UseUnderscoresInNumericLiterals"/>
<!-- переопределены ниже -->
<exclude name="MethodNamingConventions"/>
<exclude name="TooManyStaticImports"/>
</rule>
<!-- регрессионные тесты репо именуются объект_условие (AGENTS.md) -->
<rule ref="category/java/codestyle.xml/MethodNamingConventions">
<properties>
<property name="junit5TestPattern" value="^[a-z][a-zA-Z0-9]*(_[a-zA-Z0-9]+)*$"/>
</properties>
</rule>
<!-- MockMvc-тесты: >4 статических импортов — норма -->
<rule ref="category/java/codestyle.xml/TooManyStaticImports">
<properties>
<property name="maximumStaticImports" value="12"/>
</properties>
</rule>
<!-- PMD 7 удалил EqualsAvoidsNull; NPE-safe порядок операндов: литерал слева -->
<rule name="LiteralFirstInEquals" language="java"
message="NPE-safe сравнение строк: строковый литерал должен стоять слева: &quot;lit&quot;.equals(x)"
class="net.sourceforge.pmd.lang.rule.xpath.XPathRule">
<priority>3</priority>
<properties>
<property name="xpath">
<value><![CDATA[
//MethodCall[
(@MethodName = 'equals' or @MethodName = 'equalsIgnoreCase')
and ArgumentList/StringLiteral
and not(*[1][self::StringLiteral
or (self::VariableAccess and @CompileTimeConstant = true())])
]
]]></value>
</property>
</properties>
</rule>
<rule ref="category/java/bestpractices.xml/UnusedAssignment"/>
<rule ref="category/java/bestpractices.xml/UnusedFormalParameter"/>
<rule ref="category/java/bestpractices.xml/UnusedLocalVariable"/>
<rule ref="category/java/bestpractices.xml/UnusedPrivateField"/>
<rule ref="category/java/bestpractices.xml/UnusedPrivateMethod"/>
</ruleset>
+29
View File
@@ -116,6 +116,28 @@
<artifactId>maven-jar-plugin</artifactId>
<version>3.5.1</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>3.28.0</version>
<configuration>
<rulesets>
<ruleset>${maven.multiModuleProjectDirectory}/pmd-ruleset.xml</ruleset>
</rulesets>
<includeTests>true</includeTests>
<printFailingErrors>true</printFailingErrors>
<linkXRef>false</linkXRef>
</configuration>
<executions>
<execution>
<id>pmd-check</id>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
@@ -123,5 +145,12 @@
</plugin>
</plugins>
</pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>