sveld 0.35.2 → 0.36.0

package/lib/index.d.ts

@@ -1,10 +1,767 @@
-export { default as ComponentParser, type SerializedComponentEvent } from "./ComponentParser";
-export { type ApiChange, type CheckResult, diffApiDocuments, formatCheckReport, runCheck, type SemverBump, } from "./check";
-export { cli } from "./cli";
-export type { SveldDiagnostic, SveldDiagnosticKind } from "./diagnostics";
-export type { SvelteEntryPoint } from "./get-svelte-entry";
-export { defineConfig, type SveldConfig } from "./load-config";
-export { default } from "./plugin";
-export { sveld } from "./sveld";
-export { buildComponentApiDocument, type ComponentApiDocument } from "./writer/document-model";
-export { getWriter, listWriters, type OutputWriter, registerWriter } from "./writer/registry";
+/// <reference types="node" />
+
+import type { Property } from "estree";
+
+import type { Node } from "estree-walker";
+
+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 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";
+    /** 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 type CheckReportJson = CheckResult & {
+    kind: "check-report";
+};
+
+export declare function formatCheckReportJson(result: CheckResult): string;
+
+interface ComponentDocApi extends ParsedComponent {
+    filePath: NormalizedPath;
+    moduleName: string;
+}
+
+type ComponentDocs = Map<string, ComponentDocApi>;
+
+interface GenerateBundleOptions {
+    /**
+     * Throw on the first component that fails to parse instead of collecting
+     * the failure and continuing with the remaining components.
+     */
+    failFast?: boolean;
+    /**
+     * Load the TypeScript program to expand opaque imported whole-object `$props()`
+     * types into JSON/Markdown props. Off by default; requires `typescript`.
+     */
+    resolveTypes?: 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;
+    /**
+     * Run plain TS/JS `@example` blocks on props, module exports, slots, and
+     * events through the TypeScript program. Broken examples become
+     * `example-compile-error` diagnostics. Svelte/HTML markup is skipped.
+     * Off by default. Requires `typescript`.
+     */
+    checkExamples?: boolean;
+    /**
+     * Parse as usual (so cache reads and real errors still apply) but skip
+     * persisting the parse cache to disk. Set by the CLI's `--dry-run`.
+     */
+    dryRun?: boolean;
+}
+
+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">;
+
+type RelativeSourcePath = Brand<string, "RelativeSourcePath">;
+
+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[];
+
+type ParsedExports = Record<string, {
+    source: RelativeSourcePath;
+    default: boolean;
+    mixed?: boolean;
+}>;
+
+interface SveldRuntimeOptions extends PluginSveldOptions {
+    /** Print unresolved-type diagnostics to stderr. */
+    reportDiagnostics?: boolean;
+    /** Exit code 1 when diagnostics exist. Implies `reportDiagnostics`. */
+    strict?: boolean;
+    /**
+     * 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 `1` on a breaking change. Pass a
+     * string for a custom snapshot path.
+     */
+    check?: boolean | string;
+    /** Suppress writer progress logs (`created "..."` / `unchanged "..."`). */
+    quiet?: boolean;
+    /**
+     * Print the single selected `json` / `markdown` / `customElements` document
+     * to stdout instead of writing it to disk. Requires exactly one of those
+     * three outputs; CLI-only (the Vite plugin ignores it). `"ndjson"` is only
+     * valid with `json` and prints one minified JSON object per component per
+     * line instead of the single combined document.
+     */
+    stdout?: boolean | "json" | "ndjson";
+    /**
+     * 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.
+     */
+    format?: "text" | "json";
+    /**
+     * Resolve the entry, load config, and parse components as usual, but print
+     * `would write "<path>"` for each output file to stdout instead of writing
+     * it (including the parse cache). CLI-only; the Vite plugin ignores it.
+     */
+    dryRun?: boolean;
+}
+
+export type SveldConfig = SveldRuntimeOptions;
+
+export declare function defineConfig(config: SveldConfig): SveldConfig;
+
+interface PluginSveldOptions extends Pick<GenerateBundleOptions, "resolveTypes" | "cache" | "checkExamples"> {
+    /**
+     * Specify the entry point to uncompiled Svelte source.
+     * If not provided, sveld will use the "svelte" field from package.json.
+     */
+    entry?: string;
+    glob?: boolean;
+    /** Record consts, functions, and types from the entry barrel. Off by default. */
+    documentExports?: boolean;
+    types?: boolean;
+    typesOptions?: Partial<Omit<WriteTsDefinitionsOptions, "inputDir">>;
+    json?: boolean;
+    jsonOptions?: Partial<Omit<WriteJsonOptions, "inputDir">>;
+    markdown?: boolean;
+    markdownOptions?: Partial<WriteMarkdownOptions>;
+    /** Generate a Custom Elements Manifest (`custom-elements.json`, schemaVersion "1.0.0"). */
+    customElements?: boolean;
+    customElementsOptions?: Partial<Omit<WriteCustomElementsOptions, "inputDir">>;
+    /**
+     * Run additional, userland-registered writers (via `registerWriter` from
+     * "sveld") beyond the built-in `json`/`markdown`/`types` outputs. Keyed by
+     * the writer's registered `name`, valued by that writer's options.
+     */
+    additionalWriters?: Record<string, unknown>;
+    /**
+     * 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 `.svelte` source changes during
+     * `vite dev` / `vite build --watch`. Only the changed component and the
+     * components that depend on it via `@extendProps` / `@extends` are re-parsed.
+     * @default false
+     */
+    watch?: boolean;
+}
+
+interface HotUpdateContext {
+    file: string;
+}
+
+interface SveldPlugin {
+    name: string;
+    apply?: "build" | "serve";
+    enforce?: "pre" | "post";
+    buildStart(): void | Promise<void>;
+    generateBundle(): Promise<void>;
+    writeBundle(): 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;
+
+interface WriteCustomElementsOptions {
+    inputDir: string;
+    outFile: string;
+    /** Report the resolved path instead of writing. Set by `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+interface WriteJsonOptions {
+    input: string;
+    inputDir: string;
+    outFile: string;
+    outDir?: string;
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+    /** Report resolved paths instead of writing. Set by `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+interface WriteMarkdownOptions {
+    write?: boolean;
+    outFile: string;
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+    onAppend?: (type: AppendType, document: WriterMarkdown, components: ComponentDocs) => void;
+    /** Report the resolved path instead of writing. Set by `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+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;
+}
+
+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;
+}
+
+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>;
+}
+
+interface WriteTsDefinitionsOptions extends WriteTsDefinitionOptions {
+    outDir: string;
+    inputDir: string;
+    preamble: string;
+    exports: ParsedExports;
+    /** Report resolved paths instead of writing. Set by `sveld --dry-run`. */
+    dryRun?: 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";
+}
+
+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 declare function cli(process: NodeJS.Process): Promise<void>;
+
+type SveldOptions = SveldRuntimeOptions;
+
+interface SveldResult {
+    /** Diagnostics from this run. */
+    diagnostics: SveldDiagnostic[];
+    /** Populated when `check` is enabled: the API diff against the committed snapshot. */
+    check?: CheckResult;
+}
+
+export declare function sveld(opts?: SveldOptions): Promise<SveldResult>;
+
+type WriterComponentSet = "exported" | "all";
+
+export interface OutputWriter<TOptions = unknown> {
+    name: string;
+    /** Which component set this writer expects. @default "exported" */
+    componentSet?: WriterComponentSet;
+    write(components: ComponentDocs, options: TOptions): Promise<unknown> | unknown;
+}
+
+export declare function registerWriter<TOptions = unknown>(writer: OutputWriter<TOptions>): void;
+
+export declare function getWriter(name: string): OutputWriter<unknown> | undefined;
+
+export declare function listWriters(): OutputWriter<unknown>[];