SonarQube Quality

Purpose

Drive code to zero open SonarQube issues (bugs, vulnerabilities, code smells), zero security hotspots awaiting review, and a green Quality Gate, using a SonarQube instance already running locally in Docker on http://localhost:9000.

Use this skill during refactoring and general coding: run an analysis, read the exact issue list, fix the root causes, re-run, and repeat until the report says RESULT: PASS.

Prerequisites

• Docker is running with the sonarqube container published on 9000:9000 (the server). Verify with docker ps.
• python3 is available (used only for stdlib-based API calls — no pip needed).
• Per language, the build tool must be installed only for JVM/.NET projects:
  • Maven → mvn; Gradle → gradle or ./gradlew
  • .NET → dotnet + the dotnet-sonarscanner global tool
  • Everything else (JS/TS, Python, Go, PHP, Ruby, etc.) needs no local scanner — it runs via the sonarsource/sonar-scanner-cli Docker image.

Core Workflow (the quality loop)

To bring a project to 100% clean, follow this loop. Announce each analysis run.

1. Analyze. Run the orchestrator from the project directory:

   ~/.claude/skills/sonarqube-quality/scripts/sonar-check.sh [PROJECT_DIR]

   It checks the server is UP, ensures an analysis token exists (creating one on first run), detects the build system, runs the matching scanner, waits for the server-side Compute Engine task, then prints the full report.
2. Read the report. It lists every open issue grouped by file, as Lnn [TYPE/SEVERITY] message (rule-key), plus security hotspots, the Quality Gate status, and the project ratings (reliability / security / maintainability).
3. Fix root causes. For each issue, open the file at the given line and fix the underlying problem — do not silence it. See "Driving issues to zero" below.
4. Re-run sonar-check.sh. The analysis is incremental on the server side; each run reflects the current code.
5. Stop at PASS. The script exits 0 and prints RESULT: PASS only when open issues = 0, hotspots-to-review = 0, and the Quality Gate is OK. Treat a non-zero exit as "not done yet".

Run analysis after a meaningful batch of edits, not after every single line — the server-side task takes a few seconds each time.

How sonar-check.sh decides the scanner

Detection order (first match wins):

The project key defaults to a sanitized directory name; override with SONAR_PROJECT_KEY. SonarQube auto-creates the project on first analysis. For multi-language repos, language-specific options, coverage import, and exclusions, see references/scanners.md.

Authentication / token handling

The skill manages its own token. On first run, sonar-api.py ensure-token authenticates as admin (default password admin), generates a user token named claude-code-analysis, and caches it at ~/.claude/.sonar-token (mode 600). Later runs reuse and validate the cached token.

If the admin password was already changed (likely on an instance that has been running), token creation fails with a clear message. In that case, ask the user for the admin password and re-run with it exported:

SONAR_ADMIN_PASS='the-real-password' ~/.claude/skills/sonarqube-quality/scripts/sonar-check.sh

Alternatively, the user can create a token in the SonarQube UI (My Account → Security → Generate Tokens) and save it to ~/.claude/.sonar-token.

Security & concurrency notes (local throwaway instance)

• The admin/admin default and the long-lived token cached in plaintext at ~/.claude/.sonar-token (mode 600) assume a local, disposable SonarQube. Do not point this at a shared/production server without changing the admin password and managing token lifetime.
• The token is handed to the scanners via the SONAR_TOKEN environment variable, not a -Dsonar.token CLI argument — so it is not exposed to other local users via ps.
• Parallel runs: the token file is written atomically and a same-named token is never revoked (a colliding name falls back to a per-process token name), so two concurrent Sonar runs won't pull each other's token out from under a live scan. They still share one instance — give them distinct SONAR_PROJECT_KEYs.
• sonar-scanner-cli is an amd64-only image (pinned via SONAR_SCANNER_PLATFORM). On native Linux, if .scannerwork cannot be written into the project due to a container/host UID mismatch, run with --user $(id -u):$(id -g) (Docker Desktop maps ownership automatically). Scanner artifacts are cleaned up on exit.

Driving issues to zero

Aim for genuine fixes, ranked by type:

• Bugs (reliability): correctness defects — null dereferences, wrong conditions, resource leaks, unreachable code. Fix the logic.
• Vulnerabilities (security): injection, weak crypto, hard-coded secrets, unsafe deserialization. Fix the insecure pattern; never just suppress.
• Code smells (maintainability): complexity, duplication, dead code, naming, missing braces, magic numbers. Refactor toward the rule's intent.
• Security hotspots: these require human-style review, not just fixing. For each, decide whether the code is actually safe in context. If unsafe, fix it. If genuinely safe, it can be marked reviewed/safe via the API — see references/web-api.md. Do not mark hotspots safe to make the number go down; justify each.

Suppression policy: avoid // NOSONAR, @SuppressWarnings, # NOSONAR, and "Won't Fix" resolutions. Use them only for verified false positives, and state the justification in the same change. A passing report achieved by suppression is not the goal.

Duplications and coverage are part of "all levels". To eliminate duplicated blocks, extract shared code. To raise coverage, the scanner must import a coverage report produced by the project's test runner — see the coverage section in references/scanners.md.

Manual / advanced API use

For querying issues, hotspots, measures, or changing hotspot status directly (without a full re-scan), use the helper subcommands or raw endpoints documented in references/web-api.md:

python3 ~/.claude/skills/sonarqube-quality/scripts/sonar-api.py report --project-key KEY

Troubleshooting

For "server not UP", scanner-can't-reach-server (Docker networking / host.docker.internal), admin-password-changed, stuck Compute Engine tasks, missing dotnet-sonarscanner, JVM version requirements, and large-repo tuning, see references/troubleshooting.md.

Additional Resources

Scripts (scripts/)

• sonar-check.sh — one-command orchestrator: server check → token → detect build → scan → wait → report. Exit 0 only when clean.
• sonar-api.py — stdlib-only Web API helper with subcommands status, ensure-token, wait-task, report.

Reference Files (references/)

• scanners.md — per-language scanner setup, coverage import, exclusions, multi-module/monorepo notes.
• web-api.md — SonarQube Web API endpoints used, manual queries, issue types/severities, ratings, and changing hotspot status.
• troubleshooting.md — common failures and fixes.