forgebook 0.3.3 → 0.4.1

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

@@ -0,0 +1,40 @@
+/**
+ * A prop's kind (the panel's group and control) and the type it is read from: a choice, a text, a number, a toggle, an
+ * event or anything else, across the variants of a union of props that declare it and through a generic's type
+ * parameters. Used by `propDocs.ts`.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import type { PropKind } from "../componentDocs.ts";
+import type { PropReading } from "./propDocs.ts";
+import { type Generics } from "./typeParameters.ts";
+/** Whether a type is a union of string or number literals (a choice). */
+export declare const literalValues: (type: ts.Type) => (string | number)[] | undefined;
+/** A prop's kind, from its name and its type without `undefined`. */
+export declare const kindOf: (name: string, type: ts.Type, eventName: RegExp) => PropKind;
+/** A prop's type and kind, read across the variants of a union of props that declare it. */
+export type TypeAndKind = {
+    /** Its type, without `undefined`: what a type parameter is shown as, for a prop typed by one. */
+    readonly type: ts.Type;
+    /** Its type in each other variant that declares it. */
+    readonly variantTypes: readonly ts.Type[];
+    /** Whether those variants type it otherwise. */
+    readonly isMixed: boolean;
+    /** Its kind, shared by every variant's type. */
+    readonly kind: PropKind;
+    /**
+     * The checker and the bindings when its type, as the component takes it, still holds a type parameter
+     * (`readonly TItem[]`): its text then replaces them. None otherwise.
+     */
+    readonly generic: Generics | undefined;
+};
+/**
+ * A prop's type and kind.
+ *
+ * @param symbol - the prop.
+ * @param reading - how the framework's props differ, and the other variants'.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ */
+export declare const typeAndKind: (symbol: ts.Symbol, { taken, eventName, variants, bindings }: PropReading, checker: ts.TypeChecker, node: ts.Node) => TypeAndKind;

package/dist/src/vite/propKind.js

@@ -0,0 +1,71 @@
+/**
+ * A prop's kind (the panel's group and control) and the type it is read from: a choice, a text, a number, a toggle, an
+ * event or anything else, across the variants of a union of props that declare it and through a generic's type
+ * parameters. Used by `propDocs.ts`.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { genericShownType, hasTypeParameter } from "./typeParameters.js";
+/** No bindings: each type parameter is shown by its own constraint. */
+const NO_BINDINGS = new Map();
+/** An event: a function prop named `on` and a capital (React's `onPress`). */
+const EVENT_NAME = /^on[A-Z]/;
+/** Whether a type is a union of string or number literals (a choice). */
+export const literalValues = (type) => {
+    if (!type.isUnion())
+        return undefined;
+    const values = type.types.map((member) => member.isStringLiteral() || member.isNumberLiteral() ? member.value : undefined);
+    return values.every((value) => value !== undefined)
+        ? values.filter((value) => value !== undefined)
+        : undefined;
+};
+/** A prop's kind, from its name and its type without `undefined`. */
+export const kindOf = (name, type, eventName) => {
+    if (eventName.test(name) && type.getCallSignatures().length > 0)
+        return "event";
+    if (type.flags & ts.TypeFlags.Boolean || type.flags & ts.TypeFlags.BooleanLiteral)
+        return "toggle";
+    if (literalValues(type) !== undefined)
+        return "choice";
+    if (type.flags & ts.TypeFlags.String)
+        return "text";
+    if (type.flags & ts.TypeFlags.Number)
+        return "number";
+    return "other";
+};
+/**
+ * A prop's kind across the variants that declare it: theirs when all share one, `other` otherwise.
+ *
+ * @param name - the prop's name.
+ * @param types - its type in each variant, without `undefined`.
+ * @param eventName - what an event's name is.
+ */
+const sharedKind = (name, types, eventName) => {
+    const kinds = new Set(types.map((type) => kindOf(name, type, eventName)));
+    const [only] = kinds;
+    return kinds.size === 1 && only !== undefined ? only : "other";
+};
+/**
+ * A prop's type and kind.
+ *
+ * @param symbol - the prop.
+ * @param reading - how the framework's props differ, and the other variants'.
+ * @param checker - the program's checker.
+ * @param node - where the code names the component.
+ */
+export const typeAndKind = (symbol, { taken, eventName = EVENT_NAME, variants = [], bindings }, checker, node) => {
+    const ownType = taken?.type ?? checker.getTypeOfSymbolAtLocation(symbol, node);
+    const isGeneric = hasTypeParameter(ownType, checker);
+    // a prop typed by a type parameter takes what that parameter is shown as: its kind and control follow from it
+    const shown = (each) => checker.getNonNullableType(genericShownType(each, checker) ?? each);
+    const type = shown(ownType);
+    const variantTypes = variants.map((variant) => shown(checker.getTypeOfSymbolAtLocation(variant, node)));
+    // two variants that write the same type have two of it: alike is what each accepts of the other
+    const isMixed = variantTypes.some((variantType) => !checker.isTypeAssignableTo(variantType, type) || !checker.isTypeAssignableTo(type, variantType));
+    const name = symbol.getName();
+    const kind = isMixed ? sharedKind(name, [type, ...variantTypes], eventName) : kindOf(name, type, eventName);
+    // a type parameter is replaced only where the component leaves it open: a props type it instantiates is read as is
+    const generic = isGeneric ? { checker, bindings: bindings ?? NO_BINDINGS } : undefined;
+    return { type, variantTypes, isMixed, kind, generic };
+};

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

