Eliteforge Sonar Pmd Generator

Sonar PMD Generator (Spec-driven, End-to-end)

Overview

This skill converts coding standard documents into enforceable PMD rules and validates them through a real SonarQube server workflow. Completion requires an end-to-end chain: spec parsing, L1/L2/L3/L4 classification, PMD ruleset generation for L1-L2, automation planning for L3, review planning for L4, custom sonar-pmd plugin packaging, Docker Sonar startup, test project scan, and server-side verification.

Environment Variables

• ELITEFORGE_SKILL_SONAR_PMD_HOST [optional] SonarQube base URL for reference command snippets; script arguments may override it.
• ELITEFORGE_SKILL_SONAR_PMD_TOKEN [optional] SonarQube API token for local validation snippets; never print the value.
• ELITEFORGE_SKILL_SONAR_PMD_PROJECT_KEY [optional] Sonar project key used by API evidence snippets.
• ELITEFORGE_SKILL_SONAR_PMD_PLUGIN_KEY [optional] Custom Sonar plugin key used by API evidence snippets.
• ELITEFORGE_SKILL_SONAR_PMD_RULE_REPO_KEY [optional] Custom rule repository key used by API evidence snippets.
• ELITEFORGE_SKILL_SONAR_PMD_PROFILE_KEY [optional] Quality profile key used by API evidence snippets.

Progressive Loading

• Read references/workflow-playbook.md first for the full execution order.
• Read references/plugin-packaging-blueprint.md when implementing or debugging plugin modules.
• Read references/docker-sonar-validation.md when starting Sonar in Docker and running test scans.
• Read references/sonar-api-evidence-checklist.md when collecting validation evidence.
• Use scripts/verify_sonar_plugin.sh for quick API-based smoke verification after scan.

Trigger Conditions

Use this skill when the request includes one or more of these intents:

• Convert coding specifications into PMD rules.
• Auto-classify specification clauses into L1/L2/L3/L4.
• Build or extend a custom Sonar PMD plugin/profile.
• Validate PMD plugin behavior in SonarQube using Docker and real scans.
• Prove custom rules are visible and producing issues in Sonar.

Required Inputs

• One or more specification file paths.
• Target language(s) for each specification.
• Plugin workspace path (or permission to scaffold one).
• Test project path (or permission to scaffold one).
• Optional output directory for generated artifacts (default: pmd-governance/).
• Optional profile name (default: custom-spec-profile).

Classification Contract (MUST follow)

• L1: can be covered by PMD built-in rule(s) for the target language.
• L2: can be expressed with PMD AST XPath rule(s) for the target language.
• L3: cannot or should not be expressed in PMD, but can be detected reliably by other automation tools such as formatter, hook, CI job, Checkstyle, Semgrep, ArchUnit, or build plugins.
• L4: requires human review or AI review because the rule depends on business semantics, architectural intent, or unstable heuristics.
• Never force L3 or L4 into fragile PMD XPath implementations.

For each spec statement, record:

• SPEC-ID
• original statement
• target language
• level (L1/L2/L3/L4)
• detection target
• trigger condition
• exception condition
• severity
• primary tool
• execution stage
• implementation plan
• reviewer note (mandatory for L4)

End-to-end Workflow (REQUIRED)

1. Parse specification statements and assign IDs (SPEC-<LANG>-001, ...). 2. Auto-classify every statement into L1/L2/L3/L4. 3. Generate governance artifacts:

• mapping/spec-to-governance.csv
• rulesets/custom-<lang>-ruleset.xml
• automation/l3-tooling-plan.md
• manual-review/l4-review-checklist.md
• README.md

4. Build a custom PMD rules module from L1-L2 only:

• include L1 mapped refs and L2 custom XPath/Java rules
• rule keys/messages must include traceability to SPEC-ID

5. Build an automation plan for L3:

• select the smallest stable tool that can enforce the rule
• prefer formatter or build plugin over custom scripts when possible
• specify whether it runs in pre-commit, CI, build, or MR check

6. Build a review plan for L4:

• define human-review checklist entries
• define optional AI-review prompt or rubric

7. Build a custom Sonar plugin module:

