forgebook 0.3.2 → 0.4.0

package/dist/src/vite/typeParameters.js

@@ -0,0 +1,270 @@
+/**
+ * A generic component's props, written without the type parameters it leaves open: each one shown as its constraint,
+ * else its default, else `unknown`. Used by `propDocs.ts` and `propTypeNotes.ts`.
+ *
+ * @remarks
+ * A prop's text is the one its props type writes (`items: readonly T[]` in `ListProps<T>`), whose `T` is the props
+ * type's parameter, while what bounds it is the component's (`<TItem extends string>(props: ListProps<TItem>)`). The
+ * props type's parameters are followed to the types the component passes (`bindingsOf`), so the constraint shown is
+ * the component's. The replacement is made in the source's text, since the checker's instantiation is not public API.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/** How deep a type is walked: deep enough for a list of callbacks or a props type built on others; a recursive type ends. */
+const TYPE_DEPTH = 4;
+/** Whether a type is a generic's instance (`Array<TItem>`), whose type arguments the checker lists. */
+const isReference = (type) => (type.flags & ts.TypeFlags.Object) !== 0 && "target" in type;
+/** A type parameter's declaration, when the type is one. */
+const parameterOf = (type) => type.flags & ts.TypeFlags.TypeParameter
+    ? type.getSymbol()?.declarations?.find(ts.isTypeParameterDeclaration)
+    : undefined;
+/**
+ * What each type parameter of a props type stands for in this component: an alias's (`type P<T>`) and an interface's,
+ * its bases' included, through unions and intersections.
+ *
+ * @param propsType - the component's props type, as its signature takes it.
+ * @param checker - the program's checker.
+ */
+export const bindingsOf = (propsType, checker) => {
+    const bindings = new Map();
+    const visit = (type, depth) => {
+        if (depth === 0)
+            return;
+        for (const [parameter, bound] of typeArgumentsOf(type, checker)) {
+            if (!bindings.has(parameter))
+                bindings.set(parameter, bound);
+        }
+        const inner = type.isUnionOrIntersection() ? type.types : [];
+        const bases = isReference(type) && type.target.isClassOrInterface() ? checker.getBaseTypes(type.target) : [];
+        for (const each of [...inner, ...bases])
+            visit(each, depth - 1);
+    };
+    visit(propsType, TYPE_DEPTH);
+    return bindings;
+};
+/**
+ * The type arguments one type was made with, by the parameter each fills: an alias's (`P<TItem>`) and a generic
+ * interface's.
+ *
+ * @param type - the type.
+ * @param checker - the program's checker.
+ */
+const typeArgumentsOf = (type, checker) => {
+    const pairs = (parameters, types) => parameters.flatMap((parameter, index) => {
+        const bound = types[index];
+        return parameter === undefined || bound === undefined ? [] : [[parameter, bound]];
+    });
+    const alias = type.aliasSymbol?.declarations?.find(ts.isTypeAliasDeclaration);
+    const fromAlias = pairs(alias?.typeParameters ?? [], type.aliasTypeArguments ?? []);
+    if (!isReference(type))
+        return fromAlias;
+    return [
+        ...fromAlias,
+        ...pairs((type.target.typeParameters ?? []).map(parameterOf), checker.getTypeArguments(type))
+    ];
+};
+/**
+ * What a type parameter comes to, following the bindings from the props type's parameter to the component's.
+ *
+ * @param declaration - the type parameter a type writes.
+ * @param bindings - what the props type's parameters stand for.
+ */
+const resolved = (declaration, bindings) => {
+    const seen = new Set();
+    let current = declaration;
+    for (;;) {
+        const bound = bindings.get(current);
+        if (bound === undefined)
+            return { parameter: current };
+        const next = parameterOf(bound);
+        if (next === undefined)
+            return { type: bound };
+        if (next === current || seen.has(next))
+            return { parameter: next };
+        seen.add(current);
+        current = next;
+    }
+};
+/** Whether a node lies inside another. */
+const isWithin = (node, outer) => node.getSourceFile() === outer.getSourceFile() && node.pos >= outer.pos && node.end <= outer.end;
+/**
+ * Every type reference a node writes, in source order.
+ *
+ * @param node - the node.
+ */
+export const referencesIn = (node) => {
+    const found = [];
+    const visit = (each) => {
+        if (ts.isTypeReferenceNode(each))
+            found.push(each);
+        ts.forEachChild(each, visit);
+    };
+    visit(node);
+    return found;
+};
+/**
+ * The type parameters a node uses and does not declare itself (a function type's own `<T>` stays as written).
+ *
+ * @param node - the prop's declared type, or a constraint.
+ * @param checker - the program's checker.
+ */
+const parameterUses = (node, checker) => referencesIn(node).flatMap((reference) => {
+    const symbol = checker.getSymbolAtLocation(reference.typeName);
+    const declaration = symbol?.declarations?.find(ts.isTypeParameterDeclaration);
+    return declaration === undefined || isWithin(declaration, node) ? [] : [{ reference, declaration }];
+});
+/**
+ * Whether a prop's declared types name a type parameter of the props type: their text then says `TValue` where a props
+ * type the component instantiates (`BaseProps<string>`) means `string`.
+ *
+ * @param declared - the prop's declared types.
+ * @param checker - the program's checker.
+ */
+export const usesTypeParameter = (declared, checker) => declared.some((node) => parameterUses(node, checker).length > 0);
+/** What a type parameter is shown as: its constraint, else its default; none for `unknown`. */
+const shownAs = (declaration) => declaration.constraint ?? declaration.default;
+/** Whether a type written in a name's stead needs parentheses there (`readonly (A | B)[]`). */
+const needsParentheses = (reference, isLoose) => {
+    const { parent } = reference;
+    return (isLoose &&
+        (ts.isArrayTypeNode(parent) ||
+            ts.isIndexedAccessTypeNode(parent) ||
+            ts.isTypeOperatorNode(parent) ||
+            ts.isUnionTypeNode(parent) ||
+            ts.isIntersectionTypeNode(parent)));
+};
+/** Whether a type node binds looser than an array's element (a union, a function, a conditional, an operator). */
+const isLooseNode = (node) => ts.isUnionTypeNode(node) ||
+    ts.isIntersectionTypeNode(node) ||
+    ts.isFunctionTypeNode(node) ||
+    ts.isConstructorTypeNode(node) ||
+    ts.isConditionalTypeNode(node) ||
+    ts.isTypeOperatorNode(node);
+/**
+ * The text that replaces a type parameter: the type the component gives it, or the component's own parameter's
+ * constraint or default as written, `unknown` when it has neither.
+ *
+ * @param use - the type parameter's use.
+ * @param generics - the checker and the bindings.
+ * @param seen - the type parameters being replaced, so a constraint naming its own parameter ends.
+ */
+const replacementText = ({ reference, declaration }, generics, seen) => {
+    const target = resolved(declaration, generics.bindings);
+    if (target.type !== undefined) {
+        const text = generics.checker.typeToString(target.type);
+        return needsParentheses(reference, target.type.isUnionOrIntersection()) ? `(${text})` : text;
+    }
+    const node = shownAs(target.parameter);
+    if (node === undefined)
+        return "unknown";
+    // a constraint may name another type parameter (`TName extends FieldPath<TValues>`): it is replaced too, once
+    const text = seen.has(target.parameter)
+        ? target.parameter.name.text
+        : genericFreeText(node, generics, new Set([...seen, target.parameter]));
+    return needsParentheses(reference, isLooseNode(node)) ? `(${text})` : text;
+};
+/**
+ * A node's source text with each type parameter it uses replaced by what it is shown as.
+ *
+ * @param node - the prop's declared type (or one member of it), or a constraint.
+ * @param generics - the checker and the bindings.
+ * @param seen - the type parameters being replaced.
+ * @returns the text, as `getText()` would give it with the replacements made.
+ */
+export const genericFreeText = (node, generics, seen = new Set()) => {
+    const text = node.getSourceFile().text;
+    let written = "";
+    let at = node.getStart();
+    for (const use of parameterUses(node, generics.checker)) {
+        written += text.slice(at, use.reference.getStart()) + replacementText(use, generics, seen);
+        at = use.reference.getEnd();
+    }
+    return written + text.slice(at, node.getEnd());
+};
+/**
+ * The type a prop typed by a type parameter is shown as (`selected?: TKey`): what decides its kind and control. Read
+ * from the checker's type, whose parameter is the component's own.
+ *
+ * @param type - the prop's type, as the component takes it.
+ * @param checker - the program's checker.
+ * @param depth - how many defaults naming another parameter are followed.
+ * @returns the type, or none when the prop's type is not a type parameter.
+ */
+export const genericShownType = (type, checker, depth = TYPE_DEPTH) => {
+    // `T | undefined` for an optional prop, `T & {}` once `undefined` is taken away
+    const members = (type.isUnionOrIntersection() ? type.types : [type]).filter((member) => (member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Null)) === 0);
+    const declarations = members.flatMap((member) => parameterOf(member) ?? []);
+    const [declaration] = declarations;
+    if (declaration === undefined || declarations.length !== 1)
+        return undefined;
+    if (type.isUnion() && members.length !== 1)
+        return undefined;
+    const node = shownAs(declaration);
+    if (node === undefined)
+        return checker.getUnknownType();
+    const shown = checker.getTypeFromTypeNode(node);
+    return depth > 0 ? (genericShownType(shown, checker, depth - 1) ?? shown) : shown;
+};
+/**
+ * Whether a type, as the component takes it, still holds a type parameter: `readonly TItem[]` in a generic component,
+ * not the `readonly string[]` of a props type it instantiates (`BaseProps<string>`). Through unions, intersections, a
+ * generic's arguments and a function's parameters and result.
+ *
+ * @param type - the prop's type.
+ * @param checker - the program's checker.
+ * @param depth - how many levels are left to look into.
+ */
+export const hasTypeParameter = (type, checker, depth = TYPE_DEPTH) => {
+    if (type.flags & ts.TypeFlags.TypeParameter)
+        return true;
+    if (depth === 0)
+        return false;
+    const inner = (each) => hasTypeParameter(each, checker, depth - 1);
+    if (type.isUnionOrIntersection())
+        return type.types.some(inner);
+    if ((type.aliasTypeArguments ?? []).some(inner))
+        return true;
+    if (isReference(type) && checker.getTypeArguments(type).some(inner))
+        return true;
+    return type
+        .getCallSignatures()
+        .some((signature) => inner(signature.getReturnType()) ||
+        signature.getParameters().some((parameter) => inner(checker.getTypeOfSymbol(parameter))));
+};
+/**
+ * What a component's type parameter is shown as, as a prop's note says it.
+ *
+ * @param declaration - the component's type parameter.
+ * @param generics - the checker and the bindings.
+ */
+const genericNote = (declaration, generics) => {
+    const parameter = declaration.name.text;
+    const seen = new Set([declaration]);
+    if (declaration.constraint !== undefined) {
+        const type = genericFreeText(declaration.constraint, generics, seen);
+        return { reason: "generic", parameter, shownAs: "constraint", type };
+    }
+    if (declaration.default !== undefined) {
+        const type = genericFreeText(declaration.default, generics, seen);
+        return { reason: "generic", parameter, shownAs: "default", type };
+    }
+    return { reason: "generic", parameter, shownAs: "unknown", type: "unknown" };
+};
+/**
+ * The notes of the type parameters a prop's declared types leave open, each once, by the component's name for it.
+ *
+ * @param declared - the prop's declared types.
+ * @param generics - the checker and the bindings.
+ */
+export const genericNotes = (declared, generics) => {
+    const notes = new Map();
+    for (const node of declared) {
+        for (const { declaration } of parameterUses(node, generics.checker)) {
+            const { parameter } = resolved(declaration, generics.bindings);
+            if (parameter !== undefined && !notes.has(parameter))
+                notes.set(parameter, genericNote(parameter, generics));
+        }
+    }
+    return [...notes.values()];
+};

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

