forgebook 0.3.3 → 0.4.1

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

@@ -38,15 +38,28 @@ export declare const KEPT_PROGRAMS = 4;
  * one component at a time. A reader of everything asks for it (`programFor`'s `reach`).
  */
 export declare const readAskedFilesOnly: () => void;
-/** What a program is read for: what the asked file reaches, or every file of its configuration. */
-export type ProgramReach = "asked" | "whole";
+/**
+ * From now on a program holds the given story files its configuration lists and what they import, not its whole
+ * configuration: a build reads every story's docs and "Used in", which need nothing the stories do not reach. Each
+ * program is then built once, its roots known from the start. Called again, it adds to the files.
+ *
+ * @param files - the story files, absolute.
+ */
+export declare const readStoryFilesOnly: (files: readonly string[]) => void;
+/**
+ * What a program is read for: what the asked file reaches; what every story file of its configuration reaches (a
+ * group's "Used in"), which is every file of it unless a build named its story files (`readStoryFilesOnly`); or every
+ * file of its configuration (where an application draws a component).
+ */
+export type ProgramReach = "asked" | "stories" | "whole";
 /** How a file's program is read. */
 export type ProgramOptions = {
     /** The files read in place of a framework's components; none for a plain program. */
     readonly sources?: ProgramSources;
     /**
-     * What the reader needs: what the file reaches (a component's docs, the default), or every file of its
-     * configuration (a group's "Used in"); either way a build's programs hold every file.
+     * What the reader needs: what the file reaches (a component's docs, the default), what the stories reach (a group's
+     * "Used in"), or every file of its configuration; a build's programs hold what its stories reach, or every file
+     * when it named none.
      */
     readonly reach?: ProgramReach;
 };

package/dist/src/vite/docsProgram.js

@@ -18,6 +18,9 @@
  * - a dev server's programs hold the files asked for and what they import (`readAskedFilesOnly`), with the files that
  *   hold for every file (declarations, augmentations), not every file of the configuration, until enough are asked
  *   that the whole is cheaper (`MOST_ASKED`);
+ * - a build's programs hold its story files and what they import (`readStoryFilesOnly`), with the same files that hold
+ *   for every file: a monorepo's root configuration lists every package, its website and its tools, and one story it
+ *   holds would otherwise parse them all;
  * - parsed files are kept between programs and shared by every configuration that parses alike (`parsedFiles.ts`),
  *   the standard library's and `@types` without their documentation;
  * - only the programs read last are kept (`KEPT_PROGRAMS`), with the parses they hold.
@@ -119,6 +122,22 @@ export const readAskedFilesOnly = () => {
     askedFiles ??= new Map();
     checkFileChanges();
 };
+/** A build's story files, in TypeScript's form; none until a build names them, and every file is read then. */
+let storyFiles;
+/** The files a build asked for that its story files do not reach, by program: they stay roots, or it would be rebuilt. */
+const addedRoots = new Map();
+/**
+ * From now on a program holds the given story files its configuration lists and what they import, not its whole
+ * configuration: a build reads every story's docs and "Used in", which need nothing the stories do not reach. Each
+ * program is then built once, its roots known from the start. Called again, it adds to the files.
+ *
+ * @param files - the story files, absolute.
+ */
+export const readStoryFilesOnly = (files) => {
+    storyFiles ??= new Set();
+    for (const file of files)
+        storyFiles.add(file.replaceAll("\\", "/"));
+};
 /**
  * The files asked for before a program takes all its configuration's files: each new root makes a new type checker,
  * so a session that walks a whole library would pay more than the whole program costs at once.
@@ -143,8 +162,26 @@ const ambientOf = (read) => {
     return found;
 };
 /**
- * The root files of a configuration's program: all of them, or, once only what is asked for is read, its ambient
- * files and the files asked for so far, until enough are asked that the whole is cheaper.
+ * The root files of a build's program once it named its story files: the configuration's ambient files, the story files
+ * it lists, and the files asked for that none of them reached, kept so the roots stay the same.
+ *
+ * @param key - the program's key.
+ * @param read - its configuration.
+ * @param stories - the build's story files.
+ * @param asked - a file asked for that the program does not hold yet, which the configuration lists; none otherwise.
+ */
+const storyRootsOf = (key, read, stories, asked) => {
+    const added = addedRoots.get(key) ?? new Set();
+    addedRoots.set(key, added);
+    if (asked !== undefined && !stories.has(asked))
+        added.add(asked);
+    const listed = read.parsed.fileNames.filter((each) => stories.has(each));
+    return [...new Set([...ambientOf(read), ...listed, ...added])];
+};
+/**
+ * The root files of a configuration's program: all of them; or, once a build named its story files, its ambient files,
+ * the story files it lists and a file asked for that none of them reaches; or, once only what is asked for is read, its
+ * ambient files and the files asked for so far, until enough are asked that the whole is cheaper.
  *
  * @param key - the program's key.
  * @param read - its configuration.
@@ -153,20 +190,24 @@ const ambientOf = (read) => {
  */
 const rootsOf = (key, read, file, reach) => {
     const { fileNames } = read.parsed;
-    if (askedFiles === undefined)
-        return fileNames;
+    // a file the kept program reaches through an import needs no root of its own, while that program is current
+    const name = file.replaceAll("\\", "/");
+    const isHeld = !outdated.has(key) && programs.get(key)?.getSourceFile(name) !== undefined;
+    const isOwnRoot = !isHeld && read.fileSet.has(name);
+    if (askedFiles === undefined) {
+        if (storyFiles === undefined || reach === "whole")
+            return fileNames;
+        return storyRootsOf(key, read, storyFiles, isOwnRoot ? name : undefined);
+    }
     const asked = askedFiles.get(key) ?? new Set();
     askedFiles.set(key, asked);
     // a program read whole stays whole: going back and forth would build it again each time
-    if (reach === "whole")
-        for (const name of fileNames)
-            asked.add(name);
+    if (reach !== "asked")
+        for (const each of fileNames)
+            asked.add(each);
     if (asked.size >= MOST_ASKED)
         return fileNames;
-    // a file the kept program reaches through an import needs no root of its own, while that program is current
-    const name = file.replaceAll("\\", "/");
-    const isHeld = !outdated.has(key) && programs.get(key)?.getSourceFile(name) !== undefined;
-    if (!isHeld && read.fileSet.has(name))
+    if (isOwnRoot)
         asked.add(name);
     return [...new Set([...ambientOf(read), ...asked])];
 };

package/dist/src/vite/docsWorker.js

@@ -15,7 +15,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
  * Started by `docsExtractor.ts` with the framework's docs module (`adapter.ts`), which it loads once; it keeps the
  * programs of `docsProgram.ts` between requests, so only a package's first
  * read builds one, and a changed source file (`{ kind: "changed" }`) renews them on their next read. A usage request
- * (`{ kind: "usage", id, files }`) is answered from the same programs (`usageGraph.ts`). A request is `{ id, storyFile }`, the answer `{ id, result }`, `extractStoryComponent`'s result as
+ * (`{ kind: "usage", id, files }`) is answered from the same programs (`usageGraph.ts`). A build names its story files
+ * first (`{ kind: "stories", files }`), so its programs hold what they reach (`readStoryFilesOnly`). A request is `{ id, storyFile }`, the answer `{ id, result }`, `extractStoryComponent`'s result as
  * it is (plain data), with the files it can change with (`docsDependencies.ts`), which the dev server keeps it on disk
  * with. Unasked, it says `{ kind: "loaded" }` once its modules are loaded.
  *
@@ -25,7 +26,7 @@ import { parentPort, workerData } from "node:worker_threads";
 import { isDocsModule } from "./adapter.js";
 import { isSettledSince, nowNs, stampPaths } from "./diskCache.js";
 import { docsDependencies } from "./docsDependencies.js";
-import { markSourcesChanged, readAskedFilesOnly } from "./docsProgram.js";
+import { markSourcesChanged, readAskedFilesOnly, readStoryFilesOnly } from "./docsProgram.js";
 import { usageGraph } from "./usageGraph.js";
 /** Whether the worker's data names a docs module. */
 const isWorkerData = (value) => typeof value === "object" &&
@@ -104,6 +105,10 @@ parentPort?.on("message", (request) => {
         });
         return;
     }
