forgebook 0.3.0 → 0.3.1

package/README.md

@@ -1028,7 +1028,8 @@ its `frame-src`, in the preview's `frameDomains`).
   read. Vite checks `Host`
   first (`server.allowedHosts`, plain HTTP only), which stops a site that reaches `127.0.0.1` through its own domain.
 - **Only the files your project names are listed or read.** A catalogue's `stories` and `docs`, and the groups a module
-  of yours imports (`?forgebook-files`), are the only groups the server reads, whatever an address names. A query that
+  of yours imports (`?forgebook-files`), are the only groups the server reads, whatever an address names: any other
+  answers 404. A catalogue's tab left open across a restart gets its groups all the same. A query that
   names one file (`?forgebook-code`, `?forgebook-markdown`) follows Vite's `server.fs`, as `?raw` does.
 - **`server.fs.deny` wins over your globs.** A file it refuses stays out of the catalogue, its search and "Used in", with
   a warning. A file your globs name outside `server.fs.allow` is listed and served, as Vite serves any file a module of

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

@@ -19,8 +19,13 @@ export declare const isFileRefused: (config: ResolvedConfig, file: string) => bo
 export declare const isQueriedFileReadable: (config: ResolvedConfig, id: string) => boolean;
 /** What a plugin's dev server lets a client read: `devServerAccess` makes it. */
 export type DevServerAccess = {
-    /** Starts on a dev server; until then (and in a build, which has none) nothing is refused. */
-    readonly serve: (server: ViteDevServer) => void;
+    /**
+     * Starts on a dev server; until then (and in a build, which has none) nothing is refused.
+     *
+     * @param server - the dev server.
+     * @param sources - the module that imports the configuration's sources; none without a configuration.
+     */
+    readonly serve: (server: ViteDevServer, sources: string | undefined) => void;
     /**
      * Whether a resolver's importer is a module, not the stand-in Vite gives an address asked for directly.
      *
@@ -36,16 +41,35 @@ export type DevServerAccess = {
     /** Whether a file a group lists may be read; says so once when not, as nothing else would tell why it is missing. */
     readonly isKept: IsFileKept;
     /**
-     * Whether a module is answered with nothing: a group no module imported, or a file `server.fs` refuses. Asked of every
-     * id, since an address can name an id directly, past the plugin's `resolveId`.
+     * Holds a request for a group no import has named until the configuration's sources have been read.
+     *
+     * @param url - the request's address.
+     */
+    readonly settle: (url: string) => Promise<void>;
+    /**
+     * What the plugin's load answers for a file's query `server.fs` refuses: an empty module and not Vite's 404, as Vite
+     * would then read a path with a `..` as written, past the check that refused it. Asked of every id, since an address
+     * can name an id directly, past the plugin's `resolveId`.
      *
      * @param id - the module's id.
+     * @returns the module, or none when the client may read the id.
+     * @throws for a group no module of the project imports, with Vite's code for a missing file.
      */
-    readonly isRefused: (id: string) => boolean;
+    readonly refusal: (id: string) => {
+        readonly code: string;
+        readonly moduleType: "js";
+    } | undefined;
 };
+/** What a plugin's dev server lets a client read. */
+export declare const devServerAccess: () => DevServerAccess;
 /**
- * What a plugin's dev server lets a client read.
- *
- * @param renew - renews modules Vite keeps: a group refused before its first import would otherwise stay empty.
+ * The plugin's hook for Vitest (`configureVitest`), whose module cache keeps each module's transform on disk between
+ * runs: a module read from it resolves no import, so a group it names would stay refused from the second run on.
  */
-export declare const devServerAccess: (renew: (server: ViteDevServer, ids: Iterable<string>) => void) => DevServerAccess;
+export declare const VITEST_HOOKS: {
+    configureVitest: (context: {
+        readonly defineCacheKeyGenerator?: (generator: (module: {
+            readonly sourceCode: string;
+        }) => false | undefined) => void;
+    }) => void;
+};

package/dist/src/vite/fileAccess.js

@@ -12,12 +12,23 @@
  * A group's id holds its patterns, so an id alone must never choose what is read: any address could name a folder to
  * list and read, and the imports the group's module writes would make Vite serve every file listed, past `allow`.
  *