@@ -0,0 +1,22 @@
+/**
+ * What a prop's type cannot say plainly: a generic's type parameter and what it is shown as (`typeParameters.ts`), a
+ * name the checker cannot find, an `any`. `propDocs` lists a note for each, so a reader sees why a type is not the one
+ * the source wrote, or why it says nothing.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import type { PropTypeNote } from "../componentDocs.ts";
+import { type DeclaredType, type Generics } from "./typeParameters.ts";
+/**
+ * Why a prop's type is not the one its source writes, or says nothing: each generic type parameter and what it is
+ * shown as, each name the checker cannot find, and an `any` with neither.
+ *
+ * @param declared - the prop's declared types.
+ * @param type - the prop's type as the checker has it, without `undefined`.
+ * @param checker - the program's checker.
+ * @param generics - the checker and the bindings when the component leaves a type parameter of the prop's type open;
+ * none otherwise.
+ * @returns the notes, in source order, each once; empty when the type is read as written.
+ */
+export declare const propTypeNotes: (declared: readonly DeclaredType[], type: ts.Type, checker: ts.TypeChecker, generics: Generics | undefined) => PropTypeNote[];

package/dist/src/vite/propTypeNotes.js

@@ -0,0 +1,51 @@
+/**
+ * What a prop's type cannot say plainly: a generic's type parameter and what it is shown as (`typeParameters.ts`), a
+ * name the checker cannot find, an `any`. `propDocs` lists a note for each, so a reader sees why a type is not the one
+ * the source wrote, or why it says nothing.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import { genericNotes, referencesIn } from "./typeParameters.js";
+/**
+ * Whether a type reference names something the checker cannot find: no symbol, or an import of nothing.
+ *
+ * @param reference - the reference.
+ * @param checker - the program's checker.
+ */
+const isUnresolved = (reference, checker) => {
+    const symbol = checker.getSymbolAtLocation(reference.typeName);
+    if (symbol === undefined)
+        return true;
+    const target = symbol.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+    return (target.declarations ?? []).length === 0;
+};
+/**
+ * Why a prop's type is not the one its source writes, or says nothing: each generic type parameter and what it is
+ * shown as, each name the checker cannot find, and an `any` with neither.
+ *
+ * @param declared - the prop's declared types.
+ * @param type - the prop's type as the checker has it, without `undefined`.
+ * @param checker - the program's checker.
+ * @param generics - the checker and the bindings when the component leaves a type parameter of the prop's type open;
+ * none otherwise.
+ * @returns the notes, in source order, each once; empty when the type is read as written.
+ */
+export const propTypeNotes = (declared, type, checker, generics) => {
+    const notes = new Map();
+    for (const note of generics === undefined ? [] : genericNotes(declared, generics)) {
+        if (note.reason === "generic")
+            notes.set(`generic:${note.parameter}`, note);
+    }
+    for (const node of declared) {
+        for (const reference of referencesIn(node)) {
+            if (!isUnresolved(reference, checker))
+                continue;
+            const name = reference.typeName.getText();
+            notes.set(`unresolved:${name}`, { reason: "unresolved", name });
+        }
+    }
+    if (notes.size === 0 && type.flags & ts.TypeFlags.Any)
+        notes.set("any", { reason: "any" });
+    return [...notes.values()];
+};

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

