forgebook 0.1.8 → 0.2.0

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

@@ -0,0 +1,40 @@
+import type { DocBlock } from "../docPages.ts";
+import type { SearchSection } from "../searchIndex.ts";
+import type { DocsResult } from "./docsExtractor.ts";
+import type { PackJson } from "./packedModule.ts";
+/**
+ * HTML as stretches of documentation, one per heading that carries an anchor.
+ *
+ * @param html - the HTML.
+ * @returns the stretches, those with neither a heading nor a text left out.
+ */
+export declare const htmlSections: (html: string) => SearchSection[];
+/**
+ * A docs page's blocks as stretches of documentation, one per heading: a code block belongs to the heading above it.
+ * A live story or an API table adds no text: what they show is found under its own name.
+ *
+ * @param blocks - the page's blocks.
+ */
+export declare const blockSections: (blocks: readonly DocBlock[]) => SearchSection[];
+/**
+ * A group of story files' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param watch - adds a file whose edit renews the module.
+ * @param extract - reads a story file's component.
+ * @param isServing - whether a dev server runs: only its tools read the problems, which name files on this computer, so
+ * a static build leaves them out.
+ * @param pack - writes the index's JSON as the module's value: as it is, or in a gzipped file of a build's own, which
+ * few visits read.
+ */
+export declare const storySearchModule: (root: string, pattern: string, watch: (file: string) => void, extract: (storyFile: string) => Promise<DocsResult>, isServing: boolean, pack: PackJson) => Promise<string>;
+/**
+ * A group of docs pages' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param watch - adds a file whose edit renews the module.
+ * @param pack - writes the index's JSON as the module's value.
+ */
+export declare const pagesSearchModule: (root: string, pattern: string, watch: (file: string) => void, pack: PackJson) => string;

package/dist/src/vite/searchModule.js

