sveld 0.33.0 → 0.34.0

package/README.md

@@ -123,6 +123,7 @@ export default class Button extends SvelteComponentTyped<
   - [Vite](#vite)
   - [Node.js](#nodejs)
   - [CLI](#cli)
+  - [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check)
   - [Config File](#config-file)
   - [Publishing to NPM](#publishing-to-npm)
 - [Available Options](#available-options)
@@ -202,6 +203,57 @@ Without `resolveTypes`, JSON lists no props. With it, each field shows up with `
 
 **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.
 
+#### Persistent parse cache (`cache`)
+
+By default, every component is re-parsed on every run. With `cache`, parsed output is written to disk and reused when the source file has not changed. That applies across runs, including CI on a fresh checkout.
+
+```ts
+await sveld({ json: true, cache: true });
+```
+
+`cache: true` writes to `node_modules/.cache/sveld/parse-cache.json`. Pass a string to use a different location, e.g. `cache: ".cache/sveld.json"`. Also available as `--cache` / `--cache=<path>` on the CLI.
+
+If a component [`@extendProps`](#extendprops) / [`@extends`](#extendprops) another file, it is re-parsed when that dependency changes, same as in [`watch`](#available-options) mode. Bumping the `sveld` or Svelte version clears the cache.
+
+#### Compile-checked `@example` blocks (`checkExamples`)
+
+`@example` blocks are just text. Rename a prop and the sample code can sit there broken for months. Set `checkExamples: true` to run plain TS/JS `@example` blocks through the TypeScript program. Broken examples show up as `example-compile-error` diagnostics.
+
+```ts
+await sveld({ json: true, checkExamples: true });
+```
+
+```svelte
+<script>
+  /**
+   * Formats a value.
+   * @param {string} value
+   * @returns {string}
+   * @example
+   * ```js
+   * formatValue("ok");
+   * ```
+   */
+  export function formatValue(value) {
+    return value;
+  }
+</script>
+```
+
+If `formatValue` is later renamed and the example is never updated, `checkExamples` reports it:
+
+```
+@example blocks that failed to compile (1):
+  ./Component.svelte
+    - Line 1: Cannot find name 'formatValue'.
+```
+
+Plain TS/JS only. Examples fenced as `svelte` or `html`, or bare markup like `<Button />`, are skipped. Checking those needs `svelte2tsx` or similar, and sveld stays AST-only.
+
+The check is narrow on purpose. It catches renamed or removed symbols and wrong argument counts. It is not full type checking and never pulls in types sveld cannot see.
+
+Needs `typescript` and a `tsconfig.json`, same as `resolveTypes`. Use `--strict` (or the `strict` option) to fail CI when an example breaks.
+
 ## Usage
 
 ### Installation
@@ -277,6 +329,32 @@ Generate documentation in JSON and/or Markdown formats using the following flags
 npx sveld --json --markdown
 ```
 
+### CI: API-drift checks (`--check`)
+
+`--check` diffs the parsed component API against a committed `COMPONENT_API.json` snapshot, assigns a semver bump to each change, and exits `1` when it finds a breaking change.
+
+1. Generate and commit the snapshot once: `npx sveld --json`, then commit `COMPONENT_API.json`.
+2. Add `npx sveld --check` to CI:
+
+```sh
+npx sveld --check
+```
+
+```
+sveld --check: 2 API changes detected against "COMPONENT_API.json".
+Suggested semver bump: major.
+
+  Button
+    [BREAKING] prop "target" added (required)
+    [BREAKING] prop "href" removed
+```
+
+Removed props, events, or slots, and props that become required, are breaking (`major`). New optional props, new events, and widened union types are additive (`minor`). Changes to generics, `@restProps`, `@extends`, or context shapes are not classified further. If any of those changed, `--check` calls it breaking.
+
+`--check` does not write the snapshot. Run `sveld --json` (or `sveld --json --check`) and commit the file when you want to update it. If there is no snapshot yet, `--check` prints a notice and exits `0`.
+
+Use `--check=<path>` to diff against a snapshot at a custom location (defaults to `jsonOptions.outFile`, or `COMPONENT_API.json`).
+
 ### Node.js
 
 You can also call `sveld` from Node.js. The package is **ESM-only**; `require("sveld")` does not work. Use `import` or dynamic `import()`.
@@ -381,6 +459,9 @@ TypeScript definitions land in the `types` folder by default. Include that folde
 - **`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.
+- **`resolveTypes`** (boolean, optional, default: `false`): Load the TypeScript program to expand opaque imported whole-object `$props()` types into JSON. See [Opt-in semantic resolution](#opt-in-semantic-resolution-resolvetypes).
+- **`cache`** (boolean | string, optional, default: `false`): Write parsed component output to disk and skip re-parsing unchanged files on later runs. `true` uses `node_modules/.cache/sveld/parse-cache.json`; a string sets a custom path. Also available as `--cache` / `--cache=<path>`. See [Persistent parse cache](#persistent-parse-cache-cache).
+- **`checkExamples`** (boolean, optional, default: `false`): Run plain TS/JS `@example` blocks through the TypeScript program. Broken ones get an `example-compile-error` diagnostic. See [Compile-checked `@example` blocks](#compile-checked-example-blocks-checkexamples).
 
 By default, only TypeScript definitions are generated.
 

package/lib/ComponentParser.d.ts

@@ -88,7 +88,7 @@ interface ComponentPropParam {
  * its type, default value, description, and metadata about whether it's
  * required, reactive, or a function.
  */
-interface ComponentProp {
+export interface ComponentProp {
     /** The prop name as declared in the component */
     name: string;
     /** The declaration kind: "let" (required), "const" (optional with default), or "function" */
@@ -136,7 +136,7 @@ interface ComponentProp {
  * Represents a slot that can be used to pass content into the component.
  * Includes information about slot props, fallback content, and descriptions.
  */
-interface ComponentSlot {
+export interface ComponentSlot {
     /** The slot name (null or undefined for default slot) */
     name?: string | null;
     /** Whether this is the default slot */
@@ -416,6 +416,8 @@ export default class ComponentParser {
     private readonly typedefs;
     /** Component generic type parameters (null if no generics) */
     private generics;
+    /** @template tags in a @slot/@snippet block (no @extends), held until finalization. */
+    private deferredSlotBlockGenerics;
     /** Map of prop bindings (e.g., `bind:value`) keyed by prop name */
     private readonly bindings;
     /** Map of component contexts (created with `setContext`) keyed by context name */
@@ -1069,6 +1071,7 @@ export default class ComponentParser {
      * parser.parseSvelteComponent(source2, diagnostics2); // Fresh parse
      * ```
      */
+    private accumulateGeneric;
     cleanup(): void;
     /**
      * Pre-compiled regex for matching script blocks in Svelte components.

package/lib/bundle.d.ts

@@ -1,6 +1,7 @@
 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 {
@@ -45,8 +46,21 @@ export interface GenerateBundleOptions {
     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">): GenerateBundleOptions;
+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. */
@@ -55,6 +69,8 @@ export interface ProcessComponentOptions {
     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.

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

@@ -3,6 +3,13 @@ import { type PluginSveldOptions } from "./plugin";
 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;
 /**

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

@@ -4,8 +4,9 @@
  * - `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";
+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.
  */

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,7 +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";