svelte-docsmith 0.14.0 → 0.16.0

package/README.md

@@ -24,8 +24,11 @@ live table of contents. No per-page wiring, no content collection to configure.
 > breaking changes ride a major.
 >
 > **What stays experimental.** Versioning: `DocsVersions`, `currentOnly`, the
-> archive marker, and the `archive-version` command. They may still change in a
-> minor until authors have used them for real.
+> archive marker, and the `archive-version` command. Generated props tables:
+> `?props` imports and `PropsTable`'s `of`. The MCP server: `mcpHandler` and the
+> `mcp` config field. Agent markdown: the props tables and example code written
+> into `llms-full.txt` and `.md` pages. They may still change in a minor until
+> authors have used them for real.
 
 ## Install
 
@@ -170,6 +173,35 @@ plugin you already added:
 </LiveExample>
 ```
 
+To type the `?source` import, reference the package's client types once in
+`src/app.d.ts`:
+
+```ts
+/// <reference types="svelte-docsmith/client" />
+```
+
+## Props tables from your types
+
+`PropsTable` can read a component's API straight from its typed `$props()`, so
+the reference can't drift from the code either. Import the component with
+`?props` and pass it to `of`:
+
+```svelte
+<script>
+	import { PropsTable } from 'svelte-docsmith';
+	import buttonProps from '#lib/button.svelte?props';
+</script>
+
+<PropsTable of={buttonProps} />
+```
+
+Types come from the TypeScript checker (an imported `ButtonVariant` alias shows
+its values), descriptions from JSDoc, defaults from the destructuring. Snippets,
+callbacks and `$bindable()` props all get rows, and inherited HTML attributes
+collapse to one line. It needs the optional peers `typescript` and `svelte2tsx`
+(`npm i -D typescript svelte2tsx`). Generated props tables are **experimental**:
+outside the 1.0 promise for now.
+
 ## Batteries included
 
 - **Search.** A ⌘K / Ctrl-K command palette over a build-time full-text index, no
@@ -214,18 +246,19 @@ override the tokens yourself.
 
 ## What's exported
 
-| Entry point                    | What it is                                                                                                                                                                                                                               |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `svelte-docsmith`              | Components (`DocsShell`, `Changelog`, landing sections, `LiveExample`, `Callout`, …), `defineConfig`, `createSearchEngine`, `generateSitemap` / `generateLlmsTxt` / `generateLlmsFullTxt` / `generateFeed`, `currentOnly`, and the types |
-| `svelte-docsmith/preprocess`   | `docsmith()`, the mdsvex/Shiki pipeline (Node, config time)                                                                                                                                                                              |
-| `svelte-docsmith/vite`         | `docsmith()`, the content / search / llms / changelog indexes and `?source` transform (Node, build)                                                                                                                                      |
-| `svelte-docsmith/content`      | `docs` and `versions`, the generated sidebar content index and version manifest                                                                                                                                                          |
-| `svelte-docsmith/search`       | `docs`, the generated full-text search index (lazy-load it)                                                                                                                                                                              |
-| `svelte-docsmith/llms`         | `docs`, the generated LLM content index (for `llms.txt` / `llms-full.txt` routes)                                                                                                                                                        |
-| `svelte-docsmith/changelog`    | `releases`, the generated changelog index (parsed from `CHANGELOG.md`)                                                                                                                                                                   |
-| `svelte-docsmith/mermaid`      | the Mermaid diagram component (lazy-loaded by the preprocessor when a mermaid fence is present)                                                                                                                                          |
-| `svelte-docsmith/theme.css`    | the base style contract                                                                                                                                                                                                                  |
-| `svelte-docsmith/themes/*.css` | the eleven theme presets                                                                                                                                                                                                                 |
+| Entry point                    | What it is                                                                                                                                                                                                                                             |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `svelte-docsmith`              | Components (`DocsShell`, `Changelog`, landing sections, `LiveExample`, `Callout`, …), `defineConfig`, `createSearchEngine`, `generateSitemap` / `generateLlmsTxt` / `generateLlmsFullTxt` / `generateFeed`, `mcpHandler`, `currentOnly`, and the types |
+| `svelte-docsmith/preprocess`   | `docsmith()`, the mdsvex/Shiki pipeline (Node, config time)                                                                                                                                                                                            |
+| `svelte-docsmith/vite`         | `docsmith()`, the content / search / llms / changelog indexes and `?source` / `?props` transforms (Node, build)                                                                                                                                        |
+| `svelte-docsmith/content`      | `docs` and `versions`, the generated sidebar content index and version manifest                                                                                                                                                                        |
+| `svelte-docsmith/search`       | `docs`, the generated full-text search index (lazy-load it)                                                                                                                                                                                            |
+| `svelte-docsmith/llms`         | `docs`, the generated agent markdown index (for `llms.txt` / `llms-full.txt` routes)                                                                                                                                                                   |
+| `svelte-docsmith/changelog`    | `releases`, the generated changelog index (parsed from `CHANGELOG.md`)                                                                                                                                                                                 |
+| `svelte-docsmith/mermaid`      | the Mermaid diagram component (lazy-loaded by the preprocessor when a mermaid fence is present)                                                                                                                                                        |
+| `svelte-docsmith/client`       | ambient types for `?source` and `?props` imports (reference it from `src/app.d.ts`)                                                                                                                                                                    |
+| `svelte-docsmith/theme.css`    | the base style contract                                                                                                                                                                                                                                |
+| `svelte-docsmith/themes/*.css` | the eleven theme presets                                                                                                                                                                                                                               |
 
 The package also ships a CLI binary: `npx svelte-docsmith archive-version <id>`
 freezes the current docs into a versioned archive.

package/dist/buildtime/markdown-source.d.ts

@@ -27,6 +27,17 @@ export declare function splitFrontmatter(source: string): MarkdownSource;
 export declare function withFrontmatter(source: string, transform: (frontmatter: string) => string): string;
 /** Apply `transform` to a page's prose lines, leaving fenced code untouched. */
 export declare function outsideCodeFences(text: string, transform: (line: string) => string): string;
