fix(docapi): clean-checkout safe check:public:docapi (no generate first)#3472
Merged
Merged
Conversation
Before this PR, running `check:public:docapi` (or `check:public`) on a fresh checkout failed with "missing generated file" errors for artifacts under `packages/document-api/generated/`, which is gitignored. Contributors had to run `generate:docapi` first to materialize those files. Making a check command implicitly require a generate-then-check workflow is the wrong shape: a clean checkout should be able to validate the public surface without writing files. Fix: split the on-disk roots into two categories in checkGeneratedFiles(). - `roots` (tracked): committed reference docs + overview block. Existence, content, and "no extras on disk" still enforced. - `inMemoryRoots` (gitignored): `packages/document-api/generated/` subtrees. The artifacts are still BUILT in memory (so any builder error still propagates), but their on-disk presence is no longer required. If a developer happens to have stale files on disk from a previous `generate:docapi` run, the content-equality check still surfaces them. check-contract-outputs.ts passes the gitignored schema/agent roots as inMemoryRoots and only the tracked reference-docs root as the strict `roots`. The other three docapi check scripts (check-contract-parity, check-examples, check-overview-alignment) already read only tracked files, so they're clean-checkout safe without changes. `generate:docapi` remains the explicit way to materialize the gitignored artifacts locally (needed for SDK builds, publishing, etc.). It is no longer a prerequisite for any check command. Verified (worktree had no packages/document-api/generated/ on disk for the entire run): - pnpm check:public:docapi -> PASS (was: missing-file failures) - pnpm check:public -> PASS end-to-end on clean checkout - pnpm run check:types -> tsc clean - Stale tracked file (edited an .mdx in apps/docs/...reference/) -> still caught as "stale generated file content" (kind: 'content') - Stale gitignored file (wrote bogus JSON to packages/document-api/generated/agent/workflow-playbooks.json) -> still caught as "stale generated file content" (kind: 'content') Updated AGENTS.md and packages/superdoc/scripts/README.md to remove the "Requires generated artifacts to be current; run generate:docapi first" guidance and describe the new clean-checkout behavior.
L1 agent-docs scanner does `existsSync` on every backticked path-looking string in AGENTS.md / CLAUDE.md files and flags any that don't resolve. The clean-checkout state of this PR (no `packages/document-api/generated/` on disk) means the literal path fails that check. Reword the two lines in AGENTS.md so they describe the artifacts without naming the exact gitignored path. The README at `packages/superdoc/scripts/README.md` keeps the literal path because the scanner only runs against AGENTS.md / CLAUDE.md, and the path makes the README clearer for contributors hunting for the directory. Verified: `node .github/scripts/agent-docs-l1.mjs --target .` reports 0 broken path refs on root `AGENTS.md` after the fix (pre-existing findings on other AGENTS.md files are unrelated).
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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
2 participants
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.
PR 3 of the type-checking organization plan. Makes
check:public:docapi(and the umbrellacheck:public) work on a freshgit clonewithout first runninggenerate:docapi. The check is now truly non-mutating and clean-checkout safe. Builds on #3471 (now merged).Why this PR
Before this PR,
pnpm check:public:docapion a fresh checkout failed with:Those paths are gitignored. The check was asking the developer to first run
generate:docapi(which mutates the worktree), then check. That coupling makes a "check" command implicitly require a "generate" workflow — wrong shape.How
Split
checkGeneratedFiles()'s on-disk roots into two categories:roots(tracked)apps/docs/document-api/reference/(committed)inMemoryRoots(gitignored)packages/document-api/generated/schemas/+generated/agent/check-contract-outputs.tsnow passes the gitignored schema/agent roots asinMemoryRootsand only the tracked reference-docs root as the strictroots.The artifact BUILDERS still run for both root types — any builder error still propagates. We're just relaxing the "must exist on disk" assertion for paths that are gitignored.
The other three docapi check scripts (
check-contract-parity,check-examples,check-overview-alignment) already read only tracked files, so they're clean-checkout safe without changes.What didn't change
generate:docapiremains the explicit mutating command. Use it when you need the artifacts materialized locally (SDK builds, publishing). It's no longer a prerequisite forcheck:public:docapi.generate:docapirun), stale content is still caught; missing gitignored artifacts are allowed on a clean checkout.Verified (worktree had no
packages/document-api/generated/on disk)pnpm check:public:docapi→ PASS (was: missing-file failures)pnpm check:public(umbrella) → PASS end-to-end on clean checkoutpnpm run check:types→ tsc clean.mdx(edited a file inapps/docs/.../reference/) → still caught as "stale generated file content"generated/agent/workflow-playbooks.jsonthen ran the check) → still caught as "stale generated file content"node .github/scripts/agent-docs-l1.mjs --target .→ rootAGENTS.mdhas 0 broken path refsDoc updates
AGENTS.md: dropped the "Requires generated artifacts to be current; run generate:docapi first" guidance oncheck:public:docapi. Reworded to avoid the literal gitignored path so the L1 agent-docs scanner stays clean on a fresh checkout.packages/superdoc/scripts/README.md: rewrote thecheck:public:docapirow and thecheck-contract-outputs.tsrow to describe the new tracked-vs-inMemory split. README keeps the literal path because the L1 scanner only runs against AGENTS.md / CLAUDE.md and the path helps contributors find the directory.