@@ -0,0 +1,212 @@
+/**
+ * The modules that answer a group's search index: what the search reads that the tree does not hold, built at build time
+ * and loaded by the page on the first search, so nobody who never searches pays for it.
+ *
+ * @remarks
+ * A docs page's and a component's text come from the HTML the pages themselves are drawn from, so a heading's anchor here
+ * is the one on the page by construction, and whatever a page renders is what is searched. Props come from the docs the
+ * page reads too. Each stretch of text is kept whole, so a sentence is found and shown as written: it weighs little
+ * next to the code, and repeats well under compression.
+ *
+ * @module
+ */
+import { readFileSync } from "node:fs";
+import { componentPage } from "./componentPage.js";
+import { compiledDocPage } from "./docPageMarkdown.js";
+import { indexedDocPages } from "./docPagesModule.js";
+import { indexedStoryFiles } from "./storyFilesModule.js";
+/** A heading of the pages' HTML: its anchor, and what is inside it. */
+const HEADING = /<h[1-6] id="doc-([^"]*)"[^>]*>([\s\S]*?)<\/h[1-6]>/g;
+/** A tag: `>` inside a quoted attribute does not end it. */
+const TAG = /<\/?([a-z][a-z0-9]*)(?:"[^"]*"|'[^']*'|[^'">])*>/gi;
+/** The tags inside a line of text: taking one out joins what it wrote apart, as coloured code is. */
+const INLINE_TAG = /^(a|abbr|b|code|del|em|i|kbd|mark|s|small|span|strong|sub|sup|u)$/i;
+/** The entities the Markdown renderer writes, and the space a page writes by hand; `&amp;` comes last. */
+const ENTITIES = [
+    ["&lt;", "<"],
+    ["&gt;", ">"],
+    ["&quot;", '"'],
+    ["&nbsp;", " "],
+    ["&amp;", "&"]
+];
+/** HTML's text: its tags out, and what a comment or a raw `<style>` or `<script>` holds, which nobody reads. */
+const plainText = (html) => {
+    const words = html
+        .replace(/<!--[\s\S]*?-->/g, " ")
+        .replace(/<(style|script)\b[\s\S]*?<\/\1>/gi, " ")
+        .replace(TAG, (_tag, name) => (INLINE_TAG.test(name) ? "" : " "))
+        .replace(/\s+/g, " ")
+        .replace(/ ([.,;:!?)])/g, "$1")
+        .trim();
+    const numbered = words.replace(/&#(\d+);/g, (_entity, code) => String.fromCodePoint(Number(code)));
+    return ENTITIES.reduce((text, [entity, character]) => text.replaceAll(entity, character), numbered);
+};
+/**
+ * HTML as stretches of documentation, one per heading that carries an anchor.
+ *
+ * @param html - the HTML.
+ * @returns the stretches, those with neither a heading nor a text left out.
+ */
+export const htmlSections = (html) => {
+    const sections = [];
+    let reached = 0;
+    let open = {};
+    const close = (end) => {
+        const text = plainText(html.slice(reached, end));
+        if (text !== "" || open.heading !== undefined)
+            sections.push({ ...open, text });
+    };
+    for (const heading of html.matchAll(HEADING)) {
+        close(heading.index);
+        reached = heading.index + heading[0].length;
+        open = { anchor: heading[1] ?? "", heading: plainText(heading[2] ?? "") };
+    }
+    close(html.length);
+    return sections;
+};
+/**
+ * A text added to the stretch it follows: a page's text goes on after a code block or a live story under the same
+ * heading.
+ *
+ * @param sections - the stretches so far; the last one changes.
+ * @param text - the text.
+ */
+const continueSection = (sections, text) => {
+    const last = sections.pop();
+    if (last === undefined)
+        sections.push({ text });
+    else
+        sections.push({ ...last, text: `${last.text} ${text}`.trim() });
+};
+/**
+ * A docs page's blocks as stretches of documentation, one per heading: a code block belongs to the heading above it.
+ * A live story or an API table adds no text: what they show is found under its own name.
+ *
+ * @param blocks - the page's blocks.
+ */
+export const blockSections = (blocks) => {
+    const sections = [];
+    for (const block of blocks) {
+        if (block.kind === "code")
+            continueSection(sections, block.text.replace(/\s+/g, " ").trim());
+        if (block.kind !== "text")
+            continue;
+        const [first, ...rest] = htmlSections(block.html);
+        if (first?.heading === undefined && first !== undefined)
+            continueSection(sections, first.text);
+        else if (first !== undefined)
+            sections.push(first);
+        sections.push(...rest);
+    }
+    return sections;
+};
+/** Everything that is not an empty text, as one text. */
+const joinedText = (texts) => [...new Set(texts.filter((text) => text !== undefined && text !== ""))].join(" ");
+/** What a component's docs say of it, the rule of when to use it included. */
+const leadOf = ({ summary, description, guidance }) => joinedText([
+    summary,
+    description,
+    ...(guidance?.useWhen ?? []),
+    ...(guidance?.avoidWhen ?? []),
+    guidance?.deprecated
+]);
+/** A list of a component's props as the index holds them. */
+const propsOf = (props, part) => props.map(({ name, description, kind }) => ({
+    name,
+    text: description,
+    ...(part === undefined ? {} : { part }),
+    ...(kind === "event" ? { isEvent: true } : {})
+}));
+/**
+ * What the page lists of a component, in the same terms: a hook's or a function's parameters, else its props, and its
+ * parts with theirs.
+ *
+ * @param docs - the component's docs.
+ * @param isLogic - whether its stories are about logic.
+ */
+const componentProps = (docs, isLogic) => {
+    const isCall = isLogic && docs.signature !== undefined;
+    // the page draws no reference at all for a component with no props of its own, its parts' included
+    if (!isCall && docs.props.length === 0)
+        return [];
+    return [
+        ...(isCall
+            ? (docs.signature?.parameters ?? []).map(({ name, description }) => ({ name, text: description }))
+            : propsOf(docs.props, undefined)),
+        ...docs.subcomponents.flatMap((subcomponent) => [
+            { name: subcomponent.name, text: subcomponent.description },
+            ...propsOf(subcomponent.props, subcomponent.name)
+        ])
+    ];
+};
+/** The fields of a component's entry that say something, so an empty one weighs nothing. */
+const componentEntry = (docs, isLogic, sections) => {
+    const lead = docs === undefined ? "" : leadOf(docs);
+    const props = docs === undefined ? [] : componentProps(docs, isLogic);
+    return {
+        ...(lead === "" ? {} : { lead }),
+        ...(props.length === 0 ? {} : { props }),
+        ...(sections.length === 0 ? {} : { sections })
+    };
+};
+/** Whether a story file's stories are all about logic: the page then documents its call, not its props. */
+const isLogicFile = ({ index }) => index.stories.length > 0 && index.stories.every((story) => story.isLogic ?? index.isLogic ?? false);
+/** Whether what a framework read is a component's docs. */
+const isComponent = (docs) => docs.name !== null;
+/**
+ * A component's entry and, when its docs cannot be read, why: its documentation file is searched either way.
+ *
+ * @param file - the story file.
+ * @param read - what the framework read of its component.
+ * @param watch - adds a file whose edit renews the module.
+ */
+const entryOf = (file, read, watch) => {
+    const page = componentPage(file.file);
+    if (page !== undefined)
+        watch(page.file);
+    const sections = page === undefined ? [] : htmlSections(page.html);
+    if (typeof read === "string")
+        return { entry: componentEntry(undefined, false, sections), problem: `${file.key}: ${read}` };
+    if ("sources" in read)
+        for (const source of read.sources)
+            watch(source);
+    const docs = isComponent(read.docs) ? read.docs : undefined;
+    return { entry: componentEntry(docs, isLogicFile(file), sections) };
+};
+/**
+ * A group of story files' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param watch - adds a file whose edit renews the module.
+ * @param extract - reads a story file's component.
+ * @param isServing - whether a dev server runs: only its tools read the problems, which name files on this computer, so
+ * a static build leaves them out.
+ * @param pack - writes the index's JSON as the module's value: as it is, or in a gzipped file of a build's own, which
+ * few visits read.
+ */
+export const storySearchModule = async (root, pattern, watch, extract, isServing, pack) => {
+    const files = indexedStoryFiles(root, pattern, watch);
+    const entries = await Promise.all(files.map(async (file) => ({ file, ...entryOf(file, await extract(file.file), watch) })));
+    const problems = entries.flatMap(({ problem }) => problem ?? []);
+    const index = {
+        components: Object.fromEntries(entries.filter(({ entry }) => Object.keys(entry).length > 0).map(({ file, entry }) => [file.key, entry])),
+        ...(problems.length === 0 || !isServing ? {} : { problems })
+    };
+    return `export default ${pack(JSON.stringify(index))};`;
+};
+/**
+ * A group of docs pages' search index, as the code of its module.
+ *
+ * @param root - the declaring module's folder.
+ * @param pattern - the pattern.
+ * @param watch - adds a file whose edit renews the module.
+ * @param pack - writes the index's JSON as the module's value.
+ */
+export const pagesSearchModule = (root, pattern, watch, pack) => {
+    const pages = indexedDocPages(root, pattern, watch).map(({ key, file }) => [
+        key,
+        blockSections(compiledDocPage(file, readFileSync(file, "utf8")).blocks)
+    ]);
+    return `export default ${pack(JSON.stringify({ pages: Object.fromEntries(pages) }))};`;
+};

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