+/**
+ * Apply `transform` to each run of consecutive prose lines, leaving fenced code
+ * and its markers untouched. For rewrites that span lines, such as a component
+ * tag with children, which {@link outsideCodeFences} would see a line at a time.
+ *
+ * With `setupBlocks`, each top-level `<script>`/`<style>` block stays whole
+ * inside one run, even when its code has a fence-like line.
+ */
+export declare function outsideCodeFenceRuns(text: string, transform: (prose: string) => string, options?: {
+    setupBlocks?: boolean;
+}): string;
 /** A page's prose lines, in order, with fenced code and its markers dropped. */
 export declare function proseLines(text: string): Generator<string>;
 /**

package/dist/buildtime/markdown-source.js

@@ -23,6 +23,8 @@
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
 /** An opening or closing code fence, indented anywhere on its line. */
 const FENCE = /^\s*(`{3,}|~{3,})/;
+/** The open tag of a `<script>` or `<style>` block, starting a line as HTML may. */
+const SETUP_BLOCK_OPEN = /^ {0,3}<(script|style)(?=[\s>]|$)/i;
 /** Split a page into its frontmatter and its body. */
 export function splitFrontmatter(source) {
     const match = FRONTMATTER.exec(source);
@@ -51,10 +53,20 @@ export function withFrontmatter(source, transform) {
  *
  * Returns a predicate that consumes the page's lines in order and answers
  * whether each one is prose. Fence markers themselves are not.
+ *
+ * With `setupBlocks`, a `<script>` or `<style>` block starting a prose line is
+ * prose through its closing tag, as CommonMark reads such an HTML block, so a
+ * fence-like line in its code (a ``` in a template literal) opens nothing.
  */
