refactor(types): centralize public-surface taxonomy in single config (SD-2864)#3161
Merged
caio-pizzol merged 7 commits intomainfrom May 5, 2026
Merged
Conversation
…SD-2942)
After SD-2893 drained every shim entry to zero, the auto-generated
_internal-shims.d.ts file ships empty (header comments only). The
auto-capture mechanism that wrote it is no longer load-bearing: it
was a soft fallback that captured any unrelocated private @superdoc/*
specifier in dist d.ts files and silently shimmed it as `any`. With
the relocation rules + RULE1_ALLOWLIST + UNSHIMMED_PRIVATE_SPECIFIERS
now covering the entire workspace surface, that soft path mostly
swallows new private leaks instead of failing the build.
This change makes new leaks fail loudly:
- ensure-types.cjs: drop the workspace-imports scanning loops, the
shim-file write, the triple-slash reference injection, and the
SHIM_FORBIDDEN regression net (now redundant with the relocation
rules + audit Rule 1). Add an explicit unlink for any stale
_internal-shims.d.ts left over from prior builds.
- audit-declarations.cjs: update the rule documentation. Rule 1 now
fails for any unrelocated private @superdoc/* specifier; Rule 3
becomes a no-op in steady state (kept as defense against stale
tarballs or future re-introduction). The internalShimsPresent
graceful-handling already existed in audit code; no behavioral
change there.
A future PR that introduces a new private @superdoc/* import on the
public surface fails audit Rule 1 at build time. Verified with a
synthetic injection: import('@superdoc/some-new-private-pkg').T in a
public-reachable d.ts produces FAIL findings: private-specifiers and
exits 1.
Net diff: -167 +41 lines across the two scripts.
Verified: build:es clean (10 guarded packages, no shim file emitted),
consumer matrix 47/0/0, runtime smoke 4/4, dist has zero
_internal-shims references, negative test confirms hard-landing.
…942) The comment above the inline-replacement block was inherited from the pre-SD-2893 era and described two things that are no longer true after the shim drain: 1. "fall through to the ambient shim block below" — SD-2942 (this PR) removes the shim block, so non-main-entry @superdoc/common imports now resolve via the RELOCATION_RULES rewriter, not via a fallback shim. 2. "Comment, CommentContent, CommentJSON ... not on the public surface" — SD-2893 stack 6 (PR #3154) relocated these types via the bare @superdoc/common rule mapping to comments-types.d.ts. `Comment` is now publicly importable as `import type { Comment } from 'superdoc/super-editor'`. Replace the block with a description of what the inline-replacement step actually does today: handle the main entry's runtime-value imports (DOCX, PDF, HTML, getFileObject, compareVersions, BlankDOCX) which are not type-only and so the relocation rule cannot serve them.
…(SD-2864) The same workspace-relocation taxonomy was duplicated across four files: ensure-types.cjs, audit-declarations.cjs, vite.config.js, and tsconfig.json. Adding a new public-surface relocation required coordinated edits in all four. PR #3144 (pm-adapter) and several SD-2893 stack PRs each shipped a regression caused by drift between these lists. Add packages/superdoc/scripts/type-surface.config.cjs as the single source of truth and refactor each consumer to derive what it needs. Consumer changes: - ensure-types.cjs: derives RELOCATION_RULES, RELOCATION_GUARD_PACKAGES, UNSHIMMED_PRIVATE_SPECIFIERS, SHARED_COMMON_DTS_TARGETS, requiredEntryPoints, and HANDWRITTEN_DTS_BLOCKLIST from the config. - audit-declarations.cjs: derives RELOCATION_GUARD_PACKAGES and RULE1_ALLOWLIST from the config. - vite.config.js: derives the dts include list by spreading relocations[*].viteIncludes after the foundational base entries (uses createRequire to load the CJS config from ESM Vite config). - tsconfig.json stays hand-edited (it's plain JSON), but a new check-tsconfig-type-surface.cjs script enforces parity by verifying every relocation's tsconfigIncludes paths are present in tsconfig.json's include array. Wired into postbuild so drift fails the build. Net diff: -138 +47 lines across the consumer scripts plus +208 lines for the new config + parity check. The config is the authoritative taxonomy; the parity check is the safety net that makes accidental drift loud. Verified: build:es clean (10 guarded packages, no shim file emitted), consumer matrix 47/0/0, declaration audit clean. Negative drift test: removing pm-adapter entries from tsconfig.json's include makes the parity check exit 1 with a clear message naming the missing entries and the relocation that requires them; restoring exits 0.
![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: 8b84be7b33
ℹ️ 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".
…ig (SD-2864) The previous commit's claim that these two lists derive from type-surface.config.cjs was wrong: the inline literals in ensure-types.cjs were never replaced. The build kept passing because the values matched, but a contributor editing the config without also editing the script would silently land a half-applied change. Replace the inline `new Set([...])` for HANDWRITTEN_DTS_BLOCKLIST and the inline string array for SHARED_COMMON_DTS_TARGETS with references to the config's handwrittenDtsBlocklist and sharedCommonDtsTargets so the original commit's claims hold. Also annotate the two @superdoc/common relocation entries' empty viteIncludes/tsconfigIncludes arrays inline so a reader does not have to walk back to the module-level JSDoc to learn they are emitted via the tsc-postbuild path.
The previous fix commit caught HANDWRITTEN_DTS_BLOCKLIST and SHARED_COMMON_DTS_TARGETS but missed requiredEntryPoints, which remained inline. With this commit all three lists in ensure-types.cjs that the SD-2864 PR description claims to derive from the config actually do. Verified: build clean, the three list lengths read from type-surface.config.cjs match what was previously hardcoded (requiredEntryPoints: 4, sharedCommonDtsTargets: 3, handwrittenDtsBlocklist: 1).
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
The original check only fired on missing-entry drift (config requires X, tsconfig is missing X). It tolerated stale-entry drift (tsconfig has Y, config no longer requires Y), undermining the single-source-of- truth claim: a relocation removed from type-surface.config.cjs could leave a stale tsconfig include compiling against source the type surface no longer claims to manage. Add baseTsconfigIncludes to type-surface.config.cjs for the foundational source roots that aren't relocations (`src`, `../super-editor/src`, `../document-api/src`). The check now asserts tsconfig.include equals exactly baseTsconfigIncludes plus relocations[*].tsconfigIncludes - no more, no less. Catches three drift modes now: 1. New relocation in config but not mirrored in tsconfig. 2. Relocation removed from config but tsconfig entry left stale. 3. Foundational base entry dropped from tsconfig by mistake. Verified end-to-end: - Clean build passes (12 expected paths matched exactly) - Synthetic missing-entry drift exits 1 with named owner - Synthetic stale-entry drift exits 1 with remediation hint - Restored exits 0
Contributor
|
🎉 This PR is included in @superdoc-dev/mcp v0.3.0-next.55 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in vscode-ext v2.3.0-next.99 |
Contributor
|
🎉 This PR is included in @superdoc-dev/react v1.2.0-next.97 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-cli v0.8.0-next.73 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc v1.30.0-next.56 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-sdk v1.8.0-next.56 |
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.
Stacked on #3155. Consolidates the workspace-relocation taxonomy that was previously duplicated across four files into a single source of truth.
The duplication:
ensure-types.cjs,audit-declarations.cjs,vite.config.js, andtsconfig.jsoneach carried parallel data about which packages get relocated, which sources to include, which packages to guard, and which specifiers are allowlisted. Adding a new relocation required coordinated edits in all four. PR #3144 (pm-adapter) and several SD-2893 stack PRs each shipped a regression caused by drift.The fix:
packages/superdoc/scripts/type-surface.config.cjsis now the canonical taxonomy. Each consumer derives what it needs:ensure-types.cjs:RELOCATION_RULES,RELOCATION_GUARD_PACKAGES,UNSHIMMED_PRIVATE_SPECIFIERS,SHARED_COMMON_DTS_TARGETS,requiredEntryPoints,HANDWRITTEN_DTS_BLOCKLISTaudit-declarations.cjs:RELOCATION_GUARD_PACKAGES,RULE1_ALLOWLISTvite.config.js: dts include list spreadsrelocations[*].viteIncludesafter the foundational base entries (createRequire from ESM)tsconfig.jsonstays hand-edited (it's JSON), but a newcheck-tsconfig-type-surface.cjsenforces parity in postbuild - drift fails the build with a clear messageNet diff: -138 +47 lines across the consumer scripts; +208 lines for the new config + parity check. Net is +117 because the config carries explanatory comments alongside the data, but the duplicated data is gone - the next contributor adding a relocation edits one place instead of four.
Verified:
pnpm --filter superdoc build:esclean (10 guarded packages, no shim emitted)tsconfig.json's include makes the parity check exit 1 withtsconfig.json \include` is missing relocation entries: ../layout-engine/pm-adapter/src/converter-context.ts (required by @superdoc/pm-adapter/converter-context.js)and a remediation hint. Restoring the entries exits 0 with✓ tsconfig.json mirrors 9 relocation include paths`.Closes the SD-2828 cleanup arc. After SD-2942 (#3155) and this PR land, the type-surface contract has both substantive enforcement (audit Rule 1 + Rule 3) and structural coherence (single-source-of-truth taxonomy + tsconfig parity check).