sonarqube

name	sonarqube
description	Fetch and analyze SonarQube quality metrics for pull requests, reporting on code quality, bugs, vulnerabilities, coverage, and code smells

SonarQube Analysis Skill

Automatically fetches and analyzes SonarQube quality metrics for pull requests, providing insights on code quality, test coverage, bugs, vulnerabilities, and technical debt.

Prerequisites & Hooks

This skill requires several conditions to be met before execution:

Hook 1: PR Existence Check

Objective: Verify a pull request exists for the current branch

Commands:

# Get current branch
git branch --show-current

# Check if PR exists
gh pr view --json number,title,state,url

Failure handling:

• If no PR exists: Provide instructions to create one first
• If PR is closed: Report status and ask if analysis is still needed
• If no gh CLI: Fallback to manual PR number input

Example output:

✅ PR #1386 found: "feat: Frontend Ownership Tracking for Data Combiners"
   Status: OPEN
   URL: https://github.com/hivemq/hivemq-edge/pull/1386

---

Hook 2: GitHub Actions Status Check

Objective: Ensure SonarQube analysis GitHub Action has completed

Commands:

# Get PR number from Hook 1
PR_NUMBER=$(gh pr view --json number -q .number)

# Check GH Actions status for this PR
gh pr checks $PR_NUMBER --json name,conclusion,status,detailsUrl

# Filter for SonarQube-related workflow
gh pr checks $PR_NUMBER --json name,conclusion,status,detailsUrl | \
  jq '.[] | select(.name | contains("SonarQube") or contains("sonarcloud") or contains("Code Quality"))'

Expected workflow names:

• "SonarQube Analysis"
• "SonarCloud Scan"
• "Code Quality"
• (configurable in config.yaml)

Statuses:

• ✅ conclusion: "success" → Proceed to Hook 3
• ⏳ status: "in_progress" → Wait or report estimated time
• ❌ conclusion: "failure" → Report failure, show logs URL, ask if should continue anyway
• 🔴 conclusion: "cancelled" → Report cancellation, suggest re-run

Failure handling:

• If action not found: Check config for workflow name
• If action failed: Show details URL, ask user if should continue with stale data
• If action in progress: Report estimated completion time, offer to wait

Example output:

✅ SonarQube Analysis: PASSED
   Duration: 2m 34s
   Completed: 5 minutes ago
   Details: https://github.com/hivemq/hivemq-edge/actions/runs/12345

---

Hook 3: SonarQube PR Data Availability

Objective: Verify SonarQube has analysis data for this PR

API Endpoint:

GET https://sonarcloud.io/api/measures/component
  ?component={project_key}
  &pullRequest={pr_number}
  &metricKeys=alert_status,bugs,vulnerabilities,code_smells,coverage,duplicated_lines_density

Fallback if PR data not found:

• Check branch analysis instead
• Report that PR-specific analysis is pending
• Suggest re-running GH workflow

Configuration (from config.yaml):

sonarcloud:
  base_url: https://sonarcloud.io
  organization: hivemq
  project_key: hivemq_hivemq-edge
  api_version: v1

Failure handling:

• If 404: SonarQube hasn't analyzed this PR yet
• If 401: Authentication issue (report, continue with public data)
• If 500: SonarQube service issue (report, suggest retry)

Example output:

✅ SonarQube data available for PR #1386
   Analysis date: 2026-02-10 14:32 UTC
   New code period: 2026-02-09 to 2026-02-10

---

Usage

Basic Usage

# Analyze current PR (auto-detect)
/sonarqube

# Analyze specific PR by number
/sonarqube 1386

# Analyze specific branch
/sonarqube feature/new-feature

Advanced Options

# Detailed report (includes file-level metrics)
/sonarqube --detailed

# Quality gate only (quick check)
/sonarqube --quality-gate-only

# Force analysis (bypass hooks)
/sonarqube 1386 --force

Arguments

• [PR number]: PR number (e.g., 1386) - auto-detected if omitted
• [branch]: Branch name (e.g., feature/new-feature) - auto-detected if omitted
• --detailed: Include file-level hotspots, detailed metrics
• --quality-gate-only: Show only pass/fail status
• --force: Skip Hook 1 and Hook 2 (go directly to Hook 3)

