refactor(superdoc): tighten @param {Object} on three callback methods (SD-2867 phase B)#3061
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.
… (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).
… phase B)
#initCollaboration's @param was typed `Object`, so any consumer that
enables `// @ts-check` on SuperDoc.js fails at every destructure of
the function's parameter (`{ collaboration, comments }`) and at
every read of `collaborationModuleConfig.{ydoc,provider}` and
`commentsConfig.*`. Two TS2339s on line 519, plus all the downstream
property accesses up to line 605.
The actual call site at line 295 passes `this.config.modules`, so
the right shape is `Modules` (already publicly exported). Tightens
the @param to `Modules` and the @returns to `Promise<Document[] |
undefined>` (which is what the function actually returns; the value
is informational, not consumed by the caller).
Verified locally: with `// @ts-check` enabled on SuperDoc.js,
`#initCollaboration`'s body (lines 519-605) is fully type-clean.
The remaining error at line 606 is a downstream callsite (passing
`User | undefined` to a function expecting `Object`) and belongs to
the next phase B cluster, not this one.
This is groundwork; SuperDoc.js does not enroll under the gate yet.
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.
superdoc-bot
Bot
added
review: thorough
review: quick
and removed
review: thorough
labels
caio-pizzol
force-pushed
the
caio/SD-2867-phase-b-callback-params
branch
from
4ae8ee8 to
c81eb19
Compare
… (SD-2867 phase B)
Three private/public callback methods on SuperDoc had `@param {Object}`
JSDoc that masked their actual contract:
- addSharedUser(user) — typed as Object; actually expects User
(the function reads u.email, which is a User field).
- onContentError({ error, editor }) — typed as Object; actually
expects an Error/Editor pair forwarded to config.onContentError.
- canPerformPermission({ permission, role, isInternal, comment,
trackedChange }) — typed as Object; the params are read at the
body and forwarded into the permissions resolver chain. Promoted
to a structural typedef with permission/role/isInternal/comment/
trackedChange optional (the function defaults `= {}` and treats
missing permission as a no-op via the early `if (!permission)
return false` guard).
Skipped goToSearchResult: the upstream `commands.goToSearchResult`
expects a private `SearchMatch` shape (id/from/to/text) that is
not on the public surface yet. Tightening that requires either
exporting SearchMatch publicly or asserting at the call site;
deferring to a separate follow-up. Left a comment on the JSDoc
documenting the deferral.
This is groundwork for SD-2867 phase B's gate enrollment of
SuperDoc.js. Each subsequent PR closes one cluster.
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.
caio-pizzol
force-pushed
the
caio/SD-2867-phase-b-callback-params
branch
from
c81eb19 to
08bcd38
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-dev/react v1.2.0-next.75 The release is available on GitHub release |
Contributor
|
🎉 This PR is included in vscode-ext v2.3.0-next.77 |
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.
Three callback methods on SuperDoc had `@param {Object}` JSDoc that masked their actual contract:
Stacked on #3060 because all three sites are typedef-tightening on private/public methods of `SuperDoc.js`.
Skipped `goToSearchResult`: the upstream `commands.goToSearchResult` expects a private `SearchMatch` shape (`{ id, from, to, text }`) that is not on the public surface yet. Tightening that requires either exporting `SearchMatch` publicly or asserting at the call site; deferring to a separate follow-up. Left a comment on the JSDoc documenting the deferral.
This is groundwork for SD-2867 phase B's gate enrollment of `SuperDoc.js`. Each subsequent PR closes one cluster.
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.