sveld 0.33.0 → 0.34.1

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,109 @@ 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.
+
+#### Type inference diagnostics
+
+`sveld` collects unresolved-type diagnostics on every run: props that fall back to `any`, context values typed as `any`, `@event` tags with no dispatch or callback, and (when `checkExamples` is enabled) `example-compile-error`. They are always returned from the programmatic `sveld()` API in `SveldResult.diagnostics`.
+
+With `reportDiagnostics` or `strict`, the grouped summary looks like this:
+
+```
+sveld: 4 unresolved types found.
+
+Props without inferred types (1):
+  ./icons/Add.svelte
+    - Prop "title" type could not be inferred; falling back to "any".
+
+Context values typed as `any` (1):
+  ./ThemeProvider.svelte
+    - Context "theme" variable "themeStore" has no type annotation; defaulted to "any".
+
+@event tags with no dispatch or callback (2):
+  ./Modal.svelte
+    - @event "open" has no matching dispatch or callback prop.
+    - @event "close" has no matching dispatch or callback prop.
+```
+
+When `checkExamples` is also enabled, `@example` compile failures appear as a fourth group:
+
+```
+@example blocks that failed to compile (1):
+  ./Component.svelte
+    - Line 1: Cannot find name 'formatValue'.
+```
+
+By default, nothing is printed. Opt in when you are working on types or want CI output:
+
+```ts
+await sveld({ json: true, reportDiagnostics: true });
+```
+
+Use `strict: true` (or `--strict`) to exit with code `1` when diagnostics exist. `strict` implies `reportDiagnostics`, so CI always shows why the run failed.
+
+```ts
+await sveld({ json: true, strict: true });
+```
+
+CLI equivalent:
+
+```sh
+npx sveld --json --report-diagnostics
+npx sveld --json --strict
+```
+
+`--check` is separate: it diffs `COMPONENT_API.json` for API drift and semver classification, not inference warnings.
+
 ## Usage
 
 ### Installation
@@ -277,6 +381,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()`.
@@ -287,7 +417,7 @@ If no `input` is specified, `sveld` will infer the entry point based on the `pac
 import { sveld } from "sveld";
 import pkg from "./package.json" with { type: "json" };
 
-sveld({
+const { diagnostics } = await sveld({
   input: "./src/index.js",
   glob: true,
   markdown: true,
@@ -307,6 +437,8 @@ sveld({
 });
 ```
 
+`diagnostics` is always populated; printing is opt-in via `reportDiagnostics` or `strict` (see [Type inference diagnostics](#type-inference-diagnostics)).
+
 #### `jsonOptions.outDir`
 
 With `json: true`, `sveld` writes `COMPONENT_API.json` at the project root. The file documents all components.
@@ -381,6 +513,11 @@ 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).
+- **`reportDiagnostics`** (boolean, optional, default: `false`): Print unresolved-type diagnostics to stderr (CLI) or `console.warn` (programmatic API). Also available as `--report-diagnostics`. See [Type inference diagnostics](#type-inference-diagnostics).
+- **`strict`** (boolean, optional, default: `false`): Exit with code `1` when diagnostics exist. Implies `reportDiagnostics`. Also available as `--strict`. See [Type inference diagnostics](#type-inference-diagnostics).
 
 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

@@ -1,8 +1,17 @@
 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. */
+    /** Print unresolved-type diagnostics to stderr. */
+    reportDiagnostics?: boolean;
+    /** Set exit code 1 when diagnostics are present. Implies `reportDiagnostics`. */
     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";