pi-sonarqube

A Pi extension to run local SonarQube analysis and browse the resulting issues — all from within Pi.

Requirements

• Pi installed
• A running SonarQube server (e.g. http://localhost:9000)
• sonar-scanner available in $PATH

Install

pi install npm:@jonathan0823/pi-sonarqube

Or add it to your settings.json:

{
  "packages": ["npm:@jonathan0823/pi-sonarqube"]
}

Then /reload in Pi.

Quick start

1. Init project config

Inside a project directory, run:

/sonarqube init

For monorepos, you can point at a path directly:

/sonarqube init apps/web
/sonarqube init apps/api

Pi will ask you for:

• SonarQube server URL (prefilled with http://localhost:9000)
• Project key (default: derived from directory name)
• Token (optional, used when your server requires auth)

The config is saved to <project>/.pi/sonarqube.json.

2. Run analysis

/sonarqube analyze
/sonarqube analyze apps/web
/sonarqube analyze apps/api

Pi will:

1. Run sonar-scanner against your server
2. Wait for the analysis to complete
3. Fetch the latest issues
4. Return a concise summary with issues and duplication metrics

3. Browse issues

/sonarqube issues
/sonarqube issues apps/web
/sonarqube issues apps/web in:src/components/

The target (apps/web above) is a configured alias or SonarQube project root. Use in: to scope issues to a file or directory inside that project.

Use Up/Down to move, Enter to preview the affected source code, Esc to close, and type to search by issue key, file, rule, severity, status, or message.

Tip: Tab-complete /sonarqube subcommands and filters in the editor.

4. View project metrics

/sonarqube metrics
/sonarqube metrics apps/web

Shows coverage percentage, duplicated lines, and issue severity breakdown — no scanner needed.

5. Browse duplicated files

/sonarqube duplications
/sonarqube duplications apps/web

Use Up/Down to move, Enter for block locations and line ranges, and type to search by file path or duplication stats. Pass a file number directly to skip the browser: /sonarqube duplications 1.

6. Open a specific issue

/sonarqube open 3
/sonarqube open apps/web 3
/sonarqube open apps/web issue:AZ123
/sonarqube open apps/web issue:AZ123,AZ456

Issue keys are stable across filtered queries; numeric positions refer only to the current query result.

Commands

Command	Description
/sonarqube init [path]	Set up project config for a path
/sonarqube analyze [target]	Run analysis and show issues + duplication metrics
/sonarqube issues [target] [in:<scope>]	Browse project issues, optionally scoped to a file or directory
/sonarqube metrics [target]	Show project metrics (coverage %, duplication %, issue counts, no scanner)
/sonarqube duplications [target]	Browse duplicated files and blocks with drill-down
/sonarqube open [target] <n>	Preview source at positional issue #n
/sonarqube open [target] issue:<keys>	Preview source for one or more stable issue keys

Tool (for the LLM)

The extension also registers a sonarqube tool that the LLM can call with actions:

• analyze — run analysis
• issues — list issues
• metrics — show project-level coverage, duplication & issue counts
• duplications — list duplicated files and block details
• open — open one or more issues by stable issueKeys (preferred) or positional issueIndex

For tool calls, path selects a configured target alias or SonarQube project root. pathScope selects a file or directory inside that project; do not pass source scopes as path.

The tool accepts optional issue filters (severities, statuses, types, rules, softwareQualities, impactSeverities) so the agent can fetch just the most relevant issues.

Filter families

SonarQube supports two filter families depending on the server mode:

• Standard Experience (legacy): type (BUG, VULNERABILITY, CODE_SMELL) and severity (BLOCKER, CRITICAL, MAJOR, MINOR, INFO)
• MQR mode: quality (MAINTAINABILITY, RELIABILITY, SECURITY) and impactSeverity (BLOCKER, HIGH, MEDIUM, LOW, INFO)

Both families can be used from the /sonarqube issues command:

/sonarqube issues type:BUG
/sonarqube issues severity:CRITICAL status:OPEN
/sonarqube issues quality:RELIABILITY
/sonarqube issues quality:SECURITY impactSeverity:HIGH

Important: Legacy filters and MQR filters cannot be combined in the same query. If you mix them (e.g., type:BUG quality:SECURITY), you'll see an error telling you to pick one family.

The server mode is auto-detected via the api/v2/clean-code-policy/mode endpoint and cached per session.

Use project-root paths directly for targets and in: / pathScope for source scopes.

Configuration sources (precedence order)

1. Environment variables (highest)
   • SONARQUBE_URL / SONAR_HOST_URL
   • SONARQUBE_TOKEN / SONAR_TOKEN
   • SONAR_PROJECT_KEY
2. Project config — .pi/sonarqube.json (set via /sonarqube init)
3. Scan properties — sonar-project.properties
4. Defaults — http://localhost:9000, project key from directory slug

Project structure

packages/pi-sonarqube/
├── src/
│   └── index.ts          # Extension source + init command + config
├── dist/
│   ├── index.js          # Compiled output
│   ├── index.d.ts        # Type declarations
│   └── index.js.map      # Source map
├── fixtures/
│   ├── issue-project/    # Test project with known issues
│   └── clean-project/    # Test project with no issues
├── README.md
├── LICENSE
├── package.json
└── tsconfig.json

Contributing

See CONTRIBUTING.md.

License

MIT