forgebook 0.1.8 → 0.2.0

package/dist/src/vite/textModules.js

@@ -0,0 +1,132 @@
+/**
+ * The modules the plugin makes from a file's text: a story file's code (`?forgebook-code`), a component's page
+ * (`?forgebook-page`) and a source's Markdown file (`?forgebook-markdown`).
+ *
+ * @remarks
+ * Colouring code loads highlight.js and the TypeScript compiler's scanner, and Markdown its reader: each is imported
+ * only when a query needs it, code only when a story has a `render` to colour, and a story file's code is kept on disk
+ * between starts (`diskCache.ts`), so a story's page reads it without either on a later start.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { codeLiteral } from "../codeLiteral.js";
+import { componentImport } from "./componentImport.js";
+import { isSettledSince, nowNs, stampPaths } from "./diskCache.js";
+import { moduleSummaryOf } from "./moduleSummary.js";
+import { storyCode } from "./storyCode.js";
+import { CODE_QUERY, MARKDOWN_QUERY, PAGE_QUERY } from "./textQueries.js";
+/**
+ * The module whose default export is a value.
+ *
+ * @param value - the value, as JSON.
+ */
+const valueModule = (value) => ({
+    code: `export default ${codeLiteral(value)};`,
+    moduleType: "js"
+});
+/** Whether what a cache file holds is a story file's code. */
+export const isKeptCode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Each story's `render` text with its coloured HTML.
+ *
+ * @remarks
+ * The colouring loads the TypeScript compiler, tens of megabytes the server then holds for as long as it runs: only a
+ * file with a `render` to colour loads it. A file whose stories are all args has none, and its Code tab writes them
+ * from the args (the framework's code writer), so a story's page of a library written that way leaves the compiler to
+ * the docs worker; a component's page or a Markdown page still loads it, to colour their examples.
+ *
+ * @param code - each story's `render` text, by export name.
+ */
+const colouredCode = async (code) => {
+    const entries = Object.entries(code);
+    if (entries.length === 0)
+        return {};
+    const { highlightCode } = await import("./highlightCode.js");
+    return Object.fromEntries(entries.map(([name, text]) => [name, { text, html: highlightCode(text, "tsx") }]));
+};
+/**
+ * A story file's code as the Code tab reads it, what a `?forgebook-code` import answers: each story's `render` text and
+ * its coloured HTML, or `{ error }` for the card.
+ *
+ * @param storyFile - the story file's absolute path; Vite renews the module when it changes, as the id names it.
+ * @param cache - the code kept between starts; none reads the file every time.
+ */
+export const storyFileCode = async (storyFile, cache) => {
+    const kept = cache?.read(storyFile);
+    if (kept !== undefined)
+        return kept;
+    const since = nowNs();
+    const code = storyCode(storyFile, readFileSync(storyFile, "utf8"));
+    const value = typeof code === "string" ? { error: code } : await colouredCode(code);
+    // colouring loads the compiler's scanner: kept, a story's page reads its code without it on a later start
+    const stamps = stampPaths([storyFile]);
+    if (typeof code !== "string" && isSettledSince(stamps, since))
+        cache?.write(storyFile, value, stamps);
+    return value;
+};
+/**
+ * The text a component's file opens with: a framework's own kind of file (`.vue`) by its script.
+ *
+ * @param file - the file's absolute path.
+ * @param componentFiles - the framework's own kind of file; none when it has none.
+ */
+const scriptOfFile = (file, componentFiles) => {
+    const text = readFileSync(file, "utf8");
+    return componentFiles !== undefined && file.endsWith(componentFiles.extension)
+        ? componentFiles.scriptOf(text)
+        : text;
+};
+/**
+ * A story file's component page, what a `?forgebook-page` import answers: the component's documentation file as HTML
+ * (empty without one), and its file's summary, the first paragraph of its `@module` comment, for the page's lead.
+ *
+ * @remarks
+ * The summary is read here, from the component's file alone, rather than with the docs: the docs wait for the
+ * package's TypeScript program, and the lead would come seconds after the rest of the page.
+ *
+ * @param storyFile - the story file's absolute path.
+ * @param context - what the plugin gives: the watch (the documentation file, the component's file), how an import of
+ * the component resolves, and the framework's own kind of component file.
+ */
+export const storyFilePage = async (storyFile, context) => {
+    const specifier = componentImport(storyFile, readFileSync(storyFile, "utf8"));
+    const componentFile = specifier === undefined ? undefined : await context.resolveImport(specifier, storyFile);
+    const { componentPage } = await import("./componentPage.js");
+    const page = componentPage(storyFile);
+    if (page !== undefined)
+        context.watch(page.file);
+    if (componentFile !== undefined)
+        context.watch(componentFile);
+    const summary = componentFile === undefined ? "" : moduleSummaryOf(scriptOfFile(componentFile, context.componentFiles));
+    return { html: page?.html ?? "", summary };
+};
+/**
+ * The module that answers a `?forgebook-markdown` import: a source's Markdown file (its introduction) as HTML.
+ *
+ * @param file - the Markdown file's absolute path.
+ * @param watch - adds a file whose edit renews the module (the Markdown file).
+ */
+const markdownModule = async (file, watch) => {
+    watch(file);
+    const { markdownHtml } = await import("./componentPage.js");
+    const value = { html: markdownHtml(readFileSync(file, "utf8")) };
+    return { code: `export default ${codeLiteral(value)};`, moduleType: "js" };
+};
+/**
+ * The module a query asks for, when the id is one of these.
+ *
+ * @param id - the module's id.
+ * @param context - what the plugin gives.
+ */
+export const textModule = async (id, context) => {
+    if (id.endsWith(PAGE_QUERY)) {
+        return valueModule(await storyFilePage(id.slice(0, -PAGE_QUERY.length), context));
+    }
+    if (id.endsWith(CODE_QUERY)) {
+        return valueModule(await storyFileCode(id.slice(0, -CODE_QUERY.length), context.cache));
+    }
+    if (id.endsWith(MARKDOWN_QUERY))
+        return markdownModule(id.slice(0, -MARKDOWN_QUERY.length), context.watch);
+    return undefined;
+};

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

@@ -0,0 +1,20 @@
+/**
+ * The queries the plugin answers with a module made from a file's text: a story file's code, its component's page, a
+ * source's Markdown, a docs page.
+ *
+ * @remarks
+ * Their own module, so the plugin and the modules that answer them share the names without the plugin loading what
+ * answers them (the Markdown reader, the highlighter, the compiler) at start.
+ *
+ * @module
+ */
+/** The query that asks for a story file's code: each story's `render` as written. */
+export declare const CODE_QUERY = "?forgebook-code";
+/** The query that asks for a story file's component page: its documentation file as HTML. */
+export declare const PAGE_QUERY = "?forgebook-page";
+/** The query a source's Markdown file is imported with (its introduction on the home), answered with its HTML. */
+export declare const MARKDOWN_QUERY = "?forgebook-markdown";
+/** The query that asks for one docs page, compiled. */
+export declare const DOCS_PAGE_QUERY = "?forgebook-docs-page";
+/** The query that asks for the written home (`forgebook.home.md`), rendered: its file, then this. */
+export declare const HOME_QUERY = "?forgebook-home";

package/dist/src/vite/textQueries.js

@@ -0,0 +1,20 @@
+/**
+ * The queries the plugin answers with a module made from a file's text: a story file's code, its component's page, a
+ * source's Markdown, a docs page.
+ *
+ * @remarks
+ * Their own module, so the plugin and the modules that answer them share the names without the plugin loading what
+ * answers them (the Markdown reader, the highlighter, the compiler) at start.
+ *
+ * @module
+ */
+/** The query that asks for a story file's code: each story's `render` as written. */
+export const CODE_QUERY = "?forgebook-code";
+/** The query that asks for a story file's component page: its documentation file as HTML. */
+export const PAGE_QUERY = "?forgebook-page";
+/** The query a source's Markdown file is imported with (its introduction on the home), answered with its HTML. */
+export const MARKDOWN_QUERY = "?forgebook-markdown";
+/** The query that asks for one docs page, compiled. */
+export const DOCS_PAGE_QUERY = "?forgebook-docs-page";
+/** The query that asks for the written home (`forgebook.home.md`), rendered: its file, then this. */
+export const HOME_QUERY = "?forgebook-home";

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

@@ -0,0 +1,35 @@
+import type { ShellPalette, ShellTheme } from "../shellTheme.types.ts";
+import { type DesignToken } from "./designTokens.ts";
+/** A tokens file, as the configuration resolves it. */
+type TokensFileRef = {
+    /** Its absolute path. */
+    readonly path: string;
+    /** The theme it belongs to; none for the base. */
+    readonly mode: string | undefined;
+};
+/** The roles and their token names. */
+type TokenMapping = Partial<ShellPalette>;
+/** A theme read from tokens, with what could not be used. */
+export type TokenTheme = {
+    /** The colours. */
+    readonly theme: ShellTheme;
+    /** What will not work, for a warning. */
+    readonly problems: readonly string[];
+};
+/**
+ * The theme a mapping gives.
+ *
+ * @param mapping - the token's name for each role.
+ * @param tokens - the tokens.
+ * @returns the colours of each appearance, and what could not be used.
+ */
+export declare const tokenTheme: (mapping: TokenMapping, tokens: readonly DesignToken[]) => TokenTheme;
+/**
+ * Reads a catalogue's tokens files and the theme a mapping gives; no mapping reads nothing.
+ *
+ * @param mapping - the token's name for each role.
+ * @param files - the tokens files.
+ * @param dir - the configuration's folder, which problems name files from.
+ */
+export declare const tokenThemeOf: (mapping: TokenMapping, files: readonly TokensFileRef[], dir: string) => TokenTheme;
+export {};

package/dist/src/vite/themeFromTokens.js

@@ -0,0 +1,73 @@
+/**
+ * A shell's theme from a library's design tokens: a few lines of mapping instead of a palette written twice.
+ *
+ * @remarks
+ * Read once, when the configuration is, since the theme is written into the page at build. A role takes the token's value
+ * in each appearance, the themes named `light` and `dark` first: a token with no such theme holds in both, as DTCG means,
+ * and the contrast checks say when that does not work. What cannot be used is reported, never a build's failure: the
+ * shell keeps its own colour for that role.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { relative } from "node:path";
+import { readTokens } from "./designTokens.js";
+/** A token's colour in an appearance; none when only other themes define it. */
+const colorIn = (token, appearance) => token.modes[appearance] ?? (token.isThemeOnly === true ? undefined : token.value);
+/**
+ * The theme a mapping gives.
+ *
+ * @param mapping - the token's name for each role.
+ * @param tokens - the tokens.
+ * @returns the colours of each appearance, and what could not be used.
+ */
+export const tokenTheme = (mapping, tokens) => {
+    const light = {};
+    const dark = {};
+    const problems = [];
+    for (const [role, name] of Object.entries(mapping)) {
+        const token = tokens.find((each) => each.name === name);
+        if (token === undefined) {
+            problems.push(`shell.theme.fromTokens: ${role} names "${name}", which is not a token`);
+        }
+        else if (token.type !== "color") {
+            problems.push(`shell.theme.fromTokens: ${role} names "${name}", a ${token.type}, not a color`);
+        }
+        else {
+            const inLight = colorIn(token, "light");
+            const inDark = colorIn(token, "dark");
+            if (inLight !== undefined)
+                light[role] = inLight;
+            if (inDark !== undefined)
+                dark[role] = inDark;
+        }
+    }
+    return { theme: { light, dark }, problems };
+};
+/**
+ * Reads a catalogue's tokens files and the theme a mapping gives; no mapping reads nothing.
+ *
+ * @param mapping - the token's name for each role.
+ * @param files - the tokens files.
+ * @param dir - the configuration's folder, which problems name files from.
+ */
+export const tokenThemeOf = (mapping, files, dir) => {
+    if (Object.keys(mapping).length === 0)
+        return { theme: {}, problems: [] };
+    if (files.length === 0) {
+        return { theme: {}, problems: ["shell.theme.fromTokens: the configuration names no tokens file"] };
+    }
+    const unread = [];
+    const inputs = files.flatMap(({ path, mode }) => {
+        try {
+            return [{ label: relative(dir, path), mode, file: JSON.parse(readFileSync(path, "utf8")) }];
+        }
+        catch (error) {
+            unread.push(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+    });
+    const { tokens, problems } = readTokens(inputs);
+    const { theme, problems: mapped } = tokenTheme(mapping, tokens);
+    return { theme, problems: [...unread, ...problems, ...mapped] };
+};

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

@@ -0,0 +1,20 @@
+/**
+ * The answers about a catalogue's design tokens, from tokens already read: the dev server reads its files at each
+ * question, a built catalogue has them in its index.
+ *
+ * @module
+ */
+import type { AgentTokenSummary } from "./agent.types.ts";
+import type { AgentAnswer } from "./agentRoutes.ts";
+import { type DesignToken, type ParsedTokens } from "./designTokens.ts";
+/** The tokens read, with whether anything names some: a file that cannot be read is named, which is not "no tokens". */
+export type TokenReading = ParsedTokens & {
+    /** Whether the catalogue or a source names a tokens file. */
+    readonly isConfigured: boolean;
+    /** The sources whose modules could not be read: whether they hold tokens is not known. */
+    readonly unread: readonly string[];
+};
+/** A token as a list gives it: no description, and no empty fields, since each one costs an agent's context. */
+export declare const tokenSummary: (token: DesignToken) => AgentTokenSummary;
+/** The token questions, by the API's path. */
+export declare const TOKEN_ANSWERS: Readonly<Record<string, (reading: TokenReading, params: URLSearchParams) => AgentAnswer>>;

package/dist/src/vite/tokenAnswers.js

@@ -0,0 +1,86 @@
+import { filteredTokens } from "./designTokens.js";
+import { nearestTokens } from "./nearestToken.js";
+/** A list's size unless asked otherwise: an agent degrades on long answers, and asks `nearest` or one token. */
+const TOKENS_LIMIT = 100;
+/** The one answer a question about a catalogue with no tokens gets, so an agent does not read it as "no such token". */
+const NO_TOKENS_FILE = {
+    status: 404,
+    body: {
+        error: 'This catalogue names no tokens file: `tokens: ["tokens.json"]` in forgebook.config.ts, or on a source it shows'
+    }
+};
+/** How many tokens of each type. */
+const typeCounts = (tokens) => {
+    const counts = {};
+    for (const { type } of tokens)
+        counts[type] = (counts[type] ?? 0) + 1;
+    return counts;
+};
+/** A token as a list gives it: no description, and no empty fields, since each one costs an agent's context. */
+export const tokenSummary = (token) => {
+    const { name, type, value, modes, deprecated, isThemeOnly } = token;
+    return {
+        name,
+        type,
+        value,
+        modes,
+        ...(deprecated === undefined ? {} : { deprecated }),
+        ...(isThemeOnly === undefined ? {} : { isThemeOnly })
+    };
+};
+/** The tokens, of a category when one is asked for, up to a limit, with how many there are. */
+const tokensAnswer = ({ tokens, problems, unread, clashes, isConfigured }, params) => {
+    const chosen = filteredTokens(tokens, params.get("category") || undefined);
+    const limit = Number(params.get("limit") || TOKENS_LIMIT);
+    const listed = chosen.slice(0, Number.isFinite(limit) ? limit : TOKENS_LIMIT);
+    const names = new Set(listed.map((token) => token.name));
+    const body = {
+        schema: 1,
+        isConfigured,
+        total: chosen.length,
+        types: typeCounts(chosen),
+        tokens: listed.map(tokenSummary),
+        problems: [...unread, ...problems],
+        clashes: clashes.filter((clash) => names.has(clash.name))
+    };
+    return { status: 200, body };
+};
+/** One token; what broke in the files is said, since a token that failed to read looks like one that is not there. */
+const tokenAnswer = (reading, params) => {
+    if (!reading.isConfigured)
+        return NO_TOKENS_FILE;
+    const { tokens, clashes } = reading;
+    const problems = [...reading.unread, ...reading.problems];
+    const name = params.get("name") ?? "";
+    const token = tokens.find((each) => each.name === name);
+    if (token === undefined) {
+        const read = problems.length === 0 ? "" : ` (and the tokens files have problems: ${problems.join("; ")})`;
+        return { status: 404, body: { error: `No token "${name}"${read}` } };
+    }
+    const body = {
+        schema: 1,
+        token,
+        problems,
+        clashes: clashes.filter((clash) => clash.name === name)
+    };
+    return { status: 200, body };
+};
+/** The tokens nearest a value; a question that cannot be answered is an error, never an empty list. */
+const nearestTokenAnswer = ({ tokens, problems, unread, isConfigured }, params) => {
+    if (!isConfigured)
+        return NO_TOKENS_FILE;
+    const value = params.get("value") ?? "";
+    if (value === "")
+        return { status: 400, body: { error: "No value to compare" } };
+    const nearest = nearestTokens(tokens, value, params.get("type") || undefined);
+    if (nearest.reason !== undefined)
+        return { status: 400, body: { error: nearest.reason } };
+    const body = { schema: 1, value, ...nearest, problems: [...unread, ...problems] };
+    return { status: 200, body };
+};
+/** The token questions, by the API's path. */
+export const TOKEN_ANSWERS = {
+    tokens: tokensAnswer,
+    token: tokenAnswer,
+    "nearest-token": nearestTokenAnswer
+};

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

@@ -0,0 +1,44 @@
+/**
+ * The tokens two authors name with different values: a catalogue and a library it shows, or two libraries.
+ *
+ * @remarks
+ * Pure, kept apart from reading the format. One author's files are layers and replace each other on purpose, so only a
+ * change of author counts, and the same value from two authors is not a clash: a catalogue that still lists a library's
+ * file, or two sources of one package, agree. Each theme is compared with itself: a catalogue giving a dark value to a
+ * library's token that has none adds to it and replaces nothing.
+ *
+ * @module
+ */
+/** A name two authors give different values. */
+export type TokenClash = {
+    /** The token's name. */
+    readonly name: string;
+    /** The theme the values are in; none for the base. */
+    readonly mode?: string;
+    /** The file whose value stands, by what problems call it: the last one, so the catalogue's when it names the token. */
+    readonly kept: string;
+    /** The files it replaced. */
+    readonly replaced: readonly string[];
+};
+/** A token as far as a clash reads it. */
+type WrittenToken = {
+    /** Its name. */
+    readonly name: string;
+    /** Its value, as the file writes it. */
+    readonly value: unknown;
+    /** Its file, by what problems call it. */
+    readonly label: string;
+    /** The source it comes from; none for the catalogue. */
+    readonly source: string | undefined;
+};
+/**
+ * The clashes between files.
+ *
+ * @param files - each file's theme and tokens, in the order they are read.
+ * @returns one clash per name and theme, in the files' order.
+ */
+export declare const tokenClashes: (files: readonly {
+    readonly mode: string | undefined;
+    readonly raw: readonly WrittenToken[];
+}[]) => TokenClash[];
+export {};

package/dist/src/vite/tokenClashes.js

@@ -0,0 +1,45 @@
+/**
+ * The tokens two authors name with different values: a catalogue and a library it shows, or two libraries.
+ *
+ * @remarks
+ * Pure, kept apart from reading the format. One author's files are layers and replace each other on purpose, so only a
+ * change of author counts, and the same value from two authors is not a clash: a catalogue that still lists a library's
+ * file, or two sources of one package, agree. Each theme is compared with itself: a catalogue giving a dark value to a
+ * library's token that has none adds to it and replaces nothing.
+ *
+ * @module
+ */
+/** Each other author's last word on a name, when it differs from the value that stands. */
+const replacedBy = (latest, tokens) => {
+    const byAuthor = new Map(tokens.map((token) => [token.source, token]));
+    const standing = JSON.stringify(latest.value);
+    return [...byAuthor.values()]
+        .filter((token) => token.source !== latest.source && JSON.stringify(token.value) !== standing)
+        .map((token) => token.label);
+};
+/**
+ * The clashes between files.
+ *
+ * @param files - each file's theme and tokens, in the order they are read.
+ * @returns one clash per name and theme, in the files' order.
+ */
+export const tokenClashes = (files) => {
+    const written = new Map();
+    for (const { mode, raw } of files) {
+        for (const token of raw) {
+            const key = JSON.stringify([mode ?? null, token.name]);
+            const known = written.get(key);
+            if (known === undefined)
+                written.set(key, { name: token.name, mode, tokens: [token] });
+            else
+                known.tokens.push(token);
+        }
+    }
+    return [...written.values()].flatMap(({ name, mode, tokens }) => {
+        const latest = tokens.at(-1);
+        const replaced = latest === undefined ? [] : replacedBy(latest, tokens);
+        if (latest === undefined || replaced.length === 0)
+            return [];
+        return [{ name, ...(mode === undefined ? {} : { mode }), kept: latest.label, replaced }];
+    });
+};

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

@@ -32,4 +32,3 @@ export declare const touchMediaRules: (rule: Extract<Rule, {
  * hover.
  */
 export declare const NOT_UNDER_TOUCH: SelectorComponent;
-//# sourceMappingURL=touchMedia.d.ts.map

package/dist/src/vite/touchMedia.js

@@ -288,4 +288,3 @@ export const NOT_UNDER_TOUCH = {
         ]
     ]
 };
-//# sourceMappingURL=touchMedia.js.map

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

@@ -20,4 +20,3 @@ export declare const isTypeScriptLanguage: (language: string) => boolean;
  * @param language - its fence name (`tsx`, `ts`, `js`, `jsx`…); one outside the family is read as TSX.
  */
 export declare const typeScriptPieces: (code: string, language: string) => CodePiece[];
-//# sourceMappingURL=typeScriptPieces.d.ts.map

package/dist/src/vite/typeScriptPieces.js

@@ -3,8 +3,8 @@
  * the TypeScript compiler's syntactic classifications, for `highlightCode.ts` to colour.
  *
  * @remarks
- * highlight.js has no JSX grammar: it reads JSX as HTML, so an attribute holding a function or a `>` ends the tag
- * early and the rest of the example is left plain. The compiler parses JSX as the language defines it.
+ * The compiler parses JSX as the language defines it: read as HTML, an attribute holding a function or a `>` would end
+ * the tag early and leave the rest of the example plain.
  *
  * One language service in syntactic mode, created on the first block and kept: it parses the block alone (no
  * program, no library, no type checker), so a block costs a parse, not a type check. Its classifications tell
@@ -233,4 +233,3 @@ export const typeScriptPieces = (code, language) => {
     push(code.length);
     return pieces;
 };
-//# sourceMappingURL=typeScriptPieces.js.map

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

@@ -38,8 +38,13 @@ export type UsageRequestFile = {
 /**
  * The facts of a group of story files: what each story renders, and the import graph the rendered components reach.
  *
+ * @remarks
+ * A monorepo has a configuration per package, and holding every package's whole program at once is what stops a
+ * worker: the story files a configuration holds are read together, so a configuration's program is let go with the
+ * others the docs no longer keep (`KEPT_PROGRAMS`) once its group is read. An import graph is followed inside the
+ * program that holds its start, which holds what that start imports.
+ *
  * @param requests - the story files and their stories' exports.
  * @returns the facts, or why a story file's program could not be read.
  */
 export declare const usageGraph: (requests: readonly UsageRequestFile[]) => UsageGraph | string;
-//# sourceMappingURL=usageGraph.d.ts.map

package/dist/src/vite/usageGraph.js

@@ -15,7 +15,8 @@
  * @module
  */
 import ts from "typescript-6";
-import { programFor } from "./docsProgram.js";
+import { configurationOf, programFor } from "./docsProgram.js";
+import { VITE_PATHS } from "./vitePaths.js";
 /**
  * The symbol a name stands for, through its imports and re-exports.
  *
@@ -244,16 +245,17 @@ const reachedImports = (starts, programs) => {
     return imports;
 };
 /**
- * The facts of a group of story files: what each story renders, and the import graph the rendered components reach.
+ * The facts of the story files one configuration holds, read with that configuration's whole program.
  *
- * @param requests - the story files and their stories' exports.
+ * @param group - the story files, in Vite's form, each held by the same configuration.
  * @returns the facts, or why a story file's program could not be read.
  */
-export const usageGraph = (requests) => {
+const groupGraph = (group) => {
     const files = [];
     const programs = new Set();
-    for (const request of requests) {
-        const docsProgram = programFor(request.storyFile);
+    for (const request of group) {
+        // what every story of the configuration reaches: its whole program, built once
+        const docsProgram = programFor(request.storyFile, { reach: "whole" });
         if (typeof docsProgram === "string")
             return docsProgram;
         programs.add(docsProgram.program);
@@ -267,4 +269,36 @@ export const usageGraph = (requests) => {
     ]);
     return { files, imports: reachedImports([...new Set(starts)], [...programs]) };
 };
-//# sourceMappingURL=usageGraph.js.map
+/**
+ * The facts of a group of story files: what each story renders, and the import graph the rendered components reach.
+ *
+ * @remarks
+ * A monorepo has a configuration per package, and holding every package's whole program at once is what stops a
+ * worker: the story files a configuration holds are read together, so a configuration's program is let go with the
+ * others the docs no longer keep (`KEPT_PROGRAMS`) once its group is read. An import graph is followed inside the
+ * program that holds its start, which holds what that start imports.
+ *
+ * @param requests - the story files and their stories' exports.
+ * @returns the facts, or why a story file's program could not be read.
+ */
+export const usageGraph = (requests) => {
+    const byConfiguration = new Map();
+    for (const asked of requests) {
+        // in Vite's form, as TypeScript names the files the graph is made of, so a story file meets its components
+        const request = { ...asked, storyFile: VITE_PATHS.normalize(asked.storyFile) };
+        const key = configurationOf(request.storyFile);
+        byConfiguration.set(key, [...(byConfiguration.get(key) ?? []), request]);
+    }
+    const files = [];
+    const imports = {};
+    for (const group of byConfiguration.values()) {
+        const graph = groupGraph(group);
+        if (typeof graph === "string")
+            return graph;
+        files.push(...graph.files);
+        // a file two configurations hold imports, for each, what its options resolve: both are followed
+        for (const [file, targets] of Object.entries(graph.imports))
+            imports[file] = [...new Set([...(imports[file] ?? []), ...targets])];
+    }
+    return { files, imports };
+};

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

@@ -0,0 +1,33 @@
+/**
+ * When to use a component and when not, read from its TSDoc tags. Shared by the frameworks' docs modules: a framework
+ * whose components have no symbol to carry a comment (a Vue single-file component) hands the tags it read itself.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import type { UsageGuidance } from "../componentDocs.ts";
+/** One TSDoc tag, read. */
+export type DocTag = {
+    /** The tag's name, without its `@` (`useWhen`). */
+    readonly name: string;
+    /** Its text; empty when it has none. */
+    readonly text: string;
+};
+/**
+ * The field of a component's docs saying when to use it and when not; none when its TSDoc says nothing, so most
+ * components carry nothing.
+ *
+ * @param tags - the component's TSDoc tags.
+ */
+export declare const guidanceOfTags: (tags: readonly DocTag[]) => {
+    readonly guidance?: UsageGuidance;
+};
+/**
+ * The field of a component's docs saying when to use it and when not, from its symbol's TSDoc.
+ *
+ * @param symbol - the component.
+ * @param checker - the program's type checker.
+ */
+export declare const guidanceOf: (symbol: ts.Symbol, checker: ts.TypeChecker) => {
+    readonly guidance?: UsageGuidance;
+};