• register PMD rule repository
• load custom rules into Sonar
• provide default quality profile (custom-spec-profile or user-provided name)

8. Package plugin JAR and deploy into Sonar plugin directory (extensions/plugins). 9. Start SonarQube Community in Docker with the custom plugin loaded. 10. Wait for Sonar server readiness and initialize token/project binding. 11. Prepare a test project:

• use real project if provided, otherwise scaffold a minimal project
• include both violating and compliant code samples

12. Trigger real scan with Maven Sonar plugin (mvn sonar:sonar). 13. Verify plugin effectiveness via Sonar APIs/UI:

• profile exists and is active
• custom rules are listed and enabled
• issues are produced with rule key + file + line mapping

14. Report scan evidence and unresolved gaps.

Language Support Gate

1. Check if the target language is supported by PMD and your Sonar integration path. 2. If unsupported by PMD:

• classify candidates as L3 if another automation tool can enforce them
• classify remaining items as L4
• generate both automation and review outputs
• recommend alternative analyzer and optional generic external issues import

Sonar Integration

Server-side plugin execution:

• Preferred because this skill requires custom plugin validation.
• Scan command example:
• mvn -DskipTests sonar:sonar -Dsonar.host.url=http://localhost:9000 -Dsonar.token=<token>

Docker Validation Baseline

Minimum checks after container startup:

• Sonar health endpoint reports ready.
• Plugin is loaded (visible in marketplace/plugins list or startup logs).
• Quality profile from the plugin is available.

Minimum checks after scan:

• At least one custom-rule issue appears on violating sample.
• Compliant sample does not trigger that custom rule.
• Issues are mapped to concrete file and line.

Non-negotiable Rules

• Do not handcraft PMD reports; generated findings must come from actual analysis.
• L1-L2 go into PMD rules and the custom sonar-pmd plugin.
• L3 items must be exported into an automation tooling plan instead of being forced into PMD.
• L4 items must be exported into human or AI review workflows.
• End-to-end verification is incomplete without Docker Sonar + real scan evidence.
• First rollout should stay non-blocking unless user explicitly requests CI gating.

Delivery Outputs

• Governance artifacts (mapping, ruleset, L3 tooling plan, L4 review checklist).
• Custom plugin source and packaged JAR.
• Docker startup commands and runtime evidence.
• Test project scan command and result summary.
• Verification report listing profile key, rule keys, issue count, and sampled issue locations.

Troubleshooting Checklist

• Plugin not loaded: verify Sonar/plugin API compatibility and restart logs.
• Profile missing: verify repository key/profile registration code.
• No issues found: confirm profile binding and test code actually violates rule.
• False positives spike: narrow XPath scope and add negative samples.
• Scan auth errors: validate token and sonar.host.url consistency.

Docker Sonar Validation

Goal

Run a real SonarQube server with custom plugin JARs and validate scans against a test project.

1) Start SonarQube Community

docker run -d --name sonar-pmd-local \
  -p 9000:9000 \
  -v "$PWD/.sonar/plugins:/opt/sonarqube/extensions/plugins" \
  sonarqube:community

Place custom plugin jars in $PWD/.sonar/plugins before startup (or restart after copying).

2) Wait for readiness

until curl -fsS "http://localhost:9000/api/system/status" | grep -q '"status":"UP"'; do
  sleep 5
done

3) Create token (example)

Use Sonar UI to create a token, or API if admin credentials are available.

curl -u "admin:admin" -X POST "http://localhost:9000/api/user_tokens/generate?name=local-token"

If password is changed, use updated credentials.

4) Bind custom quality profile

Example API (replace placeholders):

curl -u "${ELITEFORGE_SKILL_SONAR_PMD_TOKEN}:" -X POST \
  "http://localhost:9000/api/qualityprofiles/add_project?language=java&project=<projectKey>&qualityProfile=<profileName>"

5) Run Maven scan in test project

mvn -DskipTests sonar:sonar \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=${ELITEFORGE_SKILL_SONAR_PMD_TOKEN} \
  -Dsonar.projectKey=<projectKey>

6) Verify scan outcome