+    if (request.kind === "stories") {
+        readStoryFilesOnly(request.files);
+        return;
+    }
     if (request.kind === "usage") {
         const since = nowNs();
         const result = usage(request.files);

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

@@ -0,0 +1,41 @@
+/**
+ * The patterns of a catalogue's own stories that match no story file, and what the plugin, the commands and the agent API
+ * say of them.
+ *
+ * @module
+ */
+import type { Logger } from "vite";
+import type { ResolvedConfig } from "./configFile.ts";
+/**
+ * The patterns of a catalogue's own stories that match no story file, each of them a mistake or a first story not yet
+ * written: a `forgebook build` stops on them, a dev server says so and waits. A source's patterns are its own module's,
+ * which only Vite can read.
+ *
+ * @param config - the catalogue's folder and stories.
+ */
+export declare const emptyStoryGlobs: (config: Pick<ResolvedConfig, "dir" | "stories">) => readonly string[];
+/**
+ * What to say of the patterns of `emptyStoryGlobs`.
+ *
+ * @param globs - the patterns, at least one.
+ */
+export declare const emptyStoryGlobsMessage: (globs: readonly string[]) => string;
+/**
+ * What `verify` says of the patterns of `emptyStoryGlobs`, as problems of the catalogue that leave its answer not
+ * verified while the rest of it is still given.
+ *
+ * @param config - the catalogue's folder and stories.
+ * @returns one problem naming every such pattern; none when each matches a file.
+ */
+export declare const emptyStoryGlobsProblems: (config: Pick<ResolvedConfig, "dir" | "stories">) => string[];
+/**
+ * Says what the plugin has to say of the patterns of `emptyStoryGlobs`, and of story files in hidden folders they pass
+ * over (`hiddenStoryFolders.ts`), which only warn: a hidden folder may be left out on purpose.
+ *
+ * @param config - the catalogue's folder and stories.
+ * @param isServing - whether a dev server runs: whoever runs one may be about to write the first story, while a build's
+ *   reader would find nothing.
+ * @param logger - where a dev server's warning goes.
+ * @throws in a build, when a pattern matches nothing.
+ */
+export declare const sayEmptyStoryGlobs: (config: Pick<ResolvedConfig, "dir" | "stories">, isServing: boolean, logger: Pick<Logger, "warn">) => void;

package/dist/src/vite/emptyStoryGlobs.js

@@ -0,0 +1,52 @@
+import { hiddenStoryFolders, hiddenStoryFoldersMessage } from "./hiddenStoryFiles.js";
+import { unmatchedPatterns } from "./storyPatterns.js";
+/**
+ * The patterns of a catalogue's own stories that match no story file, each of them a mistake or a first story not yet
+ * written: a `forgebook build` stops on them, a dev server says so and waits. A source's patterns are its own module's,
+ * which only Vite can read.
+ *
+ * @param config - the catalogue's folder and stories.
+ */
+export const emptyStoryGlobs = (config) => unmatchedPatterns(config.dir, config.stories);
+/**
+ * What to say of the patterns of `emptyStoryGlobs`.
+ *
+ * @param globs - the patterns, at least one.
+ */
+export const emptyStoryGlobsMessage = (globs) => `No story file matches ${globs.map((glob) => `"${glob}"`).join(", ")} (\`stories\` in the configuration)`;
+/**
+ * What `verify` says of the patterns of `emptyStoryGlobs`, as problems of the catalogue that leave its answer not
+ * verified while the rest of it is still given.
+ *
+ * @param config - the catalogue's folder and stories.
+ * @returns one problem naming every such pattern; none when each matches a file.
+ */
+export const emptyStoryGlobsProblems = (config) => {
+    const globs = emptyStoryGlobs(config);
+    return globs.length === 0
+        ? []
+        : [
+            `${emptyStoryGlobsMessage(globs)}: correct the pattern, or write the first story (npx forgebook new <component file>)`
+        ];
+};
+/**
+ * Says what the plugin has to say of the patterns of `emptyStoryGlobs`, and of story files in hidden folders they pass
+ * over (`hiddenStoryFolders.ts`), which only warn: a hidden folder may be left out on purpose.
+ *
+ * @param config - the catalogue's folder and stories.
+ * @param isServing - whether a dev server runs: whoever runs one may be about to write the first story, while a build's
+ *   reader would find nothing.
+ * @param logger - where a dev server's warning goes.
+ * @throws in a build, when a pattern matches nothing.
+ */
+export const sayEmptyStoryGlobs = (config, isServing, logger) => {
+    const hidden = hiddenStoryFolders(config);
+    if (hidden.length > 0)
+        logger.warn(`Forgebook: ${hiddenStoryFoldersMessage(hidden)}.`);
+    const globs = emptyStoryGlobs(config);
+    if (globs.length === 0)
+        return;
+    if (!isServing)
+        throw new Error(emptyStoryGlobsMessage(globs));
+    logger.warn(`Forgebook: ${emptyStoryGlobsMessage(globs)}. The catalogue shows them as soon as a file does.`);
+};

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

@@ -0,0 +1,17 @@
+/** An import a file writes. */
+export type WrittenImport = {
+    /** The names it brings in, as the module exports them; `default` for a default import. */
+    readonly names: readonly string[];
+    /** The module. */
+    readonly module: string;
+    /** Its first and last lines. */
+    readonly lines: readonly [number, number];
+};
+/**
+ * The value imports a file writes, read from its syntax, so a comment or a string holding the word is not one; a
+ * single-file component's from its scripts.
+ *
+ * @param file - its path.
+ * @param text - its text.
+ */
+export declare const importsOfFile: (file: string, text: string) => WrittenImport[];

package/dist/src/vite/fileImports.js

@@ -0,0 +1,57 @@
+/**
+ * The imports a file writes, read from its syntax, so a comment or a string holding the word is not one.
+ *
+ * @module
+ */
+import { parseSync } from "vite";
+import { isTooDeep, lineAt, lineStarts } from "./sourceText.js";
+/** The value imports of a script's text, whose lines start from an offset. */
+const importsOfScript = (file, text, firstLine) => {
+    if (isTooDeep(text))
+        return [];
+    const { program, errors } = parseSync(file, text);
+    if (errors.length > 0)
+        return [];
+    const starts = lineStarts(text);
+    return program.body.flatMap((statement) => {
+        if (statement.type !== "ImportDeclaration" || statement.importKind === "type")
+            return [];
+        const names = statement.specifiers.flatMap((each) => {
+            if (each.type === "ImportDefaultSpecifier")
+                return ["default"];
+            if (each.type !== "ImportSpecifier" || each.importKind === "type")
+                return [];
+            return ["name" in each.imported ? String(each.imported.name) : String(each.imported.value)];
+        });
+        const lines = [statement.start, statement.end].map((offset) => lineAt(starts, offset) + firstLine - 1);
+        return [{ names, module: statement.source.value, lines: [lines[0] ?? firstLine, lines[1] ?? firstLine] }];
+    });
+};
+/** A framework's own single-file component. */
+const SINGLE_FILE = /\.(?:vue|svelte|astro)$/;
+/**
+ * The value imports a file writes, read from its syntax, so a comment or a string holding the word is not one; a
+ * single-file component's from its scripts.
+ *
+ * @param file - its path.
+ * @param text - its text.
+ */
+export const importsOfFile = (file, text) => {
+    try {
+        if (!SINGLE_FILE.test(file))
+            return importsOfScript(file, text, 1);
+        const found = [];
+        const starts = lineStarts(text);
+        for (let open = text.indexOf("<script"); open !== -1; open = text.indexOf("<script", open + 1)) {
+            const opened = text.indexOf(">", open);
+            const close = text.indexOf("</script>", opened);
+            if (opened === -1 || close === -1)
+                break;
+            found.push(...importsOfScript("script.ts", text.slice(opened + 1, close), lineAt(starts, opened)));
+        }
+        return found;
+    }
+    catch {
+        return [];
+    }
+};

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

@@ -1,3 +1,4 @@
+import { type SearchCorrection } from "../searchTypos.ts";
 /** What the search reads of a component. */
 export type FindableComponent = {
     /** Its id. */
@@ -22,11 +23,18 @@ export type FoundComponent = {
     /** The words of the query it does not. */
     readonly missed: readonly string[];
 };
+/** What a query finds. */
+export type FoundComponents = {
+    /** Up to five, best first; none when no word matches. */
+    readonly components: readonly FoundComponent[];
+    /** The words nothing held as typed, and what each was read as; empty when the query was read as typed. */
+    readonly corrections: readonly SearchCorrection[];
+};
 /**
  * The components a query describes, best first.
  *
  * @param components - the catalogue's components.
  * @param query - what is being looked for, in any words.
- * @returns up to five; none when no word matches.
+ * @returns up to five, and the words read as others.
  */
-export declare const findComponents: (components: readonly FindableComponent[], query: string) => FoundComponent[];
+export declare const findComponents: (components: readonly FindableComponent[], query: string) => FoundComponents;

package/dist/src/vite/findComponent.js

@@ -7,11 +7,12 @@
  * (`keywords` in the meta, the way to say "radio tile group" of `OptionCards`), then its title and its stories' text. A
  * short list of synonyms bridges the words designers and code use for the same thing (`searchMatch.ts`, which the
  * catalogue's text search reads too). The answer says which words matched, so an agent can tell a strong result from a
- * guess.
+ * guess, and which words nothing held as typed and were read as a name a letter or two away.
  *
  * @module
  */
 import { wordsOf, worthOf } from "../searchMatch.js";
+import { correctedQuery } from "../searchTypos.js";
 /** How many components an answer gives. */
 const LIMIT = 5;
 /** A component's words. */
@@ -21,32 +22,36 @@ const partsOf = (component) => ({
     title: wordsOf(component.title),
     story: component.stories.flatMap(wordsOf)
 });
+/** Each component holding a word, best first. */
+const ranked = (components, words) => components
+    .flatMap(({ component, parts }) => {
+    const scores = words.map((word) => ({ word, score: worthOf(parts, word) }));
+    const score = scores.reduce((sum, each) => sum + each.score, 0);
+    if (score === 0)
+        return [];
+    return [
+        {
+            id: component.id,
+            title: component.title,
+            score,
+            matched: scores.filter((each) => each.score > 0).map((each) => each.word),
+            missed: scores.filter((each) => each.score === 0).map((each) => each.word)
+        }
+    ];
+})
+    .toSorted((first, second) => second.score - first.score);
 /**
  * The components a query describes, best first.
  *
  * @param components - the catalogue's components.
  * @param query - what is being looked for, in any words.
- * @returns up to five; none when no word matches.
+ * @returns up to five, and the words read as others.
  */
 export const findComponents = (components, query) => {
-    const words = wordsOf(query);
-    return components
-        .flatMap((component) => {
-        const parts = partsOf(component);
-        const scores = words.map((word) => ({ word, score: worthOf(parts, word) }));
-        const score = scores.reduce((sum, each) => sum + each.score, 0);
-        if (score === 0)
-            return [];
-        return [
-            {
-                id: component.id,
-                title: component.title,
-                score,
-                matched: scores.filter((each) => each.score > 0).map((each) => each.word),
-                missed: scores.filter((each) => each.score === 0).map((each) => each.word)
-            }
-        ];
-    })
-        .toSorted((first, second) => second.score - first.score)
-        .slice(0, LIMIT);
+    const typed = [...new Set(wordsOf(query))];
+    const parted = components.map((component) => ({ component, parts: partsOf(component) }));
+    const strict = ranked(parted, typed);
+    const { corrections, words } = correctedQuery(typed, new Set(strict.flatMap((each) => each.matched)), parted.map(({ parts }) => parts));
+    const found = corrections.length === 0 ? strict : ranked(parted, words);
+    return { components: found.slice(0, LIMIT), corrections };
 };

package/dist/src/vite/findRoute.js

@@ -45,7 +45,8 @@ export const findAnswer = async ({ tree, params, pages, view, loaded }) => {
         return { status: 400, body: { error: "No words to look for" } };
     const located = treeComponents(tree);
     const findable = located.map(({ component }) => findableOf(component));
-    const components = await Promise.all(findComponents(findable, query).map(async (found) => {
+    const { components: found, corrections } = findComponents(findable, query);
+    const components = await Promise.all(found.map(async (found) => {
         const place = located.find(({ component }) => component.id === found.id);
         const story = place?.component.stories[0]?.id;
         const source = loaded.sources.find((each) => each.id === place?.source.id);
@@ -57,6 +58,6 @@ export const findAnswer = async ({ tree, params, pages, view, loaded }) => {
             ...(guidance === undefined ? {} : { guidance })
         };
     }));
-    const body = { schema: 1, query, components };
+    const body = { schema: 1, query, components, corrections };
     return { status: 200, body };
 };

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

@@ -24,7 +24,14 @@ export declare const FORCE_ATTRIBUTE = "data-forgebook-force";
  */
 export declare const forcedSelector: (selector: Selector) => Selector;
 /**
- * The Lightning CSS visitor that applies the rewrite to every style sheet the catalogue builds, with the touch
- * simulation's (`touchMedia.ts`): the media rules that ask about the pointer follow the simulated touch.
+ * Whether a selector styles the catalogue's own interface: a story never forces a state on it, and nothing simulates
+ * touch on the shell's page, so the rewrite would only add to the catalogue's CSS.
+ *
+ * @param selector - a selector, as Lightning CSS parses it.
+ */
+export declare const isCatalogueSelector: (selector: Selector) => boolean;
+/**
+ * The Lightning CSS visitor that applies the rewrite to every style sheet the catalogue builds but its own, with the
+ * touch simulation's (`touchMedia.ts`): the media rules that ask about the pointer follow the simulated touch.
  */
 export declare const FORCED_STATES_VISITOR: Visitor<CustomAtRules>;

package/dist/src/vite/forcedStates.js

@@ -65,11 +65,20 @@ const withNested = (component) => {
 export const forcedSelector = (selector) => selector.map((component) => component.type === "pseudo-class" && isForceable(component.kind)
     ? realOrForced(component.kind)
     : withNested(component));
+/** The prefix of every class of the catalogue's own interface, in the shell and in the frame. */
+const CATALOGUE_CLASS = "forgebook-";
 /**
- * The Lightning CSS visitor that applies the rewrite to every style sheet the catalogue builds, with the touch
- * simulation's (`touchMedia.ts`): the media rules that ask about the pointer follow the simulated touch.
+ * Whether a selector styles the catalogue's own interface: a story never forces a state on it, and nothing simulates
+ * touch on the shell's page, so the rewrite would only add to the catalogue's CSS.
+ *
+ * @param selector - a selector, as Lightning CSS parses it.
+ */
+export const isCatalogueSelector = (selector) => selector.some((component) => component.type === "class" && component.name.startsWith(CATALOGUE_CLASS));
+/**
+ * The Lightning CSS visitor that applies the rewrite to every style sheet the catalogue builds but its own, with the
+ * touch simulation's (`touchMedia.ts`): the media rules that ask about the pointer follow the simulated touch.
  */
 export const FORCED_STATES_VISITOR = {
-    Selector: forcedSelector,
+    Selector: (selector) => isCatalogueSelector(selector) ? selector : forcedSelector(selector),
     Rule: { media: touchMediaRules }
 };

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

@@ -15,6 +15,8 @@ export type ForgebookPluginOptions = {
     readonly framework?: FrameworkAdapter;
     /** Folders outside the app the dev server watches for new story files, beside the configuration's `watch`. */
     readonly watch?: readonly string[];
+    /** Whether the dependency scan is a first start's quick one (`ScanFindings.isQuick`); off by default. */
+    readonly isQuickScan?: boolean;
 };
 /**
  * The catalogue's Vite plugin: the story index, the docs, the code and the Markdown of the stories, the forced-states