sveld 0.35.0 → 0.35.2

package/lib/ComponentParser.d.ts

@@ -1,8 +1,9 @@
 import type { Property } from "estree";
 import type { Node } from "estree-walker";
 import type { SveldDiagnostic } from "./diagnostics";
-/** Returns `value`, or `undefined` when it's `undefined` or the empty string. */
-export declare function assignValue(value?: "" | string): string | undefined;
+import { PARSED_COMPONENT_TYPE_SCRIPT_METADATA } from "./parsed-component-metadata";
+import { assignValueOrUndefined } from "./parser/utils";
+export { assignValueOrUndefined as assignValue };
 /** Structured JSDoc tag (e.g. `{ name: "since", body: "1.2.0" }`). */
 export interface JsDocPassthroughTag {
     name: string;
@@ -52,6 +53,16 @@ export type ModernRunesTypeNode = {
     typeName?: unknown;
     types?: ModernRunesTypeNode[];
     members?: ModernRunesTypeMember[];
+    /** Declaration-side `<T, U = Default>` (interfaces/type aliases). */
+    typeParameters?: {
+        params?: Array<{
+            name?: string;
+        }>;
+    };
+    /** Reference-side `<string, number>` concrete arguments (`TSTypeReference`). */
+    typeArguments?: {
+        params?: ModernRunesTypeNode[];
+    };
 };
 export type ModernRunesTypeMember = {
     type?: string;
@@ -82,11 +93,15 @@ export interface ParsedComponentTypeScriptMetadata {
     canonicalPropNames: string[];
     localTypeDeclarations: string[];
     typeImportStatements: string[];
+    /**
+     * Whether `canonicalPropsType` mentions one of the component's own
+     * `<script generics="...">` parameters (e.g. `Props<T>`). The semantic
+     * resolver has no binding for `T`, so `resolveTypes` must leave this
+     * component's props as their AST-derived text rather than expand them.
+     */
+    referencesComponentGenerics?: boolean;
 }
-export declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
-export declare function getParsedComponentTypeScriptMetadata(component: {
-    [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
-}): ParsedComponentTypeScriptMetadata | undefined;
+export { applyResolvedProps, getParsedComponentTypeScriptMetadata, PARSED_COMPONENT_TYPE_SCRIPT_METADATA, } from "./parsed-component-metadata";
 /** One prop returned by the TypeScript checker during `resolveTypes`. */
 export interface ResolvedComponentProp {
     name: string;
@@ -94,8 +109,6 @@ export interface ResolvedComponentProp {
     isRequired: boolean;
     description?: string;
 }
-/** Append checker-resolved props. Names the AST walker already found are left alone. */
-export declare function applyResolvedProps(component: ParsedComponent, resolved: ResolvedComponentProp[]): void;
 export type SyntaxMode = "legacy" | "runes";
 export type ScriptLanguage = "js" | "ts";
 export type ScopeBindingKind = "prop" | "local";
@@ -134,177 +147,172 @@ type ModernScriptAttribute = {
 export type ModernScriptNode = {
     attributes?: ModernScriptAttribute[];
 };
-/**
- * Diagnostic information for component parsing.
- *
- * Used to provide context about the component being parsed for error
- * messages and logging.
- */
 interface ComponentParserDiagnostics {
-    /** The module/component name (e.g., "Button", "App") */
     moduleName: string;
-    /** The file path to the component (e.g., "./Button.svelte") */
     filePath: string;
 }
 export type ComponentPropBinding = "readonly" | "writable";
-/**
- * Parameter information for function props.
- *
- * Extracted from JSDoc `@param` tags to provide detailed function signatures.
- */
+/** Function prop parameter from JSDoc `@param` tags. */
 export interface ComponentPropParam {
-    /** The parameter name */
+    /** Parameter name. */
     name: string;
-    /** The parameter type (e.g., "string", "number", "CustomType") */
+    /** Parameter type (e.g. `"string"`, `"CustomType"`). */
     type: string;
-    /** Optional description from JSDoc */
+    /** From JSDoc `@param`. */
     description?: string;
-    /** Whether the parameter is optional */
+    /** True when optional. */
     optional?: boolean;
 }
 /**
- * Component prop definition extracted from Svelte component.
+ * A parsed component prop: the shared internal IR that every prop front-end
+ * (legacy `<script context="module">` exports, legacy instance
+ * `export let`/`export function`, and runes `$props()` destructuring)
+ * produces via {@link resolvePropTypeAndDocs}, then hands to `addProp`. The
+ * three front-ends differ only in how they extract the raw signals (type
+ * text, JSDoc, initializer shape) from their respective AST shapes; the
+ * decisions below are shared and, outside the two documented mode
+ * differences, identical across modes.
  *
- * Represents a single prop that can be passed to the component, including
- * its type, default value, description, and metadata about whether it's
- * required, reactive, or a function.
+ * - `typeSource` precedence: an explicit TypeScript annotation always wins,
+ *   then JSDoc (`@type`/`@param`/`@returns`), then a type resolved from an
+ *   identifier default's own JSDoc, and only then a bare inferred/initializer
+ *   type. See {@link resolveTypeSource}.
+ * - JSDoc-vs-TS merge: `type`/`params`/`returnType`/`description` each
+ *   independently prefer their JSDoc-sourced value over the identifier
+ *   default's resolved value; an explicit TypeScript type additionally beats
+ *   JSDoc for `type` only.
+ * - Mode difference (preserved, not converged): legacy `export let`/
+ *   `export function` never infers `isFunction` from a function-shaped type
+ *   text; runes `$props()` does (`inferIsFunctionFromTypeSignature`).
+ * - Mode difference (preserved, not converged): legacy falls back to a
+ *   matching `@typedef`'s own description when the prop has none; runes does
+ *   not pass `typedefs` to {@link resolvePropTypeAndDocs} today.
  */
 export interface ComponentProp {
-    /** The prop name as declared in the component */
+    /** Public prop name. */
     name: string;
-    /** The declaration kind: "let" (required), "const" (optional with default), or "function" */
+    /** `"let"` (required), `"const"` (default), or `"function"`. */
     kind: "let" | "const" | "function";
-    /** Whether this prop is declared as `const` (has a default value) */
+    /** True when declared with `const`. */
     constant: boolean;
-    /** The TypeScript type of the prop (e.g., "string", "number | string") */
+    /** TypeScript type text. */
     type?: string;
-    /** Conservative provenance for the prop type */
+    /** Conservative provenance for the prop type. See the precedence rule on {@link ComponentProp}. */
     typeSource?: ComponentPropTypeSource;
-    /** Local variable name, emitted when it differs from the public prop name */
+    /** Local binding when it differs from the public name. */
     localName?: string;
-    /** The default value as a string representation of the source code */
+    /** Default value as source text; unset when the prop has no initializer/default. */
     value?: string;
-    /** Structured default value metadata for docs UIs */
+    /** Structured default value metadata for docs UIs; set alongside `value` from the same initializer. */
     defaultValue?: ComponentPropDefaultValue;
-    /** Description extracted from JSDoc comments */
+    /** From JSDoc, or a matching `@typedef`'s own description (legacy only; see {@link ComponentProp}). */
     description?: string;
-    /** Function parameters (for function props) extracted from `@param` tags */
+    /** From JSDoc `@param` on function props. */
     params?: ComponentPropParam[];
-    /** Return type (for function props) extracted from `@returns` tag */
+    /** From JSDoc `@returns` on function props. */
     returnType?: string;
-    /** Whether this prop is a function (arrow function or function expression) */
+    /**
+     * True for arrow/function-expression initializers and bare `function`
+     * declarations in every mode; additionally true for a function-shaped
+     * type/JSDoc signature in runes only (see {@link ComponentProp}).
+     */
     isFunction: boolean;
-    /** Whether this prop is a function declaration (not an expression) */
+    /** True for `function` declarations. */
     isFunctionDeclaration: boolean;
-    /** Whether this prop is required (no default value, declared with `let`) */
+    /** True when declared with `let` and no default. */
     isRequired: boolean;
-    /** Whether this prop is reactive (can change and trigger reactivity) */
+    /**
+     * True when the prop is mutated locally (legacy, inferred from assignment/
+     * binding targets) or declared with `$bindable()` (runes).
+     */
     reactive: boolean;
-    /** Explicit author-documented binding direction from `@bindable` JSDoc */
+    /** Binding direction from `@bindable` JSDoc. */
     binding?: ComponentPropBinding;
-    /** True when the prop is explicitly declared with Svelte 5 `$bindable()` */
+    /** True when declared with Svelte 5 `$bindable()` (runes only). */
     bindable?: true;
     /** From `@deprecated` JSDoc. */
     deprecated?: DeprecatedValue;
-    /** Structured `@since` / `@example` tags, in source order. */
+    /** `@since` / `@example` tags in source order. */
     tags?: JsDocPassthroughTag[];
-    /** Source range for the prop declaration, when available */
+    /** Source range when available. */
     source?: SourceRange;
 }
-/**
- * Component slot definition.
- *
- * Represents a slot that can be used to pass content into the component.
- * Includes information about slot props, fallback content, and descriptions.
- */
 export interface ComponentSlot {
-    /** The slot name (null or undefined for default slot) */
+    /** Slot name (`null` for the default slot). */
     name?: string | null;
-    /** Whether this is the default slot */
+    /** True for the default slot. */
     default: boolean;
-    /** Fallback content to display when slot is not provided */
+    /** Fallback content when the slot is empty. */
     fallback?: string;
-    /** TypeScript type definition for slot props (e.g., "{ title: string }") */
+    /** Slot props as TypeScript type text. */
     slot_props?: string;
-    /** Description extracted from JSDoc `@slot` or `@snippet` tags */
+    /** From JSDoc `@slot` or `@snippet`. */
     description?: string;
     /** From `@deprecated` JSDoc. */
     deprecated?: DeprecatedValue;
-    /**
-     * JSDoc tags that appeared after the prose description and before `@slot` / `@snippet`
-     * (e.g. `@example`), in source order.
-     */
+    /** Tags between the description and `@slot`/`@snippet` (e.g. `@example`), in source order. */
     tags?: JsDocPassthroughTag[];
-    /** Source range for the slot/snippet declaration or documentation tag, when available */
+    /** Source range when available. */
     source?: SourceRange;
 }
-/**
- * Slot prop value definition.
- *
- * Used internally to track slot prop types and whether they should be
- * replaced with prop type references.
- */
+/** Slot prop type text or a reference to resolve at finalize time. */
 export interface SlotPropValue {
-    /** The prop type value or reference */
+    /** Type text or reference. */
     value?: string;
-    /** Whether this value should be replaced with a prop type reference */
+    /** True to replace with a prop type reference. */
     replace: boolean;
 }
 export type SlotProps = Record<string, SlotPropValue>;
 /**
- * Event that is forwarded from a child component or element.
+ * Internal representation of {@link ComponentSlot} used while parsing.
  *
- * Forwarded events are those that use `on:eventname` syntax without
- * a handler, passing the event through to the parent.
+ * `slot_props` is either raw TS type text (from a JSDoc `@slot`/`@snippet` tag,
+ * used as-is) or a structured {@link SlotProps} map (from template parsing,
+ * formatted into TS type text once at the end of the parse). Keeping it
+ * structured until then avoids a JSON.stringify/JSON.parse round-trip per slot.
  */
+export type InternalComponentSlot = Omit<ComponentSlot, "slot_props"> & {
+    slot_props?: string | SlotProps;
+};
+/** Event forwarded with `on:eventname` and no handler. */
 export interface ForwardedEvent {
-    /** Always "forwarded" for forwarded events */
+    /** Discriminator: `"forwarded"`. */
     type: "forwarded";
-    /** The event name (e.g., "click", "change") */
+    /** Event name. */
     name: string;
-    /** The element or component that forwards this event */
+    /** Element or component that forwards the event. */
     element: ComponentInlineElement | ComponentElement;
-    /** Description extracted from JSDoc `@event` tags */
+    /** From JSDoc `@event`. */
     description?: string;
     /** From `@deprecated` JSDoc. */
     deprecated?: DeprecatedValue;
-    /** The detail type if explicitly specified in `@event` tag */
+    /** Detail type from `@event`. */
     detail?: string;
-    /** Structured `@since` / `@example` tags, in source order. */
+    /** `@since` / `@example` tags in source order. */
     tags?: JsDocPassthroughTag[];
-    /** Source range for the forwarded event declaration or documentation tag, when available */
+    /** Source range when available. */
     source?: SourceRange;
 }
-/**
- * Event that is dispatched by the component.
- *
- * Dispatched events are those created with `createEventDispatcher()` and
- * dispatched via `dispatch("eventname", detail)`, or dispatched from a custom
- * element via `$host().dispatchEvent(new CustomEvent("eventname", { detail }))`.
- */
+/** Event from `createEventDispatcher()`, `dispatch()`, or `$host().dispatchEvent()`. */
 export interface DispatchedEvent {
-    /** Always "dispatched" for dispatched events */
+    /** Discriminator: `"dispatched"`. */
     type: "dispatched";
-    /** The event name (e.g., "click", "change") */
+    /** Event name. */
     name: string;
-    /** The detail type (e.g., "{ value: string }", "null", "CustomEvent<...>") */
+    /** Detail type text. */
     detail?: string;
-    /** Description extracted from JSDoc `@event` tags */
+    /** From JSDoc `@event`. */
     description?: string;
     /** From `@deprecated` JSDoc. */
     deprecated?: DeprecatedValue;
-    /** Structured `@since` / `@example` tags, in source order. */
+    /** `@since` / `@example` tags in source order. */
     tags?: JsDocPassthroughTag[];
-    /** Source range for the dispatched event call or documentation tag, when available */
+    /** Source range when available. */
     source?: SourceRange;
 }
 export type ComponentEvent = ForwardedEvent | DispatchedEvent;
 /**
- * Serialized version of {@link ForwardedEvent} for JSON output.
- *
- * This interface maintains backward compatibility by serializing the `element`
- * property as a string instead of an object. The element name is extracted
- * from the {@link ComponentInlineElement} or {@link ComponentElement} object.
+ * Serialized {@link ForwardedEvent} for JSON output. `element` is a string, not an object.
  *
  * @example
  * ```ts
@@ -316,63 +324,47 @@ export type ComponentEvent = ForwardedEvent | DispatchedEvent;
  * ```
  */
 export interface SerializedForwardedEvent {
-    /** Always "forwarded" for forwarded events */
+    /** Discriminator: `"forwarded"`. */
     type: "forwarded";
-    /** The event name (e.g., "click", "change") */
+    /** Event name. */
     name: string;
-    /**
-     * Serialized as string for JSON backward compatibility.
-     * In the internal API, this is an object, but for JSON output it's a string.
-     */
+    /** Element name as a string for JSON output. */
     element: string;
-    /** Description extracted from JSDoc `@event` tags */
+    /** From JSDoc `@event`. */
     description?: string;
     /** From `@deprecated` JSDoc. */
     deprecated?: DeprecatedValue;
-    /** The detail type if explicitly specified in `@event` tag */
+    /** Detail type from `@event`. */
     detail?: string;
-    /** Structured `@since` / `@example` tags, in source order. */
+    /** `@since` / `@example` tags in source order. */
     tags?: JsDocPassthroughTag[];
-    /** Source range for the forwarded event declaration or documentation tag, when available */
+    /** Source range when available. */
     source?: SourceRange;
 }
 export type SerializedComponentEvent = SerializedForwardedEvent | DispatchedEvent;
-/**
- * Type definition extracted from JSDoc `@typedef` tags.
- *
- * Represents custom types defined in component comments that can be
- * referenced by props, events, and other type annotations.
- */
+/** JSDoc `@typedef` extracted as a named type. */
 export interface TypeDef {
-    /** The type string representation (e.g., "{ x: number; y: number }") */
+    /** Type text (e.g. `"{ x: number; y: number }"`). */
     type: string;
-    /** The type name (e.g., "Point", "User") */
+    /** Type name. */
     name: string;
-    /** Description extracted from JSDoc comments */
+    /** From JSDoc. */
     description?: string;
-    /** The full TypeScript type definition string (e.g., "type Point = { x: number; y: number }") */
+    /** Full `type` alias declaration text. */
     ts: string;
 }
 export type ComponentGenerics = [name: string, type: string] | null;
-/**
- * Represents an inline Svelte component element.
- *
- * Used to identify which component forwards an event or accepts rest props.
- */
 export interface ComponentInlineElement {
-    /** Always "InlineComponent" for component elements */
+    /** Discriminator: `"InlineComponent"`. */
     type: "InlineComponent";
-    /** The component name (e.g., "Button", "Modal") */
+    /** Component name. */
     name: string;
 }
 export interface ComponentElement {
     type: "Element";
     name: string;
     /**
-     * For `svelte:element`, stores the hardcoded element tag if `this` is a literal string.
-     *
-     * When `svelte:element` is used with a static tag (e.g., `svelte:element this="div"`),
-     * this property contains the tag name. If the tag is dynamic, this property is undefined.
+     * Static tag for `svelte:element this="div"`. Undefined when `this` is dynamic.
      *
      * @example
      * ```svelte
@@ -386,62 +378,43 @@ export interface ComponentElement {
      * ```
      */
     thisValue?: string;
-    /** Inline or block description from the `@restProps` JSDoc tag */
+    /** From `@restProps` JSDoc. */
     description?: string;
 }
 export type RestProps = undefined | ComponentInlineElement | ComponentElement;
-/**
- * Interface extension information from JSDoc `@extends` tag.
- *
- * Allows components to extend external TypeScript interfaces for
- * better type safety and code reuse.
- */
+/** JSDoc `@extends` target. */
 export interface Extends {
-    /** The interface name to extend (e.g., "ButtonProps") */
+    /** Interface name (e.g. `"ButtonProps"`). */
     interface: string;
-    /** The import path for the interface (e.g., "./types" or "carbon-components-svelte") */
+    /** Import path (e.g. `"./types"`). */
     import: string;
 }
 export interface ComponentPropBindings {
     elements: string[];
 }
-/**
- * Property definition for a component context.
- *
- * Represents a single property in a context object created with `setContext`.
- */
 export interface ComponentContextProp {
-    /** The property name */
+    /** Property name. */
     name: string;
-    /** The property type (inferred from JSDoc or variable types) */
+    /** Property type text. */
     type: string;
-    /** Description extracted from JSDoc comments on the variable */
+    /** From JSDoc. */
     description?: string;
-    /** Whether the property is optional */
+    /** True when optional. */
     optional: boolean;
 }
-/**
- * Component context definition.
- *
- * Represents a context created with `setContext(key, value)` that can be
- * accessed by child components via `getContext(key)`.
- */
+/** Context from `setContext(key, value)`. */
 export interface ComponentContext {
-    /** The context key (e.g., "modal", "tabs") */
+    /** Context key from `setContext`. */
     key: string;
-    /** The generated TypeScript type name (e.g., "ModalContext", "TabsContext") */
+    /** Generated type name (e.g. `"ModalContext"`). */
     typeName: string;
-    /** Description extracted from JSDoc comments */
+    /** From JSDoc. */
     description?: string;
-    /** Properties available in this context */
+    /** Context object properties. */
     properties: ComponentContextProp[];
 }
 /**
- * Complete parsed component metadata.
- *
- * This is the main return type from {@link ComponentParser.parseSvelteComponent}.
- * Contains all extracted information about a Svelte component including props,
- * slots, events, types, and more.
+ * Complete parsed component metadata from {@link ComponentParser.parseSvelteComponent}.
  *
  * @example
  * ```ts
@@ -451,51 +424,39 @@ export interface ComponentContext {
  *   filePath: "./Button.svelte"
  * });
  *
- * // Access component metadata:
- * parsed.props        // Array of component props
- * parsed.slots        // Array of component slots
- * parsed.events       // Array of component events
- * parsed.typedefs     // Array of custom type definitions
- * parsed.contexts     // Array of context definitions
+ * parsed.props;
+ * parsed.slots;
+ * parsed.events;
+ * parsed.typedefs;
+ * parsed.contexts;
  * ```
  */
 export interface ParsedComponent {
-    /** Source range for the component source that was parsed */
+    /** Source range of the parsed file. */
     source?: SourceRange;
-    /** Whether the component uses legacy or runes syntax according to compiler metadata */
     syntaxMode: SyntaxMode;
-    /** Language used by the instance or module script when it can be determined */
     scriptLanguage?: ScriptLanguage;
-    /** Component props that can be passed to the component */
+    /** Instance-level props (`export let`/`export function`, or runes `$props()`). See {@link ComponentProp} for the shared IR these are built from. */
     props: ComponentProp[];
-    /** Exports from `<script context="module">` block */
+    /** Exports from `<script context="module">`. Same {@link ComponentProp} shape as `props`, resolved through the same shared decisions. */
     moduleExports: ComponentProp[];
-    /** Slots available in the component template */
     slots: ComponentSlot[];
-    /** Events that the component can dispatch or forward (serialized for JSON/API output) */
+    /** Serialized events for JSON/API output. */
     events: SerializedComponentEvent[];
-    /** Custom type definitions from JSDoc `@typedef` tags */
     typedefs: TypeDef[];
-    /** Generic type parameters (e.g., `[name: "T", type: "string"]`) or null */
     generics: null | ComponentGenerics;
-    /** Rest props configuration (which elements/components accept rest props) */
     rest_props: RestProps;
-    /** Interface extension from JSDoc `@extends` tag */
     extends?: Extends;
-    /** Component-level description from `@component` HTML comment */
+    /** From `@component` HTML comment. */
     componentComment?: string;
-    /** Source range for the `@component` HTML comment, when available */
     componentCommentSource?: SourceRange;
-    /** Contexts created with `setContext` in the component */
     contexts?: ComponentContext[];
-    /** Custom-element tag name from `<svelte:options customElement="x-foo" />` (or the object form's `tag`), when present */
     customElementTag?: string;
     /**
      * Type guesses from this parse (unknown props, `any` contexts, orphan `@event` tags).
-     * Set on every {@link ComponentParser.parseSvelteComponent} call.
      */
     diagnostics?: SveldDiagnostic[];
-    /** Internal writer-only TypeScript metadata. Not serialized to JSON. */
+    /** Writer-only TypeScript metadata. Not serialized to JSON. */
     [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
 }
 export default class ComponentParser {
@@ -532,38 +493,7 @@ export default class ComponentParser {
     getPropTypeByLocalOrPublic(name: string): string | undefined;
     getExplicitPropType(name: string): string | undefined;
     getPropertyName(node: Property["key"]): string | undefined;
-    /**
-     * Checks if a MemberExpression represents a well-known numeric constant.
-     *
-     * Identifies constants from the Number and Math objects that should be
-     * typed as `number` rather than their literal values.
-     *
-     * @param memberExpr - The AST node to check
-     * @returns True if the expression is a recognized numeric constant
-     *
-     * @example
-     * ```ts
-     * // Recognized constants:
-     * Number.POSITIVE_INFINITY  // true
-     * Number.MAX_VALUE          // true
-     * Math.PI                   // true
-     * Math.E                    // true
-     *
-     * // Not recognized:
-     * Custom.CONSTANT           // false
-     * Number.UNKNOWN            // false
-     * ```
-     */
     isNumericConstant(memberExpr: unknown): boolean;
-    resolveTypeSource({ hasTypeScriptType, hasJSDocType, inferredType, finalType, }: {
-        hasTypeScriptType?: boolean;
-        hasJSDocType?: boolean;
-        inferredType?: string;
-        finalType?: string;
-    }): ComponentPropTypeSource;
-    /**
-     * Look up JSDoc on a local variable declaration by name.
-     */
     resolveLocalVarJSDoc(name: string): {
         type?: string;
         params?: ComponentPropParam[];
@@ -573,212 +503,49 @@ export default class ComponentParser {
         deprecated?: DeprecatedValue;
         tags?: JsDocPassthroughTag[];
     } | undefined;
-    /**
-     * Adds or merges a module export to the moduleExports map.
-     *
-     * Similar to {@link addProp}, but for exported values from the module script.
-     * If an export with the same name already exists, the new data is merged
-     * with the existing export.
-     *
-     * @param prop_name - The name of the exported value
-     * @param data - The export data to add or merge
-     *
-     * @example
-     * ```ts
-     * // For: export const API_URL = "https://api.example.com"
-     * addModuleExport("API_URL", {
-     *   name: "API_URL",
-     *   kind: "const",
-     *   type: "string",
-     *   value: '"https://api.example.com"'
-     * })
-     * ```
-     */
     private addModuleExport;
     /**
-     * Normalizes type strings by aliasing common patterns.
-     *
-     * Converts `*` to `any` (common JSDoc wildcard) and trims whitespace
-     * from type annotations.
-     *
-     * @param type - The type string to normalize
-     * @returns The normalized type string
-     *
      * @example
      * ```ts
-     * aliasType("*")        // Returns: "any"
-     * aliasType(" string ") // Returns: "string"
-     * aliasType("number")   // Returns: "number"
+     * aliasType("*"); // "any"
+     * aliasType(" string "); // "string"
      * ```
      */
     aliasType(type: string): string;
     /**
-     * Builds a cache of variable type information from JSDoc comments.
-     *
-     * Scans the source code for variable declarations and extracts type information
-     * from preceding JSDoc comments. This cache is used to infer types for context
-     * properties and other variable references.
-     *
-     * @example
-     * ```ts
-     * // Source code:
-     * /**
-     *  * @type {string}
-     *  * The user's name
-     *  *\/
-     * const userName = "John";
-     *
-     * // Cache entry:
-     * // { "userName": { type: "string", description: "The user's name" } }
-     * ```
-     */
-    private buildVariableInfoCache;
-    /**
-     * Cache for compiled regex patterns for variable name matching.
-     *
-     * Stores three regex patterns (const, let, function) per variable name
-     * to avoid recreating them on each lookup. Improves performance when
-     * searching for the same variable multiple times.
-     */
-    private static readonly VAR_NAME_REGEX_CACHE;
-    /**
-     * Gets or creates cached regex patterns for matching variable declarations.
-     *
-     * Creates three regex patterns for matching const, let, and function declarations
-     * of a specific variable name. The patterns are cached to avoid recreating them
-     * for the same variable name.
-     *
-     * @param varName - The variable name to create regex patterns for
-     * @returns A tuple of three RegExp objects for const, let, and function patterns
-     *
-     * @example
-     * ```ts
-     * getVarNameRegexes("count")
-     * // Returns:
-     * // [
-     * //   /\bconst\s+count\s*=/,
-     * //   /\blet\s+count\s*=/,
-     * //   /\bfunction\s+count\s*\(/
-     * // ]
-     * ```
-     */
-    private static getVarNameRegexes;
-    /**
-     * Finds the type and description for a variable by searching for its JSDoc comment.
-     *
-     * First checks the cache built by {@link buildVariableInfoCache}. If not found,
-     * searches the source code directly for the variable declaration and its
-     * preceding JSDoc comment.
-     *
-     * @param varName - The variable name to look up
-     * @returns The type and description if found, null otherwise
-     *
      * @example
      * ```ts
-     * // Source:
-     * /**
-     *  * @type {number}
-     *  * The count value
-     *  *\/
-     * const count = 0;
-     *
-     * findVariableTypeAndDescription("count")
-     * // Returns: { type: "number", description: "The count value" }
+     * // Given:
+     * // /**
+     * //  * @type {number}
+     * //  * The count value
+     * //  *\/
+     * // const count = 0;
+     *
+     * findVariableTypeAndDescription("count");
+     * // { type: "number", description: "The count value" }
      * ```
      */
     findVariableTypeAndDescription(varName: string): {
         type: string;
         description?: string;
     } | null;
+    accumulateGeneric(name: string, constraint: string): void;
     /**
-     * Cleans up all parser state, resetting the instance for reuse.
-     *
-     * Clears all maps, caches, and resets all state variables to their initial
-     * values. Should be called before parsing a new component or when the
-     * parser instance needs to be reset.
+     * Resets parser state for reuse between parses.
      *
      * @example
      * ```ts
      * parser.parseSvelteComponent(source1, diagnostics1);
-     * parser.cleanup(); // Reset state
-     * parser.parseSvelteComponent(source2, diagnostics2); // Fresh parse
+     * parser.cleanup();
+     * parser.parseSvelteComponent(source2, diagnostics2);
      * ```
      */
-    accumulateGeneric(name: string, constraint: string): void;
     cleanup(): void;
-    /**
-     * Pre-compiled regex for matching script blocks in Svelte components.
-     *
-     * Matches `<script>` tags and their content, capturing the opening tag,
-     * script content, and closing tag. Global and case-insensitive flags
-     * allow matching multiple script blocks.
-     *
-     * @example
-     * ```ts
-     * // Matches:
-     * // "<script>const x = 1;</script>"
-     * // "<script lang='ts'>...</script>"
-     * ```
-     */
     private static readonly SCRIPT_BLOCK_REGEX;
-    /**
-     * Pre-compiled regex for matching TypeScript directive comments.
-     *
-     * Matches TypeScript directive comments like ts-ignore, ts-expect-error,
-     * etc. Used to remove these directives from script blocks before JSDoc parsing.
-     *
-     * @example
-     * ```ts
-     * // Matches:
-     * // "// ts-ignore"
-     * // "// ts-expect-error: reason"
-     * // "// ts-nocheck"
-     * ```
-     */
     private static readonly TS_DIRECTIVE_REGEX;
-    /**
-     * Strips TypeScript directive comments from script blocks only.
-     *
-     * Removes TypeScript directive comments (e.g., ts-ignore, ts-expect-error directives)
-     * from within `<script>` blocks to prevent them from interfering with JSDoc parsing.
-     * Directives outside script blocks are left untouched.
-     *
-     * @param source - The Svelte component source code
-     * @returns The source code with TypeScript directives removed from script blocks
-     *
-     * @example
-     * ```ts
-     * // Input (with TypeScript directive):
-     * <script>
-     *   const x: string = 123; // directive removed
-     * </script>
-     *
-     * // Output (directive stripped):
-     * <script>
-     *   const x: string = 123;
-     * </script>
-     * ```
-     */
     private static stripTypeScriptDirectivesFromScripts;
     /**
-     * Parses a Svelte component and extracts all component metadata.
-     *
-     * This is the main entry point that orchestrates the entire parsing process:
-     * 1. Cleans up previous state
-     * 2. Strips TypeScript directives that might interfere with JSDoc
-     * 3. Compiles the component to get the AST
-     * 4. Collects reactive variables
-     * 5. Builds variable type cache
-     * 6. Parses custom types from JSDoc comments
-     * 7. Walks the AST to extract props, slots, events, bindings, and contexts
-     * 8. Post-processes events to distinguish dispatched vs forwarded
-     * 9. Processes props with bindings and slots with prop references
-     * 10. Returns the complete parsed component structure
-     *
-     * @param source - The Svelte component source code
-     * @param diagnostics - Diagnostic information (module name and file path)
-     * @returns A ParsedComponent object containing all extracted metadata
-     *
      * @example
      * ```ts
      * const parser = new ComponentParser();
@@ -786,9 +553,8 @@ export default class ComponentParser {
      *   moduleName: "Button",
      *   filePath: "./Button.svelte"
      * });
-     * // Returns: { props: [...], slots: [...], events: [...], ... }
+     * // { props, slots, events, typedefs, ... }
      * ```
      */
     parseSvelteComponent(source: string, diagnostics: ComponentParserDiagnostics): ParsedComponent;
 }
-export {};