sveld 0.32.8 → 0.34.0

package/lib/load-config.d.ts

@@ -0,0 +1,44 @@
+import type { PluginSveldOptions } from "./plugin";
+/**
+ * Public shape of a `sveld.config.{js,ts,mjs}` file. Identical to the options
+ * accepted by the Vite/Rollup plugin and the CLI.
+ */
+export type SveldConfig = PluginSveldOptions;
+/** Config file names probed at the project root. First existing file wins. */
+export declare const CONFIG_FILE_NAMES: readonly ["sveld.config.js", "sveld.config.mjs", "sveld.config.ts"];
+/**
+ * Identity helper that fully types a `sveld` config object.
+ *
+ * @example
+ * ```ts
+ * // sveld.config.js
+ * import { defineConfig } from "sveld";
+ *
+ * export default defineConfig({
+ *   glob: true,
+ *   json: true,
+ *   markdown: true,
+ * });
+ * ```
+ */
+export declare function defineConfig(config: SveldConfig): SveldConfig;
+/** Locate a `sveld.config.{js,mjs,ts}` file in `cwd`, or `null` if none exists. */
+export declare function resolveConfigPath(cwd?: string): string | null;
+/**
+ * Load and validate a `sveld` config file by absolute path.
+ *
+ * The package is ESM-only, so the file is loaded via dynamic `import()`. A
+ * cache-busting query is appended so repeated loads (e.g. across tests or
+ * watch runs) reflect the latest contents.
+ *
+ * @throws if the module cannot be imported (e.g. a syntax error or a config
+ * that throws at evaluation time) or if it does not default-export an object.
+ */
+export declare function loadConfigFrom(configPath: string): Promise<SveldConfig>;
+/**
+ * Discover and load a `sveld.config.{js,mjs,ts}` file from `cwd`.
+ * Returns an empty object when no config file is present.
+ */
+export declare function loadConfig(cwd?: string): Promise<SveldConfig>;
+/** Shallow-merge option sources. Later sources override earlier ones. */
+export declare function mergeConfig<T extends PluginSveldOptions = PluginSveldOptions>(...sources: Array<Partial<T> | undefined>): Partial<T>;

package/lib/parse-cache.d.ts

@@ -0,0 +1,28 @@
+import { type ParsedComponent } from "./ComponentParser";
+/** Default on-disk location for the persistent parse cache, relative to the project root. */
+export declare const DEFAULT_CACHE_FILE: string;
+/** Resolves the effective cache file path for `cache: true | string`. */
+export declare function resolveCacheFilePath(rootDir: string, cache: boolean | string): string;
+export declare function hashSource(source: string): string;
+/**
+ * Cross-run parse cache. Entries match on file path and sha256 of source.
+ * Symbol-keyed TypeScript metadata is stored separately because JSON drops symbols.
+ */
+export declare class ParseCache {
+    private readonly cacheFilePath;
+    private readonly file;
+    private readonly next;
+    /** Paths forced to miss this run (e.g. dependents of a changed `@extends` target). */
+    private readonly blocked;
+    constructor(cacheFilePath: string);
+    /** True when `get()` would return a hit for `resolvedPath` and `hash`. */
+    has(resolvedPath: string, hash: string): boolean;
+    /** Returns the cached parse for `resolvedPath` when its content hash still matches. */
+    get(resolvedPath: string, hash: string): ParsedComponent | null;
+    /** Records a freshly parsed component so it can be reused on a future run. */
+    set(resolvedPath: string, hash: string, parsed: ParsedComponent): void;
+    /** Skip cache for `resolvedPath` this run (e.g. an @extends dependent). */
+    invalidate(resolvedPath: string): void;
+    /** Persists this run's cache entries back to disk. */
+    save(): void;
+}

package/lib/parse-entry-exports.d.ts

@@ -0,0 +1,30 @@
+/** One named export from the entry barrel (not a `.svelte` component). */
+export 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;
+}
+export type EntryExports = EntryExport[];
+/**
+ * List consts, functions, and types exported from an entry barrel.
+ *
+ * Follows re-exports with AST-only traversal. Skips `.svelte` files.
+ *
+ * @param entryFile - Absolute path to the entry module.
+ * @returns Exports deduplicated by name, sorted alphabetically.
+ *
+ * @example
+ * ```ts
+ * // entry: export { VERSION } from "./constants"; export type { Theme } from "./types";
+ * parseEntryExports("/abs/src/index.ts");
+ * // [{ name: "Theme", kind: "type", isTypeOnly: true, ... }, { name: "VERSION", kind: "const", ... }]
+ * ```
+ */
+export declare function parseEntryExports(entryFile: string): EntryExports;

