sonarqube-scan
Skill6 starsChanged yesterdayApache-2.0View on GitHub
Run static code analysis on the Semantic Markdown repository with a local SonarQube server in Docker Compose, and gate releases on its results — bugs, vulnerabilities, security hotspots, code smells, duplication, maintainability and coverage. Use this skill before every release (on the release branch, before tagging and before marking the tracking PR ready), before opening a feature PR, and whenever the user asks for a code-quality, static-analysis, SonarQube/Sonar, lint, "code smells", security-scan or maintainability check, or asks whether the code is clean enough to ship. Use together with the smd-release skill, which calls for this gate in its release steps.
2 other projects use a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- runehub-ai/rune-hubedited, first seen Nov 15, 2026
- bislink360/semantic-markdownword for word, first seen Nov 8, 2026
Other versions2 projects use a version of this.
Word for word · 1
- bislink360/semantic-markdown★ 6100% same
Edited · 1
- runehub-ai/rune-hub★ 620% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Run everything from the repository root (or a worktree root):
- Very specific: line 68
Don't use a bare // NOSONAR without a rule and reason.
- Distinctive: line 70
Existing debt that can't be fixed in this release: add it to the baseline, but only with the maintainer's explicit approval in chat.
- Very specific: line 78
Never grow the baseline to make a release pass without asking.
- Distinctive: line 82
Add a Static analysis block to the smd-release §5 summary:
- Very specific: line 100
When new hand-written code folders are added (for example a new skill's scripts/), add them to sonar.sources in sonar-project.properties.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
SonarQube gate
GitHub CI runs typecheck, tests and the compatibility check, but no static analysis. This skill fills that gap locally: a SonarQube Community server runs in Docker Compose on the maintainer's machine, analyses the current checkout, and blocks the release if it finds new problems. Nothing leaves the machine, and no CI secrets are needed.
| File | Purpose |
docker-compose.yml | SonarQube Community + Postgres (UI on 127.0.0.1:9000), and a scan profile with sonar-scanner-cli |
scripts/sonar-scan.mjs | Starts the server, bootstraps credentials, runs coverage + scanner, applies the gate, writes the report |
baseline.json | Existing findings a maintainer accepted as known debt. Reported, but not blocking |
/sonar-project.properties (repo root) | What is analysed: hand-written sources only, never dist/, bundled smd.cjs or media/vendor/ |
When to run it
| Moment | Command | Must pass? |
Before opening a feature PR into release/vX.Y.Z | sonar-scan.mjs | Yes: fix or justify new findings in the PR |
On the release branch, before release-check.mjs and before tagging (smd-release §4–5) | sonar-scan.mjs | Yes, mandatory |
| Quick look while developing | sonar-scan.mjs --no-coverage | No |
| Hardening pass | sonar-scan.mjs --strict | Optional |
Run everything from the repository root (or a worktree root):
node .claude/skills/sonarqube-scan/scripts/sonar-scan.mjsPrerequisites: Docker running, npm ci done in extension/. The first run pulls ~1 GB of images and takes a few minutes. Later runs reuse the running server and take about a minute.
What the script does
docker compose up -dfor the server and waits until/api/system/statusisUP.- First run only: it replaces the default
admin/adminpassword with a random one and creates an analysis token. Both are stored in~/.smd-sonar/state.json, outside the repository, so every worktree shares one server. To sign in to the UI, read the password from that file. Never commit it, paste it into chat, or put it in a PR. - It runs the unit tests with Node's built-in coverage, which writes
extension/coverage/lcov.info. If the tests fail, the scan stops. - It runs
sonar-scannerin a container against the checkout, withsonar.projectVersionset to the version inextension/package.json. - It waits for the server to process the analysis, then applies the gate and writes
.scannerwork/sonar-report.md.
Exit codes: 0 pass, 1 blocked, 2 infrastructure or usage error (Docker down, failing tests, server didn't start).
The gate
A finding blocks unless it is listed in baseline.json:
- an open issue of severity Blocker or High (Critical in standard mode), for bugs, vulnerabilities and code smells alike
- any open security issue, whatever its severity
- any security hotspot still "to review"
- with
--strict, Medium (Major) issues too
Lower-severity code smells, duplication and coverage are reported as non-blocking. Still mention them in the release summary.
SonarQube's own quality gate (Sonar way) is shown as informational. Its "new code" is measured against whatever this local server analysed earlier, so it differs between machines. The committed baseline is what makes the gate repeatable. If the Sonar way gate fails, look at the conditions it lists (for example coverage on new code) and mention them in the summary.
Handling findings
Work through the report's Blocking section. For each finding, in order of preference:
- Fix it. This is the default. Re-run the scan to confirm it's gone.
False positive or accepted risk in code we own: suppress it at the line with a reason, so the decision is committed and reviewed:
const re = new RegExp(pattern); // NOSONAR(typescript:S5852): pattern comes from the .smd spec, input length is boundedDon't use a bare
// NOSONARwithout a rule and reason.- Security hotspot that is safe: add a
NOSONARcomment with a reason as above. Or mark it Safe in the UI (http://localhost:9000/security_hotspots?id=styled-markdown) if the reason doesn't belong in code. UI reviews only live in the local server's volume, so prefer the comment. Existing debt that can't be fixed in this release: add it to the baseline, but only with the maintainer's explicit approval in chat. Then run:
node .claude/skills/sonarqube-scan/scripts/sonar-scan.mjs --update-baselineThis rewrites
baseline.jsonfrom every current blocking finding. Review the diff so nothing new slips in, and commit it in its ownchore(quality): …commit.
Never grow the baseline to make a release pass without asking. When a baselined finding is fixed, the report notes stale entries. Prune them with --update-baseline on a run that has no blocking findings, so the diff only removes lines.
Reporting (release summary)
Add a Static analysis block to the smd-release §5 summary:
- Result: PASS/BLOCKED, quality gate status, and whether
--strictwas used - lines of code, coverage, duplication, bugs / vulnerabilities / code smells / hotspots
- new findings fixed in this release, and any
NOSONARsuppressions or baseline changes added, each with a one-line reason - the non-blocking findings worth a follow-up (top rules)
Maintenance
| Task | Command |
| Stop the server after the scan | add --down (data is kept) |
| Wipe the server, its data and the stored credentials | sonar-scan.mjs --reset |
| Different port | --port 9100 or SONAR_PORT=9100 |
| Pin or upgrade images | SONARQUBE_IMAGE=sonarqube:<tag> / SONAR_SCANNER_IMAGE=…; on upgrade the script runs the DB migration automatically |
| Admin password lost | SONAR_ADMIN_PASSWORD=<pw> sonar-scan.mjs, or --reset |
| Server won't start | docker compose -f .claude/skills/sonarqube-scan/docker-compose.yml logs sonarqube. It needs about 4 GB of RAM for Docker |
When new hand-written code folders are added (for example a new skill's scripts/), add them to sonar.sources in sonar-project.properties. Never add generated output.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