-function fenceScanner() {
+function fenceScanner({ setupBlocks = false } = {}) {
     let open;
+    let setupClose;
     return (line) => {
+        if (setupClose) {
+            if (setupClose.test(line))
+                setupClose = undefined;
+            return true;
+        }
         const match = FENCE.exec(line);
         if (open) {
             const closes = match &&
@@ -69,6 +81,12 @@ function fenceScanner() {
             open = match[1];
             return false;
         }
+        const setup = setupBlocks ? SETUP_BLOCK_OPEN.exec(line) : null;
+        if (setup) {
+            const close = new RegExp(`</${setup[1]}>`, 'i');
+            if (!close.test(line.slice(setup[0].length)))
+                setupClose = close;
+        }
         return true;
     };
 }
@@ -80,6 +98,35 @@ export function outsideCodeFences(text, transform) {
         .map((line) => (isProse(line) ? transform(line) : line))
         .join('\n');
 }
+/**
+ * Apply `transform` to each run of consecutive prose lines, leaving fenced code
+ * and its markers untouched. For rewrites that span lines, such as a component
+ * tag with children, which {@link outsideCodeFences} would see a line at a time.
+ *
+ * With `setupBlocks`, each top-level `<script>`/`<style>` block stays whole
+ * inside one run, even when its code has a fence-like line.
+ */
+export function outsideCodeFenceRuns(text, transform, options = {}) {
+    const isProse = fenceScanner(options);
+    const out = [];
+    let run = [];
+    const flush = () => {
+        if (run.length)
+            out.push(transform(run.join('\n')));
+        run = [];
+    };
+    for (const line of text.split('\n')) {
+        if (isProse(line)) {
+            run.push(line);
+        }
+        else {
+            flush();
+            out.push(line);
+        }
+    }
+    flush();
+    return out.join('\n');
+}
 /** A page's prose lines, in order, with fenced code and its markers dropped. */
 export function* proseLines(text) {
     const isProse = fenceScanner();

package/dist/buildtime/paths.d.ts

@@ -10,3 +10,8 @@ export declare function urlFor(routesDir: string, dir: string): string;
  * base of `/docs`.
  */
 export declare function docsBaseFrom(routesDir: string, contentDir: string): string;
+/**
+ * A file's path relative to the app's working directory, with `/` separators:
+ * the path an author would type, for "Edit this page" links and error messages.
+ */
+export declare function relativeToCwd(file: string): string;

package/dist/buildtime/paths.js

@@ -21,3 +21,10 @@ export function urlFor(routesDir, dir) {
 export function docsBaseFrom(routesDir, contentDir) {
     return urlFor(routesDir, contentDir);
 }
+/**
+ * A file's path relative to the app's working directory, with `/` separators:
+ * the path an author would type, for "Edit this page" links and error messages.
+ */
+export function relativeToCwd(file) {
+    return path.relative(process.cwd(), file).split(path.sep).join('/');
+}

package/dist/buildtime/props/extract.d.ts

@@ -0,0 +1,25 @@
+import type { ExtractedProps } from '../../core/extracted-props.js';
+export interface ExtractResult {
+    /** What `<PropsTable of={…}>` renders: descriptions as inline HTML. */
+    props: ExtractedProps;
+    /**
+     * The same props with descriptions and deprecation notes as the JSDoc's own
+     * markdown, for agent markdown.
+     */
+    markdown: ExtractedProps;
+    warnings: string[];
+    /** Files whose changes should re-extract this component. */
+    watchFiles: string[];
+}
+export interface PropsExtractorOptions {
+    /** Project root: where `tsconfig.json` is looked up. */
+    root: string;
+    /** tsconfig used to read prop types. Default: the root's `tsconfig.json`. */
+    tsconfig?: string;
+}
+export interface PropsExtractor {
+    extract(file: string): Promise<ExtractResult>;
+}
+export declare function createPropsExtractor(options: PropsExtractorOptions): PropsExtractor;
+/** `file-tree-item.svelte` → `FileTreeItem`. */
+export declare function componentName(file: string): string;

package/dist/buildtime/props/extract.js

@@ -0,0 +1,169 @@
+/**
+ * Props extraction for props imports (`Component.svelte?props`): merges what
+ * the source says (./parse.ts: destructured names, defaults, `$bindable()`)
+ * with what TypeScript says (./typescript.ts: types, optionality, JSDoc) into
+ * the `ExtractedProps` that `<PropsTable of={…}>` renders.
+ *
+ * Extraction never throws over one component. Anything it can't read becomes a
+ * warning naming the file, and the table shows what was found: untyped props
+ * by name only, a missing TypeScript install as names and defaults.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { marked } from 'marked';
+import { VERSION } from 'svelte/compiler';
+import { parseComponent } from './parse.js';
+import { createPropsTypeChecker, inNodeModules, loadPeers, mtimeOf, MISSING_PEERS } from './typescript.js';
+export function createPropsExtractor(options) {
+    let checker;
+    const getChecker = () => (checker ??= loadPeers().then((peers) => peers &&
+        createPropsTypeChecker(peers, {
+            ...options,
+            svelteVersion: VERSION
+        })));
+    // Props imports load concurrently (a page with five tables asks for five at
+    // once). Collect the requests made in the same tick and read them against
+    // one TypeScript program instead of rebuilding it per component.
+    let batch = [];
+    const flush = async () => {
+        const items = batch;
+        batch = [];
+        let results;
+        try {
+            const tsChecker = await getChecker();
+            results = tsChecker
+                ? tsChecker.read(items.map((item) => item.file))
+                : items.map(() => 'missing-peers');
+        }
+        catch (error) {
+            // Setting TypeScript up failed (a broken tsconfig, say). Report it on
+            // every waiting import rather than leaving them pending, and try again
+            // from scratch next time.
+            checker = undefined;
+            const failure = error instanceof Error ? error : new Error(String(error));
+            results = items.map(() => failure);
+        }
+        items.forEach((item, i) => item.done(results[i]));
+    };
+    const readTyped = (file) => new Promise((done) => {
+        if (batch.push({ file, done }) === 1)
+            setTimeout(flush, 0);
+    });
+    // Results stay valid until one of the files they were read from changes.
+    // The client and server builds both import every props module, so the
+    // second build is served from here.
+    const cache = new Map();
+    const stamp = mtimeOf;
+    return {
+        async extract(file) {
+            const cached = cache.get(file);
+            if (cached && cached.stamps.every(([f, time]) => stamp(f) === time))
+                return cached.result;
+            const result = await extractFresh(file);
+            cache.set(file, { stamps: result.watchFiles.map((f) => [f, stamp(f)]), result });
+            return result;
+        }
+    };
+    async function extractFresh(file) {
+        const warnings = [];
+        const rel = path.relative(options.root, file) || file;
+        const warn = (message) => warnings.push(`${rel}: ${message}`);
+        const extracted = {
+            name: componentName(file),
+            typeParameters: [],
+            props: [],
+            inherited: []
+        };
+        if (inNodeModules(file)) {
+            warn('reading a published package file. Published components usually have their ' +
+                'types stripped, so point the props import at the source instead.');
+        }
+        // Rows are built once, with JSDoc as markdown; the rendered table's copy
+        // differs only in turning that markdown into HTML.
+        const done = (watchFiles) => ({
+            props: {
+                ...extracted,
+                props: extracted.props.map((prop) => clean({
+                    ...prop,
+                    deprecated: prop.deprecated === undefined ? undefined : renderMarkdown(prop.deprecated),
+                    description: prop.description ? renderMarkdown(prop.description) : undefined
+                }))
+            },
+            markdown: extracted,
+            warnings,
+            watchFiles
+        });
+        let parsed;
+        try {
+            parsed = parseComponent(fs.readFileSync(file, 'utf-8'), file);
+        }
+        catch (error) {
+            warn(`could not parse the component (${message(error)}).`);
+            return done([file]);
+        }
+        extracted.typeParameters = parsed.typeParameters;
+        if (!parsed.hasProps) {
+            warn('no `$props()` found, so the props table is empty.');
+            return done([file]);
+        }
+        let typed;
+        if (parsed.typed) {
+            const result = await readTyped(file);
+            if (result === 'missing-peers')
+                warn(MISSING_PEERS);
+            else if (result instanceof Error) {
+                warn(`could not read prop types (${result.message}). Showing names only.`);
+            }
+            else
+                typed = result;
+        }
+        else {
+            warn('`$props()` has no type annotation, so props show without types.');
+        }
+        const defaults = new Map(parsed.destructured.map((d) => [d.name, d]));
+        if (typed) {
+            for (const prop of typed.props) {
+                if (prop.internal)
+                    continue;
+                const destructured = defaults.get(prop.name);
+                const fallback = prop.defaultTag ?? destructured?.default;
+                extracted.props.push(clean({
+                    name: prop.name,
+                    type: prop.type,
+                    default: fallback,
+                    required: !prop.optional && fallback === undefined,
+                    bindable: destructured?.bindable ?? false,
+                    deprecated: prop.deprecated,
+                    description: prop.description
+                }));
+            }
+            extracted.inherited = typed.inherited;
+        }
+        else {
+            for (const d of parsed.destructured) {
+                extracted.props.push(clean({ name: d.name, default: d.default, required: false, bindable: d.bindable }));
+            }
+        }
+        return done([...new Set([file, ...(typed?.files ?? [])])]);
+    }
+}
+/** `file-tree-item.svelte` → `FileTreeItem`. */
+export function componentName(file) {
+    return path
+        .basename(file, '.svelte')
+        .split(/[^A-Za-z0-9]+/)
+        .filter(Boolean)
+        .map((word) => word[0].toUpperCase() + word.slice(1))
+        .join('');
+}
+function renderMarkdown(text) {
+    return marked.parse(text, { async: false, gfm: true })
+        .trim()
+        .replace(/^<p>([\s\S]*)<\/p>$/, (match, inner) => inner.includes('<p>') ? match : inner);
+}
+function clean(prop) {
+    return Object.fromEntries(Object.entries(prop).filter(([, value]) => value !== undefined));
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/buildtime/props/parse.d.ts

@@ -0,0 +1,17 @@
+export interface DestructuredProp {
+    name: string;
+    /** Source text of the default value. */
+    default?: string;
+    bindable: boolean;
+}
+export interface ParsedComponent {
+    /** Whether the instance script calls `$props()` at all. */
+    hasProps: boolean;
+    /** Whether the `$props()` declaration carries a type annotation. */
+    typed: boolean;
+    /** Destructured props, in source order. Empty for `let props = $props()`. */
+    destructured: DestructuredProp[];
+    /** Type parameter names from `generics="…"`. */
+    typeParameters: string[];
+}
+export declare function parseComponent(code: string, filename: string): ParsedComponent;

package/dist/buildtime/props/parse.js

@@ -0,0 +1,108 @@
+/**
+ * The syntax half of props extraction: what can be read from a component's
+ * source without TypeScript. That is the `$props()` destructuring (names,
+ * default values, `$bindable()`) and the `generics`
+ * attribute. Types, optionality and descriptions come from ./typescript.ts.
+ */
+import { parse } from 'svelte/compiler';
+import { splitTopLevel } from '../../utils/type-text.js';
+export function parseComponent(code, filename) {
+    const ast = parse(code, { modern: true, filename });
+    const typeParameters = genericsOf(ast.instance?.attributes ?? [], code);
+    const empty = {
+        hasProps: false,
+        typed: false,
+        destructured: [],
+        typeParameters
+    };
+    if (!ast.instance)
+        return empty;
+    const declarator = findPropsDeclarator(ast.instance.content);
+    if (!declarator)
+        return empty;
+    const id = declarator.id;
+    const typed = Boolean(id.typeAnnotation);
+    if (id.type !== 'ObjectPattern')
+        return { ...empty, hasProps: true, typed };
+    const destructured = [];
+    for (const property of id.properties) {
+        // `...rest` is read from the type instead (inherited attributes).
+        if (property.type === 'RestElement')
+            continue;
+        const name = keyName(property.key);
+        if (name === undefined)
+            continue;
+        destructured.push({ name, ...defaultOf(property.value, code) });
+    }
+    return { hasProps: true, typed, destructured, typeParameters };
+}
+function findPropsDeclarator(node) {
+    let found;
+    walk(node, (n) => {
+        if (found)
+            return false;
+        if (n.type === 'VariableDeclarator' && isCall(n.init, '$props')) {
+            found = n;
+            return false;
+        }
+        return true;
+    });
+    return found;
+}
+function walk(node, visit) {
+    if (!visit(node))
+        return;
+    for (const value of Object.values(node)) {
+        if (Array.isArray(value)) {
+            for (const child of value)
+                if (isNode(child))
+                    walk(child, visit);
+        }
+        else if (isNode(value)) {
+            walk(value, visit);
+        }
+    }
+}
+function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.type === 'string';
+}
+function isCall(node, callee) {
+    if (!node || node.type !== 'CallExpression')
+        return false;
+    const fn = node.callee;
+    return fn.type === 'Identifier' && fn.name === callee;
+}
+function keyName(key) {
+    if (key.type === 'Identifier')
+        return key.name;
+    if (key.type === 'Literal' && typeof key.value === 'string')
+        return key.value;
+    return undefined;
+}
+function defaultOf(value, code) {
+    if (value.type !== 'AssignmentPattern')
+        return { bindable: false };
+    const right = value.right;
+    if (isCall(right, '$bindable')) {
+        const [fallback] = right.arguments;
+        return { bindable: true, default: fallback ? source(fallback, code) : undefined };
+    }
+    return { bindable: false, default: source(right, code) };
+}
+function source(node, code) {
+    return code.slice(node.start, node.end);
+}
+/** `generics="T extends string, U = number"` → `['T', 'U']`. */
+function genericsOf(attributes, code) {
+    for (const attr of attributes) {
+        if (attr.type !== 'Attribute' || attr.name !== 'generics')
+            continue;
+        const [text] = attr.value;
+        if (!text || text.type !== 'Text')
+            return [];
+        return splitTopLevel(String(text.data ?? source(text, code)), ',')
+            .map((param) => /^\s*([A-Za-z_$][\w$]*)/.exec(param)?.[1])
+            .filter((name) => Boolean(name));
+    }
+    return [];
+}

package/dist/buildtime/props/typescript.d.ts

@@ -0,0 +1,54 @@
+import type TS from 'typescript';
+type Ts = typeof TS;
+type Svelte2tsx = typeof import('svelte2tsx').svelte2tsx;
+export interface TypedProp {
+    name: string;
+    type: string;
+    optional: boolean;
+    /** JSDoc description, as markdown. */
+    description?: string;
+    /** `@deprecated` text (`''` when the tag is bare). */
+    deprecated?: string;
+    /** `@default` text, which wins over the destructured default. */
+    defaultTag?: string;
+    /** Tagged `@internal`: left out of the table. */
+    internal: boolean;
+}
+export interface TypedInheritedAttributes {
+    kind: 'element' | 'type';
+    label: string;
+}
+export interface TypedComponent {
+    props: TypedProp[];
+    inherited: TypedInheritedAttributes[];
+    /** Project files the component imports, directly or not, for HMR. */
+    files: string[];
+}
+export interface PropsTypeChecker {
+    /**
+     * Read several components against one program: building the program is the
+     * expensive part, so concurrent props imports share it. Each entry is
+     * `undefined` when that component has no typed `$props()`, or the error it
+     * threw.
+     */
+    read(files: string[]): (TypedComponent | undefined | Error)[];
+}
+export declare const MISSING_PEERS: string;
+/** The optional peer dependencies, plus svelte2tsx's ambient shims. */
+export interface Peers {
+    ts: Ts;
+    svelte2tsx: Svelte2tsx;
+    shims: string[];
+}
+/** Load the optional peers once per process; `undefined` when not installed. */
+export declare function loadPeers(): Promise<Peers | undefined>;
+/** A file's modification time, or `-1` when it can't be read. */
+export declare function mtimeOf(file: string): number;
+/** Whether a path lies inside a `node_modules` directory, on any platform. */
+export declare function inNodeModules(file: string): boolean;
+export declare function createPropsTypeChecker({ ts, svelte2tsx, shims }: Peers, options: {
+    root: string;
+    tsconfig?: string;
+    svelteVersion: string;
+}): PropsTypeChecker;
+export {};