fix(types): guard pm-adapter barrel relocation#3144
Merged
caio-pizzol merged 2 commits intomainfrom May 5, 2026
Merged
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
|
🎉 This PR is included in @superdoc-dev/mcp v0.3.0-next.47 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in @superdoc-dev/react v1.2.0-next.89 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in vscode-ext v2.3.0-next.91 |
Contributor
|
🎉 This PR is included in superdoc-cli v0.8.0-next.65 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc v1.30.0-next.48 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-sdk v1.8.0-next.50 |
caio-pizzol
added a commit
that referenced
this pull request
May 5, 2026
* fix(types): drop accidental BasicUpload public re-export (SD-2893) BasicUpload was re-exported through `superdoc/super-editor` and `superdoc` despite being marked `@internal` at the export site (packages/super-editor/src/editors/v1/index.js:103). It is not documented in any README, AGENTS guide, or example. The two dev components that use it (SuperdocDev.vue, DeveloperPlayground.vue) import it directly from `@superdoc/common/components/BasicUpload.vue`, not via the public re-export. Drop the re-export rather than relocating the .vue file. The upload widget is dev-tooling, not a public API. The bare `@superdoc/common/components/BasicUpload.vue` shim entry goes away because no public d.ts file references it anymore. Also removes the BasicUpload assertion from the consumer-typecheck customer-scenario fixture so the matrix stays green; the fixture was the only place the public re-export was exercised. Shim count: 3 to 2. Remaining: @superdoc/common (5 dist refs, catch-all bin), @superdoc/style-engine/ooxml (10 dist refs). Verified: build:es clean (8 guarded packages, 2 shim modules), consumer matrix 47/0/0, runtime smoke 4/4 with BasicUpload explicitly asserted absent from main and super-editor entries. * fix(types): drain @superdoc/style-engine/ooxml shim (SD-2893) The /ooxml subpath of style-engine is the only part publicly reachable today (10 dist d.ts references across pm-adapter, diffing, super-converter, parts adapters, and plan-engine). Approach mirrors the pm-adapter narrow-scope pattern from #3144: - Include only the ooxml subtree plus its sibling cascade.ts dependency in vite-plugin-dts. A full src/**/* glob would pull the broader project graph through @superdoc/contracts project references and re-expand the shim list. - Add an exact relocation rule for @superdoc/style-engine/ooxml. - Guard the bare @superdoc/style-engine root in both RELOCATION_GUARD_PACKAGES and UNSHIMMED_PRIVATE_SPECIFIERS so a future bare-barrel leak fails audit Rule 1 instead of producing a broken relative path or an ambient any shim. Also removes a misleading JSDoc @example block from cascade.ts. The example showed `import from '@superdoc/style-engine/cascade'` which is not a valid public import (cascade is not in the package's exports field), and the bare specifier inside the @example was being captured by the workspace-import scanner. Shim count: 2 to 1. Only @superdoc/common remains. Verified: build:es clean (9 guarded packages, 1 shim module), consumer matrix 47/0/0, runtime smoke 4/4, dist has the 6 expected declaration files, negative tests confirm the /ooxml subpath rewrites to a real target file and a bare @superdoc/style-engine specifier is preserved unchanged for audit Rule 1 to catch.
caio-pizzol
added a commit
that referenced
this pull request
May 5, 2026
…(SD-2864) (#3161) * refactor(types): remove _internal-shims.d.ts soft-landing mechanism (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. * docs(types): fix stale comment about @superdoc/common shim path (SD-2942) 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. * refactor(types): centralize public-surface taxonomy in single config (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. * refactor(types): derive blocklist and tsc-postbuild targets from config (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. * refactor(types): derive requiredEntryPoints from config (SD-2864) 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). * fix(types): tsconfig parity check now bidirectional (SD-2864) 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
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.
Summary
Verification
Note: pack:es emits the existing soft CSS budget warning; declaration build/audit is clean.