+ * A group is named by a module's import, which the plugin sees when Vite transforms that module. A client may ask before
+ * that: a tab left open across a restart holds its modules and asks for a search index first. So a request for a group
+ * no import has named waits, before Vite starts on it, for the server to read what the configuration's sources import,
+ * the same modules a page would load: inside the group's load the reading could wait for a request that waits for it. A
+ * cache of transforms would hide the import for good, and Vitest keeps one on disk between runs: a module that names a
+ * group stays out of it.
+ *
+ * A group no module names answers as a missing file does: Vite answers 404, keeps no module to renew and raises no
+ * overlay on the pages open. A module's `export default null` would read as a group, and fail far from here in whatever
+ * reads it.
+ *
  * @module
  */
 import { realpathSync } from "node:fs";
 import { join } from "node:path";
-import { isFileLoadingAllowed } from "vite";
-import { isGroupId } from "./pluginIds.js";
+import { isCSSRequest, isFileLoadingAllowed } from "vite";
+import { isGroupId, namesGroup, namingGroupOf } from "./pluginIds.js";
 import { CODE_QUERY, DOCS_PAGE_QUERY, DOCS_QUERY, HOME_QUERY, MARKDOWN_QUERY, PAGE_QUERY } from "./textQueries.js";
 import { VITE_PATHS } from "./vitePaths.js";
 /** The queries the plugin answers with a file's text, so each read keeps to what the dev server may serve. */
@@ -69,25 +80,81 @@ export const isQueriedFileReadable = (config, id) => {
     return VITE_PATHS.normalize(file) === file && isFileLoadingAllowed(config, file);
 };
 /**
- * What a plugin's dev server lets a client read.
+ * Whether reading a module can show an import of a group: not a group (reading one waits for this reading) nor a file's
+ * query, which reads no import; not a style sheet or a pre-bundled dependency, which import none.
+ *
+ * @param environment - the environment the module is read in.
+ * @param module - the module.
+ */
+const mayNameGroup = (environment, module) => {
+    const { id, url } = module;
+    return (id !== null &&
+        !isCSSRequest(url) &&
+        !isGroupId(id) &&
+        !FILE_QUERIES.some((query) => id.endsWith(query)) &&
+        environment.depsOptimizer?.isOptimizedDepUrl(url) !== true);
+};
+/**
+ * Reads a module and what it imports, for the imports the plugin sees on the way.
+ *
+ * @param environment - the environment to read them in.
+ * @param entry - the module's address.
+ * @returns whether each could be read: one that could not may name a group once it is fixed.
+ */
+const readImports = async (environment, entry) => {
+    const seen = new Set([entry]);
+    const read = async (url) => {
+        try {
+            await environment.transformRequest(url);
+        }
+        catch {
+            return false;
+        }
+        const module = await environment.moduleGraph.getModuleByUrl(url);
+        const next = [...(module?.importedModules ?? [])].filter((imported) => !seen.has(imported.url) && mayNameGroup(environment, imported));
+        for (const imported of next)
+            seen.add(imported.url);
+        const reads = await Promise.all(next.map((imported) => read(imported.url)));
+        return reads.every(Boolean);
+    };
+    return read(entry);
+};
+/**
+ * The id of the group a request's address names, when it names one: any spelling this misses reaches the plugin's load,
+ * which refuses it all the same.
  *
- * @param renew - renews modules Vite keeps: a group refused before its first import would otherwise stay empty.
+ * @param url - the request's address.
  */
