sonarqube-autofix

SonarQube Auto-Fix

When to Use

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

Purpose

Analyze issues reported by SonarQube, regardless of language or framework, classify them by type, and create approved SPEC SDDs that describe the fixes. The actual implementation of each SPEC is delegated to /execute-tdd-spec.

The process is:

1. Issue analysis — download and inspect unresolved SonarQube issues.
2. Classification — group issues by type: bug, code smell, or security.
3. SPEC generation — write one SPEC SDD per issue (or per small, related group) using references/spec-sdd-template.md.
4. Hand-off — mark each SPEC as Approved and invoke /execute-tdd-spec to implement the fixes.

⚙️ 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

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

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

# Linting
ng lint

# Formatting
npx prettier@ --write src/
npx eslint@ --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

# 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.

# 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

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

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

Example sonar-project.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:

     # SonarQube Review ToDo Board
     
     ## SonarQube Issues Checklist
     
     - [ ] Issue  — Rule:  — File: `` — Line: 
           Summary: 
     

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

Phase 2: Classify Issues

For each downloaded issue, classify it into one of the four SonarQube types and record the classification in the ToDo Board:

Add the type to each line of SONAR_FIX_TODO_BOARD.md:

- [ ] Issue  — Sonar type:  — Rule:  — File: `` — Line: 
      Summary: 

Sort the board by: VULNERABILITY → SECURITY_HOTSPOT → BUG → CODE_SMELL, then by severity.

Phase 3: Generate SPEC SDDs

For each issue (or small, related group of the same SonarQube type), create an approved SPEC SDD in .specs/SPEC-{YYYYMMDD}-{issue-key}-{slug}.md using references/spec-sdd-template.md:

1. Metadata — set Status: Approved and Type based on the SonarQube type:
   • BUG → Bugfix
   • CODE_SMELL → Refactor
   • VULNERABILITY → Security
   • SECURITY_HOTSPOT → Security Map the SonarQube rule, file, and the type slug (bug, code-smell, vulnerability, security-hotspot).
2. User Story — describe the problem exposed by SonarQube and the value of the fix.
3. Scope — one issue per SPEC, unless several identical issues are safely grouped (e.g., the same rule in the same file).
4. Technical Context — list files to read (source file, existing tests) and the affected lines.
5. Requirements — one or more numbered requirements translating the SonarQube rule to the expected code state.
6. Acceptance Criteria — Given...when...then plus "SonarQube no longer reports issue ".
7. Task Plan — the fix steps, validation commands, and a link to SONAR_FIX_TODO_BOARD.md.

Mark each generated SPEC as Status: Approved. Do not implement the code in this skill.

Phase 3.5: Hand off to /execute-tdd-spec

After all SPECs are approved, invoke /execute-tdd-spec for each one, in the order of the sorted ToDo Board. The implementation skill will follow the red-green-refactor cycle using the generated SPECs as source of truth.

Phase 4: 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

Formatters by Stack

Coverage Tools by Stack

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= -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)

# ✅ 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)

# ✅ 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

# 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@ run --coverage
npx eslint@ src/

Python

# 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

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

Go

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

Ruby / Rails

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

PHP

# ✅ 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

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

🧹 Environment Cleanup

When finishing all fixes, run:

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
• 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.

# 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:

# 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

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

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.