• Project has analysis snapshot.
• Custom profile is active for project language.
• Custom rules produce expected issues on violating files.
• Compliant files do not produce false positives for smoke-test rules.

Optional: External PMD import path

If plugin packaging is deferred, run PMD first and import report (language-property dependent).

mvn -DskipTests pmd:pmd
mvn -DskipTests sonar:sonar \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=${ELITEFORGE_SKILL_SONAR_PMD_TOKEN} \
  -Dsonar.java.pmd.reportPaths=target/pmd.xml

This path does not validate custom plugin loading.

Plugin Packaging Blueprint

Scope

Package custom PMD rules into a SonarQube plugin and expose a default quality profile.

Recommended Module Layout

custom-sonar-pmd/
  pom.xml
  custom-pmd-rules/
    pom.xml
    src/main/resources/rulesets/custom-<lang>-ruleset.xml
    src/main/java/... (optional Java PMD rules)
  custom-sonar-pmd-plugin/
    pom.xml
    src/main/java/.../CustomSonarPmdPlugin.java
    src/main/java/.../CustomRulesDefinition.java
    src/main/java/.../CustomProfileDefinition.java
    src/main/resources/...

Compatibility Checklist

• SonarQube server version.
• sonar-plugin-api version.
• sonar-pmd plugin version (if extending/depending on it).
• PMD core/language module versions.

Lock versions explicitly in Maven BOM or dependency management.

Rule Registration Checklist

1. Define a stable repository key (for example custom-pmd). 2. Register all custom rules with unique rule keys. 3. Include specification trace in rule metadata/message. 4. Register default quality profile and activate selected rules. 5. Ensure language key alignment (java, xml, etc.) with target rules.

Minimal Plugin Responsibilities

• Plugin entry class: registers extensions.
• RulesDefinition: exposes rule repository and metadata.
• ProfileDefinition: seeds default profile and rule activations.

Build and Package

mvn -DskipTests clean package

Expected output:

• plugin jar under custom-sonar-pmd-plugin/target/

Deployment

1. Copy plugin jar to Sonar plugin directory:

• container path: /opt/sonarqube/extensions/plugins/

2. Restart SonarQube. 3. Verify plugin appears in installed plugin list.

Common Failure Modes

• API mismatch between plugin and SonarQube version.
• Missing rule repository key binding.
• Profile created but no active rules.
• Plugin loads but rules invisible due to wrong language key.

Suggested Smoke Test Rule

Add one deterministic rule that is easy to trigger (for example, banning a known method call). Use this rule to verify end-to-end wiring before enabling the full ruleset.

Sonar API Evidence Checklist

Variables

export ELITEFORGE_SKILL_SONAR_PMD_HOST="http://localhost:9000"
export ELITEFORGE_SKILL_SONAR_PMD_TOKEN="<token>"
export ELITEFORGE_SKILL_SONAR_PMD_PROJECT_KEY="<projectKey>"
export ELITEFORGE_SKILL_SONAR_PMD_PLUGIN_KEY="<customPluginKey>"
export ELITEFORGE_SKILL_SONAR_PMD_RULE_REPO_KEY="<customRuleRepoKey>"
export ELITEFORGE_SKILL_SONAR_PMD_PROFILE_KEY="<language>-<profileKey>"

1) Server status

curl -u "${ELITEFORGE_SKILL_SONAR_PMD_TOKEN}:" -sS "${ELITEFORGE_SKILL_SONAR_PMD_HOST}/api/system/status"

Expect: "status":"UP".

2) Plugin installed

curl -u "${ELITEFORGE_SKILL_SONAR_PMD_TOKEN}:" -sS "${ELITEFORGE_SKILL_SONAR_PMD_HOST}/api/plugins/installed"

Expect: plugin list contains ELITEFORGE_SKILL_SONAR_PMD_PLUGIN_KEY.

3) Quality profile exists

curl -u "${ELITEFORGE_SKILL_SONAR_PMD_TOKEN}:" -sS "${ELITEFORGE_SKILL_SONAR_PMD_HOST}/api/qualityprofiles/search"

Expect: profile list contains target profile name/key.

4) Project-profile binding

