sveld 0.32.3 → 0.32.5

package/lib/ComponentParser.d.ts

@@ -135,26 +135,6 @@ interface ComponentSlot {
     /** Source range for the slot/snippet declaration or documentation tag, when available */
     source?: SourceRange;
 }
-/**
- * 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.
- */
-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;
-    /** The detail type if explicitly specified in `@event` tag */
-    detail?: string;
-    /** Source range for the forwarded event declaration or documentation tag, when available */
-    source?: SourceRange;
-}
 /**
  * Event that is dispatched by the component.
  *
@@ -173,7 +153,40 @@ interface DispatchedEvent {
     /** Source range for the dispatched event call or documentation tag, when available */
     source?: SourceRange;
 }
-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.
+ *
+ * @example
+ * ```ts
+ * // ForwardedEvent with element object:
+ * { type: "forwarded", name: "click", element: { type: "Element", name: "button" } }
+ *
+ * // SerializedForwardedEvent for JSON:
+ * { type: "forwarded", name: "click", element: "button" }
+ * ```
+ */
+export interface SerializedForwardedEvent {
+    /** Always "forwarded" for forwarded events */
+    type: "forwarded";
+    /** The event name (e.g., "click", "change") */
+    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: string;
+    /** Description extracted from JSDoc `@event` tags */
+    description?: string;
+    /** The detail type if explicitly specified in `@event` tag */
+    detail?: string;
+    /** Source range for the forwarded event declaration or documentation tag, when available */
+    source?: SourceRange;
+}
+export type SerializedComponentEvent = SerializedForwardedEvent | DispatchedEvent;
 /**
  * Type definition extracted from JSDoc `@typedef` tags.
  *
@@ -306,8 +319,8 @@ export interface ParsedComponent {
     moduleExports: ComponentProp[];
     /** Slots available in the component template */
     slots: ComponentSlot[];
