skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/dev-team/skills/sonar-review/lenses/bugs.md

@@ -0,0 +1,48 @@
+# Lens 1 — Bugs
+
+Sonar's **Bug** category is code that is **demonstrably broken or will break**: null dereferences, off-by-one, dead branches, resource leaks, race-shaped APIs, contracts that don't hold. Bugs are the highest-signal lens — every bug is, by Sonar's definition, a defect waiting to ship.
+
+## What you're looking at
+
+Pull the issues list, filter to `type=BUG`, then filter further to the changed-files set. Common bug rules to recognize on sight:
+
+| Rule family | Example IDs | What it catches |
+|---|---|---|
+| Null dereference | `javascript:S2259`, `java:S2259`, `python:S5713`, `csharpsquid:S2259` | `x.foo` where `x` can be null/None |
+| Off-by-one / loop bound | `S2440`, `S2189`, `S2583` | `<=` vs `<`, infinite loops, dead branches |
+| Resource leak | `S2095`, `S2093` | unclosed streams, files, DB connections |
+| Exception handling | `S2737`, `S108`, `S1166` | empty catch, swallowed throwables, `throw` lost in finally |
+| Equality / comparison | `S2159`, `S1698`, `S3403` | `==` on incompatible types, `equals` vs `==` |
+| Floating-point comparison | `S1244` | `if (x == 0.1)` |
+| Date / time | `S3725`, `S6353` | wrong timezone, deprecated `Date` mutation |
+| Promise / async (JS/TS) | `S4123`, `S6544` | unawaited promises, missing error handlers |
+| Mutable shared state | `S2386`, `S3008` | non-final static, mutable singletons |
+
+If the rule isn't in this list, look it up at `${SONAR_HOST_URL}/coding_rules?open=<rule-id>` — Sonar links every issue to its catalog page with examples.
+
+## How to phrase each finding
+
+Four parts, same as the report skeleton:
+
+1. **Where** — `file:line` + a 5–15 char quote of the offending code.
+2. **Rule + category** — `[BUG · javascript:S2259] Null dereference` — keep the rule ID literal.
+3. **Why it matters** — name the **runtime scenario**, not the rule. ✅ "When `req.body.discount` is omitted from the request, `discount.amount` throws `TypeError: Cannot read properties of undefined` — the endpoint 500s." ❌ "Possible null dereference."
+4. **Fix** — concrete. Either:
+   - **Paste-able patch** — a one-line guard, a `??`, an `if (x == null) return`, a `try/finally`. Quote the line numbers.
+   - **Pattern reference** — "Use the `withConnection` helper from `db.ts:14` instead of opening directly; it handles the `finally` close."
+
+## Calibration
+
+- **BLOCKER bug** ≈ ships a defect on the happy path or a security-shaped fault (e.g. unsanitized `eval`, SQL string concat). Treat as merge-blocking.
+- **CRITICAL bug** ≈ defect on a common error path (null on optional field, leak on retry). Fix before merge.
+- **MAJOR bug** ≈ defect on an uncommon path (rare race, edge encoding). Fix or file a follow-up issue.
+- **MINOR bug** is rare for the Bug category — usually means Sonar isn't sure. Verify before reporting.
+
+Trust Sonar's severity here; the Bug catalog is the most-calibrated of the five lenses.
+
+## Anti-patterns when reporting Bugs
+
+- ❌ Restating the rule name as the "why". The rule name is in the catalog — your job is the *scenario* in this codebase.
+- ❌ Fixing the symptom not the cause. ❌ "Wrap in try/catch and log." ✅ "The caller passes `null` from `getDiscount` when no promo applies — change `getDiscount` to return `{amount: 0}` instead of null, then this site needs no guard."
+- ❌ Down-grading a BLOCKER because it "looks fine to you". The bug catalog is mechanical — if Sonar caught a null deref, there's a path to it. Find the path or trust the rule.
+- ❌ Recommending `// NOSONAR` as the fix. Reserve that for documented exceptions; it's never the right answer for a Bug.

skilldrop_cli/data/packs/dev-team/skills/sonar-review/lenses/code-smells.md

@@ -0,0 +1,64 @@
+# Lens 4 — Code Smells
+
+The **maintainability** lens. Code smells aren't bugs or security issues — they're patterns Sonar predicts will slow future change. The catalog is large and noisy; this lens is where over-reporting hurts the report most.
+
+## What you're looking at
+
+Filter issues to `type=CODE_SMELL` and changed files. Common families on new code:
+
+| Family | Example IDs | Worth reporting on changed code? |
+|---|---|---|
+| Cognitive complexity | `S3776` | ✅ Yes — predictive of bugs |
+| Function / method length | `S138`, `S104` | ✅ Yes — but often a refactor target, not a one-line fix |
+| Parameter count | `S107` | ✅ Yes |
+| Duplicated string literals | `S1192` | 🟨 Maybe — only if literal is meaningful (URL, key) |
+| Magic numbers | `S109` | 🟨 Maybe — extract a constant if used > 2 places |
+| Unused imports / variables | `S1481`, `S1128` | ✅ Yes — trivial fix |
+| Empty methods / classes | `S1186`, `S1186` | ✅ Yes |
+| TODO / FIXME comments | `S1135` | ⚪ Info — surface in count, don't list each |
+| Naming conventions | `S100`, `S116` | 🟨 Only flag if the new identifier breaks the project's pattern |
+| `console.log` / `print` | `S2228`, `S1854` | ✅ Yes if not behind a logger |
+| Deprecated API use | `S1874` | ✅ Yes |
+| Commented-out code | `S125` | 🟨 Maybe — sometimes intentional (TODO + commented call) |
+
+The principle: **report what's actionable in this PR, summarize what isn't**. A finding the user can fix in five minutes is worth a line; a refactor finding that requires opening four files is worth one line in summary form.
+
+## How to phrase each finding
+
+Standard four parts:
+
+1. **Where** — `file:line` + a quote.
+2. **Rule + category** — `[SMELL · typescript:S3776] Cognitive complexity 22 > 15`.
+3. **Why it matters** — the *future-maintenance* cost, in concrete terms. ✅ "`processOrder` has six nested conditionals; the next person debugging a refund flow has to trace all six to know which branch they're in." ❌ "Code is too complex."
+4. **Fix** — concrete:
+   - Complexity → extract one of the conditional branches into a named function. Suggest the name.
+   - Long parameter list → struct/object parameter. Name the fields.
+   - Magic number → name the constant. Suggest the name and the scope (file-level vs class-level).
+   - Duplicated literal → suggest the constant name + the line numbers that should reference it.
+
+## Calibration
+
+Sonar's severity on code smells is **less reliable** than on bugs/vulns — the same `S3776` is CRITICAL when complexity is 30 and MAJOR when it's 16. Trust the severity, but don't expect every CRITICAL smell to actually block merge.
+
+| Severity | Treat as |
+|---|---|
+| 🟥 BLOCKER | Rare for smells; usually means complexity is extreme (>25). Treat as merge-blocker. |
+| 🟧 CRITICAL | High-cost smell on load-bearing code. Fix before merge. |
+| 🟨 MAJOR | Most common smell severity. Fix if cheap; defer if the refactor is large. |
+| ⚪ MINOR | Style + naming. Roll up into a count if there are > 5. |
+
+## Aggregation rule
+
+If the new code has more than **8 minor code smells of the same rule** (e.g. 12 magic numbers in one file), don't list each — emit one rolled-up finding:
+
+> 🟨 **`typescript:S1192` — String literal duplication × 12** in `src/api/orders.ts`. The literal `"USD"` appears 12 times across `createOrder`, `applyDiscount`, and `formatTotal`. Extract `const CURRENCY = "USD"` at the top of the file and reference it from each site.
+
+Don't bury single-instance findings in rollups — only roll up repeats of the same rule in the same area.
+
+## Anti-patterns when reporting Code Smells
+
+- ❌ **Listing every smell**. The report becomes unreadable. Prioritize, aggregate, summarize the tail.
+- ❌ **Recommending a rename as the fix for a complexity smell.** Renaming doesn't reduce complexity. Extract a function or flip a guard clause.
+- ❌ **Flagging style on a PR that fixes a bug.** If the change is a targeted bug fix and the smells are pre-existing in the same function, those go in the "pre-existing issues touched" FYI section, not the main report.
+- ❌ **Treating `S1192` (string duplication) as serious in tests.** Tests are *supposed* to repeat literals — that's how you read them. If Sonar flags `"alice"` appearing 8 times across tests, downgrade to nit or drop.
+- ❌ **Confusing "long function" with "complex function".** A 200-line function with no branching is fine; a 30-line function with seven nested `if`s is the smell. Cite `S3776` (cognitive complexity), not `S138` (length), when complexity is the real issue.

skilldrop_cli/data/packs/dev-team/skills/sonar-review/lenses/coverage-and-duplication.md

@@ -0,0 +1,74 @@
+# Lens 5 — Coverage + Duplication
+
+These aren't "issues" in Sonar's data model — they're **quality-gate conditions** measured against the project's new code. They're reported in the gate's `conditions` array, not the issues list. They're often what fails an otherwise-clean gate.
+
+## Coverage on new code
+
+Sonar measures *lines and branches added or modified in this branch*. A file that wasn't touched contributes nothing to the new-code coverage metric; touching it forces the touched lines into the measurement.
+
+**Default gate condition:** ≥ 80% coverage on new code.
+
+### What to report
+
+Fetch the gate JSON, find conditions where `metricKey=new_coverage` and `status=ERROR`. Then drill into:
+
+```bash
+curl -s -u "$SONAR_TOKEN:" \
+  "$SONAR_HOST_URL/api/measures/component_tree?component=$PROJECT_KEY&branch=$BRANCH&metricKeys=new_uncovered_lines,new_lines_to_cover&qualifiers=FIL"
+```
+
+Identify the files dragging the percentage down. Report:
+
+> ❌ **Coverage on new code: 71%** (gate requires ≥ 80%)
+> - `src/jobs/export.ts` — 47/82 new lines covered (57%). Uncovered: error paths at lines 55–62 and 71–78.
+> - `src/api/checkout.ts` — 31/40 new lines covered (78%). Uncovered: the new `null discount` branch at line 47.
+>
+> **Fix:** Add three tests covering the error paths in `export.ts` and the null-discount branch in `checkout.ts`. The happy path is already covered.
+
+### Naming the missing tests
+
+Don't say "add tests" — name them. ✅ "Add a test `it('returns empty when upstream API 500s', ...)` covering `export.ts:55–62`." ❌ "Improve test coverage."
+
+If you can't name the missing test scenario, the coverage finding isn't actionable — you don't understand the uncovered branch well enough to flag it as a finding. Drop it and let the gate fail until the user adds the case themselves.
+
+### When coverage looks worse than it is
+
+- **Tests in changed dirs not running.** The coverage tool ran but didn't include the new tests. Symptom: 0% on a file that clearly has tests beside it. Check `sonar.tests` and the coverage report path in `sonar-project.properties`.
+- **Coverage exclusions stripped the wrong files.** Symptom: clearly-covered file shows uncovered. Check `sonar.coverage.exclusions`.
+- **Generated files counted.** Symptom: lots of "uncovered" in `__generated__` or `dist/`. Add to `sonar.exclusions`.
+
+If you suspect a config issue, **say so explicitly** rather than reporting the bad number as fact: "Coverage shows 0% on `src/payments/`, but `payments.test.ts` exists at the same level — the coverage importer may not be picking up the report. Check `sonar.javascript.lcov.reportPaths` in `sonar-project.properties`."
+
+## Duplication
+
+**Default gate condition:** ≤ 3% duplicated lines on new code.
+
+Duplication catches copy-paste — a block of ≥ 100 tokens (≈ 10 lines for most languages) that appears more than once. The catalog rule is `common-{language}:DuplicatedBlocks`.
+
+### What to report
+
+For each duplication block on changed code:
+
+> 🟨 **Duplication: `src/api/checkout.ts:47–78` duplicates `src/api/refund.ts:32–63`** (32 lines, 89% match).
+>
+> The discount-application logic is now copied across both endpoints — the next change to discount handling has to be made twice. Extract `applyDiscount` into `src/lib/discounts.ts` and call it from both.
+
+If duplication is *within* the same file, treat it as a single-file refactor — extract a helper at the file top.
+
+If duplication is *between* a new file and an existing one, the fix usually means modifying the existing file too. Flag this explicitly — the user may have been told not to touch the other file. Suggest the extraction location, then let them decide.
+
+### When duplication is intentional
+
+Sometimes duplication is correct — test fixtures, parallel implementations across services, migration scripts that intentionally mirror old code. If you can see this is the case (e.g. the duplicated code is in `tests/` or named `migrate_*`), say so:
+
+> 🟨 **Duplication: `tests/checkout.test.ts:47–78` duplicates `tests/refund.test.ts:32–63`**.
+>
+> The two tests share setup. This is the common-fixture case — extract `setupTestOrder()` into `tests/_helpers.ts`. Not a quality-gate blocker (tests are excluded by default in `sonar.coverage.exclusions` but counted for duplication unless excluded explicitly).
+
+## Anti-patterns when reporting Coverage / Duplication
+
+- ❌ **Reporting the percentage without the files dragging it.** "Coverage is 71%" isn't actionable. Name the under-covered files and the uncovered branches.
+- ❌ **Demanding 100% coverage** on the new code. The gate asks for 80% (or whatever the project sets); 100% is rarely worth the test brittleness.
+- ❌ **Demanding tests for log statements / pass-through error paths.** Coverage of a `console.log(...)` line teaches nothing. Suggest the *meaningful* missing scenarios.
+- ❌ **Treating duplication in tests as urgent.** Test fixtures often repeat; the refactor is "nice to have", not gate-blocking, and Sonar agrees if `sonar.cpd.exclusions` is set on `**/*.test.*`.
+- ❌ **Telling the user to disable the gate condition.** The fix is more tests or a small refactor, not weakening the gate. If 80% is structurally impossible for this project, raise it as a separate gate-tuning conversation, not a per-PR finding.

skilldrop_cli/data/packs/dev-team/skills/sonar-review/lenses/security-hotspots.md

