Improving 110-java-maven-best-practices

Author: jabrena

.cursor/rules/110-java-maven-best-practices.mdc

@@ -94,7 +94,7 @@ Description: Use the `<dependencyManagement>` section in parent POMs or import B
 </project>
 ```
 
-**Bad Example:**
+**Bad example:**
 
 ```xml
 <!-- Child POM hardcoding versions -->
@@ -127,7 +127,7 @@ Description: Follow Maven's convention for directory structure (`src/main/java`,
 
 **Good example:**
 
-```
+```text
 my-app/
 ├── pom.xml
 └── src/
@@ -141,11 +141,12 @@ my-app/
         │   └── com/example/myapp/AppTest.java
         └── resources/
             └── test-data.xml
+
 ```
 
-**Bad Example:**
+**Bad example:**
 
-```
+```text
 my-app/
 ├── pom.xml
 ├── sources/  <!-- Non-standard -->
@@ -155,6 +156,7 @@ my-app/
 └── tests/    <!-- Non-standard -->
     └── com/example/myapp/AppTest.java
 <!-- This would require explicit configuration in pom.xml to specify source/resource directories -->
+
 ```
 
 ## Rule 3: Plugin Management and Configuration
@@ -200,7 +202,7 @@ Description: Use `<pluginManagement>` in a parent POM to define plugin versions
 </project>
 ```
 
-**Bad Example:**
+**Bad example:**
 
 ```xml
 <!-- Child POM -->
@@ -272,9 +274,10 @@ Description: Use Maven profiles to customize build settings for different enviro
   </profiles>
 </project>
 <!-- Activation: mvn clean install -P prod -->
+
 ```
 
-**Bad Example:**
+**Bad example:**
 
 ```xml
 <!-- Commented out sections for different environments -->
