forgebook 0.1.8 → 0.3.0

package/dist/src/vite/parsedFiles.js

@@ -0,0 +1,91 @@
+/**
+ * The files the docs' TypeScript programs parse, kept between programs and shared by every configuration that parses
+ * alike, as TypeScript's language service groups them.
+ *
+ * @remarks
+ * A renewed program reuses a file only when its compiler host hands back the same object, so without a kept parse
+ * every renewal parses everything again; and in a monorepo whose paths lead every package to every other's sources,
+ * each package's program holds the same thousands of files. A kept parse is reused while the file is unchanged, told by
+ * its change time and size (`stampOf`), which a write moves even when it keeps the modification time. A build, which
+ * changes no file, skips that check until something says files may change (`checkFileChanges`).
+ *
+ * The standard library's declarations and `@types` packages are parsed without their documentation: most of what
+ * `lib.dom.d.ts` and a framework's types weigh, which no component's docs read. Other declarations in `node_modules`
+ * keep theirs, since a catalogue may document an installed library.
+ *
+ * @module
+ */
+import { statSync } from "node:fs";
+import { dirname } from "node:path";
+import ts from "typescript-6";
+/** What tells which configurations parse a file alike, as TypeScript's language service groups them. */
+const DOCUMENT_REGISTRY = ts.createDocumentRegistry();
+/** The parsed files of each way of parsing, by file name and version. */
+const parsedFiles = new Map();
+/** Whether files may change while they are kept: a dev server's, or any reader told of an edit. */
+let mayChange = false;
+/** From now on a kept parse is checked against its file before it is reused. */
+export const checkFileChanges = () => {
+    mayChange = true;
+};
+/** Whether files may change while the programs read them: a dev server's, or any reader told of an edit. */
+export const mayFilesChange = () => mayChange;
+/**
+ * A file's stamp: its change time, in nanoseconds, and its size; none for a file that is not there.
+ *
+ * @param fileName - the file.
+ */
+const stampOf = (fileName) => {
+    const stats = statSync(fileName, { bigint: true, throwIfNoEntry: false });
+    return stats === undefined ? undefined : `${stats.ctimeNs}:${stats.size}`;
+};
+/**
+ * Whether a file's documentation is left out of its parse: the standard library's, or an `@types` package's.
+ *
+ * @param fileName - the file, as TypeScript names it (forward slashes).
+ * @param libraryFolder - the standard library's folder, the same way.
+ */
+const isUndocumented = (fileName, libraryFolder) => dirname(fileName) === libraryFolder || fileName.includes("/node_modules/@types/");
+/**
+ * The function a compiler host parses files with, keeping what it parsed for the next program that parses alike.
+ *
+ * @param options - the program's compiler options.
+ * @param parse - the host's own parse.
+ */
+export const keptParse = (options, parse) => {
+    const libraryFolder = dirname(ts.getDefaultLibFilePath(options)).replaceAll("\\", "/");
+    const shared = DOCUMENT_REGISTRY.getKeyForCompilationSettings(options);
+    const kept = parsedFiles.get(shared) ?? new Map();
+    parsedFiles.set(shared, kept);
+    return (fileName, languageVersion, onError, shouldCreate) => {
+        const stamp = mayChange ? stampOf(fileName) : undefined;
+        const version = typeof languageVersion === "object" ? languageVersion : { languageVersion };
+        const entry = `${fileName}|${version.languageVersion}|${version.impliedNodeFormat ?? ""}`;
+        const known = kept.get(entry);
+        if (known !== undefined && known.stamp === stamp && shouldCreate !== true)
+            return known.file;
+        const file = parse(fileName, isUndocumented(fileName, libraryFolder)
+            ? { ...version, jsDocParsingMode: ts.JSDocParsingMode.ParseNone }
+            : version, onError, shouldCreate);
+        kept.set(entry, { stamp, file });
+        return file;
+    };
+};
+/**
+ * Lets go every kept parse no program still holds: the limit on programs then bounds the parsed files too.
+ *
+ * @param programs - the programs kept.
+ */
+export const keepParsesOf = (programs) => {
+    const held = new Set();
+    for (const program of programs)
+        for (const file of program.getSourceFiles())
+            held.add(file);
+    for (const [shared, kept] of parsedFiles) {
+        for (const [entry, parsed] of kept)
+            if (parsed.file === undefined || !held.has(parsed.file))
+                kept.delete(entry);
+        if (kept.size === 0)
+            parsedFiles.delete(shared);
+    }
+};

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