-    /** Events that the component can dispatch or forward */
-    events: ComponentEvent[];
+    /** Events that the component can dispatch or forward (serialized 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 */
@@ -350,6 +363,8 @@ export default class ComponentParser {
     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 */
@@ -440,7 +455,6 @@ export default class ComponentParser {
     private buildScopeDeclarations;
     private createRestPropsFromParent;
     private maybeSetRestProps;
-    private isCallExpressionNamed;
     private getPropertyName;
     private logUnsupportedRunesPattern;
     private logParserWarning;
@@ -506,23 +520,14 @@ export default class ComponentParser {
      * ```ts
      * // Input JSDoc:
      * /**
-     *  * @type {string}
-     *  * @param {number} x - The x coordinate
-     *  * @param {number} y - The y coordinate
-     *  * @returns {void}
-     *  * Description text
-     *  *\/
-     *
+     * * @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"
-     * }
+     * { 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;
@@ -597,6 +602,44 @@ export default class ComponentParser {
      * Returns the init node if found, or undefined.
      */
     private resolveLocalVarInitializer;
+    /**
+     * 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.
      */
@@ -794,11 +837,7 @@ export default class ComponentParser {
      * @example
      * ```ts
      * // Input:
-     * [
-     *   { name: "value", type: "string", description: "The new value" },
-     *   { name: "count", type: "number", optional: true, default: "0" }
-     * ]
-     *
+     * [ { 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; }"
      * ```

package/lib/ast-guards.d.ts

@@ -0,0 +1,12 @@
+import type { ArrowFunctionExpression, CallExpression, FunctionDeclaration, FunctionExpression, Identifier, Literal, MemberExpression, ObjectExpression, VariableDeclaration } from "estree";
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function isVariableDeclaration(node: unknown): node is VariableDeclaration;
+export declare function isLiteral(node: unknown): node is Literal;
+export declare function isIdentifier(node: unknown): node is Identifier;
+export declare function isMemberExpression(node: unknown): node is MemberExpression;
+export declare function isObjectExpression(node: unknown): node is ObjectExpression;
+export declare function isCallExpression(node: unknown): node is CallExpression;
+export declare function isCallExpressionNamed(node: unknown, calleeName: string): node is CallExpression;
+export declare function isFunctionDeclaration(node: unknown): node is FunctionDeclaration;
+export declare function isFunctionExpression(node: unknown): node is FunctionExpression;
+export declare function isArrowFunctionExpression(node: unknown): node is ArrowFunctionExpression;

package/lib/brands.d.ts

@@ -0,0 +1,11 @@
+declare const brand: unique symbol;
+export type Brand<TBase extends string, TBrand extends string> = TBase & {
+    readonly [brand]: TBrand;
+};
+export type SvelteEntryPoint = Brand<string, "SvelteEntryPoint">;
+export declare function asSvelteEntryPoint(path: string): SvelteEntryPoint;
+export type NormalizedPath = Brand<string, "NormalizedPath">;
+export declare function asNormalizedPath(path: string): NormalizedPath;
+export type RelativeSourcePath = Brand<string, "RelativeSourcePath">;
+export declare function asRelativeSourcePath(path: string): RelativeSourcePath;
+export {};

package/lib/cli.d.ts

@@ -1,10 +1,5 @@
 /**
- * Command-line interface for sveld.
- *
- * Parses command-line arguments, runs Rollup to process the entry point,
- * generates component documentation, and writes output files.
- *
- * @param process - Node.js process object containing command-line arguments
+ * CLI entry point: parse flags, run Rollup, generate docs, write outputs.
  *
  * @example
  * ```ts

package/lib/create-exports.d.ts

@@ -1,13 +1,6 @@
 import type { ParsedExports } from "./parse-exports";
 /**
- * Creates export statements from parsed export information.
- *
- * Groups exports by source file and generates optimized export statements.
- * Handles special cases like Svelte component exports, default exports,
- * and mixed exports from module context.
- *
- * @param parsed_exports - Map of export names to their source and metadata
- * @returns A string containing all export statements
+ * Builds export statements from parsed export metadata.
  *
  * @example
  * ```ts
@@ -20,10 +13,7 @@ import type { ParsedExports } from "./parse-exports";
  */
 export declare function createExports(parsed_exports: ParsedExports): string;
 /**
- * Removes the `.svelte` extension from a file path.
- *
- * @param filePath - The file path to process
- * @returns The path without the .svelte extension
+ * Strips the `.svelte` extension from a path.
  *
  * @example
  * ```ts
@@ -32,10 +22,7 @@ export declare function createExports(parsed_exports: ParsedExports): string;
  */
 export declare function removeSvelteExt(filePath: string): string;
 /**
- * Converts a `.svelte` file path to a `.svelte.d.ts` TypeScript definition path.
- *
- * @param filePath - The Svelte file path to convert
- * @returns The path with .svelte.d.ts extension
+ * Maps a `.svelte` path to its `.svelte.d.ts` definition path.
  *
  * @example
  * ```ts

package/lib/element-tag-map.d.ts

@@ -1,9 +1,5 @@
 /**
- * Element tag map adapted from TypeScript's `lib.dom.d.ts`.
- *
- * Maps HTML element tag names to their corresponding TypeScript element types.
- * Used for generating proper TypeScript types for element bindings and rest props.
- * See the TypeScript lib.dom.d.ts for the original source.
+ * Tag-to-DOM-type map from TypeScript `lib.dom.d.ts`. Unknown tags fall back to `HTMLElement`.
  *
  * @example
  * ```ts
@@ -135,14 +131,9 @@ declare const tag_map: {
     wbr: string;
 };
 type ElementTag = keyof typeof tag_map;
+export declare function isElementTag(element: string): element is ElementTag;
 /**
- * Gets the TypeScript element type for a given HTML tag name.
- *
- * Returns the specific element type (e.g., `HTMLButtonElement`) if the tag
- * is in the map, otherwise returns the generic `HTMLElement` type.
- *
- * @param element - The HTML tag name (e.g., "button", "div", "input")
- * @returns The corresponding TypeScript element type name
+ * Returns the DOM interface for a tag, or `HTMLElement` when unknown.
  *
  * @example
  * ```ts
@@ -151,5 +142,5 @@ type ElementTag = keyof typeof tag_map;
  * getElementByTag("custom")  // Returns: "HTMLElement" (fallback)
  * ```
  */
-export declare function getElementByTag(element: ElementTag | string): string;
+export declare function getElementByTag(element: string): string;
 export {};

package/lib/get-svelte-entry.d.ts

@@ -1,6 +1,4 @@
-export type SvelteEntryPoint = string;
-/**
- * Get the file path entry point for uncompiled Svelte source code
- * Expects a "svelte" field in the consumer's `package.json`
- */
-export declare function getSvelteEntry(entryPoint?: SvelteEntryPoint): SvelteEntryPoint | null;
+import { type SvelteEntryPoint } from "./brands";
+export type { SvelteEntryPoint };
+/** Resolve the Svelte entry from `entryPoint` or `package.json#svelte`. */
+export declare function getSvelteEntry(entryPoint?: string): SvelteEntryPoint | null;

package/lib/index.d.ts

@@ -1,4 +1,5 @@
-export { default as ComponentParser } from "./ComponentParser";
+export { default as ComponentParser, type SerializedComponentEvent } from "./ComponentParser";
 export { cli } from "./cli";
+export type { SvelteEntryPoint } from "./get-svelte-entry";
 export { default } from "./plugin";
 export { sveld } from "./sveld";