refactor(superdoc): add RuntimeDocument typedef for runtime doc shape (SD-2867 phase B)#3058
Merged
Merged
Conversation
…hase B) `createSuperdocVueApp()` returned `Object` per its JSDoc, so the five fields SuperDoc.js destructures from the call (`app`, `pinia`, `superdocStore`, `commentsStore`, `highContrastModeStore`) all resolved to `Object` for any consumer enabling `// @ts-check`. Five TS2339 'Property does not exist on type Object' errors at SuperDoc.js line 464 — and inside the SD-2867 ratchet that turns each into a gate failure. Promotes the return type to a named `SuperdocVueAppRefs` typedef that imports `vue.App`, `pinia.Pinia`, and the store types via `ReturnType<typeof useSuperdocStore>` etc. The shape is internal-only (this typedef is not on the public Modules / Config surface), so adding it here doesn't widen the customer-visible surface. Verified: pnpm --filter superdoc run check:jsdoc passes (3 gated files clean); the consumer-typecheck matrix passes 31/31; the postbuild declaration audit reports no FAIL findings; pnpm --filter superdoc test passes 944/944. This is groundwork for SD-2867 phase B: closing each cluster of SuperDoc.js TS errors so the file can eventually enroll in `CHECKED_FILES`. Five errors closed; ~133 remain across implicit-any params, strict-null guards, and other type-not-assignable callsites. Each cluster will land as its own focused commit.
superdoc-bot
Bot
added
review: thorough
review: quick
and removed
review: thorough
labels
caio-pizzol
force-pushed
the
caio/SD-2867-phase-b-runtime-doc
branch
2 times, most recently
from
de24d4b to
0c1ba5d
Compare
… (SD-2867 phase B)
The internal `doc` parameter in SuperDoc.js's private methods (#applyDocumentMode,
#attachExternalCollaboration, etc.) is shaped differently from the
public `Document` interface: SuperDoc attaches a runtime `role`,
`getEditor()`, and `getPresentationEditor()` to each entry during
init. Today those methods are typed `@param {Object} doc`, so any
attempt to enable `// @ts-check` on SuperDoc.js fails with TS2339
errors at every `doc.getEditor()` / `doc.getPresentationEditor()` /
`doc.role` access (~10 sites).
Adds a `RuntimeDocument` typedef in core/types/index.ts that extends
the public `Document` with the runtime-attached fields. Updates
#applyDocumentMode's `@param {Object} doc` to `@param {RuntimeDocument}
doc` as the first call site to migrate.
The typedef is internal-only and not on the public superdoc surface
(not in the public typedef block of packages/superdoc/src/index.js),
so consumers cannot import or pass these fields from outside.
This is groundwork: subsequent SD-2867 phase B PRs will migrate the
remaining `@param {Object} doc` sites and then enable @ts-check on the
methods involved.
Verified: pnpm --filter superdoc run check:jsdoc passes (3 gated files
clean); consumer matrix passes 31/31; declaration audit reports no
FAIL findings; published .d.ts surface unchanged (RuntimeDocument is
not re-exported from the public superdoc entry).
caio-pizzol
force-pushed
the
caio/SD-2867-phase-b-runtime-doc
branch
from
0c1ba5d to
a6be8d7
Compare
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-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 @superdoc-dev/mcp v0.3.0-next.33 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in superdoc-sdk v1.8.0-next.37 |
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.
The internal `doc` parameter in SuperDoc.js's private methods (`#applyDocumentMode`, `#attachExternalCollaboration`, etc.) is shaped differently from the public `Document` interface: SuperDoc attaches a runtime `role`, `getEditor()`, and `getPresentationEditor()` to each entry during init. Today those methods are typed `@param {Object} doc`, so any attempt to enable `// @ts-check` on SuperDoc.js fails with TS2339 errors at every `doc.getEditor()` / `doc.getPresentationEditor()` / `doc.role` access (~10 sites).
Adds a `RuntimeDocument` typedef in `core/types/index.ts` that extends the public `Document` with the runtime-attached fields. Updates `#applyDocumentMode`'s `@param {Object} doc` to `@param {RuntimeDocument} doc` as the first callsite to migrate.
The typedef is internal-only and not on the public superdoc surface (not in the public typedef block of `packages/superdoc/src/index.js`), so consumers cannot import or pass these fields from outside.
Stacked on #3057 because both PRs add internal typedefs in the same area; will rebase to main if #3057 lands first.
This is groundwork: subsequent SD-2867 phase B PRs will migrate the remaining `@param {Object} doc` sites and then enable `@ts-check` on the methods involved.
Verified: `pnpm --filter superdoc run check:jsdoc` passes (3 gated files clean); consumer matrix passes 31/31; declaration audit reports no FAIL findings; published `.d.ts` surface unchanged (`RuntimeDocument` is not re-exported from the public superdoc entry).