docs: fix stale Bun references and add systemic doc drift checks

[BYK]

Summary

Fix the Bun→Node migration documentation drift with systemic improvements that prevent this class of error from recurring.

Supersedes #1022 — that PR found real issues but missed several stale references and lacked systemic prevention.

Changes

1. Fix generate-docs-sections.ts root cause

• Replace extractBunVersion() with extractPnpmVersion() derived from packageManager field
• Make both version extractors throw on mismatch instead of silently falling back — this is the core systemic fix that prevents the generator from ever silently producing wrong output again
• Update all prerequisite generators to reference Node.js + pnpm
• Remove "or Bun" from library-usage prerequisite

2. Expand generated marker coverage

Convert hand-written toolchain-dependent prose into generated sections so it can't drift:

• DEVELOPMENT.md prerequisites → GENERATED:START/END dev-prereq markers
• DEVELOPMENT.md build section → GENERATED:START/END build-toolchain markers
• contributing.md build section → GENERATED:START/END build-commands markers

Also fix remaining stale refs in: library-usage.md, plugins/README.md, check-no-deps.ts

3. Add generic check:stale-refs toolchain consistency check

New script/check-stale-references.ts that derives stale patterns from package.json — not hardcoded to Bun:

• Reads packageManager field to determine the current PM (pnpm)
• Flags all other PMs' dev commands (bun run, yarn remove, etc.) in dev-facing docs
• If the project ever migrates from pnpm to something else, changing packageManager automatically makes the check flag every pnpm run / pnpm add reference
• Added to CI lint job

4. Enhance check:fragments with subcommand coverage validation

The existing check only verified fragment files exist — not that they document all subcommands. New Check 5:

• Verifies each fragment mentions all subcommands in the route (via heading or code reference)
• Handles default commands (sentry local = sentry local serve)
• Strips fenced code blocks to avoid false heading matches from bash comments
• Warns by default, --strict flag for hard errors

5. Fill subcommand coverage gaps

• dashboard.md: add revisions, restore examples
• cli.md: add defaults, import examples
• issue.md: add events subcommand and @latest/@most_frequent selectors

Verification

All checks pass:

• check:fragments — all subcommands covered
• check:stale-refs — no stale PM references (23 files scanned)
• check:docs-sections — all generated sections up to date
• check:deps — error message fixed
• typecheck — clean
• test:unit — 314 files, 7227 tests pass

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://cli.sentry.dev/_preview/pr-1024/
Built to branch gh-pages at 2026-05-26 13:19 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c2da3ab. Configure here.}

[cursor]

Duplicated markdown fence stripping

Low Severity

The same fenced-code-block regex and stripCodeBlocks helper were added independently in check-stale-references.ts and check-fragments.ts. Shared logic will diverge if one copy’s behavior changes.

Additional Locations (1)

• script/check-fragments.ts#L135-L141

 

^{Reviewed by Cursor Bugbot for commit c2da3ab. Configure here.}

[BYK]

Addressing Bugbot feedback:

Default subcommand check too broad — Valid find. Fixed: the bare route check now uses a regex with word boundary (sentry\s+<route>(?:\s*$|[^\w-])) instead of includes(), so sentry issue events no longer falsely satisfies the default command check for sentry issue view.

Duplicated markdown fence stripping — Intentional. These are standalone check scripts with no shared imports (same pattern as check-error-patterns.ts, check-no-deps.ts, etc.). Extracting a shared module for a 3-line regex+function would add a dependency between scripts for minimal benefit. If a third consumer appears, we can revisit.

[github-actions]

Codecov Results 📊

✅ Patch coverage is 100.00%. Project has 4282 uncovered lines.
✅ Project coverage is 81.97%. Comparing base (base) to head (head).

Coverage diff

@@            Coverage Diff             @@
##          main       #PR       +/-##
==========================================
+ Coverage    81.95%    81.97%    +0.02%
==========================================
  Files          329       329         —
  Lines        23749     23754        +5
  Branches     15502     15504        +2
==========================================
+ Hits         19463     19472        +9
- Misses        4286      4282        -4
- Partials      1643      1641        -2

---

Generated by Codecov Action