Skip to content

About

Fixes Sonar code violations using OpenCode

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Coverage Security Rating Maintainability Rating Reliability Rating Bugs Vulnerabilities Supported Versions

pyopenfixer

A lightweight Python utility for retrieving and fixing SonarQube/SonarCloud code quality violations (bugs, vulnerabilities, code smells) from any branch.

Overview

pyopenfixer connects to your SonarQube server, discovers the main branch, and fetches all open/confirmed violations using the SonarQube Issues API with automatic pagination. The violations are returned as a list of dictionaries, making them easy to filter, transform, or export.

The tool's behavior depends on which git branch you're currently on:

  • On the main branch — fetches and prints every open violation on main, a severity summary, and the branch's code coverage percentage.
  • On any other branch — fetches violations for both the current branch and main, then reports only the violations that are new to the current branch (i.e. not already present on main), along with coverage for both branches.

You may also pass in a SonarQube rule (e.g. python:S1234) and pyopenfixer will use opencode to attempt to fix all the violations for that rule.

Features

  • Automatic branch discovery — Queries the SonarCloud Issues API to find the main branch instead of hardcoding a branch name
  • Full pagination support — Handles projects with thousands of issues
  • Three issue types — Fetches BUG, VULNERABILITY, and CODE_SMELL issues
  • Filterable results — All fields from the SonarCloud Issue object are preserved (severity, rule, line, message, status, assignee, etc.)
  • Importable — The main() function returns violations as a list, so you can import it into other scripts
  • Branch-aware diffing — On non-main branches, reports only violations that are new relative to main instead of the full list
  • Coverage reporting — Fetches and prints the code coverage percentage for each branch checked
  • Minimal dependencies — Only requires the requests library; the optional auto-fix feature additionally shells out to the opencode CLI if it's installed
  • CI/CD integration — Automatic SonarCloud analysis on every push and merge via GitHub Actions

Note on SonarQube Coverage Configuration

If you encounter an error like: "Invalid directory path in 'source' element: /home/runner/work/pyopenfixer/pyopenfixer", it's typically a configuration issue in your CI/CD setup or SonarQube configuration.

Ensure that:

  1. You are running coverage analysis with the correct path configuration
  2. The coverage report paths in sonar-project.properties match your current working directory
  3. If running locally, ensure you're generating coverage data in a directory that matches your SonarQube configuration

Installation