@@ -0,0 +1,27 @@
+/** A published file, with the components it declares. */
+export type PublishedFile = {
+    /** The file, absolute. */
+    readonly file: string;
+    /** The names it publishes them under, in the order they are first met. */
+    readonly names: readonly string[];
+    /** Whether one of them plainly takes props: a parameter, a type argument. */
+    readonly takesProps: boolean;
+    /** Whether one of them has a doc comment on its declaration, or the file a `@module` one. */
+    readonly hasComment: boolean;
+};
+/** What `publishedComponents` asks of the disk. */
+export type ExportsDisk = {
+    /** A file's text; none when it does not exist. */
+    readonly readText: (file: string) => string | undefined;
+    /** The file a relative import names, from the file importing it; none when none is found or it is out of reach. */
+    readonly resolve: (specifier: string, from: string) => string | undefined;
+    /** Told of an import written through a project's alias, which this cannot follow. */
+    readonly onAlias?: (specifier: string, from: string) => void;
+};
+/**
+ * The components some entries publish, one element per declaring file.
+ *
+ * @param entries - the entries' source files, absolute.
+ * @param disk - what is asked of the disk.
+ */
+export declare const publishedComponents: (entries: readonly string[], disk: ExportsDisk) => PublishedFile[];

package/dist/src/vite/publishedExports.js

