forgebook 0.1.8 → 0.3.0

package/dist/src/vite/storyMeta.js

@@ -1,33 +1,64 @@
 /**
- * A story file's meta, read from its source with the TypeScript compiler's parser: the value of one of its fields, the
- * component it names and the module it imports that component from.
+ * A story file's meta, read from its source with the TypeScript compiler's parser, for the docs: the value of one of its
+ * fields, the component it names and its subcomponents.
  *
  * @remarks
- * CSF is the same whatever framework a story is written for, so the plugin, `forgebook-docs` and every framework's
- * docs extractor read the meta through this module. Pure: a parsed file in, nodes or a specifier out.
+ * CSF is the same whatever framework a story is written for, so `forgebook-docs` and every framework's docs extractor
+ * read the meta through this module, inside their TypeScript program. The plugin's own reading, outside any program,
+ * is `componentImport.ts`. Pure: a parsed file in, nodes out.
  *
  * @module
  */
 import ts from "typescript-6";
 /**
- * The meta's object literal in a story file: its default export, without `satisfies`, `as` and parentheses.
+ * The value a constant at the top of the file is declared with, without its wrappers.
+ *
+ * @param source - the file, parsed.
+ * @param name - the constant's name.
+ */
+const constantValue = (source, name) => {
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        const declaration = statement.declarationList.declarations.find((each) => ts.isIdentifier(each.name) && each.name.text === name);
+        if (declaration?.initializer !== undefined)
+            return unwrapped(declaration.initializer);
+    }
+    return undefined;
+};
+/**
+ * The expression a story file exports as its default: `export default …`, or the local name of
+ * `export { meta as default }`.
  *
  * @param source - the story file, parsed.
  */
