tempest-react-sdk 0.26.1 → 0.28.0

package/bin/lib/css/semantic.mjs

@@ -0,0 +1,327 @@
+// Per-file CSS analysis: what the parser flagged as broken syntax, plus what is
+// syntactically fine and still wrong — a declaration the next one kills, a
+// property name nobody implements, a `var()` pointing at a token that does not
+// exist.
+import { finding } from "./findings.mjs";
+import { maskValue, normalizeSelectors } from "./parse.mjs";
+import { isCheckableProperty, KNOWN_AT_RULES, KNOWN_PROPERTIES, nearest } from "./properties.mjs";
+import { tokenForValue } from "./tokens.mjs";
+
+/** Human text for each parser-level code. */
+const SYNTAX_MESSAGES = {
+    "unterminated-comment": "unterminated `/*` comment — everything after it is swallowed",
+    "unterminated-string": "unterminated string — the rest of the line is parsed as part of it",
+    "unterminated-paren": "unbalanced `(` — the rest of the sheet is parsed as part of the value",
+    "unclosed-block": "block opened here is never closed with `}`",
+    "unexpected-brace": "stray `}` with no block open",
+    "missing-brace": "selector with no `{ … }` block",
+    "missing-colon": "declaration without `:`",
+    "missing-property": "declaration with no property name before `:`",
+    "empty-value": "declaration with an empty value — the browser drops it",
+    "empty-selector": "`{` with no selector before it",
+    "declaration-outside-rule": "declaration outside any rule — the browser drops it",
+};
+
+/** Properties whose literal values are worth suggesting a token for. */
+const TOKENIZABLE = new Set([
+    "color",
+    "background",
+    "background-color",
+    "border-color",
+    "border-top-color",
+    "border-right-color",
+    "border-bottom-color",
+    "border-left-color",
+    "outline-color",
+    "fill",
+    "stroke",
+    "box-shadow",
+    "border-radius",
+    "font-size",
+    "font-family",
+    "font-weight",
+    "line-height",
+    "gap",
+    "row-gap",
+    "column-gap",
+    "padding",
+    "margin",
+    "z-index",
+    "transition-duration",
+]);
+
+/**
+ * True when a second declaration of the same property is the progressive-
+ * enhancement idiom rather than a mistake.
+ *
+ * The pattern is deliberate and everywhere: write a value old browsers
+ * understand, then the modern one they will ignore. Flagging it would train
+ * people to ignore the whole check, so anything that smells like the modern half
+ * — a vendor prefix, a function call, a viewport unit, an `!important` escalation
+ * — exempts the pair.
+ *
+ * @param {{ value: string }} earlier
+ * @param {{ value: string }} later
+ * @returns {boolean}
+ */
+function isProgressiveFallback(earlier, later) {
+    const modern = /\b(var|env|clamp|min|max|calc|color-mix|light-dark|oklch|lab)\(/i;
+    const units = /\b\d+(\.\d+)?(dvh|svh|lvh|dvw|svw|lvw|cqw|cqh|cqi|cqb)\b/i;
+    const prefixed = /(^|\s)-(webkit|moz|ms|o)-/;
+    if (modern.test(later.value) || units.test(later.value) || prefixed.test(later.value)) {
+        return true;
+    }
+    if (prefixed.test(earlier.value)) return true;
+    return /!\s*important/i.test(later.value) && !/!\s*important/i.test(earlier.value);
+}
+
+/** `var(--name[, fallback])` references in a value. */
+function varReferences(value) {
+    const out = [];
+    const re = /var\(\s*(--[a-zA-Z0-9_-]+)\s*(,)?/g;
+    let match;
+    while ((match = re.exec(value))) out.push({ name: match[1], hasFallback: Boolean(match[2]) });
+    return out;
+}
+
+/** Key that makes two rules comparable: same selector list, same at-rule context. */
+export function ruleKey(block) {
+    return `${block.context.join(" › ")}|${normalizeSelectors(block.prelude).join(", ")}`;
+}
+
+/** Normalized `prop:value` signature of a block's declarations. */
+export function declSignature(block) {
+    return block.decls
+        .map((d) => `${d.prop.toLowerCase()}:${d.value.replace(/\s+/g, " ").toLowerCase()}`)
+        .sort()
+        .join(";");
+}
+
+/**
+ * Analyze one stylesheet.
+ *
+ * @param {object} params
+ * @param {string} params.file - Path to report findings against.
+ * @param {ReturnType<import("./parse.mjs").parseCss>} params.parsed
+ * @param {{ names: Set<string>, byValue: Map<string, string[]> }} params.tokens
+ * @param {Set<string>} params.definedVars - Custom properties defined anywhere in the project.
+ * @param {boolean} [params.isModule] - Whether the file is a CSS Module.
+ * @returns {Array<ReturnType<typeof finding>>}
+ */
+export function analyzeParsed({ file, parsed, tokens, definedVars, isModule = false }) {
+    const findings = [];
+    const at = (code, line, message, fixable = false, extra = {}) =>
+        findings.push(finding(code, { file, line, message, fixable, extra }));
+
+    for (const error of parsed.errors) {
+        const detail = error.text ? ` — \`${truncate(error.text)}\`` : "";
+        at(error.code, error.line, `${SYNTAX_MESSAGES[error.code] ?? error.code}${detail}`);
+    }
+
+    for (const { line, prop } of missingSemicolons(parsed)) {
+        at(
+            "missing-semicolon",
+            line,
+            `the value of \`${prop}\` swallows the declaration(s) below it — a \`;\` is missing, ` +
+                "so the browser drops all of them",
+        );
+    }
+
+    for (const statement of parsed.statements) {
+        checkAtRule(statement.name, statement.line, at);
+    }
+
+    const byKey = new Map();
+
+    for (const block of parsed.blocks) {
+        if (block.kind === "at") {
+            checkAtRule(/^@([\w-]+)/.exec(block.prelude)?.[1]?.toLowerCase() ?? "", block.line, at);
+        }
+
+        if (block.decls.length === 0 && block.children === 0 && !block.invalid) {
+            at(
+                "empty-rule",
+                block.line,
+                isModule
+                    ? `\`${truncate(block.prelude)}\` is empty — dead unless your JS uses it as a marker class, ` +
+                          "so it is reported but never removed automatically"
+                    : `\`${truncate(block.prelude)}\` is empty — dead code`,
+                !isModule,
+            );
+        }
+
+        const seen = new Map();
+        for (const decl of block.decls) {
+            const prop = decl.prop.toLowerCase();
+            const previous = seen.get(prop);
+            if (previous) {
+                const sameValue =
+                    previous.value.replace(/\s+/g, " ").toLowerCase() ===
+                    decl.value.replace(/\s+/g, " ").toLowerCase();
+                if (sameValue) {
+                    at(
+                        "duplicate-declaration",
+                        decl.line,
+                        `\`${prop}\` is declared twice with the same value (also on line ${previous.line}) — ` +
+                            "the first one is dead",
+                        true,
+                    );
+                } else if (!isProgressiveFallback(previous, decl)) {
+                    at(
+                        "overridden-declaration",
+                        decl.line,
+                        `\`${prop}: ${truncate(decl.value)}\` overrides \`${truncate(previous.value)}\` from ` +
+                            `line ${previous.line} in the same rule — one of them is a mistake`,
+                    );
+                }
+            }
+            seen.set(prop, decl);
+
+            checkDecl({ decl, prop, tokens, definedVars, at });
+        }
+
+        if (block.kind !== "rule") continue;
+        const key = ruleKey(block);
+        const previous = byKey.get(key);
+        if (previous) {
+            reportDuplicateRule({ block, previous, at });
+        } else {
+            byKey.set(key, block);
+        }
+    }
+
+    return findings;
+}
+
+/** Report a selector declared twice in the same file. */
+function reportDuplicateRule({ block, previous, at }) {
+    const identical = declSignature(block) === declSignature(previous) && block.decls.length > 0;
+    if (identical) {
+        at(
+            "duplicate-rule",
+            block.line,
+            `\`${truncate(block.prelude)}\` repeats line ${previous.line} declaration for declaration — ` +
+                "the first copy has no effect",
+            true,
+        );
+        return;
+    }
+    const props = new Set(previous.decls.map((d) => d.prop.toLowerCase()));
+    const shadowed = block.decls.map((d) => d.prop.toLowerCase()).filter((p) => props.has(p));
+    at(
+        "duplicate-selector",
+        block.line,
+        shadowed.length > 0
+            ? `\`${truncate(block.prelude)}\` is declared again (first on line ${previous.line}) and re-declares ` +
+                  `${shadowed.slice(0, 4).join(", ")} — the earlier value is dead; merge the rules`
+            : `\`${truncate(block.prelude)}\` is declared in two places (line ${previous.line} and here) — ` +
+                  "merge them so the rule reads in one place",
+    );
+}
+
+/**
+ * Property-level and value-level checks for a single declaration.
+ *
+ * A `var()` **with a fallback** is never reported. That is the SDK's own knob
+ * idiom — `var(--tempest-card-padding, var(--tempest-space-5))` is a component
+ * offering an override nobody is required to set — so "this name is not a token"
+ * would fire on the pattern the docs teach. Without a fallback the same
+ * declaration resolves to nothing, which is a real defect and is reported.
+ */
+function checkDecl({ decl, prop, tokens, definedVars, at }) {
+    if (isCheckableProperty(prop) && !KNOWN_PROPERTIES.has(prop)) {
+        const suggestion = nearest(prop, KNOWN_PROPERTIES);
+        if (suggestion) {
+            at(
+                "unknown-property",
+                decl.line,
+                `\`${prop}\` is not a CSS property — did you mean \`${suggestion}\`? The browser drops the declaration`,
+            );
+        }
+    }
+
+    for (const ref of varReferences(decl.value)) {
+        if (ref.hasFallback || definedVars.has(ref.name)) continue;
+        if (ref.name.startsWith("--tempest-")) {
+            if (tokens.names.size === 0) continue;
+            const suggestion = nearest(ref.name, tokens.names, 3);
+            at(
+                "unknown-token",
+                decl.line,
+                `\`${ref.name}\` is not an SDK token, nothing in this project defines it, and it has no ` +
+                    `fallback${suggestion ? ` — did you mean \`${suggestion}\`?` : ""}`,
+            );
+            continue;
+        }
+        at(
+            "undefined-var",
+            decl.line,
+            `\`${ref.name}\` is never defined in this project and has no fallback — ` +
+                "the declaration resolves to nothing",
+        );
+    }
+
+    if (!TOKENIZABLE.has(prop) || decl.value.includes("var(")) return;
+    const token = tokenForValue(decl.value, tokens.byValue);
+    if (token) {
+        at(
+            "hardcoded-token-value",
+            decl.line,
+            `\`${prop}: ${truncate(decl.value)}\` is exactly \`${token}\` — use \`var(${token})\` so ` +
+                "the theme and dark mode follow it",
+        );
+    }
+}
+
+/** Flag an at-rule name the browser will not recognize. */
+function checkAtRule(name, line, at) {
+    if (!name || KNOWN_AT_RULES.has(name)) return;
+    if (!/^[a-z][a-z-]*$/.test(name)) return;
+    const suggestion = nearest(name, KNOWN_AT_RULES);
+    at(
+        "unknown-at-rule",
+        line,
+        `\`@${name}\` is not a CSS at-rule${suggestion ? ` — did you mean \`@${suggestion}\`?` : ""}; ` +
+            "the browser skips the whole block",
+    );
+}
+
+/** Shorten a snippet for a one-line report. */
+function truncate(text, max = 60) {
+    const flat = String(text).replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+/** Custom properties **defined** by a parsed sheet (`--x: …`, at any depth). */
+export function definedCustomProperties(parsed) {
+    const out = new Set();
+    for (const block of parsed.blocks) {
+        for (const decl of block.decls) if (decl.prop.startsWith("--")) out.add(decl.prop);
+    }
+    return out;
+}
+
+/**
+ * Declarations whose value spans a `;` the author forgot.
+ *
+ * The parser cannot know: `color: red` followed by a newline and
+ * `background: blue` with no semicolon between them is one syntactically valid
+ * declaration with a nonsense value, and the browser drops both. It reads as a
+ * formatting slip and costs an afternoon.
+ *
+ * @param {ReturnType<import("./parse.mjs").parseCss>} parsed
+ * @returns {Array<{ line: number, prop: string }>}
+ */
+export function missingSemicolons(parsed) {
+    const out = [];
+    for (const block of parsed.blocks) {
+        for (const decl of block.decls) {
+            if (!decl.value.includes("\n")) continue;
+            const mask = maskValue(decl.value);
+            if (/\n[^\S\n]*[-a-zA-Z][\w-]*[^\S\n]*:/.test(mask)) {
+                out.push({ line: decl.line, prop: decl.prop });
+            }
+        }
+    }
+    return out;
+}

package/bin/lib/css/semantic.test.mjs

@@ -0,0 +1,201 @@
+import { describe, expect, it } from "vitest";
+
+import { parseCss } from "./parse.mjs";
+import { analyzeParsed, declSignature, definedCustomProperties } from "./semantic.mjs";
+
+const TOKENS = {
+    names: new Set(["--tempest-space-2", "--tempest-primary", "--tempest-text"]),
+    byValue: new Map([
+        ["8px", ["--tempest-space-2"]],
+        ["#0d6efd", ["--tempest-primary"]],
+        ["4px", ["--tempest-space-1", "--tempest-radius-sm"]],
+    ]),
+    utilities: new Set(),
+};
+
+const analyze = (text, options = {}) =>
+    analyzeParsed({
+        file: "src/a.css",
+        parsed: parseCss(text),
+        tokens: TOKENS,
+        definedVars: new Set([...TOKENS.names, ...(options.defined ?? [])]),
+        isModule: options.isModule ?? false,
+    });
+
+const codes = (text, options) => analyze(text, options).map((f) => f.code);
+const first = (text, code, options) => analyze(text, options).find((f) => f.code === code);
+
+describe("analyzeParsed — syntax passthrough", () => {
+    it("turns parser codes into findings with a message and a line", () => {
+        const [found] = analyze(".a { color: ; }");
+        expect(found).toMatchObject({ code: "empty-value", severity: "error", line: 1 });
+        expect(found.message).toContain("empty value");
+    });
+
+    it("flags a missing semicolon that swallows the next declarations", () => {
+        const found = first(".a {\n    padding: 8px\n    margin: 0;\n}\n", "missing-semicolon");
+        expect(found).toMatchObject({ severity: "error", line: 2 });
+    });
+
+    it("does not mistake a multi-line value for a missing semicolon", () => {
+        expect(
+            codes(".a {\n    grid-template-columns: repeat(\n        2,\n        1fr\n    );\n}\n"),
+        ).toEqual([]);
+    });
+});
+
+describe("analyzeParsed — duplicate declarations", () => {
+    it("flags the same property with the same value twice", () => {
+        const found = first(".a { color: red; color: red; }", "duplicate-declaration");
+        expect(found).toMatchObject({ severity: "warn", fixable: true });
+    });
+
+    it("flags an override with a different value in the same rule", () => {
+        const found = first(".a { color: red; color: blue; }", "overridden-declaration");
+        expect(found.fixable).toBe(false);
+        expect(found.message).toContain("overrides");
+    });
+
+    it("accepts a var() fallback after a literal", () => {
+        expect(codes(".a { color: #0d6efd; color: var(--tempest-primary); }")).toEqual([
+            "hardcoded-token-value",
+        ]);
+    });
+
+    it("accepts a vendor-prefixed value before the standard one", () => {
+        expect(codes(".a { display: -webkit-box; display: flex; }")).toEqual([]);
+    });
+
+    it("accepts an !important escalation", () => {
+        expect(codes(".a { color: red; color: blue !important; }")).toEqual([]);
+    });
+});
+
+describe("analyzeParsed — duplicate selectors", () => {
+    it("flags a selector declared twice with overlapping properties", () => {
+        const found = first(".a { color: red; }\n.a { color: blue; }\n", "duplicate-selector");
+        expect(found).toMatchObject({ line: 2 });
+        expect(found.message).toContain("color");
+    });
+
+    it("flags a selector split across two rules with no overlap", () => {
+        const found = first(".a { color: red; }\n.a { padding: 0; }\n", "duplicate-selector");
+        expect(found.message).toContain("merge them");
+    });
+
+    it("flags an exact repeat as a duplicate rule, and marks it fixable", () => {
+        const found = first(".a { color: red; }\n.a { color: red; }\n", "duplicate-rule");
+        expect(found).toMatchObject({ fixable: true, line: 2 });
+    });
+
+    it("treats a reordered selector list as the same rule", () => {
+        expect(codes(".a, .b { color: red; }\n.b, .a { color: blue; }\n")).toContain(
+            "duplicate-selector",
+        );
+    });
+
+    it("does not compare rules across different at-rule contexts", () => {
+        expect(codes(".a { color: red; }\n@media print {\n  .a { color: black; }\n}\n")).toEqual(
+            [],
+        );
+    });
+});
+
+describe("analyzeParsed — names", () => {
+    it("flags a misspelled property when a real one is close", () => {
+        const found = first(".a { bacground-color: red; }", "unknown-property");
+        expect(found.message).toContain("background-color");
+    });
+
+    it("stays silent on a property it simply does not know", () => {
+        expect(codes(".a { anchor-scope: all; }")).toEqual([]);
+    });
+
+    it("ignores vendor prefixes and custom properties", () => {
+        expect(codes(".a { -webkit-line-clamp: 2; --my-own: 1; }")).toEqual([]);
+    });
+
+    it("flags a misspelled at-rule", () => {
+        const found = first("@medai (min-width: 1px) { .a { color: red; } }", "unknown-at-rule");
+        expect(found.message).toContain("@media");
+    });
+
+    it("accepts modern at-rules", () => {
+        expect(codes("@layer base {\n  .a { color: red; }\n}\n")).toEqual([]);
+    });
+});
+
+describe("analyzeParsed — custom properties", () => {
+    it("flags an SDK token that does not exist, and suggests the nearest", () => {
+        const found = first(".a { gap: var(--tempest-space-3); }", "unknown-token");
+        expect(found.message).toContain("--tempest-space-2");
+    });
+
+    it("accepts a `--tempest-*` knob that carries a fallback", () => {
+        // `var(--tempest-card-padding, …)` is the SDK's own override idiom: the name
+        // is not a token, it is a hook an app may set. A fallback means it renders.
+        expect(codes(".a { gap: var(--tempest-card-padding, 8px); }")).toEqual([]);
+    });
+
+    it("flags a var() nobody defines when there is no fallback", () => {
+        const found = first(".a { width: var(--nope); }", "undefined-var");
+        expect(found.severity).toBe("warn");
+    });
+
+    it("accepts a var() defined elsewhere in the project", () => {
+        expect(codes(".a { width: var(--row-height); }", { defined: ["--row-height"] })).toEqual(
+            [],
+        );
+    });
+
+    it("accepts a var() with a fallback", () => {
+        expect(codes(".a { width: var(--row-height, 40px); }")).toEqual([]);
+    });
+
+    it("accepts a var() the same sheet defines", () => {
+        const text = ":root { --mine: 4px; }\n.a { gap: var(--mine); }\n";
+        const parsed = parseCss(text);
+        expect(definedCustomProperties(parsed)).toEqual(new Set(["--mine"]));
+    });
+});
+
+describe("analyzeParsed — token suggestions", () => {
+    it("suggests the token whose value matches exactly", () => {
+        const found = first(".a { gap: 8px; }", "hardcoded-token-value");
+        expect(found).toMatchObject({ severity: "info" });
+        expect(found.message).toContain("var(--tempest-space-2)");
+    });
+
+    it("stays silent when the value belongs to more than one token", () => {
+        expect(codes(".a { gap: 4px; }")).toEqual([]);
+    });
+
+    it("stays silent for properties nobody themes", () => {
+        expect(codes(".a { width: 8px; }")).toEqual([]);
+    });
+});
+
+describe("analyzeParsed — empty rules", () => {
+    it("flags an empty rule in a plain sheet as fixable", () => {
+        const found = first(".a {}\n", "empty-rule");
+        expect(found.fixable).toBe(true);
+    });
+
+    it("never removes an empty rule in a CSS Module", () => {
+        const found = first(".a {}\n", "empty-rule", { isModule: true });
+        expect(found.fixable).toBe(false);
+        expect(found.message).toContain("marker class");
+    });
+
+    it("does not call a rule with nested children empty", () => {
+        expect(codes(".a {\n  &:hover { color: red; }\n}\n")).toEqual([]);
+    });
+});
+
+describe("declSignature", () => {
+    it("ignores declaration order, case and whitespace", () => {
+        const a = parseCss(".x { color: RED; padding:  0 ; }").blocks[0];
+        const b = parseCss(".y { padding: 0; color: red; }").blocks[0];
+        expect(declSignature(a)).toBe(declSignature(b));
+    });
+});

package/bin/lib/css/tokens.mjs

@@ -0,0 +1,119 @@
+// The `--tempest-*` token table, read from whichever stylesheet this project
+// actually has: the installed SDK's `dist/styles.css`, or — when the CLI runs
+// from a checkout of the SDK itself — the sources under `src/styles/`.
+//
+// Read, never hard-coded. A copy of the token list inside the CLI would drift
+// the first time a token is added, and then it would report the app's correct
+// code as a typo, which is worse than not checking at all. No stylesheet found
+// means the token checks stay silent.
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/** Candidate stylesheet locations, in the order they are trusted. */
+function candidates(root, selfDir) {
+    return [
+        join(root, "node_modules", "tempest-react-sdk", "dist", "styles.css"),
+        join(root, "node_modules", "tempest-react-sdk", "dist", "utilities.css"),
+        join(selfDir, "..", "dist", "styles.css"),
+        join(selfDir, "..", "dist", "utilities.css"),
+    ];
+}
+
+/** Every `.css` file under a directory (non-recursive), sorted. */
+function cssFilesIn(dir) {
+    try {
+        return readdirSync(dir)
+            .filter((name) => name.endsWith(".css"))
+            .sort()
+            .map((name) => join(dir, name));
+    } catch {
+        return [];
+    }
+}
+
+/** Normalize a token value for value→token lookups. */
+function normalizeValue(value) {
+    return value.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+/**
+ * Collect `--custom-property: value` pairs from stylesheet text.
+ *
+ * Deliberately regex-based rather than a full parse: this runs over the SDK's
+ * own already-valid stylesheet, where the only thing wanted is the names, and a
+ * value containing `;` inside `url()` at worst costs one entry in the value map.
+ *
+ * @param {string} text
+ * @returns {Array<[name: string, value: string]>}
+ */
+function customProperties(text) {
+    const out = [];
+    const re = /(--[a-zA-Z0-9_-]+)\s*:\s*([^;}]+)/g;
+    let match;
+    while ((match = re.exec(text))) out.push([match[1], match[2].trim()]);
+    return out;
+}
+
+/**
+ * Load the SDK design tokens.
+ *
+ * @param {object} params
+ * @param {string} params.root - Project root.
+ * @param {string} params.selfDir - Directory of the running CLI (`bin/`).
+ * @returns {{
+ *   source: string | null,
+ *   names: Set<string>,
+ *   byValue: Map<string, string[]>,
+ *   utilities: Set<string>,
+ * }}
+ */
+export function loadTokens({ root, selfDir }) {
+    const files = candidates(root, selfDir).filter(existsSync);
+    if (files.length === 0) {
+        const localStyles = join(selfDir, "..", "src", "styles");
+        files.push(...cssFilesIn(localStyles));
+    }
+    const names = new Set();
+    const byValue = new Map();
+    const utilities = new Set();
+    let source = null;
+
+    for (const file of files) {
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        } catch {
+            continue;
+        }
+        source ??= file;
+        for (const [name, value] of customProperties(text)) {
+            if (!name.startsWith("--tempest-")) continue;
+            names.add(name);
+            if (value.includes("var(")) continue;
+            const key = normalizeValue(value);
+            const list = byValue.get(key) ?? [];
+            if (!list.includes(name)) list.push(name);
+            byValue.set(key, list);
+        }
+        for (const match of text.matchAll(/\.(tempest-[a-z0-9-]+)/g)) utilities.add(match[1]);
+    }
+
+    return { source, names, byValue, utilities };
+}
+
+/**
+ * Token whose value is exactly this literal, when exactly one token has it.
+ *
+ * Ambiguity is the whole reason for the single-match rule: `4px` is the value of
+ * several tokens, and telling somebody to use `--tempest-space-1` when they meant
+ * a hairline border is a bad suggestion delivered confidently. One match means
+ * the intent is unambiguous.
+ *
+ * @param {string} value - Declaration value as written.
+ * @param {Map<string, string[]>} byValue - Value→tokens index.
+ * @returns {string | null}
+ */
+export function tokenForValue(value, byValue) {
+    const matches = byValue.get(normalizeValue(value));
+    return matches && matches.length === 1 ? matches[0] : null;
+}