---

Skill Workflow

Phase 1: Prerequisites Check (Hooks)

Execute Hook 1, Hook 2, Hook 3 in sequence. If any fail:

• Report clear error message
• Provide actionable fix instructions
• Ask user if should continue anyway (with --force)

Skip with:

/sonarqube --force  # Skip PR and GH action checks

---

Phase 2: Fetch SonarQube Metrics

2.1 Quality Gate Status

API Call:

curl -s "https://sonarcloud.io/api/qualitygates/project_status?projectKey=hivemq_hivemq-edge&pullRequest=${PR_NUMBER}"

Extract:

• Overall status: PASSED / FAILED / ERROR
• Conditions: Each metric and its status
• Failing conditions: Which metrics failed the gate

Parse JSON:

{
  "projectStatus": {
    "status": "OK",
    "conditions": [
      {
        "status": "OK",
        "metricKey": "new_coverage",
        "comparator": "LT",
        "errorThreshold": "80",
        "actualValue": "85.3"
      }
    ]
  }
}

---

2.2 Core Metrics

API Call:

curl -s "https://sonarcloud.io/api/measures/component?component=hivemq_hivemq-edge&pullRequest=${PR_NUMBER}&metricKeys=alert_status,bugs,new_bugs,vulnerabilities,new_vulnerabilities,code_smells,new_code_smells,coverage,new_coverage,duplicated_lines_density,new_duplicated_lines_density,security_hotspots,new_security_hotspots,sqale_rating,new_maintainability_rating,reliability_rating,new_reliability_rating,security_rating,new_security_rating,ncloc,new_lines"

Metrics to fetch:

Quality Gate:

• alert_status - Overall gate status

Bugs:

• bugs - Total bugs (overall code)
• new_bugs - Bugs in new code (PR changes)

Vulnerabilities:

• vulnerabilities - Total vulnerabilities
• new_vulnerabilities - Vulnerabilities in new code

Code Smells:

• code_smells - Total code smells
• new_code_smells - Code smells in new code

Coverage:

• coverage - Overall test coverage %
• new_coverage - Test coverage % for new code

Duplications:

• duplicated_lines_density - % of duplicated lines (overall)
• new_duplicated_lines_density - % duplications in new code

Security Hotspots:

• security_hotspots - Total security hotspots
• new_security_hotspots - Security hotspots in new code

Ratings (A-E scale):

• sqale_rating / new_maintainability_rating - Maintainability
• reliability_rating / new_reliability_rating - Reliability
• security_rating / new_security_rating - Security

Lines of Code:

• ncloc - Total lines of code
• new_lines - New lines added in PR

---

2.3 Issues Breakdown (if --detailed)

API Call:

curl -s "https://sonarcloud.io/api/issues/search?componentKeys=hivemq_hivemq-edge&pullRequest=${PR_NUMBER}&statuses=OPEN,CONFIRMED,REOPENED&ps=100"

Group by:

• Severity: BLOCKER, CRITICAL, MAJOR, MINOR, INFO
• Type: BUG, VULNERABILITY, CODE_SMELL, SECURITY_HOTSPOT
• File: Group issues by file path

---

Phase 3: Generate Report

Generate a formatted markdown report with the following structure:

# SonarQube Analysis: PR #{pr_number}

**Project:** hivemq_hivemq-edge
**PR:** #{pr_number} - {pr_title}
**Analysis Date:** {timestamp}
**URL:** https://sonarcloud.io/summary/new_code?id=hivemq_hivemq-edge&pullRequest={pr_number}

---

## Quality Gate: {PASSED / FAILED}

{emoji} **{status_message}**

{If failed, list failing conditions}

---

## New Code Metrics (PR Changes)

| Metric               | Value                           | Status     | Threshold |
| -------------------- | ------------------------------- | ---------- | --------- |
| 🐛 Bugs              | {new_bugs}                      | {✅/❌}    | 0         |
| 🔒 Vulnerabilities   | {new_vulnerabilities}           | {✅/❌}    | 0         |
| 💡 Code Smells       | {new_code_smells}               | {✅/⚠️/❌} | < 10      |
| 📊 Coverage          | {new_coverage}%                 | {✅/⚠️/❌} | > 80%     |
| 📋 Duplications      | {new_duplicated_lines_density}% | {✅/⚠️/❌} | < 3%      |
| 🔐 Security Hotspots | {new_security_hotspots}         | {✅/⚠️/❌} | 0         |