@@ -0,0 +1,7 @@
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+/**
+ * What a query finds across the catalogue.
+ *
+ * @param context - what the routes read.
+ */
+export declare const searchAnswer: ({ tree, params, pages, view, loaded }: RouteContext) => Promise<AgentAnswer>;

package/dist/src/vite/searchRoute.js

@@ -0,0 +1,79 @@
+import { searchables, searchCatalogue } from "../search.js";
+import { isSearchIndex, mergedSearchIndex } from "../searchIndex.js";
+import { sourceSearchLoaders } from "../sourceFiles.js";
+import { componentAddressOf, docPageAddressOf, storyAddressOf } from "../viewState.js";
+import { settled } from "./agentRoutes.js";
+/** How many results an answer gives unless asked: agents degrade with long context. */
+const DEFAULT_LIMIT = 8;
+/** How many results an answer can give. */
+const MAX_LIMIT = 50;
+/** How many hits each result lists. */
+const HITS = 3;
+/** A marked text as plain text. */
+const plain = (text) => text.map((piece) => piece.text).join("");
+/** The address a search's target opens. */
+const addressOf = (target, pages, view) => {
+    if (target.kind === "story")
+        return storyAddressOf(pages.page, target.id, view);
+    const address = target.kind === "page"
+        ? docPageAddressOf(pages.page, target.id, view)
+        : componentAddressOf(pages.page, target.id, view);
+    return target.anchor === undefined ? address : `${address}#${encodeURIComponent(target.anchor)}`;
+};
+/** A hit as the document gives it. */
+const agentHit = (hit, pages, view) => ({
+    kind: hit.kind,
+    ...(hit.label === undefined ? {} : { name: plain(hit.label) }),
+    text: plain(hit.snippet),
+    address: addressOf(hit.target, pages, view)
+});
+/** A result as the document gives it. */
+const agentResult = (result, pages, view) => ({
+    kind: result.kind,
+    id: result.target.id,
+    name: plain(result.name),
+    place: result.place,
+    score: result.score,
+    matched: result.matched,
+    missed: result.missed,
+    reasons: result.reasons,
+    hits: result.hits.map((hit) => agentHit(hit, pages, view)),
+    hitCount: result.hitCount,
+    address: addressOf(result.target, pages, view)
+});
+/** A source's index, every group's read, with why one could not be. */
+const indexOf = async (source) => {
+    const read = await Promise.all(sourceSearchLoaders(source).map((load) => settled(load)));
+    const problems = read.flatMap((each) => ("error" in each ? [`${source.name}: ${each.error}`] : []));
+    const indexes = read.flatMap((each) => ("value" in each && isSearchIndex(each.value) ? [each.value] : []));
+    return { index: mergedSearchIndex(indexes), problems };
+};
+/** The limit asked for, within what an answer can give. */
+const limitOf = (text) => {
+    const limit = Number(text ?? DEFAULT_LIMIT);
+    return Number.isInteger(limit) && limit > 0 ? Math.min(limit, MAX_LIMIT) : DEFAULT_LIMIT;
+};
+/**
+ * What a query finds across the catalogue.
+ *
+ * @param context - what the routes read.
+ */
+export const searchAnswer = async ({ tree, params, pages, view, loaded }) => {
+    const query = params.get("query") ?? "";
+    if (query.trim() === "")
+        return { status: 400, body: { error: "No words to look for" } };
+    const read = await Promise.all(loaded.sources.map(async (source) => ({ id: source.id, ...(await indexOf(source)) })));
+    const indexes = new Map(read.map(({ id, index }) => [id, index]));
+    const answer = searchCatalogue(searchables(tree, indexes), query, {
+        results: limitOf(params.get("limit")),
+        hits: HITS
+    });
+    const body = {
+        schema: 1,
+        query,
+        total: answer.total,
+        results: answer.results.map((result) => agentResult(result, pages, view)),
+        problems: read.flatMap(({ index, problems }) => [...problems, ...(index.problems ?? [])])
+    };
+    return { status: 200, body };
+};

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

