arch4u-pmd: A Java repository from dykov

Overview
How to use?
How to contribute?
Contributors

Overview

arch4u-pmd is a library with pmd rules that bring new regulations related to known problems in REST API, logging, monitoring, etc., including reconfigured default pmd rules to decrease false-positive violations during usage of well-known frameworks like Spring, Quarkus, etc.

In addition to our custom/reconfigured rules we are using the latest stable pmd-java version which is 6.42.0 with more than 320+ rules with default configuration.

Legend

✅ included in arch4u-ruleset.xml
⌛ planned for review considering framework(s) architecture
🌵 temporary disabled or reconfigured in arch4u-ruleset.xml
❌ disabled/not planned in arch4u-ruleset.xml

PMD rule	Provider	Status	Spring	Quarkus
UseExistingMediaTypeConstant	`arch4u-pmd:0.1.0`	✅	✅	⌛
UseOpenApiInRestEndpoints	`arch4u-pmd:0.1.0`	✅	✅	⌛
RestEndpointsWithoutExposedMetrics	`arch4u-pmd:0.1.0`	✅	✅	⌛
UseConstantAsMetricName	`arch4u-pmd:0.1.0`	✅	✅	⌛
NoMandatoryConstructorInExceptionClass	`arch4u-pmd:0.1.0`	✅	✅	⌛
AvoidUsingObjectMapperAsALocalVariable	`arch4u-pmd:0.1.0`	✅	✅	⌛
AvoidMdcOutsideTryStatement	`arch4u-pmd:0.1.0`	✅	✅	⌛
PotentiallyThreadLocalPollutionByMdc	`arch4u-pmd:0.1.0`	✅	✅	⌛
GuardLogStatement	`pmd-java:6.42.0`	❌	⌛	⌛
JUnitAssertionsShouldIncludeMessage	`pmd-java:6.42.0`	🌵	⌛	⌛
UnusedPrivateMethod	`pmd-java:6.42.0`	🌵	⌛	⌛
AtLeastOneConstructor	`pmd-java:6.42.0`	🌵	✅	⌛
OnlyOneReturn	`pmd-java:6.42.0`	🌵	⌛	⌛
CommentRequired	`pmd-java:6.42.0`	🌵	⌛	⌛
AvoidCatchingGenericException	`pmd-java:6.42.0`	⌛	⌛	⌛
CouplingBetweenObjects	`pmd-java:6.42.0`	🌵	⌛	⌛
LawOfDemeter	`pmd-java:6.42.0`	❌	⌛	⌛
LoosePackageCoupling	`pmd-java:6.42.0`	⌛	⌛	⌛
SignatureDeclareThrowsException	`pmd-java:6.42.0`	⌛	⌛	⌛
TooManyFields	`pmd-java:6.42.0`	🌵	⌛	⌛
TooManyMethods	`pmd-java:6.42.0`	🌵	⌛	⌛
UseObjectForClearerAPI	`pmd-java:6.42.0`	❌	⌛	⌛

How to use?

Maven (pom.xml)

...
<build>
 <plugins>
   ...
   <plugin>
     <groupId>org.apache.maven.plugins</groupId>
     <artifactId>maven-pmd-plugin</artifactId>
     <version>3.15.0</version>
     <executions>
       <execution>
         <phase>test</phase>
         <goals>
           <goal>check</goal>
         </goals>
       </execution>
     </executions>
     <configuration>
       <printFailingErrors>true</printFailingErrors>
       <rulesets>
         ...
         <ruleset>io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml</ruleset>
         ...
       </rulesets>
       <excludeRoots>
         <excludeRoot>target/generated-sources/</excludeRoot>
       </excludeRoots>
     </configuration>
     <dependencies>
       <!-- Latest arch4u-rules -->
       <dependency>
         <groupId>io.github.dgroup</groupId>
         <artifactId>arch4u-pmd</artifactId>
         <version>${version}</version>
       </dependency>
     </dependencies>
   </plugin>
   ...
 </plugins>
</build>
 ...

Gradle (build.gradle)

apply plugin: 'pmd'

dependencies {
   ...
   pmd "io.github.dgroup:arch4u-pmd:${version}"    // use latest arch4u-pmd rules version
   pmd "commons-io:commons-io:2.11.0"              // required dependency by pmd engine
   ...
}

pmd {
   consoleOutput = true
   ruleSetFiles = files("io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml")
   ruleSets = []                                   // Keep it as is, workaround for pmd
}

Include arch4u-pmd rules into your existing custom ruleset

Don't forget to add rules to classpath in Maven/Gradle pmd plugin (see lines above)
Let's assume that you already have pmd rules defined in your-pmd-ruleset.xml

Add line <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml"/> to your-pmd-ruleset.xml

<?xml version="1.0"?>
<ruleset name="pmd ruleset with your rules"
  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">
 
  ...
  <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml"/>
  ...

</ruleset>

Exclude particular rule

<?xml version="1.0"?>
<ruleset name="pmd ruleset with your rules">
  ...
  <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml">
    <exclude name="UseExistingMediaTypeConstant"/>
  </rule>
  ...
</ruleset>

Reconfigure a rule

<?xml version="1.0"?>
<ruleset name="pmd ruleset with your rules">
  ...
  <!-- 1. Exclude rule with default configuration  -->
  <rule ref="io/github/dgroup/arch4u/pmd/arch4u-ruleset.xml">
    <exclude name="UseExistingMediaTypeConstant"/>
  </rule>
  <!-- 2. Reconfigure rule with expected property -->
  <rule name="UseExistingMediaTypeConstant"
        language="java"
        externalInfoUrl="https://github.com/dgroup/arch4u-pmd/discussions/43"
        message="Use existing MediaType constant instead of string literal: https://github.com/dgroup/arch4u-pmd/discussions/43"
        class="io.github.dgroup.arch4u.pmd.UseExistingConstant">
    <priority>3</priority>
    <properties>
      <!-- 3. Set the 'regexPattern' considering your needs -->
      <property name="regexPattern" description="Regular expression of prohibited string"
                value="(^|\s)(application\/(json|xml|atom\+xml|x-www-form-urlencoded|octet-stream|svg\+xml|xhtml\+xml)|(multipart\/form-data)|(text\/(html|xml|plain)))(\s|$)"/>
    </properties>
  </rule>
  ...
</ruleset>

How to contribute?

Pull requests are welcome! Don't forget to add your name to contribution section and run this, beforehand:
```
mvn -Pqulice clean install
```
Everyone interacting in this project’s codebases, issue trackers, chat rooms is expected to follow the code of conduct.

Latest maven coordinates here:

<dependency>
    <groupId>io.github.dgroup</groupId>
    <artifactId>arch4u-pmd</artifactId>
    <version>${version}</version>
</dependency>

Download pmd rule designer
- https://pmd.github.io/latest/pmd_userdocs_extending_designer_reference.html

Contributors

dgroup as Yurii Dubinka (yurii.dubinka@gmail.com)
dykov as Oleksii Dykov (dykovoleksii@gmail.com)
smithros as Rostyslav Koval (kovalr2000@gmail.com)

dykov/arch4u-pmd