dsh-sonarqube

dsh-sonarqube

English | 繁體中文 | 简体中文 | 日本語

dsh-sonarqube is a free, open-source, read-only DeepSeek Harness plugin for the
SonarQube Community Build Web API. It lets an agent inspect Quality Gates, issues,
Security Hotspots, coverage, duplication, and other project measures without changing
SonarQube state.

Issue and hotspot results include a normalized location object with the SonarQube
component key, source filePath, line, and text range when the API provides them.

Tools

Tool	Purpose
sonarqube_system_status	Read instance status and version.
sonarqube_quality_gate	Read a project's Quality Gate for the main analysis, a branch, or a pull request.
sonarqube_search_issues	Search issues by type, severity, status, branch, or pull request.
sonarqube_search_hotspots	Search Security Hotspots by status, branch, or pull request.
sonarqube_get_hotspot	Read the complete details for one Security Hotspot.
sonarqube_get_measures	Read coverage, duplication, issue counts, hotspots, or caller-selected metrics.

All tools are read-only. Version 0.1 does not assign, confirm, resolve, reopen, or otherwise
modify issues or hotspots.

Requirements

• DeepSeek Harness with compatible @deepseek-ai/dsh-tools APIs
• Node.js 22.19 or newer in the 22.x line, or Node.js 24 or newer
• Bun 1.3.5 or newer when installing from GitHub source or developing locally
• A SonarQube Community Build URL and a token with access to the requested projects

Live compatibility was manually validated on 2026-08-24 against SonarQube Community Build
26.8.0.126808 with SonarScanner CLI 8.0.1.6346. This does not imply compatibility with every
SonarQube release; verify the plugin against your own instance before relying on it in CI.

The live validation covered system status, Quality Gate, issue search with source-file and line
mapping, default measures, empty Security Hotspot search results, and safe hotspot 404 handling.
Community Build 26.8.0.126808 exposed no SECURITY_HOTSPOT rules, so a successful
sonarqube_get_hotspot response remains covered by mocked API tests rather than that live run.

Configuration

Environment variables are recommended so credentials do not appear in a profile patch:

export SONARQUBE_URL='https://sonarqube.example.com'
export SONARQUBE_TOKEN='your-token'

Plugin config takes precedence over environment variables:

Config	Environment fallback	Default
baseUrl	SONARQUBE_URL	required
token	SONARQUBE_TOKEN	required
requestTimeoutMs	none	30000
maxResponseBytes	none	5242880 (5 MiB)

Do not put token in cordis.patch.yml. If you need non-secret overrides, add a later profile
patch (later rows replace the row's whole config):

- id: dsh-sonarqube
  name: dsh-sonarqube
  config:
    baseUrl: 'https://sonarqube.example.com'
    requestTimeoutMs: 30000
    maxResponseBytes: 5242880

The bundle included in this package mounts the plugin without credentials:

- insert:
    - id: dsh-sonarqube
      name: dsh-sonarqube

Install

From a future npm release or a local tarball:

dsh plugin --profile web add dsh-sonarqube
dsh plugin --profile web add ./dsh-sonarqube-0.1.0.tgz

From GitHub source:

dsh plugin --profile web add github:maxmilian/dsh-sonarqube#PINNED_COMMIT

Git installs receive source rather than lib, so this package includes a prepare script that
builds with Bun. The profile installer may require explicit permission to run the dependency's
build script. Review the source, pin a commit, and allow the build only if you trust it.

Restart the selected DSH profile after installation. You can verify the composed layer without
booting it:

dsh --profile web --dump-config

Examples

Ask the agent:

Use sonarqube_quality_gate for project acme-api on branch main.
Search open CRITICAL issues in acme-api, 50 per page.
Get coverage and duplicated_lines_density for acme-api.
Show the full Security Hotspot with key AX_example.

branch and pull_request are mutually exclusive. Search page sizes are bounded to 1..100, and
page × page_size must stay within the first 10,000 results. A measures request accepts at most 20
metric keys, each at most 100 characters. With no metric list it requests:

coverage, duplicated_lines_density, bugs, vulnerabilities, code_smells, security_hotspots

Internationalization

Schemastery configuration descriptions are localized for English, Traditional Chinese,
Simplified Chinese, and Japanese. The map includes DSH's current en and zh IDs plus common
regional IDs: en-US, zh-CN, zh-TW, ja, and ja-JP. A locale is selectable only when the
DSH host registers it; the current core UI ships en and zh.

The current @deepseek-ai/dsh-tools API accepts one model-facing description string per tool and
parameter, so those descriptions remain in English. This avoids claiming runtime localization that
DSH cannot currently consume. Repository documentation is available through the language links at
the top of each README.

Security and error behavior

• Uses Authorization: Bearer ... and never returns or logs the token.
• Honors the DSH tool AbortSignal, a per-request timeout, and a maximum response size.
• Converts HTTP 401, 403, 404, 429, and 5xx responses into safe structured errors.
• Preserves safe Retry-After and SonarQube-Authentication-Token-Expiration metadata.
• Does not include SonarQube response bodies in errors.
• Does not support disabling TLS verification or self-signed certificate bypass in v0.1.

SonarQube's Web API is gradually moving toward API v2. Endpoints are intentionally centralized in
src/client.ts, not spread across tool definitions, so future migrations stay localized.

Development

This project uses Bun exclusively:

bun install --frozen-lockfile
bun run lint
bun run typecheck
bun run test --coverage
bun run build
bun pm pack

Tests use Vitest with mocked fetch; they do not require a live SonarQube server. Coverage gates
for lines, statements, functions, and branches are all set to at least 80%.

License

MIT