@@ -0,0 +1,31 @@
+/**
+ * Makes the dev server resolve a package on Node with the export conditions its pages resolve it with, so the stories
+ * and previews it loads for tools are the files the frames draw.
+ *
+ * @remarks
+ * Vite gives its server environment conditions of its own (`module`, `node`): a catalogue's `resolve.conditions`
+ * reaches the pages only. A monorepo that points its packages at their sources with a condition (`source`) is then
+ * read from their builds on the server, or not at all where nothing is built, and a preview that imports one cannot
+ * load there. So the server takes the pages' conditions too, except those of another runtime (`browser`, which would
+ * pick a package's browser build on Node, `worker`, `react-native`). A plugin that names the server's conditions
+ * itself (`ssr.resolve.conditions`, `environments.ssr.resolve.conditions`) keeps them. The hook runs after every other
+ * plugin's, so the conditions a framework's or the catalogue's plugins add are read as well; one a plugin sets in its
+ * `configEnvironment` hook is not. Only the `forgebook` command's server has it: an app that runs the catalogue's
+ * plugin in a Vite configuration of its own names the server's conditions there.
+ *
+ * @module
+ */
+import { type Plugin, type UserConfig } from "vite";
+/**
+ * The conditions the server resolves with for this configuration, or `undefined` to leave Vite's: none named for the
+ * pages, the server's named, or a server that runs as a web worker, which Vite gives the pages' conditions already.
+ *
+ * @param config - Vite's configuration, every plugin's included.
+ */
+export declare const serverConditionsOf: (config: UserConfig) => readonly string[] | undefined;
+/**
+ * The plugin.
+ *
+ * @returns a plugin that sets the server environment's conditions after the other plugins set theirs.
+ */
+export declare const serverConditions: () => Plugin;

package/dist/src/vite/serverConditions.js

