readme.md

• Overview
• How to use?
  • Maven (pom.xml)
  • Gradle (build.gradle)
  • Include arch4u-pmd rules into your existing custom ruleset
  • Exclude particular rule
  • Reconfigure a rule
  • Exclude particular folder from inspection
• 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 7.6.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:7.6.0	❌	❌	❌
JUnitAssertionsShouldIncludeMessage	pmd-java:7.6.0	🌵	⌛	⌛
UnusedPrivateMethod	pmd-java:7.6.0	🌵	⌛	⌛
AtLeastOneConstructor	pmd-java:7.6.0	🌵	✅	⌛
OnlyOneReturn	pmd-java:7.6.0	🌵	⌛	⌛
CommentRequired	pmd-java:7.6.0	🌵	⌛	⌛
AvoidCatchingGenericException	pmd-java:7.6.0	⌛	⌛	⌛
CouplingBetweenObjects	pmd-java:7.6.0	🌵	⌛	⌛
LawOfDemeter	pmd-java:7.6.0	❌	❌	❌
LoosePackageCoupling	pmd-java:7.6.0	⌛	⌛	⌛
SignatureDeclareThrowsException	pmd-java:7.6.0	⌛	⌛	⌛
TooManyFields	pmd-java:7.6.0	🌵	⌛	⌛
TooManyMethods	pmd-java:7.6.0	🌵	⌛	⌛
UseObjectForClearerAPI	pmd-java:7.6.0	❌	❌	❌
AtLeastOneConstructor	pmd-java:7.6.0	❌	❌	❌
UseUtilityClass	pmd-java:7.6.0	🌵	✅	⌛
ShortClassName	pmd-java:7.6.0	🌵	✅	✅
ImmutableField	pmd-java:7.6.0	🌵	✅	✅
LongVariable	pmd-java:7.6.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

0. Don't forget to add rules to classpath in Maven/Gradle pmd plugin (see lines above)
1. Let's assume that you already have pmd rules defined in your-pmd-ruleset.xml
2. 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>

Exclude particular folder from inspection

<?xml version="1.0"?>
<ruleset name="pmd ruleset with your rules">
    ...
    <!-- Exclude target folder that may contain generated sources -->
    <exclude-pattern>.*/target/generated-sources/.*</exclude-pattern>
    <exclude-pattern>.*/build/generated-sources/.*</exclude-pattern>
    <!-- Exclude test folder -->
    <exclude-pattern>.*/src/test/java/org/tbd/tbd/tbd/.*</exclude-pattern>
    ...
</ruleset>

How to contribute?

1. Pull requests are welcome! Don't forget to add your name to contribution section and run this, beforehand:

   mvn -Pqulice clean install

2. Everyone interacting in this project’s codebases, issue trackers, chat rooms is expected to follow the code of conduct.
3. Latest maven coordinates here:

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

4. 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)