sonarqube

SonarQube Skill

Phase 0: Project Key + Organization Resolution + Mode Selection

Resolve PROJECT_KEY and SONARQUBE_ORGANIZATION

Both are required for all API calls. Resolve in this order:

1. Check conversation memory/context (user stores per-directory memories — check MEMORY.md)
2. Read sonar-project.properties → sonar.projectKey + sonar.organization
3. Read .sonarlint/connectedMode.json → projectKey
4. Read package.json → sonar.projectKey
5. Check CI files (.github/workflows/*.yml) for sonar config
6. Call search_my_sonarqube_projects to list/search
7. If still unknown: AskUserQuestion

Store as PROJECT_KEY and SONARQUBE_ORGANIZATION. Scripts also read these from env.

Parse Mode from $ARGUMENTS

• --pr → PR gate fix workflow
• --fix → general issue fix workflow
• --hotspots → security hotspot review
• --coverage → coverage improvement
• --triage → triage-only (no fixes, just plan)
• (empty) → ask user:

AskUserQuestion: "What do you want to do?
1. Fix failing PR quality gate (--pr)
2. Fix codebase issues by severity (--fix)
3. Review security hotspots (--hotspots)
4. Improve test coverage (--coverage)
5. Triage only — show me a plan without fixing"

---

Phase 1: Assessment

Fire all relevant MCP calls in parallel in a single message (no subagents — orchestrator only).

PR mode (--pr)

1. git rev-parse --abbrev-ref HEAD to get current branch name
2. list_pull_requests(project: PROJECT_KEY) to find matching PR
   • Match branch name to branch field in results
   • If no match: tell user "No SonarQube PR analysis found for branch <name>. Push the branch and wait for CI to complete, then re-run."
   • If match found: store PR_ID
3. In parallel:
   • get_project_quality_gate_status(project: PROJECT_KEY, pullRequest: PR_ID)
   • search_sonar_issues_in_projects(projects: PROJECT_KEY, pullRequest: PR_ID, severities: "BLOCKER,CRITICAL,MAJOR")
   • search_security_hotspots(project: PROJECT_KEY, pullRequest: PR_ID)

General/fix mode (--fix)

In parallel:

• get_project_quality_gate_status(project: PROJECT_KEY)
• get_component_measures(component: PROJECT_KEY, metricKeys: "bugs,vulnerabilities,code_smells,duplicated_lines_density,coverage,reliability_rating,security_rating,sqale_rating")
• search_sonar_issues_in_projects(projects: PROJECT_KEY, severities: "BLOCKER,CRITICAL")
• search_security_hotspots(project: PROJECT_KEY, status: "TO_REVIEW")

Coverage mode (--coverage)

In parallel:

• get_project_quality_gate_status(project: PROJECT_KEY)
• get_component_measures(component: PROJECT_KEY, metricKeys: "coverage,uncovered_lines,lines_to_cover,uncovered_conditions")
• search_files_by_coverage(project: PROJECT_KEY, maxCoverage: 50)

Hotspots mode (--hotspots)

• search_security_hotspots(project: PROJECT_KEY, status: "TO_REVIEW")

---

Phase 2: Triage Plan

Skip for --hotspots and --coverage modes — go directly to Phase 3B or 3D.

1. Extract unique rule keys from all issues returned in Phase 1.

2. Fetch rule descriptions — run this script (no MCP needed, direct REST):

python3 ~/.claude/plugins/sonarqube-skill/skills/sonarqube/scripts/fetch_rules.py <key1> <key2> ...

Pass SONARQUBE_TOKEN, SONARQUBE_ORGANIZATION, SONARQUBE_URL as env vars (URL defaults to https://sonarcloud.io).

3. Write issues JSON to a temp file, then run triage:

python3 ~/.claude/plugins/sonarqube-skill/skills/sonarqube/scripts/triage_issues.py \
  --issues /tmp/sq_issues.json \
  --rules /tmp/sq_rules.json

4. Present triage summary to user:

Found N issues across M files:
- X quick wins (1-line fixes)
- Y complex fixes
- Z hotspots to review
- W accept/FP candidates

Files to fix: [list top 5]

5. AskUserQuestion: "Approve this fix plan? (yes / adjust / cancel)"
   • Adjust → ask what to change, re-present
   • Cancel → stop

---

Phase 3A: Parallel Code Fixes

For each file in the by_file map from triage JSON:

1. Build the agent prompt:

python3 ~/.claude/plugins/sonarqube-skill/skills/sonarqube/scripts/build_fix_prompt.py \
  --template ~/.claude/plugins/sonarqube-skill/skills/sonarqube/agents/fix-agent.md \
  --file "src/path/to/file.ts" \
  --issues '[{"rule":"...","message":"...","line":42,"ruleDescription":"...","compliantExample":"..."}]'

2. Spawn one general-purpose Agent per file with the result as the prompt, run_in_background: true.

3. After all agents complete, verify each file in parallel:

mcp__sonarqube__analyze_code_snippet(code: <file contents>, language: "ts")

4. If issues remain: show to user → offer retry for specific files.

"Needs User Review" items

Fix agents may report items they skipped as "needs user review" with a risk explanation. Collect all such reports and present them via AskUserQuestion before deciding whether to proceed.

---

Phase 3B: Hotspot Review (sequential)

For each hotspot:

1. show_security_hotspot(key: hotspot.key) → show to user
2. AskUserQuestion: "How to handle <message> in <file>:<line>?
   • Fix it (queue for Phase 3A)
   • Mark as Safe (known safe pattern)
   • Acknowledge (won't fix now)"
3. Safe → change_security_hotspot_status(hotspot: key, status: "SAFE")
4. Acknowledge → change_security_hotspot_status(hotspot: key, status: "ACKNOWLEDGED")
5. Fix → add to fix queue, run Phase 3A when done

---

Phase 3C: Status Mutations

For accept/FP candidates approved in triage:

• Run in parallel: change_sonar_issue_status(issue: key, transition: "accept") or "falsepositive"

---

Phase 3D: Coverage Improvement

Two chained agents per file: a planner that understands the code and designs real behavioral contracts, then an executor that writes the tests from the plan. This prevents vacuous coverage.

1. Identify target files (lowest coverage, from search_files_by_coverage)

2. Calculate: lines needed to reach the gate threshold

3. For each target file — run in parallel across files, sequential within each file:

   Step 1 — Planner (foreground, must complete before executor):

   Call get_file_coverage_details(project: PROJECT_KEY, file: FILE_PATH) to retrieve the list of uncovered line numbers for this file. Store the result as UNCOVERED_LINES (a JSON array of integers, e.g. [42, 43, 67, 88]). Then build the planner prompt:

   # FILE_PATH and UNCOVERED_LINES are populated from MCP call results above
   PLANNER_PROMPT=$(sed \
     -e "s|{{FILE_PATH}}|$FILE_PATH|g" \
     -e "s|{{UNCOVERED_LINES}}|$UNCOVERED_LINES|g" \
     -e "s|{{TEST_FILE_PATH}}|src/path/to/file.test.ts|g" \
     ~/.claude/plugins/sonarqube-skill/skills/sonarqube/agents/coverage-planner-agent.md)
   

   Spawn general-purpose Agent with planner prompt. Wait for result (foreground). The planner outputs a JSON test plan to its report.

   Step 2 — Executor (after planner completes): Inject planner's JSON output as {{TEST_PLAN}} into coverage-executor-agent.md. Spawn general-purpose Agent with executor prompt, run_in_background: true.

4. After all executors complete: show report of cases written vs skipped per file.

---

Phase 4: Verify

1. Re-run the same Phase 1 MCP calls in parallel (save responses to /tmp/sq_after.json)
2. Compare gate status before/after:

python3 ~/.claude/plugins/sonarqube-skill/skills/sonarqube/scripts/gate_delta.py \
  /tmp/sq_before.json /tmp/sq_after.json

Output is a markdown table — present it to user.

3. If gate still failing: show remaining blockers → offer to continue fixing.

---

Notes

• All SonarQube MCP calls happen in the orchestrator (main conversation). Fix agents only use Read + Edit.
• For PR mode: all issue/hotspot/gate calls must include pullRequest: PR_ID to scope to new code only.
• Scripts use stdlib only (no pip installs). Credentials come from env vars.
• SONARQUBE_URL defaults to https://sonarcloud.io if not set.