Prerequisites

  • Python 3.10+ (uses dictionary type hints with list[dict])
  • requests library
  • SONAR_TOKEN environment variable set to your SonarCloud user token with read_issues permission
  • You may need a free SonarCloud account (https://sonarcloud.io)
  • opencode CLI installed and available on your PATH — only required if you use the rule auto-fix feature; without it, fixing is skipped with a warning

Setup

Dependencies are pinned in pyproject.toml/uv.lock, with a hash-locked requirements.txt mirror used by CI. Pick one:

Using uv (recommended — installs requests plus the pinned test extras):

uv sync --extra test

Using pip with the hash-locked requirements file (matches CI exactly):

pip install --require-hashes -r requirements.txt

Minimal, unpinned install:

pip install requests

Configuration

Create (or edit) config.json at the project root:

{
     "sonarqube_url": "https://sonarcloud.io",
     "project_key": "my-organization:my-project"
}
Field Description Required
sonarqube_url Base URL of your SonarCloud/SonarQube instance (no trailing slash needed) Yes
project_key The exact project key as shown in SonarCloud/SonarQube (e.g., org:project) Yes

Generating Your SonarCloud Token

The token is loaded from the SONAR_TOKEN environment variable — it is not stored in any file.

  1. Log in to SonarCloud (https://sonarcloud.io)
  2. Click your avatar —> My Account —> Security
  3. Click Generate Token
  4. Name it (e.g., pyopenfixer)
  5. Leave scopes at default (read-only access to issues is enough)
  6. Copy the token

Setting the Environment Variable

Once you have your token, set the SONAR_TOKEN environment variable:

export SONAR_TOKEN="sqp_a1b2c3d4e5f6g7h8i9j0"

On Windows:

set SONAR_TOKEN=sqp_a1b2c3d4e5f6g7h8i9j0

In CI/CD pipelines, set SONAR_TOKEN as a secret environment variable in your pipeline settings.

Configuring GitHub Actions for SonarCloud Analysis

The repository includes a GitHub Actions workflow (.github/workflows/sonarcloud.yml) that automatically analyzes the project in SonarCloud on every push and pull request. To enable it:

  1. Create a SonarCloud project (if not already created) at https://sonarcloud.io/dashboard
  2. Copy the Project Key and Organisation Key
  3. Add them to your config.json
  4. Navigate to your repository on GitHub.com
  5. Go to Settings —> Secrets and variables —> Actions
  6. Click New repository secret
  7. Name the secret SONAR_TOKEN and paste the token you generated above
  8. Commit your changes

The workflow will trigger on:

  • push to branches main, master, or develop
  • pull_request of any type (opened, synchronize, reopened)

Each workflow run will:

  1. Checkout the repository with full history
  2. Set up Python 3.14
  3. Install dependencies
  4. Run the test suite
  5. Trigger a SonarCloud scan using the official SonarSource/sonarcloud-github-action@v3

No additional configuration is required.

Usage

Run as a script

python sonar_violations.py

Fix a specific rule automatically

main() reads the rule to fix from the second command-line argument (sys.argv[2]) — the first argument is currently unused, so any placeholder value must be passed in that position before the rule. Once given a rule, it filters violations to that rule and automatically runs opencode run on each match:

python sonar_violations.py _ java:S1858

This will:

  1. Fetch all violations from the project and branch
  2. Filter to only violations with rule == "java:S1858"
  3. For each matching violation, run:
    opencode run "fix the problem {message} in {component} on line {line}"

The opencode command receives a prompt built from the violation's message, component, and line fields, allowing AI to automatically remediate the issue. If opencode isn't on your PATH, each fix attempt is skipped with a warning instead of failing.

Fix with a different rule

python sonar_violations.py _ python:S301

Output on the main branch:

current git branch: main
main branch: main

on main branch - 142 violations from my-company:my-project on branch 'main':
    [MAJOR] BUG - src/utils.py (python:S125) at line 42: Variable name "x" is too short
    [CRITICAL] VULNERABILITY - src/auth.py (python:S2009) at line 101: "os.system" is a security risk
    ...

Severity summary:
 BLOCKER: 3
 CRITICAL: 5
 MAJOR: 12
 MINOR: 47
 INFO: 75

Total violations on 'main': 142

Code coverage summary for main: 82.4

Thank you for pushing PyOpenFixer 1.0.3! Please consider starring the project on GitHub: https://github.com/larrydiamond/pyopenfixer

Output on a feature branch (only violations new relative to main are shown):

current git branch: feature/my-branch
main branch: main

on branch 'feature/my-branch' (not 'main'):
 Total violations on 'feature/my-branch': 5
 Total violations on 'main': 142
 New violations on 'feature/my-branch' that are not found on 'main': 2

New violations on 'feature/my-branch' not in 'main':
    [MAJOR] BUG - src/new_feature.py (python:S125) at line 10: Variable name "x" is too short
    [MINOR] CODE_SMELL - src/new_feature.py (python:S1481) at line 22: Remove this unused local variable "tmp"

Severity summary:
 MAJOR: 1
 MINOR: 1

Code coverage summary for feature/my-branch: 78.1

Code coverage summary for main: 82.4

Thank you for pushing PyOpenFixer 1.0.3! Please consider starring the project on GitHub: https://github.com/larrydiamond/pyopenfixer

Note: If main has violations but your current branch reports zero, pyopenfixer prints a note that this can happen on free installations of SonarQube or free SonarCloud accounts, which may not run analysis on non-main branches.

Import as a module

from sonar_violations import main

violations = main()

# Filter by severity
critical = [v for v in violations if v.get("severity") == "CRITICAL"]

# Filter by type
vulnerabilities = [v for v in violations if v.get("type") == "VULNERABILITY"]

# Export to CSV or JSON
import json
with open("violations.json", "w") as f:
    json.dump(violations, f, indent=2)

Programmatic usage without loading config

from sonar_violations import fetch_violations, get_main_branch_name
import os
import requests

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {os.environ['SONAR_TOKEN']}"})

branch = get_main_branch_name(session, "https://sonarcloud.io", "my-key")
violations = fetch_violations(session, "https://sonarcloud.io", "my-key", branch)

What's Included

The violations list contains one dictionary per SonarQube issue. Each dictionary includes all fields from the SonarQube API response, such as:

Field Example Value Description
key "AAAABCDe12345" Unique issue ID
rule "python:S125" SonarQube rule identifier
severity "MAJOR" Severity: INFO, MINOR, MAJOR, CRITICAL, BLOCKER
type "BUG" Issue type: BUG, VULNERABILITY, CODE_SMELL
message "Replace this use of 'eval'." Rule description / violation message
component "src/auth.py" Source file path
line 47 Line number where issue is detected
status "OPEN" Issue status: OPEN, CONFIRMED, REOPENED, CLOSED, ACCEPTED
assignee "jdoe" Assigned developer
author "jdoe" Who created the issue
tags ["cert", "cwe-79"] Rule tags (CWE, OWASP, etc.)
creationDate "2024-01-15T10:30:00+0000" When the issue was created
updateDate "2024-03-20T14:00:00+0000" When the issue was last updated
effort "30min" Suggested fix effort
comments [...] List of comments on the issue
attachments [...] Attached screenshots/documents

See the SonarQube Issues API docs for the full schema.

Project Structure

├── .github/workflows/sonarcloud.yml   # GitHub Actions CI/CD
├── config.json.example                # Sample configuration (safe to commit)
├── config.json                        # Your actual config (gitignored — contains your token)
├── sonar_violations.py                # Main application logic
├── pyproject.toml                     # Project metadata and pinned dependencies
├── uv.lock                            # Full resolved dependency lock (uv)
├── requirements.in                    # Top-level dependency names (source for pip-compile/uv)
├── requirements.txt                   # Hash-locked dependencies used by CI
├── requirements.locked.txt            # Hash-locked dependencies (with extras)
├── sonar-project.properties           # SonarCloud/SonarQube scanner configuration
├── tests/                             # Unit tests (pytest)
│     └── test_sonar_violations.py
├── .gitignore                          # Prevents committing secrets
├── README.md                           # This file
└── AGENTS.md                           # Instructions for AI coding agents

Testing

Tests are written using pytest and can be run from the project root. If you installed with uv sync --extra test (see Setup), pytest is already available in .venv; otherwise:

pip install pytest
pytest

To run with verbose output:

pytest -v

To run a specific test class or file:

pytest tests/test_sonar_violations.py -v

To run a specific test method:

pytest tests/test_sonar_violations.py::TestLoadConfig::test_loads_valid_config -v

To see coverage:

pip install pytest-cov
pytest --cov=sonar_violations --cov-report=term-missing

The test suite covers:

  • TestLoadConfig (6 tests) — valid config, default path, missing file, missing keys, invalid JSON
  • TestGetCurrentBranch (5 tests) — normal branch, empty output, CalledProcessError, FileNotFoundError, custom cwd
  • TestIsBranchMain (3 tests) — matching branches, non-matching, case sensitivity
  • TestGetMainBranchName (3 tests) — returns main branch, fallback to "main", HTTP errors
  • TestFetchViolations (5 tests) — single page, multi-page pagination, empty list, correct params, HTTP errors
  • TestViolationSortKey (6 tests) — type ordering, severity ordering, unknown types/severities, rule/line tiebreakers
  • TestMain (3 tests) — missing token, successful run, skipping output on non-main branch

API Endpoints Used

Endpoint Purpose
GET /api/project_branches/list Discover main branch name
GET /api/issues/search Fetch paginated list of issues
GET /api/measures/component Fetch code coverage percentage for a branch

Error Handling

Scenario Behavior
config.json missing Prints error, exits with code 1
Missing config keys Prints which key is missing, exits 1
SONAR_TOKEN not set Prints error, exits with code 1
Invalid SonarQube URL requests raises ConnectionError
Invalid token SonarQube returns 401 — raises HTTPError
Invalid project key SonarQube returns 404 — raises HTTPError
Network timeout requests raises Timeout

You can wrap main() in a try/except if you want graceful handling:

try:
    violations = main()
except requests.exceptions.HTTPError as e:
    print(f"SonarQube error: {e}")
except requests.exceptions.ConnectionError:
    print("Could not connect to SonarQube. Check the URL in config.json.")
except json.JSONDecodeError:
    print("config.json is not valid JSON.")

GitHub Actions Workflow

The included .github/workflows/sonarcloud.yml workflow automatically analyzes your project with SonarCloud on every push and pull request. It will:

  1. Checkout the repository with full history (fetch-depth: 0)
  2. Set up Python 3.14
  3. Install dependencies (requests, pytest)
  4. Run the full test suite before analysis
  5. Trigger a SonarCloud scan using SonarSource/sonarcloud-github-action@v3

This ensures code quality is assessed on every merge, preventing regressions from being merged into your main branch.

About

Fixes Sonar code violations using OpenCode

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages