build(docs): update sharp to 0.35.5 for GHSA-wq5f-xc86-pv6w (#2000)

[mbeisser1]

Bug Description

The "Audit npm deps" job (audit.yml) fails on the docs site.

Expected: npm audit --audit-level=high in docs/ reports nothing at high or above.

Actual: it reports one high advisory, GHSA-wq5f-xc86-pv6w: sharp below 0.35.5, a librsvg flaw (CVE-2026-96889). Seen on PR #1996's run, which changed no lockfile.

Root Cause

docs/package-lock.json resolved sharp (a transitive dependency of Astro) at 0.35.4, and the advisory was published after that lock was written.

Fix Description

Two commits.

1. npm audit fix in docs/. The lockfile moves sharp to 0.35.5 and its @img/sharp-libvips-* binaries to 1.3.4. Nothing else changes in that commit.
2. Issue npm audit fails on the docs site: sharp below 0.35.5 (GHSA-wq5f-xc86-pv6w) #2000 asked for the remaining moderate advisories to be checked. npm reports no fix for them because their dependents pin older majors, but patched versions exist, and scripts/audit-docs.sh says an advisory with a patched version is fixed, by an update or an overrides entry. So docs/package.json gains two overrides, the way its block already handles js-yaml and svgo:
   • postcss-selector-parser 7.1.6 closes GHSA-rj75-hqrm-r3gf (moderate), reached through @astrojs/starlight → expressive-code → postcss-nested, which pins ^6.
   • katex 0.19.0 closes GHSA-238p-pmpm-9mq7 (low), reached through mermaid, which pins ^0.16.

After both, npm audit reports no advisories at any level.

How to Reproduce (Before Fix)

1. cd docs && npm ci
2. npm audit --audit-level=high
3. One high advisory for sharp, and exit code 1.

How to Verify (After Fix)

1. cd docs && npm ci
2. npm audit reports 0 vulnerabilities, and exits 0.
3. ./scripts/audit-docs.sh passes.
4. npm run check && npm run build pass (verified locally: 0 errors, 87 pages built, with the PNG to WebP conversion exercising sharp).

Impact Assessment

• Severity: Low
• Users affected: None at runtime. sharp, katex, and postcss-selector-parser run only at docs build time. The failure is in CI's audit job.
• Duration: Since 2026-10-06, when GHSA-wq5f-xc86-pv6w was published. First seen on PR feat: ffmpeg is looked for on PATH, then in the Tools Directory, and wtsexporter only there (#1053) #1996's audit run on 2026-10-08.

Regression Risk

Patch bump of a build-time image library, plus two overrides that lift a CSS selector parser one major and KaTeX three minors above what their dependents pin. The docs check and build pass with all three, and mermaid uses KaTeX only for math inside diagrams, which the docs do not use.

Checklist

• Root cause identified and documented above
• Fix addresses the root cause (not just symptoms)
• Added test to prevent regression (the audit job is the test)
• Existing tests pass locally
• Tested the specific reproduction steps

Related Issues

Fixes #2000

🤖 Generated with Claude Code

[mbeisser1]

Review of 65b6d0c. No finding has a line in the diff, so all four are here.

Spec · spec — Issue #2000: "check the remaining moderate advisories while there." The PR body reports the check but overstates its result. It says postcss-selector-parser (GHSA-rj75-hqrm-r3gf, moderate) has "No fix available" and katex (GHSA-238p-pmpm-9mq7, low) can only be fixed by a mermaid downgrade. Both have patched versions on npm: postcss-selector-parser 7.1.6 and katex 0.18.2 or later. npm's fixAvailable: false means no semver-compatible path through the dependents (postcss-nested pins ^6, mermaid pins ^0.16.47), not that no fix exists. scripts/audit-docs.sh states the repo rule: "An advisory with a patched version is fixed, never accepted: by an update, npm audit fix, or an overrides entry in docs/package.json", and docs/package.json already carries an overrides block for exactly this. Fix: add postcss-selector-parser and katex to overrides, confirm npm run check and npm run build still pass, and correct the PR body.

Standards · rule — Commit message body: "npm audit fix moves sharp to 0.35.5 and its libvips binaries to 1.3.4; nothing else in the lockfile changes." joins two clauses with a semicolon. docs/agents/writing-style.md, "Sentences and paragraphs": a compound sentence splits in two rather than joining clauses with a dash or a semicolon. AGENTS.md "Writing" applies that file to commit messages. Fix: two sentences.

Standards · rule — PR body, "How to Reproduce" step 3 and "How to Verify" step 2: "One high advisory for sharp; exit code 1." and "reports 13 advisories, none high; exit code 0." Same rule. Fix: two sentences, or join with "and".

Standards · rule — PR body, "Impact Assessment", Duration: "Since the advisory was published, surfaced on PR #1996's audit run." names no date. docs/agents/writing-style.md, "Concrete values, never vague ones". The template asks since when the bug was present. Fix: give the advisory's publication date and keep the PR #1996 run as the first sighting.

Correctness — no findings.

[mbeisser1]

Answers to the review of 65b6d0c (the findings comment above), pushed as 7918347.

Spec · spec — the PR body says postcss-selector-parser and katex have no fix, but patched versions exist and scripts/audit-docs.sh says such an advisory is fixed through an overrides entry.

Fixed in 7918347: docs/package.json overrides postcss-selector-parser to 7.1.6 and katex to 0.19.0, the lockfile follows, npm audit reports 0 vulnerabilities, and the docs check and build pass. The PR body now describes both overrides.

Standards · rule — the commit message of 65b6d0c joins two clauses with a semicolon.

Fixed in the squash merge message. The branch commit cannot be rewritten without a force push, which AGENTS.md step 3 rules out, and the squash merge drops the branch commits, so the subject and body passed to the merge carry the text as two sentences.

Standards · rule — PR body, "How to Reproduce" step 3 and "How to Verify" step 2, join clauses with a semicolon.

Fixed in the PR body: "One high advisory for sharp, and exit code 1." and "npm audit reports 0 vulnerabilities, and exits 0."

Standards · rule — PR body, Duration, names no date.

Fixed in the PR body: "Since 2026-10-06, when GHSA-wq5f-xc86-pv6w was published. First seen on PR #1996's audit run on 2026-10-08."

Re-review of 7918347 (Standards and Correctness): no findings. Correctness confirmed postcss-nested 6.2.0 uses no API that changed in postcss-selector-parser 7, mermaid 11.17.2 calls only katex.renderToString with options katex 0.19.0 still takes, commander 15 is used by katex's CLI alone, and the built site's expressive-code CSS has its nested selectors resolved.

[mbeisser1]

Review summary for 7918347.

• Spec (issue npm audit fails on the docs site: sharp below 0.35.5 (GHSA-wq5f-xc86-pv6w) #2000): 1 finding, 1 Fixed (the overrides for postcss-selector-parser and katex, 7918347).
• Standards: 3 findings, 3 Fixed (two in the PR body, one in the squash merge message).
• Correctness: 0 findings.
• Re-review of 7918347: 0 findings.
• Declined: 0. Deferred: 0.
• No commits for CI failures, and no merge of the base: the branch was up to date throughout.
• No user threads. The ci.yml run on the pushed head ended in success.