@@ -0,0 +1,298 @@
+/**
+ * The components a package's entries export, by the file that declares each: what "published" means to `verify`.
+ *
+ * @remarks
+ * Read from each file's syntax, with no program: a whole package must take moments on a change that touches one file, and
+ * an export's shape says enough. Only relative paths are followed, since a package's own files are what it publishes and
+ * another package of the repository has its own entries. A file counts as one finding however many parts it declares
+ * (`Dialog`, `DialogTrigger`): one story page shows them together, and a finding per part would bury the one that matters.
+ * Only what reads as a component counts. A context, a value, a constant in capitals and a hook are published too, and no
+ * story is owed for them.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/** A file that is a component by its extension alone: its default export is what it draws. */
+const COMPONENT_FILE = /\.(?:vue|svelte|astro)$/;
+/** A file whose capitalised functions draw something. */
+const DRAWN_FILE = /\.[cm]?[jt]sx$/;
+/** A script's text that defines a component with no JSX in it. */
+const DEFINES_COMPONENT = /\bcustomElements\.define\(|@customElement\(|\bextends\s+(?:LitElement|HTMLElement)\b|@Component\(|\bdefineComponent\(|\bforwardRef\(|\bcreateElement\(|\bstyled[.(]|<\/[A-Za-z][\w.-]{0,80}>|<[A-Z][\w.]{0,80}[^<>\n]{0,500}\/>/;
+/** A name a component can have: capitalised and not a constant. */
+const COMPONENT_NAME = /^[A-Z](?:[a-z0-9]|[A-Z]+[a-z0-9])\w*$|^[A-Z]$/;
+/** A call whose result is no component. */
+const NOT_A_COMPONENT_CALL = /^(?:React\.)?(?:createContext|cva|tv|defineConfig|Symbol|Object\.freeze)$/;
+/** An import through a project's alias rather than a package's name. */
+const ALIASED = /^(?:[@~#]\/|#)/;
+/** Whether a call's name says its result is no component. */
+const isPlainCall = (call) => NOT_A_COMPONENT_CALL.test(call.expression.getText());
+/** How the expression a name is given reads. */
+const shapeOfExpression = (node) => {
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
+        return { takesProps: node.parameters.length > 0 };
+    if (ts.isClassExpression(node))
+        return { takesProps: true };
+    if (ts.isCallExpression(node)) {
+        if (isPlainCall(node))
+            return undefined;
+        const inner = node.arguments.find((each) => ts.isArrowFunction(each) || ts.isFunctionExpression(each));
+        const typed = (node.typeArguments?.length ?? 0) > 0;
+        return { takesProps: typed || (inner !== undefined && (shapeOfExpression(inner)?.takesProps ?? false)) };
+    }
+    if (ts.isTaggedTemplateExpression(node))
+        return { takesProps: false };
+    // `export const Tooltip = Primitive.Root`, a library's part under a name of its own
+    if (ts.isPropertyAccessExpression(node) && /^[A-Z]/.test(node.name.text))
+        return { takesProps: false };
+    if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node))
+        return shapeOfExpression(node.expression);
+    return undefined;
+};
+/** How a variable's declaration reads: its value, or the type it is written with. */
+const shapeOfVariable = (declaration) => {
+    const shape = declaration.initializer === undefined ? undefined : shapeOfExpression(declaration.initializer);
+    if (shape !== undefined || declaration.type === undefined)
+        return shape;
+    return ts.isTypeReferenceNode(declaration.type) && /(?:FC|ComponentType)\b/.test(declaration.type.getText())
+        ? { takesProps: (declaration.type.typeArguments?.length ?? 0) > 0 }
+        : undefined;
+};
+/** Whether a statement carries a modifier. */
+const hasModifier = (node, kind) => ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) ?? false;
+/** The named variables a statement declares. */
+const variablesOf = (statement) => statement.declarationList.declarations.filter((declaration) => ts.isIdentifier(declaration.name));
+/** A variable's name, which `variablesOf` has seen to be an identifier. */
+const variableName = (declaration) => declaration.name.getText();
+/** Reads what a statement declares into a file's scope. */
+const addDeclared = (statement, scope) => {
+    const isCommented = ts.getJSDocCommentsAndTags(statement).length > 0;
+    const declare = (name, shape) => {
+        scope.declared.set(name, shape);
+        if (isCommented)
+            scope.commented.add(name);
+    };
+    if (ts.isFunctionDeclaration(statement) && statement.name !== undefined)
+        declare(statement.name.text, { takesProps: statement.parameters.length > 0 });
+    if (ts.isClassDeclaration(statement) && statement.name !== undefined)
+        declare(statement.name.text, { takesProps: true });
+    if (ts.isVariableStatement(statement))
+        for (const declaration of variablesOf(statement))
+            declare(variableName(declaration), shapeOfVariable(declaration));
+};
+/** Reads what a statement imports into a file's scope; a type's import brings no component. */
+const addImported = (statement, scope) => {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+        return;
+    const from = statement.moduleSpecifier.text;
+    const clause = statement.importClause;
+    if (clause === undefined || clause.isTypeOnly)
+        return;
+    if (clause.name !== undefined)
+        scope.imported.set(clause.name.text, { from, name: "default" });
+    if (clause.namedBindings === undefined || !ts.isNamedImports(clause.namedBindings))
+        return;
+    for (const each of clause.namedBindings.elements)
+        if (!each.isTypeOnly)
+            scope.imported.set(each.name.text, { from, name: (each.propertyName ?? each.name).text });
+};
+/** How a default export written in place reads. */
+const defaultThing = (expression, file, isDrawn) => {
+    const shape = shapeOfExpression(expression);
+    return shape === undefined
+        ? undefined
+        : { file, isComponent: isDrawn, takesProps: shape.takesProps, hasComment: false };
+};
+/** How TypeScript is told to read a file. */
+const scriptKindOf = (file) => {
+    if (/\.tsx$/.test(file))
+        return ts.ScriptKind.TSX;
+    if (/\.jsx$/.test(file))
+        return ts.ScriptKind.JSX;
+    if (/\.[cm]?js$/.test(file))
+        return ts.ScriptKind.JSX;
+    return ts.ScriptKind.TS;
+};
+/** Records an export, when it is something this can tell of. */
+const record = (context, name, thing) => {
+    if (thing !== undefined)
+        context.found.set(name, thing);
+};
+/** Adds what `export { … }`, with or without a `from`, exports. */
+const addNamedExports = (clause, specifier, context) => {
+    for (const each of clause.elements) {
+        if (each.isTypeOnly)
+            continue;
+        const name = (each.propertyName ?? each.name).text;
+        const thing = specifier === undefined ? context.local(name) : context.followed(specifier, name);
+        record(context, each.name.text, thing);
+    }
+};
+/** Adds what an `export … from`, or `export { … }`, exports. */
+const addExportDeclaration = (statement, context) => {
+    if (statement.isTypeOnly)
+        return;
+    const { moduleSpecifier, exportClause } = statement;
+    const specifier = moduleSpecifier !== undefined && ts.isStringLiteral(moduleSpecifier) ? moduleSpecifier.text : undefined;
+    if (exportClause !== undefined && ts.isNamedExports(exportClause)) {
+        addNamedExports(exportClause, specifier, context);
+        return;
+    }
+    if (specifier === undefined)
+        return;
+    // `export * as Dialog from`, or `export *`: either way what that file exports is published under its own name
+    for (const [name, thing] of context.allOf(specifier)) {
+        if (name !== "default" && !context.found.has(name))
+            context.found.set(name, thing);
+    }
+};
+/** Adds what `export default <expression>` exports. */
+const addExportAssignment = (statement, context) => {
+    const { expression } = statement;
+    const thing = ts.isIdentifier(expression)
+        ? context.local(expression.text)
+        : defaultThing(expression, context.file, context.isDrawn);
+    record(context, "default", thing);
+};
+/** Adds what `export function` or `export class`, with a name or as the default, exports. */
+const addExportedDeclaration = (statement, context) => {
+    const name = statement.name?.text;
+    const thing = name === undefined
+        ? {
+            file: context.file,
+            isComponent: context.isDrawn,
+            takesProps: ts.isClassDeclaration(statement),
+            hasComment: ts.getJSDocCommentsAndTags(statement).length > 0
+        }
+        : context.local(name);
+    const isDefault = hasModifier(statement, ts.SyntaxKind.DefaultKeyword);
+    record(context, isDefault ? "default" : (name ?? "default"), thing);
+};
+/** Adds what one statement exports. */
+const addExports = (statement, context) => {
+    if (ts.isExportDeclaration(statement)) {
+        addExportDeclaration(statement, context);
+        return;
+    }
+    if (ts.isExportAssignment(statement)) {
+        if (!statement.isExportEquals)
+            addExportAssignment(statement, context);
+        return;
+    }
+    if (!ts.canHaveModifiers(statement) || !hasModifier(statement, ts.SyntaxKind.ExportKeyword))
+        return;
+    if (ts.isVariableStatement(statement)) {
+        for (const declaration of variablesOf(statement)) {
+            const name = variableName(declaration);
+            record(context, name, context.local(name));
+        }
+        return;
+    }
+    if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement))
+        addExportedDeclaration(statement, context);
+};
+/**
+ * Reads files' exports, each file once.
+ *
+ * @param disk - what is asked of the disk.
+ * @returns what reads one file; a file reached again while it is read (a cycle) has none yet, as a cycle adds nothing.
+ */
+const exportReader = (disk) => {
+    const seen = new Map();
+    const targetOf = (specifier, from) => {
+        if (ALIASED.test(specifier))
+            disk.onAlias?.(specifier, from);
+        return specifier.startsWith(".") ? disk.resolve(specifier, from) : undefined;
+    };
+    const exportsOf = (file) => {
+        const known = seen.get(file);
+        if (known !== undefined)
+            return known;
+        const found = new Map();
+        seen.set(file, found);
+        const text = disk.readText(file);
+        if (text === undefined)
+            return found;
+        if (COMPONENT_FILE.test(file)) {
+            found.set("default", { file, isComponent: true, takesProps: false, hasComment: false });
+            return found;
+        }
+        const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, scriptKindOf(file));
+        const isDrawn = DRAWN_FILE.test(file) || DEFINES_COMPONENT.test(text);
+        const scope = { declared: new Map(), commented: new Set(), imported: new Map() };
+        for (const statement of source.statements) {
+            addDeclared(statement, scope);
+            addImported(statement, scope);
+        }
+        const followed = (specifier, name) => {
+            const target = targetOf(specifier, file);
+            return target === undefined ? undefined : exportsOf(target).get(name);
+        };
+        // once per file: the text may be large, and every export of it asks
+        const hasModuleComment = text.includes("@module");
+        const context = {
+            file,
+            isDrawn,
+            found,
+            followed,
+            allOf: (specifier) => {
+                const target = targetOf(specifier, file);
+                return target === undefined ? new Map() : exportsOf(target);
+            },
+            local: (name) => {
+                const imported = scope.imported.get(name);
+                if (imported !== undefined)
+                    return followed(imported.from, imported.name);
+                if (!scope.declared.has(name))
+                    return undefined;
+                const shape = scope.declared.get(name);
+                return {
+                    file,
+                    isComponent: isDrawn && shape !== undefined,
+                    takesProps: shape?.takesProps ?? false,
+                    hasComment: scope.commented.has(name) || hasModuleComment
+                };
+            }
+        };
+        for (const statement of source.statements)
+            addExports(statement, context);
+        return found;
+    };
+    return exportsOf;
+};
+/** The name a file goes by: its own, or its folder's for an index. */
+const stemOf = (file) => {
+    const parts = file.split("/");
+    const name = (parts.at(-1) ?? "").replace(/\.[^.]+$/, "");
+    return name === "index" ? (parts.at(-2) ?? name) : name;
+};
+/** The name a published thing goes by, when it reads as a component: a default export by its file's. */
+const componentNameOf = (name, thing) => {
+    if (!thing.isComponent)
+        return undefined;
+    const stem = stemOf(thing.file);
+    const named = name === "default" ? `${stem.charAt(0).toUpperCase()}${stem.slice(1)}` : name;
+    return COMPONENT_NAME.test(named) && !named.endsWith("Context") ? named : undefined;
+};
+/**
+ * The components some entries publish, one element per declaring file.
+ *
+ * @param entries - the entries' source files, absolute.
+ * @param disk - what is asked of the disk.
+ */
+export const publishedComponents = (entries, disk) => {
+    const exportsOf = exportReader(disk);
+    const files = new Map();
+    const things = entries.flatMap((entry) => [...exportsOf(entry)]);
+    for (const [name, thing] of things) {
+        const named = componentNameOf(name, thing);
+        if (named === undefined)
+            continue;
+        const file = files.get(thing.file) ?? { names: [], takesProps: false, hasComment: false };
+        if (!file.names.includes(named))
+            file.names.push(named);
+        file.takesProps ||= thing.takesProps;
+        file.hasComment ||= thing.hasComment;
+        files.set(thing.file, file);
+    }
+    return [...files].map(([file, each]) => ({ file, ...each }));
+};

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

@@ -0,0 +1,6 @@
+/**
+ * A folder's real path; for one not made yet, its nearest folder that is, with the rest of the path after it.
+ *
+ * @param folder - the folder, absolute.
+ */
+export declare const realFolder: (folder: string) => string;

package/dist/src/vite/realFolder.js

@@ -0,0 +1,25 @@
+/**
+ * A folder written as Vite writes its root: links followed and, on Windows, short names (`RUNNER~1`) written out in
+ * full. The configuration's folder and the build's output are named this way, so they compare with Vite's root.
+ *
+ * @remarks
+ * Vite reads its root with one of Node's two real paths on Windows, the plain one until a check it runs in the
+ * background ends and the native one after: they agree only on a path already written out. A root that differs from
+ * the folder the pages are named under makes the build's names climb out of it, and an output it does not see inside
+ * it is never emptied.
+ *
+ * @module
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+/**
+ * A folder's real path; for one not made yet, its nearest folder that is, with the rest of the path after it.
+ *
+ * @param folder - the folder, absolute.
+ */
+export const realFolder = (folder) => {
+    if (existsSync(folder))
+        return realpathSync.native(folder);
+    const parent = dirname(folder);
+    return parent === folder ? folder : join(realFolder(parent), basename(folder));
+};

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

@@ -0,0 +1,39 @@
+/**
+ * The configuration's `refs`, checked and made ready for the shell, and what the shell's generated entry says of them:
+ * the catalogues shown in the sidebar after this one's stories.
+ *
+ * @module
+ */
+import { type CatalogueRef } from "../catalogueRefs.ts";
+import type { RefOption } from "./config.ts";
+import type { ResolvedConfig } from "./configFile.ts";
+/** The composed catalogues, ready for the shell, in the configuration's order. */
+export type ResolvedRefs = readonly CatalogueRef[];
+/**
+ * Why the configuration's `refs` cannot be used, or none.
+ *
+ * @param config - the configuration, as loaded.
+ */
+export declare const refsProblem: (config: object) => string | undefined;
+/**
+ * The composed catalogues, each address its folder, in the configuration's order.
+ *
+ * @param refs - the configuration's `refs`, checked by `refsProblem`.
+ */
+export declare const resolvedRefs: (refs: Readonly<Record<string, RefOption>> | undefined) => readonly CatalogueRef[];
+/** The module that draws the composed catalogues, imported only by a catalogue that composes one. */
+export declare const REFS_MODULE = "forgebook/shell/refs";
+/**
+ * The composed catalogues and the code that draws them, for the shell; nothing for a catalogue that composes none, so
+ * its first load carries not even the way to that code.
+ *
+ * @param config - the configuration.
+ */
+export declare const refsLines: (config: Pick<ResolvedConfig, "refs">) => string[];
+/**
+ * What the plugin defines in the build for composition: whether the catalogue composes others, so a shell that composes
+ * none has every part of composition removed.
+ *
+ * @param refs - the composed catalogues.
+ */
+export declare const refsDefine: (refs: ResolvedRefs) => Readonly<Record<string, string>>;

package/dist/src/vite/refsConfig.js

@@ -0,0 +1,54 @@
+/**
+ * The configuration's `refs`, checked and made ready for the shell, and what the shell's generated entry says of them:
+ * the catalogues shown in the sidebar after this one's stories.
+ *
+ * @module
+ */
+import { refFolder, refProblem } from "../catalogueRefs.js";
+import { codeLiteral } from "../codeLiteral.js";
+/**
+ * Why the configuration's `refs` cannot be used, or none.
+ *
+ * @param config - the configuration, as loaded.
+ */
+export const refsProblem = (config) => {
+    const refs = Reflect.get(config, "refs");
+    if (refs === undefined)
+        return undefined;
+    if (typeof refs !== "object" || refs === null || Array.isArray(refs))
+        return 'refs must be an object of catalogues by id (`refs: { "design-system": { title, url } }`)';
+    return Object.entries(refs).flatMap(([id, ref]) => refProblem(id, ref) ?? [])[0];
+};
+/**
+ * The composed catalogues, each address its folder, in the configuration's order.
+ *
+ * @param refs - the configuration's `refs`, checked by `refsProblem`.
+ */
+export const resolvedRefs = (refs) => Object.entries(refs ?? {}).map(([id, ref]) => ({ id, title: ref.title.trim(), url: refFolder(ref.url) }));
+/** The module that draws the composed catalogues, imported only by a catalogue that composes one. */
+export const REFS_MODULE = "forgebook/shell/refs";
+/**
+ * The composed catalogues and the code that draws them, for the shell; nothing for a catalogue that composes none, so
+ * its first load carries not even the way to that code.
+ *
+ * @param config - the configuration.
+ */
+export const refsLines = (config) => config.refs.length === 0
+    ? []
+    : [
+        "    refs: {",
+        `      catalogues: ${codeLiteral(config.refs)},`,
+        `      load: () => import(${codeLiteral(REFS_MODULE)}).then((module) => module.RefPart)`,
+        "    },"
+    ];
+/** The name the build gives whether the catalogue composes others (`shell/composition.ts`). */
+const REFS_CONSTANT = "__FORGEBOOK_REFS__";
+/**
+ * What the plugin defines in the build for composition: whether the catalogue composes others, so a shell that composes
+ * none has every part of composition removed.
+ *
+ * @param refs - the composed catalogues.
+ */
+export const refsDefine = (refs) => ({
+    [REFS_CONSTANT]: JSON.stringify(refs.length > 0)
+});