forgebook 0.3.3 → 0.4.0

package/dist/src/vite/storyFilesModule.js

@@ -129,31 +129,31 @@ export const storyFileIndex = (root, pattern, key) => {
     return indexStoryFile(file, readFileSync(file, "utf8"), title === undefined ? {} : { autoTitle: title });
 };
 /**
- * Every story file a group's patterns list, indexed.
+ * Every story file a group's patterns list, indexed, and those that cannot be. Only the former are kept between starts:
+ * the stamps of the others would only say what is already known, and their next read costs one file.
  *
  * @param root - the declaring module's folder.
  * @param patterns - the patterns (`storyFileKeys`).
- * @param watch - adds a file whose edit renews the module that read it.
+ * @param watch - adds a file whose edit renews the module that read it: a refused one too, as its fix must.
  * @param cache - the index kept between starts, which holds while the files it came from do; none reads them all.
  * @param isKept - whether a listed file may be read; every one by default.
- * @throws when a story file cannot be indexed.
  */
-export const indexedStoryFiles = (root, patterns, watch, cache, isKept = EVERY_FILE) => {
+export const readStoryFiles = (root, patterns, watch, cache, isKept = EVERY_FILE) => {
     const name = storyFilesGroupText(VITE_PATHS.normalize(root), patterns);
     const since = nowNs();
     const kept = cache?.read(name);
     const listed = listedFiles(root, patterns).filter(({ key }) => isKept(VITE_PATHS.resolve(root, key)));
-    const files = listed.map(({ key, pattern }) => {
+    const files = [];
+    const refused = [];
+    for (const { key, pattern } of listed) {
         const file = VITE_PATHS.resolve(root, key);
         watch(file);
-        const known = kept?.[key];
-        if (known !== undefined)
-            return { key, pattern, file, index: known };
-        const index = storyFileIndex(root, pattern, key);
+        const index = kept?.[key] ?? storyFileIndex(root, pattern, key);
         if (typeof index === "string")
-            throw new Error(index);
-        return { key, pattern, file, index };
-    });
+            refused.push({ key, pattern, file, problem: index });
+        else
+            files.push({ key, pattern, file, index });
+    }
     // kept again when anything was read anew: a file added, or the kept index out of date
     if (cache !== undefined && files.some(({ key }) => kept?.[key] === undefined)) {
         const stamps = stampPaths(files.map((each) => each.file));
@@ -161,7 +161,29 @@ export const indexedStoryFiles = (root, patterns, watch, cache, isKept = EVERY_F
         if (isSettledSince(stamps, since))
             cache.write(name, index, stamps);
     }
-    return files;
+    return { files, refused };
+};
+/**
+ * What fails a module that cannot go on without its files: every file refused, a line each.
+ *
+ * @param refused - the files, at least one.
+ */
+export const refusalError = (refused) => new Error(refused.map(({ problem }) => problem).join("\n"));
+/**
+ * Every story file a group's patterns list, indexed, for those who cannot go on without one: a build, a test.
+ *
+ * @param root - the declaring module's folder.
+ * @param patterns - the patterns (`storyFileKeys`).
+ * @param watch - adds a file whose edit renews the module that read it.
+ * @param cache - the index kept between starts, which holds while the files it came from do; none reads them all.
+ * @param isKept - whether a listed file may be read; every one by default.
+ * @throws when a story file cannot be indexed, naming every one that cannot.
+ */
+export const indexedStoryFiles = (root, patterns, watch, cache, isKept = EVERY_FILE) => {
+    const { files, refused } = readStoryFiles(root, patterns, watch, cache, isKept);
+    if (refused.length > 0)
+        throw refusalError(refused);
+    return [...files];
 };
 /**
  * The code of the module for one group.
@@ -174,6 +196,55 @@ export const indexedStoryFiles = (root, patterns, watch, cache, isKept = EVERY_F
  * @returns the module's code, or a message saying which file cannot be indexed.
  */
 export const storyFilesModule = (root, patterns, watch, loaders = { hasUsage: true, hasReach: true }, cache) => storyFilesCode(root, patterns, indexedStoryFiles(root, patterns, watch, cache), loaders);
+/**
+ * The stories a group needs before its stories are written as rows (`indexCode`). Rows write each key once and the
+ * objects once per story, but rows need the function that turns them back, which a small group's first load pays for
+ * more than it saves: gzip already shares a key repeated in every story. On the generated library, rows cost the shell's
+ * first load 11 bytes more at 100 stories and saved 92 at 500, so the two meet near 150; past 300 they save without
+ * doubt, and the build's own weight falls by a quarter of the index.
+ */
+export const ROWS_FROM_STORIES = 300;
+/** The function the generated module rebuilds each file's stories with, from their rows. */
+const STORY_TABLE = "storyTable";
+/**
+ * The keys of a group's stories, each once, in the order the first story to have each writes it.
+ *
+ * @param files - the group's story files, indexed.
+ */
+const storyKeysOf = (files) => [
+    ...new Set(files.flatMap(({ index }) => index.stories.flatMap((story) => Object.keys(story).filter((key) => Reflect.get(story, key) !== undefined))))
+];
+/**
+ * A story file's index as code: its stories as rows of values in the group's key order, which the module turns back
+ * into the same objects (`STORY_TABLE`), in a group of `ROWS_FROM_STORIES` stories or more.
+ *
+ * @remarks
+ * A catalogue's first load fetches every group's index, and an object per story writes its keys again for every
+ * story: on a library of 500 stories, a quarter of the index was the words `exportName` and `description`. A row
+ * writes each value once and leaves a key a story does not have as a hole, which the module leaves out of its object
+ * as the literal did.
+ *
+ * @param index - the file's index.
+ * @param keys - the group's keys (`storyKeysOf`).
+ */
+const indexCode = (index, keys) => {
+    const rows = index.stories.map((story) => {
+        const values = keys.map((key) => {
+            const value = Reflect.get(story, key);
+            return value === undefined ? "" : codeLiteral(value);
+        });
+        // a story's last keys it does not have are left out: a row ends with its last value, never with a hole
+        while (values.at(-1) === "")
+            values.pop();
+        return `[${values.join(",")}]`;
+    });
+    const fields = Object.entries(index)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => key === "stories"
+        ? `${codeLiteral(key)}:${STORY_TABLE}([${rows.join(",")}])`
+        : `${codeLiteral(key)}:${codeLiteral(value)}`);
+    return `{${fields.join(",")}}`;
+};
 /**
  * The code of the module for one group, from its story files indexed.
  *
@@ -184,8 +255,10 @@ export const storyFilesModule = (root, patterns, watch, loaders = { hasUsage: tr
  * @param loaders - the group's loaders besides its story files'.
  * @param hasTexts - a build's: whether each file's docs, code and page come from the group's texts module, in the
  * rows' order (`TEXTS_PREFIX`), and not each from its query.
+ * @param refused - the story files it lists that cannot be indexed, which the catalogue names among its problems.
+ * @param scriptProblems - the project's other scripts that do not parse, named among them too.
  */
-export const storyFilesCode = (root, patterns, files, loaders, hasTexts = false) => {
+export const storyFilesCode = (root, patterns, files, loaders, hasTexts = false, refused = [], scriptProblems = []) => {
     const { hasDocs = true, hasUsage, hasReach } = loaders;
     // the group's id in Vite's form, as the plugin names the declaring module's folder
     const folder = VITE_PATHS.normalize(root);
@@ -208,10 +281,24 @@ export const storyFilesCode = (root, patterns, files, loaders, hasTexts = false)
             ];
     // a row per file, its name written once and not once per column (its index, each loader): a large catalogue's
     // names are a tenth of its index
-    const rows = files.map(({ key, index }) => [codeLiteral(key), codeLiteral(index), `() => import(${path(key)})`, ...textLoaders(key)].join(", "));
+    const keys = storyKeysOf(files);
+    const isTable = files.reduce((count, { index }) => count + index.stories.length, 0) >= ROWS_FROM_STORIES;
+    const rows = files.map(({ key, index }) => [
+        codeLiteral(key),
+        isTable ? indexCode(index, keys) : codeLiteral(index),
+        `() => import(${path(key)})`,
+        ...textLoaders(key)
+    ].join(", "));
     const written = `[${rows.map((row) => `[${row}]`).join(",\n")}]`;
     return [
         ...(hasTexts ? [`import texts from ${texts};`] : []),
+        ...(isTable
+            ? [
+                `const storyKeys = ${codeLiteral(keys)};`,
+                // `flatMap` passes over a row's holes, the keys its story lacks
+                `const ${STORY_TABLE} = (rows) => rows.map((row) => Object.fromEntries(row.flatMap((value, at) => [[storyKeys[at], value]])));`
+            ]
+            : []),
         // a build's texts are their module's rows, in the same order: each joins its file's
         `const rows = ${hasTexts ? `${written}.map((row, at) => row.concat(texts[at]))` : written};`,
         "const column = (at) => Object.fromEntries(rows.map((row) => [row[0], row[at]]));",
@@ -221,6 +308,9 @@ export const storyFilesCode = (root, patterns, files, loaders, hasTexts = false)
         hasDocs ? "docs: column(3)," : "docs: {},",
         "code: column(4),",
         "pages: column(5),",
+        ...(refused.length === 0 && scriptProblems.length === 0
+            ? []
+            : [`problems: ${codeLiteral([...refused.map(({ problem }) => problem), ...scriptProblems])},`]),
         `search: () => import(${search}).then((module) => module.default),`,
         ...(hasUsage ? [`usage: () => import(${usage}).then((module) => module.default),`] : []),
         ...(hasReach ? [`reach: () => import(${reach}).then((module) => module.default),`] : []),

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

@@ -20,6 +20,13 @@ export declare const patternsProblem: (patterns: readonly string[]) => string |
  * @param pattern - the pattern, without a `!`.
  */
 export type FindFiles = (root: string, pattern: string) => readonly string[];
+/**
+ * A pattern or an address 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 or the address.
+ */
+export declare const withoutTrailingSlashes: (pattern: string) => 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. */
@@ -37,3 +44,27 @@ export type ListedFile = {
  * @throws when every pattern is a `!` one (`patternsProblem`).
  */
 export declare const listedFiles: (root: string, patterns: readonly string[], find?: FindFiles, paths?: VitePaths) => ListedFile[];
+/**
+ * The patterns of a list that list no file, left out by the `!` ones as they are when the catalogue lists its files. Each
+ * is read on its own: a mistaken pattern beside one that works is as silent as a list that lists nothing.
+ *
+ * @param root - the folder the patterns are relative to.
+ * @param patterns - the patterns.
+ */
+export declare const unmatchedPatterns: (root: string, patterns: readonly string[]) => readonly string[];
+/**
+ * Whether a pattern matches a file, the walk from the pattern's static folder ending at the first one: telling that a
+ * pattern lists something should not cost a walk of the whole tree, which on a large library is a tenth of a second
+ * on the thread that starts the server, before anything is drawn. It finds only files the glob would list (the same
+ * matching, the dependencies left out); finding none decides nothing, and the full listing is asked then.
+ *
+ * @param root - the folder the pattern is relative to.
+ * @param pattern - the pattern, without a `!`.
+ */
+export declare const hasMatchingFile: (root: string, pattern: string) => boolean;
+/**
+ * Why what a configuration lists to show cannot be used, or none.
+ *
+ * @param config - what the file exports by default.
+ */
+export declare const filesProblem: (config: object) => string | undefined;

package/dist/src/vite/storyPatterns.js

@@ -12,7 +12,9 @@
  *
  * @module
  */
-import { globSync } from "node:fs";
+import { globSync, readdirSync, statSync } from "node:fs";
+import { posix } from "node:path";
+import { patternBase } from "./autoTitle.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** What starts a pattern that leaves files out. */
 const NEGATION = "!";
@@ -55,12 +57,12 @@ const isLeftOut = (key, left) => {
     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.
+ * A pattern or an address 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.
+ * @param pattern - the pattern or the address.
  */
-const withoutTrailingSlashes = (pattern) => {
+export const withoutTrailingSlashes = (pattern) => {
     let end = pattern.length;
     while (end > 0 && pattern[end - 1] === "/")
         end -= 1;
@@ -98,3 +100,136 @@ export const listedFiles = (root, patterns, find = globbed, paths = VITE_PATHS)
         .sort(([first], [second]) => (first < second ? -1 : 1))
         .map(([key, pattern]) => ({ key, pattern }));
 };
+/**
+ * The patterns of a list that list no file, left out by the `!` ones as they are when the catalogue lists its files. Each
+ * is read on its own: a mistaken pattern beside one that works is as silent as a list that lists nothing.
+ *
+ * @param root - the folder the patterns are relative to.
+ * @param patterns - the patterns.
+ */
+export const unmatchedPatterns = (root, patterns) => {
+    const leftOut = patterns.filter(isNegated);
+    // a pattern can match folders alone (`stories/**` over empty ones), which hold no story
+    const isFile = ({ key }) => statSync(VITE_PATHS.resolve(root, key), { throwIfNoEntry: false })?.isFile() === true;
+    // a `!` pattern left out of a pattern that lists nothing anyway changes nothing, so the walk ignores them: with any,
+    // the full listing decides
+    return patterns
+        .filter((pattern) => !isNegated(pattern))
+        .filter((pattern) => !(leftOut.length === 0 && hasMatchingFile(root, pattern)) &&
+        !listedFiles(root, [pattern, ...leftOut]).some(isFile));
+};
+/**
+ * A folder's entries, none when it cannot be read (gone, or not a folder): the walk goes on with the others.
+ *
+ * @param root - the folder the path is relative to.
+ * @param folder - the folder, relative to the root; `""` for the root itself.
+ */
+const folderEntries = (root, folder) => {
+    try {
+        return readdirSync(VITE_PATHS.resolve(root, folder === "" ? "." : folder), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+};
+/**
+ * Whether a pattern matches a file, the walk from the pattern's static folder ending at the first one: telling that a
+ * pattern lists something should not cost a walk of the whole tree, which on a large library is a tenth of a second
+ * on the thread that starts the server, before anything is drawn. It finds only files the glob would list (the same
+ * matching, the dependencies left out); finding none decides nothing, and the full listing is asked then.
+ *
+ * @param root - the folder the pattern is relative to.
+ * @param pattern - the pattern, without a `!`.
+ */
+export const hasMatchingFile = (root, pattern) => {
+    const plain = pattern.replace(/^(?:\.\/)+/, "");
+    const isDependencyNamed = pattern.includes(DEPENDENCIES);
+    // the glob enters no hidden folder (`.git`) unless the pattern names one, and nor does the walk
+    const isHiddenNamed = plain.split("/").some((segment) => segment.startsWith(".") && segment !== "..");
+    const isWalked = (entry) => (isDependencyNamed || entry.name !== DEPENDENCIES) && (isHiddenNamed || !entry.name.startsWith("."));
+    const shape = patternShape(plain);
+    const folders = [patternBase(plain)];
+    while (folders.length > 0) {
+        const folder = folders.pop() ?? "";
+        for (const entry of folderEntries(root, folder)) {
+            const path = folder === "" ? entry.name : `${folder}/${entry.name}`;
+            if (entry.isFile() && shape.isFileDepth(path) && posix.matchesGlob(path, plain))
+                return true;
+            if (entry.isDirectory() && isWalked(entry) && shape.couldHold(path))
+                folders.push(path);
+        }
+    }
+    return false;
+};
+/** Whether a pattern has a `/` inside a group (`{a,b/c}`, `@(a|b/c)`), which splitting it at its slashes would cut. */
+const hasSlashInGroup = (pattern) => {
+    let depth = 0;
+    for (const character of pattern) {
+        if (character === "{" || character === "(")
+            depth += 1;
+        else if ((character === "}" || character === ")") && depth > 0)
+            depth -= 1;
+        else if (character === "/" && depth > 0)
+            return true;
+    }
+    return false;
+};
+/**
+ * Where a pattern's files can be. Without it the walk reads every folder under the pattern's static one and matches
+ * every file there: in a monorepo whose pattern names packages by a group (`packages/@{a,b}/*\/stories/*`), that is
+ * every package's sources, most of a second, longer than the full listing the walk is there to spare. A pattern with
+ * `**` reaches any depth past it; one with a `/` inside a group cannot be cut at its slashes, and lets everything through.
+ *
+ * @param pattern - the pattern, without a `!` or a leading `./`.
+ */
+const patternShape = (pattern) => {
+    if (hasSlashInGroup(pattern))
+        return { couldHold: () => true, isFileDepth: () => true };
+    const segments = pattern.split("/");
+    const globstar = segments.indexOf("**");
+    const isAnyDepth = (depth) => globstar !== -1 && globstar < depth;
+    return {
+        couldHold: (folder) => {
+            const depth = folder.split("/").length;
+            if (isAnyDepth(depth))
+                return true;
+            return depth < segments.length && posix.matchesGlob(folder, segments.slice(0, depth).join("/"));
+        },
+        isFileDepth: (file) => {
+            const depth = file.split("/").length;
+            return isAnyDepth(depth) || depth === segments.length;
+        }
+    };
+};
+/** Whether a configuration's list has something in it. */
+const isListed = (config, key) => {
+    const list = Reflect.get(config, key);
+    return Array.isArray(list) && list.length > 0;
+};
+/**
+ * Why a configuration's list of globs lists nothing by construction (only `!` patterns), or none.
+ *
+ * @param config - what the file exports by default.
+ * @param key - the list's key.
+ */
+const globsProblem = (config, key) => {
+    const list = Reflect.get(config, key);
+    return Array.isArray(list)
+        ? patternsProblem(list.filter((item) => typeof item === "string"))
+        : undefined;
+};
+/**
+ * Why what a configuration lists to show cannot be used, or none.
+ *
+ * @param config - what the file exports by default.
+ */
+export const filesProblem = (config) => {
+    if (!["stories", "sources", "docs"].some((key) => isListed(config, key)))
+        return 'it names no stories (`stories: ["src/**/*.stories.tsx"]`) and no sources';
+    for (const key of ["stories", "docs"]) {
+        const problem = globsProblem(config, key);
+        if (problem !== undefined)
+            return `its ${key} list nothing: ${problem}`;
+    }
+    return undefined;
+};

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

@@ -4,8 +4,10 @@
  * @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.
+ * render, since a story with no JSX draws that component. A file no edge reaches is not known to reach anything:
+ * `verify` lists it as not verified rather than claim it is safe. A deleted file has no node, only the edge of whatever
+ * still imports it, written without its extension when the import was: the stories behind that edge are the ones it
+ * breaks.
  *
  * @module
  */
@@ -25,6 +27,12 @@ export type ReachedStory = {
     readonly exportName: string;
     /** Every file it reaches, its own story file included, absolute. */
     readonly files: readonly string[];
+    /** Its story file, the components it draws and what the story file imports itself: the rest it reaches through them. */
+    readonly own: readonly string[];
+    /** Its story file, absolute. */
+    readonly storyFile: string;
+    /** The file its meta's component is declared in, absolute; none when its meta names none the checker resolves. */
+    readonly metaFile?: string;
 };
 /**
  * Each story with the files it reaches.

package/dist/src/vite/storyReach.js

@@ -19,17 +19,21 @@ const reachedFrom = (imports, starts) => {
  */
 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)
-            ])
-        ]
-    })));
+    return graph.files.flatMap((file) => file.stories.map((story) => {
+        const starts = [
+            file.storyFile,
+            ...(file.component === undefined ? [] : [file.component.file]),
+            ...story.renders.map((ref) => ref.file)
+        ];
+        return {
+            title: titles.get(file.storyFile) ?? "",
+            exportName: story.exportName,
+            storyFile: file.storyFile,
+            files: [...reachedFrom(graph.imports, starts)],
+            own: [...new Set([...starts, ...(graph.imports[file.storyFile] ?? [])])],
+            ...(file.component === undefined ? {} : { metaFile: file.component.file })
+        };
+    }));
 };
 /**
  * The stories that reach any of the changed files, each once, in the graph's order.

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

@@ -0,0 +1,51 @@
+/**
+ * A story file's top level as the index and the story's code read it: its constants, the properties assigned to names
+ * after them, its meta object and the exports that are stories.
+ *
+ * @remarks
+ * Internal to the plugin: the index (`indexStoryFile.ts`) and the Code tab's texts (`storyCode.ts`) read a file the same
+ * way through it. Pure.
+ *
+ * @module
+ */
+import type { ESTree } from "vite";
+import { type Fields } from "./indexFields.ts";
+import { type NamedExport } from "./storyExports.ts";
+/** The file's top level, read once: its constants and the properties assigned to names. */
+export type TopLevel = {
+    /** Each constant's value, by name. */
+    readonly values: ReadonlyMap<string, ESTree.Expression>;
+    /** The properties assigned to a name after it (`A.storyName = "…"`), by name then property. */
+    readonly assigned: ReadonlyMap<string, ReadonlyMap<string, ESTree.Expression>>;
+};
+/**
+ * The file's top level: its constants, exported or not, and the properties assigned to names.
+ *
+ * @param program - the parsed file.
+ */
+export declare const topLevelOf: (program: ESTree.Program) => TopLevel;
+/**
+ * The object a value is, or the one the constants it names lead to (`export const B = A`); `undefined` for any other
+ * value, or for names that lead back to themselves.
+ *
+ * @param top - the file's top level.
+ * @param value - the value.
+ * @param seen - the names followed so far.
+ */
+export declare const objectOf: (top: TopLevel, value: ESTree.Expression | undefined, seen?: ReadonlySet<string>) => ESTree.ObjectExpression | undefined;
+/**
+ * The meta's object: the default export, inline or a constant of the file (`export default meta`,
+ * `export { meta as default }`).
+ *
+ * @param program - the parsed file.
+ * @param top - the file's top level.
+ */
+export declare const metaObject: (program: ESTree.Program, top: TopLevel) => ESTree.ObjectExpression | undefined;
+/**
+ * The exports that are stories, in the order of `__namedExportsOrder` when the file writes one, else of the file.
+ *
+ * @param program - the parsed file.
+ * @param top - the file's top level.
+ * @param meta - the meta's fields, for `includeStories` and `excludeStories`.
+ */
+export declare const storyExports: (program: ESTree.Program, top: TopLevel, meta: Fields) => NamedExport[];

