sveld 0.34.1 → 0.35.1

package/lib/ComponentParser.d.ts

@@ -1,6 +1,10 @@
+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;
 /** Structured JSDoc tag (e.g. `{ name: "since", body: "1.2.0" }`). */
-interface JsDocPassthroughTag {
+export interface JsDocPassthroughTag {
     name: string;
     body: string;
 }
@@ -8,6 +12,11 @@ interface JsDocPassthroughTag {
  * From `@deprecated` JSDoc: a message string, or `true` when the tag has no message.
  */
 export type DeprecatedValue = string | true;
+export interface LegacyAstRoot {
+    module?: Node;
+    html?: Node;
+    instance?: Node;
+}
 export interface SourcePosition {
     /** 1-based source line number */
     line: number;
@@ -18,11 +27,78 @@ export interface SourceRange {
     start: SourcePosition;
     end: SourcePosition;
 }
+export interface RunesPropTypeMetadata {
+    optional: boolean;
+    source?: SourceRange;
+    type: string;
+}
+export interface RunesPropsDeclarationMetadata {
+    canonicalType?: string;
+    props: Map<string, RunesPropTypeMetadata>;
+    referencedImportedTypes: Set<string>;
+    referencedLocalTypes: Set<string>;
+}
+export type ModernRunesTypeNode = {
+    type?: string;
+    id?: {
+        name?: string;
+    };
+    start?: number;
+    end?: number;
+    body?: {
+        body?: ModernRunesTypeMember[];
+    };
+    typeAnnotation?: 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;
+    computed?: boolean;
+    optional?: boolean;
+    start?: number;
+    end?: number;
+    key?: Property["key"];
+    typeAnnotation?: {
+        start?: number;
+        end?: number;
+        typeAnnotation?: ModernRunesTypeNode;
+    };
+};
+export interface TypeImportBinding {
+    importedName?: string;
+    localName: string;
+    source: string;
+    specifierType: "default" | "named" | "namespace";
+}
+export interface LocalTypeDeclaration {
+    code: string;
+    node: ModernRunesTypeNode;
+    start: number;
+}
 export interface ParsedComponentTypeScriptMetadata {
     canonicalPropsType?: string;
     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: {
@@ -37,15 +113,44 @@ export interface ResolvedComponentProp {
 }
 /** Append checker-resolved props. Names the AST walker already found are left alone. */
 export declare function applyResolvedProps(component: ParsedComponent, resolved: ResolvedComponentProp[]): void;
-type SyntaxMode = "legacy" | "runes";
-type ScriptLanguage = "js" | "ts";
-type ComponentPropTypeSource = "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
-type ComponentPropDefaultValueKind = "literal" | "array" | "object" | "expression" | "function" | "unknown";
-interface ComponentPropDefaultValue {
+export type SyntaxMode = "legacy" | "runes";
+export type ScriptLanguage = "js" | "ts";
+export type ScopeBindingKind = "prop" | "local";
+export type ScopeBinding = {
+    kind: ScopeBindingKind;
+    publicPropName?: string;
+};
+export type LexicalScope = Map<string, ScopeBinding>;
+export type ComponentPropTypeSource = "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
+export type ComponentPropDefaultValueKind = "literal" | "array" | "object" | "expression" | "function" | "unknown";
+export interface ComponentPropDefaultValue {
     raw: string;
     kind: ComponentPropDefaultValueKind;
     value?: unknown;
 }
+export interface ProcessedInitializer {
+    value?: string;
+    type?: string;
+    isFunction: boolean;
+    defaultValue?: ComponentPropDefaultValue;
+    /** JSDoc from identifier default when the prop has none. */
+    resolvedType?: string;
+    resolvedDescription?: string;
+    resolvedParams?: ComponentPropParam[];
+    resolvedReturnType?: string;
+}
+type ModernScriptAttribute = {
+    name?: string;
+    value?: Array<{
+        data?: string;
+        raw?: string;
+    }> | boolean;
+    start?: number;
+    end?: number;
+};
+export type ModernScriptNode = {
+    attributes?: ModernScriptAttribute[];
+};
 /**
  * Diagnostic information for component parsing.
  *
@@ -58,20 +163,13 @@ interface ComponentParserDiagnostics {
     /** The file path to the component (e.g., "./Button.svelte") */
     filePath: string;
 }
-/**
- * Options for configuring the ComponentParser behavior.
- */
-interface ComponentParserOptions {
-    /** Enable verbose logging for debugging parsing issues */
-    verbose?: boolean;
-}
-type ComponentPropBinding = "readonly" | "writable";
+export type ComponentPropBinding = "readonly" | "writable";
 /**
  * Parameter information for function props.
  *
  * Extracted from JSDoc `@param` tags to provide detailed function signatures.
  */
-interface ComponentPropParam {
+export interface ComponentPropParam {
     /** The parameter name */
     name: string;
     /** The parameter type (e.g., "string", "number", "CustomType") */
@@ -157,13 +255,62 @@ export interface ComponentSlot {
     /** Source range for the slot/snippet declaration or documentation tag, 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.
+ */
+export interface SlotPropValue {
+    /** The prop type value or reference */
+    value?: string;
+    /** Whether this value should be replaced with a prop type reference */
+    replace: boolean;
+}
+export type SlotProps = Record<string, SlotPropValue>;
+/**
+ * Internal representation of {@link ComponentSlot} used while parsing.
+ *
+ * `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 that is forwarded from a child component or element.
+ *
+ * Forwarded events are those that use `on:eventname` syntax without
+ * a handler, passing the event through to the parent.
+ */
+export interface ForwardedEvent {
+    /** Always "forwarded" for forwarded events */
+    type: "forwarded";
+    /** The event name (e.g., "click", "change") */
+    name: string;
+    /** The element or component that forwards this event */
+    element: ComponentInlineElement | ComponentElement;
+    /** Description extracted from JSDoc `@event` tags */
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** The detail type if explicitly specified in `@event` tag */
+    detail?: string;
+    /** Structured `@since` / `@example` tags, in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** Source range for the forwarded event declaration or documentation tag, when available */
+    source?: SourceRange;
+}
 /**
  * Event that is dispatched by the component.
  *
- * Dispatched events are those created with `createEventDispatcher()`
- * and dispatched via `dispatch("eventname", detail)`.
+ * 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 }))`.
  */
-interface DispatchedEvent {
+export interface DispatchedEvent {
     /** Always "dispatched" for dispatched events */
     type: "dispatched";
     /** The event name (e.g., "click", "change") */
@@ -179,6 +326,7 @@ interface DispatchedEvent {
     /** Source range for the dispatched event call or documentation tag, when available */
     source?: SourceRange;
 }
+export type ComponentEvent = ForwardedEvent | DispatchedEvent;
 /**
  * Serialized version of {@link ForwardedEvent} for JSON output.
  *
@@ -223,7 +371,7 @@ export type SerializedComponentEvent = SerializedForwardedEvent | DispatchedEven
  * Represents custom types defined in component comments that can be
  * referenced by props, events, and other type annotations.
  */
-interface TypeDef {
+export interface TypeDef {
     /** The type string representation (e.g., "{ x: number; y: number }") */
     type: string;
     /** The type name (e.g., "Point", "User") */
@@ -233,19 +381,19 @@ interface TypeDef {
     /** The full TypeScript type definition string (e.g., "type Point = { x: number; y: number }") */
     ts: string;
 }
-type ComponentGenerics = [name: string, type: string] | null;
+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.
  */
-interface ComponentInlineElement {
+export interface ComponentInlineElement {
     /** Always "InlineComponent" for component elements */
     type: "InlineComponent";
     /** The component name (e.g., "Button", "Modal") */
     name: string;
 }
-interface ComponentElement {
+export interface ComponentElement {
     type: "Element";
     name: string;
     /**
@@ -269,25 +417,28 @@ interface ComponentElement {
     /** Inline or block description from the `@restProps` JSDoc tag */
     description?: string;
 }
-type RestProps = undefined | ComponentInlineElement | ComponentElement;
+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.
  */
-interface Extends {
+export interface Extends {
     /** The interface name to extend (e.g., "ButtonProps") */
     interface: string;
     /** The import path for the interface (e.g., "./types" or "carbon-components-svelte") */
     import: string;
 }
+export interface ComponentPropBindings {
+    elements: string[];
+}
 /**
  * Property definition for a component context.
  *
  * Represents a single property in a context object created with `setContext`.
  */
-interface ComponentContextProp {
+export interface ComponentContextProp {
     /** The property name */
     name: string;
     /** The property type (inferred from JSDoc or variable types) */
@@ -303,7 +454,7 @@ interface ComponentContextProp {
  * Represents a context created with `setContext(key, value)` that can be
  * accessed by child components via `getContext(key)`.
  */
-interface ComponentContext {
+export interface ComponentContext {
     /** The context key (e.g., "modal", "tabs") */
     key: string;
     /** The generated TypeScript type name (e.g., "ModalContext", "TabsContext") */
@@ -365,6 +516,8 @@ export interface ParsedComponent {
     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.
@@ -374,209 +527,39 @@ export interface ParsedComponent {
     [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
 }
 export default class ComponentParser {
-    /** Parser configuration options (e.g., verbose logging) */
-    private options?;
-    /** Whether the component uses legacy or runes syntax according to compiler metadata */
-    private syntaxMode;
-    /** Language used by the component's instance or module script, when supported */
-    private scriptLanguage?;
-    /** Raw source code of the Svelte component being parsed */
-    private source?;
-    /** Compiled Svelte code containing extracted variables and AST */
-    private compiled?;
-    /** Parsed abstract syntax tree from the Svelte compiler */
-    private parsed?;
-    /** Rest props configuration (e.g., `$$restProps`) if present in component */
-    private rest_props?;
-    /** Component extension information (e.g., `extends` attribute) */
-    private extends?;
-    /** Component-level description extracted from `@component` HTML comment */
-    private componentComment?;
-    /** Source range for the `@component` HTML comment, when available */
-    private componentCommentSource?;
-    /** Set of reactive variable names found in the component */
-    private readonly reactive_vars;
-    /** Set of all variable declarations found in the component script */
-    private readonly vars;
-    /** Function declarations in the component script, by name */
-    private readonly funcDecls;
-    /** Map of component props keyed by prop name */
-    private readonly props;
-    /** Map of module exports (functions/variables exported from script) keyed by name */
-    private readonly moduleExports;
-    /** Map of component slots keyed by slot name (null for default slot) */
-    private readonly slots;
-    /** Map of component events (dispatched events) keyed by event name */
-    private readonly events;
-    /** Map of event descriptions extracted from JSDoc comments keyed by event name */
-    private readonly eventDescriptions;
-    /** Map of forwarded events (events forwarded from child components) keyed by event name */
-    private readonly forwardedEvents;
-    /** Map of type definitions (typedefs) extracted from JSDoc comments keyed by type name */
-    private readonly typedefs;
-    /** Component generic type parameters (null if no generics) */
-    private generics;
-    /** @template tags in a @slot/@snippet block (no @extends), held until finalization. */
-    private deferredSlotBlockGenerics;
-    /** Map of prop bindings (e.g., `bind:value`) keyed by prop name */
-    private readonly bindings;
-    /** Map of component contexts (created with `setContext`) keyed by context name */
-    private readonly contexts;
-    /** Cache for variable type and description information to avoid redundant lookups */
-    private variableInfoCache;
-    /** Maps local binding names back to their public prop names */
-    private readonly propLocalToPublicName;
-    /** Tracks `$props()` bindings that are used as spread/rest props */
-    private readonly restPropLocals;
-    /** Tracks identifier bindings that capture the entire `$props()` object */
-    private readonly wholePropsLocals;
-    /** Tracks prop locals that are used as snippet/render props */
-    private readonly snippetPropLocals;
-    /** Per-declarator type metadata extracted from modern AST `$props()` annotations */
-    private readonly runesPropsDeclarationMetadataByDeclaratorStart;
-    /** Explicit TypeScript prop annotations for legacy `export let` declarations keyed by local name */
-    private readonly explicitPropTypesByName;
-    /** Type-only imports keyed by their local binding names */
-    private readonly typeImportBindingsByLocalName;
-    /** Local interface/type declarations keyed by type name */
-    private readonly localTypeDeclarationsByName;
-    /** Typed `$props()` declarations discovered in source order */
-    private readonly typedRunesPropsDeclarations;
-    /** Component-level lexical scope shared by instance script and template */
-    private readonly componentScope;
-    /** Precomputed lexical scopes for nested AST nodes */
-    private scopeDeclarations;
-    /** Active lexical scopes while walking the component AST */
-    private readonly activeScopes;
-    /** Diagnostics for the parse in progress. */
-    private readonly diagnosticRecords;
-    /** File path tagged onto each diagnostic. */
-    private componentFilePath;
-    /** `@event` names from JSDoc, checked against dispatches at end of parse. */
-    private readonly jsDocEventNames;
-    /** Cached array of source code lines split by newline for efficient line-based operations */
-    private sourceLinesCache?;
-    /** Cached 0-based source offsets for the start of each line */
-    private sourceLineStartOffsetsCache?;
-    constructor(options?: ComponentParserOptions);
+    /**
+     * All per-parse mutable state (props, slots, events, scopes, source, etc.).
+     * See {@link ParserContext} for field-by-field documentation. Replaced
+     * wholesale by `cleanup()` between parses.
+     */
+    private ctx;
     private static mapToArray;
     private static getStaticAttributeValue;
-    private static resolveScriptLanguage;
+    resolveScriptLanguage(parsed: {
+        instance?: ModernScriptNode;
+        module?: ModernScriptNode;
+    }): ScriptLanguage | undefined;
+    /**
+     * Reads the `generics` attribute off the instance script (Svelte only allows
+     * it there, and only alongside `lang="ts"`). Returns the raw value for later
+     * precedence resolution against `@generics`/`@template` JSDoc tags, or
+     * `undefined` if absent. Records a `syntax-skipped` diagnostic and returns
+     * `undefined` if the attribute is present without `lang="ts"`, since sveld
+     * can't safely guess how to parse it as plain JavaScript.
+     */
+    resolveScriptGenericsAttribute(parsed: {
+        instance?: ModernScriptNode;
+    }): {
+        value: string;
+        source?: SourceRange;
+    } | undefined;
     private static assignValue;
-    private recordDiagnostic;
     private resolvePublicPropName;
-    private trackPropLocalName;
+    trackPropLocalName(propName: string, localName?: string): void;
     private getPropByLocalOrPublic;
-    private getPropTypeByLocalOrPublic;
-    private getExplicitPropType;
-    private getRunesPropsDeclarationMetadata;
-    private getRunesPropTypeMetadata;
-    private getTypeReferenceName;
-    private getTypeDependencyName;
-    private getTypeAnnotationText;
-    private getSourceLineStartOffsets;
-    private sourcePositionFromOffset;
-    private sourceRangeFromOffsets;
-    private sourceRangeFromNode;
-    private sourceRangeFromCommentTag;
-    private collectReferencedTypeDependencies;
-    private buildTypeImportStatements;
-    private buildTypeScriptMetadata;
-    private buildRunesPropTypeMetadataMap;
-    private declareScopeBinding;
-    private resolveIdentifierToReactiveProp;
-    private collectPatternIdentifiers;
-    private markReactivePropsFromMutationTarget;
-    private isScopeOwner;
-    private isFunctionScopeOwner;
-    private getOrCreateScope;
-    private declareVariableDeclaration;
-    private declareFunctionLikeScopeBindings;
-    private collectDirectBlockDeclarations;
-    private extractRunesScopeBindings;
-    private collectComponentScopeDeclarations;
-    private collectNestedScopeDeclarations;
-    private buildScopeDeclarations;
-    private createRestPropsFromParent;
-    private maybeSetRestProps;
-    private getPropertyName;
-    private logUnsupportedRunesPattern;
-    private logParserWarning;
-    private static formatComment;
-    /**
-     * Extracts and categorizes JSDoc tags from a parsed comment.
-     *
-     * Separates tags into type, param, returns, and additional categories while
-     * excluding tags that are handled separately (extends, restProps, slot/snippet, event, typedef).
-     *
-     * @param parsed - The parsed comment result from comment-parser
-     * @returns An object containing categorized tags and the comment description
-     *
-     * @example
-     * ```ts
-     * // Input: Parsed comment with tags
-     * // Output:
-     * {
-     *   type: { tag: "type", type: "string" },
-     *   param: [
-     *     { tag: "param", name: "value", type: "string" }
-     *   ],
-     *   returns: { tag: "returns", type: "void" },
-     *   additional: [{ tag: "see", name: "OtherType" }],
-     *   passthrough: [{ tag: "since", name: "1.0.0" }],
-     *   description: "Main description text"
-     * }
-     * ```
-     */
-    private getCommentTags;
-    /**
-     * Finds the last comment from an array of leading comments.
-     *
-     * TypeScript directives are stripped before parsing, so we can safely take
-     * the last comment as it will be the JSDoc comment if present.
-     *
-     * @param leadingComments - Array of comment nodes from the AST
-     * @returns The last comment's value if found, undefined otherwise
-     *
-     * @example
-     * ```ts
-     * // Given leadingComments with multiple comments:
-     * // [/* regular comment *\/, /** JSDoc comment *\/]
-     * // Returns: { value: " JSDoc comment " }
-     *
-     * // If no comments:
-     * // Returns: undefined
-     * ```
-     */
-    private static findJSDocComment;
-    private findAdjacentJSDocComment;
-    private processNodeJSDoc;
-    private processLeadingCommentsJSDoc;
-    /**
-     * Processes JSDoc comments from leadingComments and extracts structured information.
-     *
-     * Parses JSDoc comments to extract type information, parameters, return types,
-     * and descriptions. Handles both inline and block-level descriptions.
-     *
-     * @param leadingComments - Array of comment nodes from the AST
-     * @returns Structured JSDoc information or undefined if no JSDoc comment is found
-     *
-     * @example
-     * ```ts
-     * // Input JSDoc:
-     * /**
-     * * @type {string}
-     * * @param {number} x - The x coordinate
-     * * @param {number} y - The y coordinate
-     * * @returns {void}
-     * * Description text
-     * *\/
-     * // Output:
-     * { type: "string", params: [ { name: "x", type: "number", description: "The x coordinate", optional: false }, { name: "y", type: "number", description: "The y coordinate", optional: false } ], returnType: "void", description: "Description text" }
-     * ```
-     */
-    private processJSDocComment;
-    private buildRunesPropTypeMetadata;
+    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.
      *
@@ -599,135 +582,25 @@ export default class ComponentParser {
      * Number.UNKNOWN            // false
      * ```
      */
-    private isNumericConstant;
-    /**
-     * Extracts source code at the given position range.
-     *
-     * @param start - Start position in the source
-     * @param end - End position in the source
-     * @returns The source code substring, or undefined if source is not available
-     */
-    private sourceAtPos;
-    private sourceForExpression;
-    private jsonSafeValueFromExpression;
-    private classifyDefaultValue;
-    private resolveTypeSource;
-    /**
-     * Processes an initializer expression to extract its value, type, and function status.
-     *
-     * Handles various expression types including object literals, arrays, binary expressions,
-     * arrow functions, unary expressions, identifiers, member expressions, template literals,
-     * and primitive literals. Extracts the source code representation and infers types
-     * where possible.
-     *
-     * @param init - The initializer AST node
-     * @returns An object containing the value (source code), inferred type, and whether it's a function
-     *
-     * @example
-     * ```ts
-     * // ObjectExpression: { x: 1, y: 2 }
-     * // Returns: { value: "{ x: 1, y: 2 }", type: "{ x: 1, y: 2 }", isFunction: false }
-     *
-     * // ArrowFunctionExpression: () => {}
-     * // Returns: { value: undefined, type: "(...args: any[]) => any", isFunction: true }
-     *
-     * // Literal: "hello"
-     * // Returns: { value: '"hello"', type: "string", isFunction: false }
-     *
-     * // BinaryExpression: "a" + "b"
-     * // Returns: { value: '"a" + "b"', type: "string", isFunction: false }
-     *
-     * // MemberExpression: Math.PI
-     * // Returns: { value: "Math.PI", type: "number" (if numeric constant), isFunction: false }
-     * ```
-     */
-    private processInitializer;
-    /**
-     * Look up a local variable's initializer AST node by name.
-     * Returns the init node if found, or undefined.
-     */
-    private resolveLocalVarInitializer;
-    /**
-     * Look up the initializer for a local `const` by name.
-     *
-     * {@link resolveLocalVarInitializer} also walks `let`/`var`. This method does not.
-     * Props and mutable bindings can change at runtime, so they cannot be context keys.
-     *
-     * @param name - The variable name to look up
-     * @returns The initializer node for a matching `const` binding, or undefined
-     */
-    private resolveConstInitializer;
+    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.
      */
-    private resolveLocalVarJSDoc;
-    /**
-     * Build a function type from `@param`/`@returns` when `@type` is missing.
-     * If JSDoc has no params or return either, try the function `node`, then
-     * `(...args: any[]) => any`.
-     */
-    private buildFunctionTypeFromParts;
-    /**
-     * Guess arity and return type for a function default with no JSDoc `@type`.
-     * Explicit `@type`/`@param`/`@returns` on the prop beat this every time.
-     * A default's body is a weak signal for the prop contract. We only read
-     * named params and literal returns. Everything else becomes `any`.
-     */
-    private inferFunctionTypeFromNode;
-    /**
-     * Turn params into `name: any`, or use `...args: any[]` when arity is unclear:
-     * no params, destructuring, rest, or defaults.
-     */
-    private inferParamsFromNode;
-    /**
-     * Infer return type from literal returns only. Every `return` must agree on
-     * the same primitive. Bare `return;`, no returns, identifiers, calls,
-     * objects, ternaries, async, or generators all become `any`.
-     */
-    private inferReturnTypeFromNode;
-    /**
-     * Walk a block body and collect each `return`'s argument, skipping nested
-     * functions. Bare `return;` becomes `null`.
-     */
-    private collectReturnArguments;
-    /**
-     * Map one return expression to `string`, `number`, or `boolean`, or `null`
-     * if it isn't a literal, template literal, or `String`/`Number`/`Boolean` call.
-     */
-    private inferReturnPrimitive;
-    /**
-     * Unwraps `$bindable(...)` calls so defaults are documented as their underlying values.
-     */
-    private unwrapBindableInitializer;
-    /**
-     * Extracts component props from top-level `$props()` declarations in runes components.
-     */
-    private parseRunesPropsDeclaration;
-    private inferSlotPropValueFromExpression;
-    private buildSlotPropsFromObjectExpression;
-    private resolveRenderTagPropReference;
-    private extractRenderTagInfo;
-    /**
-     * Adds or merges a component prop to the props map.
-     *
-     * If a prop with the same name already exists, the new data is merged
-     * with the existing prop, with new values taking precedence.
-     *
-     * @param prop_name - The name of the prop
-     * @param data - The prop data to add or merge
-     *
-     * @example
-     * ```ts
-     * // First call:
-     * addProp("count", { name: "count", type: "number", kind: "let" })
-     * // Props map: { "count" => { name: "count", type: "number", kind: "let" } }
-     *
-     * // Second call (merge):
-     * addProp("count", { description: "The count value" })
-     * // Props map: { "count" => { name: "count", type: "number", kind: "let", description: "The count value" } }
-     * ```
-     */
-    private addProp;
+    resolveLocalVarJSDoc(name: string): {
+        type?: string;
+        params?: ComponentPropParam[];
+        returnType?: string;
+        description?: string;
+        binding?: ComponentPropBinding;
+        deprecated?: DeprecatedValue;
+        tags?: JsDocPassthroughTag[];
+    } | undefined;
     /**
      * Adds or merges a module export to the moduleExports map.
      *
@@ -766,157 +639,7 @@ export default class ComponentParser {
      * aliasType("number")   // Returns: "number"
      * ```
      */
-    private aliasType;
-    /**
-     * Extracts a property's type from an object type string.
-     *
-     * Parses type strings like `{ value: string; other: number }` and returns
-     * the type for the requested property name. Handles nested braces, generics,
-     * and optional properties.
-     *
-     * @returns The property type string, or undefined if not found
-     */
-    private extractPropertyType;
-    /**
-     * Resolves the type of a MemberExpression (e.g., `obj.value`) by looking up
-     * the object's type annotation and extracting the property type.
-     *
-     * @returns The resolved type string, or undefined if it cannot be resolved
-     */
-    private resolveMemberExpressionType;
-    /**
-     * Adds or merges a slot definition to the slots map.
-     *
-     * Handles both named slots and the default slot. If a slot with the same
-     * name already exists, merges the data with existing values taking precedence
-     * where appropriate.
-     *
-     * @param slot_name - Optional slot name (undefined/empty = default slot)
-     * @param slot_props - Optional slot props type definition
-     * @param slot_fallback - Optional fallback content for the slot
-     * @param slot_description - Optional description for the slot
-     *
-     * @example
-     * ```ts
-     * // Default slot:
-     * addSlot({ slot_name: undefined, slot_props: "{ children: string }" })
-     *
-     * // Named slot:
-     * addSlot({
-     *   slot_name: "header",
-     *   slot_props: "{ title: string }",
-     *   slot_description: "Header slot with title prop"
-     * })
-     *
-     * // Slot with fallback:
-     * addSlot({
-     *   slot_name: "footer",
-     *   slot_fallback: "<p>Default footer</p>"
-     * })
-     * ```
-     */
-    private addSlot;
-    /**
-     * Adds or merges a dispatched event to the events map.
-     *
-     * Handles event detail type inference: if no argument is provided to the
-     * dispatcher and no `@event` tag specifies a detail type, the detail defaults
-     * to `null`. Otherwise, uses the provided detail type.
-     *
-     * @param name - The event name
-     * @param detail - The event detail type string
-     * @param has_argument - Whether the dispatcher call includes a detail argument
-     * @param description - Optional event description
-     *
-     * @example
-     * ```ts
-     * // Event without detail:
-     * // createEventDispatcher()("click")
-     * addDispatchedEvent({
-     *   name: "click",
-     *   detail: "",
-     *   has_argument: false,
-     *   description: "Fires on click"
-     * })
-     * // Result: { type: "dispatched", name: "click", detail: "null" }
-     *
-     * // Event with detail:
-     * // dispatch("change", { value: 42 })
-     * addDispatchedEvent({
-     *   name: "change",
-     *   detail: "{ value: number }",
-     *   has_argument: true,
-     *   description: "Fires when value changes"
-     * })
-     * // Result: { type: "dispatched", name: "change", detail: "{ value: number }" }
-     * ```
-     */
-    private addDispatchedEvent;
-    private normalizeRunesCallbackProps;
-    /**
-     * Parses custom types, events, slots, and other JSDoc annotations from component comments.
-     *
-     * Scans the entire source for JSDoc comment blocks and extracts structured information
-     * about events, typedefs, callbacks, slots, extends, restProps, and generics. Handles complex
-     * description extraction logic that supports both inline descriptions and preceding
-     * line descriptions.
-     *
-     * @example
-     * ```ts
-     * // Parses comments like:
-     * /**
-     *  * @event {CustomEvent} change - Fires when value changes
-     *  * @property {string} value - The new value
-     *  * @property {number} timestamp - When it changed
-     *  *\/
-     *
-     * // Or:
-     * /**
-     *  * Description for the event
-     *  * @event change
-     *  *\/
-     * ```
-     */
-    private parseCustomTypes;
-    /**
-     * Builds an event detail type string from an array of property definitions.
-     *
-     * Creates an inline object type with JSDoc comments for each property,
-     * including descriptions and default values. Used for both event details
-     * and typedef property definitions.
-     *
-     * @param properties - Array of property definitions with name, type, description, etc.
-     * @param _eventName - Optional event name (unused, kept for API consistency)
-     * @returns A string representation of the object type with JSDoc comments
-     *
-     * @example
-     * ```ts
-     * // Input:
-     * [ { name: "value", type: "string", description: "The new value" }, { name: "count", type: "number", optional: true, default: "0" } ]
-     * // Output:
-     * "{ /** The new value *\/ value: string; /** @default 0 *\/ count?: number; }"
-     * ```
-     */
-    private buildEventDetailFromProperties;
-    /**
-     * Generates a TypeScript type name for a context key.
-     *
-     * Converts kebab-case, snake_case, or space-separated keys into PascalCase
-     * with "Context" suffix. Splits on dashes, underscores, and spaces, then
-     * capitalizes each part.
-     *
-     * @param key - The context key (e.g., "simple-modal", "tabs_context", "My Context")
-     * @returns The generated type name (e.g., "SimpleModalContext", "TabsContext", "MyContextContext")
-     *
-     * @example
-     * ```ts
-     * generateContextTypeName("simple-modal")  // Returns: "SimpleModalContext"
-     * generateContextTypeName("Tabs")           // Returns: "TabsContext"
-     * generateContextTypeName("user_settings") // Returns: "UserSettingsContext"
-     * generateContextTypeName("my context")    // Returns: "MyContextContext"
-     * ```
-     */
-    private generateContextTypeName;
+    aliasType(type: string): string;
     /**
      * Builds a cache of variable type information from JSDoc comments.
      *
@@ -991,72 +714,10 @@ export default class ComponentParser {
      * // Returns: { type: "number", description: "The count value" }
      * ```
      */
-    private findVariableTypeAndDescription;
-    /**
-     * Parses a context value from an AST node to extract type information.
-     *
-     * Handles two cases:
-     * 1. ObjectExpression: Parses object literal properties and infers types from variable references
-     * 2. Identifier: Looks up the variable's type from JSDoc comments
-     *
-     * @param node - The AST node representing the context value
-     * @param key - The context key name
-     * @returns A ComponentContext object with parsed properties, or null if parsing fails
-     *
-     * @example
-     * ```ts
-     * // Case 1: Object literal
-     * // setContext('modal', { open, close })
-     * // Returns: { key: "modal", typeName: "ModalContext", properties: [...] }
-     *
-     * // Case 2: Variable reference
-     * // setContext('tabs', tabContext)
-     * // Returns: { key: "tabs", typeName: "TabsContext", properties: [...] }
-     * ```
-     */
-    private parseContextValue;
-    /**
-     * Resolve a `setContext` key to the string used in `{PascalCase}Context`.
-     *
-     * Accepts string literals, static template literals, `const`-bound identifiers
-     * (up to 5 indirection levels, same as `@default`), and `Symbol()` /
-     * `Symbol.for()`. Description-less symbols fall back to the binding name.
-     *
-     * @param keyArg - The first argument of the `setContext` call
-     * @param depth - Current identifier-resolution depth (internal recursion guard)
-     * @returns The resolved key string, or `null` when the key cannot be resolved at parse time
-     */
-    private resolveContextKey;
-    /**
-     * Extracts the description string from a `Symbol(...)` or `Symbol.for(...)` call
-     * used as a context key.
-     *
-     * @param node - A CallExpression or NewExpression AST node
-     * @returns The symbol description (`""` when the symbol has no static description),
-     *   or `null` when the node is not a `Symbol()` / `Symbol.for()` call
-     */
-    private resolveSymbolKeyDescription;
-    /**
-     * Parses a `setContext` call expression to extract context information.
-     *
-     * Reads the context key from the first argument and the value from the second.
-     * Unresolved keys log a warning and are skipped.
-     *
-     * @param node - The AST node (should be a CallExpression)
-     * @param _parent - The parent node (unused)
-     *
-     * @example
-     * ```ts
-     * // Parses: setContext('modal', { open, close })
-     * // Extracts: key = "modal", value = { open, close }
-     *
-     * // Parses: const KEY = "modal"; setContext(KEY, value) // resolves to "modal"
-     * // Parses: setContext(Symbol("modal"), value)          // resolves to "modal"
-     *
-     * // Diagnostic: setContext(dynamicKey, value) // key cannot be statically resolved
-     * ```
-     */
-    private parseSetContextCall;
+    findVariableTypeAndDescription(varName: string): {
+        type: string;
+        description?: string;
+    } | null;
     /**
      * Cleans up all parser state, resetting the instance for reuse.
      *
@@ -1071,7 +732,7 @@ export default class ComponentParser {
      * parser.parseSvelteComponent(source2, diagnostics2); // Fresh parse
      * ```
      */
-    private accumulateGeneric;
+    accumulateGeneric(name: string, constraint: string): void;
     cleanup(): void;
     /**
      * Pre-compiled regex for matching script blocks in Svelte components.