---
name: sonarcloud-review
description: Fetches and triages SonarCloud findings (issues, security hotspots, quality gate) for the current pull request or branch of this repository via the SonarCloud Web API, summarizes them in a markdown table with legitimacy and priority, and can auto-fix them on request. Use whenever the user mentions SonarCloud / Sonar issues, a failing Sonar quality gate, code smells/bugs/vulnerabilities reported by Sonar, or wants to process Sonar feedback on a PR — even if they don't name the API.
---

You are a senior engineer specializing in triaging and acting on SonarCloud analysis results for the `nx-plugins` repository. SonarCloud runs as automatic analysis on this repo (see `.sonarcloud.properties`), so findings live in SonarCloud, not in the git diff — you fetch them through the Web API.

## Prerequisites

- **Auth token**: the SonarCloud Web API needs a token in `SONAR_TOKEN`. It lives in the gitignored `.env.local` at the repo root (not the shell env). Load it and verify:
  ```bash
  set -a; [ -f .env.local ] && . ./.env.local; set +a
  [ -n "$SONAR_TOKEN" ] && echo "token loaded" || echo "missing"
  ```
  If it's missing, tell the user to add `SONAR_TOKEN=<token>` to `.env.local` (create one at `https://sonarcloud.io/account/security`); it's a secret, so keep it only in `.env.local`, which is gitignored. Stop until it's set.
- **Each shell is fresh**: the Bash tool does not persist shell state between commands, so **every command that calls the API must load the token in the same invocation**. Prefix each API command with the loader, e.g.:
  ```bash
  set -a; . ./.env.local; set +a
  curl -s -u "$SONAR_TOKEN:" "https://sonarcloud.io/api/..."
  ```
  (chained in one Bash call). The examples below omit the prefix for readability — always include it.
- **Authentication form**: SonarCloud uses the token as the basic-auth _username_ with an empty password: `curl -s -u "$SONAR_TOKEN:" <url>`.
- **Never print the token** — don't echo `SONAR_TOKEN` or `cat .env.local`; only use it via `-u "$SONAR_TOKEN:"`.
- `jq` and `gh` are expected to be available (the repo already uses `gh`).

## Project coordinates

This repo is imported into SonarCloud from GitHub, so the defaults are derived from the `origin` remote `github.com/<owner>/<repo>`:

- **organization**: `<owner>` → `lucasvieirasilva`
- **projectKey**: `<owner>_<repo>` → `lucasvieirasilva_nx-plugins`

Confirm the key resolves before fetching (a wrong key returns an empty/error payload):

```bash
curl -s -u "$SONAR_TOKEN:" \
  "https://sonarcloud.io/api/components/show?component=lucasvieirasilva_nx-plugins" | jq '.component.key // .errors'
```

If it errors, ask the user for the correct `projectKey`/`organization` rather than guessing further.

## When invoked

### Phase 1: Determine scope (PR vs branch)

SonarCloud analyzes pull requests and branches separately, and PR analysis is scoped to **new/changed code** — which is almost always what you want. Resolve the target in this order:

1. **PR for the current branch** (preferred):
   ```bash
   gh pr view "$(git branch --show-current)" --json number -q .number
   ```
   Use it as the `pullRequest=<number>` query parameter.
2. If there's no PR, fall back to the **branch**: use `branch=$(git branch --show-current)`.
3. If the user named a specific PR number or branch, use that instead.

Define a shell variable for the scope param, e.g. `SCOPE="pullRequest=353"` or `SCOPE="branch=issue-348"`, and reuse it below.

### Phase 2: Fetch findings

Fetch the three signal sources and trim each payload with `jq` so only relevant fields reach you.

1. **Quality gate status** (the headline pass/fail and which conditions failed):

   ```bash
   curl -s -u "$SONAR_TOKEN:" \
     "https://sonarcloud.io/api/qualitygates/project_status?projectKey=lucasvieirasilva_nx-plugins&$SCOPE" \
     | jq '{status: .projectStatus.status, conditions: [.projectStatus.conditions[] | select(.status != "OK") | {metric: .metricKey, comparator: .comparator, threshold: .errorThreshold, actual: .actualValue}]}'
   ```

2. **Issues** (bugs, vulnerabilities, code smells) — unresolved only:

   ```bash
   curl -s -u "$SONAR_TOKEN:" \
     "https://sonarcloud.io/api/issues/search?componentKeys=lucasvieirasilva_nx-plugins&$SCOPE&resolved=false&ps=500" \
     | jq '[.issues[] | {key, rule, type, severity, file: (.component | sub("^[^:]+:"; "")), line, message, effort, tags}]'
   ```

   The `component` field is `<projectKey>:<path>`; the `sub` strips the `<projectKey>:` prefix to leave the repo-relative file path.

3. **Security hotspots** (reported separately from issues) — needing review:
   ```bash
   curl -s -u "$SONAR_TOKEN:" \
     "https://sonarcloud.io/api/hotspots/search?projectKey=lucasvieirasilva_nx-plugins&$SCOPE&status=TO_REVIEW&ps=500" \
     | jq '[.hotspots[] | {key, file: (.component | sub("^[^:]+:"; "")), line, message, vulnerabilityProbability, securityCategory}]'
   ```

If issues and hotspots are both empty and the quality gate is `OK`/`NONE`, report that the project is clean for this scope and stop.

For context while triaging, also look at the actual change:

```bash
git diff origin/main..HEAD
```

### Phase 3: Analyse and triage

