sveld 0.32.8 → 0.33.0

package/README.md

@@ -123,8 +123,10 @@ export default class Button extends SvelteComponentTyped<
   - [Vite](#vite)
   - [Node.js](#nodejs)
   - [CLI](#cli)
+  - [Config File](#config-file)
   - [Publishing to NPM](#publishing-to-npm)
 - [Available Options](#available-options)
+- [Documenting Entry Exports](#documenting-entry-exports)
 - [JSON Output](#json-output)
 - [API Reference](#api-reference)
   - [@type](#type)
@@ -135,6 +137,7 @@ export default class Button extends SvelteComponentTyped<
     - [Extra JSDoc tags before `@slot`](#extra-jsdoc-tags-before-slot)
     - [Svelte 5 Snippet Compatibility](#svelte-5-snippet-compatibility)
   - [@event](#event)
+  - [@deprecated](#deprecated)
   - [Context API](#context-api)
   - [@restProps](#restprops)
   - [@extendProps](#extendprops)
@@ -169,6 +172,36 @@ When both TypeScript syntax and JSDoc are present, `sveld` resolves prop types i
 
 `sveld` stays AST-only. It copies imported and local type text into generated `.d.ts` output but does not run project-wide semantic resolution with the TypeScript compiler. Opaque imported whole-object `$props()` types can therefore stay in declarations without being fully expanded into JSON metadata.
 
+#### Opt-in semantic resolution (`resolveTypes`)
+
+Imported whole-object `$props()` types stay opaque in JSON by default (`"props": []`). Turn on `resolveTypes` when a docs site or prop table needs the individual fields.
+
+```ts
+await sveld({ json: true, resolveTypes: true });
+```
+
+```svelte
+<script lang="ts">
+  import type { Props } from "./types";
+
+  let props: Props = $props();
+</script>
+```
+
+Without `resolveTypes`, JSON lists no props. With it, each field shows up with `"typeSource": "typescript"`:
+
+```jsonc
+{
+  "props": [
+    { "name": "disabled", "type": "boolean", "isRequired": false, "typeSource": "typescript" },
+    { "name": "href", "type": "string", "isRequired": true, "typeSource": "typescript" },
+    { "name": "variant", "type": "\"primary\" | \"secondary\"", "isRequired": true, "typeSource": "typescript" }
+  ]
+}
+```
+
+**Performance.** Off by default. This is the only path that loads TypeScript. It needs `typescript` and a `tsconfig.json`, runs slower than the AST-only pipeline, and gets slower as your types grow. Use it only when you need expanded JSON. `.d.ts` output is unchanged.
+
 ## Usage
 
 ### Installation
@@ -291,6 +324,31 @@ sveld({
 });
 ```
 
+### Config File
+
+Put a `sveld.config.js`, `sveld.config.mjs`, or `sveld.config.ts` at your project root to set defaults for the CLI and the programmatic `sveld()` API.
+
+Import `defineConfig` from `sveld` for typed options. Config files must use ESM syntax (`export default`).
+
+```js
+// sveld.config.js
+import { defineConfig } from "sveld";
+
+export default defineConfig({
+  glob: true,
+  json: true,
+  markdown: true,
+});
+```
+
+Later sources win when options overlap:
+
+CLI flags > config file > `package.json#svelte` inference / defaults
+
+With the config above, `npx sveld --json` keeps `glob` and `markdown` from the file. A CLI flag overrides the same key in the config.
+
+A bad config (syntax error, throws at load time, or no default-export object) fails with an error that names the file.
+
 ### Publishing to NPM
 
 TypeScript definitions land in the `types` folder by default. Include that folder in `package.json` when you publish to npm.
@@ -314,12 +372,15 @@ TypeScript definitions land in the `types` folder by default. Include that folde
 
 - **`entry`** (string, optional): Specify the entry point to uncompiled Svelte source. If not provided, sveld will use the `"svelte"` field from `package.json`.
 - **`glob`** (boolean, optional): Enable glob mode to analyze all `*.svelte` files.
+- **`documentExports`** (boolean, optional): Include consts, functions, and types from the entry barrel in JSON (`exports`) and Markdown ("Exports"). Off by default. See [Documenting Entry Exports](#documenting-entry-exports).
 - **`types`** (boolean, optional, default: `true`): Generate TypeScript definitions.
 - **`typesOptions`** (object, optional): Options for TypeScript definition generation, including `outDir`, `preamble`, and `printWidth`.
 - **`json`** (boolean, optional): Generate component documentation in JSON format.
 - **`jsonOptions`** (object, optional): Options for JSON output.
 - **`markdown`** (boolean, optional): Generate component documentation in Markdown format.
 - **`markdownOptions`** (object, optional): Options for Markdown output.
+- **`watch`** (boolean, optional, default: `false`): 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`](#extendprops) / `@extends` are re-parsed, rather than rebuilding every component. Without this option, the plugin only runs during `vite build`.
+- **`failFast`** (boolean, optional, default: `false`): Abort the entire run when a single component fails to parse. By default, parse failures are collected as diagnostics (and reported to `stderr`) so the remaining components still emit their output. Also available as the `--fail-fast` CLI flag.
 
 By default, only TypeScript definitions are generated.
 
@@ -332,6 +393,32 @@ sveld({
 })
 ```
 
+## Documenting Entry Exports
+
+Most entry barrels re-export more than `.svelte` components. Set `documentExports: true` to add consts, functions, and types to the JSON and Markdown output.
+
+```diff
+sveld({
+  json: true,
+  markdown: true,
++  documentExports: true,
+})
+```
+
+Example entry file:
+
+```ts
+// src/index.ts
+export { default as Button } from "./Button.svelte";
+export { VERSION } from "./constants";
+export { clamp } from "./utils";
+export type { Theme } from "./types";
+```
+
+From that barrel, `sveld` documents `VERSION`, `clamp`, and `Theme`. `Button` still goes through the component path. Type text is copied from source, not resolved with `tsc`, same as the rest of the tool.
+
+JSON adds `exports` and `totalExports`. Markdown adds an "Exports" section. Each item has `name`, `kind`, type text, optional JSDoc `description`, and `source`.
+
 ## JSON Output
 
 When `json: true` is enabled, `sveld` emits a `COMPONENT_API.json` file with schema and generator metadata plus the parsed
@@ -349,6 +436,19 @@ interface ComponentApiJson {
   };
   total: number;
   components: ComponentDocApi[];
+  // Present only when `documentExports` is enabled.
+  totalExports?: number;
+  exports?: EntryExport[];
+}
+
+interface EntryExport {
+  name: string;
+  kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
+  type?: string;
+  value?: string;
+  description?: string;
+  source?: string;
+  isTypeOnly: boolean;
 }
 
 interface SourceRange {
@@ -1361,9 +1461,11 @@ Omit the `slot-name` to type the default slot.
 
 #### Extra JSDoc tags before `@slot`
 
-Tags such as `@example`, `@deprecated`, `@see`, or `@since` that appear after the prose description and before the `@slot` / `@snippet` line are copied into generated `.d.ts` files. The emitted JSDoc above each slot's snippet prop (and the traditional `SlotDefs` shape) lists the description, then those tags in source order. The same entries appear in JSON as `tags: [{ "name", "body" }, ...]`.
+Tags such as `@example`, `@see`, or `@since` that appear after the prose description and before the `@slot` / `@snippet` line are copied into generated `.d.ts` files. The emitted JSDoc above each slot's snippet prop (and the traditional `SlotDefs` shape) lists the description, then those tags in source order. The same entries appear in JSON as `tags: [{ "name", "body" }, ...]`.
+
+`@deprecated` is handled separately from passthrough slot tags. It fills the slot's `deprecated` JSON field, adds a Markdown badge, and emits `@deprecated` in the `.d.ts`. See [@deprecated](#deprecated).
 
-Put `@slot` / `@snippet` last in the block (description, optional extra tags, slot tag). Tags after `@slot` / `@snippet` in the same comment are not tied to that slot. Unknown tag names pass through as-is. Markdown docs do not render slot descriptions or these tags yet; use TypeScript hover or JSON.
+Put `@slot` / `@snippet` last in the block (description, optional extra tags, slot tag). Tags after `@slot` / `@snippet` in the same comment are not tied to that slot. Unknown tag names pass through as-is. Markdown docs render the description and these tags in the slot's **Description** column (newlines and tag boundaries become `<br />`), alongside TypeScript hover and JSON.
 
 **Example (default slot with `@example` and `@deprecated`):**
 
@@ -1803,6 +1905,53 @@ export default class Component extends SvelteComponentTyped<
 
 Any free-text prose after the tags is attached to the event description, not to a property doc.
 
+### `@deprecated`
+
+Add `@deprecated` to a prop, event, slot, or exported accessor. An optional message after the tag can explain why or name a replacement.
+
+```svelte
+<script>
+  /**
+   * The visible label.
+   * @deprecated Use the `text` prop instead.
+   */
+  export let label = "";
+
+  /**
+   * Programmatically focus the field.
+   * @deprecated Focus the underlying element directly.
+   */
+  export function focus() {}
+
+  /**
+   * @event {{ value: string }} change
+   * @deprecated Listen for the native `input` event instead.
+   */
+
+  /**
+   * Badge content rendered next to the label.
+   * @deprecated Render the badge inline instead.
+   * @slot {{ count: number }} badge
+   */
+</script>
+```
+
+For slots, put `@deprecated` before the `@slot` / `@snippet` line, alongside the description and any other [extra tags](#extra-jsdoc-tags-before-slot). For events, put it after the `@event` line.
+
+Generated `.d.ts` files include an `@deprecated` JSDoc line so editors strike the symbol through. JSON adds a `deprecated` field (the message string, or `true` when the tag has no message). Markdown strikes through the name and adds a **Deprecated** badge with the message when present.
+
+```ts
+/**
+ * The visible label.
+ * @deprecated Use the `text` prop instead.
+ */
+label?: string;
+```
+
+```json
+{ "name": "label", "deprecated": "Use the `text` prop instead." }
+```
+
 ### Context API
 
 `sveld` generates TypeScript definitions for Svelte's `setContext`/`getContext` by extracting types from JSDoc on context values.
@@ -1812,10 +1961,27 @@ Any free-text prose after the tags is attached to the event description, not to
 When you call `setContext` in a component, `sveld`:
 
 1. Detects the `setContext` call
-2. Extracts the context key (must be a string literal)
+2. Resolves the context key (see [Supported context keys](#supported-context-keys))
 3. Finds JSDoc `@type` annotations on the variables being passed
 4. Generates a TypeScript type export for the context
 
+#### Supported context keys
+
+The key becomes the `{PascalCase}Context` type name. `sveld` can resolve:
+
+| Key form | Example | Generated type |
+| --- | --- | --- |
+| String literal | `setContext("simple-modal", …)` | `SimpleModalContext` |
+| Static template literal | `` setContext(`simple-modal`, …) `` | `SimpleModalContext` |
+| `const`-bound string | `const KEY = "simple-modal";`<br>`setContext(KEY, …)` | `SimpleModalContext` |
+| `Symbol()` / `Symbol.for()` | `setContext(Symbol("tabs"), …)` | `TabsContext` |
+
+`const` identifiers are followed up to 5 levels deep (`const A = "x"; const B = A;`). Only `const` bindings count. `let`, `var`, and props are skipped because they can change at runtime.
+
+Symbol keys take their name from the description: `Symbol("tabs")` and `Symbol.for("tabs")` both become `TabsContext`. For `const ModalKey = Symbol()` with no description, the binding name wins: `ModalKeyContext`.
+
+Anything else (dynamic identifiers, template interpolation, other function calls) logs a warning. No context type is generated.
+
 #### Example
 
 **Modal.svelte**

package/lib/ComponentParser.d.ts

@@ -1,3 +1,13 @@
+import type { SveldDiagnostic } from "./diagnostics";
+/** Structured JSDoc tag (e.g. `{ name: "since", body: "1.2.0" }`). */
+interface JsDocPassthroughTag {
+    name: string;
+    body: string;
+}
+/**
+ * From `@deprecated` JSDoc: a message string, or `true` when the tag has no message.
+ */
+export type DeprecatedValue = string | true;
 export interface SourcePosition {
     /** 1-based source line number */
     line: number;
@@ -18,6 +28,15 @@ export declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
 export declare function getParsedComponentTypeScriptMetadata(component: {
     [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
 }): ParsedComponentTypeScriptMetadata | undefined;
+/** One prop returned by the TypeScript checker during `resolveTypes`. */
+export interface ResolvedComponentProp {
+    name: string;
+    type: string;
+    isRequired: boolean;
+    description?: string;
+}
+/** Append checker-resolved props. Names the AST walker already found are left alone. */
+export declare function applyResolvedProps(component: ParsedComponent, resolved: ResolvedComponentProp[]): void;
 type SyntaxMode = "legacy" | "runes";
 type ScriptLanguage = "js" | "ts";
 type ComponentPropTypeSource = "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
@@ -104,6 +123,10 @@ interface ComponentProp {
     binding?: ComponentPropBinding;
     /** True when the prop is explicitly declared with Svelte 5 `$bindable()` */
     bindable?: true;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** Structured `@since` / `@example` tags, in source order. */
+    tags?: JsDocPassthroughTag[];
     /** Source range for the prop declaration, when available */
     source?: SourceRange;
 }
@@ -124,14 +147,13 @@ interface ComponentSlot {
     slot_props?: string;
     /** Description extracted from JSDoc `@slot` or `@snippet` tags */
     description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
     /**
      * JSDoc tags that appeared after the prose description and before `@slot` / `@snippet`
-     * (e.g. `@example`, `@deprecated`), in source order.
+     * (e.g. `@example`), in source order.
      */
-    tags?: Array<{
-        name: string;
-        body: string;
-    }>;
+    tags?: JsDocPassthroughTag[];
     /** Source range for the slot/snippet declaration or documentation tag, when available */
     source?: SourceRange;
 }
@@ -150,6 +172,10 @@ interface DispatchedEvent {
     detail?: string;
     /** Description extracted from JSDoc `@event` tags */
     description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** Structured `@since` / `@example` tags, in source order. */
+    tags?: JsDocPassthroughTag[];
     /** Source range for the dispatched event call or documentation tag, when available */
     source?: SourceRange;
 }
@@ -181,8 +207,12 @@ export interface SerializedForwardedEvent {
     element: string;
     /** Description extracted from JSDoc `@event` tags */
     description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
     /** The detail type if explicitly specified in `@event` tag */
     detail?: string;
+    /** Structured `@since` / `@example` tags, in source order. */
+    tags?: JsDocPassthroughTag[];
     /** Source range for the forwarded event declaration or documentation tag, when available */
     source?: SourceRange;
 }
@@ -335,6 +365,11 @@ export interface ParsedComponent {
     componentCommentSource?: SourceRange;
     /** Contexts created with `setContext` in the component */
     contexts?: ComponentContext[];
+    /**
+     * Type guesses from this parse (unknown props, `any` contexts, orphan `@event` tags).
+     * Set on every {@link ComponentParser.parseSvelteComponent} call.
+     */
+    diagnostics?: SveldDiagnostic[];
     /** Internal writer-only TypeScript metadata. Not serialized to JSON. */
     [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
 }
@@ -411,6 +446,12 @@ export default class ComponentParser {
     private scopeDeclarations;
     /** Active lexical scopes while walking the component AST */
     private readonly activeScopes;
+    /** Diagnostics for the parse in progress. */
+    private readonly diagnosticRecords;
+    /** File path tagged onto each diagnostic. */
+    private componentFilePath;
+    /** `@event` names from JSDoc, checked against dispatches at end of parse. */
+    private readonly jsDocEventNames;
     /** Cached array of source code lines split by newline for efficient line-based operations */
     private sourceLinesCache?;
     /** Cached 0-based source offsets for the start of each line */
@@ -420,6 +461,7 @@ export default class ComponentParser {
     private static getStaticAttributeValue;
     private static resolveScriptLanguage;
     private static assignValue;
+    private recordDiagnostic;
     private resolvePublicPropName;
     private trackPropLocalName;
     private getPropByLocalOrPublic;
@@ -478,7 +520,8 @@ export default class ComponentParser {
      *     { tag: "param", name: "value", type: "string" }
      *   ],
      *   returns: { tag: "returns", type: "void" },
-     *   additional: [{ tag: "since", name: "1.0.0" }],
+     *   additional: [{ tag: "see", name: "OtherType" }],
+     *   passthrough: [{ tag: "since", name: "1.0.0" }],
      *   description: "Main description text"
      * }
      * ```
@@ -602,6 +645,16 @@ export default class ComponentParser {
      * Returns the init node if found, or undefined.
      */
     private resolveLocalVarInitializer;
+    /**
+     * Look up the initializer for a local `const` by name.
+     *
+     * {@link resolveLocalVarInitializer} also walks `let`/`var`. This method does not.
+     * Props and mutable bindings can change at runtime, so they cannot be context keys.
+     *
+     * @param name - The variable name to look up
+     * @returns The initializer node for a matching `const` binding, or undefined
+     */
+    private resolveConstInitializer;
     /**
      * Look up JSDoc on a local variable declaration by name.
      */
@@ -960,12 +1013,32 @@ export default class ComponentParser {
      * ```
      */
     private parseContextValue;
+    /**
+     * Resolve a `setContext` key to the string used in `{PascalCase}Context`.
+     *
+     * Accepts string literals, static template literals, `const`-bound identifiers
+     * (up to 5 indirection levels, same as `@default`), and `Symbol()` /
+     * `Symbol.for()`. Description-less symbols fall back to the binding name.
+     *
+     * @param keyArg - The first argument of the `setContext` call
+     * @param depth - Current identifier-resolution depth (internal recursion guard)
+     * @returns The resolved key string, or `null` when the key cannot be resolved at parse time
+     */
+    private resolveContextKey;
+    /**
+     * Extracts the description string from a `Symbol(...)` or `Symbol.for(...)` call
+     * used as a context key.
+     *
+     * @param node - A CallExpression or NewExpression AST node
+     * @returns The symbol description (`""` when the symbol has no static description),
+     *   or `null` when the node is not a `Symbol()` / `Symbol.for()` call
+     */
+    private resolveSymbolKeyDescription;
     /**
      * Parses a `setContext` call expression to extract context information.
      *
-     * Extracts the context key from the first argument (must be a string literal
-     * or simple template literal) and the context value from the second argument.
-     * Only processes static keys - dynamic keys are skipped with a warning.
+     * Reads the context key from the first argument and the value from the second.
+     * Unresolved keys log a warning and are skipped.
      *
      * @param node - The AST node (should be a CallExpression)
      * @param _parent - The parent node (unused)
@@ -975,7 +1048,10 @@ export default class ComponentParser {
      * // Parses: setContext('modal', { open, close })
      * // Extracts: key = "modal", value = { open, close }
      *
-     * // Skips: setContext(dynamicKey, value) // key is not a literal
+     * // Parses: const KEY = "modal"; setContext(KEY, value) // resolves to "modal"
+     * // Parses: setContext(Symbol("modal"), value)          // resolves to "modal"
+     *
+     * // Diagnostic: setContext(dynamicKey, value) // key cannot be statically resolved
      * ```
      */
     private parseSetContextCall;

package/lib/bundle.d.ts

@@ -0,0 +1,140 @@
+import { type NormalizedPath } from "./brands";
+import { type ParsedComponent } from "./ComponentParser";
+import { type SveldDiagnostic } from "./diagnostics";
+import { type EntryExports } from "./parse-entry-exports";
+import { type ParsedExports } from "./parse-exports";
+export interface ComponentDocApi extends ParsedComponent {
+    filePath: NormalizedPath;
+    moduleName: string;
+}
+export type ComponentDocs = Map<string, ComponentDocApi>;
+/**
+ * A parse failure for a single component, captured so the rest of the run
+ * can continue. Surfaced via {@link GenerateBundleResult.errors}.
+ */
+export interface ComponentParseError {
+    filePath: string;
+    moduleName: string;
+    message: string;
+    stack?: string;
+}
+export interface GenerateBundleResult {
+    exports: ParsedExports;
+    /** Entry-barrel exports other than components. Empty when `documentExports` is off. */
+    entryExports: EntryExports;
+    components: ComponentDocs;
+    allComponentsForTypes: ComponentDocs;
+    /**
+     * Components that failed to parse. Empty unless `failFast` is disabled and
+     * one or more components threw during parsing.
+     */
+    errors: ComponentParseError[];
+    /** Unknown props, `any` contexts, and orphan `@event` tags across the bundle. */
+    diagnostics: SveldDiagnostic[];
+}
+export 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;
+}
+export declare function toGenerateBundleOptions(opts?: Pick<GenerateBundleOptions, "failFast" | "resolveTypes" | "documentExports">): GenerateBundleOptions;
+/** A function that resolves a (possibly relative) component path to an absolute path. */
+export type ResolveComponentFilePath = (filePath: string) => string;
+/** Options controlling how a single component parse failure is handled. */
+export interface ProcessComponentOptions {
+    /** Rethrow on parse failure instead of reporting it via `onParseError`. */
+    failFast?: boolean;
+    /** Invoked with a diagnostic when a component fails to parse (and `failFast` is off). */
+    onParseError?: (error: ComponentParseError) => void;
+}
+/**
+ * Discovered component sources for an entry point, before parsing.
+ *
+ * `exports` holds explicitly exported components (used for JSON/Markdown);
+ * `allComponents` additionally includes glob-discovered components (used for
+ * `.d.ts` generation). `resolveComponentFilePath` maps a component `source`
+ * to its absolute path on disk.
+ */
+export interface CollectedComponents {
+    exports: ParsedExports;
+    allComponents: ParsedExports;
+    rootDir: string;
+    resolveComponentFilePath: ResolveComponentFilePath;
+}
+/**
+ * Discovers component sources for an entry point without parsing them.
+ *
+ * Parses the entry's exports (when `input` is a file) and, when `glob` is set,
+ * augments the set with every `.svelte` file under the entry directory.
+ *
+ * @param documentExports - When `true`, log and continue if the entry file fails
+ *   the acorn component-export parse (TypeScript-only syntax is common).
+ */
+export declare function collectComponents(input: string, glob: boolean, documentExports?: boolean): CollectedComponents;
+/**
+ * Reads the given component file paths into a map of path -> contents.
+ *
+ * Failed reads are recorded as `null` (and logged) so callers can skip them
+ * gracefully rather than aborting the whole bundle.
+ */
+export declare function readFileMap(filePaths: Iterable<string>): Promise<Map<string, string | null>>;
+/**
+ * Parses a single component entry into its documentation API.
+ *
+ * Reads the component contents from `fileMap`, removes top-level styles for
+ * metadata parsing, and parses it to extract component metadata. Returns `null`
+ * for non-Svelte entries or files that could not be read.
+ *
+ * A component that throws while parsing is captured via `options.onParseError`
+ * (and `null` is returned) so callers can continue with the rest, unless
+ * `options.failFast` is set, in which case the error is rethrown.
+ *
+ * @param entry - Export entry tuple `[exportName, exportInfo]`
+ * @param entries - All sibling entries, used to resolve the module name
+ * @param fileMap - Map of resolved file paths to their contents
+ * @param resolveComponentFilePath - Resolves a component `source` to its absolute path
+ * @param options - Parse-failure handling (`failFast` / `onParseError`)
+ */
+export declare function processComponent([exportName, entry]: [string, ParsedExports[string]], entries: Array<[string, ParsedExports[string]]>, fileMap: Map<string, string | null>, resolveComponentFilePath: ResolveComponentFilePath, options?: ProcessComponentOptions): ComponentDocApi | null;
+/** Collects the resolved, absolute paths of all `.svelte` entries. */
+export declare function collectSvelteFilePaths(entriesList: Array<Array<[string, ParsedExports[string]]>>, resolveComponentFilePath: ResolveComponentFilePath): Set<string>;
+/** Reports collected component parse errors to stderr. No-op when empty. */
+export declare function reportParseErrors(errors: ComponentParseError[]): void;
+/**
+ * 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).
+ *
+ * A single component that fails to parse is captured as a diagnostic (see
+ * {@link GenerateBundleResult.errors}) so the remaining components still emit
+ * output. Pass `{ failFast: true }` to restore abort-on-first-error behavior.
+ *
+ * @param input - Entry point file or directory containing Svelte components
+ * @param glob - Whether to glob for all .svelte files in the directory
+ * @param options - Bundle options (e.g. `failFast`, `resolveTypes`, `documentExports`)
+ * @returns Bundle result containing exports, entryExports, components, allComponentsForTypes, and errors
+ *
+ * @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);
+ *
+ * // Abort on the first parse failure:
+ * const result = await generateBundle("./src", true, { failFast: true });
+ * ```
+ */
+export declare function generateBundle(input: string, glob: boolean, options?: GenerateBundleOptions): Promise<GenerateBundleResult>;

package/lib/cli.d.ts

@@ -1,5 +1,13 @@
+import { type PluginSveldOptions } from "./plugin";
+/** CLI options layered on top of the shared plugin options. */
+interface CliOptions extends PluginSveldOptions {
+    /** Set exit code 1 when diagnostics are present. */
+    strict?: boolean;
+}
+export declare function parseCliOptions(argv: string[]): CliOptions;
 /**
- * CLI entry point: parse flags, run Rollup, generate docs, write outputs.
+ * CLI entry point: parse flags, load any config file, run Rollup, generate
+ * docs, write outputs.
  *
  * @example
  * ```ts
@@ -8,3 +16,4 @@
  * ```
  */
 export declare function cli(process: NodeJS.Process): Promise<void>;
+export {};

package/lib/diagnostics.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Why sveld could not pin a type during parsing.
+ *
+ * - `prop-unknown-type`: prop `typeSource` is `"unknown"`.
+ * - `context-any-type`: `setContext` value inferred as `any`.
+ * - `event-no-source`: `@event` with no dispatch, forward, or callback prop.
+ */
+export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "event-no-source";
+/**
+ * One place sveld had to guess a type instead of inferring it.
+ */
+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;
+}
+/**
+ * Drop duplicates (same component, kind, and name). Each file is parsed twice
+ * when building exports and `.d.ts`, so without this the CLI summary doubles.
+ */
+export declare function dedupeDiagnostics(diagnostics: SveldDiagnostic[]): SveldDiagnostic[];
+/**
+ * Group diagnostics by kind and component for CLI output.
+ */
+export declare function formatDiagnosticsSummary(diagnostics: SveldDiagnostic[]): string;

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { default as ComponentParser, type SerializedComponentEvent } from "./ComponentParser";
 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";