forgebook 0.1.8 → 0.2.0

package/dist/src/vite/designTokens.js

@@ -0,0 +1,382 @@
+/**
+ * Design tokens read from DTCG files (the Design Tokens Format, 2025.10): a flat list with references followed and
+ * themes applied, every value as CSS writes it.
+ *
+ * @remarks
+ * Pure: parsed JSON in, tokens out. The format has no themes of its own, so a theme is a file of its own read over the
+ * base (`tokens: ["tokens.json", { file: "dark.json", mode: "dark" }]`). References are followed over base and theme
+ * together: a theme can alias the base, and a base alias follows what a theme overrides, which is why semantic tokens
+ * over a palette change with the theme at all. That is why files are collected first and resolved only once all are
+ * known. A token that cannot be used is named in `problems` with its file, and the others stay usable: nothing vanishes
+ * in silence, since a token an agent cannot find is a colour it writes by hand.
+ *
+ * Files of a catalogue's sources are read before its own, so its aliases reach a library's palette and a later file
+ * replaces an earlier one's token. Within one author's files that is plain layering; between authors it is a clash,
+ * reported and never refused: the catalogue is what puts the libraries together, so its value is the one in use.
+ *
+ * @module
+ */
+import { tokenClashes } from "./tokenClashes.js";
+/** A reference to a token in a value: nothing but its name in braces. */
+const ALIAS = /^\{([^{}]+)\}$/;
+/** What a token or group name may not hold: the format reserves them for references. */
+const RESERVED_IN_NAME = /[.{}]/;
+/** The key of the token a group holds under its own name. */
+const ROOT_KEY = "$root";
+/** Whether a value is an object with named fields. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A field as text, when it is text. */
+const textField = (node, field) => {
+    const value = node[field];
+    return typeof value === "string" ? value : undefined;
+};
+/** What a node says of deprecation: the key's presence decides, since `false` clears what a group set. */
+const deprecationOf = (node, inherited) => {
+    if (!("$deprecated" in node))
+        return inherited;
+    const value = node["$deprecated"];
+    if (value === true)
+        return "Deprecated.";
+    return typeof value === "string" ? value : undefined;
+};
+/** A JSON pointer's target in a document; none when it leads nowhere. */
+const pointed = (root, pointer) => {
+    let current = root;
+    for (const part of pointer.replace(/^#\/?/, "").split("/")) {
+        if (part === "")
+            continue;
+        const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (Array.isArray(current))
+            current = current[Number(key)];
+        else if (isRecord(current))
+            current = current[key];
+        else
+            return undefined;
+    }
+    return current;
+};
+/** Everything under a node with its `$ref`s replaced by what they point at, a node's own fields winning. */
+const withoutRefs = (node, root, through, problems) => {
+    if (Array.isArray(node))
+        return node.map((each) => withoutRefs(each, root, through, problems));
+    if (!isRecord(node))
+        return node;
+    const pointer = textField(node, "$ref");
+    const own = Object.fromEntries(Object.entries(node)
+        .filter(([key]) => key !== "$ref")
+        .map(([key, value]) => [key, withoutRefs(value, root, through, problems)]));
+    if (pointer === undefined)
+        return own;
+    if (through.has(pointer)) {
+        problems.push(`$ref ${pointer} leads back to itself`);
+        return own;
+    }
+    const target = pointed(root, pointer);
+    if (target === undefined) {
+        problems.push(`$ref ${pointer} leads nowhere`);
+        return own;
+    }
+    const expanded = withoutRefs(target, root, new Set([...through, pointer]), problems);
+    return isRecord(expanded) ? { ...expanded, ...own } : expanded;
+};
+/** A group's fields over the one it extends: a local token replaces the inherited one whole, a group merges. */
+const mergedGroup = (base, local) => {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(local)) {
+        const known = merged[key];
+        const areGroups = isRecord(value) && isRecord(known) && !("$value" in value) && !("$value" in known);
+        merged[key] = areGroups ? mergedGroup(known, value) : value;
+    }
+    return merged;
+};
+/** A group with what it extends applied, the groups under it included. */
+const withExtends = (group, root, through, problems) => {
+    const reference = textField(group, "$extends");
+    const name = reference === undefined ? undefined : ALIAS.exec(reference)?.[1];
+    let base = {};
+    if (name !== undefined) {
+        const target = pointed(root, name.split(".").join("/"));
+        if (through.has(name))
+            problems.push(`$extends {${name}} leads back to itself`);
+        else if (!isRecord(target))
+            problems.push(`$extends {${name}} leads nowhere`);
+        else if ("$value" in target)
+            problems.push(`$extends {${name}} names a token, not a group`);
+        else
+            base = withExtends(target, root, new Set([...through, name]), problems);
+    }
+    const own = Object.fromEntries(Object.entries(group)
+        .filter(([key]) => key !== "$extends")
+        .map(([key, value]) => [
+        key,
+        isRecord(value) && !("$value" in value) && !key.startsWith("$")
+            ? withExtends(value, root, through, problems)
+            : value
+    ]));
+    return mergedGroup(base, own);
+};
+/** One token's raw form. */
+const rawToken = (node, name, inherited) => ({
+    name,
+    ownType: textField(node, "$type"),
+    groupType: inherited.type,
+    value: node["$value"],
+    description: textField(node, "$description"),
+    deprecated: deprecationOf(node, inherited.deprecated),
+    label: inherited.label,
+    source: inherited.source
+});
+/** Every token under a group, what the group says of type and deprecation reaching its tokens. */
+const collected = (group, path, inherited, problems) => {
+    const passed = {
+        ...inherited,
+        type: textField(group, "$type") ?? inherited.type,
+        deprecated: deprecationOf(group, inherited.deprecated)
+    };
+    return Object.entries(group).flatMap(([key, node]) => {
+        if (!isRecord(node) || (key.startsWith("$") && key !== ROOT_KEY))
+            return [];
+        const nodePath = [...path, key];
+        const name = nodePath.join(".");
+        if (RESERVED_IN_NAME.test(key)) {
+            problems.push(`${name}: a name cannot hold ".", "{" or "}"`);
+            return [];
+        }
+        if (!("$value" in node))
+            return collected(node, nodePath, passed, problems);
+        const children = Object.keys(node).filter((child) => !child.startsWith("$"));
+        if (children.length > 0)
+            problems.push(`${name}: a token cannot also be a group (${children.join(", ")})`);
+        return [rawToken(node, name, passed)];
+    });
+};
+/** A file's raw tokens. */
+const fileTokens = (input, problems) => {
+    const local = [];
+    const inherited = { type: undefined, deprecated: undefined, label: input.label, source: input.source };
+    let raw = [];
+    if (!isRecord(input.file))
+        local.push("the file is not a group of tokens");
+    else {
+        try {
+            const root = withoutRefs(input.file, input.file, new Set(), local);
+            raw = collected(withExtends(asRecord(root), input.file, new Set(), local), [], inherited, local);
+        }
+        catch (error) {
+            // a file nested past the stack costs that file, not every other author's tokens
+            local.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    problems.push(...local.map((problem) => `${input.label}: ${problem}`));
+    return raw;
+};
+/** A value known to be a record, for the document's root. */
+const asRecord = (value) => (isRecord(value) ? value : {});
+/** A font name, quoted unless it is a plain identifier or a generic family. */
+const fontName = (name) => (/^-?[a-zA-Z_][\w-]*$/.test(name) ? name : JSON.stringify(name));
+/** A number of 0 to 1 as two hexadecimal digits. */
+const hexByte = (part) => Math.round(Math.min(1, Math.max(0, part)) * 255)
+    .toString(16)
+    .padStart(2, "0");
+/** What `color()` cannot write: these spaces are CSS functions of their own. */
+const FUNCTION_SPACES = {
+    hsl: ([h, s, l]) => `hsl(${h} ${s}% ${l}%)`,
+    hwb: ([h, w, b]) => `hwb(${h} ${w}% ${b}%)`,
+    lab: ([l, a, b]) => `lab(${l}% ${a} ${b})`,
+    lch: ([l, c, h]) => `lch(${l}% ${c} ${h})`,
+    oklab: ([l, a, b]) => `oklab(${l} ${a} ${b})`,
+    oklch: ([l, c, h]) => `oklch(${l} ${c} ${h})`
+};
+/** A colour with its alpha added to a function's text. */
+const withAlpha = (text, alpha) => alpha >= 1 ? text : `${text.slice(0, -1)} / ${alpha})`;
+/**
+ * A colour object as CSS writes it. Its `hex` is only a fallback, so it is taken in sRGB alone: elsewhere it would hide
+ * the colour itself, and with an alpha it would drop it.
+ */
+const colorText = (color) => {
+    const space = textField(color, "colorSpace");
+    const parts = color["components"];
+    if (space === undefined || !Array.isArray(parts))
+        return undefined;
+    const alpha = typeof color["alpha"] === "number" ? color["alpha"] : 1;
+    const isNumeric = parts.every((part) => typeof part === "number");
+    if (space === "srgb" && isNumeric) {
+        const hex = `#${parts.map((part) => hexByte(Number(part))).join("")}`;
+        return alpha >= 1 ? (textField(color, "hex") ?? hex) : `${hex}${hexByte(alpha)}`;
+    }
+    const written = parts.map(String);
+    const own = FUNCTION_SPACES[space];
+    return withAlpha(own === undefined ? `color(${space} ${written.join(" ")})` : own(written), alpha);
+};
+/** Parts of a value written as CSS, where the parts have a CSS form; a composite keeps its fields. */
+const cssParts = (value) => {
+    if (Array.isArray(value))
+        return value.map(cssParts);
+    if (!isRecord(value))
+        return value;
+    const color = colorText(value);
+    if (color !== undefined)
+        return color;
+    if ("value" in value && "unit" in value)
+        return `${String(value["value"])}${String(value["unit"])}`;
+    return Object.fromEntries(Object.entries(value).map(([key, part]) => [key, cssParts(part)]));
+};
+/** A value as CSS writes it; a composite as JSON of its parts. */
+const valueText = (value, type) => {
+    if (type === "fontFamily") {
+        return (Array.isArray(value) ? value : [value]).map((name) => fontName(String(name))).join(", ");
+    }
+    if (type === "cubicBezier" && Array.isArray(value))
+        return `cubic-bezier(${value.join(", ")})`;
+    if (typeof value === "string" || typeof value === "number")
+        return String(value);
+    const parts = cssParts(value);
+    return typeof parts === "string" ? parts : JSON.stringify(parts);
+};
+/** The name a value references, when it is nothing else. */
+const aliasOf = (value) => typeof value === "string" ? ALIAS.exec(value)?.[1] : undefined;
+/** A value with every reference followed. Throws the problem's text, caught for its token. */
+const followed = (value, byName, through) => {
+    const name = aliasOf(value);
+    if (name !== undefined) {
+        if (through.has(name))
+            throw new Error(`the alias {${name}} leads back to itself`);
+        const target = byName.get(name);
+        if (target === undefined)
+            throw new Error(`the alias {${name}} leads nowhere`);
+        return followed(target.value, byName, new Set([...through, name]));
+    }
+    if (Array.isArray(value))
+        return value.map((part) => followed(part, byName, through));
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, part]) => [key, followed(part, byName, through)]));
+    }
+    return value;
+};
+/** A token's type: its own, then what its alias resolves to, then its group's, as the format orders them. */
+const typeOf = (raw, byName, seen) => {
+    if (raw.ownType !== undefined)
+        return raw.ownType;
+    const name = aliasOf(raw.value);
+    const target = name === undefined || seen.has(name) ? undefined : byName.get(name);
+    const aliased = target === undefined ? undefined : typeOf(target, byName, new Set([...seen, target.name]));
+    const replaced = raw.replaces === undefined ? undefined : typeOf(raw.replaces, byName, seen);
+    return aliased ?? raw.groupType ?? replaced;
+};
+/** What a token comes to under a set of tokens, or why it cannot be used. */
+const resolvedValue = (raw, byName) => {
+    const type = typeOf(raw, byName, new Set([raw.name]));
+    if (type === undefined)
+        return `${raw.name}: no $type, on it or on its groups`;
+    const name = aliasOf(raw.value);
+    const target = name === undefined ? undefined : byName.get(name);
+    const targetType = target === undefined ? undefined : typeOf(target, byName, new Set([target.name]));
+    if (raw.ownType !== undefined && targetType !== undefined && raw.ownType !== targetType) {
+        return `${raw.name}: it says ${raw.ownType}, its alias is ${targetType}`;
+    }
+    try {
+        return { text: valueText(followed(raw.value, byName, new Set([raw.name])), type), type };
+    }
+    catch (error) {
+        return `${raw.name}: ${error instanceof Error ? error.message : String(error)}`;
+    }
+};
+/** The token a raw one makes, its values in each theme filled in afterwards. */
+const tokenOf = (raw, value, type) => {
+    const alias = aliasOf(raw.value);
+    return {
+        name: raw.name,
+        type,
+        value,
+        ...(alias === undefined ? {} : { alias }),
+        ...(raw.description === undefined ? {} : { description: raw.description }),
+        ...(raw.deprecated === undefined ? {} : { deprecated: raw.deprecated }),
+        ...(raw.source === undefined ? {} : { source: raw.source }),
+        modes: {}
+    };
+};
+/**
+ * The tokens of files by name, the later file replacing. A file over another writes the value and little else, so what
+ * it leaves out is the replaced token's: it retunes the token, it does not make a new one.
+ */
+const byNameOf = (lists) => {
+    const merged = new Map();
+    for (const token of lists.flat()) {
+        const known = merged.get(token.name);
+        merged.set(token.name, known === undefined
+            ? token
+            : {
+                ...token,
+                replaces: known,
+                description: token.description ?? known.description,
+                deprecated: token.deprecated ?? known.deprecated
+            });
+    }
+    return merged;
+};
+/** Each token's value in a theme, with a problem for what the theme itself broke. */
+const themeValues = (own, base, problems) => {
+    const merged = byNameOf([[...base.values()], own]);
+    const names = new Set(own.map((token) => token.name));
+    const values = new Map();
+    for (const raw of merged.values()) {
+        const result = resolvedValue(raw, merged);
+        if (typeof result !== "string")
+            values.set(raw.name, { ...result, raw });
+        else if (names.has(raw.name))
+            problems.push(`${raw.label}: ${result}`);
+    }
+    return values;
+};
+/** A theme's values on the tokens: a token it names, one a reference changed, and one only it has. */
+const applyTheme = (tokens, mode, own, values) => {
+    for (const [name, value] of values) {
+        const known = tokens.get(name);
+        if (known === undefined) {
+            tokens.set(name, {
+                ...tokenOf(value.raw, value.text, value.type),
+                isThemeOnly: true,
+                modes: { [mode]: value.text }
+            });
+        }
+        else if (value.text !== known.value || own.some((token) => token.name === name)) {
+            tokens.set(name, { ...known, modes: { ...known.modes, [mode]: value.text } });
+        }
+    }
+};
+/**
+ * Reads the files of a catalogue: the base first, then each theme over it. A theme gives a token a value when it names
+ * the token, or when a reference brings it a different one. The files of one theme are one layer, the later replacing,
+ * so a catalogue's dark file reaches what a library's dark file sets.
+ *
+ * @param inputs - the files: each source's in the catalogue's order, then the catalogue's own.
+ */
+export const readTokens = (inputs) => {
+    const problems = [];
+    const files = inputs.map(({ mode, ...input }) => ({ mode, raw: fileTokens({ mode, ...input }, problems) }));
+    const layer = (mode) => byNameOf(files.filter((file) => file.mode === mode).map((file) => file.raw));
+    const base = layer(undefined);
+    const tokens = new Map();
+    for (const raw of base.values()) {
+        const result = resolvedValue(raw, base);
+        if (typeof result !== "string")
+            tokens.set(raw.name, tokenOf(raw, result.text, result.type));
+        else
+            problems.push(`${raw.label}: ${result}`);
+    }
+    for (const mode of new Set(files.flatMap((file) => (file.mode === undefined ? [] : [file.mode])))) {
+        const own = [...layer(mode).values()];
+        applyTheme(tokens, mode, own, themeValues(own, base, problems));
+    }
+    return { tokens: [...tokens.values()], problems, clashes: tokenClashes(files) };
+};
+/**
+ * The tokens of a category: a type (`color`), or a first group (`space`).
+ *
+ * @param tokens - the tokens.
+ * @param category - the category; none for all of them.
+ */
+export const filteredTokens = (tokens, category) => tokens.filter((token) => category === undefined ||
+    token.type === category ||
+    token.name === category ||
+    token.name.startsWith(`${category}.`));

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

