sveld 0.33.0 → 0.34.0

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/plugin.d.ts

@@ -1,10 +1,11 @@
 import { type GenerateBundleOptions, type GenerateBundleResult } from "./bundle";
-import { type WriteJsonOptions } from "./writer/writer-json";
-import { type WriteMarkdownOptions } from "./writer/writer-markdown";
-import { type WriteTsDefinitionsOptions } from "./writer/writer-ts-definitions";
+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"> {
+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.
@@ -19,6 +20,12 @@ export interface PluginSveldOptions extends Pick<GenerateBundleOptions, "resolve
     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

package/lib/resolve-types.d.ts

@@ -1,9 +1,21 @@
 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.
@@ -21,9 +33,20 @@ export declare class TypeResolver {
     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/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/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/package.json

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