sonarqube-review

Use when fixing SonarQube code quality issues automatically across any language or framework — issue analysis, fix generation, unit tests, and coverage. Supports Community, Enterprise, and custom SonarQube deployments via environment variables. Do NOT use for general code review without SonarQube (use code-review-and-quality), for whole-repo quality interventions without SonarQube (use quality-test-implementation), or for non-SonarQube static analysis tools. Part of the afonsoft/skills collection.

SonarQube Review Skill

When to Use

• User asks or mentions this skill in English (e.g., "use /sonarqube-review", "run sonarqube-review").
• O usuário pede ou menciona esta skill em português (ex.: "use /sonarqube-review", "execute sonarqube-review").

Purpose

Automatically fix issues reported by SonarQube, regardless of language or framework, following a structured process with:

• Issue analysis
• Fix checklist
• Unit tests and coverage (stack-agnostic)
• Review documentation
• .gitignore update

⚙️ Environment Variable Configuration

The skill supports multiple SonarQube editions through environment variables. Detection is automatic based on the availability of the variables (in priority order):

⚠️ IMPORTANT: For security, NEVER read, print, or inspect the value of environment variables that contain tokens. The most you may know is which variable the token is stored in. Use the variables directly in commands without accessing their contents.

Available Variables

For Custom URL (Highest Priority)

• SONARQUBE_CUSTOM_URL: Base URL of the custom SonarQube
• SONARQUBE_CUSTOM_TOKEN: Authentication token for the custom SonarQube
• SONARQUBE_CUSTOM_EDITION: Edition of the custom SonarQube (open or enterprise, default: open)

For SonarQube Enterprise

• SONARQUBE_ENTERPRISE_TOKEN: Authentication token for SonarQube Enterprise
• SONARQUBE_ENTERPRISE_URL: Base URL of SonarQube Enterprise (required, no fallback)

For SonarQube Open (Default)

• SONARQUBE_OPEN_TOKEN: Authentication token for SonarQube Open (preferred)
• SONAR_TK: Authentication token for SonarQube Open (fallback for compatibility, used only if SONARQUBE_OPEN_TOKEN is not set)
• SONARQUBE_OPEN_URL: Base URL of SonarQube Open (required, no fallback)

Branch Support

Enterprise and Custom editions with enterprise edition automatically support the branch parameter in the API. The skill automatically detects the current branch using git branch --show-current.

🌍 Supports Any Stack

• ✅ Languages: Java, Kotlin, Python, JavaScript, TypeScript, C#, C++, Go, Ruby, PHP, Scala, PLSQL, VB.NET and others
• ✅ Frameworks: Spring, Django, Flask, FastAPI, Express, React, Vue, Angular, .NET, ASP.NET, Gin, Rails, etc.
• ✅ Any test tool that generates coverage reports
• ✅ Any dependency manager (Maven, Gradle, npm, pip, dotnet, etc.)

🔍 Automatic Stack Detection

The skill automatically detects the project's stack by analyzing configuration files. Load the script references/detect-stack.sh to determine the stack and configure the appropriate commands.

Detection Patterns

File	Stack	Manager	Test Tool	Coverage Tool
pom.xml	Java/Kotlin	Maven	Maven Surefire/Failsafe	JaCoCo
build.gradle / build.gradle.kts	Java/Kotlin	Gradle	Gradle Test	JaCoCo
package.json	JavaScript/TypeScript	npm/yarn/pnpm	Jest/Vitest/Mocha	Istanbul
requirements.txt / pyproject.toml	Python	pip	pytest	Coverage.py
.csproj / .sln	C#/.NET	dotnet	dotnet test	OpenCover/Cobertura
go.mod	Go	go mod	go test	go test -cover
Gemfile	Ruby	bundler	rspec/minitest	SimpleCov
composer.json	PHP	composer	phpunit	phpunit
build.sbt	Scala	sbt	sbt test	sbt coverage

Detection Script

Load the script references/detect-stack.sh to automatically detect the project's stack and configure the appropriate commands.

Angular-Specific Support

Angular Detection

