sonar-llm-suggestion-pack

Generate an LLM-ready refactoring suggestion pack from:

• SonarQube issues
• LCOV uncovered lines
• Git PR diff

The CLI produces focused context instead of sending your whole repository to an LLM.

Why this tool

• Reduces token usage by scoping to changed files and high-signal findings.
• Lowers hallucination risk with concrete issue metadata and code snippets.
• Improves auditability with deterministic JSON/Markdown outputs.
• Works well in CI after sonar-scanner and coverage generation.

Table of Contents

• Requirements
• Installation
• Quick Start
• Configuration
• CLI Usage
• Output Files
• Filtering Rules
• CI Integration
• Troubleshooting
• Security Notes
• Local Development
• License

Requirements

• Node.js >=18
• A SonarQube project with API access
• A valid SonarQube User Token with at least Browse permission
• LCOV report (default: coverage/lcov.info)
• Git repository (recommended for PR-diff filtering)

Installation

Global install (recommended for CI runners)

npm install -g sonar-llm-suggestion-pack

Run via:

sonar-llm-suggestion-pack --help

Alias:

sonar-llm-suggestion --help

One-off with npx

npx sonar-llm-suggestion-pack --help

Quick Start

1. Create .env:

SONAR_HOST_URL=http://sonarqube.example.com
SONAR_TOKEN=your_user_token
SONAR_PROJECT_KEY=your_project_key
SONAR_BRANCH=main
BASE_REF=origin/main
HEAD_REF=HEAD
COVERAGE_PATH=coverage/lcov.info

2. Run:

sonar-llm-suggestion-pack

Run with explicit severity threshold:

sonar-llm-suggestion-pack --min-severity CRITICAL

3. Check outputs:

• llm_suggestion_pack/full_suggestion.md
• llm_suggestion_pack/full_suggestion.json
• llm_suggestion_pack/prompt_template.md
• llm_suggestion_pack/prompt_template.json
• llm_suggestion_pack/files/**
• Backward-compatible files: llm_suggestion.md, llm_suggestion.json

Configuration

Required environment variables

| Variable | Description | | --- | --- | | SONAR_HOST_URL | SonarQube server URL | | SONAR_TOKEN | SonarQube User Token | | SONAR_PROJECT_KEY | Sonar project key |

Optional environment variables

| Variable | Default | Description | | --- | --- | --- | | SONAR_BRANCH | (unset) | Sonar branch name | | BASE_REF | origin/main | Git diff base | | HEAD_REF | HEAD | Git diff head | | COVERAGE_PATH | coverage/lcov.info | LCOV report path | | OUTPUT_MD | llm_suggestion.md | Legacy Markdown output | | OUTPUT_JSON | llm_suggestion.json | Legacy JSON output | | OUTPUT_DIR | llm_suggestion_pack | Main output directory | | COMPLEXITY_THRESHOLD | 10 | Cognitive complexity threshold | | MIN_SEVERITY | MAJOR | Minimum Sonar severity to include | | SONAR_TIMEOUT_MS | 10000 | Timeout per Sonar API request (ms) | | SONAR_RETRY_COUNT | 2 | Retry count for transient Sonar/network failures | | SONAR_RETRY_BASE_DELAY_MS | 400 | Base delay for exponential backoff (ms) |

Precedence:

• CLI options override environment variables.
• Environment variables override built-in defaults.

CLI Usage

sonar-llm-suggestion-pack [options]

| Option | Description | Default | | --- | --- | --- | | --project <key> | SonarQube project key | SONAR_PROJECT_KEY | | --branch <name> | SonarQube branch | SONAR_BRANCH | | --min-severity <lvl> | Minimum severity (INFO/MINOR/MAJOR/CRITICAL/BLOCKER) | MIN_SEVERITY | | --base <ref> | Git base ref | origin/main | | --head <ref> | Git head ref | HEAD | | --coverage <path> | LCOV path | coverage/lcov.info | | --out-md <path> | Legacy Markdown output path | llm_suggestion.md | | --out-json <path> | Legacy JSON output path | llm_suggestion.json | | --out-dir <path> | Output directory | llm_suggestion_pack | | --threshold <number> | Complexity threshold | 10 | | -h, --help | Show help | - |

Supported formats:

• --key value
• --key=value

Examples:

# Generate pack for current branch diff against origin/main
sonar-llm-suggestion-pack --base origin/main --head HEAD

# Keep only CRITICAL/BLOCKER issues
sonar-llm-suggestion-pack --min-severity CRITICAL

# Custom output directory
sonar-llm-suggestion-pack --out-dir artifacts/llm_pack

Output Files

Example structure:

llm_suggestion_pack/
  full_suggestion.md
  full_suggestion.json
  prompt_template.md
  prompt_template.json
  files/
    src/
      auth/
        login.ts.md
        login.ts.json

full_suggestion.md

• Human-readable report
• Per-file issues, uncovered ranges, complexity findings
• Includes ready-to-use LLM instructions

full_suggestion.json

Top-level fields:

• generated_at
• summary
• llm_prompt
• files

Per-file fields:

• file
• changed_in_pr
• issues
• coverage.uncovered_lines
• coverage.uncovered_ranges
• complexity.score

prompt_template.*

Reusable templates for sending the generated suggestions to an LLM API.

Filtering Rules

By default, the tool includes only:

• Sonar issues with severity >= MAJOR
• LCOV uncovered lines for relevant files
• Files with cognitive_complexity > 10

Sonar API calls use timeout and retry by default:

• Timeout: 10s per request
• Retry count: 2 (total up to 3 attempts)
• Backoff: exponential from 400ms
• Retryable status codes: 408, 425, 429, 500, 502, 503, 504

Non-retryable errors (for example 401/403) fail fast.

When Git diff is available (BASE_REF...HEAD_REF), results are restricted to changed files. If the current directory is not a Git repository, diff filtering is skipped.

CI Integration

Recommended pipeline order:

test + coverage -> sonar-scanner -> quality gate -> sonar-llm-suggestion-pack

GitHub Actions

- name: Generate LLM suggestion pack
  run: sonar-llm-suggestion-pack --base origin/main --head HEAD
  env:
    SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
    SONAR_PROJECT_KEY: your_project_key
    SONAR_BRANCH: ${{ github.head_ref || github.ref_name }}

Bitbucket Pipelines

- step:
    name: Generate LLM suggestion pack
    script:
      - sonar-llm-suggestion-pack --base origin/main --head HEAD

Troubleshooting

Sonar API 401

• Token is missing, invalid, or expired.
• Verify SONAR_TOKEN is present and active.

Sonar API 403

• Token is valid but lacks permissions.
• Ensure token owner has at least Browse on the target project.

Browser works but CLI fails

• Browser uses logged-in session cookies.
• CLI uses SONAR_TOKEN via Basic Auth.

No changed files detected

• Confirm you are in a Git repository.
• Check BASE_REF and HEAD_REF.
• Ensure the base branch was fetched in CI.

No coverage findings

• Verify COVERAGE_PATH.
• Confirm LCOV contains records like DA:<line>,0.

Timeouts or transient network errors

• Increase SONAR_TIMEOUT_MS (for slow SonarQube servers).
• Increase SONAR_RETRY_COUNT if your CI network is unstable.
• Keep SONAR_RETRY_BASE_DELAY_MS moderate to avoid aggressive retries.

Security Notes

• Use SonarQube User Tokens, not hard-coded credentials.
• Store tokens in CI secrets, not in committed files.
• Rotate tokens periodically and use least-privilege access.

Local Development

From source:

git clone <your-repo-url>
cd sonar-llm-suggestion-pack
npm install
node index.js --help

License

Add a LICENSE file before public release and ensure package.json includes the license field.