@@ -0,0 +1,56 @@
+# Lens 3 — Security Hotspots
+
+Hotspots are the lens most agents get wrong. They are **not** vulnerabilities. They are **security-sensitive code patterns Sonar can't auto-decide are safe** — the resolution is a *human security review*, recorded in Sonar as **Safe**, **At Risk**, or **Acknowledged**.
+
+Hotspots come from a **different API** (`/api/hotspots/search`) than Issues. The quality gate counts unresolved hotspots — so an un-reviewed hotspot fails the gate even if the code is secure.
+
+## What you're looking at
+
+| Family | Example IDs | What it catches |
+|---|---|---|
+| Cryptographic operations | `S4426`, `S2278` | Use of crypto APIs (could be configured weakly) |
+| Random number generation | `S2245` | `Math.random()` / `Random` — fine for UI, dangerous for tokens |
+| Regex DoS | `S5852` | Catastrophic backtracking patterns |
+| File permissions | `S2612` | World-writable file creation |
+| Authentication / authorization | `S5332` | TLS disabled, `verify=False`, `--insecure` |
+| User-controlled file paths | `S2083` (sometimes Hotspot) | Where validation might be present |
+| Hardcoded IPs / CIDR | `S1313` | Could be a test fixture, could be a backdoor |
+| Cookie / session config | `S2092`, `S3330` | Missing flags Sonar can't verify in context |
+| HTTP method overrides | `S5122` | CORS / `_method` rewriting |
+| Command execution | `S4721` | `exec`-shaped calls (may be safe with constants) |
+
+## How to phrase each Hotspot finding
+
+This lens has **five** parts, not four — because the artifact you produce isn't "fix this", it's "evidence for the user to make a decision":
+
+1. **Where** — `file:line` + the sensitive call. Quote 5–15 chars.
+2. **Rule + category** — `[HOTSPOT · javascript:S2245] Pseudorandom generator use`.
+3. **Why it's flagged** — what *category* of risk Sonar is asking about. ✅ "`Math.random()` is fine for UI shuffling but unsafe for security tokens." ❌ "Insecure RNG."
+4. **Evidence for review** — what *this codebase* tells you about whether the usage is actually risky. Quote the surrounding context:
+   - Where does the value flow next? (logged? sent? stored? returned to user?)
+   - Are there upstream guards? Quote them with `file:line`.
+   - Is this test/dev-only code? Quote the file path or test scaffolding around it.
+5. **Action** — name the **resolution the user should record in Sonar**, with the reasoning they should paste into the resolution comment:
+   - **Safe** — quote the upstream guard or the non-security usage that makes it OK.
+   - **At Risk** — name the path you can't rule out + the code fix.
+   - **Acknowledged** — for known issues with a tracked follow-up. Include the ticket reference.
+
+## Calibration
+
+Hotspots don't carry the BLOCKER/CRITICAL/MAJOR severities issues do — they have a **review priority** (`HIGH`/`MEDIUM`/`LOW`) and a **status** (`TO_REVIEW`/`REVIEWED`). Map to your report:
+
+| Hotspot priority | Report marker |
+|---|---|
+| HIGH | 🟧 |
+| MEDIUM | 🟨 |
+| LOW | ⚪ |
+
+Group hotspots in their own section — don't intermix with bugs/vulnerabilities. They're a different shape of finding.
+
+## Anti-patterns when reporting Hotspots
+
+- ❌ **Treating Hotspots like Vulnerabilities.** A Hotspot isn't a defect — it's a question. Reporting "fix this insecure RNG" when the value flows to a UI shuffle is wrong; the answer is "mark Safe with this evidence."
+- ❌ **Recommending a code patch without naming the resolution.** A code patch alone doesn't clear the hotspot in Sonar — the user still needs to mark it Reviewed. Always include "and mark `<status>` in the Sonar UI with the evidence above".
+- ❌ **Skipping the evidence step.** "Looks fine to me" isn't actionable. Quote the upstream guard or the test-only usage that lets the user click Safe with confidence.
+- ❌ **Marking everything At Risk to be cautious.** If the evidence is "no upstream guard, flows to user output", say At Risk. If the evidence is "constant string from build config, never user-influenced", say Safe. Hedging defeats the workflow.
+- ❌ **Forgetting that un-reviewed hotspots fail the gate.** Even a clearly-safe hotspot fails the gate until reviewed. Tell the user explicitly: "marking this Safe is what unblocks the gate — not a code change."

skilldrop_cli/data/packs/dev-team/skills/sonar-review/lenses/vulnerabilities.md