-export const devServerAccess = (renew) => {
+const groupIdOf = (url) => {
+    try {
+        const path = decodeURI(url.split("?")[0] ?? "");
+        const at = path.indexOf("virtual:forgebook-");
+        return at === -1 ? undefined : `\0${path.slice(at)}`;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** Vite's code for a file it could not load: its server answers 404, with no overlay, and a runner fails with the text. */
+const MISSING_MODULE = "ERR_LOAD_URL";
+/** What a plugin's dev server lets a client read. */
+export const devServerAccess = () => {
     let devServer;
     let addressImporter;
+    let sourcesEntry;
+    /** The reading of the sources: once, as an edit that names a new group is seen when Vite transforms it. */
+    let sourcesRead;
     const imported = new Set();
-    const refused = new Set();
     return {
-        serve: (server) => {
+        serve: (server, sources) => {
             devServer = server;
             addressImporter = join(server.config.root, "index.html");
+            sourcesEntry = sources;
+            sourcesRead = undefined;
         },
         isModule: (importer) => importer !== undefined && importer !== addressImporter,
         noteImported: (id) => {
-            imported.add(id);
-            if (refused.delete(id) && devServer !== undefined)
-                renew(devServer, [id]);
+            imported.add(namingGroupOf(id));
         },
         isKept: (file) => {
             if (devServer === undefined || !isFileRefused(devServer.config, file))
@@ -95,15 +162,38 @@ export const devServerAccess = (renew) => {
             devServer.config.logger.warnOnce(`Forgebook leaves out ${file}: Vite's server.fs refuses it`);
             return false;
         },
-        isRefused: (id) => {
+        settle: async (url) => {
+            const id = groupIdOf(url);
+            if (id === undefined || devServer === undefined || sourcesEntry === undefined)
+                return;
+            if (imported.has(namingGroupOf(id)))
+                return;
+            sourcesRead ??= readImports(devServer.environments.client, sourcesEntry).then((isRead) => {
+                if (!isRead)
+                    sourcesRead = undefined;
+            });
+            await sourcesRead;
+        },
+        refusal: (id) => {
             if (devServer === undefined)
-                return false;
+                return undefined;
             if (!isGroupId(id))
-                return (FILE_QUERIES.some((query) => id.endsWith(query)) && !isQueriedFileReadable(devServer.config, id));
-            if (imported.has(id))
-                return false;
-            refused.add(id);
-            return true;
+                return FILE_QUERIES.some((query) => id.endsWith(query)) &&
+                    !isQueriedFileReadable(devServer.config, id)
+                    ? { code: "export default null;", moduleType: "js" }
+                    : undefined;
+            if (imported.has(namingGroupOf(id)))
+                return undefined;
+            throw Object.assign(new Error(`Forgebook serves a group of files only when a module imports it: no module of the project imports ${id.slice(1)}`), { code: MISSING_MODULE });
         }
     };
 };
+/**
+ * The plugin's hook for Vitest (`configureVitest`), whose module cache keeps each module's transform on disk between
+ * runs: a module read from it resolves no import, so a group it names would stay refused from the second run on.
+ */
+export const VITEST_HOOKS = {
+    configureVitest: (context) => {
+        context.defineCacheKeyGenerator?.(({ sourceCode }) => (namesGroup(sourceCode) ? false : undefined));
+    }
+};

package/dist/src/vite/forgebookPlugin.js

@@ -33,7 +33,7 @@ import { currentCloseWatch } from "./closeWatch.js";
 import { findConfigFile, loadConfigFile, packageResolver } from "./configFile.js";
 import { codeStamp, diskCache } from "./diskCache.js";
 import { createDocsExtractor, NO_DOCS_EXTRACTOR } from "./docsExtractor.js";
-import { devServerAccess } from "./fileAccess.js";
+import { devServerAccess, VITEST_HOOKS } from "./fileAccess.js";
 import { FORCED_STATES_VISITOR } from "./forcedStates.js";
 import { builtPlacement } from "./framesConfig.js";
 import { serveFrames } from "./framesServer.js";
@@ -137,7 +137,7 @@ export const forgebookPlugin = (options = {}) => {
     /** The groups' search indexes: any edit may change what a component's docs say. */
     const searchModules = new Set();
     /** What a client may read of a dev server. */
-    const access = devServerAccess(invalidateEverywhere);
+    const access = devServerAccess();
     /** The errors the open frames report, for `forgebook errors` and the agents. */
     const live = createLiveErrors();
     /** Where the frames run: the dev server's second port once it listens, the configuration's choice in a build. */
@@ -392,7 +392,10 @@ export const forgebookPlugin = (options = {}) => {
                 resolved.logger.warn(`Forgebook's shell theme: ${problem}`);
         },
         configureServer: (server) => {
-            access.serve(server);
+            access.serve(server, config === undefined ? undefined : pageModulePath(config.dir, AGENT_SOURCES_FILE));
+            server.middlewares.use((request, _response, next) => {
+                access.settle(request.url ?? "/").then(() => next(), next);
+            });
             // no person waits for a page in a test run
             watching.serve(isTestRun ? undefined : server);
             server.httpServer?.on("close", () => void docs?.close());
@@ -466,13 +469,14 @@ export const forgebookPlugin = (options = {}) => {
             await docs?.close();
         },
         ...storyFileHotHooks(isRedrawing, served.changedBy, watching),
+        ...VITEST_HOOKS,
         async load(id) {
             const generated = await pagesModule(id);
             if (generated !== undefined)
                 return generated;
-            // an answer, not an error: an error would raise Vite's overlay on every reader's open page
-            if (access.isRefused(id))
-                return { code: "export default null;", moduleType: "js" };
+            const refusal = access.refusal(id);
+            if (refusal !== undefined)
+                return refusal;
             // in Vite's form, the text Vite's module graph knows a file by: a Node path on Windows (`C:\app\x.md`) is another
             const watch = (file) => this.addWatchFile(VITE_PATHS.normalize(file));
             const resolveImport = async (specifier, importer) => {

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

@@ -21,6 +21,21 @@ export declare const virtualId: (source: string) => string | undefined;
  * @param id - the module's id.
  */
 export declare const isGroupId: (id: string) => boolean;
+/**
+ * The group a project's module names for a group's module: the story files of their "Used in", reach, search index and
+ * texts, the docs pages of their search index. Those read the same files and only their group's module imports them, so
+ * a client that already holds the group's module needs no other import to have been seen.
+ *
+ * @param id - a group's module's id.
+ */
+export declare const namingGroupOf: (id: string) => string;
+/**
+ * Whether a module's text names a group. Its transform must run for the plugin to see the import, so a cache of
+ * transforms must not keep it.
+ *
+ * @param code - the module's text.
+ */
+export declare const namesGroup: (code: string) => boolean;
 /** The resolved id of the configuration's data module. */
 export declare const CONFIG_ID = "\0virtual:forgebook/config";
 /** The resolved id of the design tokens' module. */

package/dist/src/vite/pluginIds.js

@@ -70,6 +70,29 @@ export const virtualId = (source) => {
  * @param id - the module's id.
  */
 export const isGroupId = (id) => VIRTUAL_PREFIXES.some((prefix) => id.startsWith(`\0${prefix}`));
+/** The modules that read a group of story files' own files: named once its story files are. */
+const STORY_FILES_READERS = [USAGE_PREFIX, REACH_PREFIX, SEARCH_PREFIX, TEXTS_PREFIX];
+/**
+ * The group a project's module names for a group's module: the story files of their "Used in", reach, search index and
+ * texts, the docs pages of their search index. Those read the same files and only their group's module imports them, so
+ * a client that already holds the group's module needs no other import to have been seen.
+ *
+ * @param id - a group's module's id.
+ */
+export const namingGroupOf = (id) => {
+    const pagesSearch = `\0${PAGES_SEARCH_PREFIX}`;
+    if (id.startsWith(pagesSearch))
+        return `${DOCS_PAGES_PREFIX}${id.slice(pagesSearch.length)}`;
+    const reader = STORY_FILES_READERS.map((prefix) => `\0${prefix}`).find((mark) => id.startsWith(mark));
+    return reader === undefined ? id : `${FILES_PREFIX}${id.slice(reader.length)}`;
+};
+/**
+ * Whether a module's text names a group. Its transform must run for the plugin to see the import, so a cache of
+ * transforms must not keep it.
+ *
+ * @param code - the module's text.
+ */
+export const namesGroup = (code) => [FILES_QUERY, DOCS_PAGES_QUERY, ...VIRTUAL_PREFIXES].some((name) => code.includes(name));
 /** The resolved id of the configuration's data module. */
 export const CONFIG_ID = `\0${CONFIG_MODULE}`;
 /** The resolved id of the design tokens' module. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgebook",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "See every component in every theme, contrast, language and width: CSF stories, one frame per story, and a props table from the components' types.",
   "keywords": [
     "react",
@@ -240,7 +240,7 @@
     "lightningcss": "1.33.0",
     "marked": "18.1.0",
     "typescript-6": "npm:typescript@6.0.3",
-    "@forgebook/story-format": "0.2.1"
+    "@forgebook/story-format": "0.2.2"
   },
   "peerDependencies": {
     "@testing-library/dom": "^10.4.0",
@@ -262,8 +262,8 @@
     "sass-embedded": "1.106.1",
     "vite": "8.3.5",
     "vitest": "5.0.5",
-    "@forgebook/tools": "0.0.0",
-    "@forgebook/typescript-config": "0.0.0"
+    "@forgebook/typescript-config": "0.0.0",
+    "@forgebook/tools": "0.0.0"
   },
   "peerDependenciesMeta": {
     "@testing-library/dom": {