curl -u "${ELITEFORGE_SKILL_SONAR_PMD_TOKEN}:" -sS "${ELITEFORGE_SKILL_SONAR_PMD_HOST}/api/qualityprofiles/search?project=${ELITEFORGE_SKILL_SONAR_PMD_PROJECT_KEY}"

Expect: target language profile for project is the custom profile.

5) Rules visible in repository

curl -u "${ELITEFORGE_SKILL_SONAR_PMD_TOKEN}:" -sS "${ELITEFORGE_SKILL_SONAR_PMD_HOST}/api/rules/search?repositories=${ELITEFORGE_SKILL_SONAR_PMD_RULE_REPO_KEY}&ps=500"

Expect: rules count > 0 and includes smoke-test rule key.

6) Issues generated

curl -u "${ELITEFORGE_SKILL_SONAR_PMD_TOKEN}:" -sS "${ELITEFORGE_SKILL_SONAR_PMD_HOST}/api/issues/search?componentKeys=${ELITEFORGE_SKILL_SONAR_PMD_PROJECT_KEY}&ps=100"

Expect: at least one issue tied to custom rule key on violating samples.

7) Issue location spot-check

Use issue payload fields to confirm:

• file/component path
• line number
• rule key
• message includes traceable SPEC-ID

Evidence Bundle Recommendation

Capture and store:

• plugin installed response snippet
• profile search snippet
• rule search snippet
• issue search snippet
• scan command and commit hash of test project

Workflow Playbook

Goal

Deliver a complete, reproducible path from specification to validated SonarQube findings.

Inputs

• Specification documents.
• Target language list.
• Plugin workspace (existing or to-be-created).
• Test project workspace.
• Sonar endpoint and token strategy.

Output Artifacts

• mapping/spec-to-governance.csv
• rulesets/custom-<lang>-ruleset.xml
• automation/l3-tooling-plan.md
• manual-review/l4-review-checklist.md
• Custom plugin JAR
• Scan evidence report (profile key, rule keys, issue examples)

Phase 1: Requirement Extraction and Classification

1. Parse normative clauses (must/forbid/required/unified style). 2. Assign IDs (SPEC-<LANG>-001...). 3. Classify each item:

• L1: built-in PMD coverage.
• L2: XPath or custom PMD rule.
• L3: non-PMD automation can detect it.
• L4: human or AI review needed.

4. Fill mapping CSV with trace fields.

Phase 2: PMD Rule Generation

1. Build L1 rules by PMD category refs. 2. Build L2 rules as XPath (or Java PMD rules when XPath is not safe). 3. Add traceability in rule names/messages (SPEC-ID). 4. Validate each custom rule using positive and negative samples.

Phase 3: L3 Automation Planning

1. Pick the narrowest stable tool for each L3 rule:

• formatter
• pre-commit hook
• build plugin
• Semgrep / regex script
• ArchUnit

2. Define execution stage (pre-commit, build, CI, MR check). 3. Record expected failure mode and exemptions.

Phase 4: L4 Review Planning

1. Define the manual review checklist item. 2. If AI review is useful, define the prompt and evidence expected from the reviewer.

Phase 5: Sonar Plugin Packaging

1. Build PMD rules module (resources + optional Java rule classes). 2. Build Sonar plugin module (repository + profile registration). 3. Package plugin JAR. 4. Copy JAR into Sonar plugin directory.

See plugin-packaging-blueprint.md for structure and class-level checklist.

Phase 6: Docker Sonar Validation

1. Start SonarQube Community container. 2. Wait until system status is UP. 3. Confirm plugin loaded. 4. Create token and bind profile to target project. 5. Run real scan from test project (mvn sonar:sonar).

See docker-sonar-validation.md for command templates.

Phase 7: Evidence Collection

1. Query Sonar APIs for:

• plugin installed
• profile active
• rules visible
• issues generated

2. Export issue samples with file + line + rule key. 3. Record failed checks and mitigation.

See sonar-api-evidence-checklist.md for API commands.

Done Criteria

• All spec items classified.
• L1/L2 implemented and traceable.
• L3 tooling plan generated.
• L4 review checklist generated.
• Plugin loaded in Docker Sonar.
• Test scan produced expected issues.
• Evidence report available.