@@ -0,0 +1,52 @@
+# Lens 2 — Vulnerabilities
+
+Sonar's **Vulnerability** category is code where **Sonar is confident an attacker can exploit it**: injection, weak crypto, hard-coded secrets, broken auth flows, unsafe deserialization. Different from **Hotspots** (lens 3) — Hotspots are "this *could* be unsafe, a human needs to look"; Vulnerabilities are "this *is* unsafe by the catalog's definition".
+
+Every Vulnerability on new code is a **gate failure** under the default Sonar way. Treat as merge-blocking.
+
+## What you're looking at
+
+Pull the issues list, filter to `type=VULNERABILITY`, intersect with changed files. Common rule families:
+
+| Family | Example IDs | What it catches |
+|---|---|---|
+| SQL injection | `javascript:S3649`, `java:S3649`, `python:S3649` | String-concatenated queries |
+| Command injection | `S2076`, `S4036` | `exec(\`tar ${user}\`)`, `Runtime.exec(userInput)` |
+| Path traversal | `S2083`, `S6549` | `fs.readFile(userInput)` without normalization |
+| XSS | `javascript:S5247`, `S5131` | `innerHTML = userInput`, unescaped template output |
+| SSRF | `S5144` | HTTP client URL built from user input |
+| Hard-coded secrets | `S6418`, `S2068` | API keys, passwords, tokens in source |
+| Weak crypto | `S2278`, `S5547`, `S4790` | MD5/SHA1 for auth, ECB mode, deprecated TLS |
+| Insecure cookie | `S2092`, `S3330` | `httpOnly: false`, missing `secure` flag |
+| Open redirect | `javascript:S5146` | `res.redirect(userInput)` |
+| Unsafe deserialization | `S5135` | `pickle.loads(network_bytes)`, Java `ObjectInputStream` |
+| Permissive CORS | `S5122` | `Access-Control-Allow-Origin: *` with credentials |
+
+Every Vulnerability rule is tagged with **CWE** and (where applicable) **OWASP Top 10** identifiers — surface these in the finding so the user can map to compliance frameworks.
+
+## How to phrase each finding
+
+1. **Where** — `file:line` + the offending expression. Quote enough to make the data flow obvious.
+2. **Rule + category + standards tags** — `[VULNERABILITY · javascriptsecurity:S3649 · CWE-89 · OWASP A03:2021] SQL injection`.
+3. **Why it matters** — describe the **exploit path**, not the rule. ✅ "`userId` flows from `req.params.id` into the SQL string at line 42 without escaping — an attacker can send `1 OR 1=1` and read every row of the table." ❌ "Possible SQL injection."
+4. **Fix** — concrete and **the right one**:
+   - SQL injection → parameterized query / prepared statement, with a code snippet using the project's existing DB client. Quote the right call from elsewhere in the codebase if available.
+   - Command injection → `execFile(cmd, [args])` not `exec(cmd + args)`; never `shell: true` with user data.
+   - XSS → contextual escaping (text vs attribute vs URL vs JS), or the framework's safe primitive (`.textContent` not `.innerHTML`; `{}` not `{{{}}}`).
+   - Hard-coded secret → move to env/secret manager, **rotate the leaked value**, and call out the rotation explicitly — finding it in source means it was committed and is in git history.
+   - Weak crypto → name the replacement algorithm (e.g. `SHA-256 + HMAC`, `bcrypt/argon2`, `AES-256-GCM`).
+
+## Calibration
+
+- **BLOCKER vulnerability** — direct injection / hard-coded prod credential / known-broken crypto on auth. Stop the merge; in some cases stop the deploy (rotate creds, audit access).
+- **CRITICAL vulnerability** — exploit requires a slightly less trivial path (chained, requires auth, narrow window). Fix before merge.
+- **MAJOR vulnerability** — defense-in-depth issue (missing flag, weak default). Fix before merge if reasonable.
+
+Do not down-grade these. If you think Sonar is wrong, mark it for the user to dispute via the Sonar UI (`Resolve as won't fix` / `false positive`) — don't silently drop it from the report.
+
+## Anti-patterns when reporting Vulnerabilities
+
+- ❌ Suggesting input validation as the fix for injection. Validation is defense in depth; **parameterization** is the fix. ❌ "Validate the user ID looks like a number." ✅ "Use `db.query('SELECT * FROM users WHERE id = $1', [userId])` — never concatenate."
+- ❌ Forgetting the rotation step on a leaked secret. If a key was in source, it leaked; "remove the line" without "rotate the value" leaves the exposure live.
+- ❌ Listing the rule's CWE without using it. The CWE tag is for the user's report, not your decoration — include it so they can answer "is this our SOC 2 finding?".
+- ❌ Recommending the user mark it "won't fix" to pass the gate. The gate is the point. If it's truly a false positive, the resolution path is via the Sonar UI's `false positive` workflow, with a comment — not a CI-bypass.

skilldrop_cli/data/packs/dev-team/skills/sonar-review/manifest.json

