poveste 0.19.1 → 0.21.0

package/README.md

@@ -5,9 +5,14 @@
 Poveste builds a browsable *book* of stories from your components, powered by
 [Vite](https://vite.dev). It is a drop-in fork of
 [histoire](https://github.com/histoire-dev/histoire), covering Vue, Nuxt, Svelte,
-SvelteKit and Quasar — the last of which histoire does not support. Solid and React
-are supported as renderers only: their stories render, and they have no controls
-panel.
+SvelteKit and Quasar — the last of which no released version of histoire includes — and
+Solid and React, whose stories render with no controls panel yet.
+
+In every one of those books, each story's **Docs** tab also shows a props, slots and
+events table read from its components' types: the ones a Vue or Svelte story imports, or
+the one a Solid or React story names in its `component` field. That needs `typescript` 6
+or earlier in the book, plus `svelte2tsx` in a Svelte book and `@types/react` in a React
+one.
 
 <img src="https://raw.githubusercontent.com/poveste-dev/poveste/main/screenshot.png" alt="A poveste book: the story list, a variant grid, and the controls panel" width="900">
 
@@ -20,11 +25,11 @@ pnpm i -D poveste @poveste/plugin-vue                          # Vue 3
 pnpm i -D poveste @poveste/plugin-svelte                       # Svelte 5 and SvelteKit
 pnpm i -D poveste @poveste/plugin-vue @poveste/plugin-nuxt     # Nuxt 4
 pnpm i -D poveste @poveste/plugin-vue @poveste/plugin-quasar   # Quasar
-pnpm i -D poveste @poveste/plugin-solid                        # Solid, renderer only
-pnpm i -D poveste @poveste/plugin-react                        # React 19, renderer only
+pnpm i -D poveste @poveste/plugin-solid                        # Solid, no controls yet
+pnpm i -D poveste @poveste/plugin-react                        # React 19, no controls yet
 ```
 
-> **Installed an older version than you expected?** For about a day after a release, pnpm installs the previous one with no error and no hint, and for a plugin that's new in that release, its empty `0.0.1` placeholder. That's pnpm's release-age cooldown, not a broken publish. `package.json` keeps the old `^x.y.z`, so waiting doesn't fix it: install again with `npm`, with `--config.minimum-release-age=0` (kebab-case: pnpm 12.4 ignores the camelCase spelling), or with exact versions.
+> **Installed an older version than you expected?** For about a day after a release, pnpm installs the previous one with no error, and for a plugin that's new in that release, its empty `0.0.1` placeholder. pnpm 11.5.3 added `(x.y.z is available)` after the version it installed; pnpm 12.14.0 said nothing. That's pnpm's release-age cooldown, not a broken publish. `package.json` keeps the old `^x.y.z`, so waiting doesn't fix it: install again with `npm`, with `--config.minimum-release-age=0` (kebab-case: pnpm 12.4.0 ignores the camelCase spelling, which 12.14.0 accepts), or with exact versions.
 
 Then create a `poveste.config.ts` in your project root. For a Vue project it is this:
 
@@ -57,7 +62,9 @@ Node `>=22.22.2` and Vite `^8.0.0`. See
 [supported versions](https://poveste.dev/guide/getting-started#supported-versions) for
 what proves each range.
 
-On Node 24, use 24.15 or later: Poveste's DOM dependency (jsdom) accepts `^22.22.2 || ^24.15.0 || >=26`.
+On Node 24, prefer 24.15 or later. Poveste's DOM dependency, jsdom, and three of its own dependencies declare `^22.22.2 || ^24.15.0 || >=26`. On 24.13.0 npm warns `EBADENGINE` for each of them and installs anyway, and a Vue book built there, but nothing tests Poveste on a Node 24 before 24.15.
+
+Auto-docs, the props, slots and events table in Vue, Nuxt, Quasar, Svelte, SvelteKit, Solid and React books, needs `typescript` 6 or earlier in the book: `npm i -D typescript@6`. A Svelte or SvelteKit book also needs `svelte2tsx`, and a React book `@types/react`. Without them, or with TypeScript 7, it turns itself off and says so once. See [`autoDocs`](https://poveste.dev/reference/config#autodocs).
 
 ## Links
 

package/dist/node/build.js

@@ -8,13 +8,14 @@ import { APP_PATH } from './alias.js';
 import { buildCounts, buildSummary, builtSomething, storyGuideUrl } from './build-counts.js';
 import { getSerializedStoryData } from './build-serialize.js';
 import { useCollectStories } from './collect/index.js';
+import { extractComponentDocs } from './docgen/build.js';
 import { useModuleLoader } from './load.js';
 import { createMarkdownFilesWatcher } from './markdown.js';
 import { BuildPluginApi } from './plugin.js';
 import { startPreview } from './preview.js';
 import { findAllStories } from './stories.js';
 import { chromeCssScopePlugin, entryCssMergerPlugin, userCssScopePlugin, } from './style-isolation/index.js';
-import { applyHeadTransform } from './util/head.js';
+import { applyHeadTransform, defaultDescription } from './util/head.js';
 import { wrapLogError } from './util/log.js';
 import { viteMode } from './util/vite-mode.js';
 import { getViteConfigWithPlugins } from './vite.js';
@@ -38,6 +39,12 @@ const APP_ONLY_VENDORS = [
     /[\\/]node_modules[\\/]shiki[\\/]/,
     /[\\/]node_modules[\\/]@shikijs[\\/]/,
 ];
+// Left to the bundler wherever they are installed, rather than sent to `vendor`.
+// `@poveste/controls` loads three controls lazily, and in a book installed from
+// npm `vendor` took them in, so every reader downloaded them before anything
+// rendered. The workspace book never showed it: linked source has no
+// `node_modules` in its path (#1343).
+const LEFT_TO_BUNDLER = ['@poveste/app', '@poveste/controls'];
 const PREFETCHED_MODULES = [
     'StoryView',
     'reactivity',
@@ -117,6 +124,7 @@ export async function build(ctx) {
             // Same wrapper the dev path uses for these exact calls (server.ts).
             await wrapLogError('destroyCollectStories', () => destroyCollectStories());
         }
+        ctx.componentDocs = await extractComponentDocs(ctx, server);
         const counts = buildCounts(ctx.storyFiles);
         const { viteConfig: buildViteConfigRaw } = await getViteConfigWithPlugins(false, ctx);
         const buildViteConfig = mergeViteConfig(buildViteConfigRaw, {
@@ -198,7 +206,7 @@ export async function build(ctx) {
                         if (id.replace(/^\0/, '').startsWith('vite/')) {
                             return 'app-runtime';
                         }
-                        if (!id.includes('@poveste/app') && id.includes('node_modules')) {
+                        if (!LEFT_TO_BUNDLER.some(name => id.includes(name)) && id.includes('node_modules')) {
                             if (APP_ONLY_VENDORS.some(test => test.test(id))) {
                                 return 'highlighter';
                             }
@@ -233,6 +241,10 @@ export async function build(ctx) {
                     // returns whatever the minifier left — `codegen-vue.spec.ts` fails
                     // on three cases with this on (#329).
                     minify: false,
+                    // CSS too, whatever a book's own config says: Vite's minifier strips the
+                    // comments story CSS is found by before it is wrapped in `@scope`. The
+                    // entry-css-merger minifies instead, after wrapping (#1441).
+                    cssMinify: false,
                     // Don't build in SSR mode
                     ssr: false,
                 });
@@ -242,7 +254,7 @@ export async function build(ctx) {
         const isolate = ctx.config.isolateStyles !== false;
         buildPlugins.push(userCssScopePlugin({ enabled: isolate }));
         buildPlugins.push(chromeCssScopePlugin({ enabled: isolate }));
-        buildPlugins.push(entryCssMergerPlugin({ isolateStyles: isolate }));
+        buildPlugins.push(entryCssMergerPlugin({ isolateStyles: isolate, minify: true }));
         for (const cb of changeViteConfigCallbacks) {
             await cb(buildViteConfig);
         }
@@ -271,13 +283,19 @@ export async function build(ctx) {
         let indexHtml = generateEntryHtml(indexOutput.fileName, mainStyleOutput.fileName, {
             HEAD: `${preloadHtml}${prefetchHtml}`,
         }, ctx);
-        indexHtml = await applyHeadTransform(indexHtml, ctx.config.head);
+        indexHtml = await applyHeadTransform(indexHtml, ctx.config.head, defaultDescription(ctx.config.theme.title ?? 'Poveste'));
         await writeFile('index.html', indexHtml, ctx);
         // Sandbox
         let sandboxHtml = generateEntryHtml(sandboxOutput.fileName, sandboxStyleOutput.fileName, {}, ctx);
         sandboxHtml = await applyHeadTransform(sandboxHtml, ctx.config.head);
         await writeFile('__sandbox.html', sandboxHtml, ctx);
         await writeFile('poveste.json', JSON.stringify(getSerializedStoryData(ctx), null, 2), ctx);
+        // A host's SPA fallback answers a missing /robots.txt with index.html, which a
+        // crawler reads as a malformed robots file rather than as none (#316). One in
+        // the public directory is the book's own, and was copied here already.
+        if (!await fs.pathExists(join(ctx.config.outDir, 'robots.txt'))) {
+            await writeFile('robots.txt', 'User-agent: *\nAllow: /\n', ctx);
+        }
         const duration = performance.now() - startTime;
         const { empty } = counts;
         if (empty.length) {

package/dist/node/collect/index.js

@@ -5,6 +5,7 @@ import { TEMP_PATH } from '../alias.js';
 import { createPath } from '../tree.js';
 import { escapeRegExp } from '../util/escape-regexp.js';
 import { slash } from '../util/fs.js';
+import { NOOP_ID, SETUP_ID } from '../virtual/index.js';
 import { globalsFromDefine } from './define-globals.js';
 import { strayLayoutKeys } from './layout-keys.js';
 import { createModuleServer } from './module-server.js';
@@ -41,7 +42,16 @@ export function useCollectStories(options, ctx) {
         threads: threadsCount,
         invoke: (name, data) => node.invoke(name, data),
     });
+    // Resolved once: a change to the config restarts the server.
+    let setupFile;
+    function resolveSetupFile() {
+        return setupFile ??= server.pluginContainer.resolveId(SETUP_ID, undefined, { ssr: true })
+            .then(resolved => resolved && resolved.id !== NOOP_ID ? resolved.id : undefined);
+    }
+    // Every story the setup file reaches fails with it, so it is reported once a pass.
+    let setupFailureReported = false;
     function clearCache() {
+        setupFailureReported = false;
         server.moduleGraph.invalidateAll();
         node.clearCache();
         // Both of those make every module read again, and a worker told nothing would
@@ -66,6 +76,7 @@ export function useCollectStories(options, ctx) {
                 base: server.config.base,
                 storyFile,
                 defineGlobals,
+                setupFile: await resolveSetupFile(),
             };
             const { storyData } = await threadPool.run(payload);
             const finalData = storyData[0];
@@ -101,12 +112,20 @@ export function useCollectStories(options, ctx) {
         catch (e) {
             // Work `destroy` cut short fails with whatever the pool or a closing server
             // throws. That is the shutdown, not the story, so it is not reported (#878).
-            if (destroying && !options.throws) {
+            // A build destroys only once a story has failed, which already threw.
+            if (destroying) {
                 return;
             }
             // A Vite transform error carries the code frame on `frame`.
             const error = (e instanceof Error ? e : new Error(String(e)));
-            console.error(pc.red(`Error while collecting story ${storyFile.path}:\n${error.frame ? `${pc.bold(error.message)}\n${error.frame}` : error.stack}`));
+            const detail = error.frame ? `${pc.bold(error.message)}\n${error.frame}` : error.stack;
+            if (!error.setupFile) {
+                console.error(pc.red(`Error while collecting story ${storyFile.path}:\n${detail}`));
+            }
+            else if (!setupFailureReported) {
+                setupFailureReported = true;
+                console.error(pc.red(`Error while loading the setup file ${error.setupFile}, so no story that needs it was collected:\n${detail}`));
+            }
             if (options.throws) {
                 throw e;
             }

package/dist/node/collect/module-server.js

@@ -152,6 +152,13 @@ export function createModuleServer(server, options) {
         ? true
         : [...options.inline, ...(Array.isArray(noExternal) ? noExternal : noExternal ? [noExternal] : [])];
     const externalizeCache = new Map();
+    // Each entry keeps the module's invalidation time it was transformed under, in
+    // Vite's clock rather than `Date.now()`. That clock adds a millisecond for every
+    // call within one, so a burst of transforms runs it ahead of the wall clock, and
+    // `invalidateAll` then stamps every module seconds in the future. Against
+    // `Date.now()` the whole cache read as stale until real time caught up, each
+    // re-transform pushed the clock further ahead, and one reload re-collected a
+    // large book a hundred times over (#1352).
     const fetchCache = new Map();
     function getTransformMode(id) {
         const path = cleanUrl(id);
@@ -227,12 +234,11 @@ export function createModuleServer(server, options) {
         const moduleNode = server.moduleGraph.getModuleById(id) ?? [...server.moduleGraph.getModulesByFile(path) ?? []][0];
         const invalidatedAt = moduleNode ? Math.max(moduleNode.lastHMRTimestamp, moduleNode.lastInvalidationTimestamp) : 0;
         const cached = fetchCache.get(path);
-        if (cached && (invalidatedAt === 0 || cached.timestamp >= invalidatedAt)) {
+        if (cached && invalidatedAt <= cached.invalidatedAt) {
             // Unchanged since the runner last read it: it keeps what it has. A runner
             // that never had it gets the code, with nothing of its own to invalidate.
             return cachedByRunner ? { cache: true } : { ...cached.result, invalidate: false };
         }
-        const timestamp = Date.now();
         const result = await transform(id, getTransformMode(id));
         if (!result) {
             throw new Error(`[poveste] could not transform ${id}${importer ? `, imported from ${importer}` : ''}`);
@@ -244,7 +250,7 @@ export function createModuleServer(server, options) {
             url: id,
             invalidate: true,
         };
-        fetchCache.set(path, { timestamp, result: fetched });
+        fetchCache.set(path, { invalidatedAt, result: fetched });
         return fetched;
     }
     /** The two calls a `ModuleRunner` makes, as its transport's `invoke` carries them. */

package/dist/node/collect/runner.d.ts

@@ -31,11 +31,22 @@ export type Invoke = (name: string, data: unknown[]) => Promise<unknown>;
  */
 export declare function filenameOf(module: Readonly<EvaluatedModuleNode>, root: string): string;
 /**
- * The keys an externalised module added to `globalThis` when Node ran it. Node
- * caches that module, so once a worker's reset deletes them nothing installs them
- * again. Vue's development build sets `__VUE_HMR_RUNTIME__` this way, and a story
- * compiled with HMR code reads it at its top level (#1320).
+ * The keys a module Node ran itself added to `globalThis`. Node caches that module,
+ * so once a worker's reset deletes them nothing installs them again. Vue's
+ * development build sets `__VUE_HMR_RUNTIME__` this way, and a story compiled with
+ * HMR code reads it at its top level (#1320). Node runs a module either as an
+ * external, or when an inlined CommonJS module requires it: an installed Nuxt or
+ * Quasar book's `vue.cjs.prod.js` is inlined and requires `@vue/runtime-dom` (#1404).
  */
 export declare const globalsFromExternals: Set<string>;
+/**
+ * Lets a dependency Node runs natively import its own stylesheet. A `type: module`
+ * package's `.js` is externalised, and @primer/react 38's `dist` imports `.css`
+ * files, which Node has no format for (#1392). Nothing in collection reads a
+ * stylesheet, so for this thread it is an empty module; the book still gets it from
+ * Vite. Checked rather than assumed, because a runtime that is not Node, such as
+ * StackBlitz's, may not have the hook.
+ */
+export declare function stubStylesheetsForNode(): void;
 /** A runner over a module server, reached through `invoke`. `root` is the Vite root. */
 export declare function createRunner(invoke: Invoke, root: string, evaluatedModules?: EvaluatedModules): ModuleRunner;

package/dist/node/collect/runner.js

@@ -1,4 +1,5 @@
 import { existsSync } from 'node:fs';
+import * as nodeModule from 'node:module';
 import { createRequire } from 'node:module';
 import { dirname, isAbsolute, join } from 'node:path';
 import process from 'node:process';
@@ -68,13 +69,40 @@ export function filenameOf(module, root) {
     return join(root, 'virtual-module');
 }
 /**
- * The keys an externalised module added to `globalThis` when Node ran it. Node
- * caches that module, so once a worker's reset deletes them nothing installs them
- * again. Vue's development build sets `__VUE_HMR_RUNTIME__` this way, and a story
- * compiled with HMR code reads it at its top level (#1320).
+ * The keys a module Node ran itself added to `globalThis`. Node caches that module,
+ * so once a worker's reset deletes them nothing installs them again. Vue's
+ * development build sets `__VUE_HMR_RUNTIME__` this way, and a story compiled with
+ * HMR code reads it at its top level (#1320). Node runs a module either as an
+ * external, or when an inlined CommonJS module requires it: an installed Nuxt or
+ * Quasar book's `vue.cjs.prod.js` is inlined and requires `@vue/runtime-dom` (#1404).
  */
 export const globalsFromExternals = new Set();
 const ranExternals = new Set();
+const requiredModules = new Set();
+/** The `require` an inlined module gets, recording what each module it loads first installs. */
+function requireRecordingGlobals(filename) {
+    const nodeRequire = createRequire(filename);
+    const recording = (id) => {
+        const resolved = nodeRequire.resolve(id);
+        if (requiredModules.has(resolved)) {
+            return nodeRequire(id);
+        }
+        const before = new Set(Object.keys(globalThis));
+        try {
+            return nodeRequire(id);
+        }
+        finally {
+            requiredModules.add(resolved);
+            for (const key of Object.keys(globalThis)) {
+                if (!before.has(key)) {
+                    globalsFromExternals.add(key);
+                }
+            }
+        }
+    };
+    // `resolve`, `cache` and the rest, as the module expects of `require`.
+    return Object.assign(recording, nodeRequire);
+}
 async function importRecordingGlobals(file) {
     const before = new Set(Object.keys(globalThis));
     const imported = await import(file);
@@ -86,6 +114,25 @@ async function importRecordingGlobals(file) {
     }
     return imported;
 }
+const STYLESHEET = /\.(?:css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:[?#]|$)/;
+/**
+ * Lets a dependency Node runs natively import its own stylesheet. A `type: module`
+ * package's `.js` is externalised, and @primer/react 38's `dist` imports `.css`
+ * files, which Node has no format for (#1392). Nothing in collection reads a
+ * stylesheet, so for this thread it is an empty module; the book still gets it from
+ * Vite. Checked rather than assumed, because a runtime that is not Node, such as
+ * StackBlitz's, may not have the hook.
+ */
+export function stubStylesheetsForNode() {
+    if (typeof nodeModule.registerHooks !== 'function') {
+        return;
+    }
+    nodeModule.registerHooks({
+        load: (url, context, nextLoad) => STYLESHEET.test(url)
+            ? { format: 'module', source: 'export default {}', shortCircuit: true }
+            : nextLoad(url, context),
+    });
+}
 /** As vite-node did: a CJS package's named exports are read through its default. */
 class InteropEvaluator {
     root;
@@ -146,7 +193,7 @@ class InteropEvaluator {
         // own scope it redeclared it, a syntax error that failed every story of the book
         // (#1301). The closing brace goes on a new line: the code may end in a line comment.
         const run = new AsyncFunction(ssrModuleExportsKey, ssrImportMetaKey, ssrImportKey, ssrDynamicImportKey, ssrExportAllKey, ssrExportNameKey, 'require', 'exports', 'module', '__filename', '__dirname', `"use strict";{\n${code}\n}`);
-        await run(context[ssrModuleExportsKey], context[ssrImportMetaKey], context[ssrImportKey], context[ssrDynamicImportKey], context[ssrExportAllKey], context[ssrExportNameKey], createRequire(filename), cjsExports, moduleProxy, filename, dirname(filename));
+        await run(context[ssrModuleExportsKey], context[ssrImportMetaKey], context[ssrImportKey], context[ssrDynamicImportKey], context[ssrExportAllKey], context[ssrExportNameKey], requireRecordingGlobals(filename), cjsExports, moduleProxy, filename, dirname(filename));
     }
     async runExternalModule(file) {
         const imported = ranExternals.has(file) ? await import(file) : await importRecordingGlobals(file);

package/dist/node/collect/types.d.ts

@@ -4,6 +4,8 @@ export interface Payload {
     base: string;
     storyFile: ServerStoryFile;
     defineGlobals?: Record<string, unknown>;
+    /** The book's setup file as the collect server resolved it, when it has one. */
+    setupFile?: string | undefined;
 }
 export interface ReturnData {
     storyData: ServerStory[];

package/dist/node/collect/worker.js

@@ -6,7 +6,7 @@ import pc from 'picocolors';
 import { EvaluatedModules } from 'vite/module-runner';
 import { createDomEnv, resetDomEnv } from '../dom/env.js';
 import { invokeOver } from './rpc.js';
-import { createRunner, globalsFromExternals } from './runner.js';
+import { createRunner, globalsFromExternals, stubStylesheetsForNode } from './runner.js';
 import { serveTasks } from './task.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const _evaluatedModules = new EvaluatedModules();
@@ -41,12 +41,29 @@ function invalidateAll() {
         _evaluatedModules.invalidateModule(node);
     }
 }
+// A framework's collect module imports the setup file, so a setup file that fails
+// to load fails every story with an error that names neither of them (#1324). The
+// runner keeps a module that failed as its rejected promise, which is how it is told
+// apart from a story that failed on its own. Matched on the fetched file, because
+// the module's id is however its importer wrote it, root-relative inside the root.
+async function blameSetupFile(error, setupFile) {
+    const nodes = setupFile
+        ? [..._evaluatedModules.idToModuleMap.values()].filter(node => node.meta && 'file' in node.meta && node.meta.file === setupFile)
+        : [];
+    const failed = await Promise.all(nodes.map(node => node.promise?.then(() => false, () => true)));
+    if (!failed.includes(true)) {
+        return error;
+    }
+    const blamed = typeof error === 'object' && error !== null ? error : new Error(String(error));
+    return Object.assign(blamed, { setupFile });
+}
 if (!parentPort) {
     throw new Error('[poveste] the collection worker was started outside a worker thread');
 }
 // The port it answers over is the one tasks arrive on, so nothing is handed over
 // per story.
 const _invoke = invokeOver(parentPort);
+stubStylesheetsForNode();
 serveTasks(parentPort, { invalidate, invalidateAll, collect });
 async function collect(payload) {
     const startTime = performance.now();
@@ -73,11 +90,16 @@ async function collect(payload) {
     const { run } = (await runner.import(resolve(__dirname, './run.js')));
     const afterExecuteTime = performance.now();
     const storyData = [];
-    await run({
-        file: payload.storyFile,
-        storyData,
-        el,
-    });
+    try {
+        await run({
+            file: payload.storyFile,
+            storyData,
+            el,
+        });
+    }
+    catch (error) {
+        throw await blameSetupFile(error, payload.setupFile);
+    }
     const afterRunTime = performance.now();
     if (payload.storyFile.markdownFile) {
         const el = document.createElement('div');

package/dist/node/config-validation.js

@@ -7,6 +7,9 @@ const RULES = [
     { path: 'setupCode', kind: 'string[]' },
     { path: 'globalStyles', kind: 'string[]' },
     { path: 'isolateStyles', kind: 'boolean' },
+    { path: 'autoDocs', kind: ['boolean', 'object'] },
+    { path: 'autoDocs.allow', kind: 'string[]' },
+    { path: 'autoDocs.exclude', kind: 'string[]' },
     { path: 'autoApplyContrastColor', kind: 'boolean' },
     { path: 'defaultBackgroundColor', kind: 'string' },
     { path: 'sandboxDarkClass', kind: 'string' },

package/dist/node/context.d.ts

@@ -1,5 +1,6 @@
 import type { ConfigMode, FinalSupportPlugin, PluginCommand, PovesteConfig, ServerMarkdownFile, ServerStoryFile } from '@poveste/shared';
 import type { ResolvedConfig } from 'vite';
+import type { StoryDocsResult } from './docgen/protocol.js';
 export interface Context {
     root: string;
     config: PovesteConfig;
@@ -9,6 +10,8 @@ export interface Context {
     supportPlugins: FinalSupportPlugin[];
     markdownFiles: ServerMarkdownFile[];
     registeredCommands: PluginCommand[];
+    /** What `poveste build` extracted for auto-docs, by story id (#1159). */
+    componentDocs?: Record<string, StoryDocsResult['components']>;
 }
 export interface CreateContextOptions {
     mode: Context['mode'];

package/dist/node/docgen/build.d.ts

@@ -0,0 +1,8 @@
+import type { ViteDevServer } from 'vite';
+import type { Context } from '../context.js';
+import type { StoryDocsResult } from './protocol.js';
+/**
+ * The build's pass (#1159): with no reader to wait for, every story's named
+ * components are extracted once, after collection, into what the book ships.
+ */
+export declare function extractComponentDocs(ctx: Context, server: Pick<ViteDevServer, 'moduleGraph' | 'pluginContainer'>): Promise<Record<string, StoryDocsResult['components']>>;

package/dist/node/docgen/build.js

@@ -0,0 +1,52 @@
+import { componentsOfStory, storyOf } from './components-of.js';
+import { createDocgenService } from './service.js';
+/**
+ * The build's pass (#1159): with no reader to wait for, every story's named
+ * components are extracted once, after collection, into what the book ships.
+ */
+export async function extractComponentDocs(ctx, server) {
+    const docgen = createDocgenService({
+        root: ctx.root,
+        plugins: ctx.config.plugins,
+        enabled: ctx.config.autoDocs !== false,
+        bookOptions: typeof ctx.config.autoDocs === 'object' ? ctx.config.autoDocs : undefined,
+        collected: Promise.resolve(),
+        storyOf: storyId => storyOf(ctx.storyFiles, storyId),
+        componentsOf: storyId => componentsOfStory(ctx.storyFiles, server, storyId),
+    });
+    if (!docgen.enabled) {
+        return {};
+    }
+    const docs = {};
+    const failed = new Map();
+    try {
+        for (const storyFile of ctx.storyFiles) {
+            const storyId = storyFile.story?.id;
+            if (!storyId) {
+                continue;
+            }
+            const { components } = await docgen.request(storyId);
+            // A built book is published, so an extractor's error stays on the build
+            // machine: the component keeps its runtime props, as with auto-docs off (#1382).
+            // A result with neither is a file with nothing to document, such as a JSX
+            // story that names no component, and is not a failure.
+            const read = Object.entries(components).filter(([file, result]) => {
+                if (!result.doc && result.error !== undefined) {
+                    failed.set(file, result.error);
+                }
+                return result.doc;
+            });
+            if (read.length) {
+                docs[storyId] = Object.fromEntries(read);
+            }
+        }
+    }
+    finally {
+        await docgen.dispose();
+    }
+    if (failed.size) {
+        const [file, error] = [...failed][0];
+        console.warn(`[poveste] auto-docs could not read ${failed.size} component${failed.size === 1 ? '' : 's'}, which show their runtime props instead. The first, ${file}: ${error}`);
+    }
+    return docs;
+}

package/dist/node/docgen/components-of.d.ts

@@ -0,0 +1,19 @@
+import type { ServerStory, ServerStoryFile } from '@poveste/shared';
+import type { ViteDevServer } from 'vite';
+/** The story's own file, absolute, the framework collection gave it, and its own `autoDocs`. */
+export declare function storyOf(storyFiles: ServerStoryFile[], storyId: string): {
+    file: string;
+    supportPluginId: string;
+    autoDocs?: ServerStory['autoDocs'];
+} | undefined;
+/** The components a story names, and how many capitalised imports reached none. */
+export interface StoryComponents {
+    files: string[];
+    unresolved: number;
+}
+/**
+ * The files a story names: those its `component` field lists, when it has one; else
+ * what its own module imports, as collection resolved it, and the components its
+ * imports reach through re-exports (#1432). Other story files are left out.
+ */
+export declare function componentsOfStory(storyFiles: ServerStoryFile[], server: Pick<ViteDevServer, 'moduleGraph' | 'pluginContainer'>, storyId: string): Promise<StoryComponents>;

package/dist/node/docgen/components-of.js

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute } from 'pathe';
+import { storyComponents } from './reexports.js';
+/** The story's own file, absolute, the framework collection gave it, and its own `autoDocs`. */
+export function storyOf(storyFiles, storyId) {
+    const storyFile = storyFiles.find(file => file.story?.id === storyId);
+    return storyFile && { file: storyFile.path, supportPluginId: storyFile.supportPluginId, autoDocs: storyFile.story?.autoDocs };
+}
+/**
+ * The files a story names: those its `component` field lists, when it has one; else
+ * what its own module imports, as collection resolved it, and the components its
+ * imports reach through re-exports (#1432). Other story files are left out.
+ */
+export async function componentsOfStory(storyFiles, server, storyId) {
+    const storyFile = storyOf(storyFiles, storyId)?.file;
+    if (!storyFile) {
+        return { files: [], unresolved: 0 };
+    }
+    const resolve = async (specifier, importer) => {
+        const id = (await server.pluginContainer.resolveId(specifier, importer, { ssr: true }))?.id.split('?')[0];
+        return id && isAbsolute(id) && existsSync(id) ? id : undefined;
+    };
+    const traced = await storyComponents(storyFile, resolve).catch(() => ({ files: [], named: false, unresolved: 0 }));
+    if (traced.named) {
+        return { files: traced.files, unresolved: traced.unresolved };
+    }
+    const storyPaths = new Set(storyFiles.map(file => file.path));
+    const files = new Set(traced.files);
+    for (const mod of server.moduleGraph.getModulesByFile(storyFile) ?? []) {
+        for (const imported of mod.importedModules) {
+            if (imported.file && !storyPaths.has(imported.file)) {
+                files.add(imported.file);
+            }
+        }
+    }
+    return { files: [...files], unresolved: traced.unresolved };
+}

package/dist/node/docgen/engine.d.ts

@@ -0,0 +1,58 @@
+import type { ComponentDoc, DocgenExtractorModule } from '@poveste/shared';
+export interface EngineExtractorSpec {
+    /** The plugin's name, which keys its extractor. */
+    name: string;
+    module: string;
+    options?: unknown;
+}
+/**
+ * An empty result is a file the extractor found nothing to document in, such as a story naming no component.
+ * A failure's `name` is the component's, when the extractor knew it and the file is not the component's own.
+ */
+export type ExtractResult = {
+    doc: ComponentDoc;
+} | {
+    doc?: undefined;
+    error: string;
+    name?: string;
+} | {
+    doc?: undefined;
+    error?: undefined;
+};
+export interface DocgenEngineOptions {
+    root: string;
+    extractors: EngineExtractorSpec[];
+    /**
+     * Dispose every extractor once the heap passes this share of its limit, and
+     * build afresh on the next request. Storybook recycles at 0.7, and laziness
+     * alone did not cap its memory (storybookjs/storybook#35260).
+     */
+    heapRatio?: number;
+    heapLimit?: number;
+    heapUsed?: () => number;
+    load?: (module: string) => Promise<DocgenExtractorModule>;
+}
+/**
+ * What a reader is shown of an extractor's failure: its first line, with the
+ * book's root made relative and any other absolute path cut to its file name.
+ * Node's `MODULE_NOT_FOUND` message carries a require stack of absolute paths,
+ * which a built book published under every component (#1382).
+ */
+export declare function describeError(error: unknown, root: string): string;
+/** The extraction loop that runs inside the docgen worker, kept free of the thread. */
+/** `import()` takes a URL, and an absolute Windows path is not one: `D:` reads as its scheme. */
+export declare function importable(module: string): string;
+export declare function createDocgenEngine(options: DocgenEngineOptions): {
+    stats: {
+        created: number;
+        recycled: number;
+    };
+    extract(requests: {
+        name: string;
+        file: string;
+    }[]): Promise<Record<string, ExtractResult>>;
+    /** Every live extractor's sources, for the dev server to watch. */
+    sources(): Promise<string[]>;
+    update(file: string): Promise<void>;
+    dispose: () => Promise<void>;
+};