---

## Overall Project Metrics

| Metric                   | Value             | Rating   | Trend          |
| ------------------------ | ----------------- | -------- | -------------- |
| 🐛 Total Bugs            | {bugs}            | {rating} | {↑/↓/→}        |
| 🔒 Total Vulnerabilities | {vulnerabilities} | {rating} | {↑/↓/→}        |
| 💡 Total Code Smells     | {code_smells}     | {rating} | {↑/↓/→}        |
| 📊 Overall Coverage      | {coverage}%       | {rating} | {↑/↓/→}        |
| 📏 Lines of Code         | {ncloc}           | -        | (+{new_lines}) |

---

## Ratings

- **Maintainability:** {maintainability_rating} ({A-E})
- **Reliability:** {reliability_rating} ({A-E})
- **Security:** {security_rating} ({A-E})

---

## {If --detailed} Issues Breakdown

### 🔴 Blocker Issues ({count})

{List of blocker issues with file:line}

### 🟠 Critical Issues ({count})

{List of critical issues}

### 🟡 Major Issues ({count})

{List of major issues}

---

## Recommendations

{If bugs > 0}

- ⚠️ **Fix {new_bugs} new bugs** before merging

{If coverage < 80%}

- ⚠️ **Improve test coverage** from {new_coverage}% to at least 80%

{If code_smells > 10}

- 💡 **Address {new_code_smells} code smells** to improve maintainability

{If quality_gate == "FAILED"}

- 🔴 **Quality gate failed** - Address issues above before merging

{If quality_gate == "PASSED"}

- ✅ **Quality gate passed** - Code meets quality standards

---

## Quick Actions

**View full analysis:**
https://sonarcloud.io/summary/new_code?id=hivemq_hivemq-edge&pullRequest={pr_number}

**View issues:**
https://sonarcloud.io/project/issues?id=hivemq_hivemq-edge&pullRequest={pr_number}

