forgebook 0.3.3 → 0.4.1

package/dist/src/vite/storylessRoutes.js

@@ -8,13 +8,25 @@
  *
  * @module
  */
-import { readFile } from "node:fs/promises";
+import { readFile, realpath } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { codeLiteral } from "../codeLiteral.js";
-import { addedLines, checkedCode, deletedTests, fileLines } from "./checkCode.js";
+import { smallFileText } from "./appTokenFiles.js";
+import { readAppTokens } from "./appTokens.js";
+import { addedLines, codeFindings, deletedTests, excusedValues, fileLines, LEFT_ALONE } from "./checkCode.js";
+import { currentComponents } from "./componentCache.js";
+import { graphDocument } from "./componentGraph.js";
+import { COMPONENT_FILE } from "./componentScan.js";
+import { compositionFindings } from "./compositionCheck.js";
 import { gitChange, gitOutput } from "./gitChange.js";
+import { workspacePackages } from "./projectFiles.js";
+import { reuseFindings } from "./reuseCheck.js";
 import { readTokenFiles, sourceTokensIn } from "./sourceTokens.js";
 import { TOKEN_ANSWERS, tokenSummary } from "./tokenAnswers.js";
+/** How many component files a change may touch and still be compared: past this it is a move or a rewrite. */
+const MOST_REUSE_FILES = 300;
+/** Fewer colours than this in what an application declares is no palette to compare with. */
+const FEWEST_COLORS = 5;
 /**
  * What one source's module declares; a module the bundler answers itself has no text to read, so it declares none.
  *
@@ -39,14 +51,14 @@ const sourceDeclaration = async (specifier, resolveSource, watch) => {
     }
 };
 /**
- * The catalogue's tokens, read at each question, so an edited file answers at once and costs nothing unasked. Sources
- * are read from their modules' text, each source's files before the catalogue's, which win a clash.
+ * The tokens a catalogue and its sources name, read at each question, so an edited file answers at once and costs nothing
+ * unasked. Sources are read from their modules' text, each source's files before the catalogue's, which win a clash.
  *
  * @param config - the catalogue's configuration.
  * @param resolveSource - finds the file of a source's module.
  * @param watch - told of every file read: the sources' modules and the tokens files; none by default.
  */