@@ -0,0 +1,69 @@
+/**
+ * Makes the dev server resolve a package on Node with the export conditions its pages resolve it with, so the stories
+ * and previews it loads for tools are the files the frames draw.
+ *
+ * @remarks
+ * Vite gives its server environment conditions of its own (`module`, `node`): a catalogue's `resolve.conditions`
+ * reaches the pages only. A monorepo that points its packages at their sources with a condition (`source`) is then
+ * read from their builds on the server, or not at all where nothing is built, and a preview that imports one cannot
+ * load there. So the server takes the pages' conditions too, except those of another runtime (`browser`, which would
+ * pick a package's browser build on Node, `worker`, `react-native`). A plugin that names the server's conditions
+ * itself (`ssr.resolve.conditions`, `environments.ssr.resolve.conditions`) keeps them. The hook runs after every other
+ * plugin's, so the conditions a framework's or the catalogue's plugins add are read as well; one a plugin sets in its
+ * `configEnvironment` hook is not. Only the `forgebook` command's server has it: an app that runs the catalogue's
+ * plugin in a Vite configuration of its own names the server's conditions there.
+ *
+ * @module
+ */
+import { defaultServerConditions } from "vite";
+/**
+ * The conditions that name a build for another runtime than Node's: a package's browser build, a worker's, a native
+ * app's, another server runtime's. Node cannot run them, so the server leaves them out.
+ */
+const OTHER_RUNTIMES = new Set([
+    "browser",
+    "worker",
+    "react-native",
+    "deno",
+    "bun",
+    "workerd",
+    "edge-light"
+]);
+/**
+ * The conditions the server resolves with for this configuration, or `undefined` to leave Vite's: none named for the
+ * pages, the server's named, or a server that runs as a web worker, which Vite gives the pages' conditions already.
+ *
+ * @param config - Vite's configuration, every plugin's included.
+ */
+export const serverConditionsOf = (config) => {
+    const pages = config.environments?.["client"]?.resolve?.conditions ?? config.resolve?.conditions;
+    if (pages === undefined)
+        return undefined;
+    if (config.ssr?.target === "webworker")
+        return undefined;
+    if (config.ssr?.resolve?.conditions !== undefined)
+        return undefined;
+    if (config.environments?.["ssr"]?.resolve?.conditions !== undefined)
+        return undefined;
+    const forNode = pages.filter((condition) => !OTHER_RUNTIMES.has(condition));
+    return [...new Set([...forNode, ...defaultServerConditions])];
+};
+/**
+ * The plugin.
+ *
+ * @returns a plugin that sets the server environment's conditions after the other plugins set theirs.
+ */
+export const serverConditions = () => ({
+    name: "forgebook:server-conditions",
+    // a build loads nothing on the server, and an environment added to it would reach every plugin's hooks
+    apply: "serve",
+    config: {
+        order: "post",
+        handler: (config) => {
+            const conditions = serverConditionsOf(config);
+            return conditions === undefined
+                ? undefined
+                : { environments: { ssr: { resolve: { conditions: [...conditions] } } } };
+        }
+    }
+});

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

@@ -0,0 +1,18 @@
+/**
+ * A hook's or a function's signature, read from its types and TSDoc: what a story about logic documents first. Shared
+ * by the frameworks' docs modules.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import type { FunctionSignatureDocs } from "../componentDocs.ts";
+/**
+ * A hook's or a function's signature, read at the expression that names it: its type parameters, each parameter as
+ * the source writes it (a destructured one by its pattern, a rest one marked) with its `@param` text, and the return
+ * type with its `@returns` text. An overloaded function gives its first signature.
+ *
+ * @param symbol - the function's declared symbol.
+ * @param expression - where the code names it.
+ * @param checker - the program's checker.
+ */
+export declare const signatureDocs: (symbol: ts.Symbol, expression: ts.Expression, checker: ts.TypeChecker) => FunctionSignatureDocs | undefined;

package/dist/src/vite/signatureDocs.js