• File: angular.json or angular-cli.json
• Manager: npm, yarn, pnpm
• Test Framework: Karma + Jasmine or Jest
• Coverage Tool: Istanbul (ng test --code-coverage)

Angular Commands

bash

# Tests with coverage
ng test --code-coverage --watch=false

# Linting
ng lint

# Formatting
npx prettier@<VERSION> --write src/
npx eslint@<VERSION> --fix src/

# Build for validation
ng build --configuration=production

Angular Scripts

• references/validate-angular.sh — Angular validation (ng lint, ng test, prettier, eslint)

Angular Test Template

• references/templates/test-angular.md — Template for Karma/Jasmine tests with TestBed

C# .NET-Specific Support

C# .NET Detection

• File: .csproj or .sln
• Manager: dotnet CLI
• Test Framework: xUnit, NUnit, MSTest
• Coverage Tool: dotnet test /p:CollectCoverage=true

C# .NET Commands

bash

# Tests with coverage
dotnet test /p:CollectCoverage=true /p:CoverageFormat=cobertura

# Linting and analysis
dotnet build /p:RunAnalyzersDuringBuild=true

# Formatting
dotnet format

# Package restore
dotnet restore

C# .NET Scripts

• references/validate-csharp.sh — C#/.NET validation (dotnet build, dotnet test, dotnet format)

C# .NET Test Template

• references/templates/test-csharp.md — Template for xUnit/Moq tests

SonarQube Local Validation

Local Validation Script

Load the script references/sonar-local-scan.sh to run SonarQube locally and revalidate fixes before committing.

bash

# Run local scan
bash references/sonar-local-scan.sh

Local SonarQube Configuration

The sonar-local-scan.sh script requires:

• sonar-scanner installed (available at https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/scanners/sonarscanner/)
• Java 17+ and jq
• sonar-project.properties file in the project root (optional, script configures automatically)

sonar-scanner Installation

bash

# Linux/macOS (manual): unzip the SonarScanner ZIP and add <path>/bin to PATH
export PATH="$HOME/sonar-scanner-<version>/bin:$PATH"

# Or use this repository's installer
./install-skill-tools.sh --sonar

Example sonar-project.properties

properties

sonar.projectKey=my-project
sonar.sources=src
sonar.tests=tests
sonar.exclusions=**/node_modules/**,**/dist/**,**/bin/**,**/obj/**
sonar.coverage.exclusions=**/*Tests.cs,**/Program.cs
sonar.cs.vscoveragexml.reportPaths=coverage.xml
sonar.javascript.lcov.reportPaths=coverage/lcov.info

Workflow

Pre Steps

• Save the time you started running the skill to measure the time spent.
• When finishing the run, save the end time to calculate the total time spent.
• Compare the time spent with the "effort" estimated in the issue to evaluate the skill's efficiency (report how many % of time saved or lost relative to the estimated effort).

Phase 1: Analysis and Preparation

1. Detect Project Stack

   • Load the script references/detect-stack.sh to automatically detect the stack
   • The script returns: STACK, BUILD_TOOL, TEST_FRAMEWORK, COVERAGE_TOOL
   • Configure the appropriate commands based on the detected stack
   • If automatic detection is not possible, ask the user

2. Verify issues file

   • Check the project name, usually it is the workspace folder name.

   • If it is not at the project root, create the .sonar_devin_auto_fix/ folder

   • ⚠️ CRITICAL SECURITY: Never print the value of environment variables that contain tokens or secrets. NEVER read token values into your memory — the most you may know is which environment variable the token is stored in. Use the variables directly in bash commands without ever inspecting their contents.

   • Download the project's issues: If the user specifies the project name, use it; otherwise try to use the workspace folder name, and if that is still not possible, ask the user for the project name. If the user provides the issues to be fixed, query using the issues parameter and pass a csv list with the issue IDs; otherwise download all unresolved issues from the project using the SonarQube API. If the user requests to fix only new issues, download the unresolved issues and add the inNewCodePeriod filter set to true.

     Automatic SonarQube edition detection: The skill automatically detects which edition to use based on the available environment variables (in priority order):

     1. Custom URL (highest priority): If $SONARQUBE_CUSTOM_URL is set
     2. Enterprise: If $SONARQUBE_ENTERPRISE_TOKEN is set
     3. Open: If $SONARQUBE_OPEN_TOKEN or $SONAR_TK is set
     4. Error: If none of the above, abort and request the environment variables to be configured (there is no automatic/fallback URL).

     Download issues with automatic detection: Load the reference script references/download-issues.sh and execute it.

   • Indent the downloaded issues file using the script references/jsonf.sh

   • Confirm that .sonar_devin_auto_fix/sonarqube_issues.json exists and is parseable

   • Base all fixes exclusively on the issues listed in that JSON

