docs: weekly documentation audit — fix DSN table, Zod→Valibot drift, missing env vars, new commands - #1461
Conversation
…s and command docs - generate-docs-sections.ts: fix 'Zod schemas' → 'Valibot schemas' in project structure tree (Valibot migration merged in #1389) - env-registry.ts: add DO_NOT_TRACK (industry-standard telemetry opt-out) and SENTRY_PIPELINE (build plugin identification) to the env var registry - explore.ts: update --environment flag brief — it now works for all datasets, not just replays (fixed in #1442) - cli.md fragment: add sentry cli completion examples (new command from #1427) - dashboard.md fragment: add --sixel flag example (new feature from #1410) Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
The DSN code scanner uses a universal regex that matches DSN URLs in any text file — the previous table implied language-specific Sentry.init() pattern matching. Updated to list all supported file extensions from TEXT_EXTENSIONS in src/lib/scan/constants.ts, including newly supported languages: Kotlin, Scala, Groovy, C#, F#, VB, Rust, Swift, Dart, Elixir/Erlang, Lua, and config formats. Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Jared, take the PR over, make the CI pass, address all bot comments and then get it merged. For the undocumented flag, env variable, and command gaps: implement a general solution to eliminate the class of these problems before merging. |
Fixes the biome formatting failure on the --environment brief. Adds script/check-env-coverage.ts (also runnable via the check:env-coverage script) to eliminate the class of undocumented env var gaps this audit found: it scans source for env reads and fails when a user-facing SENTRY_* (or known public) var is read but missing from ENV_VAR_REGISTRY, unless it is explicitly listed as internal with a reason. Enforced in CI by check-env-coverage.test.ts, which runs the check against the source tree in the unit test job.
github-actions
Bot
added
risk: high
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 4ac61c1. Configure here.
| "check:errors": "pnpm tsx script/check-error-patterns.ts", | ||
| "check:patches": "pnpm tsx script/check-patches.ts", | ||
| "check:docs-sections": "pnpm tsx script/generate-docs-sections.ts --check", | ||
| "check:env-coverage": "pnpm tsx script/check-env-coverage.ts", |
There was a problem hiding this comment.
Missing root check script alias
Low Severity
check:env-coverage was added under packages/cli but not mirrored in the workspace root package.json, unlike every other check:* script. From the repo root, pnpm run check:env-coverage fails, so the new guard is harder to run the same way as check:deps, check:errors, and peers.
Reviewed by Cursor Bugbot for commit 4ac61c1. Configure here.
2 participants
Documentation Audit Report (2026-08-24)
Weekly automated audit comparing the CLI implementation against its documentation. Changes since the last merged audit (PR #1400, 2026-08-11) include: the
sentry cli completioncommand (#1427), sixel dashboard rendering (#1410), the--environmentexplore fix (#1442), and the 0.43.0 release.Findings & Fixes
A. Undocumented or missing commands/subcommands
sentry cli completionsrc/commands/cli/completion.ts(added in #1427)apps/cli-docs/src/fragments/commands/cli.mdAll other commands in
src/commands/have corresponding fragment files. Hidden backward-compat aliases (send-event,send-envelope,bash-hook,whoami, plural aliases) are correctly excluded from docs.B. Undocumented flags
--sixel/-ssentry dashboard viewsrc/commands/dashboard/view.tsfragments/commands/dashboard.mdAll other non-hidden flags are auto-generated into the command docs via
generate-command-docs.ts.C. Missing usage examples
No new gaps. The
sentry cli completioncommand was the only command without examples, now fixed.D. Stale descriptions
sentry explore --environmentE. Missing route mappings in skill generator
N/A —
ROUTE_TO_REFERENCEwas removed and replaced with automatic 1:1 route-to-reference mapping viagroupRoutesByReference()inscript/generate-skill.ts. No manual mapping to go stale.F. Installation / distribution gaps
No new gaps. Install script flags (
--no-modify-path,--no-completions,--no-agent-skills) and env vars (SENTRY_INSTALL_DIR,SENTRY_VERSION,SENTRY_INIT) are documented ingetting-started.mdx. Platform support table matches.craft.ymltargets (macOS x64/arm64, Linux x64/arm64, Windows x64).G. Undocumented environment variables
DO_NOT_TRACKsrc/lib/telemetry.tsconfiguration.md(generated from env-registry)SENTRY_PIPELINEsrc/commands/build/upload.ts,src/lib/build/index.tsconfiguration.mdRemaining niche/internal vars NOT added (intentionally excluded from user-facing docs):
SENTRY_ENVIRONMENT— bash-hook template onlySENTRY_CLI_NO_EXIT_TRAP— bash-hook template internalSENTRY_SCAN_DISABLE_WORKERS— internal performance tuningSENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE— test-onlySENTRY_RN_*— internal react-native wrapper varsSENTRY_TRACES_SAMPLE_RATE— inherited from SDK, not a CLI configH. Auth / self-hosted gaps
No new gaps. OAuth scopes in
self-hosted.mdandDEVELOPMENT.mdare auto-generated (GENERATED:START oauth-scopes). The--urlflag forauth loginandSENTRY_HOST/SENTRY_URLbehavior are documented. Token priority (OAuth > env token unlessSENTRY_FORCE_ENV_TOKEN) is correct.I. Plugin/skills gaps
No new gaps since the last audit. Skills install to
~/.claudeand~/.agentsonly. Theagentic-usage.mdcorrectly states this. Detection of other agents (Cursor, Windsurf, Copilot, etc.) is for telemetry and the docs correctly list them as "supported" agents (they can use the CLI, just not via auto-installed skills).J. README / DEVELOPMENT.md / contributing.md drift
script/generate-docs-sections.tsline 210apps/cli-docs/src/content/docs/features.mdSentry.init()patternsNode.js version claims (v22.15+ for dev, >=20 for runtime) are correct. Build commands, test commands, and license (
FSL-1.1-Apache-2.0) are all accurate.Top 5 Most Impactful Fixes (prioritized)
DSN detection language table overhaul (
features.md) — The previous table implied language-specificSentry.init()pattern matching, which is misleading. The universal regex approach supports 30+ file extensions. Users of Kotlin, Rust, Swift, Dart, C#, etc. would not have known their DSNs are detected.Missing
sentry cli completiondocs (cli.mdfragment) — New command from feat(cli): add completion command #1427 with no usage examples. Users discovering shell completions would miss this standalone alternative tosentry cli setup.Stale
--environmentflag brief (explore.ts) — After fix(explore): Translate --environment to query for non-replays #1442 fixed--environmentto work for all datasets, the flag'sbriefstring still said "Replay environment filter". Users would think it only applies to replays.Missing env vars in registry (
env-registry.ts) —DO_NOT_TRACK(industry-standard telemetry opt-out) andSENTRY_PIPELINE(build plugin identification) were referenced in code but absent from the generated configuration page.Zod→Valibot drift in project structure (
generate-docs-sections.ts) — The auto-generated project structure tree incontributing.mdstill said "Zod schemas" despite the migration to Valibot in refactor(cli): remove remaining zod usage, migrate to valibot #1389. Contributors would be confused about which validation library to use.