new-rule

# New Rule Implementation Skill This skill provides sonar-java-specific guidelines for implementing new rules. ## What to Do ### Metadata Files - **DO** generate rule metadata using rule-api tool from the RSPEC repository: - Ensure your local rspec repository is up-to-date with the rule branch - Use rule-api jar (check Maven local repository for available versions) - Command: `java -jar <rule-api.jar> generate -branch rule/add-RSPEC-S{RULE_ID} -rule S{RULE_ID}` - This generates HTML and JSON files and updates the Sonar way profile automatically - Generated files will be placed in: - `sonar-java-plugin/src/main/resources/org/sonar/l10n/java/rules/java/S{RULE_ID}.html` - `sonar-java-plugin/src/main/resources/org/sonar/l10n/java/rules/java/S{RULE_ID}.json` - `sonar-java-plugin/src/main/resources/profiles/{Sonar_way|Sonar_agentic_AI}/S{RULE_ID}` ### Tests Ruling test expectation files, located in `its/ruling/src/test/resources`, are updated by merging an automatically generated PR into the branch when CI checks fail. ### MethodMatchers Use `MethodMatchers` to match method calls by type, name, and signature: ```java private static final MethodMatchers MY_MATCHER = MethodMatchers.create() .ofTypes("java.util.List") .names("add") .withAnyParameters() .build(); // In visitNode: if (MY_MATCHER.matches(methodInvocationTree)) { reportIssue(methodInvocationTree, "Message."); } ``` ### External Dependencies in Tests - **DO NOT** add external library dependencies for test samples - **DO** create mock-ups or use non-compiling tests when external libraries are needed - **SEE** Spring examples in `java-checks-test-sources/*/src/main/files/non-compiling/checks/` ## What NOT to Do ### 1. Version Control - **DO NOT** commit log files (e.g., `*.log`, build logs) - **DO NOT** commit temporary or generated files ### 2. Build Configuration - **DO NOT** modify `pom.xml` files - Build configuration is managed centrally - Only modify if explicitly required by the rule implementation ### 3. Architecture - **DO NOT** make architectural changes to the codebase - New rules should fit within the existing architecture - Follow the patterns used by similar existing rules ### 4. Test Dependencies - **DO NOT** add real external dependencies to test projects - Use mocks, stubs, or non-compiling tests instead - Keep test projects lightweight and self-contained ## File Structure Reference ### Rule Implementation - Rule class: `java-checks/src/main/java/org/sonar/java/checks/{RuleId}Check.java` - Test class: `java-checks/src/test/java/org/sonar/java/checks/{RuleId}CheckTest.java` - Test samples: `java-checks-test-sources/default/src/main/java/checks/{RuleId}CheckSample.java` ### Metadata - HTML description: `sonar-java-plugin/src/main/resources/org/sonar/l10n/java/rules/java/{RULE_ID}.html` - JSON metadata: `sonar-java-plugin/src/main/resources/org/sonar/l10n/java/rules/java/{RULE_ID}.json` - Profile: `sonar-java-plugin/src/main/resources/profiles/{Sonar_way|Sonar_agentic_AI}/S{RULE_ID}` ### Non-Compiling Tests (when needed) - Location: `java-checks-test-sources/default/src/main/files/non-compiling/checks/` - Use for: Code that requires external libraries (Spring, AWS SDK, etc.)