fix(typecheck): one wrapper for SuperDoc public surface across CI lanes#3471
Merged
Conversation
Extends check:public:superdoc (the wrapper script) to subsume the
package-shape, snapshots, and classification-closure steps that
ci-superdoc.yml, release-superdoc.yml, and release-stable.yml each ran
separately. Adds two stages so all three lanes call a single command.
scripts/check-public-contract.mjs:
- Adds stages 4-6: package-shape-gate, snapshot --all --check,
check-root-classification-closure. All three reuse the
packed-and-installed fixture produced by stage 2 (typecheck-matrix),
so ordering matters: matrix produces the install, the rest reuse it.
- Updated header docstring to enumerate all six stages and explain why
the post-install gates are grouped here.
.github/workflows/:
- ci-superdoc.yml: drop 3 duplicated steps (package-shape, snapshots,
closure); the wrapper now covers them. Single step
`pnpm check:public:superdoc --skip-build`.
- release-superdoc.yml: drop 5 separate steps (matrix, audit,
package-shape, snapshots, closure); replace with the same single
wrapper call.
- release-stable.yml: same replacement as release-superdoc.yml.
Net: ~110 lines removed across the three workflows, ~30 added in the
wrapper. A change to the validation chain (new stage, reorder, rename)
now lands in one place and propagates to every lane automatically.
package.json (alias inversion):
- Canonical names now point at the real implementations:
check:types -> tsc -b tsconfig.references.json
check:public:superdoc -> node scripts/check-public-contract.mjs
check:public:docapi -> the four docapi check commands
generate:docapi -> tsx generate-contract-outputs.ts
report:public:superdoc -> node scripts/report-public-contract.mjs
- Legacy names delegate to canonical:
type-check -> pnpm run check:types
check:public-contract -> pnpm run check:public:superdoc
docapi:check -> pnpm run check:public:docapi
docapi:sync -> pnpm run generate:docapi
docapi:sync:check -> generate:docapi && check:public:docapi
report:public-contract -> pnpm run report:public:superdoc
This makes the new names actually canonical (no extra alias hop in
the hot path) and keeps --skip-build / other args forwarding
cleanly through both name systems. Verified both
`pnpm check:public:superdoc --skip-build` and
`pnpm check:public-contract --skip-build` reach the SKIP branch in
the wrapper.
AGENTS.md + packages/superdoc/scripts/README.md:
- Reflect that check:public:superdoc now runs all six stages.
- Reflect that all three workflows call the wrapper directly.
- Drop "tracked separately" caveat for the package-shape / snapshots /
closure folding; that's now done.
- Tag legacy aliases on each canonical command line so contributors
who know the old name can find the new one.
Verified:
- pnpm check:public:superdoc (canonical) -> PASS 6 stages, 144.2s
- pnpm check:public:superdoc --skip-build -> SKIP branch reached
- pnpm check:public-contract --skip-build (legacy) -> same SKIP path
- pnpm run check:types -> tsc clean
- pnpm run type-check (legacy alias) -> tsc clean
- pnpm run report:public:superdoc -> tier report (canonical)
- pnpm run report:public-contract -> tier report (legacy alias)
…k-wrapper PR-2) Review-feedback wording correction. The previous text said "stages 3-6 reuse the install produced by typecheck-matrix" but that conflated two distinct inputs: - deep-type-audit, snapshot, and check-root-classification-closure read from the consumer fixture's node_modules/superdoc/ (installed via the tarball). - package-shape-gate reads the tarball directly (packages/superdoc/superdoc.tgz), not the installed fixture. Updated the script's header docstring and the package-shape-gate stage blurb to call out the distinction. Updated the matching paragraph in packages/superdoc/scripts/README.md. No behavior change.
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 2 of the type-checking organization plan. Folds the three duplicated CI step lists into one wrapper command, and inverts the alias direction so canonical names directly invoke implementations. Builds on #3469 (now merged).
What changed
scripts/check-public-contract.mjs— wrapper extensionAdds three stages so
check:public:superdoccovers everything the SuperDoc public surface needs:build:superdoctypecheck-matrixdeep-type-audit --strict-supported-rootpackage-shape-gatesnapshot --all --checkcheck-root-classification-closureOrdering matters: stage 2 packs
superdoc.tgzand installs it into the consumer fixture. Stages 3, 5, and 6 read from the installed fixture; stage 4 reads the tarball directly. Both inputs are produced by stage 2, so it always runs first.Three CI lanes switched to the wrapper
ci-superdoc.ymlpnpm check:public:superdoc --skip-buildrelease-superdoc.ymlrelease-stable.ymlNet ~110 lines removed across workflows. Any future change to the SuperDoc validation chain (new stage, reorder, rename) lands in one place and propagates to every lane automatically.
Alias direction inverted
Per the agreed migration plan: canonical names now directly invoke the real implementations; legacy names delegate.
check:types→tsc -b tsconfig.references.jsontype-check→pnpm run check:typescheck:public:superdoc→node scripts/check-public-contract.mjscheck:public-contract→pnpm run check:public:superdoccheck:public:docapi→ 4 docapi check commandsdocapi:check→pnpm run check:public:docapigenerate:docapi→tsx generate-contract-outputs.tsdocapi:sync→pnpm run generate:docapireport:public:superdoc→node scripts/report-public-contract.mjsreport:public-contract→pnpm run report:public:superdocThe new names are now in the hot path (no extra alias hop), and
--skip-build/ other arg forwarding works through both name systems.Doc updates
AGENTS.md: enumerated all 6 stages on thecheck:public:superdocline; legacy alias tagged on each canonical command.packages/superdoc/scripts/README.md: dropped the "tracked separately" caveat for the package-shape/snapshots/closure folding (now done); rewrote "CI vs local" to say all three workflows call the wrapper; clarified thatpackage-shape-gatereads the tarball while the other downstream stages read the installed fixture.Verified
pnpm check:public:superdoc(canonical, full build) → PASS 6 stages, 144.2spnpm check:public:superdoc --skip-build→ PASS 5 ran / 1 skipped, 111.9spnpm check:public-contract --skip-build(legacy, one hop) → reaches SKIP branchpnpm run check:types(canonical) → tsc cleanpnpm run type-check(legacy alias) → tsc cleanpnpm run report:public:superdoc(canonical) → tier reportpnpm run report:public-contract(legacy alias) → tier report