@@ -0,0 +1,64 @@
+/**
+ * A hook's or a function's signature, read from its types and TSDoc: what a story about logic documents first. Shared
+ * by the frameworks' docs modules.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/**
+ * A type as the source writes it, on one line.
+ *
+ * @param node - the type's node.
+ */
+const writtenText = (node) => node.getText().replace(/\s+/g, " ").trim();
+/**
+ * A JSDoc tag's text on one line.
+ *
+ * @param comment - the tag's comment.
+ */
+const tagText = (comment) => (ts.getTextOfJSDocComment(comment) ?? "").replace(/^-\s*/, "").replace(/\s+/g, " ").trim();
+/**
+ * A hook's or a function's signature, read at the expression that names it: its type parameters, each parameter as
+ * the source writes it (a destructured one by its pattern, a rest one marked) with its `@param` text, and the return
+ * type with its `@returns` text. An overloaded function gives its first signature.
+ *
+ * @param symbol - the function's declared symbol.
+ * @param expression - where the code names it.
+ * @param checker - the program's checker.
+ */
+export const signatureDocs = (symbol, expression, checker) => {
+    const [signature] = checker.getTypeOfSymbolAtLocation(symbol, expression).getCallSignatures();
+    if (signature === undefined)
+        return undefined;
+    // a signature the checker made (a mapped or an intersected type) has no declaration
+    const declaration = signature.getDeclaration();
+    // a hook typed through an alias (`const useX: UseX = …`) has its comment on its own declaration, not the alias's
+    const ownTags = (symbol.declarations ?? []).flatMap((each) => [...ts.getJSDocTags(each)]);
+    const ownParameterTag = (name) => ownTags.filter(ts.isJSDocParameterTag).find((tag) => tag.name.getText() === name);
+    const parameters = signature.parameters.map((parameter) => {
+        const node = parameter.valueDeclaration;
+        const written = node !== undefined && ts.isParameter(node) ? node : undefined;
+        const tag = (written === undefined ? undefined : ts.getJSDocParameterTags(written)[0]) ??
+            ownParameterTag(parameter.getName());
+        return {
+            // a destructured parameter has no name of its own: the checker calls it `__0`
+            name: written === undefined || ts.isIdentifier(written.name)
+                ? parameter.getName()
+                : writtenText(written.name),
+            type: written?.type === undefined
+                ? checker.typeToString(checker.getTypeOfSymbolAtLocation(parameter, expression))
+                : writtenText(written.type),
+            description: tagText(tag?.comment),
+            isOptional: written?.questionToken !== undefined || written?.initializer !== undefined,
+            isRest: written?.dotDotDotToken !== undefined
+        };
+    });
+    const returnType = declaration?.type;
+    return {
+        typeParameters: (declaration?.typeParameters ?? []).map(writtenText),
+        parameters,
+        returns: returnType === undefined ? checker.typeToString(signature.getReturnType()) : writtenText(returnType),
+        returnsDescription: tagText(((declaration === undefined ? undefined : ts.getJSDocReturnTag(declaration)) ??
+            ownTags.find(ts.isJSDocReturnTag))?.comment)
+    };
+};

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

@@ -0,0 +1,57 @@
+import { type ParsedTokens } from "./designTokens.ts";
+/** What a source's module says of its tokens, its paths as written. */
+export type DeclaredSource = {
+    /** The source's id, when written plainly. */
+    readonly id: string | undefined;
+    /** Its tokens files, the base first. */
+    readonly tokens: readonly {
+        readonly file: string;
+        readonly mode: string | undefined;
+    }[];
+    /** What cannot be read of tokens it does declare. */
+    readonly problems: readonly string[];
+    /** Why the module could not be read, so whether it declares tokens is not known. */
+    readonly unread?: string;
+};
+/** A tokens file to read. */
+export type TokensFileToRead = {
+    /** Its absolute path. */
+    readonly path: string;
+    /** The theme it belongs to; none for the base. */
+    readonly mode: string | undefined;
+    /** What a problem calls it. */
+    readonly label: string;
+    /** The source it comes from; none for the catalogue's own. */
+    readonly source?: string;
+};
+/** A source's tokens files, ready to read. */
+export type SourceTokens = {
+    /** Its id, when written plainly. */
+    readonly id: string | undefined;
+    /** Its tokens files. */
+    readonly files: readonly TokensFileToRead[];
+    /** What cannot be read of tokens it does declare. */
+    readonly problems: readonly string[];
+    /** Why its module could not be read, so whether it declares tokens is not known. */
+    readonly unread?: string;
+};
+/**
+ * What a source's module declares, from its text.
+ *
+ * @param file - the module's path, for the parser (its extension says TypeScript or JSX).
+ * @param text - the module's text.
+ */
+export declare const declaredSource: (file: string, text: string) => DeclaredSource;
+/**
+ * What the source in a module gives, its paths absolute.
+ *
+ * @param file - the module's absolute path.
+ * @param name - what names the module, for the problems and the files' labels (`@acme/ui/stories`).
+ */
+export declare const sourceTokensIn: (file: string, name: string) => SourceTokens;
+/**
+ * Reads tokens files from disk.
+ *
+ * @param files - the files: each source's, then the catalogue's own.
+ */
+export declare const readTokenFiles: (files: readonly TokensFileToRead[]) => ParsedTokens;