@@ -0,0 +1,37 @@
+/**
+ * The props of a component whose props are a union of variants (`{ kind: "link"; href } | { kind: "button"; onClick }`):
+ * every variant's props, not only the ones all variants share, each prop only some variants declare with the
+ * discriminant's values that select them. Used by `functionComponentDocs.ts`.
+ *
+ * @remarks
+ * The checker lists a union's properties as those every member has, so a variant's own props vanished from the docs
+ * with no sign. A prop only some variants declare is never required: whether it must be passed depends on the variant.
+ * The discriminant is a prop every variant declares with one literal value (`kind: "link"`) or leaves out; a prop of a
+ * variant that takes it left out (`mode?: "single"`) applies then too. A union without one lists its variants' props
+ * with no condition. A prop declared by several variants takes all their types.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+import type { PropCondition } from "../componentDocs.ts";
+/** A prop only some variants of a union of props declare. */
+export type VariantProp = {
+    /** When it can be passed; none when the union has no discriminant. */
+    readonly onlyWhen: PropCondition | undefined;
+    /** The same prop as each variant that declares it has it, the first included: their types together are its type. */
+    readonly declarations: readonly ts.Symbol[];
+};
+/** The props of a component's props type. */
+export type TypeProps = {
+    /** Every prop, of every variant, each once: the shared ones first, then each variant's own in the order they come. */
+    readonly props: readonly ts.Symbol[];
+    /** The props only some variants declare, by the symbol `props` lists for each. */
+    readonly variantOnly: ReadonlyMap<ts.Symbol, VariantProp>;
+};
+/**
+ * A component's props, read from its props type: a plain type's own, or every variant's of a union.
+ *
+ * @param propsType - the type of its props, without `undefined`.
+ * @param checker - the program's checker.
+ */
+export declare const propsOfType: (propsType: ts.Type, checker: ts.TypeChecker) => TypeProps;

