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-25 22:04 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[cursor]

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

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

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

[cursor]

Default subcommand check too broad

Low Severity

Check 5 treats the default subcommand as documented when the fragment contains any substring sentry <route>, including longer invocations like sentry issue events. That makes default coverage pass whenever any sibling subcommand is documented, so missing default-subcommand docs may never warn.

 

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