@@ -346,7 +349,7 @@ Description: Organize your `pom.xml` sections in a consistent order (e.g., proje
 </project>
 ```
 
-**Bad Example:**
+**Bad example:**
 
 ```xml
 <!-- Haphazard order, missing properties for versions -->
@@ -397,7 +400,7 @@ Description: Prefer dependencies from Maven Central. If custom repositories are
 <!-- Better: Configure these in settings.xml and use a repository manager -->
 ```
 
-**Bad Example:**
+**Bad example:**
 
 ```xml
 <!-- No explicit repository for a non-central artifact, relying on developer's local settings or transitive ones -->
@@ -436,22 +439,22 @@ Description: Define all dependency and plugin versions in the `<properties>` sec
     <maven.version>3.9.10</maven.version>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
-    
+
     <!-- Dependency versions -->
     <jackson.version>2.15.3</jackson.version>
     <junit.version>5.10.1</junit.version>
     <mockito.version>5.7.0</mockito.version>
     <logback.version>1.4.11</logback.version>
-    
+
     <!-- Maven plugin versions -->
     <maven-plugin-compiler.version>3.14.0</maven-plugin-compiler.version>
     <maven-plugin-surefire.version>3.5.3</maven-plugin-surefire.version>
     <maven-plugin-failsafe.version>3.5.3</maven-plugin-failsafe.version>
     <maven-plugin-enforcer.version>3.5.0</maven-plugin-enforcer.version>
-    
+
     <!-- Third-party plugin versions -->
     <maven-plugin-jacoco.version>0.8.13</maven-plugin-jacoco.version>
-    
+
     <!-- Quality thresholds -->
     <coverage.level>80</coverage.level>
     <mutation.level>70</mutation.level>
@@ -503,7 +506,7 @@ Description: Define all dependency and plugin versions in the `<properties>` sec
 </project>
 ```
 
-**Bad Example:**
+**Bad example:**
 
 ```xml
 <!-- Hardcoded versions scattered throughout the POM -->

spml/pom.xml

@@ -230,6 +230,7 @@
                   <directory>${project.basedir}/src/test/resources</directory>
                   <includes>
                     <include>100-java-checklist-guide.mdc</include>
+                    <include>110-java-maven-best-practices.mdc</include>
                   </includes>
                 </resource>
               </resources>

spml/src/main/resources/110-java-maven-best-practices.xml

@@ -23,7 +23,9 @@
     </system-characterization>
 
     <description>
-        Effective Maven usage involves robust dependency management via `&lt;dependencyManagement&gt;` and BOMs, adherence to the standard directory layout, and centralized plugin management. Build profiles should be used for environment-specific configurations. POMs must be kept readable and maintainable with logical structure and properties for versions. Custom repositories should be declared explicitly and their use minimized, preferably managed via a central repository manager.
+        <![CDATA[
+        Effective Maven usage involves robust dependency management via `<dependencyManagement>` and BOMs, adherence to the standard directory layout, and centralized plugin management. Build profiles should be used for environment-specific configurations. POMs must be kept readable and maintainable with logical structure and properties for versions. Custom repositories should be declared explicitly and their use minimized, preferably managed via a central repository manager.
+        ]]>
     </description>
 
     <toc auto-generate="true"/>
@@ -35,7 +37,9 @@
                 <rule-subtitle>Manage Dependencies Effectively using `dependencyManagement` and BOMs</rule-subtitle>
             </rule-header>
             <rule-description>
-                Use the `&lt;dependencyManagement&gt;` section in parent POMs or import Bill of Materials (BOMs) to centralize and control dependency versions. This helps avoid version conflicts and ensures consistency across multi-module projects. Avoid hardcoding versions directly in `&lt;dependencies&gt;` when managed elsewhere.
+                <![CDATA[
+                Use the `<dependencyManagement>` section in parent POMs or import Bill of Materials (BOMs) to centralize and control dependency versions. This helps avoid version conflicts and ensures consistency across multi-module projects. Avoid hardcoding versions directly in `<dependencies>` when managed elsewhere.
+                ]]>
             </rule-description>
             <code-examples>
                 <good-example>
@@ -133,11 +137,12 @@
                 <rule-subtitle>Adhere to the Standard Directory Layout</rule-subtitle>
             </rule-header>
             <rule-description>
-                Follow Maven's convention for directory structure (`src/main/java`, `src/main/resources`, `src/test/java`, `src/test/resources`, etc.). This makes projects easier to understand and build, as Maven relies on these defaults.
+                <![CDATA[Follow Maven's convention for directory structure (`src/main/java`, `src/main/resources`, `src/test/java`, `src/test/resources`, etc.). This makes projects easier to understand and build, as Maven relies on these defaults.]]>
             </rule-description>
             <code-examples>
                 <good-example>
-                    <code-block>my-app/
+                    <code-block language="text"><![CDATA[
+my-app/
 ├── pom.xml
 └── src/
     ├── main/
@@ -149,18 +154,21 @@
         ├── java/
         │   └── com/example/myapp/AppTest.java
         └── resources/
-            └── test-data.xml</code-block>
+            └── test-data.xml
+                   ]]></code-block>
                 </good-example>
                 <bad-example>
-                    <code-block>my-app/
+                    <code-block language="text"><![CDATA[
+my-app/
 ├── pom.xml
-├── sources/  &lt;!-- Non-standard --&gt;
+├── sources/  <!-- Non-standard -->
 │   └── com/example/myapp/App.java
-├── res/      &lt;!-- Non-standard --&gt;
+├── res/      <!-- Non-standard -->
 │   └── config.properties
-└── tests/    &lt;!-- Non-standard --&gt;
+└── tests/    <!-- Non-standard -->
     └── com/example/myapp/AppTest.java
-&lt;!-- This would require explicit configuration in pom.xml to specify source/resource directories --&gt;</code-block>
+<!-- This would require explicit configuration in pom.xml to specify source/resource directories -->
+                    ]]></code-block>
                 </bad-example>
             </code-examples>
         </rule-section>
@@ -171,7 +179,7 @@
                 <rule-subtitle>Manage Plugin Versions and Configurations Centrally</rule-subtitle>
             </rule-header>
             <rule-description>
-                Use `&lt;pluginManagement&gt;` in a parent POM to define plugin versions and common configurations. Child POMs can then use the plugins without specifying versions, ensuring consistency. Override configurations in child POMs only when necessary.
+                <![CDATA[Use `<pluginManagement>` in a parent POM to define plugin versions and common configurations. Child POMs can then use the plugins without specifying versions, ensuring consistency. Override configurations in child POMs only when necessary.]]>
             </rule-description>
             <code-examples>
                 <good-example>
@@ -237,7 +245,7 @@
                 <rule-subtitle>Employ Build Profiles for Environment-Specific Settings</rule-subtitle>
             </rule-header>
             <rule-description>
-                Use Maven profiles to customize build settings for different environments (e.g., dev, test, prod) or other conditional scenarios. This can include different dependencies, plugin configurations, or properties. Activate profiles via command line, OS, JDK, or file presence.
+                <![CDATA[Use Maven profiles to customize build settings for different environments (e.g., dev, test, prod) or other conditional scenarios. This can include different dependencies, plugin configurations, or properties. Activate profiles via command line, OS, JDK, or file presence.]]>
             </rule-description>
             <code-examples>
                 <good-example>
@@ -306,7 +314,7 @@
                 <rule-subtitle>Structure POMs Logically for Readability</rule-subtitle>
             </rule-header>
             <rule-description>
-                Organize your `pom.xml` sections in a consistent order (e.g., project coordinates, parent, properties, dependencyManagement, dependencies, build, profiles, repositories). Use properties for recurring versions or values. Add comments for complex configurations.
+                <![CDATA[Organize your `pom.xml` sections in a consistent order (e.g., project coordinates, parent, properties, dependencyManagement, dependencies, build, profiles, repositories). Use properties for recurring versions or values. Add comments for complex configurations.]]>
             </rule-description>
             <code-examples>
                 <good-example>
@@ -393,7 +401,7 @@
                 <rule-subtitle>Declare Custom Repositories Explicitly and Minimize Their Use</rule-subtitle>
             </rule-header>
             <rule-description>
-                Prefer dependencies from Maven Central. If custom repositories are necessary, declare them in the `&lt;repositories&gt;` section and `&lt;pluginRepositories&gt;` for plugins. It's often better to manage these in a company-wide Nexus/Artifactory instance configured in `settings.xml` rather than per-project POMs. Avoid relying on transitive repositories.
+                <![CDATA[Prefer dependencies from Maven Central. If custom repositories are necessary, declare them in the `<repositories>` section and `<pluginRepositories>` for plugins. It's often better to manage these in a company-wide Nexus/Artifactory instance configured in `settings.xml` rather than per-project POMs. Avoid relying on transitive repositories.]]>
             </rule-description>
             <code-examples>
                 <good-example>
@@ -441,7 +449,7 @@
                 <rule-subtitle>Use Properties to Manage Dependency and Plugin Versions</rule-subtitle>
             </rule-header>
             <rule-description>
-                Define all dependency and plugin versions in the `&lt;properties&gt;` section rather than hardcoding them throughout the POM. This centralizes version management, makes updates easier, reduces duplication, and helps maintain consistency across related dependencies. Use consistent property naming conventions: `maven-plugin-[name].version` for Maven plugins, simple names like `[library].version` for dependencies, and descriptive names for quality thresholds like `coverage.level`.
+                <![CDATA[Define all dependency and plugin versions in the `<properties>` section rather than hardcoding them throughout the POM. This centralizes version management, makes updates easier, reduces duplication, and helps maintain consistency across related dependencies. Use consistent property naming conventions: `maven-plugin-[name].version` for Maven plugins, simple names like `[library].version` for dependencies, and descriptive names for quality thresholds like `coverage.level`.]]>
             </rule-description>
             <code-examples>
                 <good-example>

spml/src/test/java/info/jab/xml/CursorRuleGeneratorTest.java

@@ -347,7 +347,7 @@ void should_produceConsistentStructure_when_processingDifferentXmlTypes() throws
 
         // Save all for comparison
         saveGeneratedContentToTarget(checklistGuideResult, "100-java-checklist-guide.mdc");
-        //saveGeneratedContentToTarget(bestPracticesResult, "unified-best-practices.mdc");
+        saveGeneratedContentToTarget(bestPracticesResult, "110-java-maven-best-practices.mdc");
         //saveGeneratedContentToTarget(documentationResult, "unified-documentation.mdc");
         //saveGeneratedContentToTarget(objectOrientedDesignResult, "unified-object-oriented-design.mdc");
         //saveGeneratedContentToTarget(typeDesignResult, "unified-type-design.mdc");

spml/src/test/resources/110-java-maven-best-practices.mdc

@@ -127,7 +127,7 @@ Description: Follow Maven's convention for directory structure (`src/main/java`,
 
 **Good example:**
 
-```
+```text
 my-app/
 ├── pom.xml
 └── src/
@@ -141,11 +141,12 @@ my-app/
         │   └── com/example/myapp/AppTest.java
         └── resources/
             └── test-data.xml
+
 ```
 
 **Bad example:**
 
-```
+```text
 my-app/
 ├── pom.xml
 ├── sources/  <!-- Non-standard -->
@@ -155,6 +156,7 @@ my-app/
 └── tests/    <!-- Non-standard -->
     └── com/example/myapp/AppTest.java
 <!-- This would require explicit configuration in pom.xml to specify source/resource directories -->
+
 ```
 
 ## Rule 3: Plugin Management and Configuration