refactor(superdoc): type #initCollaboration param as Modules (SD-2867 phase B)#3060
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
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 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
1 participant
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.
`#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}` / `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 via SD-2880). 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).
Stacked on #3058 because both PRs migrate `@param {Object}` annotations on private SuperDoc.js methods.
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.
Gates: `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.