feat(scripts): add public-contract tier metadata report (SD-3256 Phase 2)#3447
Conversation
…e 2) Adds a `publicContract` section to the canonical `type-surface.config.cjs`. Every `package.json#exports` subpath now has a declared tier: - supported (4): root, ./types, ./ui, ./ui/react — route through src/public/** - legacy (6): ./converter, ./docx-zipper, ./file-zipper, ./headless-toolbar, ./headless-toolbar/react, ./headless-toolbar/vue — route through src/public/legacy/** - legacy-raw (1): ./super-editor — resolves directly to dist/superdoc/src/super-editor.d.ts, NOT through src/public/legacy/**. SD-3256 Phase 3 will curate this through src/public/legacy/super-editor.ts after team alignment on which exports stay public. - asset (1): ./style.css — no types - deprecated (0) This phase is design-light: it adds metadata + a read-only report script. NO new enforcement, NO behavior change, NO export changes. The classification is open for team review before Phase 3 / Phase 4 build on it. New command: pnpm report:public-contract Prints the tier breakdown plus a cross-check that every `package.json#exports` subpath has a `publicContract` entry and vice versa. The cross-check warns but does not fail CI in this phase (read-only by design); Phase 4 will gate. Source-of-truth notes in the config explain each tier's intended policy (supported = strict gate, legacy = no-growth, legacy-raw = Phase 3 target). Phase 4's ratchet will read these tiers to apply per-tier enforcement rules. Verified: pnpm report:public-contract → 12 / 12 entries, cross-check OK. pnpm check:public-contract → PASS (3 stages, 199s). pnpm run type-check clean. pnpm run build:superdoc clean.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 72c82aedee
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| ...publicContract.asset, | ||
| ...publicContract.deprecated, | ||
| ]; | ||
| const contractSubpaths = new Set(allContractEntries.map((e) => e.subpath)); |
There was a problem hiding this comment.
The report collapses publicContract entries into a Set, so a subpath listed in multiple tiers is silently deduplicated and the script can still print OK even though the classification is contradictory. This weakens the Phase 2 review signal because one export can appear in two tiers without being flagged; consider validating allContractEntries.length === contractSubpaths.size (and reporting duplicates) before declaring the cross-check clean.
Useful? React with 👍 / 👎.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
🎉 This PR is included in superdoc-cli v0.12.0 The release is available on GitHub release |
|
🎉 This PR is included in superdoc-sdk v1.11.0 |
|
🎉 This PR is included in @superdoc-dev/mcp v0.7.0 The release is available on GitHub release |
|
🎉 This PR is included in superdoc v1.35.0 The release is available on GitHub release |
|
🎉 This PR is included in @superdoc-dev/react v1.6.0 The release is available on GitHub release |
|
🎉 This PR is included in vscode-ext v2.7.0 |
2 participants
Design-light Phase 2 of the SD-3256 umbrella. Adds tier metadata for every
package.json#exportssubpath ontype-surface.config.cjs, plus a read-only report command. No new enforcement. No export changes. No behavior change. The classification is open for team review before Phase 3 (./super-editor curation) and Phase 4 (ratchet) build on it.Tiers (12 / 12 subpaths classified):
.,./types,./ui,./ui/react— route throughsrc/public/**./converter,./docx-zipper,./file-zipper,./headless-toolbar,./headless-toolbar/react,./headless-toolbar/vue— route throughsrc/public/legacy/**./super-editor— resolves directly todist/superdoc/src/super-editor.d.ts, NOT throughsrc/public/legacy/**. Phase 3 target../style.cssNew command:
Prints the tier breakdown plus a cross-check that every
package.json#exportssubpath has apublicContractentry and vice versa. The cross-check warns but does not fail CI in this phase (read-only by design); Phase 4 will gate.The classification is derived directly from where each subpath's types resolve today, so it documents reality rather than proposing changes. The one outlier (
./super-editoraslegacy-raw) is explicitly flagged for Phase 3 with a note.Verified:
pnpm report:public-contract→ 12/12, cross-check OK;pnpm check:public-contract→ PASS (3 stages, 199s);pnpm run type-checkclean;pnpm run build:superdocclean.