fix(ci): generated skill bundles still analysed by SonarCloud despite the exclusion

[amondnet]

Observation

.sonarcloud.properties on main excludes the committed bundles:

sonar.exclusions=skills/spring-docs/scripts/
sonar.cpd.exclusions=skills/spring-docs/scripts/

That landed in ee09832 ("chore(ci): scope Sonar and Codacy off the generated skill bundles"). Yet the SonarCloud analysis of #21 still reported five issues inside the excluded directory:

[CRITICAL/BUG]        skills/spring-docs/scripts/docs.mjs:92  — sort without a compare function
[CRITICAL/CODE_SMELL] skills/spring-docs/scripts/docs.mjs:108 — Unexpected var, use let or const
[CRITICAL/CODE_SMELL] skills/spring-docs/scripts/docs.mjs:109 — Unexpected var, use let or const
[MAJOR/CODE_SMELL]    skills/spring-docs/scripts/docs.mjs:123 — nested ternary
[CRITICAL/CODE_SMELL] skills/spring-docs/scripts/docs.mjs:417 — Unexpected var, use let or const

The var findings are Bun's output, not anything a person wrote — bun run build:skill:check byte-compares the bundle against a fresh build, so they cannot be edited away. That is exactly the situation the exclusion exists to prevent, and it is the reason the file's own header warns the rating "no edit can recover".

Why it matters

A bundled copy of every source finding double-counts the same program, and a BUG in generated output can hold the quality gate at a D reliability rating on new code that nothing in the repository can fix.

Candidate causes, unverified

• The file's header notes that Automatic Analysis "accepts no wildcards in these values, so paths are written as plain directory prefixes". Whether a trailing-slash directory prefix is honoured, or whether Automatic Analysis expects a glob such as skills/spring-docs/scripts/**/*, is the first thing to check.
• The same header notes that only the copy on the default branch takes effect. The exclusion is on main, so that does not explain it — but it is worth re-confirming that the analysis of a PR inherits the default branch's properties rather than the PR head's.

Codacy is configured separately in .codacy.yml with skills/*/scripts/** and should be checked the same way; its check is also failing on #21.

Definition of done

A PR that touches scripts/docs.ts produces no SonarCloud or Codacy finding under skills/*/scripts/, verified on a real PR rather than from configuration alone — the previous attempt looked correct too.

[amondnet]

Measured on main — the exclusion is not applying at all

The original report counted five findings on PR #21's new code. Querying the main branch analysis directly shows the real scope:

$ curl -sS 'https://sonarcloud.io/api/issues/search?componentKeys=pleaseai_spring-plugin&branch=main&resolved=false&ps=500'

total open on main:  418
inside skills/spring-docs/scripts/:  362   (87%)

  skills/spring-docs/scripts/detect.mjs   332
  skills/spring-docs/scripts/docs.mjs      30

  CODE_SMELL 335 · BUG 26 · VULNERABILITY 1

sonar.exclusions=skills/spring-docs/scripts/ has been on main since ee09832, so this is not the "only the default branch counts" caveat — the exclusion is on the default branch and is being ignored outright.

What the noise looks like

detect.mjs bundles fast-xml-parser, so its 332 findings are that library's HTML entity tables and numeric code read as first-party source:

detect.mjs:725  — Duplicate name 'amp'.
detect.mjs:1158 — Duplicate name 'minus'.
detect.mjs:1849 — Do not check floating point equality or inequality with exact values.
detect.mjs:3765 — Remove this "!==" check; it will always be true.
detect.mjs:361  — Move this Unicode combined character '·̀' outside of the character class

None is editable: bun run build:skill:check byte-compares the bundle against a fresh build, so any hand-edit fails CI.

Why this is worth more than a tidy-up

87% of the project's Sonar findings are generated-code noise. That makes the quality gate unreadable as a signal — a genuine finding in scripts/ arrives in the same list as 332 entity-table duplicates, and the reflex becomes to ignore the gate rather than read it.

It also has a concrete cost already: PR #21 merged while its gate was red, and a real new-code BUG (docs-cache.ts:235, a .sort() with no comparator) reached main inside that red. A gate nobody can read is a gate nobody checks.

Raising Importance to High on that basis — the fix is still small, so Effort stays Low.

[amondnet]

Verified on main — the exclusion now applies

#26 merged as c29a203. The Definition of Done asked for this to be confirmed on a real analysis rather than from configuration, so here is main's own state before and after, from the same API query the report above used:

$ curl -sS 'https://sonarcloud.io/api/issues/search?componentKeys=pleaseai_spring-plugin&branch=main&resolved=false&ps=500'

	before (314d38d)	after (c29a203)
open findings on main	412	53
inside skills/spring-docs/scripts/	359 (87%)	0
ncloc	10,716	5,698

The 332 fast-xml-parser entity-table findings and the 27 in docs.mjs are gone; what remains is 53 findings in real first-party source, which is a list someone can actually read.

Root cause

sonar.exclusions=skills/spring-docs/scripts/ matched nothing. SonarQube Cloud matches these values against whole file paths, and the pattern documentation is explicit that a whole subtree is written dir/**/* and a bare prefix does not work. A pattern that matches nothing is discarded without a warning, which is why ee09832 looked correct.

The file's own header caused it: it read the Automatic Analysis page's "Wildcard patterns are not allowed" as covering every value in the file. That line constrains the plain path lists sonar.sources and sonar.tests, not the exclusion patterns. Both the header and .please/docs/knowledge/gotchas.md now say so, with links.

Codacy needed no change

The issue asked for .codacy.yml to be checked the same way. exclude_paths: ['skills/*/scripts/**'] is Java glob, where dir/** does cover everything beneath, and Codacy's API reported 0 of its 211 findings under skills/. #21's red Codacy check was the genuine scripts/docs.ts bug that #25 fixed — the exclusion working, not failing.

Guard against the recurrence

scripts/__tests__/generated-bundle-exclusions.test.ts asserts that every exclusion pattern configured in .sonarcloud.properties, .codacy.yml and eslint.config.js matches the committed bundles, reading each config's active setting so a commented-out entry cannot supply a passing pattern. Mutation-checked against seven scenarios: it tolerates whitespace around =, a leading indent, and double-quoted YAML, and fails on the old bare prefix or a commented-out entry in any of the three files.

It is not proof that SonarCloud reads a pattern identically — Bun.Glob stands in for three matchers it is not. It catches the failure that actually happened here: a pattern matching no file at all, which review cannot distinguish from a working one by reading it.