@motion-proto/live-tokens 0.78.0 → 0.80.0

package/bin/lib/componentSource.mjs

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PKG_ROOT, declaredCustomProperties, extractGlobalRootBlocks } from './tokenVocabulary.mjs';
+
+// Property suffixes come from the editor's own kind table, so the checker and
+// the picker can never disagree about what a name means. Read as text rather
+// than imported: this module must load without the compiled engine (CI runs the
+// suite before the plugin is built).
+const ALIAS_KINDS = 'src/editor/core/components/aliasKinds.ts';
+
+/** Each kind with the suffixes that name it, in the file's own order, since
+ *  the first match wins there too. */
+export function readKindRules(root) {
+  for (const base of [root, PKG_ROOT]) {
+    const path = join(base, ALIAS_KINDS);
+    if (!existsSync(path)) continue;
+    const src = readFileSync(path, 'utf8');
+    const block = src.match(/KIND_RULES[^=]*=\s*\[([\s\S]*?)\n\];/);
+    if (!block) continue;
+    const out = [];
+    for (const m of block[1].matchAll(/\{\s*kind:\s*'([a-z-]+)',\s*suffix:\s*\[([\s\S]*?)\]/g)) {
+      out.push({ kind: m[1], suffixes: [...m[2].matchAll(/'-([a-z0-9-]+)'/g)].map((n) => n[1]) });
+    }
+    if (out.length > 0) return out;
+  }
+  return [];
+}
+
+export function readKnownSuffixes(root) {
+  return [...new Set(readKindRules(root).flatMap((r) => r.suffixes))];
+}
+
+/**
+ * The token scale a property draws its value from, by way of the editor's own
+ * kind for it. A kind with no scale behind it — a length, a duration, a font
+ * axis — has none, so a literal there has no candidate to offer.
+ */
+const KIND_SCALE = {
+  'text-color': 'text',
+  surface: 'surface',
+  border: 'border',
+  radius: 'radius',
+  padding: 'space',
+  gap: 'space',
+  'hairline-inset': 'space',
+  'border-width': 'border-width',
+  'hairline-width': 'border-width',
+  'indicator-width': 'border-width',
+  shadow: 'shadow',
+};
+
+export const COLOR_SCALES = ['text', 'surface', 'border'];
+export const GEOMETRY_SCALES = ['space', 'radius', 'border-width', 'shadow'];
+
+export function tokenScale(token, kindRules, wanted) {
+  const bare = SIDE_SUFFIXES.find((x) => token.endsWith(x)) ? token.slice(0, token.lastIndexOf('-')) : token;
+  const rule = kindRules.find((r) => r.suffixes.some((s) => bare.endsWith(`-${s}`)));
+  const scale = rule ? (KIND_SCALE[rule.kind] ?? null) : null;
+  return wanted.includes(scale) ? scale : null;
+}
+
+// Per-side padding names (`--card-body-padding-top`) are written by the padding
+// selector, never declared by hand, and belong with their parent.
+export const SIDE_SUFFIXES = ['-top', '-right', '-bottom', '-left'];
+
+// State tokens that must come *before* the property, never after.
+export const STATE_TOKENS = ['hover', 'disabled', 'selected', 'focus', 'active', 'focused'];
+
+export function tokenSuffix(token, known) {
+  const bare = SIDE_SUFFIXES.find((x) => token.endsWith(x)) ? token.slice(0, token.lastIndexOf('-')) : token;
+  for (const suffix of known) {
+    if (bare.endsWith(`-${suffix}`)) return suffix;
+  }
+  return null;
+}
+
+/**
+ * Token patterns the editor declares in `intrinsics` — the only tokens allowed a
+ * bare keyword instead of a theme token.
+ *
+ * Matched on each spec's `variable`, not its `key`: the two need not agree
+ * (Image's `zoom` key declares `--image-zoom-enabled`), and `variable` is what
+ * actually names the token. A `${...}` hole stands for a variant segment.
+ */
+export function intrinsicMatchers(editor) {
+  const block = editor.match(/export\s+const\s+intrinsics[^=]*=\s*\[([\s\S]*?)\];/);
+  if (!block) return [];
+  const out = [];
+  for (const m of block[1].matchAll(/\bvariable\s*:[^`'"]*[`'"]([^`'"]+)[`'"]/g)) {
+    const pattern = m[1]
+      .replace(/[.*+?^${}()|[\]\\]/g, (c) => (c === '$' ? '$' : `\\${c}`))
+      .replace(/\$\\\{[^}]*\\\}/g, '[a-z0-9-]+')
+      .replace(/\$\{[^}]*\}/g, '[a-z0-9-]+');
+    out.push(new RegExp(`^${pattern}$`));
+  }
+  return out;
+}
+
+/** Every custom property the `:global(:root)` blocks declare, comments ignored. */
+export function declaredTokens(blocks) {
+  const declared = new Set();
+  for (const block of blocks) {
+    for (const n of declaredCustomProperties(block.replace(/\/\*[\s\S]*?\*\//g, ' '))) declared.add(n);
+  }
+  return declared;
+}
+
+/**
+ * Properties a component declares that nothing in its own file reads. A read is
+ * the name appearing outside the `:global(:root)` block: in a `var()`, in a
+ * `style:` directive, or as the string a padding mixin takes. SCSS interpolation
+ * (`--badge-#{$v}-surface`) reads every property the pattern covers. A per-side
+ * padding is read through its parent.
+ */
+export function unreadTokens(source, tokens) {
+  let body = source.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/<!--[\s\S]*?-->/g, ' ');
+  for (const block of extractGlobalRootBlocks(body)) body = body.replace(block, ' ');
+  const patterns = [...body.matchAll(/--[a-z0-9-]*(?:#\{[^}]*\}[a-z0-9-]*)+/g)].map(
+    (m) => new RegExp(`^${m[0].replace(/[.*+?^()|[\]\\]/g, '\\$&').replace(/#\{[^}]*\}/g, '[a-z0-9-]+')}$`),
+  );
+  const isRead = (name) => body.includes(name) || patterns.some((re) => re.test(name));
+  return [...tokens].filter((name) => {
+    const side = SIDE_SUFFIXES.find((s) => name.endsWith(s));
+    return !isRead(name) && !(side && isRead(name.slice(0, -side.length)));
+  });
+}
+
+/**
+ * Every token the editor names in a row: `variable: '--x'`, the type-group
+ * `colorVariable` / `familyVariable` / ... keys, and the arrow form intrinsics
+ * use. A `${...}` hole stands for a variant segment. Per-side padding names are
+ * written by the padding selector rather than declared, so they resolve to
+ * their parent.
+ */
+export function editorTokenRefs(editor) {
+  const literals = new Set();
+  const patterns = [];
+  for (const m of editor.matchAll(/\b(?:variable|[a-zA-Z]+Variable)\s*:\s*(?:\([^)]*\)\s*=>\s*)?[`'"](--(?:\$\{[^}]*\}|[^`'"])+)[`'"]/g)) {
+    const name = stripSide(m[1]);
+    if (name.includes('${')) {
+      patterns.push([name, new RegExp(`^${name.replace(/[.*+?^()|[\]\\]/g, '\\$&').replace(/\$\{[^}]*\}/g, '[a-z0-9-]+')}$`)]);
+    } else {
+      literals.add(name);
+    }
+  }
+  return { literals, patterns };
+}
+
+function stripSide(token) {
+  const side = SIDE_SUFFIXES.find((x) => token.endsWith(x));
+  return side ? token.slice(0, -side.length) : token;
+}

package/bin/lib/cssValues.mjs

@@ -48,3 +48,12 @@ export function stripVarFallbacks(value) {
 export function blankStrings(css) {
   return css.replace(/(["'])(?:\\.|(?!\1)[^\\])*\1/g, (m) => m[0] + ' '.repeat(m.length - 2) + m[0]);
 }
+
+/** The token scale a CSS property draws its colour from. The role inside that
+ *  scale stays the user's choice. */
+export function colorScaleOfProperty(prop) {
+  if (prop === 'color') return 'text';
+  if (/^background/.test(prop)) return 'surface';
+  if (/^(border|outline)(-|$)/.test(prop)) return 'border';
+  return null;
+}

package/bin/lib/dataDir.mjs

@@ -0,0 +1,126 @@
+// Resolves the project's live-tokens data directory and its optional
+// `live-tokens.testing.ts` settings file, statically — no engine import, no
+// dynamic import of the consumer's own config. Shared by `contractRunner.mjs`
+// (which isolates a copy of this directory before spawning the test tools)
+// and the `config-token` rule in `bin/rules/tokens.mjs` (which reads
+// `component-configs/<id>/default.json` under it directly), so the two agree
+// on which tree a project's saved assignments live in.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export function settingsFilePath(root) {
+  for (const name of ['live-tokens.testing.ts', 'live-tokens.testing.mts', 'live-tokens.testing.js', 'live-tokens.testing.mjs']) {
+    const path = join(root, name);
+    if (existsSync(path)) return path;
+  }
+  return null;
+}
+
+/**
+ * A generated config's own extensionless relative imports (Vite/Playwright's
+ * loaders resolve those, matching how this repo's own `vite.config.ts` and
+ * `live-tokens.testing.ts` are written) only get that treatment for a
+ * *static* import. A dynamic `import()` of the same path, called after a Vite
+ * config finishes loading, runs through plain Node resolution instead and
+ * fails on the same files: verified against `vitest.contract.config.ts` with
+ * both a `file://` URL and a plain absolute path as the dynamic specifier,
+ * identical `ERR_MODULE_NOT_FOUND` both times. So neither `settings.viteConfig`
+ * nor `settings.dataDir` (the resolved values `resolveTestingConfig` computes)
+ * has a reader here on purpose — reading either would mean importing the
+ * settings file dynamically first, which reintroduces exactly this failure.
+ * Regexing the settings file's *source text* for a field, imprecise as that
+ * is, is what stays inside the static-import constraint: a wrong guess still
+ * fails loudly (a bad `viteConfig` throws on its own static import in the
+ * generated file; a bad `dataDir` throws "no data directory at ..." below),
+ * never as a silent pass. A settings-level `dataDir` this cannot see at all
+ * is worse than one resolved this imprecisely, since a project that names its
+ * data directory only in `live-tokens.testing.ts` would otherwise have its
+ * contracts checked against whatever happens to sit at the default path.
+ */
+function stripComments(text) {
+  // Block comments first: a `//` inside one (`/* // note */`) must not seed a
+  // second, overlapping strip.
+  return text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '');
+}
+
+/** Measured across eleven settings-file shapes: a commented-out `dataDir:`
+ *  above the real one won the regex, because the regex only sees text
+ *  position, never comment syntax, and a comment naming the field with
+ *  nothing else present invented a setting out of prose. Comments are
+ *  stripped before the field ever gets a chance to match. A field present in
+ *  live code as a template literal, a computed value, or an import throws
+ *  instead of falling through to a default silently: the two guesses this
+ *  feeds, `viteConfig` and `dataDir`, can each resolve to a real path that
+ *  simply names the wrong tree, which then reads as a clean run. */
+export function scrapeSettingsField(settingsPath, fieldName) {
+  if (!settingsPath) return null;
+  let text;
+  try {
+    text = readFileSync(settingsPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const live = stripComments(text);
+  const literal = new RegExp(`\\b${fieldName}\\s*:\\s*['"]([^'"]+)['"]`).exec(live);
+  if (literal) return literal[1];
+  if (new RegExp(`\\b${fieldName}\\s*:`).test(live)) {
+    throw new Error(
+      `"${fieldName}" in ${settingsPath} is set to something other than a plain string literal, ` +
+        `so it cannot be read statically. Use a literal string, or remove the key to fall back to the default.`,
+    );
+  }
+  return null;
+}
+
+/**
+ * `dataDir` as the plugin resolves it: a `dataDir` field scraped from the
+ * settings file (see above), else `live-tokens.config.json`'s own key, else
+ * the default. Mirrors `resolveTestingConfig`'s own `configuredDataDir`
+ * fallback (`src/testing/config.ts`) rather than importing it: that module
+ * compiles into `src/testing-js`, which does not exist until `build:testing`
+ * runs, and importing the *source* `.ts` module to reach it hits the same
+ * extensionless-import failure documented above — measured with
+ * `src/testing-js` moved aside, `resolveTestingEntry`'s `.ts` fallback threw
+ * exactly that trying to load `vitest.ts`. Duplicating this small a resolver
+ * has precedent in this module already, in `settingsFilePath`.
+ */
+export function resolveSourceDataDir(root, settingsPath) {
+  const scraped = scrapeSettingsField(settingsPath, 'dataDir');
+  if (scraped) return resolve(root, scraped);
+  try {
+    const parsed = JSON.parse(readFileSync(join(root, 'live-tokens.config.json'), 'utf8'));
+    if (parsed && typeof parsed === 'object' && typeof parsed.dataDir === 'string') {
+      return resolve(root, parsed.dataDir);
+    }
+  } catch {
+    // Missing or unparseable reads as absent, matching the plugin's own resolver.
+  }
+  return resolve(root, 'src/live-tokens/data');
+}
+
+/**
+ * `component-configs/<id>/default.json` under the source data directory, as
+ * `{ path, text, data }`, or null when there is none to read. A non-literal
+ * `dataDir` in `live-tokens.testing.ts` (a template literal, a computed value)
+ * is only resolvable at `--tests` time, when the settings module itself runs;
+ * `resolveSourceDataDir` throws rather than guess. A plain-Node rule has no
+ * settings module to run, so it reads that as no config instead of taking the
+ * whole static lint down with it. Unparseable JSON reads as no config too.
+ */
+export function readComponentConfig(root, id) {
+  let dataDir;
+  try {
+    dataDir = resolveSourceDataDir(root, settingsFilePath(root));
+  } catch {
+    return null;
+  }
+  const path = join(dataDir, 'component-configs', id, 'default.json');
+  if (!existsSync(path)) return null;
+  const text = readFileSync(path, 'utf8');
+  try {
+    return { path, text, data: JSON.parse(text) };
+  } catch {
+    return null;
+  }
+}

package/bin/lib/findings.mjs

@@ -20,6 +20,15 @@ export function lineOf(text, index) {
   return line;
 }
 
+/** The line a `"<key>":` sits on. The quote on both sides of the key makes
+ *  this exact by construction — `"--card-default-body"` cannot match inside
+ *  `"--card-default-body-padding"`, unlike a bare substring search. */
+export function findJsonKeyLine(text, key) {
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const m = new RegExp(`"${escaped}"\\s*:`).exec(text);
+  return m ? lineOf(text, m.index) : 1;
+}
+
 export function readChecksConfig(root) {
   const path = join(root, 'live-tokens.config.json');
   if (!existsSync(path)) return {};
@@ -52,7 +61,7 @@ export function isExcluded(relPath, root) {
  * Unrecognised flags are returned in `rest` for the caller to handle.
  */
 export function parseCheckFlags(argv) {
-  const opts = { off: [], warn: [], error: [], strict: false, json: false, tests: false, rest: [] };
+  const opts = { off: [], warn: [], error: [], strict: false, json: false, tests: false, noFix: false, rest: [] };
   for (const arg of argv) {
     const m = arg.match(/^--(off|warn|error)=(.+)$/);
     if (m) {
@@ -60,17 +69,43 @@ export function parseCheckFlags(argv) {
     } else if (arg === '--strict') opts.strict = true;
     else if (arg === '--json') opts.json = true;
     else if (arg === '--tests') opts.tests = true;
+    else if (arg === '--no-fix') opts.noFix = true;
     else opts.rest.push(arg);
   }
   return opts;
 }
 
+/**
+ * One checker's rule table, keyed in `order`, from the modules under
+ * `bin/rules/` that define its rules. An id on one side and not the other
+ * throws when the checker loads.
+ */
+export function assembleRules(order, ...tables) {
+  const defined = Object.assign({}, ...tables);
+  const stray = [...order.filter((id) => !defined[id]), ...Object.keys(defined).filter((id) => !order.includes(id))];
+  if (stray.length > 0) throw new Error(`rule order and rule modules disagree on: ${stray.join(', ')}`);
+  return Object.fromEntries(order.map((id) => [id, defined[id]]));
+}
+
+/**
+ * The config entry that records a deliberate decision to keep a finding.
+ *
+ * A page or CSS file drops out of discovery, which is narrower than turning a
+ * rule off across the project. Everything else steps its rule down one notch,
+ * since a rule already resolved to `warn` is not silenced by `warn`.
+ */
+function exceptionFor(finding, severity, exclude) {
+  return exclude
+    ? { checks: { exclude: [finding.file] } }
+    : { checks: { rules: { [finding.rule]: severity === 'error' ? 'warn' : 'off' } } };
+}
+
 /** The same last-wins resolution `applySeverity` applies per finding, exposed
  *  standalone so coverage (which has no findings to attach a severity to, but
  *  still has to honor `--off`) can ask the same question. */
 export function resolveRuleSeverity(ruleId, rules, opts = {}, config = {}) {
   const configured = config.rules ?? {};
-  let severity = rules[ruleId] ?? 'error';
+  let severity = rules[ruleId]?.severity ?? 'error';
   if (SEVERITIES.includes(configured[ruleId])) severity = configured[ruleId];
   if (opts.off?.includes(ruleId)) severity = 'off';
   if (opts.warn?.includes(ruleId)) severity = 'warn';
@@ -80,16 +115,28 @@ export function resolveRuleSeverity(ruleId, rules, opts = {}, config = {}) {
 }
 
 /**
- * Resolve each finding's severity and drop the ones turned off.
- * `rules` maps rule id to its default severity.
+ * Resolve each finding's severity and drop the ones turned off, then attach
+ * what a repair needs: how to make it (`guidance`), how far code can take it
+ * (`repair`), and the config entry that records a decision to keep it
+ * (`exception`).
+ *
+ * `rules` maps rule id to `{ severity, repair, guidance }`. A rule's `repair`
+ * is the ceiling: a finding that arrives carrying its own has already lowered
+ * it, because its context is more ambiguous than the rule's.
  */
-export function applySeverity(findings, rules, opts = {}, config = {}, fixes = {}) {
+export function applySeverity(findings, rules, opts = {}, config = {}, { exclude = false } = {}) {
   return findings
-    .map((f) => ({
-      ...f,
-      severity: resolveRuleSeverity(f.rule, rules, opts, config),
-      ...(fixes[f.rule] ? { fix: fixes[f.rule] } : {}),
-    }))
+    .map((f) => {
+      const severity = resolveRuleSeverity(f.rule, rules, opts, config);
+      const rule = rules[f.rule];
+      return {
+        ...f,
+        severity,
+        ...(rule?.guidance ? { guidance: rule.guidance } : {}),
+        repair: f.repair ?? rule?.repair ?? 'authored',
+        exception: exceptionFor(f, severity, exclude),
+      };
+    })
     .filter((f) => f.severity !== 'off');
 }
 
@@ -144,11 +191,55 @@ export function formatFindings(findings, { label, checked = 0 } = {}) {
   return lines.join('\n');
 }
 
-export function toJson(findings, { label, checked = 0, coverage } = {}) {
+export function toJson(findings, { label, checked = 0, coverage, fix } = {}) {
   const { errors, warnings } = countBySeverity(findings);
   return JSON.stringify(
-    { check: label, checked, errors, warnings, findings, ...(coverage ? { coverage } : {}) },
+    { check: label, checked, errors, warnings, ...(fix ? { fix } : {}), findings, ...(coverage ? { coverage } : {}) },
     null,
     2,
   );
 }
+
+/** The unresolved property names a `contract-alias` finding lists, read off the
+ *  first line: a Playwright or Vitest stack follows on the lines after it.
+ *  `assertAliasesResolve` is the only obligation that lists them; every other
+ *  `contract-alias` message (an empty shipped config, say) misses and is left
+ *  alone. */
+const UNRESOLVED_ALIASES = /aliases resolve to nothing at the root: (.+)/;
+
+/** `component-configs/<id>/default.json`, the file both rules name. */
+const CONFIG_FILE = /component-configs[/\\]([^/\\]+)[/\\]default\.json$/;
+
+/**
+ * One broken alias, one finding.
+ *
+ * A `default.json` alias naming something the vocabulary lacks is a
+ * `config-token` finding from plain Node, and the same string makes the
+ * property resolve to nothing at the root, which the browser reports as
+ * `contract-alias`. Under `--tests` both run, so the merge drops the browser's
+ * copy when every name it lists already carries a `config-token` finding for
+ * the same component. A `contract-alias` naming a token the vocabulary knows,
+ * declared, spelled correctly, and still unresolved, is a different defect and
+ * stays.
+ */
+export function dedupeAliasFindings(findings) {
+  const broken = new Map();
+  for (const f of findings) {
+    if (f.rule !== 'config-token') continue;
+    const id = CONFIG_FILE.exec(f.file ?? '')?.[1];
+    const property = f.details?.property;
+    if (!id || !property) continue;
+    if (!broken.has(id)) broken.set(id, new Set());
+    broken.get(id).add(property);
+  }
+  if (broken.size === 0) return findings;
+  return findings.filter((f) => {
+    if (f.rule !== 'contract-alias') return true;
+    const id = CONFIG_FILE.exec(f.file ?? '')?.[1];
+    const known = id ? broken.get(id) : undefined;
+    if (!known) return true;
+    const listed = UNRESOLVED_ALIASES.exec(String(f.message ?? '').split('\n')[0])?.[1];
+    if (!listed) return true;
+    return !listed.split(',').map((name) => name.trim()).filter(Boolean).every((name) => known.has(name));
+  });
+}

package/bin/lib/fixers.mjs

@@ -0,0 +1,64 @@
+// Applies the patches an `auto` finding already computed in its own
+// `details.patch`. This module owns none of the per-rule repair logic — that
+// lives beside each rule, in bin/rules/, pageSource.mjs, geometry.mjs, and
+// catalogue.mjs, since only the rule that found the fault knows its shape.
+// This module only knows how to write one down safely.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The character offset where 1-based `line` begins. The inverse of
+ *  `lineOf` in findings.mjs. */
+function offsetOfLine(text, line) {
+  let n = 1;
+  for (let i = 0; i < text.length; i++) {
+    if (n === line) return i;
+    if (text[i] === '\n') n++;
+  }
+  return text.length;
+}
+
+/**
+ * Writes every `auto` finding's patch, one file at a time.
+ *
+ * A patch applies at the first occurrence of `from` at or after the finding's
+ * own line: the file has moved since the finding was computed, or another
+ * patch in the same file shifted text, so a patch whose `from` cannot be
+ * found there is not applied and comes back in `skipped` instead of guessing
+ * at a different occurrence. Findings within one file apply in line order;
+ * none of the four fixers inserts or removes a newline, so an earlier
+ * patch's line never moves a later one's.
+ */
+export function applyFixes(findings, root) {
+  const byFile = new Map();
+  for (const f of findings) {
+    if (f.repair !== 'auto' || !f.details?.patch) continue;
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
+  }
+
+  const applied = [];
+  const skipped = [];
+  for (const [file, list] of byFile) {
+    const path = join(root, file);
+    if (!existsSync(path)) {
+      skipped.push(...list);
+      continue;
+    }
+    let text = readFileSync(path, 'utf8');
+    let changed = false;
+    for (const finding of list.sort((a, b) => a.line - b.line)) {
+      const { from, to } = finding.details.patch;
+      const at = text.indexOf(from, offsetOfLine(text, finding.line));
+      if (at === -1) {
+        skipped.push(finding);
+        continue;
+      }
+      text = text.slice(0, at) + to + text.slice(at + from.length);
+      changed = true;
+      applied.push(finding);
+    }
+    if (changed) writeFileSync(path, text);
+  }
+  return { applied, skipped };
+}

package/bin/lib/geometry.mjs

@@ -0,0 +1,92 @@
+// Which token a raw dimension should have been, computed rather than guessed.
+//
+// `dimension-literal` fires on a declaration the checkers already flagged; this
+// module answers the follow-up a repair needs: what the literal measures, which
+// step of its scale sits nearest, and whether that step is unique. A tie is the
+// one case a person has to settle, so it is reported rather than resolved.
+
+import { stripVarFallbacks } from './cssValues.mjs';
+
+const REM_PX = 16;
+
+// The same literals `hasDimensionLiteral` flags: px and rem, no leading sign.
+const LITERAL = /(?<![\w.-])(\d*\.?\d+)(px|rem)\b/g;
+
+const round = (n) => Math.round(n * 1000) / 1000;
+
+/**
+ * A token's value in pixels, or null when it is not a single length. A shadow
+ * step (`1px 1px 2px hsla(...)`) and `--space-full: 100%` both measure nothing
+ * a literal can be matched against, so neither becomes a candidate.
+ */
+function pixelsOf(value) {
+  const m = /^\s*(\d*\.?\d+)(px|rem)?\s*$/.exec(value);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  if (!m[2]) return n === 0 ? 0 : null;
+  return m[2] === 'rem' ? n * REM_PX : n;
+}
+
+/** The token scale a CSS property draws its lengths from, for check-page. */
+export function geometryScaleOfProperty(prop) {
+  if (/-radius$/.test(prop)) return 'radius';
+  if (/shadow$/.test(prop)) return 'shadow';
+  if (/^(border|outline)(-|$)/.test(prop)) return 'border-width';
+  if (/^(padding|margin|gap|row-gap|column-gap|inset|top|right|bottom|left)(-|$)/.test(prop)) return 'space';
+  return null;
+}
+
+/** Each literal in `text` (fallback-stripped, the same text `from` names)
+ *  replaced by its one candidate's token. Only called once every literal is
+ *  unique, so `candidates[0]` is never a guess. A zero-valued match has no
+ *  entry in `literals` (the census skips it too), so it must be recognised
+ *  here and left untouched rather than consuming the next entry.
+ */
+function rewriteLiterals(text, literals) {
+  let i = 0;
+  return text.replace(LITERAL, (match, num, unit) => {
+    const px = round(parseFloat(num) * (unit === 'rem' ? REM_PX : 1));
+    if (px === 0) return match;
+    return `var(${literals[i++].candidates[0].token})`;
+  });
+}
+
+/**
+ * Every literal in a declaration, each with the nearest step of `scale`.
+ *
+ * A term inside `calc()` or a shorthand is measured on its own, so
+ * `padding: 8px 16px` reports two literals and `calc(100% - 20px)` reports the
+ * 20px. `auto` holds only when every one of them lands on a single step and
+ * the declaration carries no var() fallback: a tie, a scale with no
+ * comparable steps, or a fallback beside the literal leaves the choice open.
+ */
+export function resolveGeometryLiteral(value, scale, tokens = []) {
+  const steps = [];
+  for (const token of tokens) {
+    const px = pixelsOf(token.value ?? '');
+    if (px !== null) steps.push({ token: token.name, px });
+  }
+
+  const stripped = stripVarFallbacks(value);
+  const literals = [];
+  for (const m of stripped.matchAll(LITERAL)) {
+    const px = round(parseFloat(m[1]) * (m[2] === 'rem' ? REM_PX : 1));
+    if (px === 0) continue;
+    const nearest = steps.reduce((best, s) => Math.min(best, Math.abs(s.px - px)), Infinity);
+    const candidates = steps
+      .filter((s) => Math.abs(Math.abs(s.px - px) - nearest) < 1e-6)
+      .map((s) => ({ token: s.token, px: s.px, shift: round(s.px - px) }));
+    literals.push({ value: m[0], px, candidates });
+  }
+
+  // A var() fallback beside a flagged literal makes `stripped` text the source
+  // never contains, so no patch could find its site; the choice stays open.
+  const auto =
+    stripped === value && literals.length > 0 && literals.every((l) => l.candidates.length === 1);
+  return {
+    scale,
+    literals,
+    auto,
+    patch: auto ? { from: stripped, to: rewriteLiterals(stripped, literals) } : null,
+  };
+}