@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/tokens/add.js

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Adding a design token to the token file: a declaration in its category in
+ * the base `:root` block and, for `override`, in the dark-mode and
+ * theme-attribute blocks; or, with a variant, a declaration in the
+ * `:root<variant>` block. Every function works on text.
+ */
+import { usageError } from '../cli/command.js';
+import { FireForgeError } from '../kernel/errors.js';
+import { parseCss } from '../syntax/index.js';
+import { appendToBlock, baseRoot, declarationsIn, isolateClose } from './css.js';
+import { categories } from './model.js';
+/** How a token behaves in dark mode: it follows the platform, never changes, or has its own dark value. */
+export const TOKEN_MODES = ['auto', 'static', 'override'];
+/**
+ * The full custom property name for a name as typed. A bare name takes the
+ * project's token prefix unless it already starts with it.
+ *
+ * @param raw - `--name` or a bare name
+ * @param prefix - The project's token prefix (`--brand-`), if it has one
+ * @throws `invalid-argument` for a name that cannot be written as a custom property
+ */
+export function tokenName(raw, prefix) {
+    const ident = raw.replace(/^--/, '');
+    let problem;
+    if (ident === '')
+        problem = 'must not be empty';
+    else if (/[\s\p{Cc}]/u.test(ident))
+        problem = 'must not contain whitespace or control characters';
+    else if (!/^[-_a-zA-Z0-9\u0080-\u{10ffff}]+$/u.test(ident)) {
+        problem = 'must use only letters, digits, hyphens and underscores';
+    }
+    if (problem !== undefined)
+        throw usageError(`Token name "${raw}" ${problem}.`);
+    if (raw.startsWith('--') || prefix === undefined)
+        return `--${ident}`;
+    const bare = prefix.replace(/^--/, '').replace(/-$/, '');
+    return ident === bare || ident.startsWith(`${bare}-`) ? `--${ident}` : `--${bare}-${ident}`;
+}
+/** Why `text` cannot be one declaration's value, or undefined. */
+function valueProblem(text) {
+    if (/[\r\n]/.test(text))
+        return 'must be a single line';
+    let quote;
+    let depth = 0;
+    for (let i = 0; i < text.length; i++) {
+        const char = text.charAt(i);
+        if (quote !== undefined) {
+            if (char === '\\')
+                i++;
+            else if (char === quote)
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'")
+            quote = char;
+        else if (char === '(')
+            depth++;
+        else if (char === ')')
+            depth--;
+        else if (char === '{' || char === '}')
+            return `must not contain "${char}" outside a string`;
+        else if (char === ';' && depth <= 0)
+            return 'must not contain ";" outside a string or ()';
+        else if (char === '/' && text.charAt(i + 1) === '*')
+            return 'must not contain a comment';
+        if (depth < 0)
+            return 'has an unbalanced ")"';
+    }
+    if (quote !== undefined)
+        return 'has an unterminated string';
+    return depth === 0 ? undefined : 'has an unbalanced "("';
+}
+const ATTRIBUTE = String.raw `\[[a-zA-Z][\w-]*(?:=(?:"[\w-]+"|'[\w-]+'|[\w-]+))?\]`;
+const VARIANT = new RegExp(`^(?:${ATTRIBUTE})+(?::[a-zA-Z][\\w-]*(?:\\((?:${ATTRIBUTE})+\\))?)?$`);
+/**
+ * Checks a variant selector fragment and writes its attribute values in the
+ * quoted form: `[data-skin=x]` becomes `[data-skin="x"]`.
+ */
+function normalizeVariant(raw) {
+    const value = raw.trim();
+    if (!VARIANT.test(value)) {
+        throw usageError(`--variant "${raw}" must be attribute selectors such as [data-private] or [data-skin=precision], ` +
+            'optionally followed by a pseudo-class such as :not([data-private]).');
+    }
+    return value.replace(/=(?:'([\w-]+)'|([\w-]+))\]/g, (_all, quoted, bare) => `="${quoted ?? bare}"]`);
+}
+function checkRequest(request) {
+    for (const [label, text] of [
+        ['value', request.value],
+        ['dark value', request.darkValue],
+    ]) {
+        const problem = text === undefined ? undefined : valueProblem(text);
+        if (problem !== undefined)
+            throw usageError(`Token ${label} "${text ?? ''}" ${problem}.`);
+    }
+    if (request.description !== undefined && /[\r\n]|\*\//.test(request.description)) {
+        throw usageError('Token description must be one line without "*/".');
+    }
+    if (request.mode === 'override' && request.darkValue === undefined) {
+        throw usageError('--mode override needs --dark-value.');
+    }
+    if (request.mode !== 'override' && request.darkValue !== undefined) {
+        throw usageError('--dark-value applies to --mode override only.');
+    }
+    if (request.variant === undefined) {
+        if (request.category === undefined || request.category.trim() === '') {
+            throw usageError('A token is declared in a category, so --category is required.', 'Pass --variant <selector> to add to a :root<selector> block instead.');
+        }
+        return undefined;
+    }
+    if (request.mode === 'override' || request.createCategory === true) {
+        throw usageError('--variant cannot be combined with --mode override or --create-category.', 'Add the base token first, then add each variant.');
+    }
+    return normalizeVariant(request.variant);
+}
+function annotation(mode, value) {
+    if (mode === 'override')
+        return 'override';
+    if (mode === 'auto')
+        return value.includes('light-dark(') ? 'auto (light-dark)' : 'auto';
+    return value.startsWith('var(--') ? 'static' : 'static, fork-specific';
+}
+function canonical(selector) {
+    return selector.replace(/\s+/g, '').replace(/["']/g, '');
+}
+function noTokenFile() {
+    return new FireForgeError('token-file-invalid', 'The token file has no :root block that closes.', {
+        hint: 'Restore the :root block of the token file.',
+    });
+}
+/** The category name at a zero-based line, or undefined. */
+function categoryAt(sheet, line) {
+    return categories(sheet).find((section) => line > section.line && line < section.end)?.name;
+}
+function unknownCategory(sheet, name) {
+    const known = categories(sheet).map((section) => `"${section.name}"`);
+    return new FireForgeError('token-category-missing', `Category "${name}" not found in the token file.\n\n` +
+        (known.length > 0
+            ? `Categories: ${known.join(', ')}.`
+            : 'The file has no category banners.') +
+        '\n\nBanners are comments inside :root, such as /* = My Category = */. ' +
+        'Pass --create-category to declare one.');
+}
+/** The top-level `:root<attributes>` block whose attribute run is `variant`, with any qualifier when `anyQualifier`. */
+function variantBlock(sheet, variant, anyQualifier) {
+    const wanted = canonical(`:root${variant}`);
+    return sheet.blocks.find((block) => {
+        if (block.parent !== undefined)
+            return false;
+        const own = canonical(block.selector);
+        if (own === wanted)
+            return true;
+        if (!anyQualifier)
+            return false;
+        const attributes = /^:root(?:\[[^\]]+\])*/.exec(block.selector)?.[0];
+        return attributes !== undefined && canonical(attributes) === wanted;
+    });
+}
+function addVariant(text, request, variant) {
+    const sheet = parseCss(text);
+    const block = variantBlock(sheet, variant, false);
+    const where = `:root${variant}`;
+    const existing = block === undefined
+        ? undefined
+        : declarationsIn(sheet, block).find((declaration) => declaration.name === request.name);
+    if (existing !== undefined) {
+        return {
+            text,
+            changed: false,
+            existing: { line: existing.line + 1, where },
+            categoryCreated: false,
+            mirrored: [],
+            notes: [],
+        };
+    }
+    const declaration = `  ${request.name}: ${request.value}; /* ${annotation(request.mode, request.value)} */`;
+    const lines = sheet.lines;
+    if (block !== undefined) {
+        appendToBlock(lines, block, [declaration]);
+    }
+    else {
+        const root = baseRoot(sheet);
+        lines.splice(root === undefined || root.close === -1 ? lines.length : root.close + 1, 0, '', `${where} {`, declaration, '}');
+    }
+    return { text: lines.join('\n'), changed: true, categoryCreated: false, mirrored: [], notes: [] };
+}
+/** Writes the dark value into the nested `:root` of the dark `@media` block, creating what is missing. */
+function addDarkValue(text, name, value) {
+    const sheet = parseCss(text);
+    const media = sheet.blocks.find((block) => block.parent === undefined && /^@media\b.*prefers-color-scheme:\s*dark/.test(block.selector));
+    const lines = sheet.lines;
+    if (media === undefined || media.close === -1) {
+        while (lines.length > 0 && (lines.at(-1) ?? '').trim() === '')
+            lines.pop();
+        lines.push('', '@media (prefers-color-scheme: dark) {', '  :root {', `    ${name}: ${value};`, '  }', '}', '');
+        return lines.join('\n');
+    }
+    const nested = sheet.blocks.find((block) => block.parent === media && block.selector.split(',').some((part) => part.trim() === ':root'));
+    if (nested !== undefined && nested.close !== -1)
+        appendToBlock(lines, nested, [`    ${name}: ${value};`]);
+    else
+        appendToBlock(lines, media, ['  :root {', `    ${name}: ${value};`, '  }']);
+    return lines.join('\n');
+}
+/**
+ * Mirrors an override into the `:root[data-theme="dark"]` and
+ * `:root[data-theme="light"]` blocks the file already has, so every themed
+ * list declares the same tokens. A block with a qualifier (`:not(...)`) is
+ * written too, and reported.
+ */
+function mirrorThemes(text, request) {
+    const written = [];
+    const notes = [];
+    let current = text;
+    for (const [variant, value] of [
+        ['[data-theme="dark"]', request.darkValue ?? request.value],
+        ['[data-theme="light"]', request.value],
+    ]) {
+        const sheet = parseCss(current);
+        const block = variantBlock(sheet, variant, true);
+        if (block === undefined || block.close === -1)
+            continue;
+        if (declarationsIn(sheet, block).some((declaration) => declaration.name === request.name))
+            continue;
+        appendToBlock(sheet.lines, block, [`  ${request.name}: ${value};`]);
+        current = sheet.lines.join('\n');
+        written.push(block.selector);
+        const qualifier = block.selector.slice(`:root${variant}`.length);
+        if (canonical(qualifier) !== '') {
+            notes.push(`Wrote ${request.name} into "${block.selector}"; its "${qualifier}" qualifier narrows where the override applies.`);
+        }
+    }
+    return { text: current, written, notes };
+}
+function addBase(text, request) {
+    const category = request.category ?? '';
+    let sheet = parseCss(text);
+    const root = baseRoot(sheet);
+    if (root === undefined || root.close === -1)
+        throw noTokenFile();
+    const present = declarationsIn(sheet, root).find((declaration) => declaration.name === request.name);
+    if (present !== undefined) {
+        const where = categoryAt(sheet, present.line);
+        if (where === category) {
+            return {
+                text,
+                changed: false,
+                existing: { line: present.line + 1, where: `category "${category}"` },
+                categoryCreated: false,
+                mirrored: [],
+                notes: [],
+            };
+        }
+        throw new FireForgeError('token-exists', `Token "${request.name}" is already declared outside category "${category}" (line ${present.line + 1}${where === undefined ? '' : `, category "${where}"`}). ` +
+            'A token belongs to one category.', {
+            hint: where === undefined
+                ? 'Remove the stray declaration first.'
+                : `Pass --category "${where}", or remove it first.`,
+        });
+    }
+    let categoryCreated = false;
+    if (!categories(sheet).some((section) => section.name === category)) {
+        if (request.createCategory !== true)
+            throw unknownCategory(sheet, category);
+        const lines = sheet.lines;
+        lines.splice(isolateClose(lines, root), 0, '', `  /* = ${category} = */`);
+        sheet = parseCss(lines.join('\n'));
+        categoryCreated = true;
+    }
+    const section = categories(sheet).find((candidate) => candidate.name === category);
+    if (section === undefined)
+        throw unknownCategory(sheet, category);
+    const lines = sheet.lines;
+    let at = section.end;
+    for (let i = section.end - 1; i > section.line; i--) {
+        if ((lines[i] ?? '').trim() !== '') {
+            at = i + 1;
+            break;
+        }
+    }
+    lines.splice(at, 0, ...(request.description === undefined ? [] : [`  /* ${request.description} */`]), `  ${request.name}: ${request.value}; /* ${annotation(request.mode, request.value)} */`);
+    let result = lines.join('\n');
+    let mirrored = [];
+    let notes = [];
+    if (request.mode === 'override' && request.darkValue !== undefined) {
+        result = addDarkValue(result, request.name, request.darkValue);
+        const themed = mirrorThemes(result, request);
+        ({ text: result, written: mirrored, notes } = themed);
+    }
+    return { text: result, changed: true, categoryCreated, mirrored, notes };
+}
+/**
+ * Adds a token to the token file's text.
+ *
+ * @param text - The token file
+ * @param request - The token
+ * @throws `invalid-argument` for a request that cannot be written as CSS;
+ *   `token-category-missing`, `token-exists` or `token-file-invalid` for a file that cannot take it
+ */
+export function addToken(text, request) {
+    const variant = checkRequest(request);
+    return variant === undefined ? addBase(text, request) : addVariant(text, request, variant);
+}

package/dist/src/tokens/coverage.js

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Token coverage of the owned stylesheets: how many of their values come
+ * from a project token and how many are raw colors or custom properties
+ * that belong to nobody the project knows.
+ */
+import { cssVarReferences, customProperties, parseCss, rawColors } from '../syntax/index.js';
+import {} from './settings.js';
+function measure(file, css, settings) {
+    const sheet = parseCss(css);
+    const entry = {
+        file,
+        tokenUsages: 0,
+        allowlisted: 0,
+        unknownVars: 0,
+        rawColors: 0,
+    };
+    for (const { name } of cssVarReferences(sheet)) {
+        if (name.startsWith(settings.prefix))
+            entry.tokenUsages++;
+        else if (settings.exempt.has(name) ||
+            settings.platformPrefixes.some((prefix) => name.startsWith(prefix))) {
+            entry.allowlisted++;
+        }
+        else
+            entry.unknownVars++;
+    }
+    entry.rawColors = rawColors(sheet).length;
+    return entry;
+}
+/**
+ * Measures the owned stylesheets other than the token file, which is judged
+ * only for declarations outside the project prefix.
+ *
+ * @param tokenFile - Engine path of the token file
+ * @param owned - The project's owned files
+ * @param settings - The project's token conventions
+ */
+export async function measureCoverage(tokenFile, owned, settings) {
+    const files = [];
+    for (const path of owned.paths.filter((p) => p.endsWith('.css') && p !== tokenFile).sort()) {
+        const css = await owned.read(path);
+        if (css !== undefined)
+            files.push(measure(path, css, settings));
+    }
+    const sum = (pick) => files.reduce((total, file) => total + pick(file), 0);
+    const tokenUsages = sum((f) => f.tokenUsages);
+    const unknownVars = sum((f) => f.unknownVars);
+    const rawColors = sum((f) => f.rawColors);
+    const total = tokenUsages + unknownVars + rawColors;
+    const tokens = owned.paths.includes(tokenFile) ? await owned.read(tokenFile) : undefined;
+    return {
+        files,
+        percent: total === 0 ? 100 : Math.round((tokenUsages / total) * 100),
+        tokenUsages,
+        allowlisted: sum((f) => f.allowlisted),
+        unknownVars,
+        rawColors,
+        foreignDeclarations: [
+            ...new Set((tokens === undefined ? [] : customProperties(parseCss(tokens)))
+                .map((declaration) => declaration.name)
+                .filter((name) => !name.startsWith(settings.prefix))),
+        ].sort(),
+    };
+}

package/dist/src/tokens/css.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Finding and editing the blocks of the token file: the base `:root`, the
+ * custom properties written directly in a block, and splicing declarations
+ * into a block's lines. Parsing is `src/syntax`'s.
+ */
+import { customProperties, } from '../syntax/index.js';
+/** The base `:root` block: the first top-level rule that has `:root` as one of its selectors. */
+export function baseRoot(sheet) {
+    return sheet.blocks.find((block) => block.parent === undefined &&
+        block.selector.split(',').some((part) => part.trim() === ':root'));
+}
+/** The custom properties written directly in a block. */
+export function declarationsIn(sheet, block) {
+    return customProperties(sheet).filter((declaration) => declaration.block === block);
+}
+/**
+ * Gives a block's closing brace its own line, so a declaration can go in
+ * front of it. A rule written on one line, or closed after a declaration,
+ * is split. Mutates `lines`.
+ *
+ * @returns The line now holding the closing brace
+ */
+export function isolateClose(lines, block) {
+    const line = lines[block.close] ?? '';
+    const indent = /^\s*/.exec(lines[block.open] ?? '')?.[0] ?? '';
+    const tail = `${indent}${line.slice(block.closeCol)}`;
+    if (block.open === block.close) {
+        const body = line.slice(block.openCol + 1, block.closeCol).trim();
+        const replacement = [
+            line.slice(0, block.openCol + 1),
+            ...(body === '' ? [] : [`${indent}  ${body}`]),
+            tail,
+        ];
+        lines.splice(block.close, 1, ...replacement);
+        return block.close + replacement.length - 1;
+    }
+    const before = line.slice(0, block.closeCol);
+    if (before.trim() === '')
+        return block.close;
+    lines.splice(block.close, 1, before.trimEnd(), tail);
+    return block.close + 1;
+}
+/**
+ * Adds lines at the end of a block's content, after its last non-blank line.
+ * Mutates `lines`.
+ */
+export function appendToBlock(lines, block, add) {
+    const close = isolateClose(lines, block);
+    let at = close;
+    for (let i = close - 1; i > block.open; i--) {
+        if ((lines[i] ?? '').trim() !== '') {
+            at = i + 1;
+            break;
+        }
+    }
+    lines.splice(at, 0, ...add);
+}

package/dist/src/tokens/index.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Design tokens: the CSS custom-property file the project owns (its
+ * categories, tokens and themed blocks), adding tokens to it, and judging
+ * how the project's stylesheets use it. Functions take text or file
+ * interfaces; none reads the project on its own.
+ */
+export { addToken, TOKEN_MODES, tokenName } from './add.js';
+export { measureCoverage } from './coverage.js';
+export { lintTokens } from './lint.js';
+export { listTokens, tokenValues } from './model.js';
+export { readTokenFile, tokenSettings, tokenSettingsKeys } from './settings.js';

package/dist/src/tokens/lint.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Structural checks over the token system:
+ *
+ * - `token-lockstep`: a themed block (the dark `@media` mirror, a
+ *   `:root[variant]` block) declares only tokens the base `:root` declares;
+ *   otherwise every other theme resolves the token to nothing.
+ * - `token-undeclared`: a `var(--<prefix>...)` in the token file or an owned
+ *   stylesheet names a token nothing declares. Declarations in the same
+ *   sheet, in a sibling sheet, and the settings' exempt names do not count
+ *   as missing, and neither does a reference with a fallback.
+ */
+import { cssVarReferences, customProperties, parseCss } from '../syntax/index.js';
+import { baseRoot } from './css.js';
+import { blockPath, declaredTokens } from './model.js';
+import { readTokenFile } from './settings.js';
+import { siblingSheets } from './siblings.js';
+/** Themed declarations of prefixed tokens that the base block does not declare. */
+function lockstep(file, text, prefix) {
+    const sheet = parseCss(text);
+    const root = baseRoot(sheet);
+    if (root === undefined)
+        return [];
+    const inBase = (line) => line >= root.open && (root.close === -1 || line <= root.close);
+    const declared = customProperties(sheet);
+    const base = new Set(declared.filter((d) => inBase(d.line)).map((d) => d.name));
+    return declared
+        .filter((d) => !inBase(d.line) && d.name.startsWith(prefix) && !base.has(d.name))
+        .map((d) => ({
+        check: 'token-lockstep',
+        file,
+        line: d.line + 1,
+        token: d.name,
+        message: `${d.name} is declared in ${blockPath(d.block)} but not in the base :root block, so every ` +
+            'other theme resolves it to nothing. Declare the base value first (fireforge token add), or drop the override.',
+    }));
+}
+/** `var(--<prefix>...)` references to tokens that are not declared anywhere they could come from. */
+function undeclared(file, text, known, settings) {
+    const sheet = parseCss(text);
+    const local = new Set(customProperties(sheet).map((d) => d.name));
+    const findings = [];
+    const seen = new Set();
+    for (const { name, line, fallback } of cssVarReferences(sheet)) {
+        const skip = fallback ||
+            !name.startsWith(settings.prefix) ||
+            known.has(name) ||
+            local.has(name) ||
+            settings.exempt.has(name) ||
+            seen.has(name);
+        if (skip)
+            continue;
+        seen.add(name);
+        findings.push({
+            check: 'token-undeclared',
+            file,
+            line: line + 1,
+            token: name,
+            message: `var(${name}) names a token the token file does not declare, so it resolves to nothing. ` +
+                'Add the token, fix the name, or list a runtime channel in furnace.json runtimeVariables.',
+        });
+    }
+    return findings;
+}
+/**
+ * Judges the token file and every owned stylesheet.
+ *
+ * @param tokenFile - Engine path of the token file
+ * @param owned - The project's owned files
+ * @param settings - The project's token conventions
+ * @throws `token-file-missing`
+ */
+export async function lintTokens(tokenFile, owned, settings) {
+    const tokens = await readTokenFile(owned, tokenFile);
+    const known = declaredTokens(tokens);
+    const findings = [
+        ...lockstep(tokenFile, tokens, settings.prefix),
+        ...undeclared(tokenFile, tokens, known, settings),
+    ];
+    const sheets = owned.paths.filter((path) => path.endsWith('.css') && path !== tokenFile).sort();
+    const siblings = await siblingSheets(owned, sheets, settings);
+    let filesScanned = 1;
+    for (const file of sheets) {
+        const text = await owned.read(file);
+        if (text === undefined)
+            continue;
+        filesScanned++;
+        const visible = new Set(known);
+        for (const sibling of siblings.get(file) ?? []) {
+            for (const name of declaredTokens((await owned.read(sibling)) ?? ''))
+                visible.add(name);
+        }
+        findings.push(...undeclared(file, text, visible, settings));
+    }
+    return { filesScanned, findings };
+}

package/dist/src/tokens/model.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The token file: which categories its base `:root` block is divided into,
+ * which tokens each declares, and what a token resolves to in every block.
+ *
+ * A category is a banner comment inside the base block, either one line
+ * (`/* = Spacing = *\/`) or a boxed block whose first text line is the name.
+ * It owns everything up to the next banner. A decorative rule of only `=`
+ * ends a section once the section has declarations, and belongs to the
+ * section's own banner before that.
+ */
+import { customProperties, parseCss, } from '../syntax/index.js';
+import { baseRoot } from './css.js';
+/** What a banner comment declares: a name, a decorative rule (`''`), or nothing (undefined). */
+function bannerName(comment) {
+    const text = comment.text.trim();
+    if (!text.startsWith('='))
+        return undefined;
+    if (comment.start === comment.end) {
+        if (!text.endsWith('='))
+            return undefined;
+        return text.replace(/^=+/, '').replace(/=+$/, '').trim();
+    }
+    const rows = text.split('\n').map((row) => row.replace(/^\s*\*\s?/, '').trim());
+    return rows.find((row) => row !== '' && !/^=+$/.test(row)) ?? '';
+}
+function within(root, line) {
+    return line > root.open && (root.close === -1 || line < root.close);
+}
+/**
+ * The categories of the base block, in file order. Empty when the file has
+ * no closed base block.
+ *
+ * @param sheet - The parsed token file
+ */
+export function categories(sheet) {
+    const root = baseRoot(sheet);
+    if (root === undefined || root.close === -1)
+        return [];
+    const found = [];
+    let current;
+    for (const comment of sheet.comments) {
+        if (!within(root, comment.start))
+            continue;
+        const name = bannerName(comment);
+        if (name === undefined)
+            continue;
+        if (name === '' && current !== undefined) {
+            const owner = current;
+            const started = customProperties(sheet).some((declaration) => declaration.block === root &&
+                declaration.line > owner.line &&
+                declaration.line < comment.start);
+            if (!started)
+                continue;
+        }
+        if (current !== undefined)
+            current.end = comment.start;
+        current = undefined;
+        if (name !== '') {
+            current = { name, line: comment.start, end: root.close };
+            found.push(current);
+        }
+    }
+    return found;
+}
+/**
+ * The tokens declared in the base block, grouped under the banner above
+ * them. A banner without tokens is still a group.
+ *
+ * @param text - The token file
+ */
+export function listTokens(text) {
+    const sheet = parseCss(text);
+    const root = baseRoot(sheet);
+    if (root === undefined)
+        return [];
+    const sections = categories(sheet);
+    const groups = sections.map((section) => ({ category: section.name, tokens: [] }));
+    const loose = { category: null, tokens: [] };
+    for (const declaration of customProperties(sheet)) {
+        if (declaration.block !== root)
+            continue;
+        const index = sections.findIndex((section) => declaration.line > section.line && declaration.line < section.end);
+        const entry = { name: declaration.name, line: declaration.line + 1, value: declaration.value };
+        (index === -1 ? loose : groups[index])?.tokens.push(entry);
+    }
+    return loose.tokens.length > 0 ? [loose, ...groups] : groups;
+}
+/** The selectors enclosing a declaration, outermost first, joined with ` > `. */
+export function blockPath(block) {
+    const selectors = [];
+    for (let at = block; at !== undefined; at = at.parent)
+        selectors.unshift(at.selector || '(block)');
+    return selectors.length > 0 ? selectors.join(' > ') : '(file scope)';
+}
+/**
+ * Every declaration of a token in the file, labelled by its block.
+ *
+ * @param text - The token file
+ * @param name - Custom property name, with `--`
+ */
+export function tokenValues(text, name) {
+    return customProperties(parseCss(text))
+        .filter((declaration) => declaration.name === name)
+        .map((declaration) => ({
+        block: blockPath(declaration.block),
+        value: declaration.value,
+        line: declaration.line + 1,
+    }));
+}
+/**
+ * Every custom property the file declares, in any block.
+ *
+ * @param text - A stylesheet
+ */
+export function declaredTokens(text) {
+    return new Set(customProperties(parseCss(text)).map((declaration) => declaration.name));
+}