**Re-run analysis:**
\```bash
gh pr checks {pr_number} --rerun
\```

---

Configuration

Configuration is stored in .claude/skills/sonarqube/config.yaml:

sonarcloud:
  # Base URL for SonarCloud API
  base_url: https://sonarcloud.io

  # Organization key
  organization: hivemq

  # Project key
  project_key: hivemq_hivemq-edge

  # API version
  api_version: v1

github:
  # GitHub repository (owner/repo)
  repository: hivemq/hivemq-edge

  # Workflow names to check for SonarQube analysis
  workflow_names:
    - 'SonarQube Analysis'
    - 'SonarCloud Scan'
    - 'Code Quality'
    - 'CI' # Fallback if SonarQube runs in main CI

quality_gate:
  # Thresholds for metric interpretation
  thresholds:
    bugs: 0
    vulnerabilities: 0
    code_smells_warning: 5
    code_smells_error: 10
    coverage_warning: 70
    coverage_error: 80
    duplications_warning: 3
    duplications_error: 5

  # Rating interpretation (A=1, B=2, C=3, D=4, E=5)
  rating_pass: 2 # A or B acceptable

reporting:
  # Include detailed issues in report
  detailed_by_default: false

  # Max issues to show in report (per severity)
  max_issues_per_severity: 10

  # Show historical trends (requires multiple analyses)
  show_trends: true

  # Emoji mapping for statuses
  emoji:
    passed: '✅'
    failed: '❌'
    warning: '⚠️'
    info: 'ℹ️'
    bug: '🐛'
    vulnerability: '🔒'
    code_smell: '💡'
    coverage: '📊'
    duplications: '📋'
    security_hotspot: '🔐'

# Metadata
version: '1.0.0'
last_updated: '2026-02-10'
project: 'hivemq-edge-frontend'

---

Error Handling

Error 1: No PR Found (Hook 1 Failure)

Message:

❌ No pull request found for current branch: {branch_name}

**Next steps:**
1. Create a PR first:
   gh pr create --title "Your PR title" --body "Description"

2. Or specify a PR number:
   /sonarqube 1386

3. Or force skip PR check:
   /sonarqube --force

---

Error 2: GH Action Not Completed (Hook 2 Failure)

Message:

⏳ SonarQube analysis is still running...

**Status:** IN_PROGRESS
**Started:** 2 minutes ago
**Estimated completion:** ~3 minutes

**Options:**
1. Wait for completion (will auto-check every 30s)
2. Continue anyway with potentially stale data: /sonarqube --force
3. View action logs: https://github.com/hivemq/hivemq-edge/actions/runs/12345

---

Error 3: SonarQube Data Not Available (Hook 3 Failure)

Message:

❌ SonarQube has no analysis data for PR #1386

**Possible causes:**
1. Analysis hasn't run yet (GH action failed?)
2. PR is too new (analysis in progress)
3. SonarQube configuration issue

**Next steps:**
1. Check GH action status: gh pr checks 1386
2. Re-run GH workflow: gh pr checks 1386 --rerun
3. Wait a few minutes and try again
4. Check SonarQube project settings

---

Error 4: API Rate Limit

Message:

⚠️ SonarCloud API rate limit reached

**Options:**
1. Wait 60 seconds and retry
2. Use web interface: https://sonarcloud.io/summary/new_code?id=hivemq_hivemq-edge&pullRequest={pr_number}

---

Integration with Other Skills

With /pre-review Skill

Workflow:

# 1. Run pre-review first (local checks)
/pre-review

# 2. Fix critical issues

# 3. Create PR
gh pr create

# 4. Wait for CI to complete

# 5. Run SonarQube analysis
/sonarqube

# 6. Address SonarQube findings

# 7. Ready to merge!

Combined report:

• Pre-review catches local pattern violations
• SonarQube validates against broader quality metrics
• Both reports reference each other

---

Advanced Usage

Compare Multiple PRs

# Analyze multiple PRs
/sonarqube 1386
/sonarqube 1387

# Compare metrics manually

Branch Analysis (Without PR)

# Analyze a branch directly
/sonarqube feature/new-feature

Historical Trends

# Show how metrics changed over time
/sonarqube 1386 --trends

---

Testing the Skill

Test cases:

1. Happy path:

   /sonarqube  # Should auto-detect PR and fetch metrics
   

2. No PR:

   # On a branch without PR
   /sonarqube  # Should prompt to create PR or use --force
   

3. GH action in progress:

   /sonarqube  # Should wait or show progress
   

4. Failed quality gate:

   /sonarqube <pr_with_issues>  # Should show failing conditions
   

5. Detailed report:

   /sonarqube --detailed  # Should show issue breakdown
   

---

Future Enhancements

Planned features:

• Auto-comment on PR with quality metrics
• Trend analysis (compare with previous PRs)
• Blocker detection (prevent merge if critical issues)
• Integration with GitHub Status Checks
• Custom quality gate definitions
• Export metrics to CSV/JSON
• Slack/Teams notification integration
• Historical metrics visualization
• AI-powered issue prioritization

---

Hooks System (For Skill Developers)

Hook Definition

Hooks are prerequisite checks that must pass before the main skill logic runs.

Structure:

hooks:
  - id: hook-1
    name: 'Descriptive Name'
    objective: 'What this hook validates'
    commands: ['bash command to check']
    success_criteria: 'What indicates success'
    failure_handling: 'What to do on failure'
    can_skip: true/false
    skip_flag: '--force'

Hook execution:

1. Run in order (Hook 1 → Hook 2 → Hook 3)
2. If any hook fails and can_skip: false, abort skill
3. If can_skip: true, prompt user with options
4. If skip_flag provided, skip all skippable hooks

Example in skill:

### Hook 1: PR Existence Check

**Commands:**

```bash
gh pr view --json number,title,state
```

Success criteria:

• Exit code 0
• JSON contains "state": "OPEN"

Failure handling:

• Prompt user to create PR
• Or ask for manual PR number
• Or skip with --force

---

**Generated:** 2026-02-10
**Version:** 1.0.0
**Status:** Ready for use