package/lib/plugin.d.ts

@@ -1,67 +1,62 @@
-import { type NormalizedPath } from "./brands";
-import { type ParsedComponent } from "./ComponentParser";
-import { type ParsedExports } from "./parse-exports";
-import { type WriteJsonOptions } from "./writer/writer-json";
-import { type WriteMarkdownOptions } from "./writer/writer-markdown";
-import { type WriteTsDefinitionsOptions } from "./writer/writer-ts-definitions";
-export interface PluginSveldOptions {
+import { type GenerateBundleOptions, type GenerateBundleResult } from "./bundle";
+import "./writer/built-in-writers";
+import type { WriteJsonOptions } from "./writer/writer-json";
+import type { WriteMarkdownOptions } from "./writer/writer-markdown";
+import type { WriteTsDefinitionsOptions } from "./writer/writer-ts-definitions";
+export type { CollectedComponents, ComponentDocApi, ComponentDocs, ComponentParseError, GenerateBundleOptions, GenerateBundleResult, ResolveComponentFilePath, } from "./bundle";
+export { collectComponents, collectSvelteFilePaths, generateBundle, processComponent, readFileMap, reportParseErrors, toGenerateBundleOptions, } from "./bundle";
+export 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>;
+    /**
+     * 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;
 }
-export interface ComponentDocApi extends ParsedComponent {
-    filePath: NormalizedPath;
-    moduleName: string;
+/** Subset of Vite/Rollup's HMR context that the watch hook relies on. */
+interface HotUpdateContext {
+    file: string;
 }
-export type ComponentDocs = Map<string, ComponentDocApi>;
 interface SveldPlugin {
     name: string;
     apply?: "build" | "serve";
     enforce?: "pre" | "post";
-    buildStart(): void;
+    buildStart(): void | Promise<void>;
     generateBundle(): Promise<void>;
     writeBundle(): 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 GenerateBundleResult {
-    exports: ParsedExports;
-    components: ComponentDocs;
-    allComponentsForTypes: ComponentDocs;
-}
-/**
- * Generates component documentation bundle from Svelte source files.
- *
- * Parses exports, discovers components (optionally via glob), and processes
- * all Svelte files to extract component metadata. Returns both exported
- * components (for JSON/Markdown) and all components (for TypeScript definitions).
- *
- * @param input - Entry point file or directory containing Svelte components
- * @param glob - Whether to glob for all .svelte files in the directory
- * @returns Bundle result containing exports, components, and allComponentsForTypes
- *
- * @example
- * ```ts
- * // Generate from single file:
- * const result = await generateBundle("./src/App.svelte", false);
- *
- * // Generate from directory with glob:
- * const result = await generateBundle("./src", true);
- * ```
- */
-export declare function generateBundle(input: string, glob: boolean): Promise<{
-    exports: ParsedExports;
-    components: ComponentDocs;
-    allComponentsForTypes: ComponentDocs;
-}>;
 /**
  * Writes output files based on plugin options.
  *
@@ -84,4 +79,3 @@ export declare function generateBundle(input: string, glob: boolean): Promise<{
  * ```
  */
 export declare function writeOutput(result: GenerateBundleResult, opts: PluginSveldOptions, input: string): void;
-export {};

package/lib/resolve-types.d.ts

@@ -0,0 +1,52 @@
+import type { ParsedComponentTypeScriptMetadata, ResolvedComponentProp } from "./ComponentParser";
+import type { ExampleCheckSource } from "./example-check";
+export interface ResolveTarget {
+    moduleName: string;
+    filePath: string;
+    metadata: ParsedComponentTypeScriptMetadata;
+}
+export interface ExampleCheckTarget {
+    moduleName: string;
+    filePath: string;
+    sources: ExampleCheckSource[];
+}
+/** One `@example` block that failed to type-check. */
+export interface ExampleCheckDiagnostic {
+    id: string;
+    name: string;
+    message: string;
+}
+/**
+ * Expands opaque imported `$props()` types using the project's TypeScript program.
+ * Loaded only when `resolveTypes` is enabled.
+ */
+export declare class TypeResolver {
+    private readonly api;
+    private readonly symbolFlags;
+    private readonly tsconfigPath;
+    private readonly overlay;
+    private constructor();
+    /**
+     * Loads `typescript` and the nearest `tsconfig.json`.
+     * Returns `null` when either is missing.
+     */
+    static create(cwd?: string): Promise<TypeResolver | null>;
+    /** Resolves every target in one program snapshot. */
+    expandAll(targets: ResolveTarget[]): Promise<Map<string, ResolvedComponentProp[]>>;
+    /**
+     * Type-checks every `@example` block in one program snapshot.
+     *
+     * Each example gets its own virtual file: a `declare`-style binding for the
+     * documented symbol (typed as `any` end-to-end, so types sveld can't see
+     * never cause a false positive), then the example body. Catches renamed
+     * or removed symbols and wrong arity. Not full type checking; it does not
+     * depend on the rest of the component's types.
+     */
+    checkExamples(targets: ExampleCheckTarget[]): Promise<Map<string, ExampleCheckDiagnostic[]>>;
+    /** Closes the TypeScript server process. */
+    dispose(): Promise<void>;
+    private resolveFile;
+    private createFileSystem;
+    private virtualFileName;
+    private exampleFileName;
+}

package/lib/sveld.d.ts

@@ -1,3 +1,4 @@
+import { type SveldDiagnostic } from "./diagnostics";
 import { type PluginSveldOptions } from "./plugin";
 interface SveldOptions extends Omit<PluginSveldOptions, "entry"> {
     /**
@@ -6,6 +7,17 @@ interface SveldOptions extends Omit<PluginSveldOptions, "entry"> {
      * the entry point from the `package.json#svelte` field.
      */
     input?: string;
+    /**
+     * Exit with code 1 when diagnostics are present. Default `false`.
+     */
+    strict?: boolean;
+}
+/**
+ * Result of a programmatic `sveld` run.
+ */
+interface SveldResult {
+    /** Diagnostics from this run. */
+    diagnostics: SveldDiagnostic[];
 }
 /**
  * Programmatic entry point for sveld.
@@ -21,5 +33,5 @@ interface SveldOptions extends Omit<PluginSveldOptions, "entry"> {
  * });
  * ```
  */
-export declare function sveld(opts?: SveldOptions): Promise<void>;
+export declare function sveld(opts?: SveldOptions): Promise<SveldResult>;
 export {};

package/lib/watch.d.ts

@@ -0,0 +1,34 @@
+import { type GenerateBundleResult } from "./bundle";
+/** Result of an incremental update. */
+export interface SveldBundleUpdate {
+    /** The full, updated bundle result (all components, with the affected ones re-parsed). */
+    result: GenerateBundleResult;
+    /**
+     * Absolute paths of the components that were re-parsed: the changed files
+     * plus their transitive `@extendProps` / `@extends` dependents. Other
+     * components are reused from the previous parse.
+     */
+    reparsed: string[];
+}
+/**
+ * A long-lived bundle that supports scoped, incremental re-parsing.
+ *
+ * `createSveldBundle` performs the initial full parse. `update` then re-parses
+ * only the components affected by a set of changed files, leaving every other
+ * component's previously-parsed output untouched. This is the core of the
+ * plugin's watch mode.
+ */
+export interface SveldBundle {
+    readonly result: GenerateBundleResult;
+    /** Re-parse the changed files plus their dependents and return the updated bundle. */
+    update(changedFilePaths: string[]): Promise<SveldBundleUpdate>;
+}
+/**
+ * Creates a watch-mode bundle for the given entry point, performing the initial
+ * full parse up front.
+ *
+ * @param input - Entry point file or directory containing Svelte components
+ * @param glob - Whether to glob for all `.svelte` files in the directory
+ * @param documentExports - Record consts, functions, and types from the entry barrel
+ */
+export declare function createSveldBundle(input: string, glob: boolean, documentExports?: boolean): Promise<SveldBundle>;

package/lib/writer/built-in-writers.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/writer/document-model.d.ts

@@ -0,0 +1,34 @@
+import type { EntryExports } from "../parse-entry-exports";
+import type { ComponentDocApi, ComponentDocs } from "../plugin";
+export declare const COMPONENT_API_SCHEMA_VERSION = 1;
+/**
+ * Canonical, renderer-agnostic representation of a component collection.
+ *
+ * Every writer (JSON, Markdown, TypeScript definitions) builds this document
+ * via `buildComponentApiDocument` instead of independently sorting/filtering
+ * the raw `ComponentDocs` map, so sort order and field stripping can't drift
+ * between output formats.
+ */
+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;
+}
+/**
+ * Builds the canonical document for a component collection: components
+ * sorted alphabetically by `moduleName`, with the Node-only `diagnostics`
+ * field stripped.
+ */
+export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;

package/lib/writer/markdown-format-utils.d.ts

@@ -1,9 +1,11 @@
+import type { DeprecatedValue } from "../ComponentParser";
 export declare const BACKTICK_REGEX: RegExp;
 export declare const WHITESPACE_REGEX: RegExp;
 export declare const MD_TYPE_UNDEFINED = "--";
 export declare const PROP_TABLE_HEADER = "| Prop name | Required | Kind | Reactive | Binding | Type | Default value | Description |\n| :- | :- | :- | :- | :- | :- | :- | :- |\n";
-export declare const SLOT_TABLE_HEADER = "| Slot name | Default | Props | Fallback |\n| :- | :- | :- | :- |\n";
+export declare const SLOT_TABLE_HEADER = "| Slot name | Default | Props | Fallback | Description |\n| :- | :- | :- | :- | :- |\n";
 export declare const EVENT_TABLE_HEADER = "| Event name | Type | Detail | Description |\n| :- | :- | :- | :- |\n";
+export declare const EXPORT_TABLE_HEADER = "| Name | Kind | Type | Description |\n| :- | :- | :- | :- |\n";
 /**
  * Escape `|` and wrap a prop type for markdown table cells.
  *
@@ -33,6 +35,16 @@ export declare function escapeHtml(text: string): string;
  * ```
  */
 export declare function formatPropValue(value: string | undefined): string;
+/**
+ * Strike through deprecated prop, slot, and event names in markdown tables.
+ *
+ * @example
+ * ```ts
+ * formatNameWithDeprecation("size", "use width")
+ * // Returns: "<s>size</s><br />**Deprecated**: use width"
+ * ```
+ */
+export declare function formatNameWithDeprecation(name: string, deprecated: DeprecatedValue | undefined): string;
 /**
  * Format a prop description; newlines become `<br />`.
  *
@@ -63,6 +75,23 @@ export declare function formatSlotProps(props?: string): string;
  * ```
  */
 export declare function formatSlotFallback(fallback?: string): string;
+/**
+ * Format a slot/snippet description plus pass-through JSDoc tags for markdown
+ * table cells. Newlines become `<br />` and `<`, `>`, `|` are escaped so the
+ * content stays inside a single table cell.
+ *
+ * @example
+ * ```ts
+ * formatSlotDescription("Header content.", [{ name: "since", body: "1.0.0" }])
+ * // Returns: "Header content.<br />@since 1.0.0"
+ * formatSlotDescription(undefined, [])
+ * // Returns: "--"
+ * ```
+ */
+export declare function formatSlotDescription(description?: string, tags?: Array<{
+    name: string;
+    body: string;
+}>): string;
 /**
  * Format event detail types for markdown table cells.
  *

package/lib/writer/markdown-render-utils.d.ts

@@ -1,3 +1,4 @@
+import type { EntryExports } from "../parse-entry-exports";
 import type { ComponentDocs } from "../plugin";
 import type { AppendType } from "./MarkdownWriterBase";
 /** Minimal markdown writer surface used by JSON and browser renderers. */
@@ -5,5 +6,5 @@ interface MarkdownDocument {
     append(type: AppendType, raw?: string): MarkdownDocument;
     tableOfContents(): MarkdownDocument;
 }
-export declare function renderComponentsToMarkdown(document: MarkdownDocument, components: ComponentDocs): void;
+export declare function renderComponentsToMarkdown(document: MarkdownDocument, components: ComponentDocs, entryExports?: EntryExports): void;
 export {};

package/lib/writer/registry.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentDocs } from "../plugin";
+/** Which component set a writer expects: exported-only, or every discovered component. */
+export type WriterComponentSet = "exported" | "all";
+/**
+ * A pluggable output format. Built-in writers (`json`, `markdown`, `types`)
+ * register themselves under these names; third parties can `registerWriter`
+ * their own to add new output formats without a core PR.
+ */
+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>[];

package/lib/writer/writer-json.d.ts

@@ -1,9 +1,12 @@
+import type { EntryExports } from "../parse-entry-exports";
 import type { ComponentDocs } from "../plugin";
 export interface WriteJsonOptions {
     input: string;
     inputDir: string;
     outFile: string;
     outDir?: string;
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
 }
 /**
  * Writes component documentation to JSON format.

package/lib/writer/writer-markdown.d.ts

@@ -1,8 +1,11 @@
+import type { EntryExports } from "../parse-entry-exports";
 import type { ComponentDocs } from "../plugin";
 import WriterMarkdown, { type AppendType } from "./WriterMarkdown";
 export interface WriteMarkdownOptions {
     write?: boolean;
     outFile: string;
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
     onAppend?: (type: AppendType, document: WriterMarkdown, components: ComponentDocs) => void;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sveld",
-  "version": "0.32.8",
+  "version": "0.34.0",
   "license": "Apache-2.0",
   "description": "Generate TypeScript definitions and component documentation for your Svelte components.",
   "type": "module",