agentleFS
bislink360bislink360/semantic-markdown/.claude/skills/sonarqube-scan/SKILL.md

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

  • Other versions2 projects use a version of this.

    Word for word · 1

    1. bislink360/styled-markdown★ 6100% same

    Edited · 1

    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
  1. Distinctive:

    Run everything from the repository root (or a worktree root):

    line 26
  2. Very specific:

    Don't use a bare // NOSONAR without a rule and reason.

    line 68
  3. Distinctive:

    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.

    line 70
  4. Very specific:

    Never grow the baseline to make a release pass without asking.

    line 78
  5. Distinctive:

    Add a Static analysis block to the smd-release §5 summary:

    line 82
  6. Very specific:

    When new hand-written code folders are added (for example a new skill's scripts/), add them to sonar.sources in sonar-project.properties.

    line 100

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

FilePurpose
docker-compose.ymlSonarQube Community + Postgres (UI on 127.0.0.1:9000), and a scan profile with sonar-scanner-cli
scripts/sonar-scan.mjsStarts the server, bootstraps credentials, runs coverage + scanner, applies the gate, writes the report
baseline.jsonExisting 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

MomentCommandMust pass?
Before opening a feature PR into release/vX.Y.Zsonar-scan.mjsYes: 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.mjsYes, mandatory
Quick look while developingsonar-scan.mjs --no-coverageNo
Hardening passsonar-scan.mjs --strictOptional

Run everything from the repository root (or a worktree root):

node .claude/skills/sonarqube-scan/scripts/sonar-scan.mjs

Prerequisites: 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

  1. docker compose up -d for the server and waits until /api/system/status is UP.
  2. First run only: it replaces the default admin/admin password 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.
  3. It runs the unit tests with Node's built-in coverage, which writes extension/coverage/lcov.info. If the tests fail, the scan stops.
  4. It runs sonar-scanner in a container against the checkout, with sonar.projectVersion set to the version in extension/package.json.
  5. 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:

  1. Fix it. This is the default. Re-run the scan to confirm it's gone.
  2. 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 bounded

    Don't use a bare // NOSONAR without a rule and reason.

  3. Security hotspot that is safe: add a NOSONAR comment 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.
  4. 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-baseline

    This rewrites baseline.json from every current blocking finding. Review the diff so nothing new slips in, and commit it in its own chore(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 --strict was used
  • lines of code, coverage, duplication, bugs / vulnerabilities / code smells / hotspots
  • new findings fixed in this release, and any NOSONAR suppressions or baseline changes added, each with a one-line reason
  • the non-blocking findings worth a follow-up (top rules)

Maintenance

TaskCommand
Stop the server after the scanadd --down (data is kept)
Wipe the server, its data and the stored credentialssonar-scan.mjs --reset
Different port--port 9100 or SONAR_PORT=9100
Pin or upgrade imagesSONARQUBE_IMAGE=sonarqube:<tag> / SONAR_SCANNER_IMAGE=…; on upgrade the script runs the DB migration automatically
Admin password lostSONAR_ADMIN_PASSWORD=<pw> sonar-scan.mjs, or --reset
Server won't startdocker 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.