sonar-list-issues

What this skill does

# SonarQube — List Issues

Search for issues in a SonarQube project using the `sonarqube-cli`.

Unlike SonarQube MCP tools (which may use a default project from integration), **`sonar list issues` always requires `-p <project-key>`**. Resolve the key from the user-provided arguments or `sonar-project.properties` before running the CLI.

## Usage

```
sonar-list-issues                                          # issues in the current project
sonar-list-issues my-project                               # issues in a specific project key
sonar-list-issues my-project --severity CRITICAL           # filter by severity
sonar-list-issues my-project --types BUG,VULNERABILITY     # filter by type
sonar-list-issues my-project --statuses OPEN,CONFIRMED     # filter by status
sonar-list-issues my-project --rules python:S2077          # filter by rule key
sonar-list-issues my-project --tags security               # filter by tag
sonar-list-issues my-project --component src/auth/login.py # issues in a specific file
sonar-list-issues my-project --resolved                    # only resolved issues
sonar-list-issues my-project --branch main                 # on a specific branch
sonar-list-issues my-project --pr 42                       # on a pull request
```

## Prerequisites

This skill uses the `sonarqube-cli` command. The CLI must be installed and authenticated before proceeding.

**Before proceeding**, verify that `sonar` is available on your PATH and authenticated. If it is not, do not attempt to call any alternative commands or invent alternatives, and show the user:

> Unable to list issues.
>
> **Possible causes:**
> - `sonarqube-cli` not installed or not authenticated — invoke the sonar-integrate skill
> - Project key is wrong or missing — `-p` is mandatory for `sonar list issues`; invoke the sonar-list-projects skill or set `sonar.projectKey` in `sonar-project.properties`

Then ask the user (yes/no) whether to run the sonar-integrate skill now. If they confirm, invoke the sonar-integrate skill yourself and follow it end-to-end in this session, then re-check and continue; if they decline, stop.

## Instructions

### Step 1: Resolve the project key

This flow uses **`sonar list issues`** (CLI), not MCP. The CLI **always** needs **`-p <project-key>`** — do not invoke it without a resolved key.

- If the user provided a project key, use it.
- Otherwise look for `sonar.projectKey` in `sonar-project.properties` at the repo root.
- If still not found, **do not run** `sonar list issues`. Tell the user: *"Invoke the sonar-list-projects skill to find your project key, then re-run with that key,"* or add `sonar.projectKey` to `sonar-project.properties`. (MCP integration defaults do **not** apply to this CLI command.)

### Step 2: Parse optional flags from the user-provided arguments

| Flag                  | Maps to CLI option                                           |
| --------------------- | ------------------------------------------------------------ |
| `--severity <value>`  | `--severity`                                                 |
| `--types <values>`    | `--types`                                                    |
| `--statuses <values>` | `--statuses`                                                 |
| `--rules <values>`    | `--rules`                                                    |
| `--tags <values>`     | `--tags`                                                     |
| `--component <path>`  | `--component-keys` (file key format: `project-key:src/path`) |
| `--resolved`          | `--resolved`                                                 |
| `--branch <name>`     | `--branch`                                                   |
| `--pr <id>`           | `--pull-request`                                             |

When `--component` is given as a plain path, prepend the resolved project key to form the component key (e.g. `my-project:src/auth/login.py`).

### Step 3: Validate arguments

Before building the command, validate each user-supplied value against the following rules. If any value fails validation, stop and tell the user what was rejected and why — do not run the command. Validate the resolved project key (from args or `sonar-project.properties`) against the project-key pattern before running the CLI.

| Argument      | Allowed pattern                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| project key   | `^[a-zA-Z0-9_\-\.:]+$`                                                                                         |
| `--severity`  | one of: `BLOCKER`, `CRITICAL`, `MAJOR`, `MINOR`, `INFO`, `HIGH`, `MEDIUM`, `LOW`                               |
| `--types`     | comma-separated subset of: `BUG`, `VULNERABILITY`, `CODE_SMELL`, `SECURITY_HOTSPOT`                            |
| `--statuses`  | comma-separated subset of: `OPEN`, `CONFIRMED`, `REOPENED`, `RESOLVED`, `CLOSED`, `ACCEPTED`, `FALSE_POSITIVE` |
| `--rules`     | comma-separated values matching `^[a-zA-Z0-9_\-:]+$`                                                           |
| `--tags`      | comma-separated values matching `^[a-zA-Z0-9_\-]+$`                                                            |
| `--component` | file path matching `^[a-zA-Z0-9_\-\./:,]+$`                                                                    |
| `--branch`    | `^[a-zA-Z0-9_\-\./]+$`                                                                                         |
| `--pr`        | digits only                                                                                                    |

### Step 4: Run `sonar list issues`

Build and run the command using a shell command. **Always** pass **`-p`** with the key resolved in Step 1.

```bash
sonar list issues -p <project-key> --format toon [--severity <value>] [--types <values>] [--statuses <values>] [--rules <values>] [--tags <values>] [--component-keys <key>] [--resolved] [--branch <name>] [--pull-request <id>]
```

Only include optional flags that were provided.

### Step 5: Format the results

**If issues are found**, present a summary line then a table sorted by severity then line number:

```markdown
## SonarQube Issues — `my-project` (branch: `main`)

Found **12 issue(s)**:

| File                 | Line | Severity  | Rule         | Message                       |
| -------------------- | ---- | --------- | ------------ | ----------------------------- |
| src/auth/login.py    | 12   | 🔴 Blocker | python:S2077 | SQL injection risk            |
| src/utils/helpers.py | 34   | 🟠 High    | python:S2259 | Null dereference              |
| src/api/routes.py    | 67   | 🟡 Medium  | python:S3776 | Cognitive complexity too high |
```

Severity icons (the label depends on the server version):
- 🔴 Blocker
- 🟠 Critical / High
- 🟡 Major / Medium
- 🔵 Minor / Low
- ⚪ Info

**If no issues are found**:

```markdown
## SonarQube Issues — `my-project`

✅ No issues found.
```

### Step 6: Next steps

- To fix a specific issue: *"Ask me to fix `<rule>` at `<file>:<line>`."*
- To check the quality gate: *"Invoke the sonar-quality-gate skill."*