sveld 0.37.8 → 0.38.0

package/lib/index.d.ts

@@ -1,3 +1,962 @@
-/// <reference types="node" />
+import type { Property } from "estree";
 
-export declare function parse(source: string): unknown;
+import type { Dirent } from "node:fs";
+
+import { type Program } from "acorn";
+
+interface ComponentParserDiagnostics {
+    moduleName: string;
+    filePath: string;
+}
+
+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;
+    /**
+     * Resets parser state for reuse between parses.
+     *
+     * @example
+     * ```ts
+     * parser.parseSvelteComponent(source1, diagnostics1);
+     * parser.cleanup();
+     * parser.parseSvelteComponent(source2, diagnostics2);
+     * ```
+     */
+    cleanup(): void;
+    /**
+     * @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;
+    /**
+     * Like {@link parseSvelteComponent}, but returns the candidates only a
+     * pass with file access can resolve beside the component rather than
+     * inside its metadata.
+     */
+    parse(source: string, diagnostics: ComponentParserDiagnostics): ComponentParseResult;
+}
+
+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 PendingCallDefaultCandidate {
+    propName: string;
+    location: "props" | "moduleExports";
+    calleeName: string;
+    importSource?: string;
+    importedName?: string;
+}
+
+interface PendingConstDefaultCandidate {
+    propName: string;
+    location: "props" | "moduleExports";
+    importSource: string;
+    importedName: string;
+    /** Members read off the import, through namespace exports: `["DELAY"]` for `C.timing.DELAY`. */
+    members?: string[];
+}
+
+interface PendingContextKeyCandidate {
+    importSource: string;
+    importedName: string;
+    /** Members read off the import, through namespace exports: `["THEME"]` for `ns.keys.THEME`. */
+    members?: string[];
+    /** See {@link ComponentContext.type}. */
+    type?: string;
+    properties: ComponentContextProp[];
+    description?: string;
+    /** See {@link ComponentContext.hasUnresolvedSpread}. */
+    hasUnresolvedSpread?: boolean;
+    /** See {@link ComponentContext.internal}. */
+    internal?: boolean;
+    /** Source range of the `setContext(...)` call, when available. */
+    source?: SourceRange;
+}
+
+interface PendingDispatchEscapeCandidate {
+    importSource: string;
+    importedName: string;
+    /** Members read off the import, through namespace exports: `["helper"]` for `ns.helper`. */
+    members?: string[];
+    /** Callee as written, for messages. */
+    calleeText: string;
+    /** Local name of the `createEventDispatcher()` result. */
+    dispatcherName: string;
+    /** Argument position the dispatcher is passed at. */
+    argumentIndex: number;
+    /** Set when passed as an object literal property (`{ dispatch }`): that property's key. */
+    property?: string;
+    /** Source range of the call, when available. */
+    source?: SourceRange;
+    /** `@sveld-ignore sveld/dispatch-escapes` on the dispatcher's declaration. */
+    ignored?: boolean;
+}
+
+interface PendingCrossFileCandidates {
+    /** Unresolved CallExpression defaults. */
+    pendingCallDefaultCandidates?: PendingCallDefaultCandidate[];
+    /** Imported-identifier defaults. */
+    pendingConstDefaultCandidates?: PendingConstDefaultCandidate[];
+    /** Unresolved `setContext` import keys. */
+    pendingContextKeyCandidates?: PendingContextKeyCandidate[];
+    /** Dispatchers passed to imported functions. */
+    pendingDispatchEscapeCandidates?: PendingDispatchEscapeCandidate[];
+    /**
+     * `event-no-source` diagnostics held back while the dispatcher escapes to
+     * imported functions: the cross-file pass keeps those the functions don't dispatch.
+     */
+    deferredEventNoSourceDiagnostics?: SveldDiagnostic[];
+    /**
+     * `@event` tags with no `{type}` or `@property`, whose `null` detail no
+     * same-file dispatch replaced; an escaped dispatcher's helper may still.
+     */
+    untypedJsDocEventNames?: string[];
+}
+
+interface ParsedComponentTypeScriptMetadata extends PendingCrossFileCandidates {
+    canonicalPropsType?: string;
+    canonicalPropNames: string[];
+    localTypeDeclarations: string[];
+    /** Types the module script exports (`export interface Item`), emitted with `export`. */
+    moduleTypeDeclarations?: string[];
+    typeImportStatements: string[];
+}
+
+interface ComponentParseResult {
+    component: ParsedComponent;
+    /** Undefined when the component depends on no other file's contents. */
+    pending?: PendingCrossFileCandidates;
+}
+
+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 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 ComponentPropReExport {
+    /** Module specifier as written in the source (e.g. `"./utils.js"`). */
+    from: string;
+    /** Name `from` exports: `"default"` for a default import, `"*"` for `export *` or a namespace import. */
+    imported: string;
+}
+
+interface ComponentClassMember {
+    /** `"property"` covers fields, constructor parameter properties, and getter/setter pairs. */
+    kind: "constructor" | "method" | "property";
+    /** Member name; `"constructor"` for the constructor. */
+    name: string;
+    /** Property type text; `"any"` when neither TypeScript nor JSDoc types it. */
+    type?: string;
+    /** Method or constructor parameters, typed from TypeScript or JSDoc `@param`, else `"any"`. A rest parameter's name starts with `...`. */
+    params?: ComponentPropParam[];
+    /** Method return type from TypeScript or JSDoc `@returns`; unset when neither gives one. */
+    returnType?: string;
+    /** A method's own type parameter list (`U extends object`), without the angle brackets. */
+    typeParameters?: string;
+    static?: true;
+    /** A `readonly` field, or a getter with no setter. */
+    readonly?: true;
+    optional?: true;
+    abstract?: true;
+    description?: string;
+    deprecated?: DeprecatedValue;
+    tags?: JsDocPassthroughTag[];
+}
+
+interface ComponentProp {
+    /** Public prop name; `"*"` for a bare `export * from "..."`. */
+    name: string;
+    /**
+     * `"let"` (required), `"const"` (default), or `"function"`. `"re-export"`
+     * is module-export only: `export { x } from "..."`, `export * from "..."`,
+     * or `export { x }` of an imported binding, written to the `.d.ts` as-is.
+     * `"class"` is module-export only too: a class the module script declares,
+     * with its public surface in {@link ComponentProp.members}.
+     */
+    kind: "let" | "const" | "function" | "re-export" | "class";
+    /** 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;
+    /**
+     * A function's own type parameter list from its `@template` tags (e.g.
+     * `T extends { id: string }`), without the angle brackets. Also prefixed
+     * onto `type` when that signature is built from `@param`/`@returns`.
+     * For a `"class"`, the class's type parameters, from TypeScript or `@template`.
+     */
+    typeParameters?: string;
+    /** Set when `kind` is `"class"`: its public constructor, methods, and properties, in source order. */
+    members?: ComponentClassMember[];
+    /** Set when `kind` is `"class"` and the class is `abstract`. */
+    abstract?: true;
+    /** Set when `kind` is `"class"` and it extends a base class: `Base<T>`. */
+    extends?: string;
+    /** Set when `kind` is `"class"` and it implements interfaces: `["Disposable"]`. */
+    implements?: 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[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Set when `kind` is `"re-export"`. */
+    reExport?: ComponentPropReExport;
+    /** 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[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** 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[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** 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[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** 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;
+    /** Tags in the same block (e.g. `@since`, `@example`, `@see`), in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Source range of the `@typedef`/`@callback` tag, when available. */
+    source?: SourceRange;
+}
+
+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;
+}
+
+type CustomElementPropType = "String" | "Boolean" | "Number" | "Array" | "Object";
+
+interface CustomElementPropConfig {
+    /** Explicit attribute name. Svelte itself always observes every prop as an attribute; sveld's own output omits the attribute entirely when this is `false`. */
+    attribute?: string | false;
+    reflect?: boolean;
+    type?: CustomElementPropType;
+}
+
+interface CustomElementOptions {
+    tag?: string;
+    shadow?: "open" | "none";
+    props?: Record<string, CustomElementPropConfig>;
+    extend?: true;
+}
+
+interface ComponentCssPart {
+    name: string;
+    description?: string;
+}
+
+interface ComponentCssProperty {
+    /** Includes the leading `--`. */
+    name: string;
+    type?: string;
+    default?: string;
+    description?: string;
+}
+
+interface ComponentContextProp {
+    /** Property name. */
+    name: string;
+    /** Property type text. */
+    type: string;
+    /** From JSDoc. */
+    description?: string;
+    /** True when optional. */
+    optional: boolean;
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+}
+
+interface ComponentContext {
+    /** Context key from `setContext`. */
+    key: string;
+    /** Generated type name (e.g. `"ModalContext"`). */
+    typeName: string;
+    /**
+     * The context's whole type, when the `setContext` value is a variable whose
+     * type isn't an object type literal (`ModalAPI`, `Writable<number>`, or `any`
+     * when untyped). `properties` is empty then.
+     */
+    type?: string;
+    /** From JSDoc. */
+    description?: string;
+    /** Context object properties. Empty when {@link ComponentContext.type} is set. */
+    properties: ComponentContextProp[];
+    /** True when a `{...spread}` in the context's object literal couldn't be resolved; the generated type intersects with `Record<string, any>`. */
+    hasUnresolvedSpread?: boolean;
+    /** True from `@ignore`/`@internal` JSDoc on the `setContext` call; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Source range of the `setContext(...)` call, when available. */
+    source?: SourceRange;
+}
+
+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;
+    /** Full `<svelte:options customElement=... />` config (shorthand or object form), when present. */
+    customElement?: CustomElementOptions;
+    /** From component-level `@csspart` JSDoc tags. */
+    cssParts?: ComponentCssPart[];
+    /** From component-level `@cssprop`/`@cssproperty` JSDoc tags. */
+    cssProperties?: ComponentCssProperty[];
+    /**
+     * 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 type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "dispatch-escapes" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "type-syntax-error" | "rest-props-unresolved" | "context-duplicate-key" | "context-key-unresolved" | "context-value-unresolved" | "spread-unresolved" | "export-unresolved" | "module-export-conflict" | "extend-props-target-missing" | "extend-props-duplicate" | "extend-props-override" | "jsdoc-unknown-tag" | "typedef-duplicate" | "property-duplicate" | "generics-conflict" | "event-description-ambiguous" | "jsdoc-tag-dropped" | "internal-typedef-referenced" | "cross-file-unresolved" | "export-ambiguous";
+
+export type SveldDiagnosticSeverity = "error" | "warning";
+
+export declare const DIAGNOSTIC_CODES: Record<SveldDiagnosticKind, string>;
+
+export interface SveldDiagnostic {
+    /**
+     * File this came from, e.g. `"./Button.svelte"`, or the entry barrel
+     * (`"./index.js"`) for `export-ambiguous`.
+     */
+    component: string;
+    kind: SveldDiagnosticKind;
+    /** Stable, namespaced identifier for `kind` (e.g. `"sveld/prop-unknown-type"`). */
+    code: string;
+    severity: SveldDiagnosticSeverity;
+    /** 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;
+    /**
+     * True when suppressed by an inline `@sveld-ignore` tag or a `diagnostics.ignore`
+     * config matcher. Still present here (and counted in the summary) but never
+     * fails `--strict` / `--strict=errors`.
+     */
+    ignored?: boolean;
+}
+
+export interface DiagnosticIgnoreMatcher {
+    code?: string;
+    component?: string;
+    name?: string;
+}
+
+export declare const DIAGNOSTICS_SCHEMA_VERSION = 1;
+
+export interface DiagnosticsJson {
+    kind: "diagnostics";
+    schemaVersion: typeof DIAGNOSTICS_SCHEMA_VERSION;
+    diagnostics: SveldDiagnostic[];
+}
+
+declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
+
+export type SemverBump = "major" | "minor" | "patch" | "none";
+
+export interface ApiChange {
+    /** Component `moduleName` this change belongs to, or `"*"` for document-wide notices. */
+    component: string;
+    kind: "component" | "prop" | "moduleExport" | "event" | "slot" | "shape" | "schema";
+    /** Prop, event, slot, or shape-field name, when applicable. */
+    name?: string;
+    bump: SemverBump;
+    message: string;
+}
+
+export interface CheckResult {
+    /** `false` when there was nothing on disk to diff against (e.g. first run). */
+    snapshotExists: boolean;
+    snapshotFile: string;
+    changes: ApiChange[];
+    /** Highest bump across all changes. */
+    bump: SemverBump;
+}
+
+export declare function diffApiDocuments(previous: ComponentApiDocument, next: ComponentApiDocument): ApiChange[];
+
+interface RunCheckOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+}
+
+export declare function runCheck(components: ComponentDocs, snapshotFile: string, options?: RunCheckOptions): Promise<CheckResult>;
+
+export declare function formatCheckReport(result: CheckResult): string;
+
+export declare const CHECK_REPORT_SCHEMA_VERSION = 1;
+
+export type CheckReportJson = CheckResult & {
+    kind: "check-report";
+    schemaVersion: typeof CHECK_REPORT_SCHEMA_VERSION;
+};
+
+export declare function formatCheckReportJson(result: CheckResult): string;
+
+interface ComponentDocApi extends ParsedComponent {
+    filePath: NormalizedPath;
+    moduleName: string;
+}
+
+type ComponentDocs = Map<string, ComponentDocApi>;
+
+interface ComponentParseError {
+    filePath: string;
+    moduleName: string;
+    message: string;
+    stack?: string;
+}
+
+interface GenerateBundleOptions {
+    /**
+     * Throw on the first component that fails to parse instead of collecting
+     * the failure and continuing with the remaining components.
+     */
+    failFast?: boolean;
+    /** Record consts, functions, and types from the entry barrel. Off by default. */
+    documentExports?: boolean;
+    /**
+     * Cache parsed component output to disk. Unchanged files skip re-parsing on
+     * later runs. On by default, writing to
+     * `node_modules/.cache/sveld/parse-cache.json`; a string sets a custom path.
+     * Pass `false` to disable.
+     */
+    cache?: boolean | string;
+    /**
+     * Check `@example` blocks on props, module exports, slots, and events.
+     * `true` runs plain TS/JS examples through the TypeScript program
+     * (`example-compile-error` diagnostics; requires `typescript`) and
+     * Svelte/HTML examples through sveld's own template parser
+     * (`example-syntax-error` diagnostics; no `typescript` needed). Pass
+     * `"syntax"` to run only the markup path, so `typescript` is never loaded
+     * even when TS/JS examples exist. Off by default.
+     */
+    checkExamples?: boolean | "syntax";
+    /**
+     * `ignore`: diagnostics matching at least one `{ code?, component?, name? }`
+     * matcher are marked `ignored` (an omitted field matches anything;
+     * `component` is a glob). Ignored diagnostics still appear in
+     * `SveldResult.diagnostics` and are counted in the text summary, but never
+     * fail `--strict` / `--strict=errors`.
+     */
+    diagnostics?: {
+        ignore?: DiagnosticIgnoreMatcher[];
+    };
+}
+
+declare const brand: unique symbol;
+
+type Brand<TBase extends string, TBrand extends string> = TBase & {
+    readonly [brand]: TBrand;
+};
+
+export type SvelteEntryPoint = Brand<string, "SvelteEntryPoint">;
+
+type NormalizedPath = Brand<string, "NormalizedPath">;
+
+interface EntryExport {
+    name: string;
+    kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
+    /**
+     * Type text from the source, when present. A namespace export
+     * (`export * as ns from "./x"`) gets `typeof import("./x.ts")`, the
+     * wrapped module relative to the entry file.
+     */
+    type?: string;
+    /** Initializer text for simple constants. */
+    value?: string;
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** `@since` / `@example` / `@see` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Declaring module, relative to the entry file. */
+    source?: string;
+    isTypeOnly: boolean;
+}
+
+type EntryExports = EntryExport[];
+
+export interface SveldRuntimeOptions extends PluginSveldOptions {
+    /** Print unresolved-type diagnostics to stderr. */
+    reportDiagnostics?: boolean;
+    /**
+     * Exit code 4 when diagnostics exist. Implies `reportDiagnostics`. Pass
+     * `"errors"` to fail only on `severity: "error"` diagnostics
+     * (`example-compile-error`, `syntax-skipped`), letting warnings
+     * (`prop-unknown-type`, `context-any-type`, `event-no-source`) through.
+     */
+    strict?: boolean | "errors";
+    /**
+     * Diff the parsed component API against a committed snapshot (default:
+     * the `json` writer's `outFile`, or `COMPONENT_API.json`) and assign a
+     * semver bump to each change. Exits `3` on a breaking change. Pass a
+     * string for a custom snapshot path.
+     */
+    check?: boolean | string;
+    /**
+     * Minimum bump `--check` fails the run (exit `3`) on: `"major"` (default,
+     * preserves prior behavior), `"minor"`, or `"patch"`.
+     */
+    checkLevel?: "major" | "minor" | "patch";
+    /** Suppress writer progress logs (`created "..."` / `unchanged "..."`). */
+    quiet?: boolean;
+    /**
+     * Print the single selected `json` / `markdown` document to stdout
+     * instead of writing it to disk. Requires exactly one of those two
+     * outputs; CLI-only (the Vite plugin ignores it).
+     */
+    stdout?: boolean;
+    /**
+     * Output format for the `--check` report and the `--report-diagnostics` /
+     * `--strict` diagnostics summary: `"text"` (default) or `"json"`.
+     * Channels are unchanged, the check report on stdout and diagnostics on
+     * stderr. CLI-only; `sveld()` ignores `format` for its own console output.
+     */
+    format?: "text" | "json";
+}
+
+export type SveldConfig = SveldRuntimeOptions;
+
+export declare function defineConfig(config: SveldConfig): SveldConfig;
+
+interface PluginSveldOptions extends Pick<GenerateBundleOptions, "cache" | "checkExamples" | "diagnostics"> {
+    /**
+     * Specify the entry point to uncompiled Svelte source.
+     * If not provided, sveld will use the "svelte" field from package.json.
+     */
+    entry?: string;
+    /**
+     * Load `sveld.config.{js,mjs,ts}` and merge it with these options; these
+     * options win when a key is set in both. `true` resolves the config from
+     * the Vite project root (or `process.cwd()` if the plugin isn't running
+     * under Vite); a string is an explicit path to the config file itself.
+     * @default false
+     */
+    config?: boolean | string;
+    glob?: boolean;
+    /** Suppress writer progress logs (`created "..."` / `unchanged "..."`). */
+    quiet?: boolean;
+    /** Record consts, functions, and types from the entry barrel. Off by default. */
+    documentExports?: boolean;
+    types?: boolean;
+    typesOptions?: TypesOptions;
+    json?: boolean;
+    jsonOptions?: JsonOptions;
+    markdown?: boolean;
+    markdownOptions?: MarkdownOptions;
+    /**
+     * Abort the entire run when a single component fails to parse.
+     * When `false` (the default), parse failures are collected as diagnostics
+     * and the remaining components still emit their output.
+     */
+    failFast?: boolean;
+    /**
+     * Regenerate output incrementally when relevant source changes during
+     * `vite dev` / `vite build --watch`: a component, the entry barrel itself
+     * (adding/removing an export), a module a component reads a value from,
+     * or a non-`.svelte` file a component names via `@extendProps` /
+     * `@extends`. Only the edited components and those that read an edited
+     * module are re-parsed.
+     * @default false
+     */
+    watch?: boolean;
+}
+
+interface HotUpdateContext {
+    file: string;
+}
+
+interface RollupPluginContext {
+    error(message: string): never;
+}
+
+interface ResolvedViteConfig {
+    root: string;
+}
+
+interface SveldPlugin {
+    name: string;
+    apply?: "build" | "serve";
+    enforce?: "pre" | "post";
+    /** Vite-only hook: captures the project root before `buildStart` runs. */
+    configResolved?(config: ResolvedViteConfig): void;
+    buildStart(): void | Promise<void>;
+    generateBundle(this: RollupPluginContext): Promise<void>;
+    writeBundle(this: RollupPluginContext): Promise<void>;
+    /** Vite dev-server HMR hook (serve mode). */
+    handleHotUpdate?(ctx: HotUpdateContext): void;
+    /** Rollup/Vite watch hook (build `--watch`). */
+    watchChange?(id: string): void;
+}
+
+export default function pluginSveld(opts?: PluginSveldOptions): SveldPlugin;
+
+export interface JsonOptions {
+    /**
+     * Path (relative to the project root) for the single combined JSON
+     * document. Ignored when `outDir` is set.
+     * @default "COMPONENT_API.json"
+     */
+    outFile?: string;
+    /**
+     * Emit one `<ComponentName>.api.json` file per component into this
+     * directory instead of the single combined `outFile`.
+     */
+    outDir?: string;
+    /**
+     * Include `source`/`componentCommentSource` position ranges in the
+     * output. These are the bulk of a large component library's
+     * `COMPONENT_API.json` (roughly a quarter of the file for a 150+
+     * component library); set to `false` to omit them and shrink the file
+     * when consumers don't need exact source positions.
+     * @default true
+     */
+    source?: boolean;
+}
+
+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;
+}
+
+interface BuildComponentApiDocumentOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+}
+
+export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;
+
+export interface MarkdownOptions {
+    /**
+     * Path (relative to the project root) for the single combined Markdown
+     * document. Ignored when `outDir` is set.
+     * @default "COMPONENT_INDEX.md"
+     */
+    outFile?: string;
+    /**
+     * Emit one `<ModuleName>.md` file per component into this directory,
+     * plus an index `README.md` linking to each, instead of the single
+     * combined `outFile`. See `jsonOptions.outDir` for the equivalent JSON
+     * option.
+     */
+    outDir?: string;
+    /**
+     * Called every time a heading, quote, paragraph, divider, or raw block is
+     * appended to the document, to inject extra content.
+     */
+    onAppend?: (type: AppendType, document: MarkdownDocument, components: ComponentDocs) => void;
+}
+
+type AppendType = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "quote" | "p" | "divider" | "raw";
+
+interface TocLine {
+    /** Leading space count; 0 for the top-level (`h2`) entries the TOC currently lists. */
+    indent: number;
+    raw: string;
+}
+
+type MarkdownAppendCallback = (type: AppendType, document: MarkdownDocument) => void;
+
+interface MarkdownDocumentOptions {
+    onAppend?: MarkdownAppendCallback;
+}
+
+declare class MarkdownDocument {
+    sourceParts: string[];
+    hasToC: boolean;
+    toc: TocLine[];
+    onAppend?: MarkdownAppendCallback;
+    constructor(options?: MarkdownDocumentOptions);
+    get source(): string;
+    appendLineBreaks(): this;
+    append(type: AppendType, raw?: string): this;
+    tableOfContents(): this;
+    end(): string;
+}
+
+type TransformContext = {
+    kind: "component";
+    component: ComponentDocApi;
+    filePath: string;
+} | {
+    kind: "index";
+    filePath: string;
+};
+
+export interface TypesOptions extends WriteTsDefinitionOptions {
+    /**
+     * Output directory for generated `.d.ts` files, relative to the project
+     * root.
+     * @default "types"
+     */
+    outDir?: string;
+    /**
+     * Raw text prepended to the generated `index.d.ts` barrel, e.g. a license
+     * header.
+     * @default ""
+     */
+    preamble?: string;
+    /**
+     * Post-processes each generated file's text before it is written. Runs
+     * after the generated-text cache, so it applies on every run. Config file
+     * or `sveld()` only.
+     */
+    transform?: (text: string, context: TransformContext) => string | Promise<string>;
+    /**
+     * Also re-export generated types from `index.d.ts`: each component's
+     * `Props` type, and its `Exports` type under `format: "component"`.
+     */
+    indexTypes?: boolean;
+}
+
+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";
+}
+
+type SveldOptions = SveldRuntimeOptions;
+
+export interface SveldResult {
+    /** Diagnostics from this run. */
+    diagnostics: SveldDiagnostic[];
+    /** Populated when `check` is enabled: the API diff against the committed snapshot. */
+    check?: CheckResult;
+    /** Parse errors for components that failed to parse (empty unless `failFast` is disabled and a component errors). */
+    errors: ComponentParseError[];
+    /**
+     * The component API document for the exported components, exactly as the
+     * `json` writer writes `COMPONENT_API.json`. Populated whether or not
+     * `json` is enabled, so custom output can be rendered from it directly.
+     */
+    document: ComponentApiDocument;
+    /**
+     * Suggested process exit code for this run, using the same mapping as the
+     * CLI (see {@link resolveExitCode}). `sveld()` never mutates `process.exitCode` itself; assign this
+     * value yourself if you want the process to exit non-zero.
+     */
+    exitCode: ExitCode;
+}
+
+type ExitCode = 0 | 1 | 2 | 3 | 4;
+
+export declare function sveld(opts?: SveldOptions): Promise<SveldResult>;