svelte-docinfo 0.6.0 → 0.8.0

package/dist/source.js

@@ -1,12 +1,9 @@
 /**
- * Source file type predicates and path helpers.
- *
- * Pure functions for detecting file types by extension and extracting
- * component names from paths. No configuration dependency — these are
- * the building blocks used by `source-config.ts`.
+ * Source file shapes (`SourceFileInfo`, `AnalyzerType`), extension predicates,
+ * and svelte2tsx virtual-path and generated-name helpers. No configuration
+ * dependency; the building blocks under `source-config.ts`.
  *
  * @see `source-config.ts` for configuration-aware functions (`isSource`, `extractPath`, etc.)
- * @see `analyze.ts` for consumers (`analyze`, `analyzeFromFiles`)
  *
  * @module
  */
@@ -14,7 +11,7 @@
  * Default analyzer resolver based on file extension.
  *
  * - `.svelte` → `'svelte'`
- * - `.ts`, `.js` → `'typescript'`
+ * - `.ts` (not `.d.ts`), `.js` → `'typescript'`
  * - `.css` → `'css'`
  * - `.json` → `'json'`
  * - Other extensions → `null` (skip)

package/dist/svelte.d.ts

@@ -74,8 +74,9 @@ export interface TransformResult {
  *
  * Produces a `SvelteVirtualFile` containing the transformed TypeScript content
  * and source map. The virtual file can be included in a TypeScript program
- * (via `createAnalysisProgram({ virtualFiles })`) so that the checker can
- * resolve imported types, `<script module>` exports, and re-exports.
+ * (via `createAnalysisProgram({ virtualFiles })`, or the language service's
+ * `setFile` in sessions) so that the checker can resolve imported types,
+ * `<script module>` exports, and re-exports.
  *
  * Errors at ingest are returned via `diagnostics` rather than thrown:
  * - svelte2tsx throws → `transform_failed`, `virtual: undefined`
@@ -153,7 +154,7 @@ export declare const extractSvelteModuleComment: (scriptContent: string) => stri
  * assembling modules themselves through `analyzeModule` /
  * `analyzeSvelteModule`.
  *
- * @mutates diagnostics — rewrites `line`/`column` on virtual-file entries
+ * @mutates diagnostics - rewrites `line`/`column` on virtual-file entries
  */
 export declare const remapVirtualDiagnosticPositions: (diagnostics: Array<Diagnostic>, virtualFiles: Iterable<SvelteVirtualFile>) => void;
 /**
@@ -224,11 +225,27 @@ export declare const synthesizeSnippetTypeSignature: (parameters: Array<Paramete
  * Analyze a Svelte module using checker-backed analysis.
  *
  * Requires the svelte2tsx virtual output to be included in the TypeScript program
- * (via `createAnalysisProgram({ virtualFiles })`). Provides full type resolution for:
+ * (via `createAnalysisProgram({ virtualFiles })`, or the language service's
+ * `setFile` in sessions). Provides full type resolution for:
  * - Imported prop types (`let {x}: ImportedProps = $props()`)
  * - `<script module>` exports (constants, types, re-exports)
  * - Star exports and re-exports from Svelte files
  *
+ * Mirrors the numbered steps in the body:
+ *
+ * 1. `analyzeExports` on the virtual collects `<script module>` exports,
+ *    re-exports, and star exports
+ * 2. svelte2tsx internals are filtered (`isSvelte2tsxGeneratedExport`) and
+ *    exported snippets reclassified to `kind: 'snippet'` (`isSnippetReturnType`);
+ *    2b remaps module-level `sourceLine`s to the original `.svelte` source
+ * 3. the component declaration is synthesized: props via `extractPropsViaChecker`,
+ *    `acceptsChildren` from a `Snippet`-typed `children` prop or, failing that,
+ *    template use (`__sveltets_2_ensureSnippet`), plus generics, doc comment, and
+ *    source line from the landmarks `findComponentNodes` locates
+ * 4. the module comment is read from the original source
+ * 5. declarations combine, component first
+ * 6. dependencies are extracted
+ *
  * @param sourceFile - the original Svelte source file
  * @param modulePath - module path relative to source root; feeds
  *   `ModuleJson.path` and the component name, never `Diagnostic.file` (which

package/dist/svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte.ts"],"names":[],"mappings":"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"}

package/dist/svelte.js

@@ -34,15 +34,16 @@ import { getComponentName, isSvelte2tsxGeneratedExport, SVELTE_COMPONENT_ALIAS_S
 import { extractDependencies } from './source-config.js';
 import { compareStrings } from './postprocess.js';
 import {} from './diagnostics.js';
-import { to_error_message } from './error.js';
+import { toErrorMessage } from './error.js';
 import { toPosixPath } from './paths.js';
 /**
  * Pre-transform a Svelte source file via svelte2tsx.
  *
  * Produces a `SvelteVirtualFile` containing the transformed TypeScript content
  * and source map. The virtual file can be included in a TypeScript program
- * (via `createAnalysisProgram({ virtualFiles })`) so that the checker can
- * resolve imported types, `<script module>` exports, and re-exports.
+ * (via `createAnalysisProgram({ virtualFiles })`, or the language service's
+ * `setFile` in sessions) so that the checker can resolve imported types,
+ * `<script module>` exports, and re-exports.
  *
  * Errors at ingest are returned via `diagnostics` rather than thrown:
  * - svelte2tsx throws → `transform_failed`, `virtual: undefined`
@@ -85,7 +86,7 @@ export const transformSvelteSource = (sourceFile) => {
         diagnostics.push({
             kind: 'transform_failed',
             file: posixId,
-            message: `svelte2tsx failed to transform Svelte source: ${to_error_message(err)}`,
+            message: `svelte2tsx failed to transform Svelte source: ${toErrorMessage(err)}`,
             severity: 'error'
         });
         return { virtual: undefined, diagnostics };
@@ -99,7 +100,7 @@ export const transformSvelteSource = (sourceFile) => {
         diagnostics.push({
             kind: 'source_map_failed',
             file: posixId,
-            message: `Failed to parse svelte2tsx source map: ${to_error_message(err)}. Line/column positions for this file will reference virtual TypeScript output instead of the original Svelte source.`,
+            message: `Failed to parse svelte2tsx source map: ${toErrorMessage(err)}. Line/column positions for this file will reference virtual TypeScript output instead of the original Svelte source.`,
             severity: 'warning'
         });
     }
@@ -491,6 +492,9 @@ const extractComponentTsdoc = (nodes, sourceFile) => {
  * documented statement in a propless runes component or a legacy `export let`
  * component is some local's doc, not the component's). The HTML `@component`
  * comment is the authoring path for anchorless components.
+ *
+ * A JSDoc above the instance script's first import is missed: svelte2tsx
+ * hoists imports out of `$$render`, taking their leading comments with them.
  */
 const findInstanceTsdoc = (renderBody, sourceFile) => {
     const { statements } = renderBody;
@@ -521,6 +525,13 @@ const isPropsDeclaration = (statement) => ts.isVariableStatement(statement) &&
  * annotation (or the one svelte2tsx synthesizes for untyped `$props()`)
  * parses to an empty result and would otherwise claim the doc slot, masking
  * the HTML `@component` fallback.
+ *
+ * Two JS-component caveats: a description block written above a separate
+ * `/** @type {...} *\/` block never attaches (TypeScript binds only the last
+ * block — write docs in the HTML comment, or inside the `@type` block), and
+ * svelte2tsx consumes descriptions merged into an inline `@type {{...}}`
+ * literal when it rewrites it into a synthesized typedef (the HTML fallback
+ * still applies).
  */
 const findComponentTsdoc = (root, sourceFile) => {
     let foundTsdoc = undefined;
@@ -566,7 +577,7 @@ const findComponentTsdoc = (root, sourceFile) => {
  * assembling modules themselves through `analyzeModule` /
  * `analyzeSvelteModule`.
  *
- * @mutates diagnostics — rewrites `line`/`column` on virtual-file entries
+ * @mutates diagnostics - rewrites `line`/`column` on virtual-file entries
  */
 export const remapVirtualDiagnosticPositions = (diagnostics, virtualFiles) => {
     if (diagnostics.length === 0)
@@ -825,7 +836,7 @@ const detectChildrenSnippet = (propsType, propsTypeNode, ctx, componentName, dia
         ctx.diagnostics.push({
             kind: 'svelte_prop_failed',
             file: diagnosticFile,
-            message: `Failed to resolve type for "children" in ${componentName} while detecting acceptsChildren: ${to_error_message(err)}`,
+            message: `Failed to resolve type for "children" in ${componentName} while detecting acceptsChildren: ${toErrorMessage(err)}`,
             severity: 'warning',
             componentName,
             propName: 'children'
@@ -888,15 +899,18 @@ const extractPropsViaChecker = (virtualSource, ctx, componentName, diagnosticFil
     }
     const { type: propsType, node: propsTypeNode } = resolvedProps;
     // Detect `acceptsChildren` via type inference: `children` must resolve to a
-    // `Snippet<...>` type. Checking the symbol name alone (the previous approach)
-    // misreports a non-Snippet `children` (e.g. `children: string`) as accepting
-    // children. The lookup runs on the unfiltered props type so inherited
-    // `children` from `SvelteHTMLElements`/`DOMAttributes` (declared as `Snippet`)
-    // is honored even when its declaration lives in node_modules.
+    // `Snippet<...>` type. Checking the symbol name alone would misreport a
+    // non-Snippet `children` (e.g. `children: string`) as accepting children.
+    // The lookup runs on the unfiltered props type so inherited `children` from
+    // `SvelteHTMLElements`/`DOMAttributes` (declared as `Snippet`) is honored
+    // even when its declaration lives in node_modules.
     const acceptsChildren = detectChildrenSnippet(propsType, propsTypeNode, ctx, componentName, diagnosticFile);
     // Drop properties contributed by external types (node_modules / svelte's
     // element-attribute bags like `SvelteHTMLElements['li']`); those external
     // types are summarized in `externalTypes` rather than enumerated as props.
+    // No `hasExtractableProperties` gate here, unlike the type-alias path, so
+    // union prop types (`HTMLButtonAttributes | HTMLAnchorAttributes`) still get
+    // `externalTypes`.
     const { properties, externalTypes } = filterDocumentedProperties(propsType, propsTypeNode, checker, ctx.isExternalFile);
     // One pick rule for "which declaration represents this prop": the symbol's
     // declaration in the component's own file when one exists, else the usual
@@ -996,7 +1010,7 @@ const extractPropsViaChecker = (virtualSource, ctx, componentName, diagnosticFil
                 file: diagnosticFile,
                 line: finalLine,
                 column: finalColumn,
-                message: `Failed to resolve type for prop "${prop.name}" in ${componentName}, falling back to 'any': ${to_error_message(err)}`,
+                message: `Failed to resolve type for prop "${prop.name}" in ${componentName}, falling back to 'any': ${toErrorMessage(err)}`,
                 severity: 'warning',
                 componentName,
                 propName: prop.name
@@ -1010,11 +1024,27 @@ const extractPropsViaChecker = (virtualSource, ctx, componentName, diagnosticFil
  * Analyze a Svelte module using checker-backed analysis.
  *
  * Requires the svelte2tsx virtual output to be included in the TypeScript program
- * (via `createAnalysisProgram({ virtualFiles })`). Provides full type resolution for:
+ * (via `createAnalysisProgram({ virtualFiles })`, or the language service's
+ * `setFile` in sessions). Provides full type resolution for:
  * - Imported prop types (`let {x}: ImportedProps = $props()`)
  * - `<script module>` exports (constants, types, re-exports)
  * - Star exports and re-exports from Svelte files
  *
+ * Mirrors the numbered steps in the body:
+ *
+ * 1. `analyzeExports` on the virtual collects `<script module>` exports,
+ *    re-exports, and star exports
+ * 2. svelte2tsx internals are filtered (`isSvelte2tsxGeneratedExport`) and
+ *    exported snippets reclassified to `kind: 'snippet'` (`isSnippetReturnType`);
+ *    2b remaps module-level `sourceLine`s to the original `.svelte` source
+ * 3. the component declaration is synthesized: props via `extractPropsViaChecker`,
+ *    `acceptsChildren` from a `Snippet`-typed `children` prop or, failing that,
+ *    template use (`__sveltets_2_ensureSnippet`), plus generics, doc comment, and
+ *    source line from the landmarks `findComponentNodes` locates
+ * 4. the module comment is read from the original source
+ * 5. declarations combine, component first
+ * 6. dependencies are extracted
+ *
  * @param sourceFile - the original Svelte source file
  * @param modulePath - module path relative to source root; feeds
  *   `ModuleJson.path` and the component name, never `Diagnostic.file` (which
@@ -1275,7 +1305,10 @@ export const analyzeSvelteModule = (sourceFile, modulePath, checker, options, di
             severity: 'warning'
         });
     }
-    // 5. Combine: component declaration first (primary export), then <script module> exports
+    // 5. Combine: component declaration first (primary export), then <script module> exports;
+    // `@nodocs` is read from whichever doc source won (in-script JSDoc over the
+    // HTML `@component` comment), so an HTML `@nodocs` is ignored when in-script
+    // JSDoc supplies the doc
     const allDeclarations = [
         { declaration: componentDecl, nodocs: componentTsdoc?.tsdoc.nodocs === true },
         ...moduleDeclarations

package/dist/tsdoc.d.ts

@@ -22,25 +22,23 @@
  *
  * `@internal` is a marker, not an exclusion: it means "not stable public API"
  * and lands as `internalMessage` (with any trailing prose; empty string for a
- * bare tag) while the declaration stays documented. Use `@nodocs` to exclude
- * a declaration from output entirely.
- *
- * The `@nodocs` tag excludes exports from documentation and flat namespace validation.
- * The declaration is still exported and usable, just not documented.
+ * bare tag) while the declaration stays documented. `@nodocs` excludes a
+ * declaration from documentation and flat-namespace validation — it's still
+ * exported and usable, just not documented.
  *
  * Also supports `@mutates` (non-standard) for documenting mutations to parameters or external state.
- * Uses same format as `@param`: `@mutates key - description of mutation`. The key is
- * unvalidated — typically a parameter name, but compound paths (`this.foo`, `obj.field`)
- * and external state references are accepted as-is.
+ * Format: `@mutates target - description of mutation` — the target is everything before the
+ * first ` - ` separator. It is unvalidated: typically a parameter name, but compound paths
+ * (`this.foo`, `obj.field`) and multi-word external references are accepted; backticks are
+ * stripped from the target so `` `a` `` and `a` are one key. Without a separator the first
+ * line is a bare target (empty description) and any continuation lines are the description.
  *
  * The `@see` tag supports multiple formats: plain URLs (`https://...`), `{@link}` syntax, and module names.
  * Relative/absolute path support in `@see` is TBD.
  *
  * ## Behavioral notes
  *
- * JSDoc blocks tagged `@module` are excluded from `parseComment` entirely (text
- * and tags) — module comments attach to the file's first statement in the AST
- * and are owned by `extractModuleComment` instead.
+ * `@module` blocks are excluded from `parseComment` (see there).
  *
  * `JSDocPropertyLikeTag` nodes (`@property`/`@param` declaring a symbol in a
  * typedef or callback) parse to their own tag description — the only doc such
@@ -48,7 +46,8 @@
  *
  * Due to TS Compiler API limitations:
  * - TS API includes dash separator in `@param` tag text; we strip the leading `- ` as it's syntax, not content
- * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
+ * - `@throws` braced types (`{TypeError}`) parse into the tag's typeExpression, not its text —
+ *   the type is read from there; unbraced text falls back to a first-word-as-type regex
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *
  * @see `declaration-build.ts` for `DeclarationJsonBuild`
@@ -93,7 +92,11 @@ export interface TsdocParsedComment {
     since?: string;
     /** Default value from `@default` (or its `@defaultValue`/`@defaultvalue` spellings). */
     defaultValue?: string;
-    /** Mutation documentation from `@mutates` (non-standard), mapped by parameter name. */
+    /**
+     * Mutation documentation from `@mutates` (non-standard), mapped by target —
+     * typically a parameter name, possibly a compound path (`this.foo`) or a
+     * multi-word external reference. Empty string for a bare tag with no description.
+     */
     mutates?: Record<string, string>;
     /** Whether to exclude from documentation. From `@nodocs` tag. */
     nodocs?: boolean;

package/dist/tsdoc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,YAAY,GACxB,MAAM,EAAE,CAAC,IAAI,EACb,aAAY,EAAE,CAAC,UAAiC,KAC9C,kBAAkB,GAAG,SA8HvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,2BAA2B,kBAAkB,KAAG,OAGrB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,GAC9B,aAAa,oBAAoB,GAAG,eAAe,EACnD,OAAO,kBAAkB,GAAG,SAAS,EACrC,WAAU,OAAe,KACvB,IAwCF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,KAAG,MAAM,GAAG,SAW3D,CAAC"}
+{"version":3,"file":"tsdoc.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEpF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AA+DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,YAAY,GACxB,MAAM,EAAE,CAAC,IAAI,EACb,aAAY,EAAE,CAAC,UAAiC,KAC9C,kBAAkB,GAAG,SAqIvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,2BAA2B,kBAAkB,KAAG,OAGrB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB,GAC9B,aAAa,oBAAoB,GAAG,eAAe,EACnD,OAAO,kBAAkB,GAAG,SAAS,EACrC,WAAU,OAAe,KACvB,IAwCF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,KAAG,MAAM,GAAG,SAW3D,CAAC"}

package/dist/tsdoc.js

@@ -22,25 +22,23 @@
  *
  * `@internal` is a marker, not an exclusion: it means "not stable public API"
  * and lands as `internalMessage` (with any trailing prose; empty string for a
- * bare tag) while the declaration stays documented. Use `@nodocs` to exclude
- * a declaration from output entirely.
- *
- * The `@nodocs` tag excludes exports from documentation and flat namespace validation.
- * The declaration is still exported and usable, just not documented.
+ * bare tag) while the declaration stays documented. `@nodocs` excludes a
+ * declaration from documentation and flat-namespace validation — it's still
+ * exported and usable, just not documented.
  *
  * Also supports `@mutates` (non-standard) for documenting mutations to parameters or external state.
- * Uses same format as `@param`: `@mutates key - description of mutation`. The key is
- * unvalidated — typically a parameter name, but compound paths (`this.foo`, `obj.field`)
- * and external state references are accepted as-is.
+ * Format: `@mutates target - description of mutation` — the target is everything before the
+ * first ` - ` separator. It is unvalidated: typically a parameter name, but compound paths
+ * (`this.foo`, `obj.field`) and multi-word external references are accepted; backticks are
+ * stripped from the target so `` `a` `` and `a` are one key. Without a separator the first
+ * line is a bare target (empty description) and any continuation lines are the description.
  *
  * The `@see` tag supports multiple formats: plain URLs (`https://...`), `{@link}` syntax, and module names.
  * Relative/absolute path support in `@see` is TBD.
  *
  * ## Behavioral notes
  *
- * JSDoc blocks tagged `@module` are excluded from `parseComment` entirely (text
- * and tags) — module comments attach to the file's first statement in the AST
- * and are owned by `extractModuleComment` instead.
+ * `@module` blocks are excluded from `parseComment` (see there).
  *
  * `JSDocPropertyLikeTag` nodes (`@property`/`@param` declaring a symbol in a
  * typedef or callback) parse to their own tag description — the only doc such
@@ -48,7 +46,8 @@
  *
  * Due to TS Compiler API limitations:
  * - TS API includes dash separator in `@param` tag text; we strip the leading `- ` as it's syntax, not content
- * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
+ * - `@throws` braced types (`{TypeError}`) parse into the tag's typeExpression, not its text —
+ *   the type is read from there; unbraced text falls back to a first-word-as-type regex
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *
  * @see `declaration-build.ts` for `DeclarationJsonBuild`
@@ -66,6 +65,37 @@ import ts from 'typescript';
  * @returns cleaned text with leading `- ` removed if present
  */
 const cleanTagDescription = (text) => text.trim().replace(/^-\s+/, '');
+/**
+ * Parse an `@mutates` tag's text into target and description.
+ *
+ * The target is everything before the first ` - ` separator — a parameter
+ * name, a compound path (`this.foo`, `obj.field`), or a multi-word external
+ * reference — with backticks stripped so `` `a` `` and `a` normalize to one
+ * key (matching `params` keys) and renderers apply their own code styling.
+ * Without a separator the first line is a bare target (empty description)
+ * and any continuation lines are the description.
+ *
+ * @returns target and description, or undefined when no target remains after stripping
+ */
+const parseMutatesTag = (text) => {
+    const cleaned = text.trim();
+    const match = /^(.+?)\s+-\s+([\s\S]+)$/.exec(cleaned);
+    let rawTarget;
+    let description;
+    if (match) {
+        rawTarget = match[1];
+        // the regex consumed the separator, so a leading `- ` here is
+        // content (a markdown list bullet) — trim only, no strip
+        description = match[2].trim();
+    }
+    else {
+        const newlineIndex = cleaned.indexOf('\n');
+        rawTarget = newlineIndex === -1 ? cleaned : cleaned.slice(0, newlineIndex);
+        description = newlineIndex === -1 ? '' : cleaned.slice(newlineIndex + 1).trim();
+    }
+    const target = rawTarget.replaceAll('`', '').trim();
+    return target ? { target, description } : undefined;
+};
 /**
  * Whether a JSDoc block is a module-level comment (carries a `@module` tag).
  */
@@ -149,19 +179,21 @@ export const parseComment = (node, sourceFile = node.getSourceFile()) => {
     let defaultValue;
     let mutates;
     let nodocs;
-    // Extract main comment text
+    // Extract main comment text. `getTextOfJSDocComment` keeps inline `{@link}`
+    // tags — a link node carries its target in `name`, not `text`, so a manual
+    // `.map((c) => c.text)` join would silently drop it.
     for (const comment of tsdocComments) {
         if (ts.isJSDoc(comment) && comment.comment) {
-            const text = typeof comment.comment === 'string'
-                ? comment.comment
-                : comment.comment.map((c) => c.text).join('');
-            fullText += text + '\n';
+            const text = ts.getTextOfJSDocComment(comment.comment);
+            if (text) {
+                fullText += text + '\n';
+            }
         }
     }
     // Extract tags (module-block tags filtered like their text above)
     const tags = ts.getJSDocTags(node).filter((tag) => !belongsToModuleBlock(tag));
     for (const tag of tags) {
-        const tagText = typeof tag.comment === 'string' ? tag.comment : tag.comment?.map((c) => c.text).join('');
+        const tagText = ts.getTextOfJSDocComment(tag.comment);
         const tagName = tag.tagName.text;
         if (tagName === 'param' && ts.isJSDocParameterTag(tag)) {
             // Extract parameter name and description
@@ -173,14 +205,26 @@ export const parseComment = (node, sourceFile = node.getSourceFile()) => {
         else if ((tagName === 'returns' || tagName === 'return') && tagText) {
             returns = tagText.trim();
         }
-        else if (tagName === 'throws' && tagText) {
-            // Try to extract error type and description
-            const match = /^\{?(\w+)\}?\s+(.+)/.exec(tagText);
-            if (match) {
-                (throws ??= []).push({ type: match[1], description: cleanTagDescription(match[2]) });
+        else if (tagName === 'throws') {
+            // The standard braced form (`@throws {TypeError} - description`) parses
+            // its type into the tag's typeExpression — the comment text carries only
+            // the description (or nothing at all, for a bare `@throws {TypeError}`)
+            const typeNode = ts.isJSDocThrowsTag(tag) ? tag.typeExpression?.type : undefined;
+            if (typeNode) {
+                (throws ??= []).push({
+                    type: typeNode.getText(sourceFile),
+                    description: tagText ? cleanTagDescription(tagText) : ''
+                });
             }
-            else {
-                (throws ??= []).push({ description: cleanTagDescription(tagText) });
+            else if (tagText) {
+                // Unbraced text: heuristically extract a leading word as the error type
+                const match = /^\{?(\w+)\}?\s+([\s\S]+)/.exec(tagText);
+                if (match) {
+                    (throws ??= []).push({ type: match[1], description: cleanTagDescription(match[2]) });
+                }
+                else {
+                    (throws ??= []).push({ description: cleanTagDescription(tagText) });
+                }
             }
         }
         else if (tagName === 'example' && tagText) {
@@ -213,16 +257,12 @@ export const parseComment = (node, sourceFile = node.getSourceFile()) => {
             defaultValue = tagText.trim();
         }
         else if (tagName === 'mutates' && tagText) {
-            // Extract parameter name and description (format: @mutates paramName - description)
-            const cleanedText = cleanTagDescription(tagText);
-            const match = /^(\w+)\s+-?\s*(.+)/.exec(cleanedText);
-            if (match) {
-                const paramName = match[1];
-                const description = match[2].trim();
-                // Null-prototype map: `paramName` comes from source (`\w+` matches
-                // `__proto__`, `constructor`, …); a plain object would let such a key
-                // pollute the prototype on write and read back later by key.
-                (mutates ??= Object.create(null))[paramName] = description;
+            const parsed = parseMutatesTag(tagText);
+            if (parsed) {
+                // Null-prototype map: the target comes from source (it can be
+                // `__proto__`, `constructor`, …); a plain object would let such a
+                // key pollute the prototype on write and read back later by key.
+                (mutates ??= Object.create(null))[parsed.target] = parsed.description;
             }
         }
         else if (tagName === 'nodocs') {