sveld 0.32.8 → 0.34.0

package/lib/bundle.d.ts

@@ -0,0 +1,156 @@
+import { type NormalizedPath } from "./brands";
+import { type ParsedComponent } from "./ComponentParser";
+import { type SveldDiagnostic } from "./diagnostics";
+import { ParseCache } from "./parse-cache";
+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;
+    /**
+     * Cache parsed component output to disk. Unchanged files skip re-parsing on
+     * later runs. `true` uses `node_modules/.cache/sveld/parse-cache.json`; a
+     * string sets a custom path. Off by default.
+     */
+    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;
+}
+export declare function toGenerateBundleOptions(opts?: Pick<GenerateBundleOptions, "failFast" | "resolveTypes" | "documentExports" | "cache" | "checkExamples">): 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;
+    /** When set, reuse a component's previous parse if its content hash is unchanged. */
+    cache?: ParseCache;
+}
+/**
+ * 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/check.d.ts

@@ -0,0 +1,37 @@
+import type { ComponentDocs } from "./bundle";
+import type { EntryExports } from "./parse-entry-exports";
+import { type ComponentApiDocument } from "./writer/document-model";
+export type SemverBump = "major" | "minor" | "patch" | "none";
+/** One API diff between the committed snapshot and the current parse. */
+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;
+}
+/** Diffs two `COMPONENT_API.json` documents and assigns a semver bump to each change. */
+export declare function diffApiDocuments(previous: ComponentApiDocument, next: ComponentApiDocument): ApiChange[];
+export interface RunCheckOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+}
+/**
+ * Diffs the current component set against a committed `COMPONENT_API.json`
+ * snapshot and assigns a semver bump to each change. Returns
+ * `snapshotExists: false` when no snapshot file exists yet, so the first
+ * run does not fail CI.
+ */
+export declare function runCheck(components: ComponentDocs, snapshotFile: string, options?: RunCheckOptions): Promise<CheckResult>;
+/** Groups changes by component for CLI output. */
+export declare function formatCheckReport(result: CheckResult): string;

package/lib/cli.d.ts

@@ -1,5 +1,20 @@
+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;
+    /**
+     * 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;
+}
+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 +23,4 @@
  * ```
  */
 export declare function cli(process: NodeJS.Process): Promise<void>;
+export {};

package/lib/dependency-graph.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentDocApi, ComponentDocs, ResolveComponentFilePath } from "./bundle";
+/**
+ * Resolves a component's `@extendProps` / `@extends` target to an absolute path,
+ * or `null` when it doesn't point at a local `.svelte` file (e.g. it references
+ * an external package interface like `carbon-components-svelte`).
+ */
+export declare function resolveExtendsDependency(api: ComponentDocApi, componentPath: string): string | null;
+/**
+ * Builds a reverse-dependency map: `dependencyPath -> set of dependent paths`.
+ *
+ * A component is a dependent of `X` when it extends `X` via `@extendProps` /
+ * `@extends`. When `X` changes, every dependent must be re-parsed.
+ */
+export declare function buildReverseDeps(components: ComponentDocs, resolveComponentFilePath: ResolveComponentFilePath): Map<string, Set<string>>;
+/**
+ * Expands the set of changed paths to include every transitive dependent via
+ * the reverse-dependency map (e.g. editing `Button.svelte` also marks the
+ * `SecondaryButton.svelte` that `@extendProps`-es it).
+ */
+export declare function expandAffected(changed: Iterable<string>, reverseDeps: Map<string, Set<string>>): Set<string>;

package/lib/diagnostics.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ * - `example-compile-error`: an `@example` block failed to type-check (opt-in, `checkExamples`).
+ */
+export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "event-no-source" | "example-compile-error";
+/**
+ * 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/example-check.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedComponent } from "./ComponentParser";
+/**
+ * One `@example` block worth type-checking, reduced to what `resolve-types.ts`
+ * needs: a declaration for the documented symbol and the example body itself.
+ */
+export interface ExampleCheckSource {
+    /** Stable id for diagnostics, e.g. `"prop:variant"` or `"prop:variant#1"` for a second example. */
+    id: string;
+    /** Human-readable name shown in diagnostics, e.g. `"variant"` or `"variant (example 2)"`. */
+    name: string;
+    /** TypeScript type to bind the documented symbol to before running `code`. */
+    type: string;
+    /** The `@example` body, stripped of any surrounding code fence. */
+    code: string;
+}
+/**
+ * Collects every `@example` block sveld can type-check for a parsed component:
+ * plain TS/JS bodies on props, module exports, slots, and events. Svelte/HTML
+ * markup examples (most slot/event examples, many prop examples) are skipped.
+ * Checking those needs `svelte2tsx` or similar; sveld stays AST-only.
+ */
+export declare function collectExampleSources(component: ParsedComponent): ExampleCheckSource[];

package/lib/index.d.ts

@@ -1,5 +1,10 @@
 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";