-const metaObject = (source) => {
+const defaultExport = (source) => {
     for (const statement of source.statements) {
-        if (!ts.isExportAssignment(statement) || statement.isExportEquals)
+        if (ts.isExportAssignment(statement) && !statement.isExportEquals)
+            return unwrapped(statement.expression);
+        if (!ts.isExportDeclaration(statement) || statement.moduleSpecifier !== undefined)
             continue;
-        let expression = statement.expression;
-        while (ts.isSatisfiesExpression(expression) ||
-            ts.isAsExpression(expression) ||
-            ts.isParenthesizedExpression(expression)) {
-            expression = expression.expression;
-        }
-        return ts.isObjectLiteralExpression(expression) ? expression : undefined;
+        const clause = statement.exportClause;
+        const specifier = clause !== undefined && ts.isNamedExports(clause)
+            ? clause.elements.find((element) => element.name.text === "default")
+            : undefined;
+        if (specifier !== undefined)
+            return specifier.propertyName ?? specifier.name;
     }
     return undefined;
 };
+/**
+ * The meta's object literal in a story file: its default export, written in place or held in a constant of the file
+ * (`export default meta`, `export { meta as default }`), as Storybook reads it; without `satisfies`, `as` and
+ * parentheses.
+ *
+ * @param source - the story file, parsed.
+ */
+const metaObject = (source) => {
+    const exported = defaultExport(source);
+    const value = exported !== undefined && ts.isIdentifier(exported) ? constantValue(source, exported.text) : exported;
+    return value !== undefined && ts.isObjectLiteralExpression(value) ? value : undefined;
+};
 /**
  * The value the meta writes for one of its fields.
  *
@@ -44,31 +75,36 @@ export const metaField = (source, name) => {
  * @param source - the story file, parsed.
  */
 export const metaComponent = (source) => metaField(source, "component");
+/** An expression without the wrappers around a literal list (`as const`, `satisfies`, parentheses). */
+export const unwrapped = (expression) => {
+    let inner = expression;
+    while (ts.isAsExpression(inner) || ts.isSatisfiesExpression(inner) || ts.isParenthesizedExpression(inner)) {
+        inner = inner.expression;
+    }
+    return inner;
+};
 /**
- * The module a story file imports its meta's component from (`./Button`), read from the file alone: no program, so
- * it answers at once, where the docs need the package's program.
+ * The subcomponents the meta names, in the order it writes them: `subcomponents: { ChipList, Items: MenuItem }`.
  *
- * @param storyFile - the story file's path, for the parser.
- * @param text - the story file's text.
- * @returns the import's module specifier, or none when the meta names no imported component.
+ * @param source - the story file, parsed.
+ * @param checker - the program's checker.
  */
-export const componentImport = (storyFile, text) => {
-    const source = ts.createSourceFile(storyFile, text, ts.ScriptTarget.Latest, true);
-    const expression = metaComponent(source);
-    if (expression === undefined || !ts.isIdentifier(expression))
-        return undefined;
-    const name = expression.text;
-    for (const statement of source.statements) {
-        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
-            continue;
-        const clause = statement.importClause;
-        const bindings = clause?.namedBindings;
-        const isNamed = bindings !== undefined &&
-            ts.isNamedImports(bindings) &&
-            bindings.elements.some((element) => element.name.text === name);
-        if (clause?.name?.text === name || isNamed)
-            return statement.moduleSpecifier.text;
-    }
-    return undefined;
+export const metaSubcomponents = (source, checker) => {
+    const field = metaField(source, "subcomponents");
+    const object = field === undefined ? undefined : unwrapped(field);
+    if (object === undefined || !ts.isObjectLiteralExpression(object))
+        return [];
+    return object.properties.flatMap((property) => {
+        if (ts.isShorthandPropertyAssignment(property)) {
+            const symbol = checker.getShorthandAssignmentValueSymbol(property);
+            return [{ name: property.name.text, expression: property.name, symbol }];
+        }
+        if (!ts.isPropertyAssignment(property))
+            return [];
+        const name = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name)
+            ? property.name.text
+            : property.name.getText(source);
+        const symbol = checker.getSymbolAtLocation(property.initializer);
+        return [{ name, expression: property.initializer, symbol }];
+    });
 };
-//# sourceMappingURL=storyMeta.js.map

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

@@ -0,0 +1,18 @@
+/**
+ * A story file parsed with Vite's parser, as the index and the story's code read it.
+ *
+ * @remarks
+ * A `.js` story file parses as JSX: the libraries that write their stories in JavaScript write JSX there (Carbon's
+ * do), and JSX is a superset of what a `.js` file can otherwise hold. Without it such a file is an error and its stories
+ * are missing from the sidebar.
+ *
+ * @module
+ */
+import { parseSync } from "vite";
+/**
+ * A story file parsed.
+ *
+ * @param file - the file's path; its extension decides TypeScript and JSX.
+ * @param text - the file's source.
+ */
+export declare const parseStoryFile: (file: string, text: string) => ReturnType<typeof parseSync>;

package/dist/src/vite/storyParse.js

@@ -0,0 +1,20 @@
+/**
+ * A story file parsed with Vite's parser, as the index and the story's code read it.
+ *
+ * @remarks
+ * A `.js` story file parses as JSX: the libraries that write their stories in JavaScript write JSX there (Carbon's
+ * do), and JSX is a superset of what a `.js` file can otherwise hold. Without it such a file is an error and its stories
+ * are missing from the sidebar.
+ *
+ * @module
+ */
+import { parseSync } from "vite";
+/** The extension of a file that says nothing about JSX. */
+const PLAIN_SCRIPT = /\.[cm]?js$/;
+/**
+ * A story file parsed.
+ *
+ * @param file - the file's path; its extension decides TypeScript and JSX.
+ * @param text - the file's source.
+ */
+export const parseStoryFile = (file, text) => parseSync(file, text, PLAIN_SCRIPT.test(file) ? { lang: "jsx" } : {});

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

@@ -0,0 +1,39 @@
+import { type VitePaths } from "./vitePaths.ts";
+/**
+ * Whether a pattern leaves files out (`!src/**\/legacy/*`) rather than listing them. One that starts with an extglob's
+ * `!(…)` lists the names its group does not match, as fast-glob reads it.
+ *
+ * @param pattern - the pattern.
+ */
+export declare const isNegated: (pattern: string) => boolean;
+/**
+ * Why a list of patterns lists nothing by construction, or none: every pattern in it is a `!` one, which only leaves
+ * files out of what the others list.
+ *
+ * @param patterns - the patterns.
+ */
+export declare const patternsProblem: (patterns: readonly string[]) => string | undefined;
+/**
+ * The paths one pattern matches, as Node's `globSync` gives them (backslashes on Windows), relative to the folder.
+ *
+ * @param root - the folder the pattern is relative to.
+ * @param pattern - the pattern, without a `!`.
+ */
+export type FindFiles = (root: string, pattern: string) => readonly string[];
+/** A file a list of patterns lists, with the pattern that lists it. */
+export type ListedFile = {
+    /** Its path relative to the patterns' folder, starting with `./` or `../`, with forward slashes. */
+    readonly key: string;
+    /** The first pattern that lists it: its static start begins the file's title when its meta writes none. */
+    readonly pattern: string;
+};
+/**
+ * The files a list of patterns lists, each once, sorted by key.
+ *
+ * @param root - the folder the patterns are relative to: the declaring module's.
+ * @param patterns - the patterns (`../src/**\/*.stories.tsx`, `!../src/**\/legacy/*`), in any order.
+ * @param find - what matches one pattern; the disk's by default, another system's in a test.
+ * @param paths - the path functions; the running system's unless a test names another.
+ * @throws when every pattern is a `!` one (`patternsProblem`).
+ */
+export declare const listedFiles: (root: string, patterns: readonly string[], find?: FindFiles, paths?: VitePaths) => ListedFile[];

package/dist/src/vite/storyPatterns.js

@@ -0,0 +1,100 @@
+/**
+ * The files a list of patterns names, as Vite's `import.meta.glob` and fast-glob read one: the union of its patterns,
+ * less what its `!` patterns match, whatever their order. Used for a catalogue's story files and docs pages, by the
+ * plugin and by the testing package, so both list the same files.
+ *
+ * @remarks
+ * A `!` pattern is matched by the same engine as the others (Node's `globSync`), from the same folder, so it follows
+ * the same syntax: `!src/**\/legacy/*.stories.tsx` leaves out what `src/**\/legacy/*.stories.tsx` would list, and one
+ * that matches a folder (`!src/drafts`) leaves out every file in it, as fast-glob does. A file two
+ * patterns list is listed once, by the first, whose static start begins its title (as Storybook's first specifier
+ * does). A list of `!` patterns alone lists nothing, which is a mistake, never what its author meant: it is refused.
+ *
+ * @module
+ */
+import { globSync } from "node:fs";
+import { VITE_PATHS } from "./vitePaths.js";
+/** What starts a pattern that leaves files out. */
+const NEGATION = "!";
+/**
+ * Whether a pattern leaves files out (`!src/**\/legacy/*`) rather than listing them. One that starts with an extglob's
+ * `!(…)` lists the names its group does not match, as fast-glob reads it.
+ *
+ * @param pattern - the pattern.
+ */
+export const isNegated = (pattern) => pattern.startsWith(NEGATION) && !pattern.startsWith(`${NEGATION}(`);
+/**
+ * Why a list of patterns lists nothing by construction, or none: every pattern in it is a `!` one, which only leaves
+ * files out of what the others list.
+ *
+ * @param patterns - the patterns.
+ */
+export const patternsProblem = (patterns) => patterns.length > 0 && patterns.every(isNegated)
+    ? `every pattern is a \`!\` one (${patterns.map((pattern) => `"${pattern}"`).join(", ")}), which only leaves files out of what the others list: add a pattern that lists files beside them`
+    : undefined;
+/** The folder of a project's dependencies. */
+const DEPENDENCIES = "node_modules";
+/**
+ * What a pattern leaves out: the dependencies, unless it names them. A `**` from a monorepo's root would otherwise walk
+ * every package's, seconds on the server's thread for files nobody asked for, as Storybook's own globs skip them.
+ *
+ * @param pattern - the pattern.
+ */
+const excludedFrom = (pattern) => pattern.includes(DEPENDENCIES) ? () => false : (name) => name === DEPENDENCIES;
+/** The files a pattern matches on the disk, the dependencies left out unless it names them. */
+const globbed = (root, pattern) => globSync(pattern, { cwd: root, exclude: excludedFrom(pattern) });
+/**
+ * Whether a file is left out: a `!` pattern matched it, or one of the folders it is in (`!src/drafts`), as fast-glob
+ * leaves out a folder's every file.
+ *
+ * @param key - the file's key (`./src/drafts/x.stories.tsx`).
+ * @param left - the keys of the files and folders the `!` patterns matched.
+ */
+const isLeftOut = (key, left) => {
+    const segments = key.split("/");
+    return segments.some((_segment, at) => at > 0 && left.has(segments.slice(0, at + 1).join("/")));
+};
+/**
+ * A pattern without its trailing slashes (`src/drafts/`): the glob gives the folder it names without them. A loop,
+ * not a regular expression, whose backtracking a long run of slashes would make quadratic.
+ *
+ * @param pattern - the pattern.
+ */
+const withoutTrailingSlashes = (pattern) => {
+    let end = pattern.length;
+    while (end > 0 && pattern[end - 1] === "/")
+        end -= 1;
+    return pattern.slice(0, end);
+};
+/**
+ * The files a list of patterns lists, each once, sorted by key.
+ *
+ * @param root - the folder the patterns are relative to: the declaring module's.
+ * @param patterns - the patterns (`../src/**\/*.stories.tsx`, `!../src/**\/legacy/*`), in any order.
+ * @param find - what matches one pattern; the disk's by default, another system's in a test.
+ * @param paths - the path functions; the running system's unless a test names another.
+ * @throws when every pattern is a `!` one (`patternsProblem`).
+ */
+export const listedFiles = (root, patterns, find = globbed, paths = VITE_PATHS) => {
+    const problem = patternsProblem(patterns);
+    if (problem !== undefined)
+        throw new Error(problem);
+    // with forward slashes on every system, so a file has the same key wherever the catalogue runs
+    const keysOf = (pattern) => find(root, pattern).map((file) => paths.relativeKey(root, file));
+    const listing = patterns.filter((each) => !isNegated(each));
+    // a `!` pattern that names the dependencies leaves out only what a listing one names there: walked otherwise, it
+    // would read every package's folder for files no pattern lists
+    const isWalkedFor = (pattern) => !pattern.includes(DEPENDENCIES) || listing.some((each) => each.includes(DEPENDENCIES));
+    const left = new Set(patterns
+        .filter((each) => isNegated(each) && isWalkedFor(each))
+        .flatMap((pattern) => keysOf(withoutTrailingSlashes(pattern.slice(NEGATION.length)))));
+    const listed = new Map();
+    for (const pattern of listing)
+        for (const key of keysOf(pattern))
+            if (!isLeftOut(key, left) && !listed.has(key))
+                listed.set(key, pattern);
+    // by code unit, as a plain `sort()` orders the keys: the keys are unique
+    return [...listed]
+        .sort(([first], [second]) => (first < second ? -1 : 1))
+        .map(([key, pattern]) => ({ key, pattern }));
+};

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

@@ -0,0 +1,29 @@
+/**
+ * Whether a story file writes a `play` for a story, read without running it: the story's own field, one assigned to it
+ * (`Story.play = …`), or one it takes from a story of the file it spreads (`{ ...Other, args }`).
+ *
+ * @remarks
+ * Among an object's fields the last one written wins, as when it runs. A `play` spread from another file, or written
+ * by code the index cannot follow, is not seen. Pure.
+ *
+ * @module
+ */
+import type { ESTree } from "vite";
+/** What the file's top level holds, by local name. */
+export type StoryValues = {
+    /** Each constant's value. */
+    readonly values: ReadonlyMap<string, ESTree.Expression>;
+    /** The properties assigned to each name after its declaration. */
+    readonly assigned: ReadonlyMap<string, ReadonlyMap<string, ESTree.Expression>>;
+};
+/**
+ * The index's field for a `play`: set when the story has one of its own or the meta does, which runs for every story
+ * of the file; left out otherwise.
+ *
+ * @param local - the story's local name; none for a story re-exported from another file, whose own `play` is not seen.
+ * @param top - the file's top level.
+ * @param metaPlay - the meta's `play`; none when it writes none.
+ */
+export declare const playField: (local: string | undefined, top: StoryValues, metaPlay: ESTree.Expression | undefined) => {
+    readonly hasPlay?: true;
+};

package/dist/src/vite/storyPlay.js

@@ -0,0 +1,54 @@
+/**
+ * Whether an expression is a `play`: `undefined` written out takes one away.
+ *
+ * @param value - the field's value; none when there is no such field.
+ */
+const isPlay = (value) => value !== undefined && !(value.type === "Identifier" && value.name === "undefined");
+/**
+ * What an object says of `play`, its last word first; none when it says nothing.
+ *
+ * @param object - the object.
+ * @param top - the file's top level, for what it spreads.
+ * @param seen - the names followed so far, so stories spreading each other end.
+ */
+const objectPlay = (object, top, seen) => {
+    for (const property of object.properties.toReversed()) {
+        if (property.type === "SpreadElement") {
+            const spread = property.argument;
+            const said = spread.type === "Identifier" ? namedPlay(spread.name, top, seen) : undefined;
+            if (said !== undefined)
+                return said;
+        }
+        else if (!property.computed && property.key.type === "Identifier" && property.key.name === "play") {
+            return isPlay(property.value);
+        }
+    }
+    return undefined;
+};
+/**
+ * What a local name says of `play`: an assignment outranks its object's fields, since it runs after them.
+ *
+ * @param name - the local name.
+ * @param top - the file's top level.
+ * @param seen - the names followed so far.
+ */
+const namedPlay = (name, top, seen) => {
+    if (seen.has(name))
+        return undefined;
+    const assigned = top.assigned.get(name)?.get("play");
+    if (assigned !== undefined)
+        return isPlay(assigned);
+    const value = top.values.get(name);
+    return value?.type === "ObjectExpression" ? objectPlay(value, top, new Set([...seen, name])) : undefined;
+};
+/**
+ * The index's field for a `play`: set when the story has one of its own or the meta does, which runs for every story
+ * of the file; left out otherwise.
+ *
+ * @param local - the story's local name; none for a story re-exported from another file, whose own `play` is not seen.
+ * @param top - the file's top level.
+ * @param metaPlay - the meta's `play`; none when it writes none.
+ */
+export const playField = (local, top, metaPlay) => (local !== undefined && namedPlay(local, top, new Set()) === true) || isPlay(metaPlay)
+    ? { hasPlay: true }
+    : {};

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

@@ -0,0 +1,42 @@
+/**
+ * Which stories a change touches: each story with the files it reaches, and from changed files back to stories.
+ *
+ * @remarks
+ * Pure, on the same graph "Used in" reads (`usageGraph.ts`), so what cannot be followed there cannot be followed here: a
+ * computed lazy import, a component handed in as a prop. A story file reaches its meta's component whatever its stories
+ * render, since a story with no JSX draws that component. Style sheets and other files outside the graph are not known
+ * to reach anything: `verify` says so by checking the stories it can name, not by claiming the rest are safe.
+ *
+ * @module
+ */
+import type { UsageGraph } from "./usageGraph.ts";
+/** A story file's title, to name its stories by. */
+export type ReachFile = {
+    /** The story file's absolute path. */
+    readonly storyFile: string;
+    /** Its title. */
+    readonly title: string;
+};
+/** A story with what it reaches. */
+export type ReachedStory = {
+    /** Its component's title. */
+    readonly title: string;
+    /** Its export. */
+    readonly exportName: string;
+    /** Every file it reaches, its own story file included, absolute. */
+    readonly files: readonly string[];
+};
+/**
+ * Each story with the files it reaches.
+ *
+ * @param graph - what the stories render and what the modules import.
+ * @param files - each story file's title.
+ */
+export declare const storyReach: (graph: UsageGraph, files: readonly ReachFile[]) => ReachedStory[];
+/**
+ * The stories that reach any of the changed files, each once, in the graph's order.
+ *
+ * @param reach - each story with what it reaches.
+ * @param changed - the changed files, absolute.
+ */
+export declare const affectedStories: (reach: readonly ReachedStory[], changed: readonly string[]) => ReachedStory[];

package/dist/src/vite/storyReach.js

@@ -0,0 +1,43 @@
+/** The files a module reaches, itself included, through the graph's imports. */
+const reachedFrom = (imports, starts) => {
+    const reached = new Set();
+    const queue = [...starts];
+    while (queue.length > 0) {
+        const file = queue.pop() ?? "";
+        if (reached.has(file))
+            continue;
+        reached.add(file);
+        queue.push(...(imports[file] ?? []));
+    }
+    return reached;
+};
+/**
+ * Each story with the files it reaches.
+ *
+ * @param graph - what the stories render and what the modules import.
+ * @param files - each story file's title.
+ */
+export const storyReach = (graph, files) => {
+    const titles = new Map(files.map((file) => [file.storyFile, file.title]));
+    return graph.files.flatMap((file) => file.stories.map((story) => ({
+        title: titles.get(file.storyFile) ?? "",
+        exportName: story.exportName,
+        files: [
+            ...reachedFrom(graph.imports, [
+                file.storyFile,
+                ...(file.component === undefined ? [] : [file.component.file]),
+                ...story.renders.map((ref) => ref.file)
+            ])
+        ]
+    })));
+};
+/**
+ * The stories that reach any of the changed files, each once, in the graph's order.
+ *
+ * @param reach - each story with what it reaches.
+ * @param changed - the changed files, absolute.
+ */
+export const affectedStories = (reach, changed) => {
+    const files = new Set(changed);
+    return reach.filter((story) => story.files.some((file) => files.has(file)));
+};

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

@@ -0,0 +1,29 @@
+import type { AgentAnswer } from "./agentRoutes.ts";
+import type { ResolvedConfig } from "./configFile.ts";
+import { type TokenReading } from "./tokenAnswers.ts";
+/** Finds the file of a source's module specifier. */
+export type ResolveSource = (specifier: string) => Promise<string | undefined>;
+/**
+ * The catalogue's tokens, read at each question, so an edited file answers at once and costs nothing unasked. Sources
+ * are read from their modules' text, each source's files before the catalogue's, which win a clash.
+ *
+ * @param config - the catalogue's configuration.
+ * @param resolveSource - finds the file of a source's module.
+ * @param watch - told of every file read: the sources' modules and the tokens files; none by default.
+ */
+export declare const catalogueTokens: (config: ResolvedConfig, resolveSource: ResolveSource, watch?: (file: string) => void) => Promise<TokenReading>;
+/**
+ * The tokens' module, for a designer's page: what a list gives, and what could not be read. A static build has no
+ * server to ask, so the page imports them; a problem names a file from the catalogue's folder (`./tokens.json`),
+ * since a published page must not carry the building machine's paths.
+ *
+ * @param config - the catalogue's configuration.
+ * @param watch - adds a file whose edit renews the module.
+ * @param resolveSource - finds the file of a source's module.
+ */
+export declare const tokensModule: (config: ResolvedConfig, watch: (file: string) => void, resolveSource: ResolveSource) => Promise<{
+    code: string;
+    moduleType: "js";
+}>;
+/** The answers that need nothing of the stories, so a story broken mid-edit cannot take them down. */
+export declare const STORYLESS_ROUTES: Readonly<Record<string, (config: ResolvedConfig, params: URLSearchParams, resolveSource: ResolveSource) => Promise<AgentAnswer>>>;

package/dist/src/vite/storylessRoutes.js

@@ -0,0 +1,126 @@
+/**
+ * The answers that read no story: the design tokens, and what a change adds against them.
+ *
+ * @remarks
+ * Kept from the stories' answers on purpose: the sources are not loaded for them, so a story broken mid-edit, which is
+ * when an agent asks, cannot take them down, and a token question costs no bundling. A source's tokens are read from
+ * its module's text for the same reason: the module imports the stories' index, a language's texts, its named values.
+ *
+ * @module
+ */
+import { readFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { codeLiteral } from "../codeLiteral.js";
+import { addedLines, checkedCode, deletedTests, fileLines } from "./checkCode.js";
+import { gitChange, gitOutput } from "./gitChange.js";
+import { readTokenFiles, sourceTokensIn } from "./sourceTokens.js";
+import { TOKEN_ANSWERS, tokenSummary } from "./tokenAnswers.js";
+/**
+ * What one source's module declares; a module the bundler answers itself has no text to read, so it declares none.
+ *
+ * @param specifier - the source's module, as the configuration names it.
+ * @param resolveSource - finds its file.
+ * @param watch - told of the module's file, whose edit may name other tokens files.
+ */
+const sourceDeclaration = async (specifier, resolveSource, watch) => {
+    const none = { id: undefined, files: [], problems: [] };
+    try {
+        const id = await resolveSource(specifier);
+        if (id === undefined)
+            return { ...none, unread: `${specifier}: not found` };
+        const file = id.split("?")[0] ?? id;
+        if (!isAbsolute(file))
+            return none;
+        watch(file);
+        return sourceTokensIn(file, specifier);
+    }
+    catch (error) {
+        return { ...none, unread: `${specifier}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+};
+/**
+ * The catalogue's tokens, read at each question, so an edited file answers at once and costs nothing unasked. Sources
+ * are read from their modules' text, each source's files before the catalogue's, which win a clash.
+ *
+ * @param config - the catalogue's configuration.
+ * @param resolveSource - finds the file of a source's module.
+ * @param watch - told of every file read: the sources' modules and the tokens files; none by default.
+ */
+export const catalogueTokens = async (config, resolveSource, watch = () => undefined) => {
+    const declared = await Promise.all(config.sources.map((specifier) => sourceDeclaration(specifier, resolveSource, watch)));
+    const own = config.tokens.map(({ path, mode }) => ({ path, mode, label: relative(config.dir, path) }));
+    const files = [...declared.flatMap((source) => source.files), ...own];
+    for (const { path } of files)
+        watch(path);
+    const { tokens, problems, clashes } = readTokenFiles(files);
+    const declaring = declared.flatMap((source) => source.problems);
+    return {
+        tokens,
+        clashes,
+        problems: [...declaring, ...problems],
+        unread: declared.flatMap((source) => (source.unread === undefined ? [] : [source.unread])),
+        isConfigured: files.length > 0 || declaring.length > 0
+    };
+};
+/**
+ * The tokens' module, for a designer's page: what a list gives, and what could not be read. A static build has no
+ * server to ask, so the page imports them; a problem names a file from the catalogue's folder (`./tokens.json`),
+ * since a published page must not carry the building machine's paths.
+ *
+ * @param config - the catalogue's configuration.
+ * @param watch - adds a file whose edit renews the module.
+ * @param resolveSource - finds the file of a source's module.
+ */
+export const tokensModule = async (config, watch, resolveSource) => {
+    const { tokens, problems, unread } = await catalogueTokens(config, resolveSource, watch);
+    // in both forms: Vite's, and the system's, which a Windows error message writes
+    const shown = (problem) => problem.replaceAll(config.dir, ".").replaceAll(resolve(config.dir), ".");
+    const value = { tokens: tokens.map(tokenSummary), problems: [...unread, ...problems].map(shown) };
+    return { code: `export default ${codeLiteral(value)};`, moduleType: "js" };
+};
+/**
+ * What a change adds that breaks the design system. It needs nothing of the stories, like the tokens, so a story broken
+ * mid-edit does not stop it; tokens that were asked for and cannot be read do, or a check would pass having checked less.
+ * A source whose module cannot be read is only `skipped`: it may hold no tokens at all.
+ *
+ * @param config - the catalogue's configuration.
+ * @param params - the query: `since`, the commit to compare with.
+ * @param resolveSource - finds the file of a source's module.
+ */
+const checkCodeAnswer = async (config, params, resolveSource) => {
+    const since = params.get("since") || "HEAD";
+    const { tokens, problems, unread } = await catalogueTokens(config, resolveSource);
+    if (problems.length > 0) {
+        return { status: 400, body: { error: `The tokens files have problems: ${problems.join("; ")}` } };
+    }
+    const change = await gitChange(config.dir, since);
+    if (typeof change === "string")
+        return { status: 400, body: { error: change } };
+    const root = (await gitOutput(config.dir, "rev-parse", "--show-toplevel")).trim();
+    const fresh = await Promise.all(change.untracked.map(async (file) => fileLines(file, await readFile(join(root, file), "utf8").catch(() => ""))));
+    const hasTokens = tokens.length > 0;
+    const body = {
+        schema: 1,
+        since,
+        checked: hasTokens
+            ? ["raw-color", "raw-size", "suppression", "deleted-test"]
+            : ["suppression", "deleted-test"],
+        skipped: [
+            ...(hasTokens ? [] : ["Colours and sizes: this catalogue names no tokens file."]),
+            ...unread.map((source) => `Tokens of a source: ${source}`)
+        ],
+        problems: [
+            ...checkedCode([...addedLines(change.diff), ...fresh.flat()], tokens),
+            ...deletedTests(change.deleted)
+        ]
+    };
+    return { status: 200, body };
+};
+/** The answers that need nothing of the stories, so a story broken mid-edit cannot take them down. */
+export const STORYLESS_ROUTES = {
+    ...Object.fromEntries(Object.entries(TOKEN_ANSWERS).map(([route, answer]) => [
+        route,
+        async (config, params, resolveSource) => answer(await catalogueTokens(config, resolveSource), params)
+    ])),
+    "check-code": checkCodeAnswer
+};