@@ -0,0 +1,37 @@
+{
+  "name": "sonar-review",
+  "version": "0.1.0",
+  "description": "Run a Sonar scan against the just-changed code on the current branch and produce a structured compliance report — quality-gate verdict (PASS / FAIL), then severity-tagged findings (🟥 blocker / 🟧 critical / 🟨 major / ⚪ minor / ⚪ info) scoped to changed files, each with file:line, the Sonar rule ID, the category (bug / vulnerability / security hotspot / code smell), why it matters, and a concrete fix. Works against both **SonarQube server** (self-hosted) and **SonarCloud** (SaaS) — mode is detected from `sonar-project.properties`. Sister skill to `devils-advocate`, but enforces Sonar's rule catalog and the project's quality gate rather than a hand-rolled lens sweep. Use after writing code, before pushing or opening a PR, when the user says \"is this Sonar-compliant?\", \"run Sonar on this\", \"will the quality gate pass?\", or any pre-merge compliance check.",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [
+      "SONAR_TOKEN"
+    ],
+    "optional": [
+      "SONAR_HOST_URL"
+    ]
+  },
+  "related": [
+    "devils-advocate",
+    "sonar-onboard"
+  ],
+  "tags": [
+    "sonarqube",
+    "sonarcloud",
+    "sonar",
+    "code-quality",
+    "review",
+    "quality-gate",
+    "compliance",
+    "security",
+    "dev-workflow"
+  ],
+  "model": {
+    "tier": "standard",
+    "rationale": "Formats Sonar API findings into a report. The hard analysis is Sonar's; this is synthesis. Escalates on very large diffs."
+  }
+}

skilldrop_cli/data/packs/dev-team/skills/sonar-review/reference.md