package/dist/src/vite/unionProps.js

@@ -0,0 +1,121 @@
+/**
+ * The props of a component whose props are a union of variants (`{ kind: "link"; href } | { kind: "button"; onClick }`):
+ * every variant's props, not only the ones all variants share, each prop only some variants declare with the
+ * discriminant's values that select them. Used by `functionComponentDocs.ts`.
+ *
+ * @remarks
+ * The checker lists a union's properties as those every member has, so a variant's own props vanished from the docs
+ * with no sign. A prop only some variants declare is never required: whether it must be passed depends on the variant.
+ * The discriminant is a prop every variant declares with one literal value (`kind: "link"`) or leaves out; a prop of a
+ * variant that takes it left out (`mode?: "single"`) applies then too. A union without one lists its variants' props
+ * with no condition. A prop declared by several variants takes all their types.
+ *
+ * @module
+ */
+import ts from "typescript-6";
+/**
+ * A discriminant's value in one variant: the literal its type is, `null` when the variant leaves it out
+ * (`mode?: undefined`), none when its type is anything else.
+ */
+const literalOf = (type, checker) => {
+    if (type.isStringLiteral() || type.isNumberLiteral())
+        return type.value;
+    if (type.flags & ts.TypeFlags.BooleanLiteral)
+        return checker.typeToString(type) === "true";
+    return type.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never) ? null : undefined;
+};
+/**
+ * A prop's value in one variant, when it can discriminate: one literal, or left out.
+ *
+ * @param variant - the variant.
+ * @param name - the prop.
+ * @param checker - the program's checker.
+ */
+const variantValueOf = (variant, name, checker) => {
+    const member = checker.getPropertyOfType(variant, name);
+    if (member === undefined)
+        return undefined;
+    const type = checker.getTypeOfSymbol(member);
+    const value = literalOf(checker.getNonNullableType(type), checker);
+    if (value === undefined)
+        return undefined;
+    const canBeOmitted = (member.flags & ts.SymbolFlags.Optional) !== 0 ||
+        (type.isUnion() && type.types.some((each) => (each.flags & ts.TypeFlags.Undefined) !== 0));
+    return { value, canBeOmitted };
+};
+/**
+ * The discriminant of a union of props: among the shared props each variant declares with one literal value or leaves
+ * out, the one with the most different values (`mode` over `required` in a date picker's props), the first on a tie.
+ *
+ * @param shared - the props every variant declares.
+ * @param variants - the union's members.
+ * @param checker - the program's checker.
+ * @returns the discriminant, or none when the union has none.
+ */
+const discriminantOf = (shared, variants, checker) => {
+    let best;
+    for (const prop of shared) {
+        const name = prop.getName();
+        const values = variants.map((variant) => variantValueOf(variant, name, checker));
+        if (!values.every((value) => value !== undefined))
+            continue;
+        const count = new Set(values.flatMap(({ value }) => (value === null ? [] : [value]))).size;
+        if (count > 1 && (best === undefined || count > best.count)) {
+            best = { discriminant: { name, variants: values }, count };
+        }
+    }
+    return best?.discriminant;
+};
+/**
+ * Notes one variant's declaration of a prop: its symbol, and the discriminant's value there.
+ *
+ * @param entry - the prop, as read so far.
+ * @param prop - its symbol in this variant.
+ * @param at - the discriminant in this variant; none when the union has none.
+ */
+const record = (entry, prop, at) => {
+    entry.declarations.push(prop);
+    if (at === undefined)
+        return;
+    if (at.canBeOmitted || at.value === null)
+        entry.canBeOmitted = true;
+    if (at.value !== null && !entry.values.includes(at.value))
+        entry.values.push(at.value);
+};
+/**
+ * A component's props, read from its props type: a plain type's own, or every variant's of a union.
+ *
+ * @param propsType - the type of its props, without `undefined`.
+ * @param checker - the program's checker.
+ */
+export const propsOfType = (propsType, checker) => {
+    const shared = propsType.getProperties();
+    if (!propsType.isUnion())
+        return { props: shared, variantOnly: new Map() };
+    const variants = propsType.types;
+    const sharedNames = new Set(shared.map((prop) => prop.getName()));
+    const discriminant = discriminantOf(shared, variants, checker);
+    const own = new Map();
+    variants.forEach((variant, index) => {
+        const at = discriminant?.variants[index];
+        for (const prop of variant.getProperties()) {
+            const name = prop.getName();
+            if (sharedNames.has(name))
+                continue;
+            const entry = own.get(name) ?? { declarations: [], values: [], canBeOmitted: false };
+            own.set(name, entry);
+            record(entry, prop, at);
+        }
+    });
+    const variantOnly = new Map();
+    for (const { declarations, values, canBeOmitted } of own.values()) {
+        const [first] = declarations;
+        if (first === undefined)
+            continue;
+        const onlyWhen = discriminant === undefined
+            ? undefined
+            : { prop: discriminant.name, values, ...(canBeOmitted ? { orOmitted: true } : {}) };
+        variantOnly.set(first, { onlyWhen, declarations });
+    }
+    return { props: [...shared, ...variantOnly.keys()], variantOnly };
+};

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