package/dist/src/vite/storyTopLevel.js

@@ -0,0 +1,146 @@
+import { unwrapped } from "./indexFields.js";
+import { moduleName, namedExports } from "./storyExports.js";
+/**
+ * The property a top-level statement assigns to a name, when it assigns one.
+ *
+ * @param statement - the statement.
+ */
+const assignedProperty = (statement) => {
+    if (statement.type !== "ExpressionStatement")
+        return undefined;
+    const { expression } = statement;
+    if (expression.type !== "AssignmentExpression" || expression.left.type !== "MemberExpression")
+        return undefined;
+    const { object, property } = expression.left;
+    if (object.type !== "Identifier" || property.type !== "Identifier")
+        return undefined;
+    return { name: object.name, property: property.name, value: unwrapped(expression.right) };
+};
+/**
+ * The constants a top-level statement declares with a value, exported or not.
+ *
+ * @param statement - the statement.
+ */
+const declaredBy = (statement) => {
+    const declaration = statement.type === "ExportNamedDeclaration" ? statement.declaration : statement;
+    if (declaration?.type !== "VariableDeclaration")
+        return [];
+    return declaration.declarations.flatMap(({ id, init }) => id.type === "Identifier" && init !== null ? [{ name: id.name, value: unwrapped(init) }] : []);
+};
+/**
+ * The file's top level: its constants, exported or not, and the properties assigned to names.
+ *
+ * @param program - the parsed file.
+ */
+export const topLevelOf = (program) => {
+    const values = new Map();
+    const assigned = new Map();
+    for (const statement of program.body) {
+        for (const declared of declaredBy(statement))
+            values.set(declared.name, declared.value);
+        const property = assignedProperty(statement);
+        if (property === undefined)
+            continue;
+        const properties = assigned.get(property.name) ?? new Map();
+        properties.set(property.property, property.value);
+        assigned.set(property.name, properties);
+    }
+    return { values, assigned };
+};
+/**
+ * The object a value is, or the one the constants it names lead to (`export const B = A`); `undefined` for any other
+ * value, or for names that lead back to themselves.
+ *
+ * @param top - the file's top level.
+ * @param value - the value.
+ * @param seen - the names followed so far.
+ */
+export const objectOf = (top, value, seen = new Set()) => {
+    if (value?.type === "ObjectExpression")
+        return value;
+    if (value?.type !== "Identifier" || seen.has(value.name))
+        return undefined;
+    return objectOf(top, top.values.get(value.name), new Set([...seen, value.name]));
+};
+/**
+ * Whether an export is a story, as the meta's `includeStories` and `excludeStories` say (a list of names or a regular
+ * expression, written plainly).
+ *
+ * @param meta - the meta's fields.
+ * @param exportName - the export.
+ */
+const isIncluded = (meta, exportName) => {
+    const matches = (name) => {
+        const filter = meta(name);
+        if (filter?.type === "ArrayExpression")
+            return filter.elements.some((element) => element?.type === "Literal" && element.value === exportName);
+        if (filter?.type === "Literal" && "regex" in filter && filter.regex !== undefined)
+            return new RegExp(filter.regex.pattern, filter.regex.flags).test(exportName);
+        return undefined;
+    };
+    return matches("includeStories") !== false && matches("excludeStories") !== true;
+};
+/**
+ * The order `__namedExportsOrder` writes, when the file writes one plainly.
+ *
+ * @param top - the file's top level.
+ */
+const exportsOrder = (top) => {
+    const order = top.values.get("__namedExportsOrder");
+    if (order?.type !== "ArrayExpression")
+        return undefined;
+    return order.elements.flatMap((element) => element?.type === "Literal" && typeof element.value === "string" ? [element.value] : []);
+};
+/**
+ * The meta exported by name (`export { meta as default }`), when it is a constant of the file written as an object.
+ *
+ * @param program - the parsed file.
+ * @param top - the file's top level.
+ */
+const namedMeta = (program, top) => {
+    for (const statement of program.body) {
+        if (statement.type !== "ExportNamedDeclaration" || statement.source !== null)
+            continue;
+        const specifier = statement.specifiers.find((each) => moduleName(each.exported) === "default");
+        if (specifier === undefined)
+            continue;
+        const value = top.values.get(moduleName(specifier.local));
+        return value?.type === "ObjectExpression" ? value : undefined;
+    }
+    return undefined;
+};
+/**
+ * The meta's object: the default export, inline or a constant of the file (`export default meta`,
+ * `export { meta as default }`).
+ *
+ * @param program - the parsed file.
+ * @param top - the file's top level.
+ */
+export const metaObject = (program, top) => {
+    const meta = program.body.find((statement) => statement.type === "ExportDefaultDeclaration");
+    if (meta === undefined)
+        return namedMeta(program, top);
+    const { declaration } = meta;
+    if (declaration.type === "FunctionDeclaration" ||
+        declaration.type === "ClassDeclaration" ||
+        declaration.type === "TSInterfaceDeclaration")
+        return undefined;
+    const expression = unwrapped(declaration);
+    const value = expression.type === "Identifier" ? top.values.get(expression.name) : expression;
+    return value?.type === "ObjectExpression" ? value : undefined;
+};
+/**
+ * The exports that are stories, in the order of `__namedExportsOrder` when the file writes one, else of the file.
+ *
+ * @param program - the parsed file.
+ * @param top - the file's top level.
+ * @param meta - the meta's fields, for `includeStories` and `excludeStories`.
+ */
+export const storyExports = (program, top, meta) => {
+    const exported = namedExports(program).filter(({ exportName }) => exportName !== "__namedExportsOrder" && isIncluded(meta, exportName));
+    const order = exportsOrder(top);
+    if (order === undefined)
+        return exported;
+    const rank = (name) => (order.includes(name) ? order.indexOf(name) : order.length);
+    return [...exported].sort((first, second) => rank(first.exportName) - rank(second.exportName));
+};

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

@@ -4,12 +4,13 @@ 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.
+ * The tokens an agent is answered from: what the catalogue and its sources name or, when they name none, what the
+ * application already declares, which is read from its files and never run. A catalogue that says `tokens: []` wants
+ * none, so a named file is not the only way to say so.
  *
  * @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.
+ * @param watch - told of every file read; none by default.
  */
 export declare const catalogueTokens: (config: ResolvedConfig, resolveSource: ResolveSource, watch?: (file: string) => void) => Promise<TokenReading>;
 /**