@@ -0,0 +1,167 @@
+# sonar-review — reference
+
+Long-form material that doesn't belong in `SKILL.md`.
+
+## SonarQube server vs SonarCloud — what changes for this skill
+
+Almost nothing. The API endpoints used here (`/api/qualitygates/project_status`, `/api/issues/search`, `/api/hotspots/search`) are identical in shape on both, authenticated the same way (`Authorization: Bearer $SONAR_TOKEN` or basic auth with the token as username). Only the host differs:
+
+| Mode | `$SONAR_HOST` |
+|---|---|
+| SonarQube server | `$SONAR_HOST_URL` (from env) |
+| SonarCloud | `https://sonarcloud.io` (fixed) |
+
+Mode is detected from `sonar-project.properties` — presence of `sonar.organization=<key>` means SonarCloud; absence means server. Don't ask the user; the properties file is canonical.
+
+Two behaviors that *do* differ:
+
+- **Branch analysis** — SonarCloud supports branch + PR analysis on all tiers. SonarQube Community Edition does not. If you set `sonar.branch.name` and the server returns `License not valid for branch analysis`, you're on Community Edition. Re-run without the flag; the scan will overwrite the default-branch history, which is acceptable for a local pre-merge check but not for CI.
+- **PR decoration** — SonarCloud auto-decorates the PR with findings if `GITHUB_TOKEN` is in the workflow env. Self-hosted needs ALM integration set up server-side. This skill doesn't touch PR decoration, but if the user asks why findings aren't appearing on the PR even though the scan ran, it's usually this.
+
+## SonarQube API shapes you'll parse
+
+### `/api/qualitygates/project_status`
+
+```json
+{
+  "projectStatus": {
+    "status": "ERROR",  // or "OK"
+    "conditions": [
+      {
+        "status": "ERROR",
+        "metricKey": "new_coverage",
+        "comparator": "LT",
+        "errorThreshold": "80",
+        "actualValue": "71.4"
+      },
+      {
+        "status": "OK",
+        "metricKey": "new_bugs",
+        "comparator": "GT",
+        "errorThreshold": "0",
+        "actualValue": "0"
+      }
+    ]
+  }
+}
+```
+
+`status` is the gate verdict (`OK` / `ERROR`). `conditions` is the per-rule breakdown — list the `ERROR` ones in the report's gate-conditions table.
+
+### `/api/issues/search`
+
+```json
+{
+  "issues": [
+    {
+      "key": "AYz1...",
+      "rule": "javascript:S2259",
+      "severity": "CRITICAL",
+      "type": "BUG",
+      "component": "myorg_payments:src/api/checkout.ts",
+      "line": 47,
+      "message": "Refactor this code to not use null dereference.",
+      "status": "OPEN",
+      "tags": ["cwe"]
+    }
+  ],
+  "paging": { "total": 42, "pageIndex": 1, "pageSize": 100 }
+}
+```
+
+`component` includes the project key prefix — strip it to get the file path. `severity` is one of `BLOCKER` / `CRITICAL` / `MAJOR` / `MINOR` / `INFO`. `type` is one of `BUG` / `VULNERABILITY` / `CODE_SMELL` (hotspots come from a different endpoint).
+
+### `/api/hotspots/search`
+
+```json
+{
+  "hotspots": [
+    {
+      "key": "AYz2...",
+      "component": "myorg_payments:src/jobs/export.ts",
+      "line": 28,
+      "ruleKey": "javascript:S2076",
+      "vulnerabilityProbability": "HIGH",  // HIGH / MEDIUM / LOW — maps to review priority
+      "status": "TO_REVIEW",                // TO_REVIEW / REVIEWED
+      "message": "Make sure that executing this OS command is safe here."
+    }
+  ]
+}
+```
+
+Hotspots **don't** appear in `/api/issues/search`. Forgetting to call this endpoint silently drops the security-hotspot lens.
+
+## Maven / Gradle / dotnet wrappers
+
+If `sonar-project.properties` references the standalone scanner but the project has `pom.xml`, `build.gradle`, or a `.sln`, prefer the language-native wrapper — it hooks into the compile step and produces better analysis:
+
+| Project type | Command |
+|---|---|
+| Maven | `mvn -B verify sonar:sonar -Dsonar.host.url=$SONAR_HOST_URL -Dsonar.token=$SONAR_TOKEN` |
+| Gradle | `./gradlew build sonar -Dsonar.host.url=$SONAR_HOST_URL -Dsonar.token=$SONAR_TOKEN` |
+| .NET | `dotnet sonarscanner begin /k:"<key>" /d:sonar.host.url=$SONAR_HOST_URL /d:sonar.token=$SONAR_TOKEN` → `dotnet build` → `dotnet sonarscanner end /d:sonar.token=$SONAR_TOKEN` |
+
+The standalone `sonar-scanner` still works for these but won't see compile-time information (type resolution, framework attributes). Findings will be shallower.
+
+## Scoping to PR diff
+
+The skill scopes the **report** to changed files, not the scan itself. To compute the changed files:
+
+```bash
+# vs origin/main (most PRs)
+git diff --name-only origin/main...HEAD
+
+# vs the previous commit (just-pushed work)
+git diff --name-only HEAD~1
+```
+
+When filtering issues, normalize the Sonar `component` field (`<projectKey>:<path>`) against your diff list. Strip the project-key prefix; compare paths.
+
+**Don't filter the scan**. `sonar-scanner` analyzes the whole project because cross-file analysis (call graphs, import resolution) requires it. You filter the *findings* on the way out.
+
+## Running against the SonarQube server with `branch` analysis
+
+The SonarQube Developer Edition+ supports branch analysis natively — pass `-Dsonar.branch.name=<branch>`. Community Edition does **not**. If the Sonar server returns:
+
+```
+ERROR: License not valid for branch analysis. Branches will not be analyzed.
+```
+
+… the project is on Community Edition. Workarounds:
+
+- Use the **`sonar.projectVersion`** trick — set `projectVersion=<branch>` to get separate histories per branch (crude but works on CE).
+- Scan only on merge to `main` (PR-time scanning unavailable on CE).
+- Upgrade to Developer Edition if branch analysis is required.
+
+Document the edition limitation in the report — don't pretend the missing branch view is a configuration issue.
+
+## Polling the scan task
+
+`sonar-scanner` returns once it uploads to the server, but the gate isn't computed until the server processes the task. After the scanner finishes:
+
+```bash
+TASK_URL=$(grep '^ceTaskUrl=' .scannerwork/report-task.txt | cut -d= -f2-)
+
+# Poll until status=SUCCESS (or FAILED)
+while true; do
+  STATUS=$(curl -s -u "$SONAR_TOKEN:" "$TASK_URL" | jq -r '.task.status')
+  case "$STATUS" in
+    SUCCESS) break ;;
+    FAILED|CANCELED) echo "Scan task failed: $STATUS"; exit 1 ;;
+    *) sleep 5 ;;
+  esac
+done
+```
+
+Skipping this means the gate API returns stale data from the *previous* scan, not this one. Always poll.
+
+## Common false positives worth knowing
+
+| Rule | Common false positive | What to do |
+|---|---|---|
+| `javascript:S2068` (hard-coded password) | Variable named `password` in a Zod/Joi schema definition | Mark `false positive` in Sonar UI |
+| `python:S5689` (use of `eval`) | `ast.literal_eval` (safe) flagged alongside `eval` | Confirm `literal_eval`, ignore |
+| `java:S3776` (cognitive complexity) | Big `switch` over an enum | Extract per-case handlers if it improves things; otherwise dispute |
+| `csharpsquid:S1135` (TODO comment) | TODOs intentionally tracked in code | Roll up the count, don't list each |
+
+These are dispositions to suggest, **not** to apply silently. The user marks them in Sonar UI; you surface them in the report so they know which to look at.

skilldrop_cli/data/packs/dev-team/skills/sonar-review/templates/report.md