@@ -0,0 +1,51 @@
+/** A disk cache of one kind of answer. */
+export type DiskCache<TValue> = {
+    /** The answer kept under a key, when everything it was made from is unchanged. */
+    readonly read: (key: string) => TValue | undefined;
+    /** Keeps an answer under a key, with the paths it was made from, stamped (`stampPaths`). */
+    readonly write: (key: string, value: TValue, stamps: readonly PathStamp[]) => void;
+    /** Whether it keeps any answer, fresh or not: none on a project's first start. */
+    readonly isEmpty: () => boolean;
+};
+/** A path and its stamp; `null` for a path that does not exist, which may appear later. */
+export type PathStamp = readonly [path: string, stamp: string | null, changedAt: string | null];
+/**
+ * The stamps of the paths an answer was made from, taken once it is made.
+ *
+ * @param paths - files and folders; repeats are stamped once.
+ */
+export declare const stampPaths: (paths: readonly string[]) => PathStamp[];
+/** The time now, in nanoseconds since the epoch: what `isSettledSince` compares a path's last change with. */
+export declare const nowNs: () => bigint;
+/**
+ * How long before an answer's making a change still counts as made during it, in nanoseconds. A file system writes
+ * times with its own clock and grain (two seconds on FAT, a coarse kernel clock on Linux) and some update them late,
+ * so a change made while the answer was read can carry a time a little before its start.
+ */
+export declare const SETTLE_MARGIN_NS = 3000000000n;
+/**
+ * Whether no path changed since shortly before an answer's making started (`SETTLE_MARGIN_NS`): one that did may have
+ * been read before or after its change, so the answer is not kept; the next one made after it settles is.
+ *
+ * @param stamps - the paths' stamps, taken once the answer was made.
+ * @param since - when its making started (`nowNs`).
+ */
+export declare const isSettledSince: (stamps: readonly PathStamp[], since: bigint) => boolean;
+/**
+ * What the answers of a piece of code depend on besides their files: every file of its folders, and the manifests of
+ * the packages it reads with, by stamp (or by text, for a file that changed just before, `codeFileStamp`), so another
+ * version installed, or an edit of a source while developing it, makes every kept answer a miss.
+ *
+ * @param folders - the folders of the code that makes the answers.
+ * @param files - other files it depends on (the manifests of the parser, the compiler, the highlighter).
+ * @param since - when the stamp is taken; now unless a test says otherwise.
+ */
+export declare const codeStamp: (folders: readonly string[], files?: readonly string[], since?: bigint) => string;
+/**
+ * A cache in a folder.
+ *
+ * @param folder - the folder, created on the first write.
+ * @param code - the stamp of the code that makes the answers (`codeStamp`): another one is a miss.
+ * @param isValue - whether what was read is an answer: a file written by another version may hold anything.
+ */
+export declare const diskCache: <TValue>(folder: string, code: string, isValue: (value: unknown) => value is TValue & {}) => DiskCache<TValue>;

