refactor(types): drain 85 type-bearing JSDoc entries from .ts source (SD-673) by caio-pizzol · Pull Request #3513 · superdoc-dev/superdoc

caio-pizzol · 2026-05-26T18:28:45Z

Drains the jsdoc-hygiene-ts baseline from 85 entries to 0. Follow-up to the scanner PR (#3511, now merged); this is the bulk mechanical cleanup. The zero-baseline enforcement flip lands in a third small PR after this.

declaration-doc-type (78 entries):

@param {T} name description -> @param name description (drop braces, keep prose).
@returns {T} description -> @returns description (drop braces, keep prose).
@template T - description -> @typeParam T - description. TSDoc-canonical replacement; prose preserved (16 entries across Mark / Node / OxmlNode / defineMark / defineNode / Extension / EventEmitter / helpers).
@extends {Base} / @implements {Iface} -> deleted (TS has native extends / implements syntax on the declaration).
Empty @returns tags removed (10 dead documentation lines across both EventEmitters and PresentationEditor where the brace strip left a tag carrying no information).

inline-fake-cast (6 entries: 5 from original baseline + 1 new on Editor.ts:219 that landed post-#3511):

#abortUpgrade, readyEditors, pendingCollaborationSaves: the @type was redundant next to the TS field annotation. Dropped the tag, kept the prose.
/** @type {RuntimeDocument} */ ... and /** @type {string} */ doc.id in SuperDoc.ts: real-intent casts that did nothing in .ts. Converted to as RuntimeDocument and as string.
/** @type {YMapEvent<unknown>} */ on a Yjs observe callback param in SuperDoc.ts: converted to a TS param annotation (event: Y.YMapEvent<unknown>).
/** @type {Mark[]} */ on insertionMarks in Editor.ts:219 (new in main since the scanner PR): converted to const insertionMarks: PmMark[] = [] (PmMark was already imported).
The InternalConfig doc example in types/index.ts was teaching the /** @type */ cast pattern explicitly. Rewrote to teach (value as Type) instead.

typedef-style (2 entries): rewrites. The @typedef tags lived inside @example blocks in defineMark.ts / defineNode.ts teaching JS consumers how to type-hint. Replaced literal /** @typedef */ syntax with prose describing the pattern; preserves teaching value without triggering the scanner.

Based directly on main (rebased after #3511 merged). 14 files changed; no infrastructure churn (rename / wiring / wrapper docs all landed in #3511).

Verified:

node packages/superdoc/scripts/check-jsdoc-hygiene-ts.cjs -> OK, 0 violations
node packages/superdoc/scripts/check-jsdoc-hygiene-ts-tests.cjs -> 13/13 pass
pnpm check:types -> PASS
pnpm check:public:superdoc --skip-build -> PASS (11 ran, 1 skipped, 135.3s)
pnpm --filter superdoc test --run -> PASS (1064/1064, 79 files)

linear-code · 2026-05-26T18:28:49Z

SD-673

cubic-dev-ai

No issues found across 18 files

_{Re-trigger cubic}

@returns

…(SD-673) Drains the jsdoc-hygiene-ts baseline from 85 entries to 0. Companion to the scanner PR (#3511) that grandfathered these entries; this is the bulk mechanical cleanup. The zero-baseline flip lands in a third PR after this. declaration-doc-type (78 entries): - @param {T} name description -> @param name description (drop braces, keep prose). - @returns {T} description -> @returns description (drop braces, keep prose). - @template T - description -> @typeparam T - description. TSDoc-canonical replacement; prose preserved (16 entries across Mark / Node / OxmlNode / defineMark / defineNode / Extension / EventEmitter / helpers). - @extends {Base} / @implements {Iface} -> deleted (TS has native extends / implements syntax on the declaration). - Empty @returns tags removed (10 dead documentation lines across both EventEmitters and PresentationEditor where the brace strip left a tag carrying no information). inline-fake-cast (6 entries: 5 from original baseline + 1 new on Editor.ts:219 that landed post-#3511): - #abortUpgrade, readyEditors, pendingCollaborationSaves: the @type was redundant next to the TS field annotation. Dropped the tag, kept the prose. - /** @type {RuntimeDocument} */ ... and /** @type {string} */ doc.id in SuperDoc.ts: real-intent casts that did nothing in .ts. Converted to 'as RuntimeDocument' and 'as string'. - /** @type {YMapEvent<unknown>} */ on a Yjs observe callback param in SuperDoc.ts: converted to a TS param annotation (event: Y.YMapEvent<unknown>). - /** @type {Mark[]} */ on insertionMarks in Editor.ts:219 (new in main since the scanner PR): converted to a TS local var annotation (PmMark[] is already imported). - The InternalConfig doc example in types/index.ts was teaching the /** @type */ cast pattern explicitly. Rewrote to teach '(value as Type)' instead. typedef-style (2 entries): rewrites. The @typedef tags lived inside @example blocks in defineMark.ts / defineNode.ts teaching JS consumers how to type-hint. Replaced literal /** @typedef */ syntax with prose describing the pattern; preserves teaching value without triggering the scanner. Verified: - node check-jsdoc-hygiene-ts.cjs -> OK, 0 violations - node check-jsdoc-hygiene-ts-tests.cjs -> 13/13 pass - pnpm check:types -> PASS - pnpm check:public:superdoc --skip-build -> PASS (11 ran, 1 skipped, 135.3s) - pnpm --filter superdoc test --run -> PASS (1064/1064, 79 files)

codecov-commenter · 2026-05-26T20:52:33Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

…jsdoc-hygiene-ts Two pre-review trims on the strict-zero scanner: - occurrenceIndex / occurrenceCounter were the stable-baseline-key mechanism. With strict-zero, there's no key — failure messages only need (file, line, tag, class, symbol) for display. Dropped the counter, the per-finding occurrenceIndex field, and the sort comparator that used it. Sort now keys on (file, line, tag) which is the natural display order for a scanner failure. - Removed '#3513'/'#3511' from source/doc prose. PR numbers belong in PR bodies, not long-lived files. The scanner header and type-hygiene.md now use timeless wording ('no baseline, grandfathering, or --write mode'). No behavior change. Scanner output, exit codes, and the canary case all match the previous commit.

### Bug Fixes - copy-pasted text in suggestion mode (#3576) - center virtualized matches after mount in find nav (SD-3315) - stop find navigation jumping to the reverted caret (SD-3315) - honor the focus() contract + fix dangling docs reference (SD-3312) - don't re-center visible matches on find navigation (SD-3315) - report 'zoom' not 'mixed' for a zoom repaint (SD-3311) - wire pointer-source tracking on all init paths; update export snapshot - reset state on unload, dedupe + export payload types, add core tests - skip empty block SDT content selection - type modules.contentControls exactly (no pass-through index) - allow block SDT wrapper deletion to follow lock rules - promote image-bearing inline SDT wrappers to inline-block - keep block sdt fill behind content - hide block sdt fills in output modes - paint block SDT background on chrome layer - use logical inset for inline SDT label position - anchor inline SDT label to start of chrome - route smartTag through export and preserve smartTagPr in SDT flatten (SD-2647) - include inline SDT chrome width in block SDT bounds - keep block SDT chrome at full fragment width - render and round-trip w:smartTag content (SD-2647) - decouple base64 image helper imports - preserve block ids during metadata updates - ignore covered sdt label clicks - sync block sdt label selection updates - show empty SDT placeholder text in viewing and print modes - skip empty sdt scan on arrow right - preserve permission-only sdt placeholders - preserve comment-only sdt placeholders - preserve empty sdt bookmark placeholders - collapse hidden sdt placeholder text - keep sdt placeholder pm range atomic - trust empty sdt paragraph conversion - keep vanished sdt paragraph side effects - preserve vanished block sdt paragraphs - suppress hidden block sdt chrome - keep remeasured sdt placeholder atomic - transform sdt placeholder measure - remeasure sdt placeholders - hide sdt placeholders in print - hide sdt placeholders in viewing - ignore collapsed inline sdt cut - expose block sdt appearance - hide empty block sdt placeholder - align empty block sdt caret - use measured width for empty SDT placeholders - size SDT block labels to content width - collapse selection on sdtContentLocked delete - allow history transactions through sdt lock - drop unreachable move fallback - target marker-only textblock end - ignore empty block sdt key targets - cap block sdt label width - handle sdt marker gaps and block atoms - skip hidden field annotations in sdt navigation - skip hidden metadata sdt markers - skip hidden block sdt markers - handle marker-only sdt paragraphs - keep visible atoms in sdt navigation - skip hidden sdt navigation markers - target nearest sdt cursor position - respect inline atoms in sdt navigation - handle empty block sdt navigation - avoid restoring dragged block to its source position - exclude sdt chrome labels from caret position lookup - keep text-align enabled in locked SDT paragraphs - block disabled toolbar execution - guard unlisted locked toolbar commands - block locked sdt toolbar execution - reject malformed base64 image data URIs - reuse colliding data uri media targets - enforce upload byte cap for data uris - avoid non-image data uri extensions - reject raw raster data uri dimensions - validate oversized async svg images - register preset raster data uris in place - narrow sdt metadata overrides - normalize image data uri extensions - centralize image data url policy - reuse target image relationships - validate in-place svg payloads - validate field annotation data uri exports - reject malformed data uri files - avoid duplicate image rids - block raw raster data uri exports - reject malformed svg data uri payloads - warn on skipped image exports - reject separatorless data uri files - block non-image data uri exports - read svg data uri dimensions - share data uri media parsing - skip invalid data uri image targets - normalize svg data uri filenames - validate in-place svg image data - guard non-base64 data uri exports - export field annotation svgs as svg - allow non-base64 SVG data URLs in image rendering - mirror in-place image media to parent - decode non-base64 data URI exports - extract shared hash helpers - reuse data URI image exports - support non-base64 data URI images in registration - scope inline SDT placeholder to structuredContent metadata - register sized SVG data URI images without canvas processing - persist data URI images set via setPresetContent - share SDT lock predicates - version inline image metadata - align RTL SDT chrome to text - size SDT chrome for justified lines - honor ancestor image SDT locks - dirty inline image SDT changes - align SDT chrome within paragraph width - preserve SDT chrome continuation offsets - offset block SDT chrome for indents - suppress SDT pseudo hover in viewing mode - allow top-aligned inline images - fit block SDT chrome to actual content width - bottom-align text on lines with inline images - keep block SDT chrome and inline images out of paragraph geometry - disable image resize inside content-locked SDTs - detect inline image run changes in paragraph diff - mark block SDT selected when contained image is selected - select inline SDT content as text on Delete - intercept beforeinput insertText at inline SDT boundaries - delete contentLocked SDT wrapper in one step - bump sdBlockRev on ancestors of inline edits - select inline SDT content as text on Backspace - select inline SDT on Backspace at start of following run (SD-3165) - share structured content chrome label set - resolve block labels at node boundary - use contract label selectors - clear label gesture state on cancel - scope label clicks to owning editor - defer label selection to mouseup so native drag still fires - share structured content label classes - avoid deferred block label retry - select labels with active editor - focus editor after label selection - correct cursor placement and label interactions for structured content - handle cell-level SDT in vMerge column lookup (SD-3289) - preserve cell-level SDT wrapping table cells (SD-3289) - preserve recipient identity attrs on replay (SD-3279) - accept legacy fingerprints in compare/apply (SD-3279) - drop misleading pnpm run type-check hint from audit - structural-fail on missing dist + sync check-jsdoc header - strip session-local sdBlockId from diff fingerprint (SD-3279) - autoFit table width overflow from cell preferences (#3522) - flip public-method-coverage to strict-zero gate (SD-673) - flip jsdoc-hygiene-ts to strict-zero gate (SD-673) - rename jsdoc-hygiene-ts self-tests + wire into CI (fixes vitest discovery on #3511) - jsdoc-hygiene-ts handles private-identifier symbols + README - more bugs - add ui for overlapping delete, other fixes - replacement pair - remaining collab bugs - coalesce tracked inserts across run gaps - restore tracked change comment interactions - expose tracked mark predicate option - more cases - tc fixes - collab mode bug - floating comments fixes - make jsdoc-hygiene-ts baseline key line-independent + update wrapper docs - preserve tab underline via runProperties fallback in collab ### Changes - Merge branch 'main' into caio/sd-3315-find-replace-scroll - Merge pull request #3509 from superdoc-dev/artem/SD-3232 - Merge pull request #3555 from superdoc-dev/luccas/delete-image-content-locked-sdt - Merge branch 'main' into artem/SD-3159 - Merge pull request #3550 from superdoc-dev/luccas/sd-3302-bug-sdt-in-template-builder-shows-grey-background-highlight - Merge branch 'main' into artem/SD-3159 - SD-2676 - fix: table selection not providing a feedback (#3508) - Merge pull request #3549 from superdoc-dev/luccas/left-align-inline-sdt-label - Merge pull request #3546 from superdoc-dev/caio/sd-2647-bug-render-and-round-trip-content-wrapped-in-wsmarttag - Merge remote-tracking branch 'origin/stable' into sync/stable-to-main-20260527-230540 - Merge pull request #3539 from superdoc-dev/caio-pizzol/sd-3289-preserve-cell-level-sdt - Merge pull request #3527 from superdoc-dev/caio-pizzol/sd-3279-strip-sdblockid-from-diff-fingerprint - Merge branch 'main' into caio-pizzol/SD-js-contract-owner-audit - Merge pull request #3531 from superdoc-dev/caio-pizzol/SD-docs-snippet-typecheck-2 - Merge pull request #3526 from superdoc-dev/caio-pizzol/SD-runtime-payload-tests - Merge pull request #3521 from superdoc-dev/caio-pizzol/SD-public-method-coverage-strict-zero - Merge branch 'stable' - Merge pull request #3485 from superdoc-dev/artem/SD-3200 - Merge pull request #3517 from superdoc-dev/caio-pizzol/SD-jsdoc-hygiene-zero-flip - Merge pull request #3513 from superdoc-dev/caio-pizzol/SD-jsdoc-hygiene-cleanup - Merge branch 'stable' - Merge pull request #3511 from superdoc-dev/caio-pizzol/SD-jsdoc-hygiene-scanner - Merge pull request #3435 from superdoc-dev/nick/sd-3220-overlapping-suggestion-contract - Merge pull request #3429 from superdoc-dev/artem/underlined-tab-collab ### Documentation - note content controls in entityAt hit types (SD-3313) - clarify data uri buffer conversion - document image data uri helpers - clarify image registration comments - sync README exit semantics for js contract-owner audit - clarify wrapper-stages prose + add ts-jsdoc to check:public summary ### Features - add ui.contentControls.focus to place the caret in a control (SD-3312) - add ui.viewport.observe geometry-invalidation signal (SD-3311) - add ui.contentControls.scrollIntoView (SD-3310) - add activePath (full active stack) to content-control:active-change - expose public sdt events - select adjacent block SDT content at textblock boundaries - inherit run styles in empty block SDT placeholders - render placeholder text for empty SDTs - move caret into following block sdt on delete - move caret into preceding block sdt on backspace - disable mutation toolbar controls inside content-locked SDTs - render empty inline SDTs as a visible placeholder - add modules.contentControls.chrome - js contract-owner audit, report-only (SD-673) - add snippet typecheck for editor/superdoc/** + fix stale examples (SD-673) - add non-hover field color for sdt (#3506) - comments and tc on small screen (#3446) - overlapping tracked changes - add type-bearing JSDoc hygiene gate for .ts source (SD-673) - add anchored metadata orphan status ### Tests - resolve handleBase64 source path from package or repo root - cover locked block SDT Delete selection - cover nested block SDT boundary selection - update SDT keymap chain coverage - cover contentControlsChrome plumbing; clarify chrome-none comment - assert chrome-none hover suppression and cascade order - add v2 bridge unit + round-trip behavior coverage (SD-2647) - assert smartTag child text survives export round-trip (SD-2647) - cover nested block sdt navigation - roundtrip mixed image block sdts - cover image data uri length boundary - repaint saved sdt images through painter - cover structured content image edges - cover inline image diff fields - cover locked inline SDT beforeinput - cover inline SDT Cmd+X selection - cover inline SDT content Delete flow - clarify inline SDT boundary lock comment - cover two-step inline SDT Backspace - cover inline SDT selection meta escape - use real production payload for list-definitions-change bridge (SD-673) - tighten list-definitions-change bridge assertion (SD-673) - pin list-definitions-change bridge and DELETED comments shape (SD-673) - pin runtime event payload shapes (SD-673) ### Refactoring - consolidate type imports in dom painter - share block sdt navigation helpers - share box model between block and inline sdt labels - share structured content predicates - wrap shared tryDecodeDataUriText re-export - reuse shared data uri export policy - share image relationship export lookup - centralize image data uri parsing - share data uri text decoding - trim data uri metadata fields - extract CHECKED_FILES to shared module + drop audit from wrapper - drop list-item fragment renderer (SD-2851) (#3269) - drain 85 type-bearing JSDoc entries from .ts source (SD-673) ### Performance - avoid scanning data uri media ### Chores - 1.37.0 [skip ci] - fix import breaking delinstrtext orphans (#3535) - fix tests (#3533) - fixes - more fixes - run generate:all and fixes - more fixes - soec fixes - type fixes - ui and more - fix regression - type fixes - more fixes - more fixes - ci fixes - type fixes - add dispatch test for collab bug - review fix, type fix - add tests for metadata issue - tests for review issues

superdoc-bot · 2026-05-29T21:27:15Z

🎉 This PR is included in superdoc-cli v0.15.0

The release is available on GitHub release

superdoc-bot · 2026-05-29T21:39:22Z

🎉 This PR is included in superdoc-sdk v1.14.0

superdoc-bot · 2026-05-29T21:42:34Z

🎉 This PR is included in @superdoc-dev/mcp v0.10.0

The release is available on GitHub release

superdoc-bot · 2026-05-29T21:47:35Z

🎉 This PR is included in superdoc v1.38.0

The release is available on GitHub release

superdoc-bot · 2026-05-29T21:51:19Z

🎉 This PR is included in @superdoc-dev/react v1.9.0

The release is available on GitHub release

superdoc-bot · 2026-05-29T21:56:28Z

🎉 This PR is included in vscode-ext v2.10.0

caio-pizzol requested a review from a team as a code owner May 26, 2026 18:28

superdoc-bot Bot added review: thorough review: quick and removed review: thorough labels May 26, 2026

cubic-dev-ai Bot reviewed May 26, 2026

View reviewed changes

Base automatically changed from caio-pizzol/SD-jsdoc-hygiene-scanner to main May 26, 2026 20:14

caio-pizzol force-pushed the caio-pizzol/SD-jsdoc-hygiene-cleanup branch from 81a33a0 to e5ac087 Compare May 26, 2026 20:37

caio-pizzol mentioned this pull request May 26, 2026

fix(scripts): flip jsdoc-hygiene-ts to strict-zero gate (SD-673) #3517

Merged

caio-pizzol merged commit ead3815 into main May 26, 2026
70 checks passed

caio-pizzol deleted the caio-pizzol/SD-jsdoc-hygiene-cleanup branch May 26, 2026 21:41

superdoc-bot Bot added the released on @latest label May 29, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(types): drain 85 type-bearing JSDoc entries from .ts source (SD-673)#3513

refactor(types): drain 85 type-bearing JSDoc entries from .ts source (SD-673)#3513
caio-pizzol merged 1 commit into
mainfrom
caio-pizzol/SD-jsdoc-hygiene-cleanup

caio-pizzol commented May 26, 2026 •

edited

Loading

Uh oh!

linear-code Bot commented May 26, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

codecov-commenter commented May 26, 2026

Uh oh!

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

caio-pizzol commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linear-code Bot commented May 26, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

codecov-commenter commented May 26, 2026

Codecov Report

Uh oh!

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

superdoc-bot Bot commented May 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

caio-pizzol commented May 26, 2026 •

edited

Loading