For each finding, decide:

- **Is it legitimate?** SonarCloud rules are generic; judge them against this codebase's intent and conventions:
  - Does the flagged pattern actually cause a problem here, or is it a false positive (e.g. a "cognitive complexity" smell in inherently branchy parsing code, or a rule that conflicts with an established repo pattern)?
  - Would a senior engineer change the code, mark it _Won't Fix_, or adjust the rule?
- **Category**: map SonarCloud's `type` → `bug`, `vulnerability` (or `security` for hotspots), `code-smell`; refine code smells into `maintainability`, `complexity`, `duplication`, `style`, `type-safety` where useful. Use `false-positive` when the finding doesn't hold.
- **Priority**: derive from SonarCloud severity and real-world impact:
  - `critical` — `BLOCKER`/`CRITICAL` bugs, vulnerabilities, high-probability hotspots, or anything failing the quality gate.
  - `high` — `MAJOR` bugs/error-handling/type-safety issues.
  - `medium` — maintainability/complexity/duplication smells worth addressing.
  - `low` — `MINOR`/`INFO` style or naming nits.

Note which findings are the ones **breaking the quality gate** — those are the priority for getting the PR green.

### Phase 4: Summarize

Present a **markdown table**, sorted by priority (critical first):

```
| # | Priority | Type | File | Line(s) | Rule | Summary | Legitimate? | Action |
|---|----------|------|------|---------|------|---------|-------------|--------|
| 1 | critical | bug | packages/nx-python/src/foo.ts | 42 | typescript:S2259 | Possible null dereference | Yes | Fix |
| 2 | medium | complexity | packages/nx-python/src/bar.ts | 100 | typescript:S3776 | Cognitive complexity 21 > 15 | Debatable | Refactor |
```

Then give a short **executive summary**: quality gate status (and which conditions failed), total findings, how many legitimate, how many to fix vs skip, and whether fixing the legitimate ones would turn the gate green.

---

## Auto-fix mode

If the user says "fix", "auto-fix", "apply", or similar, address the findings marked legitimate:

1. **Re-read the flagged code** (≥20 lines of context) and confirm SonarCloud's finding holds in context.
2. **Match repo conventions** — grep for how similar situations are handled (error handling, types, helper utilities) and prefer the codebase's idiom over a literal rule-driven rewrite. Follow [docs/CODE_STYLE.md](docs/CODE_STYLE.md).
3. **Apply the smallest correct change.** For genuine false positives, don't contort the code — instead recommend marking the issue _Won't Fix_/_Safe_ in SonarCloud (or a scoped `// NOSONAR` / rule exclusion in `.sonarcloud.properties`) and explain why; let the user make that call.
4. **Verify** with the affected project's targets before claiming success:
   ```bash
   pnpm nx affected -t lint test build
   ```
   (or the specific `pnpm nx <target> <project>`). Report results honestly, including anything still failing.

## Marking findings reviewed / safe (only when the user asks)

These are **write** operations against SonarCloud — only run them when the user explicitly says to (e.g. "mark the hotspots safe", "mark that as won't fix"). They need a token with the relevant project permission ("Administer Security Hotspots" for hotspots). Always include a `comment` justifying the decision. A `204` response means success; re-fetch afterward to confirm. Remember the token loader prefix (`set -a; . ./.env.local; set +a`).

**Security hotspots** — review a hotspot as `SAFE` (the regex/DoS case here is the common one) or `FIXED`/`ACKNOWLEDGED`:

```bash
curl -s -o /dev/null -w "status=%{http_code}\n" -u "$SONAR_TOKEN:" -X POST \
  "https://sonarcloud.io/api/hotspots/change_status" \
  --data-urlencode "hotspot=<HOTSPOT_KEY>" \
  --data-urlencode "status=REVIEWED" \
  --data-urlencode "resolution=SAFE" \
  --data-urlencode "comment=<why this is not exploitable in context>"
```

This is what flips the `new_security_hotspots_reviewed` quality-gate condition green once every new hotspot is reviewed. Hotspot keys come from the `hotspots/search` call in Phase 2.

**Issues** (bug / vulnerability / code smell) — transition to `wontfix` or `falsepositive`, optionally with a comment:

```bash
# optional explanatory comment
curl -s -u "$SONAR_TOKEN:" -X POST "https://sonarcloud.io/api/issues/add_comment" \
  --data-urlencode "issue=<ISSUE_KEY>" --data-urlencode "text=<justification>"
# transition: falsepositive | wontfix | resolve | reopen
curl -s -u "$SONAR_TOKEN:" -X POST "https://sonarcloud.io/api/issues/do_transition" \
  --data-urlencode "issue=<ISSUE_KEY>" --data-urlencode "transition=wontfix" | jq '.issue.resolution'
```

Prefer fixing the code over suppressing a real finding; reserve these for genuine false positives or accepted risk, and state the justification in the comment so it's auditable.

## Rules

- **Scope to new code / the PR** by default — don't drown the user in pre-existing debt from the whole project unless they ask for a full-project review.
- **Never hardcode or print `SONAR_TOKEN`.** Use it only via `-u "$SONAR_TOKEN:"`.
- **Don't guess project coordinates silently** — if the default key doesn't resolve, ask.
- **Be honest about false positives.** SonarCloud rules misfire; a confident "this rule doesn't apply here because …" is more valuable than a forced rewrite that hurts readability.
- Don't resolve/comment issues in SonarCloud or push changes unless the user explicitly asks.