docs: documentation audit — fix toolchain drift, license, missing docs#1229
Draft
cursor[bot] wants to merge 4 commits into
Draft
docs: documentation audit — fix toolchain drift, license, missing docs#1229cursor[bot] wants to merge 4 commits into
cursor[bot] wants to merge 4 commits into
Conversation
…oad docs - AGENTS.md: Replace bun references with pnpm/vitest (actual toolchain) - Quick Reference section: bun install → pnpm install, bun test → vitest - Testing section header: bun:test → vitest - Code examples: import from 'vitest' instead of 'bun:test' - mock.module → vi.mock (vitest API) - check:deps: bun run → pnpm run - add -d → add -D (pnpm flag) - .craft.yml: Fix Homebrew formula license FSL-1.1-MIT → FSL-1.1-Apache-2.0 - getting-started.mdx: Update pinned version example, add SENTRY_INIT tip - agentic-usage.md: Document all detected agents (Gemini, Codex, Copilot, etc.) - proguard.md: Add missing 'proguard upload' examples and notes Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
…pdate plugins README
- AGENTS.md: Fix remaining bun→pnpm references in generate:docs,
check:fragments, and check:errors commands
- AGENTS.md: Correct project description ('built with Bun' → esbuild/fossilize)
- index.mdx: Add missing yarn option to InstallSelector on homepage
- plugins/README.md: Mention broader agent support (~/.agents) in Other Agents
Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
- Replace 'Bun's test runner uses --isolate --parallel' with Vitest - Update BUN_TEST_WORKER_ID → VITEST_POOL_ID - Clarify that Bun APIs are used in source but shimmed for Node.js Co-authored-by: Miguel Betegón <miguelbetegongarcia@gmail.com>
Contributor
|
Contributor
Codecov Results 📊✅ Patch coverage is 100.00%. Project has 5339 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
- Coverage 81.81% 81.80% -0.01%
==========================================
Files 423 423 —
Lines 29343 29343 —
Branches 19118 19118 —
==========================================
+ Hits 24008 24004 -4
- Misses 5335 5339 +4
- Partials 1989 1988 -1Generated by Codecov Action |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documentation Audit Report
Weekly cron-triggered audit of the Sentry CLI repository to find gaps between implementation and documentation. This PR fixes the most impactful issues found.
Gap Report
A. Undocumented or Missing Commands/Subcommands
sentry proguard uploadsrc/commands/proguard/upload.tsdocs/src/fragments/commands/proguard.mduuidAll other commands in
src/commands/have corresponding fragments.B. Undocumented Flags
No non-hidden flags found that are missing from their corresponding doc fragments. The doc generation system (
generate-command-docs.ts) auto-generates flag tables from command metadata, so flags stay in sync.C. Missing Usage Examples
sentry proguard uploadsrc/commands/proguard/upload.tsdocs/src/fragments/commands/proguard.mdAll other ~120 subcommands have bash examples in their fragments.
D. Stale Descriptions
No meaningful discrepancies found between
briefstrings in code and the generated doc pages (the doc generator pulls directly from command metadata).E. Missing Route Mappings in Skill Generator
The
ROUTE_TO_REFERENCEmap was removed in a prior refactor — the skill generator now usesgroupRoutesByReference()for automatic 1:1 mapping. No manual maintenance needed.F. Installation / Distribution Gaps
.craft.ymlHomebrew formula has wrong licenseFSL-1.1-MIT(should beFSL-1.1-Apache-2.0).craft.yml:41index.mdxInstallSelector omitsyarn(README and getting-started include it)docs/src/content/docs/index.mdxgetting-started.mdxpins version0.19.0in example (outdated, current is 0.38.x)docs/src/content/docs/getting-started.mdx:27SENTRY_INIT=1env var for post-install wizard not mentioned in getting-startedinstall:338vsgetting-started.mdxSENTRY_INSTALL_DIR— not mentioned in getting-startedinstall:101G. Undocumented Environment Variables
The configuration page is auto-generated from
src/lib/env-registry.ts. All user-facingSENTRY_*variables are registered there. Internal-only variables (SENTRY_PIPELINE,SENTRY_MONITOR_SLUG,SENTRY_SCAN_DISABLE_WORKERS,SENTRY_CLI_NO_EXIT_TRAP,SENTRY_CLI_INTEGRATION_TEST_VERSION_OVERRIDE) are intentionally excluded as they're set by Sentry's own plugins/infrastructure, not by end users.H. Auth / Self-Hosted Gaps
No issues found. The self-hosted docs correctly describe:
SENTRY_CLIENT_IDrequirement--urlflag for trust anchor registrationSENTRY_FORCE_ENV_TOKEN)NODE_EXTRA_CA_CERTS,SENTRY_CUSTOM_HEADERS)I. Plugin/Skills Gaps
plugins/README.mdonly mentions Claude Code and Cursor — doesn't mention broader~/.agentsagent supportplugins/README.mdagentic-usage.mddoesn't list all detected agents (Gemini, Codex, Copilot, Windsurf, Goose, Amp, Augment, Antigravity, OpenCode)docs/src/content/docs/agentic-usage.mddetect-agent.tssupports 11 agents; only Claude and Cursor were documentedsrc/lib/detect-agent.tsJ. README / DEVELOPMENT.md / AGENTS.md Drift
AGENTS.md:7bun install,bun run,bun test— should bepnpm install,pnpm run,vitestAGENTS.md:38-62bun add -d— should bepnpm add -DAGENTS.md:68bun run check:deps— should bepnpm run check:depsAGENTS.md:66bun run generate:docs/bun run check:fragments/bun run check:errorsbun:test— should bevitestAGENTS.md:702bun:test— should bevitestAGENTS.md:759,807,935mock.module— should bevi.mock(vitest API)AGENTS.md:944--isolate --parallel" — should reference vitest worker poolsAGENTS.md:736BUN_TEST_WORKER_ID— should beVITEST_POOL_IDAGENTS.md:736pnpmthroughout, generated sections)Prioritized Top 5 Most Impactful Fixes
AGENTS.md toolchain drift (bun → pnpm/vitest) — Most impactful because AGENTS.md is loaded as workspace rules by AI coding agents. Wrong commands cause failed builds and test runs.
.craft.ymlHomebrew license mismatch — The formula template shipsFSL-1.1-MITbut the actual license isFSL-1.1-Apache-2.0. This affects every Homebrew release.Missing
proguard uploaddocumentation — The upload command existed with no examples in the fragment, meaning the generated docs had no usage guidance for a key Android workflow.Undocumented agent detection — 11 agents are detected but only 2 were documented. Users of Gemini CLI, Codex, Windsurf, etc. had no visibility into how the CLI recognizes their agent.
Homepage missing yarn — The install selector on the docs homepage omitted yarn, creating a discrepancy with README and getting-started that could confuse yarn users.
Changes Made
AGENTS.md— Replace allbuntoolchain references with correctpnpm/vitestequivalents.craft.yml— Fix Homebrew formula license toFSL-1.1-Apache-2.0docs/src/content/docs/getting-started.mdx— Update pinned version, addSENTRY_INITtipdocs/src/content/docs/index.mdx— Add missingyarnto InstallSelectordocs/src/content/docs/agentic-usage.md— Document all 11 detected agentsdocs/src/fragments/commands/proguard.md— Addproguard uploadexamplesplugins/README.md— Document broader~/.agentssupport