package/dist/src/vite/diskCache.js

@@ -0,0 +1,211 @@
+/**
+ * What a dev server worked out once and need not work out again, kept on disk: a story file's component docs, its
+ * code, a group's "Used in", a pattern's index; each with the paths it was made from, stamped as they were read.
+ *
+ * @remarks
+ * A story's page reads its component's docs at once, and those need a TypeScript program: more memory than the rest of
+ * the server. Kept here, a later start answers from a file and starts no worker until something changes.
+ *
+ * An entry is reused only while nothing it was made from changed:
+ * - every path it depends on keeps its stamp (`stampPaths`): a file's change and modification times, size and inode;
+ *   a folder's list of names, so a file added beside one an import found, which the import may now find, is a miss,
+ *   while a save that replaces a file is not; a path that was missing must still be missing;
+ * - the code that made it is the same (`codeStamp`): another version of Forgebook, of the framework's adapter or of
+ *   the tools they read with, or an edit of their sources, is a miss; a file changed within the margin below is
+ *   stamped by its text, since no later answer waits for it to settle.
+ *
+ * Paths are stamped once the answer is made, and an answer is kept only when none of them changed after its making
+ * started (`isSettledSince`): an edit made while it was being read would otherwise be stamped beside the old answer.
+ * The same wait makes a file system's time grain harmless: a kept stamp's last change is older than the margin, so a
+ * later save, even of the same size, carries a later time.
+ *
+ * The folder sits in Vite's cache folder, so what clears that clears this. A cache that cannot be read or written is
+ * only a slower start: every failure here is a miss.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+/** The largest entry read back, in bytes: anything larger was not written here. */
+const MOST_BYTES = 64 * 1024 * 1024;
+/** Whether a value is a path's stamp. */
+const isPathStamp = (value) => Array.isArray(value) &&
+    typeof value[0] === "string" &&
+    (typeof value[1] === "string" || value[1] === null) &&
+    (typeof value[2] === "string" || value[2] === null);
+/** Whether a parsed file is an entry. */
+const isEntry = (value) => typeof value === "object" &&
+    value !== null &&
+    "code" in value &&
+    typeof value.code === "string" &&
+    "value" in value &&
+    "paths" in value &&
+    Array.isArray(value.paths) &&
+    value.paths.every(isPathStamp);
+/**
+ * A path's stamp as it is now, with when it last changed (nanoseconds since the epoch, as a text).
+ *
+ * @param path - a file or a folder.
+ */
+const stampOf = (path) => {
+    const stats = statSync(path, { bigint: true, throwIfNoEntry: false });
+    if (stats === undefined)
+        return [path, null, null];
+    if (!stats.isDirectory())
+        return [path, `${stats.ctimeNs}:${stats.mtimeNs}:${stats.size}:${stats.ino}`, String(stats.ctimeNs)];
+    const names = readdirSync(path).sort().join("\0");
+    return [path, `dir:${createHash("sha256").update(names).digest("hex")}`, String(stats.ctimeNs)];
+};
+/**
+ * The stamps of the paths an answer was made from, taken once it is made.
+ *
+ * @param paths - files and folders; repeats are stamped once.
+ */
+export const stampPaths = (paths) => [...new Set(paths)].map(stampOf);
+/** The time now, in nanoseconds since the epoch: what `isSettledSince` compares a path's last change with. */
+export const nowNs = () => BigInt(Date.now()) * 1000000n;
+/**
+ * How long before an answer's making a change still counts as made during it, in nanoseconds. A file system writes
+ * times with its own clock and grain (two seconds on FAT, a coarse kernel clock on Linux) and some update them late,
+ * so a change made while the answer was read can carry a time a little before its start.
+ */
+export const SETTLE_MARGIN_NS = 3000000000n;
+/**
+ * Whether no path changed since shortly before an answer's making started (`SETTLE_MARGIN_NS`): one that did may have
+ * been read before or after its change, so the answer is not kept; the next one made after it settles is.
+ *
+ * @param stamps - the paths' stamps, taken once the answer was made.
+ * @param since - when its making started (`nowNs`).
+ */
+export const isSettledSince = (stamps, since) => stamps.every(([, , changedAt]) => changedAt === null || BigInt(changedAt) < since - SETTLE_MARGIN_NS);
+/**
+ * A file's part of a code stamp: its stamp, or the hash of its text when it changed shortly before `since`. A file
+ * system's times have a grain (a clock tick on Windows), so two same-size saves in one tick leave the same stamp; a
+ * code stamp is taken once at a start, with no answer made after it to wait for (`isSettledSince`), so a file still
+ * within the margin is read instead. Only those are read: after an install, the first start reads the package once.
+ *
+ * @param path - a file or a folder of the code.
+ * @param since - when the code stamp is taken (`nowNs`).
+ */
+const codeFileStamp = (path, since) => {
+    const stamped = stampOf(path);
+    const [, stamp] = stamped;
+    if (stamp === null)
+        return "";
+    // a folder's stamp is its names, which have no grain
+    if (stamp.startsWith("dir:") || isSettledSince([stamped], since))
+        return stamp;
+    try {
+        return `text:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+    }
+    catch {
+        // gone since it was stamped: its stamp still tells it apart from the file that was there
+        return stamp;
+    }
+};
+/**
+ * What the answers of a piece of code depend on besides their files: every file of its folders, and the manifests of
+ * the packages it reads with, by stamp (or by text, for a file that changed just before, `codeFileStamp`), so another
+ * version installed, or an edit of a source while developing it, makes every kept answer a miss.
+ *
+ * @param folders - the folders of the code that makes the answers.
+ * @param files - other files it depends on (the manifests of the parser, the compiler, the highlighter).
+ * @param since - when the stamp is taken; now unless a test says otherwise.
+ */
+export const codeStamp = (folders, files = [], since = nowNs()) => {
+    const hash = createHash("sha256");
+    for (const folder of [...new Set(folders)].sort()) {
+        const names = readdirSync(folder, { recursive: true, encoding: "utf8" }).sort();
+        for (const name of names)
+            hash.update(`${name}\0${codeFileStamp(join(folder, name), since)}\0`);
+    }
+    for (const file of [...new Set(files)].sort())
+        hash.update(`${file}\0${codeFileStamp(file, since)}\0`);
+    return hash.digest("hex");
+};
+/**
+ * The text of an entry's file, when it is a plain file of a size this cache writes.
+ *
+ * @param path - the entry's file.
+ */
+const entryText = (path) => {
+    const stats = lstatSync(path, { throwIfNoEntry: false });
+    if (stats === undefined || !stats.isFile() || stats.size > MOST_BYTES)
+        return undefined;
+    return readFileSync(path, "utf8");
+};
+/**
+ * Writes a file whole, in place of what was there: renamed into place, so a reader, or a server stopped halfway,
+ * never meets half a file; created anew, so a link left in the folder is not followed.
+ *
+ * @param path - the file.
+ * @param text - its text.
+ */
+const writeWhole = (path, text) => {
+    const partial = `${path}.${process.pid}.${Date.now()}`;
+    try {
+        const descriptor = openSync(partial, "wx");
+        try {
+            writeSync(descriptor, text);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        renameSync(partial, path);
+    }
+    catch {
+        // a cache that cannot be written is a slower next start; what was left half done goes
+        try {
+            unlinkSync(partial);
+        }
+        catch {
+            // never created
+        }
+    }
+};
+/**
+ * A cache in a folder.
+ *
+ * @param folder - the folder, created on the first write.
+ * @param code - the stamp of the code that makes the answers (`codeStamp`): another one is a miss.
+ * @param isValue - whether what was read is an answer: a file written by another version may hold anything.
+ */
+export const diskCache = (folder, code, isValue) => {
+    const path = (key) => join(folder, `${createHash("sha256").update(key).digest("hex").slice(0, 32)}.json`);
+    return {
+        read: (key) => {
+            try {
+                const text = entryText(path(key));
+                if (text === undefined)
+                    return undefined;
+                const entry = JSON.parse(text);
+                if (!isEntry(entry) || entry.code !== code)
+                    return undefined;
+                const isFresh = entry.paths.every(([name, stamp]) => stampOf(name)[1] === stamp);
+                return isFresh && isValue(entry.value) ? entry.value : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        write: (key, value, stamps) => {
+            const entry = { code, paths: stamps, value };
+            try {
+                mkdirSync(folder, { recursive: true });
+            }
+            catch {
+                return;
+            }
+            writeWhole(path(key), JSON.stringify(entry));
+        },
+        isEmpty: () => {
+            try {
+                return !readdirSync(folder).some((name) => name.endsWith(".json"));
+            }
+            catch {
+                return true;
+            }
+        }
+    };
+};