fix(superdoc): hide internal fields at source + repair node16 Config resolution (SD-2886)#3056
Merged
Merged
Conversation
superdoc-bot
Bot
added
review: thorough
review: quick
and removed
review: thorough
labels
caio-pizzol
force-pushed
the
caio/SD-2886-strip-internal-fields
branch
from
8364657 to
59d0fb4
Compare
caio-pizzol
force-pushed
the
caio/SD-2886-strip-internal-fields
branch
from
59d0fb4 to
8fe5e29
Compare
caio-pizzol
changed the title
caio-pizzol
force-pushed
the
caio/SD-2886-strip-internal-fields
branch
3 times, most recently
from
45d4bf2 to
59aa639
Compare
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…resolution (SD-2886)
After SD-2880 published Config and SuperDocLayoutEngineOptions, two
fields the source explicitly marks as internal became reachable on the
public surface:
- Config.socket. 'Internal: ... do not pass from outside.' Set by
SuperDoc when modules.collaboration.providerType is 'hocuspocus';
a consumer who passes it from outside breaks the collaboration
setup.
- SuperDocLayoutEngineOptions.semanticOptions. 'Internal-only ...
intentionally not a stable public API in v1.' A consumer who
pins a shape couples themselves to behavior we may break.
Earlier attempts and why they were wrong:
1. stripInternal: true in superdoc's tsconfig. Review pass found
this would silently strip 100+ pre-existing @internal-tagged
fields across super-editor (ImageAttrs.id, ParagraphAttrs.paraId,
TableAttrs.sdBlockId, etc.) — a worse regression than the one
this PR closes.
2. Omit<...> at the typedef alias boundary in superdoc/src/index.js.
Review pass found this only narrowed the standalone Config alias.
The nested Config.layoutEngineOptions still reached the un-Omitted
SuperDocLayoutEngineOptions, and the SuperDoc constructor signature
still took the un-Omitted Config — so `new SuperDoc({ socket })`
and `{ layoutEngineOptions: { semanticOptions } }` still type-
checked.
This patch removes both fields from the source `Config` and
`SuperDocLayoutEngineOptions` interfaces in core/types/index.ts and
adds InternalConfig / InternalSuperDocLayoutEngineOptions extensions
for the runtime callsites that need the augmented shape (SuperDoc.js's
this.config.socket assignments, etc.). Public surface no longer carries
either field anywhere it can be reached.
Side fix surfaced by the same review: the JSDoc `@typedef
{import('./types').X}` form in core/SuperDoc.js and core/surface-manager.js
did not resolve under TypeScript's node16 module resolution. The published
constructor signature decayed to `any` for node16 consumers, and the
constructor probe (`new SuperDoc({ socket: undefined })`) silently
type-checked. Switched all 11 `import('./types')` usages to
`import('./types/index.js')` so the path resolves under both bundler
and node16.
The regression-net fixture under tests/consumer-typecheck/ now covers
all four reachable surfaces: standalone Config alias, standalone
SuperDocLayoutEngineOptions alias, nested Config.layoutEngineOptions,
and the SuperDoc constructor parameter. Each uses @ts-expect-error so
a regression on any path fails CI with TS2578 ("Unused @ts-expect-error
directive").
Verified: matrix passes 31/31; declaration audit reports no FAIL
findings; published .d.ts no longer references socket or
semanticOptions on any reachable public path.
caio-pizzol
force-pushed
the
caio/SD-2886-strip-internal-fields
branch
from
59aa639 to
50d7bee
Compare
caio-pizzol
changed the title
Contributor
|
🎉 This PR is included in @superdoc-dev/mcp v0.3.0-next.31 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in @superdoc-dev/react v1.2.0-next.74 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in vscode-ext v2.3.0-next.76 |
Contributor
|
🎉 This PR is included in superdoc v1.30.0-next.33 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-cli v0.8.0-next.49 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-sdk v1.8.0-next.35 |
Contributor
|
🎉 This PR is included in superdoc-cli v0.8.0 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-sdk v1.8.0 |
Contributor
|
🎉 This PR is included in @superdoc-dev/mcp v0.3.0 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc v1.31.0 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in vscode-ext v2.3.0 |
Contributor
|
🎉 This PR is included in @superdoc-dev/react v1.3.0 The release is available on GitHub release |
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.
After SD-2880 (#3053) published `Config` and `SuperDocLayoutEngineOptions`, two internal-only fields became reachable through the public surface:
Two earlier attempts surfaced their own problems and were rejected:
This patch removes both fields from the source `Config` and `SuperDocLayoutEngineOptions` interfaces in `core/types/index.ts` and adds `InternalConfig` / `InternalSuperDocLayoutEngineOptions` extensions for the runtime callsites that need the augmented shape. Public surface no longer carries either field anywhere it can be reached.
Side fix surfaced by the same review: the JSDoc `@typedef {import('./types').X}` form in `core/SuperDoc.js` and `core/surface-manager.js` did not resolve under TypeScript's node16 module resolution. The published constructor signature decayed to `any` for node16 consumers, and the constructor probe silently type-checked. Switched all 11 `import('./types')` usages to `import('./types/index.js')` so the path resolves under both bundler and node16.
The regression-net fixture under `tests/consumer-typecheck/` now covers all four reachable surfaces: standalone `Config` alias, standalone `SuperDocLayoutEngineOptions` alias, nested `Config.layoutEngineOptions`, and the `SuperDoc` constructor parameter. Each uses `@ts-expect-error` so a regression on any path fails CI with TS2578 ("Unused @ts-expect-error directive").
Verified: matrix passes 31/31; declaration audit reports no FAIL findings; published `.d.ts` no longer references `socket` or `semanticOptions` on any reachable public path.