@@ -0,0 +1,84 @@
+# Sonar review: {feature / PR title}
+_Scope: {N changed files, M lines added/removed} · Branch: `{branch}` · Scanned: {YYYY-MM-DD HH:MM} · Scan duration: {Ns}_
+_Sonar project: [`{project-key}`]({sonar-host}/dashboard?id={project-key}&branch={branch})_
+
+## Quality gate
+
+**{✅ PASS / ❌ FAIL}** — {one-line reason — what failed (or "all conditions met")}
+
+{2–3 sentence summary. Lead with what failed the gate. If PASS, say so plainly and call out the closest condition to the line.}
+
+### Gate conditions
+
+| Condition | Actual | Threshold | Status |
+|---|---|---|---|
+| New bugs | {N} | 0 | ✅ / ❌ |
+| New vulnerabilities | {N} | 0 | ✅ / ❌ |
+| New security hotspots reviewed | {pct}% | 100% | ✅ / ❌ |
+| Coverage on new code | {pct}% | ≥ 80% | ✅ / ❌ |
+| Duplicated lines on new code | {pct}% | ≤ 3% | ✅ / ❌ |
+
+(Drop rows the project's gate doesn't enforce.)
+
+## Findings on changed code
+
+| Severity | Bugs | Vulnerabilities | Hotspots | Code smells |
+|---|---|---|---|---|
+| 🟥 Blocker | {N} | {N} | — | {N} |
+| 🟧 Critical | {N} | {N} | {N} | {N} |
+| 🟨 Major | {N} | {N} | {N} | {N} |
+| ⚪ Minor | {N} | — | — | {N} |
+| ⚪ Info | {N} | — | — | {N} |
+
+### 1. Bugs
+
+{For each finding:}
+
+#### 🟥 [`javascript:S2259`] TypeError on null dereference
+- **Where:** `src/api/checkout.ts:47` — `discount.amount`
+- **Why it matters:** When `discount=null` reaches line 47, `applyDiscount` throws `TypeError` — the request returns a 500, not a graceful "no discount applied".
+- **Fix:** Add `if (discount == null) return 0;` at the top of `applyDiscount`, matching the pattern in `applyTax` at line 102.
+
+{If no findings: "No bugs flagged on changed code."}
+
+### 2. Vulnerabilities
+### 3. Security hotspots
+
+{Hotspots are review-required, not auto-fix. Each one:}
+
+#### 🟧 [`javascript:S2076`] OS command construction from user input
+- **Where:** `src/jobs/export.ts:28` — `exec(\`tar -czf ${userPath}\`)`
+- **Why it matters:** `userPath` flows from the export API without escaping — if an attacker controls the export name, they can inject shell metacharacters.
+- **Evidence for review:** `userPath` is validated upstream in `validateExportName` (`src/api/exports.ts:14`) to match `/^[a-zA-Z0-9_-]+$/` — that *should* make injection impossible, but the validation runs in a separate process and the variable name is reused.
+- **Action:** Mark **Safe** if you confirm the upstream validation is enforced on every code path that hits this exec; otherwise mark **At Risk** and switch to `execFile` with an args array.
+
+### 4. Code smells
+### 5. Coverage + duplication
+
+#### ❌ Coverage on new code: 71% (gate requires ≥ 80%)
+- **Where:** `src/jobs/export.ts` — 47/82 new lines covered; `src/api/checkout.ts` — 31/40 new lines covered.
+- **Why it matters:** The two uncovered branches in `export.ts` are the error paths (lines 55–62, 71–78) — exactly where regressions hide.
+- **Fix:** Add three tests — happy path is covered; add cases for (a) upstream API 500, (b) empty result set, (c) `userPath` failing validation.
+
+## Pre-existing issues in touched files (FYI — not blocking)
+
+{Issues that pre-date this branch but live in files you changed. For awareness; the gate doesn't enforce them.}
+
+- ⚪ `src/api/checkout.ts:102` — [`typescript:S3776`] Cognitive complexity 18 > 15 (existing).
+- ⚪ `src/api/checkout.ts:155` — [`typescript:S1192`] String literal `"USD"` duplicated 4 times (existing).
+
+## What's solid
+
+- {2–4 things the change got right — patterns that survived the scan cleanly. Not flattery; signal for what to preserve.}
+- New `parseDiscount` helper has 100% branch coverage and no findings — keep the test shape for the rest of the payment module.
+
+## Suggested order to address
+
+1. **Fix anything failing the quality gate** — blockers, new vulnerabilities, coverage shortfall. The PR can't merge until these are green.
+2. **Review the security hotspots** — mark each Safe / At Risk / Acknowledged in the Sonar UI. The gate counts them as unresolved until you do.
+3. **Major code smells**, prioritizing files in `src/api/` and `src/jobs/` over UI / config.
+4. **Minors and nits** if time permits, otherwise defer.
+
+---
+
+Full report: {sonar-host}/dashboard?id={project-key}&branch={branch}