3. Create ToDo Board

   • Create the file .sonar_devin_auto_fix/SONAR_FIX_TODO_BOARD.md
   • Use the format:

     markdown

     # SonarQube Review ToDo Board
     
     ## SonarQube Issues Checklist
     
     - [ ] Issue <ID> — Rule: <RuleKey> — File: `<path/to/file>` — Line: <line>
           Summary: <short issue message>
     

   • Group by file if possible
   • Sort by severity (Blocker → Critical → Major → Minor → Info)

Phase 2: Issue Fixing

For each issue, execute in order:

1. Modify the code - Resolve the specific issue
2. Generate tests automatically (if applicable) - Load the appropriate test template for the detected stack
3. Update tests - Ensure 100% coverage of the modified lines
4. Run tests - Execute the unit test suite
5. Check coverage - Confirm 100% coverage of the modified lines
6. Run stack-specific linters - Execute stack linters to validate the fix
7. Format the code - Execute stack formatters to keep consistency
8. Update the ToDo Board - Mark the issue as [x] when fixed

Phase 3: Documentation and Finalization

1. Update .gitignore

   • Open .gitignore at the project root
   • Add the line: .sonar_devin_auto_fix/**
   • Only if an equivalent does not already exist

2. Generate Review Guide

   • Create .sonar_devin_auto_fix/SONAR_FIX_REVIEW_NOTES.md
   • Include sections:
     • Summary of changes: number of issues fixed and types of fixes
     • How to review: instructions for the developer to review the changes
     • Points of attention: sensitive logic that was changed
     • Tests: how to run tests and coverage
     • Post-review verification: final validations

3. Final validation

   • The SonarQube scan will be run by the CI/CD pipeline after the merge
   • Confirm that the code is clean and tests are passing

4. Generate Metrics Dashboard

   • Create .sonar_devin_auto_fix/SONAR_FIX_METRICS.html
   • Include:
     • Time spent vs estimated effort (in %)
     • Number of issues fixed by type (bug, code smell, vulnerability, hotspot)
     • Coverage before/after
     • Regressions avoided
     • Detected stack and tools used

🛠️ Integrated External Tools

The skill automatically integrates external tools per stack to validate and format the code after fixes.

Linters by Stack

Stack	Linter	Command
Java/Kotlin	Checkstyle, PMD	mvn checkstyle:check pmd:check
JavaScript/TypeScript	ESLint	npx eslint@<VERSION> src/
Python	Pylint, Flake8	python -m pylint src/
C#/.NET	StyleCop, Roslyn Analyzers	dotnet build /p:RunAnalyzersDuringBuild=true
Go	golint, golangci-lint	golangci-lint run
Ruby	RuboCop	bundle exec rubocop
PHP	PHPStan	vendor/bin/phpstan analyse
Scala	Scalastyle, Scapegoat	sbt scalastyle scapegoat

Formatters by Stack

Stack	Formatter	Command
Java/Kotlin	Spotless, Google Java Format	mvn spotless:apply
JavaScript/TypeScript	Prettier	npx prettier@<VERSION> --write src/
Python	Black, isort	python -m black src/
C#/.NET	dotnet format	dotnet format
Go	gofmt, goimports	gofmt -w .
Ruby	Rufo	bundle exec rufo
PHP	PHP CS Fixer	vendor/bin/php-cs-fixer fix

Coverage Tools by Stack

Stack	Tool	Command
Java/Kotlin	JaCoCo	mvn jacoco:report
JavaScript/TypeScript	Istanbul	npx vitest@<VERSION> run --coverage
Python	Coverage.py	python -m coverage run -m pytest
C#/.NET	OpenCover, Cobertura	dotnet test /p:CollectCoverage=true /p:CoverageFormat=cobertura
Go	go test -cover	go test -cover ./...
Ruby	SimpleCov	bundle exec rspec --coverage
PHP	phpunit --coverage-clover	vendor/bin/phpunit --coverage-clover=coverage.xml
Scala	sbt coverage	sbt clean coverage test coverageReport

SonarLint and SonarScanner

The skill may use SonarLint and SonarScanner for local validation before committing:

SonarLint (IDE Integration):

• Available for IntelliJ IDEA, VS Code, Eclipse
• Validates code in real time
• Can be invoked via command line for batch validation

SonarScanner CLI:

• For local scans before push
• Offline validation of fixes
• Command: sonar-scanner -Dsonar.projectKey=<project> -Dsonar.sources=src

Validation Scripts

The skill loads reference scripts for automatic validation per stack:

• references/validate-java.sh — Java/Kotlin validation (Checkstyle, PMD, Spotless, JaCoCo)
• references/validate-js.sh — JavaScript/TypeScript validation (ESLint, Prettier, Vitest)
• references/validate-python.sh — Python validation (Pylint, Flake8, Black, pytest)
• references/validate-csharp.sh — C#/.NET validation (Roslyn Analyzers, dotnet format, dotnet test)
• references/validate-go.sh — Go validation (golangci-lint, gofmt, go test)
• references/validate-ruby.sh — Ruby validation (RuboCop, Rufo, rspec)
• references/validate-php.sh — PHP validation (PHPStan, PHP CS Fixer, phpunit)
• references/validate-scala.sh — Scala validation (Scalastyle, Scapegoat, sbt)

🎨 Test Templates by Stack

The skill generates tests automatically based on stack-specific templates. Load the appropriate template from the references/templates/ folder:

• test-java.md — Template for JUnit/Mockito tests
• test-kotlin.md — Template for KotlinTest/Mockk tests
• test-python.md — Template for pytest/unittest tests
• test-javascript.md — Template for Jest/Vitest tests
• test-typescript.md — Template for TypeScript tests
• test-csharp.md — Template for xUnit/Moq tests
• test-go.md — Template for Go tests
• test-ruby.md — Template for RSpec/Minitest tests
• test-php.md — Template for PHPUnit tests
• test-scala.md — Template for ScalaTest/ScalaCheck tests

Tests and Coverage

• ✅ 100% coverage of modified lines (verified in coverage report)
• ✅ No coverage exclusions, such as:
  • Comments: // NOSONAR, // no sonar, # noqa, # pragma: no cover, etc.
  • Decorators/Attributes: @IgnoreCoverage, ExcludeFromCodeCoverage, @Suppress, etc.
  • Compiler pragmas: #pragma, etc.
  • IMPORTANT: If the file already has a coverage exclusion, remove it and implement tests for the fix as well as for the rest of the file's code, ensuring full coverage.
• ✅ Remove SonarQube scanner files that may be present, such as sonar-project.properties, sonar-scanner.properties, etc. Also remove other scanners, such as the SonarScanner for Maven usually present in the POM.xml, since our pipeline is autonomous and does not depend on these files to work. (For now, keep only SonarQube-related configurations in .csproj files).
• ✅ All tests passing
• ✅ Coverage report available (formats: OpenCover, JaCoCo, Cobertura, Istanbul, etc.)

Code Quality

• ✅ No new code smells or SonarQube violations
• ✅ No functional regressions
• ✅ No obvious performance problems
• ✅ Minimal, targeted changes
• ✅ Code follows project conventions and standards
• ✅ No unnecessary changes in areas unrelated to the issue

Business Logic

• ✅ Do not change business logic without extreme necessity
• ✅ If it is necessary to change sensitive points (business rules, critical calculations, main flows):
  • Minimize the change
  • Document clearly in the review guide
  • Justify why it was unavoidable
  • Add specific tests to validate the change

Dependencies

• ✅ Do not add unnecessary dependencies
• ✅ Stay within the scope of SonarQube fixes
• ✅ If adding a dependency is absolutely necessary, justify and document it
• ✅ Check that there are no conflicts with existing dependencies

Completion Checklist

• All issues analyzed and categorized in SONAR_FIX_TODO_BOARD.md
• All issues fixed with 100% test coverage
• All tests passing
• .gitignore updated with .sonar_devin_auto_fix/**
• SONAR_FIX_REVIEW_NOTES.md generated with complete instructions
• No new issue introduced (verified via code review and tests)

Useful Commands (Examples by Stack)

⚠️ Important: Isolated Environments with Required Parameters

Commands are configured to force isolated environments. The isolation prefix is required, but you may add more parameters after it.

Rule: Keep the isolation parameter (e.g. -Dmaven.repo.local=./.m2/repository), but you may add more flags.

Java / Kotlin (Maven)

bash

# ✅ ALLOWED - Mandatory isolation + additional parameters
mvn -Dmaven.repo.local=./.m2/repository clean test
mvn -Dmaven.repo.local=./.m2/repository -DskipTests=false jacoco:report
mvn -Dmaven.repo.local=./.m2/repository -Dorg.slf4j.simpleLogger.defaultLogLevel=debug clean test

# ❌ NOT ALLOWED - No isolation
mvn clean test

Java / Kotlin (Gradle)

bash

# ✅ ALLOWED - Mandatory isolation + additional flags
gradle --gradle-user-home ./.gradle test
gradle --gradle-user-home ./.gradle test --info
gradle --gradle-user-home ./.gradle clean build -x test

# ❌ NOT ALLOWED - No isolation
gradle test

JavaScript / TypeScript / Node.js

bash

# npm ✅ ALLOWED
npm install --no-save
npm install --no-save --verbose
npm test -- --coverage --verbose

# yarn ✅ ALLOWED
yarn install --offline
yarn install --offline --verbose

# pnpm ✅ ALLOWED
pnpm install
pnpm install --verbose

# npx ✅ ALLOWED only with pinned versions
npx vitest@<VERSION> run --coverage
npx eslint@<VERSION> src/

Python

bash

# Create venv (if not exists) ✅ ALLOWED
python -m venv .venv
python -m venv .venv --upgrade-deps

# pip with isolation ✅ ALLOWED
python -m pip install -r requirements.txt -q
python -m pip install --target ./.venv/lib -q package-name
python -m pip install --target ./.venv/lib --upgrade package-name

# pytest and coverage ✅ ALLOWED
python -m pytest --cov=src tests/ -v
python -m pytest --cov=src tests/ --cov-report=html
python -m coverage run -m pytest
python -m coverage report --skip-covered

C# / .NET

bash

# ✅ ALLOWED
dotnet test
dotnet test /p:CollectCoverage=true /p:CoverageFormat=cobertura
dotnet test /p:CollectCoverage=true /p:Exclude="[*Tests]*"

Go

bash

# ✅ ALLOWED
go test -cover ./...
go test -cover ./... -v
go test -coverprofile=coverage.out ./... -timeout=10m

Ruby / Rails

bash

# ✅ ALLOWED
bundle install --local
bundle install --local --no-deployment
bundle exec rspec --coverage
bundle exec rspec --coverage -f progress

PHP

bash

# ✅ ALLOWED
composer install --no-dev
composer install --no-dev --optimize-autoloader
composer install --no-dev --classmap-authoritative
vendor/bin/phpunit --coverage-clover=coverage.xml
vendor/bin/phpunit --coverage-clover=coverage.xml -v

Scala

bash

# ✅ ALLOWED
sbt clean coverage test coverageReport
sbt clean coverage test coverageReport -Dconfig=test
sbt "test -- -Dverbose=true"

🧹 Environment Cleanup

When finishing all fixes, run:

bash

git status

Analyze the output and:

• Temporary, build, coverage, or cache files that appear → add to .gitignore
• Staged files that should not be there → remove with git restore --staged <file>
• Confirm that .sonar_devin_auto_fix/ does not appear as staged

⚠️ Do not commit. Leave the repository clean and organized so the human developer can review and decide what to commit.

Cleanup of Isolated Environments (Optional)

If the user asks to remove isolated environments after completion, list the paths first and ask for explicit confirmation before deleting anything. Do not run rm -rf or find -exec rm -rf without consent.

bash

# List what would be removed (do not delete automatically)
echo "The following paths could be removed: .venv .m2 node_modules .npm __pycache__ .pytest_cache"
# Ask the user to confirm before proceeding. Prefer `git clean` for tracked artifacts.

Important: Verify that the isolated environments are in .gitignore:

bash

# Check if already in .gitignore
grep -E "^\.venv$|^\.m2$|^node_modules$|^__pycache__$" .gitignore

# If not found, add them:
echo ".venv" >> .gitignore
echo ".m2" >> .gitignore
echo "node_modules" >> .gitignore
echo ".pytest_cache" >> .gitignore
echo "__pycache__" >> .gitignore

Important Notes

• 🎯 Work in iterations: one issue at a time, with tests and documentation
• 📝 Keep code clean and aligned with the project's existing standard
• 🔍 Prioritize clarity and maintainability
• ⚠️ Always consider the impact of each change on business logic
• 🧹 ALWAYS clean the environment when finishing — no temporary file should remain pending
• ⚡ Be efficient with time and tokens: avoid unnecessary reads, excessive exploration, and repetitions. Read only what is strictly necessary to fix the issue at hand. Prefer direct and objective actions. Avoid invoking unnecessary tools — use only what the task requires.
• 🚫 Do not implement anything beyond what was requested: fix exclusively the issues listed in sonarqube_issues.json. Do not refactor without need, do not improve, do not add features, do not reorganize code that is not directly related to the issue.
• 🚫 Do not run programming scripts that require human validation before release: when trying to run scripts, a prompt is presented to the user to decide whether it can be executed, which removes your autonomy and generates more work for the user.

The Iron Law

text

NO COVERAGE EXCLUSIONS

No coverage exclusion may be used to bypass the lack of tests.

No exceptions:

• Do not use // NOSONAR, // no sonar, # noqa, # pragma: no cover
• Do not use decorators such as @IgnoreCoverage, ExcludeFromCodeCoverage, @Suppress
• Do not use compiler pragmas such as #pragma for exclusions
• If the file already has an exclusion, remove it and implement tests for the code
• Ensure 100% coverage of the modified lines

Common Mistakes

Mistake	Consequence	How to avoid
Add coverage exclusions	Code without tests approved	Implement tests for all modified lines
Fix issues without tests	Undetected regressions	Always add unit tests for each fix
Change business logic without need	Bug risk	Stay within the scope of the SonarQube issue
Do not run linters after fixing	New violations introduced	Run stack linters after each fix
Do not clean environment at the end	Temporary files in repo	Run environment cleanup when finishing
Print environment variable values	Security violation	NEVER read or print tokens, use variables directly in commands

Anti-Patterns

❌ "This code is too simple to need a test"

Even simple code can have bugs. TDD applies to any fix, regardless of complexity.

❌ "I'll add a coverage exclusion just for this case"

Coverage exclusions violate the quality principle. If the code is too complex to test, refactor it.

❌ "SonarQube is wrong, I won't fix it"

SonarQube can have false positives, but most issues are valid. Fix them and discuss legitimate cases with the team.

❌ "I'll fix everything at once without tests"

Bulk fixes without tests drastically increase the risk of regressions. Fix one issue at a time with tests.

❌ "I don't need to run the local scan, the pipeline will validate"

Local validation saves time and avoids pipeline rejections. Use the sonar-local-scan.sh script.

Adaptations for this catalog

This skill follows the agent catalog standards:

• Frontmatter aligned to repo standard: license: MIT, metadata.version, metadata.author, tripartite description with explicit Do NOT use for clause
• Language: English (en-us) for content, technical terms in English
• Branch policy: follow feature/{agent}-{YYYYMMDD}-{short-description}
• Git workflow: branches created from develop, PR target is develop (not main)

Origin

This skill was created following patterns from obra/superpowers/skills/writing-skills and adapted for SonarQube auto-fix workflows across multiple stacks.