sveld 0.35.1 → 0.36.0

package/lib/browser.d.ts

@@ -1,39 +1,660 @@
-/**
- * Browser-safe entry point.
- *
- * Everything exported here avoids Node built-ins (`node:fs`, `node:path`, ...),
- * so it bundles for the browser (Vite, esbuild, webpack, Rollup) without a
- * polyfill. It covers parsing a single component's source and rendering that
- * result to JSON, Markdown, TypeScript definitions, or a Custom Elements
- * Manifest — everything except the filesystem-driven project scanning
- * (`sveld()`/`pluginSveld()`) and CLI, which only make sense in Node.
- *
- * @example
- * ```ts
- * import { asNormalizedPath, ComponentParser, buildComponentApiDocument } from "sveld/browser";
- *
- * const parser = new ComponentParser();
- * const diagnostics = { moduleName: "Button", filePath: "Button.svelte" };
- * const parsed = parser.parseSvelteComponent(source, diagnostics);
- *
- * // `parseSvelteComponent` returns component metadata only; add the fields
- * // `ComponentDocApi` needs (`moduleName`, `filePath`) yourself.
- * const component = {
- *   ...parsed,
- *   moduleName: diagnostics.moduleName,
- *   filePath: asNormalizedPath(diagnostics.filePath),
- * };
- *
- * const doc = buildComponentApiDocument(new Map([[component.moduleName, component]]));
- * ```
- */
-export { asNormalizedPath, type NormalizedPath } from "./brands";
-export { default as ComponentParser, type SerializedComponentEvent } from "./ComponentParser";
-export type { SveldDiagnostic, SveldDiagnosticKind } from "./diagnostics";
-export type { ComponentDocApi, ComponentDocs } from "./plugin";
-export { type BuildComponentApiDocumentOptions, buildComponentApiDocument, COMPONENT_API_SCHEMA_VERSION, type ComponentApiDocument, } from "./writer/document-model";
-export type { AppendType, MarkdownWriterBase, TocLine } from "./writer/MarkdownWriterBase";
-export { renderComponentsToMarkdown } from "./writer/markdown-render-utils";
-export { type BuildCustomElementsManifestOptions, buildCustomElementsManifest, type CemAttribute, type CemClassDeclaration, type CemClassField, type CemCustomElementExport, type CemEvent, type CemExport, type CemJavaScriptExport, type CemModule, type CemSlot, type CemType, type CustomElementsManifest, } from "./writer/writer-custom-elements-core";
-export { BrowserWriterMarkdown, type WriteMarkdownCoreOptions, writeMarkdownCore, } from "./writer/writer-markdown-core";
-export { formatTsProps, getContextDefs, getTypeDefs, type WriteTsDefinitionOptions, writeTsDefinition, } from "./writer/writer-ts-definitions-core";
+import type { Property } from "estree";
+
+import type { Node } from "estree-walker";
+
+declare const brand: unique symbol;
+
+type Brand<TBase extends string, TBrand extends string> = TBase & {
+    readonly [brand]: TBrand;
+};
+
+export type NormalizedPath = Brand<string, "NormalizedPath">;
+
+export declare function asNormalizedPath(path: string): NormalizedPath;
+
+interface JsDocPassthroughTag {
+    name: string;
+    body: string;
+}
+
+type DeprecatedValue = string | true;
+
+interface SourcePosition {
+    /** 1-based source line number */
+    line: number;
+    /** 0-based source column number */
+    column: number;
+}
+
+interface SourceRange {
+    start: SourcePosition;
+    end: SourcePosition;
+}
+
+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;
+}
+
+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 {
+    raw: string;
+    kind: ComponentPropDefaultValueKind;
+    value?: unknown;
+}
+
+type ModernScriptAttribute = {
+    name?: string;
+    value?: Array<{
+        data?: string;
+        raw?: string;
+    }> | boolean;
+    start?: number;
+    end?: number;
+};
+
+type ModernScriptNode = {
+    attributes?: ModernScriptAttribute[];
+};
+
+interface ComponentParserDiagnostics {
+    moduleName: string;
+    filePath: string;
+}
+
+type ComponentPropBinding = "readonly" | "writable";
+
+interface ComponentPropParam {
+    /** Parameter name. */
+    name: string;
+    /** Parameter type (e.g. `"string"`, `"CustomType"`). */
+    type: string;
+    /** From JSDoc `@param`. */
+    description?: string;
+    /** True when optional. */
+    optional?: boolean;
+}
+
+interface ComponentProp {
+    /** Public prop name. */
+    name: string;
+    /** `"let"` (required), `"const"` (default), or `"function"`. */
+    kind: "let" | "const" | "function";
+    /** True when declared with `const`. */
+    constant: boolean;
+    /** TypeScript type text. */
+    type?: string;
+    /** Conservative provenance for the prop type. See the precedence rule on {@link ComponentProp}. */
+    typeSource?: ComponentPropTypeSource;
+    /** Local binding when it differs from the public name. */
+    localName?: string;
+    /** Default value as source text; unset when the prop has no initializer/default. */
+    value?: string;
+    /** Structured default value metadata for docs UIs; set alongside `value` from the same initializer. */
+    defaultValue?: ComponentPropDefaultValue;
+    /** From JSDoc, or a matching `@typedef`'s own description (legacy only; see {@link ComponentProp}). */
+    description?: string;
+    /** From JSDoc `@param` on function props. */
+    params?: ComponentPropParam[];
+    /** From JSDoc `@returns` on function props. */
+    returnType?: string;
+    /**
+     * 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;
+    /** True for `function` declarations. */
+    isFunctionDeclaration: boolean;
+    /** True when declared with `let` and no default. */
+    isRequired: boolean;
+    /**
+     * True when the prop is mutated locally (legacy, inferred from assignment/
+     * binding targets) or declared with `$bindable()` (runes).
+     */
+    reactive: boolean;
+    /** Binding direction from `@bindable` JSDoc. */
+    binding?: ComponentPropBinding;
+    /** True when declared with Svelte 5 `$bindable()` (runes only). */
+    bindable?: true;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** `@since` / `@example` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+interface ComponentSlot {
+    /** Slot name (`null` for the default slot). */
+    name?: string | null;
+    /** True for the default slot. */
+    default: boolean;
+    /** Fallback content when the slot is empty. */
+    fallback?: string;
+    /** Slot props as TypeScript type text. */
+    slot_props?: string;
+    /** From JSDoc `@slot` or `@snippet`. */
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** Tags between the description and `@slot`/`@snippet` (e.g. `@example`), in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+interface DispatchedEvent {
+    /** Discriminator: `"dispatched"`. */
+    type: "dispatched";
+    /** Event name. */
+    name: string;
+    /** Detail type text. */
+    detail?: string;
+    /** From JSDoc `@event`. */
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** `@since` / `@example` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+interface SerializedForwardedEvent {
+    /** Discriminator: `"forwarded"`. */
+    type: "forwarded";
+    /** Event name. */
+    name: string;
+    /** Element name as a string for JSON output. */
+    element: string;
+    /** From JSDoc `@event`. */
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** Detail type from `@event`. */
+    detail?: string;
+    /** `@since` / `@example` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+export type SerializedComponentEvent = SerializedForwardedEvent | DispatchedEvent;
+
+interface TypeDef {
+    /** Type text (e.g. `"{ x: number; y: number }"`). */
+    type: string;
+    /** Type name. */
+    name: string;
+    /** From JSDoc. */
+    description?: string;
+    /** Full `type` alias declaration text. */
+    ts: string;
+}
+
+type ComponentGenerics = [name: string, type: string] | null;
+
+interface ComponentInlineElement {
+    /** Discriminator: `"InlineComponent"`. */
+    type: "InlineComponent";
+    /** Component name. */
+    name: string;
+}
+
+interface ComponentElement {
+    type: "Element";
+    name: string;
+    /**
+     * Static tag for `svelte:element this="div"`. Undefined when `this` is dynamic.
+     *
+     * @example
+     * ```svelte
+     * <!-- Static tag -->
+     * <svelte:element this="div" bind:this={elementRef} />
+     * // thisValue: "div"
+     *
+     * <!-- Dynamic tag -->
+     * <svelte:element this={tagName} bind:this={elementRef} />
+     * // thisValue: undefined
+     * ```
+     */
+    thisValue?: string;
+    /** From `@restProps` JSDoc. */
+    description?: string;
+}
+
+type RestProps = undefined | ComponentInlineElement | ComponentElement;
+
+interface Extends {
+    /** Interface name (e.g. `"ButtonProps"`). */
+    interface: string;
+    /** Import path (e.g. `"./types"`). */
+    import: string;
+}
+
+interface ComponentContextProp {
+    /** Property name. */
+    name: string;
+    /** Property type text. */
+    type: string;
+    /** From JSDoc. */
+    description?: string;
+    /** True when optional. */
+    optional: boolean;
+}
+
+interface ComponentContext {
+    /** Context key from `setContext`. */
+    key: string;
+    /** Generated type name (e.g. `"ModalContext"`). */
+    typeName: string;
+    /** From JSDoc. */
+    description?: string;
+    /** Context object properties. */
+    properties: ComponentContextProp[];
+}
+
+interface ParsedComponent {
+    /** Source range of the parsed file. */
+    source?: SourceRange;
+    syntaxMode: SyntaxMode;
+    scriptLanguage?: ScriptLanguage;
+    /** 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">`. Same {@link ComponentProp} shape as `props`, resolved through the same shared decisions. */
+    moduleExports: ComponentProp[];
+    slots: ComponentSlot[];
+    /** Serialized events for JSON/API output. */
+    events: SerializedComponentEvent[];
+    typedefs: TypeDef[];
+    generics: null | ComponentGenerics;
+    rest_props: RestProps;
+    extends?: Extends;
+    /** From `@component` HTML comment. */
+    componentComment?: string;
+    componentCommentSource?: SourceRange;
+    contexts?: ComponentContext[];
+    customElementTag?: string;
+    /**
+     * Type guesses from this parse (unknown props, `any` contexts, orphan `@event` tags).
+     */
+    diagnostics?: SveldDiagnostic[];
+    /** Writer-only TypeScript metadata. Not serialized to JSON. */
+    [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
+}
+
+export class ComponentParser {
+    /**
+     * 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;
+    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 resolvePublicPropName;
+    trackPropLocalName(propName: string, localName?: string): void;
+    private getPropByLocalOrPublic;
+    getPropTypeByLocalOrPublic(name: string): string | undefined;
+    getExplicitPropType(name: string): string | undefined;
+    getPropertyName(node: Property["key"]): string | undefined;
+    isNumericConstant(memberExpr: unknown): boolean;
+    resolveLocalVarJSDoc(name: string): {
+        type?: string;
+        params?: ComponentPropParam[];
+        returnType?: string;
+        description?: string;
+        binding?: ComponentPropBinding;
+        deprecated?: DeprecatedValue;
+        tags?: JsDocPassthroughTag[];
+    } | undefined;
+    private addModuleExport;
+    /**
+     * @example
+     * ```ts
+     * aliasType("*"); // "any"
+     * aliasType(" string "); // "string"
+     * ```
+     */
+    aliasType(type: string): string;
+    /**
+     * @example
+     * ```ts
+     * // 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;
+    /**
+     * Resets parser state for reuse between parses.
+     *
+     * @example
+     * ```ts
+     * parser.parseSvelteComponent(source1, diagnostics1);
+     * parser.cleanup();
+     * parser.parseSvelteComponent(source2, diagnostics2);
+     * ```
+     */
+    cleanup(): void;
+    private static readonly SCRIPT_BLOCK_REGEX;
+    private static readonly TS_DIRECTIVE_REGEX;
+    private static stripTypeScriptDirectivesFromScripts;
+    /**
+     * @example
+     * ```ts
+     * const parser = new ComponentParser();
+     * const result = parser.parseSvelteComponent(source, {
+     *   moduleName: "Button",
+     *   filePath: "./Button.svelte"
+     * });
+     * // { props, slots, events, typedefs, ... }
+     * ```
+     */
+    parseSvelteComponent(source: string, diagnostics: ComponentParserDiagnostics): ParsedComponent;
+}
+
+export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "event-no-source" | "example-compile-error" | "syntax-skipped";
+
+export interface SveldDiagnostic {
+    /** File this came from, e.g. `"./Button.svelte"`. */
+    component: string;
+    kind: SveldDiagnosticKind;
+    /** Prop, context field, or event name. */
+    name: string;
+    /** What went wrong and what type sveld used. */
+    message: string;
+    /** Where in the component source this diagnostic points, when the parser holds a stable position. */
+    source?: SourceRange;
+}
+
+declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
+
+export interface ComponentDocApi extends ParsedComponent {
+    filePath: NormalizedPath;
+    moduleName: string;
+}
+
+export type ComponentDocs = Map<string, ComponentDocApi>;
+
+interface EntryExport {
+    name: string;
+    kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
+    /** Type text from the source, when present. */
+    type?: string;
+    /** Initializer text for simple constants. */
+    value?: string;
+    description?: string;
+    /** Declaring module, relative to the entry file. */
+    source?: string;
+    isTypeOnly: boolean;
+}
+
+type EntryExports = EntryExport[];
+
+export interface CemType {
+    text: string;
+}
+
+export interface CemClassField {
+    kind: "field";
+    name: string;
+    type?: CemType;
+    default?: string;
+    description?: string;
+    deprecated?: DeprecatedValue;
+}
+
+export interface CemAttribute {
+    name: string;
+    fieldName: string;
+    type?: CemType;
+    default?: string;
+    description?: string;
+}
+
+export interface CemEvent {
+    name: string;
+    type: CemType;
+    description?: string;
+    deprecated?: DeprecatedValue;
+}
+
+export interface CemSlot {
+    name: string;
+    description?: string;
+    deprecated?: DeprecatedValue;
+}
+
+export interface CemClassDeclaration {
+    kind: "class";
+    name: string;
+    description?: string;
+    members: CemClassField[];
+    attributes: CemAttribute[];
+    events: CemEvent[];
+    slots: CemSlot[];
+    /** Only present when the source component sets `<svelte:options customElement="..." />`. */
+    tagName?: string;
+    /** Only present when the source component sets `<svelte:options customElement="..." />`. */
+    customElement?: true;
+}
+
+export interface CemJavaScriptExport {
+    kind: "js";
+    name: string;
+    declaration: {
+        name: string;
+        module: string;
+    };
+}
+
+export interface CemCustomElementExport {
+    kind: "custom-element-definition";
+    name: string;
+    declaration: {
+        name: string;
+        module: string;
+    };
+}
+
+export type CemExport = CemJavaScriptExport | CemCustomElementExport;
+
+export interface CemModule {
+    kind: "javascript-module";
+    path: string;
+    declarations: CemClassDeclaration[];
+    exports: CemExport[];
+}
+
+export interface CustomElementsManifest {
+    schemaVersion: "1.0.0";
+    modules: CemModule[];
+}
+
+export interface BuildCustomElementsManifestOptions {
+    /** Resolves each component's manifest `path`. Defaults to the component's `filePath` as-is. */
+    resolveModulePath?: (component: ComponentDocApi) => string;
+}
+
+export declare function buildCustomElementsManifest(components: ComponentDocs, options?: BuildCustomElementsManifestOptions): CustomElementsManifest;
+
+type OnAppend = (type: AppendType, document: WriterMarkdown) => void;
+
+interface MarkdownOptions {
+    onAppend?: OnAppend;
+}
+
+declare class WriterMarkdown extends Writer {
+    onAppend?: OnAppend;
+    private markdownBase;
+    constructor(options: MarkdownOptions);
+    get source(): string;
+    get hasToC(): boolean;
+    get toc(): TocLine[];
+    appendLineBreaks(): this;
+    append(type: AppendType, raw?: string): this;
+    tableOfContents(): this;
+    end(): string;
+}
+
+export type AppendType = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "quote" | "p" | "divider" | "raw";
+
+export interface TocLine {
+    /** Leading space count; 0 for the top-level (`h2`) entries the TOC currently lists. */
+    indent: number;
+    raw: string;
+}
+
+export interface MarkdownWriterBase {
+    sourceParts: string[];
+    hasToC: boolean;
+    toc: TocLine[];
+    appendLineBreaks(): this;
+    append(type: AppendType, raw?: string): this;
+    tableOfContents(): this;
+    end(): string;
+    get source(): string;
+}
+
+declare class MarkdownWriterBaseImpl implements MarkdownWriterBase {
+    sourceParts: string[];
+    hasToC: boolean;
+    toc: TocLine[];
+    get source(): string;
+    appendLineBreaks(): this;
+    append(type: AppendType, raw?: string): this;
+    tableOfContents(): this;
+    end(): string;
+}
+
+interface WriterOptions {
+    /** Report the resolved path to stdout instead of writing. Set by `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+declare class Writer {
+    private readonly dryRun;
+    constructor(options?: WriterOptions);
+    /**
+     * Skips the write when `filePath` already contains `raw`, so repeated runs
+     * over unchanged sources don't touch the file (or its mtime). In dry-run
+     * mode, prints `would write "<path>"` to stdout and touches nothing.
+     *
+     * @returns `true` if the file was written, `false` if it was already up to date.
+     *
+     * @example
+     * ```ts
+     * const writer = new Writer();
+     * await writer.write("./dist/index.d.ts", "export type Props = {};");
+     * ```
+     */
+    write(filePath: string, raw: string): Promise<boolean>;
+}
+
+export declare function formatTsProps(props?: string): string;
+
+export declare function getTypeDefs(def: Pick<ComponentDocApi, "typedefs">): string;
+
+export declare function getContextDefs(def: Pick<ComponentDocApi, "contexts" | "generics">): string;
+
+export interface WriteTsDefinitionOptions {
+    /**
+     * `"class"` (default) extends the deprecated `SvelteComponentTyped`.
+     * `"component"` emits `declare const X: Component<Props, Exports, Bindings>`
+     * instead, for Svelte 5+ consumers. Generic components get a per-component
+     * interface with a generic call signature instead of `Component<...>`
+     * directly, since a `declare const` can't itself carry a generic type
+     * parameter (see `genGenericComponentDeclaration`).
+     */
+    format?: "class" | "component";
+}
+
+export declare function writeTsDefinition(component: ComponentDocApi, options?: WriteTsDefinitionOptions): string;
+
+export declare const COMPONENT_API_SCHEMA_VERSION = 1;
+
+export interface ComponentApiDocument {
+    schemaVersion: 1;
+    generator: {
+        name: string;
+        version: string;
+        svelteVersion: string;
+    };
+    total: number;
+    components: ComponentDocApi[];
+    /** Only when `documentExports` is on. */
+    totalExports?: number;
+    exports?: EntryExports;
+}
+
+export interface BuildComponentApiDocumentOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+}
+
+export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;
+
+interface MarkdownDocument {
+    append(type: AppendType, raw?: string): MarkdownDocument;
+    tableOfContents(): MarkdownDocument;
+}
+
+export declare function renderComponentsToMarkdown(document: MarkdownDocument, components: ComponentDocs, entryExports?: EntryExports): void;
+
+export declare class BrowserWriterMarkdown extends MarkdownWriterBaseImpl {
+    onAppend?: OnAppend;
+    constructor(options: MarkdownOptions);
+    append(type: AppendType, raw?: string): this;
+}
+
+export interface WriteMarkdownCoreOptions {
+    onAppend?: (type: AppendType, document: BrowserWriterMarkdown, components: ComponentDocs) => void;
+}
+
+export declare function writeMarkdownCore(components: ComponentDocs, options?: WriteMarkdownCoreOptions): string;