forgebook 0.1.7 → 0.2.0

package/dist/src/vite/plainGrammars.js

@@ -0,0 +1,113 @@
+/** A quoted string, either quote, on one line. */
+const QUOTED = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/y;
+/** A number, with a CSS unit when it has one. */
+const NUMBER = /-?\b\d+(?:\.\d+)?(?:[a-zA-Z]+|%)?/y;
+/** The rules of CSS, which SCSS extends. */
+const CSS_RULES = [
+    [/\/\*[\s\S]*?\*\//y, "comment"],
+    [QUOTED, "string"],
+    [/@[\w-]+/y, "keyword"],
+    [/#[0-9a-fA-F]{3,8}\b/y, "number"],
+    [/[.#][a-zA-Z_][\w-]*/y, "type"],
+    [/--[\w-]+/y, "property"],
+    [/[a-zA-Z-]+(?=[ \t]*:[ \t])/y, "property"],
+    [NUMBER, "number"]
+];
+/** The rules of SCSS: line comments and variables on top of CSS. */
+const SCSS_RULES = [
+    [/\/\/[^\n]*/y, "comment"],
+    [/\$[\w-]+/y, "property"],
+    ...CSS_RULES
+];
+/** The rules of JSON: a string before a colon is a key. */
+const JSON_RULES = [
+    [/"(?:[^"\\\n]|\\.)*"(?=[ \t]*:)/y, "property"],
+    [QUOTED, "string"],
+    [/\b(?:true|false|null)\b/y, "keyword"],
+    [NUMBER, "number"]
+];
+/** The rules of a shell. */
+const SHELL_RULES = [
+    [/(?<![^\s])#[^\n]*/y, "comment"],
+    [QUOTED, "string"],
+    [/\$\{[^}\n]*\}|\$\w+/y, "property"],
+    [/\b(?:if|then|else|elif|fi|for|in|do|done|while|case|esac|function|export|return|cd|echo)\b/y, "keyword"]
+];
+/** The rules inside an HTML tag, whose name comes first. */
+const TAG_RULES = [
+    [/(?<=<\/?)[\w:.-]+/y, "tag"],
+    [QUOTED, "string"],
+    [/[\w:.-]+(?==)/y, "attribute"]
+];
+/** The grammars, by the names a Markdown fence gives them. */
+const GRAMMARS = {
+    css: CSS_RULES,
+    scss: SCSS_RULES,
+    json: JSON_RULES,
+    bash: SHELL_RULES,
+    sh: SHELL_RULES,
+    shell: SHELL_RULES,
+    zsh: SHELL_RULES
+};
+/** The names of HTML. */
+const HTML_NAMES = new Set(["html", "xml", "svg"]);
+/** The rule that matches at a position, with its length. */
+const matchAt = (code, index, rules) => {
+    for (const [pattern, role] of rules) {
+        pattern.lastIndex = index;
+        const found = pattern.exec(code);
+        if (found !== null && found[0] !== "")
+            return { role, length: found[0].length };
+    }
+    return undefined;
+};
+/** Pieces with the plain text between them joined, so an example makes few spans. */
+const piecesOf = (code, rules) => {
+    const pieces = [];
+    let plainFrom = 0;
+    let index = 0;
+    while (index < code.length) {
+        const match = matchAt(code, index, rules);
+        if (match === undefined) {
+            index += 1;
+        }
+        else {
+            if (plainFrom < index)
+                pieces.push({ text: code.slice(plainFrom, index) });
+            pieces.push({ text: code.slice(index, index + match.length), role: match.role });
+            index += match.length;
+            plainFrom = index;
+        }
+    }
+    if (plainFrom < code.length)
+        pieces.push({ text: code.slice(plainFrom) });
+    return pieces;
+};
+/** HTML: comments and tags are coloured, and the text between them is left as it is. */
+const htmlPieces = (code) => {
+    const pieces = [];
+    let index = 0;
+    for (const part of code.matchAll(/<!--[\s\S]*?-->|<[^>]*>/g)) {
+        if (part.index > index)
+            pieces.push({ text: code.slice(index, part.index) });
+        const isComment = part[0].startsWith("<!--");
+        pieces.push(...(isComment ? [{ text: part[0], role: "comment" }] : piecesOf(part[0], TAG_RULES)));
+        index = part.index + part[0].length;
+    }
+    if (index < code.length)
+        pieces.push({ text: code.slice(index) });
+    return pieces;
+};
+/**
+ * A piece of documentation's code as coloured pieces.
+ *
+ * @param code - the code.
+ * @param language - its language, as a Markdown fence names it.
+ * @returns the pieces, or none for a language with no grammar here.
+ */
+export const grammarPieces = (code, language) => {
+    if (HTML_NAMES.has(language))
+        return htmlPieces(code);
+    const rules = Object.hasOwn(GRAMMARS, language) ? GRAMMARS[language] : undefined;
+    return rules === undefined ? undefined : piecesOf(code, rules);
+};

package/dist/src/vite/pluginConfig.d.ts

@@ -0,0 +1,47 @@
+import type { ForgebookPlugin } from "../plugin.ts";
+import { type ViewSwitch } from "../switches.ts";
+import type { PluginsDocument } from "./agent.types.ts";
+/** The versions of the contract this Forgebook speaks. */
+export declare const SUPPORTED_PLUGIN_API_VERSIONS: readonly number[];
+/**
+ * The module a plugin runs in a catalogue's frames, or none.
+ *
+ * @param plugin - the plugin.
+ * @param framework - the catalogue's framework.
+ */
+export declare const pluginFrameModule: (plugin: ForgebookPlugin, framework: string) => string | undefined;
+/**
+ * Why a list of plugins cannot be used, or none.
+ *
+ * @param plugins - the configuration's plugins.
+ * @param framework - the catalogue's framework.
+ * @param dir - the configuration's folder.
+ */
+export declare const pluginsProblem: (plugins: readonly ForgebookPlugin[], framework: string, dir: string) => string | undefined;
+/**
+ * The catalogue's switches with the plugins' after them: a plugin adds to the catalogue's and never takes the place of
+ * the theme and the contrast it would have by default. The catalogue's own switch of the same id wins.
+ *
+ * @param switches - the catalogue's, merged with its presets'; none when neither declares any.
+ * @param plugins - the plugins.
+ */
+export declare const withPluginSwitches: (switches: readonly ViewSwitch[] | undefined, plugins: readonly ForgebookPlugin[]) => readonly ViewSwitch[] | undefined;
+/**
+ * Every module of the plugins that pages import, for pre-bundling an installed plugin.
+ *
+ * @param plugins - the plugins.
+ * @param framework - the catalogue's framework.
+ */
+export declare const pluginModules: (plugins: readonly ForgebookPlugin[], framework: string) => string[];
+/**
+ * The fences the plugins add, for the docs pages' compiler.
+ *
+ * @param plugins - the plugins.
+ */
+export declare const pluginFences: (plugins: readonly ForgebookPlugin[]) => readonly string[];
+/**
+ * The plugins as tools and agents read them.
+ *
+ * @param plugins - the plugins.
+ */
+export declare const pluginsDocument: (plugins: readonly ForgebookPlugin[]) => PluginsDocument;

package/dist/src/vite/pluginConfig.js

@@ -0,0 +1,220 @@
+/**
+ * The plugins a configuration lists, checked on Node before anything is generated from them, and what they add to it.
+ *
+ * @remarks
+ * A configuration is code nobody type-checked against this version, and what it names ends up in generated imports and
+ * in the address, so every plugin is read as `unknown`-shaped data here: one whose contract this Forgebook does not
+ * speak, or that collides with another or with Forgebook itself, stops the catalogue with a message that names it,
+ * rather than breaking a page later.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { PANEL_TAB_IDS } from "../catalogue.js";
+import { DEFAULT_SWITCHES } from "../switches.js";
+/** The versions of the contract this Forgebook speaks. */
+export const SUPPORTED_PLUGIN_API_VERSIONS = [1];
+/**
+ * The fences a plugin may not take: a page's own, and the languages people write code in, which would stop being code on
+ * every page of the catalogue.
+ */
+const OWN_FENCES = [
+    ...[
+        "story",
+        "props",
+        "bash",
+        "c",
+        "cpp",
+        "css",
+        "diff",
+        "go",
+        "html",
+        "java",
+        "js",
+        "json",
+        "jsx",
+        "kotlin"
+    ],
+    ...["markdown", "md", "mdx", "php", "python", "py", "ruby", "rust", "scss", "sh", "shell", "sql", "swift"],
+    ...["text", "toml", "ts", "tsx", "txt", "xml", "yaml", "yml"]
+];
+/** A plugin's id: lower-case words and hyphens. */
+const NAME = /^[a-z][a-z0-9-]*$/;
+/**
+ * The first of some names that is there twice, or not one of the plugin's.
+ *
+ * @param plugin - the plugin's id.
+ * @param names - the names.
+ * @param seen - the names of every plugin so far.
+ * @param what - what a name names, for the message.
+ */
+const namesProblem = (plugin, names, seen, what) => {
+    for (const name of names) {
+        if (name !== plugin && !(name.startsWith(`${plugin}-`) && NAME.test(name)))
+            return `${what} "${name}" must be "${plugin}", or start with "${plugin}-"`;
+        if (seen.has(name))
+            return `${what} "${name}" is given twice`;
+        seen.add(name);
+    }
+    return undefined;
+};
+/**
+ * The module a plugin runs in a catalogue's frames, or none.
+ *
+ * @param plugin - the plugin.
+ * @param framework - the catalogue's framework.
+ */
+export const pluginFrameModule = (plugin, framework) => typeof plugin.frame === "object" ? plugin.frame[framework] : plugin.frame;
+/** A package's name, from a specifier of it (`@acme/ui/browser` → `@acme/ui`). */
+const packageOf = (specifier) => specifier
+    .split("/")
+    .slice(0, specifier.startsWith("@") ? 2 : 1)
+    .join("/");
+/**
+ * Whether a project installs a package, by its folder: a browser-only package may hide even its manifest from Node.
+ *
+ * @param dir - the configuration's folder.
+ * @param name - the package.
+ */
+const isPackageInstalled = (dir, name) => (createRequire(resolve(dir, "package.json")).resolve.paths(name) ?? []).some((folder) => existsSync(join(folder, name)));
+/**
+ * Why a plugin's fields do not have their shape, or none: a configuration is not type-checked, and a field read as
+ * what it is not would otherwise stop the catalogue with a bare `TypeError`.
+ *
+ * @param plugin - the plugin.
+ */
+const shapeProblem = (plugin) => {
+    const lists = [
+        plugin.tabs,
+        plugin.switches,
+        plugin.docBlocks,
+        plugin.browserDependencies
+    ];
+    if (lists.some((list) => list !== undefined && !Array.isArray(list)))
+        return `the plugin "${plugin.id}" gives a list that is no list`;
+    const named = [
+        ...(plugin.tabs ?? []).map((tab) => tab?.id),
+        ...(plugin.switches ?? []).map((each) => each?.id),
+        ...(plugin.docBlocks ?? []).map((block) => block?.fence)
+    ];
+    if (named.some((name) => typeof name !== "string"))
+        return `the plugin "${plugin.id}" adds something with no id`;
+    const { frame } = plugin;
+    const isFrame = frame === undefined || typeof frame === "string" || (typeof frame === "object" && frame !== null);
+    return isFrame ? undefined : `the plugin "${plugin.id}" names a frame that is no specifier`;
+};
+/**
+ * Why one plugin cannot be used, or none.
+ *
+ * @param plugin - the plugin.
+ * @param framework - the catalogue's framework.
+ * @param dir - the configuration's folder.
+ */
+const pluginProblem = (plugin, framework, dir) => {
+    if (!SUPPORTED_PLUGIN_API_VERSIONS.includes(plugin.apiVersion)) {
+        return (`the plugin "${plugin.id}" is written for version ${String(plugin.apiVersion)} of the plugin API, and this ` +
+            `Forgebook speaks version ${SUPPORTED_PLUGIN_API_VERSIONS.join(", ")}: update one of them`);
+    }
+    if (typeof plugin.frame === "object" && plugin.frame[framework] === undefined) {
+        const frameworks = Object.keys(plugin.frame).join(", ");
+        return `the plugin "${plugin.id}" runs in frames of ${frameworks}, and this catalogue is ${framework}`;
+    }
+    const modules = [
+        ...(plugin.tabs ?? []).map((tab) => tab.view),
+        ...(plugin.docBlocks ?? []).map((block) => block.view),
+        ...(plugin.frame === undefined ? [] : [pluginFrameModule(plugin, framework)])
+    ];
+    if (modules.some((module) => typeof module !== "string" || module === ""))
+        return `the plugin "${plugin.id}" names a module that is no specifier`;
+    const missing = (plugin.browserDependencies ?? [])
+        .map(packageOf)
+        .find((name) => !isPackageInstalled(dir, name));
+    return missing === undefined
+        ? undefined
+        : `the plugin "${plugin.id}" needs the package ${missing}, which this project does not install`;
+};
+/**
+ * Why a list of plugins cannot be used, or none.
+ *
+ * @param plugins - the configuration's plugins.
+ * @param framework - the catalogue's framework.
+ * @param dir - the configuration's folder.
+ */
+export const pluginsProblem = (plugins, framework, dir) => {
+    const ids = new Set();
+    const tabs = new Set(PANEL_TAB_IDS);
+    const switches = new Set();
+    const fences = new Set(OWN_FENCES);
+    for (const plugin of plugins) {
+        const { id } = plugin;
+        if (typeof id !== "string" || !NAME.test(id))
+            return `the plugin "${String(id)}" must be lower-case words and hyphens`;
+        if (ids.has(id))
+            return `the plugin "${id}" is given twice`;
+        ids.add(id);
+        const problem = shapeProblem(plugin) ??
+            pluginProblem(plugin, framework, dir) ??
+            namesProblem(id, (plugin.tabs ?? []).map((tab) => tab.id), tabs, "the tab") ??
+            namesProblem(id, (plugin.switches ?? []).map((each) => each.id), switches, "the switch") ??
+            namesProblem(id, (plugin.docBlocks ?? []).map((block) => block.fence), fences, "the docs block");
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+};
+/**
+ * The catalogue's switches with the plugins' after them: a plugin adds to the catalogue's and never takes the place of
+ * the theme and the contrast it would have by default. The catalogue's own switch of the same id wins.
+ *
+ * @param switches - the catalogue's, merged with its presets'; none when neither declares any.
+ * @param plugins - the plugins.
+ */
+export const withPluginSwitches = (switches, plugins) => {
+    const added = plugins.flatMap((plugin) => plugin.switches ?? []);
+    if (added.length === 0)
+        return switches;
+    const own = switches ?? DEFAULT_SWITCHES;
+    return [...own, ...added.filter((each) => !own.some((other) => other.id === each.id))];
+};
+/**
+ * Every module of the plugins that pages import, for pre-bundling an installed plugin.
+ *
+ * @param plugins - the plugins.
+ * @param framework - the catalogue's framework.
+ */
+export const pluginModules = (plugins, framework) => plugins.flatMap((plugin) => {
+    const frame = pluginFrameModule(plugin, framework);
+    return [
+        ...(plugin.tabs ?? []).map((tab) => tab.view),
+        ...(plugin.docBlocks ?? []).map((block) => block.view),
+        ...(frame === undefined ? [] : [frame])
+    ];
+});
+/**
+ * The fences the plugins add, for the docs pages' compiler.
+ *
+ * @param plugins - the plugins.
+ */
+export const pluginFences = (plugins) => plugins.flatMap((plugin) => (plugin.docBlocks ?? []).map((block) => block.fence));
+/**
+ * The plugins as tools and agents read them.
+ *
+ * @param plugins - the plugins.
+ */
+export const pluginsDocument = (plugins) => ({
+    schema: 1,
+    apiVersions: SUPPORTED_PLUGIN_API_VERSIONS,
+    plugins: plugins.map((plugin) => ({
+        id: plugin.id,
+        tabs: (plugin.tabs ?? []).map((tab) => ({
+            id: tab.id,
+            label: tab.label,
+            ...(tab.when === undefined ? {} : { when: tab.when })
+        })),
+        switches: (plugin.switches ?? []).map((each) => each.id),
+        docBlocks: (plugin.docBlocks ?? []).map((block) => block.fence),
+        runsInFrames: plugin.frame !== undefined
+    }))
+});

package/dist/src/vite/pluginIds.d.ts

@@ -0,0 +1,20 @@
+/** The id of a pattern's docs pages: virtual, with the declaring module's folder and the pattern after it. */
+export declare const DOCS_PAGES_PREFIX = "\0forgebook-docs-pages:";
+/**
+ * The id of a pattern's module, when an import asks for one: its story files, or its docs pages.
+ *
+ * @param source - the import's specifier.
+ * @param folder - the importing module's folder.
+ */
+export declare const patternId: (source: string, folder: string) => string | null;
+/**
+ * The id of a virtual module the plugin makes (the configuration's data, the tokens, a group's "Used in", reach,
+ * search indexes or texts), when the import names one.
+ *
+ * @param source - the import's specifier.
+ */
+export declare const virtualId: (source: string) => string | undefined;
+/** The resolved id of the configuration's data module. */
+export declare const CONFIG_ID = "\0virtual:forgebook/config";
+/** The resolved id of the design tokens' module. */
+export declare const TOKENS_ID = "\0virtual:forgebook/tokens";

package/dist/src/vite/pluginIds.js

@@ -0,0 +1,61 @@
+/**
+ * The ids of the modules the plugin makes: a pattern's story files or docs pages, the configuration's data, the design
+ * tokens, a group's "Used in", reach and texts. Pure: a specifier in, an id out.
+ *
+ * @module
+ */
+import { CONFIG_MODULE, TOKENS_MODULE } from "./pages.js";
+import { FILES_PREFIX } from "./pluginModules.js";
+import { PAGES_SEARCH_PREFIX, REACH_PREFIX, SEARCH_PREFIX, storyFilesGroupText, TEXTS_PREFIX, USAGE_PREFIX } from "./storyFilesModule.js";
+/** The query that asks for the story files a pattern matches (`../src/**\/*.stories.tsx?forgebook-files`). */
+const FILES_QUERY = "?forgebook-files";
+/** The query that asks for the docs pages a pattern matches (`./docs/*.md?forgebook-docs-pages`). */
+const DOCS_PAGES_QUERY = "?forgebook-docs-pages";
+/** The id of a pattern's docs pages: virtual, with the declaring module's folder and the pattern after it. */
+export const DOCS_PAGES_PREFIX = "\0forgebook-docs-pages:";
+/**
+ * The id of a `?forgebook-files` module: its prefix, then its group (`storyFilesGroupText`), which holds no `..`.
+ *
+ * @param folder - the importing module's folder.
+ * @param pattern - the pattern as the import writes it.
+ */
+const filesId = (folder, pattern) => `${FILES_PREFIX}${storyFilesGroupText(folder, pattern)}`;
+/**
+ * The id of a pattern's module, when an import asks for one: its story files, or its docs pages.
+ *
+ * @param source - the import's specifier.
+ * @param folder - the importing module's folder.
+ */
+export const patternId = (source, folder) => {
+    if (source.endsWith(FILES_QUERY))
+        return filesId(folder, source.slice(0, -FILES_QUERY.length));
+    if (!source.endsWith(DOCS_PAGES_QUERY))
+        return null;
+    const pattern = source.slice(0, -DOCS_PAGES_QUERY.length);
+    return `${DOCS_PAGES_PREFIX}${storyFilesGroupText(folder, pattern)}`;
+};
+/** The specifiers' prefixes of a group's virtual modules: its "Used in", its reach, its search indexes, its texts. */
+const VIRTUAL_PREFIXES = [
+    USAGE_PREFIX,
+    REACH_PREFIX,
+    SEARCH_PREFIX,
+    PAGES_SEARCH_PREFIX,
+    TEXTS_PREFIX
+];
+/**
+ * The id of a virtual module the plugin makes (the configuration's data, the tokens, a group's "Used in", reach,
+ * search indexes or texts), when the import names one.
+ *
+ * @param source - the import's specifier.
+ */
+export const virtualId = (source) => {
+    if (source === CONFIG_MODULE)
+        return CONFIG_ID;
+    if (source === TOKENS_MODULE)
+        return TOKENS_ID;
+    return VIRTUAL_PREFIXES.some((prefix) => source.startsWith(prefix)) ? `\0${source}` : undefined;
+};
+/** The resolved id of the configuration's data module. */
+export const CONFIG_ID = `\0${CONFIG_MODULE}`;
+/** The resolved id of the design tokens' module. */
+export const TOKENS_ID = `\0${TOKENS_MODULE}`;

package/dist/src/vite/pluginModules.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The modules the plugin answers from what it read of the story files: a story file's component docs, a pattern's
+ * index and loaders, a group's "Used in" and what its stories reach.
+ *
+ * @remarks
+ * The modules made from a file's text (a story's code, a component's page, Markdown) are `textModules.ts`, which the
+ * plugin loads on their first query: what they need is heavy, and a story's page needs none of it.
+ *
+ * @module
+ */
+import type { DiskCache } from "./diskCache.ts";
+import type { DocsExtractor, DocsResult } from "./docsExtractor.ts";
+import type { PackJson } from "./packedModule.ts";
+import { type GroupLoaders, type IndexedStoryFile, type KeptIndex } from "./storyFilesModule.ts";
+/** The id of a pattern's module: virtual, with the declaring module's folder and the pattern after it. */
+export declare const FILES_PREFIX = "\0forgebook-files:";
+/** The resolved id of a group's "Used in" module: Rollup's mark of a virtual module, then its import's specifier. */
+export declare const USAGE_ID_PREFIX = "\0virtual:forgebook-usage:";
+/** The resolved id of a group's reach module, the same way. */
+export declare const REACH_ID_PREFIX = "\0virtual:forgebook-reach:";
+/** The resolved id of a group's texts module, a build's, the same way. */
+export declare const TEXTS_ID_PREFIX = "\0virtual:forgebook-texts:";
+/** The resolved id of a group of story files' search index. */
+export declare const SEARCH_ID_PREFIX = "\0virtual:forgebook-search:";
+/** The resolved id of a group of docs pages' search index. */
+export declare const PAGES_SEARCH_ID_PREFIX = "\0virtual:forgebook-search-pages:";
+/**
+ * A story file's component docs as the panel reads them, or `{ error }`.
+ *
+ * @param component - what the extractor read for the story file.
+ * @param watch - adds a file whose edit renews what holds them.
+ */
+export declare const docsValue: (component: DocsResult, watch: (file: string) => void) => unknown;
+/**
+ * The module that answers a `?forgebook-docs` import: the story file's component docs, or `{ error }` for the panel.
+ *
+ * @param component - what the extractor read for the story file.
+ * @param watch - adds a file whose edit renews the module.
+ */
+export declare const docsModule: (component: DocsResult, watch: (file: string) => void) => {
+    code: string;
+    moduleType: "js";
+};
+/**
+ * The module of a `?forgebook-files` pattern: every matched story file's index and loaders; with the files, indexed,
+ * which the dev server keeps to tell an edit that changes the list.
+ *
+ * @param id - the module's id (`FILES_PREFIX`, then the group: `storyFilesGroupText`).
+ * @param watch - adds a file whose edit renews the module (each story file).
+ * @param loaders - the group's loaders besides its story files'.
+ * @param cache - the pattern's index kept between starts; none reads every file.
+ * @param warm - starts reading the docs of a story file ahead of its request; none in a test run.
+ * @param startTexts - a build's: starts reading the files' docs, code and pages, which the module imports from the
+ * group's texts module (`builtTexts.ts`); none imports each from its query.
+ * @throws when a story file cannot be indexed.
+ */
+export declare const patternModule: (id: string, watch: (file: string) => void, loaders: GroupLoaders, cache: DiskCache<KeptIndex> | undefined, warm: ((storyFile: string) => void) | undefined, startTexts?: (files: readonly IndexedStoryFile[]) => void) => {
+    code: string;
+    moduleType: "js";
+    files: readonly IndexedStoryFile[];
+};
+/**
+ * A group's "Used in" module: for each component, the components that use it, packed once per title and list of
+ * stories (`packedUsage`), which a page reads.
+ *
+ * @param id - the module's id (`USAGE_ID_PREFIX`, then the group: `storyFilesGroupText`).
+ * @param watch - adds a file whose edit renews the module (each story file).
+ * @param usage - reads the facts in the docs worker.
+ * @param cache - the pattern's index kept between starts; none reads every file.
+ * @param pack - writes the module's JSON as its value: as it is on a dev server, in a gzipped file of a build's.
+ */
+export declare const usageModule: (id: string, watch: (file: string) => void, usage: DocsExtractor["usage"], cache: DiskCache<KeptIndex> | undefined, pack: PackJson) => Promise<{
+    code: string;
+    moduleType: "js";
+}>;
+/**
+ * A group's reach module: the files each story reaches, which only the dev server's tools read (a check of what a
+ * change touches). A module of its own, since a large library's stories reach thousands of files each, which a page
+ * showing "Used in" must not download.
+ *
+ * @param id - the module's id (`REACH_ID_PREFIX`, then the group: `storyFilesGroupText`).
+ * @param watch - adds a file whose edit renews the module (each story file).
+ * @param usage - reads the facts in the docs worker.
+ * @param cache - the pattern's index kept between starts; none reads every file.
+ */
+export declare const reachModule: (id: string, watch: (file: string) => void, usage: DocsExtractor["usage"], cache: DiskCache<KeptIndex> | undefined) => Promise<{
+    code: string;
+    moduleType: "js";
+}>;
+/** A search index, made: its module, and whether it is a group of docs pages' (renewed as pages come and go). */
+export type SearchIndexModule = {
+    /** The module. */
+    readonly module: {
+        readonly code: string;
+        readonly moduleType: "js";
+    };
+    /** Whether it indexes docs pages, not story files. */
+    readonly isPages: boolean;
+};
+/**
+ * A group's search index, when the id names one: its story files' (what their components' docs and pages say) or its
+ * docs pages'. The search's code, and the Markdown reader it needs, load with the first.
+ *
+ * @param id - the module's id.
+ * @param watch - adds a file whose edit renews the module.
+ * @param read - a story file's component docs, and how the module writes its JSON.
+ * @returns the index; none for another id.
+ */
+export declare const searchIndexModule: (id: string, watch: (file: string) => void, read: {
+    readonly docsOf: (storyFile: string) => Promise<DocsResult>;
+    readonly isServing: boolean;
+    readonly pack: PackJson;
+}) => Promise<SearchIndexModule | undefined>;
+/** What a catalogue's search indexes read and tell: what `searchIndexes` makes. */
+export type SearchIndexes = {
+    /** A story file's component docs: a dev server reads them again each time, as they change while it runs. */
+    readonly docsOf: (storyFile: string) => Promise<DocsResult>;
+    /**
+     * A group's search index, when the id names one; none for another id.
+     *
+     * @param id - the module's id.
+     * @param watch - adds a file whose edit renews the module.
+     * @param pack - writes the index's JSON as the module's value.
+     */
+    readonly moduleOf: (id: string, watch: (file: string) => void, pack: PackJson) => Promise<{
+        code: string;
+        moduleType: "js";
+    } | undefined>;
+};
+/**
+ * The search's indexes of a plugin: a build reads each component's docs once, for its page and its index.
+ *
+ * @param read - reads a story file's component docs, says whether a dev server runs, and keeps each index's id with the
+ * modules an edit renews (a docs pages' index with the docs pages').
+ */
+export declare const searchIndexes: (read: {
+    readonly extract: (storyFile: string) => Promise<DocsResult>;
+    readonly isServing: () => boolean;
+    readonly track: (id: string, isPages: boolean) => void;
+}) => SearchIndexes;