@@ -0,0 +1,20 @@
+/**
+ * The languages outside the TypeScript family that a component's documentation writes, split into coloured pieces: CSS,
+ * SCSS, JSON, shell and HTML.
+ *
+ * @remarks
+ * Each is a short list of patterns tried in order at every position, since a page shows short examples and colouring
+ * them needs no parser: a general highlighter would add 9 MB to every install for five small grammars. The patterns
+ * take negated classes and no nested repetition, so a long text cannot slow them down.
+ *
+ * @module
+ */
+import type { CodePiece } from "./typeScriptPieces.ts";
+/**
+ * A piece of documentation's code as coloured pieces.
+ *
+ * @param code - the code.
+ * @param language - its language, as a Markdown fence names it.
+ * @returns the pieces, or none for a language with no grammar here.
+ */
+export declare const grammarPieces: (code: string, language: string) => readonly CodePiece[] | undefined;

package/dist/src/vite/plainGrammars.js

@@ -0,0 +1,113 @@
+/** A quoted string, either quote, on one line. */
+const QUOTED = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'/y;
+/** A number, with a CSS unit when it has one. */
+const NUMBER = /-?\b\d+(?:\.\d+)?(?:[a-zA-Z]+|%)?/y;
+/** The rules of CSS, which SCSS extends. */
+const CSS_RULES = [
+    [/\/\*[\s\S]*?\*\//y, "comment"],
+    [QUOTED, "string"],
+    [/@[\w-]+/y, "keyword"],
+    [/#[0-9a-fA-F]{3,8}\b/y, "number"],
+    [/[.#][a-zA-Z_][\w-]*/y, "type"],
+    [/--[\w-]+/y, "property"],
+    [/[a-zA-Z-]+(?=[ \t]*:[ \t])/y, "property"],
+    [NUMBER, "number"]
+];
+/** The rules of SCSS: line comments and variables on top of CSS. */
+const SCSS_RULES = [
+    [/\/\/[^\n]*/y, "comment"],
+    [/\$[\w-]+/y, "property"],
+    ...CSS_RULES
+];
+/** The rules of JSON: a string before a colon is a key. */
+const JSON_RULES = [
+    [/"(?:[^"\\\n]|\\.)*"(?=[ \t]*:)/y, "property"],
+    [QUOTED, "string"],
+    [/\b(?:true|false|null)\b/y, "keyword"],
+    [NUMBER, "number"]
+];
+/** The rules of a shell. */
+const SHELL_RULES = [
+    [/(?<![^\s])#[^\n]*/y, "comment"],
+    [QUOTED, "string"],
+    [/\$\{[^}\n]*\}|\$\w+/y, "property"],
+    [/\b(?:if|then|else|elif|fi|for|in|do|done|while|case|esac|function|export|return|cd|echo)\b/y, "keyword"]
+];
+/** The rules inside an HTML tag, whose name comes first. */
+const TAG_RULES = [
+    [/(?<=<\/?)[\w:.-]+/y, "tag"],
+    [QUOTED, "string"],
+    [/[\w:.-]+(?==)/y, "attribute"]
+];
+/** The grammars, by the names a Markdown fence gives them. */
+const GRAMMARS = {
+    css: CSS_RULES,
+    scss: SCSS_RULES,
+    json: JSON_RULES,
+    bash: SHELL_RULES,
+    sh: SHELL_RULES,
+    shell: SHELL_RULES,
+    zsh: SHELL_RULES
+};
+/** The names of HTML. */
+const HTML_NAMES = new Set(["html", "xml", "svg"]);
+/** The rule that matches at a position, with its length. */
+const matchAt = (code, index, rules) => {
+    for (const [pattern, role] of rules) {
+        pattern.lastIndex = index;
+        const found = pattern.exec(code);
+        if (found !== null && found[0] !== "")
+            return { role, length: found[0].length };
+    }
+    return undefined;
+};
+/** Pieces with the plain text between them joined, so an example makes few spans. */
+const piecesOf = (code, rules) => {
+    const pieces = [];
+    let plainFrom = 0;
+    let index = 0;
+    while (index < code.length) {
+        const match = matchAt(code, index, rules);
+        if (match === undefined) {
+            index += 1;
+        }
+        else {
+            if (plainFrom < index)
+                pieces.push({ text: code.slice(plainFrom, index) });
+            pieces.push({ text: code.slice(index, index + match.length), role: match.role });
+            index += match.length;
+            plainFrom = index;
+        }
+    }
+    if (plainFrom < code.length)
+        pieces.push({ text: code.slice(plainFrom) });
+    return pieces;
+};
+/** HTML: comments and tags are coloured, and the text between them is left as it is. */
+const htmlPieces = (code) => {
+    const pieces = [];
+    let index = 0;
+    for (const part of code.matchAll(/<!--[\s\S]*?-->|<[^>]*>/g)) {
+        if (part.index > index)
+            pieces.push({ text: code.slice(index, part.index) });
+        const isComment = part[0].startsWith("<!--");
+        pieces.push(...(isComment ? [{ text: part[0], role: "comment" }] : piecesOf(part[0], TAG_RULES)));
+        index = part.index + part[0].length;
+    }
+    if (index < code.length)
+        pieces.push({ text: code.slice(index) });
+    return pieces;
+};
+/**
+ * A piece of documentation's code as coloured pieces.
+ *
+ * @param code - the code.
+ * @param language - its language, as a Markdown fence names it.
+ * @returns the pieces, or none for a language with no grammar here.
+ */
+export const grammarPieces = (code, language) => {
+    if (HTML_NAMES.has(language))
+        return htmlPieces(code);
+    const rules = Object.hasOwn(GRAMMARS, language) ? GRAMMARS[language] : undefined;
+    return rules === undefined ? undefined : piecesOf(code, rules);
+};

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

@@ -0,0 +1,47 @@
+import type { ForgebookPlugin } from "../plugin.ts";
+import { type ViewSwitch } from "../switches.ts";
+import type { PluginsDocument } from "./agent.types.ts";
+/** The versions of the contract this Forgebook speaks. */
+export declare const SUPPORTED_PLUGIN_API_VERSIONS: readonly number[];
+/**
+ * The module a plugin runs in a catalogue's frames, or none.
+ *
+ * @param plugin - the plugin.
+ * @param framework - the catalogue's framework.
+ */
+export declare const pluginFrameModule: (plugin: ForgebookPlugin, framework: string) => string | undefined;
+/**
+ * Why a list of plugins cannot be used, or none.
+ *
+ * @param plugins - the configuration's plugins.
+ * @param framework - the catalogue's framework.
+ * @param dir - the configuration's folder.
+ */
+export declare const pluginsProblem: (plugins: readonly ForgebookPlugin[], framework: string, dir: string) => string | undefined;
+/**
+ * The catalogue's switches with the plugins' after them: a plugin adds to the catalogue's and never takes the place of
+ * the theme and the contrast it would have by default. The catalogue's own switch of the same id wins.
+ *
+ * @param switches - the catalogue's, merged with its presets'; none when neither declares any.
+ * @param plugins - the plugins.
+ */
+export declare const withPluginSwitches: (switches: readonly ViewSwitch[] | undefined, plugins: readonly ForgebookPlugin[]) => readonly ViewSwitch[] | undefined;
+/**
+ * Every module of the plugins that pages import, for pre-bundling an installed plugin.
+ *
+ * @param plugins - the plugins.
+ * @param framework - the catalogue's framework.
+ */
+export declare const pluginModules: (plugins: readonly ForgebookPlugin[], framework: string) => string[];
+/**
+ * The fences the plugins add, for the docs pages' compiler.
+ *
+ * @param plugins - the plugins.
+ */
+export declare const pluginFences: (plugins: readonly ForgebookPlugin[]) => readonly string[];
+/**
+ * The plugins as tools and agents read them.
+ *
+ * @param plugins - the plugins.
+ */
+export declare const pluginsDocument: (plugins: readonly ForgebookPlugin[]) => PluginsDocument;

package/dist/src/vite/pluginConfig.js

@@ -0,0 +1,220 @@
+/**
+ * The plugins a configuration lists, checked on Node before anything is generated from them, and what they add to it.
+ *
+ * @remarks
+ * A configuration is code nobody type-checked against this version, and what it names ends up in generated imports and
+ * in the address, so every plugin is read as `unknown`-shaped data here: one whose contract this Forgebook does not
+ * speak, or that collides with another or with Forgebook itself, stops the catalogue with a message that names it,
+ * rather than breaking a page later.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { PANEL_TAB_IDS } from "../catalogue.js";
+import { DEFAULT_SWITCHES } from "../switches.js";
+/** The versions of the contract this Forgebook speaks. */
+export const SUPPORTED_PLUGIN_API_VERSIONS = [1];
+/**
+ * The fences a plugin may not take: a page's own, and the languages people write code in, which would stop being code on
+ * every page of the catalogue.
+ */
+const OWN_FENCES = [
+    ...[
+        "story",
+        "props",
+        "bash",
+        "c",
+        "cpp",
+        "css",
+        "diff",
+        "go",
+        "html",
+        "java",
+        "js",
+        "json",
+        "jsx",
+        "kotlin"
+    ],
+    ...["markdown", "md", "mdx", "php", "python", "py", "ruby", "rust", "scss", "sh", "shell", "sql", "swift"],
+    ...["text", "toml", "ts", "tsx", "txt", "xml", "yaml", "yml"]
+];
+/** A plugin's id: lower-case words and hyphens. */
+const NAME = /^[a-z][a-z0-9-]*$/;
+/**
+ * The first of some names that is there twice, or not one of the plugin's.
+ *
+ * @param plugin - the plugin's id.
+ * @param names - the names.
+ * @param seen - the names of every plugin so far.
+ * @param what - what a name names, for the message.
+ */
+const namesProblem = (plugin, names, seen, what) => {
+    for (const name of names) {
+        if (name !== plugin && !(name.startsWith(`${plugin}-`) && NAME.test(name)))
+            return `${what} "${name}" must be "${plugin}", or start with "${plugin}-"`;
+        if (seen.has(name))
+            return `${what} "${name}" is given twice`;
+        seen.add(name);
+    }
+    return undefined;
+};
+/**
+ * The module a plugin runs in a catalogue's frames, or none.
+ *
+ * @param plugin - the plugin.
+ * @param framework - the catalogue's framework.
+ */
+export const pluginFrameModule = (plugin, framework) => typeof plugin.frame === "object" ? plugin.frame[framework] : plugin.frame;
+/** A package's name, from a specifier of it (`@acme/ui/browser` → `@acme/ui`). */
+const packageOf = (specifier) => specifier
+    .split("/")
+    .slice(0, specifier.startsWith("@") ? 2 : 1)
+    .join("/");
+/**
+ * Whether a project installs a package, by its folder: a browser-only package may hide even its manifest from Node.
+ *
+ * @param dir - the configuration's folder.
+ * @param name - the package.
+ */
+const isPackageInstalled = (dir, name) => (createRequire(resolve(dir, "package.json")).resolve.paths(name) ?? []).some((folder) => existsSync(join(folder, name)));
+/**
+ * Why a plugin's fields do not have their shape, or none: a configuration is not type-checked, and a field read as
+ * what it is not would otherwise stop the catalogue with a bare `TypeError`.
+ *
+ * @param plugin - the plugin.
+ */
+const shapeProblem = (plugin) => {
+    const lists = [
+        plugin.tabs,
+        plugin.switches,
+        plugin.docBlocks,
+        plugin.browserDependencies
+    ];
+    if (lists.some((list) => list !== undefined && !Array.isArray(list)))
+        return `the plugin "${plugin.id}" gives a list that is no list`;
+    const named = [
+        ...(plugin.tabs ?? []).map((tab) => tab?.id),
+        ...(plugin.switches ?? []).map((each) => each?.id),
+        ...(plugin.docBlocks ?? []).map((block) => block?.fence)
+    ];
+    if (named.some((name) => typeof name !== "string"))
+        return `the plugin "${plugin.id}" adds something with no id`;
+    const { frame } = plugin;
+    const isFrame = frame === undefined || typeof frame === "string" || (typeof frame === "object" && frame !== null);
+    return isFrame ? undefined : `the plugin "${plugin.id}" names a frame that is no specifier`;
+};
+/**
+ * Why one plugin cannot be used, or none.
+ *
+ * @param plugin - the plugin.
+ * @param framework - the catalogue's framework.
+ * @param dir - the configuration's folder.
+ */
+const pluginProblem = (plugin, framework, dir) => {
+    if (!SUPPORTED_PLUGIN_API_VERSIONS.includes(plugin.apiVersion)) {
+        return (`the plugin "${plugin.id}" is written for version ${String(plugin.apiVersion)} of the plugin API, and this ` +
+            `Forgebook speaks version ${SUPPORTED_PLUGIN_API_VERSIONS.join(", ")}: update one of them`);
+    }
+    if (typeof plugin.frame === "object" && plugin.frame[framework] === undefined) {
+        const frameworks = Object.keys(plugin.frame).join(", ");
+        return `the plugin "${plugin.id}" runs in frames of ${frameworks}, and this catalogue is ${framework}`;
+    }
+    const modules = [
+        ...(plugin.tabs ?? []).map((tab) => tab.view),
+        ...(plugin.docBlocks ?? []).map((block) => block.view),
+        ...(plugin.frame === undefined ? [] : [pluginFrameModule(plugin, framework)])
+    ];
+    if (modules.some((module) => typeof module !== "string" || module === ""))
+        return `the plugin "${plugin.id}" names a module that is no specifier`;
+    const missing = (plugin.browserDependencies ?? [])
+        .map(packageOf)
+        .find((name) => !isPackageInstalled(dir, name));
+    return missing === undefined
+        ? undefined
+        : `the plugin "${plugin.id}" needs the package ${missing}, which this project does not install`;
+};
+/**
+ * Why a list of plugins cannot be used, or none.
+ *
+ * @param plugins - the configuration's plugins.
+ * @param framework - the catalogue's framework.
+ * @param dir - the configuration's folder.
+ */
+export const pluginsProblem = (plugins, framework, dir) => {
+    const ids = new Set();
+    const tabs = new Set(PANEL_TAB_IDS);
+    const switches = new Set();
+    const fences = new Set(OWN_FENCES);
+    for (const plugin of plugins) {
+        const { id } = plugin;
+        if (typeof id !== "string" || !NAME.test(id))
+            return `the plugin "${String(id)}" must be lower-case words and hyphens`;
+        if (ids.has(id))
+            return `the plugin "${id}" is given twice`;
+        ids.add(id);
+        const problem = shapeProblem(plugin) ??
+            pluginProblem(plugin, framework, dir) ??
+            namesProblem(id, (plugin.tabs ?? []).map((tab) => tab.id), tabs, "the tab") ??
+            namesProblem(id, (plugin.switches ?? []).map((each) => each.id), switches, "the switch") ??
+            namesProblem(id, (plugin.docBlocks ?? []).map((block) => block.fence), fences, "the docs block");
+        if (problem !== undefined)
+            return problem;
+    }
+    return undefined;
+};
+/**
+ * The catalogue's switches with the plugins' after them: a plugin adds to the catalogue's and never takes the place of
+ * the theme and the contrast it would have by default. The catalogue's own switch of the same id wins.
+ *
+ * @param switches - the catalogue's, merged with its presets'; none when neither declares any.
+ * @param plugins - the plugins.
+ */
+export const withPluginSwitches = (switches, plugins) => {
+    const added = plugins.flatMap((plugin) => plugin.switches ?? []);
+    if (added.length === 0)
+        return switches;
+    const own = switches ?? DEFAULT_SWITCHES;
+    return [...own, ...added.filter((each) => !own.some((other) => other.id === each.id))];
+};
+/**
+ * Every module of the plugins that pages import, for pre-bundling an installed plugin.
+ *
+ * @param plugins - the plugins.
+ * @param framework - the catalogue's framework.
+ */
+export const pluginModules = (plugins, framework) => plugins.flatMap((plugin) => {
+    const frame = pluginFrameModule(plugin, framework);
+    return [
+        ...(plugin.tabs ?? []).map((tab) => tab.view),
+        ...(plugin.docBlocks ?? []).map((block) => block.view),
+        ...(frame === undefined ? [] : [frame])
+    ];
+});
+/**
+ * The fences the plugins add, for the docs pages' compiler.
+ *
+ * @param plugins - the plugins.
+ */
+export const pluginFences = (plugins) => plugins.flatMap((plugin) => (plugin.docBlocks ?? []).map((block) => block.fence));
+/**
+ * The plugins as tools and agents read them.
+ *
+ * @param plugins - the plugins.
+ */
+export const pluginsDocument = (plugins) => ({
+    schema: 1,
+    apiVersions: SUPPORTED_PLUGIN_API_VERSIONS,
+    plugins: plugins.map((plugin) => ({
+        id: plugin.id,
+        tabs: (plugin.tabs ?? []).map((tab) => ({
+            id: tab.id,
+            label: tab.label,
+            ...(tab.when === undefined ? {} : { when: tab.when })
+        })),
+        switches: (plugin.switches ?? []).map((each) => each.id),
+        docBlocks: (plugin.docBlocks ?? []).map((block) => block.fence),
+        runsInFrames: plugin.frame !== undefined
+    }))
+});

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

@@ -0,0 +1,27 @@
+/** The id of a group of docs pages: virtual, with the declaring module's folder and the patterns after it. */
+export declare const DOCS_PAGES_PREFIX = "\0virtual:forgebook-docs-pages:";
+/**
+ * The id of a pattern's module, when an import asks for one: its story files, or its docs pages.
+ *
+ * @param source - the import's specifier.
+ * @param folder - the importing module's folder.
+ */
+export declare const patternId: (source: string, folder: string) => string | null;
+/**
+ * The id of a virtual module the plugin makes (the configuration's data, the tokens, a group's "Used in", reach,
+ * search indexes or texts), when the import names one.
+ *
+ * @param source - the import's specifier.
+ */
+export declare const virtualId: (source: string) => string | undefined;
+/**
+ * Whether an id names a group's module: one whose patterns are written in the id itself, so that whoever writes the id
+ * chooses what the plugin reads.
+ *
+ * @param id - the module's id.
+ */
+export declare const isGroupId: (id: 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. */
+export declare const TOKENS_ID = "\0virtual:forgebook/tokens";

package/dist/src/vite/pluginIds.js

@@ -0,0 +1,76 @@
+/**
+ * The ids of the modules the plugin makes: a pattern's story files or docs pages, the configuration's data, the design
+ * tokens, a group's "Used in", reach and texts. Pure: a specifier in, an id out.
+ *
+ * @module
+ */
+import { CONFIG_MODULE, TOKENS_MODULE } from "./pages.js";
+import { FILES_PREFIX } from "./pluginModules.js";
+import { DOCS_PAGES_SPECIFIER_PREFIX, FILES_SPECIFIER_PREFIX, GROUP_SEPARATOR, PAGES_SEARCH_PREFIX, REACH_PREFIX, SEARCH_PREFIX, storyFilesGroupText, TEXTS_PREFIX, USAGE_PREFIX } from "./storyFilesModule.js";
+/** The query that asks for the story files a pattern matches (`../src/**\/*.stories.tsx?forgebook-files`). */
+const FILES_QUERY = "?forgebook-files";
+/** The query that asks for the docs pages a pattern matches (`./docs/*.md?forgebook-docs-pages`). */
+const DOCS_PAGES_QUERY = "?forgebook-docs-pages";
+/** The id of a group of docs pages: virtual, with the declaring module's folder and the patterns after it. */
+export const DOCS_PAGES_PREFIX = `\0${DOCS_PAGES_SPECIFIER_PREFIX}`;
+/**
+ * The id of a `?forgebook-files` module: its prefix, then its group (`storyFilesGroupText`), which holds no `..`.
+ *
+ * @param folder - the importing module's folder.
+ * @param pattern - the pattern as the import writes it.
+ */
+const filesId = (folder, pattern) => `${FILES_PREFIX}${storyFilesGroupText(folder, [pattern])}`;
+/**
+ * The id of a pattern's module, when an import asks for one: its story files, or its docs pages.
+ *
+ * @param source - the import's specifier.
+ * @param folder - the importing module's folder.
+ */
+export const patternId = (source, folder) => {
+    // the separator of a group's id: a folder that holds it would read back as patterns of its own
+    if (folder.includes(GROUP_SEPARATOR))
+        return null;
+    if (source.endsWith(FILES_QUERY))
+        return filesId(folder, source.slice(0, -FILES_QUERY.length));
+    if (!source.endsWith(DOCS_PAGES_QUERY))
+        return null;
+    const pattern = source.slice(0, -DOCS_PAGES_QUERY.length);
+    return `${DOCS_PAGES_PREFIX}${storyFilesGroupText(folder, [pattern])}`;
+};
+/**
+ * The specifiers' prefixes of a group's virtual modules: the group named by its patterns (story files or docs pages),
+ * its "Used in", its reach, its search indexes, its texts.
+ */
+const VIRTUAL_PREFIXES = [
+    FILES_SPECIFIER_PREFIX,
+    DOCS_PAGES_SPECIFIER_PREFIX,
+    USAGE_PREFIX,
+    REACH_PREFIX,
+    SEARCH_PREFIX,
+    PAGES_SEARCH_PREFIX,
+    TEXTS_PREFIX
+];
+/**
+ * The id of a virtual module the plugin makes (the configuration's data, the tokens, a group's "Used in", reach,
+ * search indexes or texts), when the import names one.
+ *
+ * @param source - the import's specifier.
+ */
+export const virtualId = (source) => {
+    if (source === CONFIG_MODULE)
+        return CONFIG_ID;
+    if (source === TOKENS_MODULE)
+        return TOKENS_ID;
+    return VIRTUAL_PREFIXES.some((prefix) => source.startsWith(prefix)) ? `\0${source}` : undefined;
+};
+/**
+ * Whether an id names a group's module: one whose patterns are written in the id itself, so that whoever writes the id
+ * chooses what the plugin reads.
+ *
+ * @param id - the module's id.
+ */
+export const isGroupId = (id) => VIRTUAL_PREFIXES.some((prefix) => id.startsWith(`\0${prefix}`));
+/** The resolved id of the configuration's data module. */
+export const CONFIG_ID = `\0${CONFIG_MODULE}`;
+/** The resolved id of the design tokens' module. */
+export const TOKENS_ID = `\0${TOKENS_MODULE}`;