refactor(docs): gitignore generated command docs, extract fragments#696
refactor(docs): gitignore generated command docs, extract fragments#696
Conversation
Command docs (docs/src/content/docs/commands/*.md) were a mix of auto-generated flag tables and hand-written examples. Both halves changed on every CI run due to dynamic PERIOD_BRIEF dates, creating daily noise in PRs via auto-commit. Split hand-written content into fragment files (docs/src/fragments/ commands/) and gitignore the generated output. The docs build and CI now run generate:docs before astro build. Skill files (plugins/sentry-cli/skills/sentry-cli/) remain committed since they are consumed directly by external plugin systems. PERIOD_BRIEF dates are snapped to the 1st of the month to reduce churn from daily to ~monthly. - Add generate:docs composite script (generate:command-docs + generate:skill) - Replace generate:skill with generate:docs in all dependent scripts - Extract 19 command doc fragments from below the GENERATED:END marker - Update generate-command-docs.ts to read from fragments directory - Add check:fragments validation script, remove check:skill/check:command-docs - Update CI: generation before docs build, slimmed auto-commit for skill files only - Delete generate-skill.yml workflow (superseded by CI check-generated job) - Snap PERIOD_BRIEF example dates to 1st of month
Semver Impact of This PR🟢 Patch (bug fixes) 📋 Changelog PreviewThis is how your changes will appear in the changelog. New Features ✨
Bug Fixes 🐛
Internal Changes 🔧
🤖 This preview updates automatically when you update the PR. |
…nerated-docs # Conflicts: # docs/src/content/docs/commands/dashboard.md # docs/src/content/docs/commands/event.md # docs/src/content/docs/commands/issue.md # docs/src/content/docs/commands/span.md # docs/src/content/docs/commands/trace.md # docs/src/fragments/commands/log.md # plugins/sentry-cli/skills/sentry-cli/references/dashboard.md # plugins/sentry-cli/skills/sentry-cli/references/event.md # plugins/sentry-cli/skills/sentry-cli/references/issue.md # plugins/sentry-cli/skills/sentry-cli/references/log.md # plugins/sentry-cli/skills/sentry-cli/references/span.md # plugins/sentry-cli/skills/sentry-cli/references/trace.md
generate-command-docs.ts imports src/app.js which transitively imports agent-skills.ts → skill-content.ts. On fresh CI checkouts the file doesn't exist yet. Use dynamic import() after writing a minimal stub to break the circular dependency with generate:skill.
|
Codecov Results 📊✅ 134 passed | Total: 134 | Pass Rate: 100% | Execution Time: 0ms 📊 Comparison with Base Branch
✨ No test changes detected All tests are passing successfully. ✅ Patch coverage is 100.00%. Project has 1480 uncovered lines. Coverage diff@@ Coverage Diff @@
## main #PR +/-##
==========================================
+ Coverage 95.43% 95.45% +0.02%
==========================================
Files 224 224 —
Lines 32538 32532 -6
Branches 0 0 —
==========================================
+ Hits 31052 31052 —
- Misses 1486 1480 -6
- Partials 0 0 —Generated by Codecov Action |
…nerated-docs # Conflicts: # docs/src/content/docs/commands/dashboard.md # docs/src/content/docs/commands/event.md # docs/src/content/docs/commands/issue.md # docs/src/content/docs/commands/span.md # docs/src/content/docs/commands/trace.md # docs/src/fragments/commands/log.md # plugins/sentry-cli/skills/sentry-cli/references/dashboard.md # plugins/sentry-cli/skills/sentry-cli/references/event.md # plugins/sentry-cli/skills/sentry-cli/references/issue.md # plugins/sentry-cli/skills/sentry-cli/references/log.md # plugins/sentry-cli/skills/sentry-cli/references/span.md # plugins/sentry-cli/skills/sentry-cli/references/trace.md
![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 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 0dca797. Configure here.
| // Must run before the dynamic import below (static imports hoist above top-level await). | ||
| const SKILL_CONTENT_PATH = "src/generated/skill-content.ts"; | ||
| const SKILL_CONTENT_STUB = | ||
| "export const SKILL_FILES: [string, string][] = [];\n"; |
There was a problem hiding this comment.
Inconsistent stub types for same generated file
Low Severity
The generate-command-docs.ts script creates a stub for src/generated/skill-content.ts that declares SKILL_FILES as an array. This conflicts with the ReadonlyMap type used in the actual file generated by generate-skill.ts. Since generate-command-docs.ts runs first, its stub can persist, leading to a type mismatch that may cause runtime errors when using Map-specific methods.
Reviewed by Cursor Bugbot for commit 0dca797. Configure here.
| const d = new Date(); | ||
| d.setDate(1); | ||
| return d.toISOString().slice(0, 10); | ||
| })(); |
There was a problem hiding this comment.
Date snapping uses local time with UTC output
Low Severity
EXAMPLE_START and EXAMPLE_END use setDate(1) which operates in local time, but toISOString().slice(0, 10) extracts the UTC date. In positive UTC-offset timezones (e.g. UTC+12) during the first hours of a new month, the UTC date is still the last day of the previous month, producing e.g. "2026-03-31" instead of "2026-04-01". This partially defeats the PR's goal of snapping to the 1st of the month for ~12 changes/year. The old EXAMPLE_END code (new Date().toISOString().slice(0, 10)) didn't have this problem since it wasn't targeting a specific day. Using setUTCDate(1) and setUTCMonth() would make the output consistently correct across all timezones.
Reviewed by Cursor Bugbot for commit 0dca797. Configure here.
1 participant
Summary
docs/src/content/docs/commands/) — they're rebuilt at build time from CLI metadata + hand-written fragmentsdocs/src/fragments/commands/(19 fragment files)PERIOD_BRIEFexample dates to 1st of month (~12 changes/year instead of 365)plugins/sentry-cli/skills/sentry-cli/) remain committed for external plugin consumers, with slimmed CI auto-commitMotivation
Generated files with dynamic dates (
PERIOD_BRIEFcomputed fromnew Date()) caused daily churn in PRs via CI auto-commit. Command docs were a mix of auto-generated flag tables and hand-written content, making them impossible to gitignore without losing the custom parts.Changes
Fragment extraction
generate-command-docs.tsnow reads custom content fromdocs/src/fragments/commands/{route}.mdcheck:fragmentsscript validates fragment ↔ route consistencyBuild pipeline
generate:docscomposite script chainsgenerate:command-docs→generate:skilldev,build,typecheck,test:*) usegenerate:docsinstead ofgenerate:skillbuild-docsanddocs-previewjobs run generation beforeastro buildCI simplification
check-skilljob →check-generated: validates fragments, auto-commits skill files only (not command docs)generate-skill.ymlworkflow (superseded bycheck-generated)check:skillandcheck:command-docsscripts (replaced bycheck:fragments)