-export const catalogueTokens = async (config, resolveSource, watch = () => undefined) => {
+const namedTokens = async (config, resolveSource, watch = () => undefined) => {
     const declared = await Promise.all(config.sources.map((specifier) => sourceDeclaration(specifier, resolveSource, watch)));
     const own = config.tokens.map(({ path, mode }) => ({ path, mode, label: relative(config.dir, path) }));
     const files = [...declared.flatMap((source) => source.files), ...own];
@@ -59,7 +71,52 @@ export const catalogueTokens = async (config, resolveSource, watch = () => undef
         clashes,
         problems: [...declaring, ...problems],
         unread: declared.flatMap((source) => (source.unread === undefined ? [] : [source.unread])),
-        isConfigured: files.length > 0 || declaring.length > 0
+        isConfigured: files.length > 0 || declaring.length > 0,
+        sources: files.map(({ label }) => ({ kind: "tokens-file", file: label })),
+        notes: []
+    };
+};
+/** What the application declares; a failure of the system (a folder gone) is a note, with no machine's path in it. */
+const appTokensOf = (dir) => {
+    try {
+        return readAppTokens(dir);
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? String(error.code) : "an error";
+        return {
+            tokens: [],
+            clashes: [],
+            sources: [],
+            files: [],
+            problems: [],
+            unread: [`the application's files: ${code}`]
+        };
+    }
+};
+/**
+ * The tokens an agent is answered from: what the catalogue and its sources name or, when they name none, what the
+ * application already declares, which is read from its files and never run. A catalogue that says `tokens: []` wants
+ * none, so a named file is not the only way to say so.
+ *
+ * @param config - the catalogue's configuration.
+ * @param resolveSource - finds the file of a source's module.
+ * @param watch - told of every file read; none by default.
+ */
+export const catalogueTokens = async (config, resolveSource, watch = () => undefined) => {
+    const named = await namedTokens(config, resolveSource, watch);
+    if (named.isConfigured || config.isAppTokensOff === true)
+        return named;
+    const app = appTokensOf(config.dir);
+    for (const file of app.files)
+        watch(file);
+    return {
+        ...named,
+        tokens: app.tokens,
+        problems: app.problems,
+        clashes: app.clashes,
+        isConfigured: app.tokens.length > 0,
+        sources: app.sources,
+        notes: app.unread
     };
 };
 /**
@@ -72,12 +129,110 @@ export const catalogueTokens = async (config, resolveSource, watch = () => undef
  * @param resolveSource - finds the file of a source's module.
  */
 export const tokensModule = async (config, watch, resolveSource) => {
-    const { tokens, problems, unread } = await catalogueTokens(config, resolveSource, watch);
+    const { tokens, problems, unread } = await namedTokens(config, resolveSource, watch);
     // in both forms: Vite's, and the system's, which a Windows error message writes
     const shown = (problem) => problem.replaceAll(config.dir, ".").replaceAll(resolve(config.dir), ".");
     const value = { tokens: tokens.map(tokenSummary), problems: [...unread, ...problems].map(shown) };
     return { code: `export default ${codeLiteral(value)};`, moduleType: "js" };
 };
+/**
+ * The tokens worth comparing a change with. A named tokens file is the system whatever its size. In what an application
+ * merely declares, a handful of colours (a brand colour, a chart's) is no palette: against it every colour written by hand
+ * would read as a mistake, and a check that says so on every line gets turned off.
+ */
+const checkableTokens = ({ tokens, sources }) => {
+    if (sources.some((source) => source.kind === "tokens-file"))
+        return tokens;
+    const colors = tokens.filter((token) => token.type === "color").length;
+    return colors >= FEWEST_COLORS ? tokens : tokens.filter((token) => token.type !== "color");
+};
+/** How many sizes in objects that may not be styles an answer lists: past this, a file of options would bury the rest. */
+const MOST_CODE_ADVICE = 20;
+/**
+ * What added lines break: values only in the catalogue's folder when the tokens are what that folder's application
+ * declares, since a repository's other packages have systems of their own. A turned-off check is one everywhere. Only
+ * the compared values give advice: with no tokens there is nothing to weigh.
+ */
+const codeFindingsOf = (added, tokens, inFolder) => {
+    const compared = codeFindings(added.filter(({ file }) => inFolder(file)), tokens);
+    const elsewhere = codeFindings(added.filter(({ file }) => !inFolder(file)), []);
+    return { problems: [...compared.problems, ...elsewhere.problems], advice: compared.advice };
+};
+/** What a change's values were not compared with, and why, in the words `skipped` gives. */
+const notCheckedLine = (hasColors, hasSizes, { tokens }) => {
+    if (hasColors && hasSizes)
+        return [];
+    const what = [...(hasColors ? [] : ["colours"]), ...(hasSizes ? [] : ["sizes"])].join(" and ");
+    const reason = tokens.length === 0
+        ? "no tokens file"
+        : `too few tokens of that kind in the application (${tokens.length})`;
+    return [`${what} not checked: ${reason}`];
+};
+/** What a change's files were, at the commit it starts from: a file it adds has none. */
+const filesAtBase = async (root, base, files) => {
+    const read = await Promise.all(files.map(async (file) => ({
+        file,
+        text: await gitOutput(root, "show", `${base}:${file}`).catch(() => undefined)
+    })));
+    return read.flatMap(({ file, text }) => (text === undefined ? [] : [{ file, text }]));
+};
+/**
+ * What a change adds against the project's components, read over the whole repository, since the one a new component
+ * copies may live in another package. Only a change to a component's file costs this reading.
+ */
+const reuseOf = async (root, change, added) => {
+    try {
+        return await readReuse(root, change, added);
+    }
+    catch (error) {
+        // a crafted file past what a walk can take costs this part of the answer, and says so
+        const reason = error instanceof RangeError ? "a file nests too deep" : "it could not be read";
+        return {
+            problems: [],
+            advice: [],
+            excused: [],
+            hasRules: false,
+            notes: [`components not compared: ${reason}`]
+        };
+    }
+};
+/** What `reuseOf` reads. */
+const readReuse = async (root, change, added) => {
+    const isComponent = (file) => COMPONENT_FILE.test(file) && !LEFT_ALONE.test(file);
+    const touched = new Set(added.flatMap(({ file }) => (isComponent(file) ? [file] : [])));
+    const empty = { problems: [], advice: [], excused: [], notes: [], hasRules: false };
+    if (touched.size === 0)
+        return empty;
+    const deleted = change.deleted.filter(isComponent);
+    if (touched.size + deleted.length > MOST_REUSE_FILES) {
+        return {
+            ...empty,
+            notes: [`components not compared: the change touches more than ${MOST_REUSE_FILES} of them`]
+        };
+    }
+    const notes = [];
+    const components = currentComponents(root, notes);
+    const changed = [...touched].flatMap((file) => {
+        const text = smallFileText(join(root, file));
+        return text === undefined ? [] : [{ file, text }];
+    });
+    const packages = workspacePackages(root);
+    const composition = compositionFindings(added, changed, components, packages);
+    const findings = reuseFindings({
+        added,
+        changed,
+        previous: await filesAtBase(root, change.base, [...touched, ...deleted]),
+        components,
+        packages
+    });
+    return {
+        problems: [...findings.problems, ...composition.problems],
+        advice: findings.advice,
+        excused: [...findings.excused, ...composition.excused],
+        hasRules: components.some((each) => each.rules !== undefined),
+        notes: notes.map((note) => `components not all compared: ${note}`)
+    };
+};
 /**
  * What a change adds that breaks the design system. It needs nothing of the stories, like the tokens, so a story broken
  * mid-edit does not stop it; tokens that were asked for and cannot be read do, or a check would pass having checked less.
@@ -89,7 +244,9 @@ export const tokensModule = async (config, watch, resolveSource) => {
  */
 const checkCodeAnswer = async (config, params, resolveSource) => {
     const since = params.get("since") || "HEAD";
-    const { tokens, problems, unread } = await catalogueTokens(config, resolveSource);
+    const reading = await catalogueTokens(config, resolveSource);
+    const { problems, unread } = reading;
+    const tokens = checkableTokens(reading);
     if (problems.length > 0) {
         return { status: 400, body: { error: `The tokens files have problems: ${problems.join("; ")}` } };
     }
@@ -98,29 +255,63 @@ const checkCodeAnswer = async (config, params, resolveSource) => {
         return { status: 400, body: { error: change } };
     const root = (await gitOutput(config.dir, "rev-parse", "--show-toplevel")).trim();
     const fresh = await Promise.all(change.untracked.map(async (file) => fileLines(file, await readFile(join(root, file), "utf8").catch(() => ""))));
-    const hasTokens = tokens.length > 0;
+    const hasNamedFile = reading.sources.some((source) => source.kind === "tokens-file");
+    const added = [...addedLines(change.diff), ...fresh.flat()];
+    const folder = relative(root, await realpath(config.dir)).replaceAll("\\", "/");
+    const isInCatalogue = (file) => folder === "" || file === folder || file.startsWith(`${folder}/`);
+    const inFolder = (file) => hasNamedFile || isInCatalogue(file);
+    const hasColors = tokens.some((token) => token.type === "color") || (hasNamedFile && tokens.length > 0);
+    const hasSizes = tokens.some((token) => token.type === "dimension") || (hasNamedFile && tokens.length > 0);
+    const reuse = await reuseOf(root, change, added.filter(({ file }) => isInCatalogue(file)));
+    const code = codeFindingsOf(added, tokens, inFolder);
     const body = {
         schema: 1,
         since,
-        checked: hasTokens
-            ? ["raw-color", "raw-size", "suppression", "deleted-test"]
-            : ["suppression", "deleted-test"],
+        checked: [
+            ...(hasColors ? ["raw-color"] : []),
+            ...(hasSizes ? ["raw-size"] : []),
+            "suppression",
+            "deleted-test",
+            "deprecated-component",
+            "duplicate-component",
+            ...(reuse.hasRules ? ["composition"] : [])
+        ],
         skipped: [
-            ...(hasTokens ? [] : ["Colours and sizes: this catalogue names no tokens file."]),
-            ...unread.map((source) => `Tokens of a source: ${source}`)
+            ...notCheckedLine(hasColors, hasSizes, reading),
+            ...reuse.notes,
+            ...unread.map((source) => `tokens of a source not checked: ${source}`),
+            ...(code.advice.length > MOST_CODE_ADVICE
+                ? [`${code.advice.length - MOST_CODE_ADVICE} more sizes in objects to weigh not listed`]
+                : [])
         ],
-        problems: [
-            ...checkedCode([...addedLines(change.diff), ...fresh.flat()], tokens),
-            ...deletedTests(change.deleted)
-        ]
+        problems: [...code.problems, ...deletedTests(change.deleted), ...reuse.problems],
+        advice: [...code.advice.slice(0, MOST_CODE_ADVICE), ...reuse.advice],
+        tokenSources: reading.sources,
+        tokenClashes: reading.clashes.length,
+        tokenNotes: [...reading.notes],
+        notCompared: [...new Set(added.flatMap(({ file }) => (inFolder(file) ? [] : [file])))],
+        excused: [...excusedValues(added.filter(({ file }) => inFolder(file))), ...reuse.excused]
     };
     return { status: 200, body };
 };
+/** The map of the project, for a client with no shell. */
+const graphAnswer = async (config, params) => {
+    const limit = Number(params.get("limit"));
+    return {
+        status: 200,
+        body: graphDocument(config.dir, {
+            component: params.get("component") || undefined,
+            intent: params.get("intent") || undefined,
+            limit: Number.isInteger(limit) && limit > 0 ? limit : undefined
+        })
+    };
+};
 /** The answers that need nothing of the stories, so a story broken mid-edit cannot take them down. */
 export const STORYLESS_ROUTES = {
     ...Object.fromEntries(Object.entries(TOKEN_ANSWERS).map(([route, answer]) => [
         route,
         async (config, params, resolveSource) => answer(await catalogueTokens(config, resolveSource), params)
     ])),
-    "check-code": checkCodeAnswer
+    "check-code": checkCodeAnswer,
+    graph: graphAnswer
 };

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

@@ -0,0 +1,19 @@
+import { type ViewSwitch } from "../switches.ts";
+import { type VitePaths } from "./vitePaths.ts";
+/**
+ * Why the settings of a catalogue's switches' values cannot be used, or none.
+ *
+ * @param switches - the catalogue's switches, the ready-made ones among them: a value may imply one.
+ * @param dir - the configuration's folder.
+ * @param paths - how paths are read; Vite's by default.
+ */
+export declare const switchValuesProblem: (switches: readonly ViewSwitch[], dir: string, paths?: VitePaths) => string | undefined;
+/**
+ * The switches with their values' files as absolute paths, as the generated pages import them. Their settings are
+ * checked already.
+ *
+ * @param switches - the catalogue's switches.
+ * @param dir - the configuration's folder.
+ * @param paths - how paths are read; Vite's by default.
+ */
+export declare const withAbsoluteValueFiles: (switches: readonly ViewSwitch[], dir: string, paths?: VitePaths) => readonly ViewSwitch[];

package/dist/src/vite/switchValuesCheck.js

@@ -0,0 +1,164 @@
+/**
+ * What a catalogue's configuration may set on its switches' values, checked on Node before anything runs: a gallery's
+ * previews, what a value implies, a value's own style sheet; and their files' paths made absolute.
+ *
+ * @remarks
+ * Only here, not in `switches.ts`: a page has no use for these answers, and they need the files, so a first load carries
+ * none of it. A preview and a sheet are never named by an address, which is what the checks on their paths and values
+ * hold: a preset's remote picture or font would make every reader of the catalogue call a server its author may never
+ * have chosen. A sheet's contents are not read: like a source's sheets, it is the author's own CSS, compiled by Vite, and
+ * what it imports is theirs to decide.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { LANGUAGE_SWITCH_ID, switchControl } from "../switches.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** The most colours a preview shows: past them, none has room to read. */
+const MAX_SWATCHES = 8;
+/** The longest font name a preview takes: a family's name, never a list or a rule. */
+const MAX_FONT_NAME = 64;
+/** A scheme, or a `//` or `\\` address: what makes a path an address. A drive letter (`C:\`) has one letter only. */
+const ADDRESS = /^(?:[a-z][a-z0-9+.-]+:|\/\/|\\\\)/i;
+/** The pictures a browser draws in an `img`. */
+const PICTURE_FILE = /\.(?:avif|gif|jpe?g|png|svg|webp)$/i;
+/** The style sheets Vite compiles. */
+const SHEET_FILE = /\.(?:css|less|sass|scss|styl|stylus)$/i;
+/** A colour as CSS writes one: a word, a hex or a function of plain numbers; never `url()` or a rule. */
+const COLOUR = /^(?:#[0-9a-f]{3,8}|[a-z]+|(?:rgb|rgba|hsl|hsla|hwb|lab|lch|oklab|oklch)\([0-9a-z.,%/\s-]+\))$/i;
+/** A font's name: letters, digits, spaces and dashes, in any script. */
+const FONT_NAME = /^[\p{L}\p{N}][\p{L}\p{N} _-]*$/u;
+/**
+ * Why a value's file cannot be used, or none.
+ *
+ * @param what - what names it in the answer.
+ * @param path - the file, as the configuration writes it.
+ * @param file - which files it may be.
+ * @param kinds - their kinds, for the answer.
+ * @param dir - the configuration's folder.
+ * @param paths - how paths are read.
+ */
+const fileProblem = (what, path, file, kinds, dir, paths) => {
+    if (typeof path !== "string" || path === "")
+        return `${what} must be a file's path`;
+    if (ADDRESS.test(path))
+        return `${what} is an address ("${path}"): give a file's path, nothing is loaded from an address`;
+    if (!file.test(path))
+        return `${what} must be ${kinds} ("${path}")`;
+    return existsSync(paths.resolve(dir, path)) ? undefined : `${what} names no file ("${path}")`;
+};
+/**
+ * Why a value's preview cannot be used, or none.
+ *
+ * @param what - what names it in the answer.
+ * @param preview - the preview, as the configuration writes it.
+ * @param dir - the configuration's folder.
+ * @param paths - how paths are read.
+ */
+const previewProblem = (what, preview, dir, paths) => {
+    const keys = Object.keys(preview);
+    const unknown = keys.find((key) => !["image", "swatches", "font"].includes(key));
+    if (unknown !== undefined)
+        return `${what} has no "${unknown}": it takes image, or swatches and font`;
+    if ("image" in preview) {
+        if (keys.length > 1)
+            return `${what} takes image, or swatches and font, not both`;
+        return fileProblem(what, preview.image, PICTURE_FILE, "a picture", dir, paths);
+    }
+    const { swatches, font } = preview;
+    if (!Array.isArray(swatches) || swatches.length === 0 || swatches.length > MAX_SWATCHES)
+        return `${what} needs image, or swatches: 1 to ${MAX_SWATCHES} colours`;
+    const wrong = swatches.find((colour) => typeof colour !== "string" || !COLOUR.test(colour));
+    if (wrong !== undefined)
+        return `${what} has a swatch that is not a plain colour (${String(wrong)})`;
+    if (font !== undefined &&
+        (typeof font !== "string" || font.length > MAX_FONT_NAME || !FONT_NAME.test(font)))
+        return `${what} has a font that is not a name (${String(font)}): one family's name, nothing is loaded for it`;
+    return undefined;
+};
+/**
+ * Why what a value implies cannot be used, or none: every switch and value named exists, a value does not imply its own
+ * switch, and what it implies implies nothing further, so a view always has one answer.
+ *
+ * @param what - what names it in the answer.
+ * @param each - the switch.
+ * @param implies - the values it implies.
+ * @param switches - the catalogue's switches.
+ */
+const impliesProblem = (what, each, implies, switches) => {
+    for (const [id, value] of Object.entries(implies)) {
+        const target = switches.find((candidate) => candidate.id === id);
+        // a source may offer languages this configuration does not know: the switch and its values exist only in the page
+        if (id === LANGUAGE_SWITCH_ID)
+            continue;
+        if (target === undefined)
+            return `${what} implies a switch there is not ("${id}")`;
+        if (target === each)
+            return `${what} implies its own switch`;
+        const implied = target.values.find((candidate) => candidate.value === value);
+        if (implied === undefined)
+            return `${what} implies a value "${id}" does not have ("${value}")`;
+        // Compare leaves out a value that only follows the system: a switch implied there would have no cell at all
+        if (implied.scheme === "system")
+            return `${what} implies ${id}=${value}, which only follows the system`;
+        if (implied.implies !== undefined)
+            return `${what} implies ${id}=${value}, which implies more: an implied value implies nothing further`;
+    }
+    return undefined;
+};
+/**
+ * Why one value's settings cannot be used, or none.
+ *
+ * @param each - the switch.
+ * @param value - the value.
+ * @param switches - the catalogue's switches.
+ * @param dir - the configuration's folder.
+ * @param paths - how paths are read.
+ */
+const valueProblem = (each, value, switches, dir, paths) => {
+    const what = `The switch "${each.id}", value "${value.value}":`;
+    if (value.preview !== undefined && switchControl(each) !== "gallery")
+        return `${what} a preview shows only in a gallery: add control: "gallery" to the switch`;
+    return ((value.preview === undefined
+        ? undefined
+        : previewProblem(`${what} its preview`, value.preview, dir, paths)) ??
+        (value.implies === undefined ? undefined : impliesProblem(what, each, value.implies, switches)) ??
+        (value.sheet === undefined
+            ? undefined
+            : fileProblem(`${what} its sheet`, value.sheet, SHEET_FILE, "a style sheet", dir, paths)));
+};
+/**
+ * Why the settings of a catalogue's switches' values cannot be used, or none.
+ *
+ * @param switches - the catalogue's switches, the ready-made ones among them: a value may imply one.
+ * @param dir - the configuration's folder.
+ * @param paths - how paths are read; Vite's by default.
+ */
+export const switchValuesProblem = (switches, dir, paths = VITE_PATHS) => {
+    for (const each of switches) {
+        for (const value of each.values) {
+            const problem = valueProblem(each, value, switches, dir, paths);
+            if (problem !== undefined)
+                return problem;
+        }
+    }
+    return undefined;
+};
+/**
+ * The switches with their values' files as absolute paths, as the generated pages import them. Their settings are
+ * checked already.
+ *
+ * @param switches - the catalogue's switches.
+ * @param dir - the configuration's folder.
+ * @param paths - how paths are read; Vite's by default.
+ */
+export const withAbsoluteValueFiles = (switches, dir, paths = VITE_PATHS) => switches.map((each) => ({
+    ...each,
+    values: each.values.map((value) => ({
+        ...value,
+        ...(value.sheet === undefined ? {} : { sheet: paths.resolve(dir, value.sheet) }),
+        ...(value.preview !== undefined && "image" in value.preview
+            ? { preview: { image: paths.resolve(dir, value.preview.image) } }
+            : {})
+    }))
+}));

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

@@ -0,0 +1,15 @@
+/**
+ * What `forgebook switches` and `list_switches` answer: the switches a catalogue offers, so an agent can name a value in
+ * a view (`--view look=night`) and see what it brings with it without opening the shell.
+ *
+ * @module
+ */
+import { type ViewSwitch } from "../switches.ts";
+import type { SwitchesDocument } from "./agent.types.ts";
+/**
+ * The document of a catalogue's switches.
+ *
+ * @param switches - the catalogue's switches, the ready-made ones among them, their files absolute.
+ * @param dir - the configuration's folder.
+ */
+export declare const switchesDocument: (switches: readonly ViewSwitch[], dir: string) => SwitchesDocument;

package/dist/src/vite/switchesDocument.js

@@ -0,0 +1,47 @@
+/**
+ * What `forgebook switches` and `list_switches` answer: the switches a catalogue offers, so an agent can name a value in
+ * a view (`--view look=night`) and see what it brings with it without opening the shell.
+ *
+ * @module
+ */
+import { switchControl } from "../switches.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/** A file's path as the document gives it. */
+const fromDir = (dir, file) => VITE_PATHS.relative(dir, file);
+/**
+ * A value as the document gives it, its files by their path from the configuration's folder.
+ *
+ * @param each - the switch.
+ * @param value - the value.
+ * @param dir - the configuration's folder.
+ */
+const documentValue = (each, value, dir) => {
+    const { preview, implies, sheet } = value;
+    return {
+        value: value.value,
+        label: value.label,
+        view: `${each.id}=${value.value}`,
+        ...(implies === undefined ? {} : { implies }),
+        ...(sheet === undefined ? {} : { sheet: fromDir(dir, sheet) }),
+        ...(preview === undefined
+            ? {}
+            : { preview: "image" in preview ? { image: fromDir(dir, preview.image) } : preview })
+    };
+};
+/**
+ * The document of a catalogue's switches.
+ *
+ * @param switches - the catalogue's switches, the ready-made ones among them, their files absolute.
+ * @param dir - the configuration's folder.
+ */
+export const switchesDocument = (switches, dir) => ({
+    schema: 1,
+    switches: switches.map((each) => ({
+        id: each.id,
+        label: each.label,
+        default: each.default,
+        control: switchControl(each),
+        ...(each.role === undefined ? {} : { role: each.role }),
+        values: each.values.map((value) => documentValue(each, value, dir))
+    }))
+});

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

@@ -0,0 +1,41 @@
+/** A theme value the file writes. */
+export type ConfigToken = {
+    /** Its name, as Tailwind 4 names it. */
+    readonly name: string;
+    /** Its value. */
+    readonly value: string;
+    /** Its type, from the theme key that holds it. */
+    readonly type: string;
+};
+/** What a configuration file gives. */
+export type TailwindConfigReading = {
+    /** Its tokens. */
+    readonly tokens: readonly ConfigToken[];
+    /** What cannot be read without running it, one line each. */
+    readonly unread: readonly string[];
+    /** The modules its `presets` name, to read in turn. */
+    readonly presets: readonly string[];
+    /** The theme keys it replaces rather than extends: Tailwind's defaults for these do not apply. */
+    readonly replaced: readonly string[];
+    /** How it reaches Tailwind's default palette by name (`colors.blue` from `tailwindcss/colors`). */
+    readonly paletteAliases: readonly {
+        readonly name: string;
+        readonly palette: string;
+    }[];
+};
+/**
+ * Reads a Tailwind configuration's text.
+ *
+ * @param file - its path, for the parser (its extension says TypeScript).
+ * @param text - its text.
+ */
+export declare const readTailwindConfig: (file: string, text: string) => TailwindConfigReading;
+/**
+ * The colours of Tailwind's default palette, from the text of `tailwindcss/lib/public/colors.js`: only an object of
+ * plain strings, read and not run, as any other file here.
+ *
+ * @param file - its path.
+ * @param text - its text.
+ * @returns each colour's name as Tailwind 4 names it, with its value.
+ */
+export declare const readTailwindPalette: (file: string, text: string) => ConfigToken[];