@@ -0,0 +1,20 @@
+import { type ReadConfig, type ReadSheet } from "./appTokenFiles.ts";
+import type { TokenDeclaration } from "./cssTokenValues.ts";
+/** What the check found. */
+export type UnresolvedTokens = {
+    /** Tokens with no value, one line each with its file and line. */
+    readonly problems: readonly string[];
+    /** Tokens that may have no value, where what declares the name could not all be read. */
+    readonly unread: readonly string[];
+};
+/**
+ * Finds the tokens that resolve to nothing.
+ *
+ * @param dir - the catalogue's folder, its links followed.
+ * @param read - the sheets and configurations read, and the declarations tokens are made from, the lowest first.
+ */
+export declare const unresolvedTokens: (dir: string, read: {
+    readonly sheets: readonly ReadSheet[];
+    readonly configs: readonly ReadConfig[];
+    readonly declarations: readonly TokenDeclaration[];
+}) => UnresolvedTokens;

package/dist/src/vite/unresolvedTokens.js

@@ -0,0 +1,193 @@
+/**
+ * The tokens of an application's sheets that a browser gives no value, as problems: a reference that leads back to
+ * itself, or one to a name nothing declares.
+ *
+ * @remarks
+ * A token that resolves to nothing draws the UI with no colour or no size, and nothing else says so: the browser drops the
+ * declaration in silence. A cycle in the base is always a problem. A name the sheets do not declare may still get a value:
+ * another rule declares it, `@property` registers it, an installed package's sheet does, or code sets it (`next/font`
+ * writes `--font-geist-sans` on the page's element). So the names every sheet read declares count, those of the packages
+ * the sheets import count, and so does a name the repository's files write as code sets one: in quotes, as a declaration
+ * (`--gap:` in a template, a `.vue` style block, a sheet not read), a Svelte `style:` directive, a Tailwind arbitrary
+ * property. When that cannot all be known (a package's sheet that cannot be read, a sheet that builds names with Sass or
+ * Less, the files that cannot be searched), or when a cycle exists only inside a theme, which depends on the element the
+ * theme is set on, the line is something not read, which fails nothing, and never a problem that might be false. The
+ * repository is searched only for names already found missing, so an answer with none reads nothing more.
+ *
+ * @module
+ */
+import { spawnSync } from "node:child_process";
+import { importedPackageSheets, repositoryOf } from "./appTokenFiles.js";
+import { readCssText } from "./cssDeclarations.js";
+import { brokenReferences } from "./cssReferences.js";
+/** The files a custom property is set in, by code or by a sheet this does not read as the application's system. */
+const SEARCHED_FILES = [
+    "*.js",
+    "*.jsx",
+    "*.mjs",
+    "*.cjs",
+    "*.ts",
+    "*.tsx",
+    "*.mts",
+    "*.cts",
+    "*.vue",
+    "*.svelte",
+    "*.astro",
+    "*.html",
+    "*.css",
+    "*.scss",
+    "*.sass",
+    "*.less",
+    "*.pcss",
+    "*.postcss"
+];
+/** How long git may take to search the repository, in milliseconds. */
+const SEARCH_TIMEOUT = 10_000;
+/** How many names a line gives, of a cycle or of tokens that could not be told: past a few, they say nothing more. */
+const MOST_NAMED = 5;
+/** A name built by Sass or Less interpolation (`--#{$key}`, `--@{key}`), which no reading of the text can know. */
+const BUILT_NAME = /--(?:#\{|@\{)/;
+/** A custom property `@property` registers: it has its initial value wherever nothing else sets it. */
+const REGISTERED = /@property\s+(--[\w-]+)/g;
+/**
+ * The names of custom properties sheets declare. A cleared one (`initial`) gives no value, and one that only reads its own
+ * name (Tailwind's `@theme inline { --font-sans: var(--font-sans); }`) takes its value from elsewhere.
+ */
+const declaredNames = (readings, texts) => {
+    const declared = new Set(readings.flatMap(({ declarations }) => declarations.flatMap(({ name, value }) => (isOwnReference(name, value) ? [] : [name]))));
+    for (const text of texts)
+        for (const [, name = ""] of text.matchAll(REGISTERED))
+            declared.add(name);
+    return declared;
+};
+/** Whether a value gives no value of its own: cleared, or reading only its own name. */
+const isOwnReference = (name, value) => value === "initial" || value.replace(/\s/g, "") === `var(${name})`;
+/**
+ * Whether a line of a file sets a name: in quotes (`variable: "--font-sans"`, `style={{ "--gap": … }}`,
+ * `setProperty("--gap", …)`), as a declaration (`--gap: 4px`) that is not only its own name, a Svelte `style:` directive
+ * or a Tailwind arbitrary property (`[--gap:4px]`). A reference is `var(--gap)`, which none of these match.
+ */
+const setsName = (line, name) => {
+    if ([`"${name}"`, `'${name}'`, `\`${name}\``, `style:${name}=`, `[${name}:`].some((form) => line.includes(form))) {
+        return true;
+    }
+    const at = line.indexOf(`${name}:`);
+    if (at === -1)
+        return false;
+    const value = line.slice(at + name.length + 1).split(/[;}]/)[0] ?? "";
+    return !isOwnReference(name, value.trim());
+};
+/**
+ * The names among some that the repository's files set, searched as fixed strings, which git matches all at once where
+ * a pattern per name takes seconds; the strings go on its input, since a command line has a limit on Windows. None when
+ * the files cannot be searched.
+ */
+const namesSetIn = (root, names) => {
+    // a repository's configuration may name a program for git to run: nothing here is to run
+    const found = spawnSync("git", [
+        "-c",
+        "core.fsmonitor=false",
+        "grep",
+        "--untracked",
+        "-I",
+        "-h",
+        "-F",
+        "-f",
+        "-",
+        "--",
+        ...SEARCHED_FILES
+    ], {
+        cwd: root,
+        input: names.join("\n"),
+        encoding: "utf8",
+        timeout: SEARCH_TIMEOUT,
+        maxBuffer: 64 * 1024 * 1024
+    });
+    if (found.status === 1)
+        return new Set();
+    if (found.status !== 0)
+        return undefined;
+    const lines = found.stdout.split("\n");
+    return new Set(names.filter((name) => lines.some((line) => line.includes(name) && setsName(line, name))));
+};
+/** Where a declaration stands, for a line that names it. */
+const placeOf = ({ origin }) => origin.line === undefined ? origin.file : `${origin.file}:${origin.line}`;
+/** What is wrong with a declaration, without where. */
+const whatOf = (broken) => {
+    const { name } = broken.declaration;
+    if (broken.kind === "undeclared")
+        return `${name} reads var(${broken.target})`;
+    const shown = broken.through.slice(0, MOST_NAMED);
+    const more = broken.through.length - shown.length;
+    const names = more > 0 ? `${shown.join(", ")} and ${more} more` : shown.join(", ");
+    const theme = broken.mode === undefined ? "" : ` in the ${broken.mode} theme`;
+    return `${name} leads back to ${shown.length === 0 ? "itself" : `itself through ${names}`}${theme}`;
+};
+/** A problem's line. */
+const problemOf = (broken) => {
+    const at = placeOf(broken.declaration);
+    if (broken.kind === "cycle")
+        return `${at}: ${whatOf(broken)}, so a browser gives it no value`;
+    return `${at}: ${whatOf(broken)}, which nothing declares, so a browser gives it no value: declare ${broken.target} or give it a fallback`;
+};
+/**
+ * What could not be told for one reason, one line a token, or one line in all past a few: an application whose
+ * dependencies are not installed has hundreds, and each says the same.
+ */
+const unsureLines = (unsure, why) => {
+    if (unsure.length <= MOST_NAMED)
+        return unsure.map((each) => `${placeOf(each.declaration)}: ${whatOf(each)}: ${why}`);
+    const shown = unsure.slice(0, MOST_NAMED).map(whatOf).join("; ");
+    return [
+        `${unsure.length} tokens may have no value (${shown}; and ${unsure.length - MOST_NAMED} more): ${why}`
+    ];
+};
+/** Why a name nothing read declares cannot be called missing; none when it can. */
+const doubtOf = (unreadable, hasBuiltNames, setInFiles) => {
+    if (setInFiles === undefined)
+        return "nothing read declares it, and the repository could not be searched for it";
+    if (hasBuiltNames)
+        return "nothing read declares it, and a sheet builds names with Sass or Less, which only running it knows";
+    if (unreadable.length > 0) {
+        const named = unreadable.map((each) => `"${each}"`).join(", ");
+        return `nothing read declares it; it may come from ${named}, which could not be read`;
+    }
+    return undefined;
+};
+/**
+ * Finds the tokens that resolve to nothing.
+ *
+ * @param dir - the catalogue's folder, its links followed.
+ * @param read - the sheets and configurations read, and the declarations tokens are made from, the lowest first.
+ */
+export const unresolvedTokens = (dir, read) => {
+    const packages = importedPackageSheets(dir, read.sheets);
+    const declared = declaredNames([...read.sheets.map(({ reading }) => reading), ...packages.texts.map((text) => readCssText(text))], [...read.sheets.map(({ text }) => text), ...packages.texts]);
+    for (const { reading } of read.configs)
+        for (const { name } of reading.tokens)
+            declared.add(name);
+    const broken = brokenReferences(read.declarations, (name) => declared.has(name)).filter(({ declaration }) => declaration.origin.kind !== "tailwind-default");
+    const missing = [...new Set(broken.flatMap((each) => (each.kind === "undeclared" ? [each.target] : [])))];
+    const setInFiles = missing.length === 0 ? new Set() : namesSetIn(repositoryOf(dir), missing);
+    const hasBuiltNames = read.sheets.some(({ text }) => BUILT_NAME.test(text));
+    const doubt = doubtOf(packages.unreadable, hasBuiltNames, setInFiles);
+    const problems = [];
+    const inTheme = [];
+    const doubted = [];
+    for (const each of broken) {
+        if (each.kind === "cycle" && each.mode !== undefined)
+            inTheme.push(each);
+        else if (each.kind === "cycle" || (doubt === undefined && setInFiles?.has(each.target) !== true)) {
+            problems.push(problemOf(each));
+        }
+        else if (setInFiles?.has(each.target) !== true)
+            doubted.push(each);
+    }
+    return {
+        problems,
+        unread: [
+            ...unsureLines(inTheme, "a browser gives it no value if the theme is set on the root, as its base is"),
+            ...(doubt === undefined ? [] : unsureLines(doubted, doubt))
+        ]
+    };
+};