SonarQube

````instructions
---
name: sonarqube
description: 'Operate SonarQube end-to-end for local and CI workflows: configure analysis, run sonar-scanner, monitor Compute Engine tasks, evaluate Quality Gates, and remediate blockers (bugs, vulnerabilities, hotspots, code smells, coverage, duplication). Use when requests mention SonarQube or SonarCloud, failing quality gates, sonar-scanner, `sonar-project.properties`, or static-analysis compliance in pull requests/releases.'
---

# SonarQube

> **Agent-agnostic** — this skill works with any AI coding agent (Claude Code, GitHub Copilot, Codex, Cursor, Windsurf, etc.). All instructions use standard CLI tools and scripts.

## Overview

Run and remediate SonarQube analysis with deterministic, repeatable steps.
Prioritize gate-blocking issues first, then clean up non-blocking debt.

## Follow This Workflow

### 1. Validate prerequisites

- Confirm Sonar endpoint and credentials are available (`SONAR_HOST_URL`, `SONAR_TOKEN`).
- Confirm analysis configuration file exists (`sonar-project.properties`).
- Confirm scanner is available (`sonar-scanner` CLI or `npx sonar-scanner`).
- Confirm coverage artifact expectations before scanning.

### 2. Execute analysis

**PowerShell (Windows / cross-platform):**

```powershell
.github/skills/sonarqube/scripts/run-scan.ps1 -ProjectDir .
```

With preflight lint/build checks:

```powershell
.github/skills/sonarqube/scripts/run-scan.ps1 -ProjectDir . -Build
```

**Bash (Linux / macOS):**

```bash
# If sonar-scanner is installed globally:
sonar-scanner -Dsonar.host.url="$SONAR_HOST_URL" -Dsonar.token="$SONAR_TOKEN"

# Or via npx:
npx sonar-scanner -Dsonar.host.url="$SONAR_HOST_URL" -Dsonar.token="$SONAR_TOKEN"
```

### 3. Evaluate the Quality Gate

**By CE task ID (exact scan):**

```powershell
.github/skills/sonarqube/scripts/check-quality-gate.ps1 -CeTaskId "<ce-task-id>"
```

**By project key (latest scan):**

```powershell
.github/skills/sonarqube/scripts/check-quality-gate.ps1 -ProjectKey "<project-key>"
```

**Raw API (any shell):**

```bash
curl -u "$SONAR_TOKEN:" "$SONAR_HOST_URL/api/qualitygates/project_status?projectKey=<key>"
```

### 4. Fix in strict order

1. **Security**: vulnerabilities and high-risk hotspots.
2. **Reliability**: bugs likely to break runtime behavior.
3. **Gate metrics**: coverage and duplication breaches.
4. **Maintainability**: code smells and style debt.

### 5. Re-run until gate passes

- Keep changes minimal and focused on failing rules/metrics.
- Re-scan after each fix batch.
- Report before/after gate status and remaining risks.

## Use These Decision Rules

| Situation                      | Action                                                     |
| ------------------------------ | ---------------------------------------------------------- |
| Fast local scan                | Run `run-scan.ps1` or `npx sonar-scanner`                  |
| Exact gate for a specific scan | Run `check-quality-gate.ps1 -CeTaskId`                     |
| Branch/PR-scoped analysis      | Pass branch/PR scanner args via `-ExtraArgs` or `-D` flags |
| Project-specific setup         | Read `references/repo-profile.md`                          |
| Fix strategy by issue type     | Read `references/remediation-playbook.md`                  |

## Script Parameters

### `scripts/run-scan.ps1`

| Parameter                         | Description                                                                |
| --------------------------------- | -------------------------------------------------------------------------- |
| `-ProjectDir`                     | Repository root to analyze (default: `.`)                                  |
| `-HostUrl`                        | SonarQube URL (defaults to `SONAR_HOST_URL`, then `http://localhost:9100`) |
| `-Token`                          | Sonar token (`SONAR_TOKEN` fallback)                                       |
| `-Build`                          | Run `pnpm lint` and `pnpm build` before scanning                           |
| `-RequireCoverage`                | Fail fast if expected LCOV file is missing                                 |
| `-SkipCoverageCheck`              | Bypass local coverage-path checks                                          |
| `-WaitQualityGate`                | Automatically wait for CE completion and quality gate result               |
| `-GateTimeoutSec`, `-GatePollSec` | Tune quality gate polling                                                  |
| `-ExtraArgs`                      | Pass raw scanner args (branch, PR, exclusions, etc.)                       |

Example PR analysis:

```powershell
.github/skills/sonarqube/scripts/run-scan.ps1 `
  -WaitQualityGate `
  -ExtraArgs @(
    "-Dsonar.pullrequest.key=123",
    "-Dsonar.pullrequest.branch=feature/my-change",
    "-Dsonar.pullrequest.base=main"
  )
```

### `scripts/check-quality-gate.ps1`

| Parameter                 | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `-CeTaskId`               | Poll CE task and resolve exact analysis ID                 |
| `-ProjectKey`             | Fallback for latest project-level status                   |
| `-Branch`                 | Branch-specific gate check                                 |
| `-PullRequest`            | PR-specific gate check                                     |
| `-TimeoutSec`, `-PollSec` | Polling behavior                                           |
| `-AllowAnonymous`         | Allow unauthenticated API calls for public/local instances |

## Report Results in This Format

- Sonar host URL.
- Project key and branch/PR context.
- CE task ID and CE status (if used).
- Quality gate status (`OK`, `ERROR`, or `WARN`).
- Failing metrics/rules with actual values vs thresholds.
- Patch summary and re-scan outcome.

## Escalate Only When Needed

- Escalate authentication, connectivity, or server-health failures immediately.
- Escalate rule disputes only after confirming issue is not valid.
- Escalate gate-threshold changes only with explicit owner approval.

## References

- Repo setup and defaults: `references/repo-profile.md`
- Remediation tactics by issue class: `references/remediation-playbook.md`

````