@motion-proto/live-tokens 0.77.0 → 0.79.0

package/bin/lib/catalogue.mjs

@@ -4,25 +4,121 @@
 // use, so a skill or a script sees exactly what the checkers will hold it to.
 
 import { readFileSync } from 'node:fs';
-import { relative } from 'node:path';
-import { CONTRACT_SCALES } from './tokenVocabulary.mjs';
-
-/** The runtime file's leading HTML comment, which is where a component says what
-    it is for. A labelled line (`Use for:`, `Not for:`, `Emphasis:`) opens a line
-    of the description and every other line continues the one above it, so the
-    comment wraps in the source and still reads as its four lines here. */
-function descriptionOf(source) {
-  const m = source.match(/^\s*<!--([\s\S]*?)-->/);
-  if (!m) return '';
-  const lines = [];
-  for (const raw of m[1].split('\n')) {
-    const line = raw.trim().replace(/\s+/g, ' ');
-    if (!line) continue;
-    if (lines.length && !/^[A-Z][A-Za-z ]{0,20}:/.test(line)) lines[lines.length - 1] += ` ${line}`;
-    else lines.push(line);
+import { join, relative } from 'node:path';
+import { CONTRACT_SCALES, PKG_ROOT } from './tokenVocabulary.mjs';
+
+const PKG = '@motion-proto/live-tokens';
+
+// The one deep import with a public equivalent: a component by file.
+const DEEP_COMPONENT = new RegExp(`^${PKG}/src/system/components/([A-Za-z0-9]+\\.svelte)$`);
+
+let subpaths = null;
+
+/** Everything the package's `exports` map makes importable, as specifiers. */
+export function publicSubpaths() {
+  if (subpaths) return subpaths;
+  try {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+    subpaths = Object.keys(pkg.exports ?? {}).map((key) => (key === '.' ? PKG : `${PKG}/${key.slice(2)}`));
+  } catch {
+    subpaths = [];
   }
-  if (lines.length) lines[0] = lines[0].replace(/^\S+\.svelte\s*(?:[—–-]+|\.)\s*/, '');
-  return lines.join('\n');
+  return subpaths;
+}
+
+/**
+ * What a `deep-import` finding's repair needs. A component file has one public
+ * specifier, so the rewrite is mechanical; anything else reaches for internals
+ * that may have no public equivalent at all, which leaves the choice open.
+ */
+export function deepImportRepair(specifier) {
+  const m = DEEP_COMPONENT.exec(specifier);
+  if (!m) return { details: { specifier, exports: publicSubpaths() }, repair: 'choice' };
+  const publicSpecifier = `${PKG}/components/${m[1]}`;
+  return { details: { specifier, public: publicSpecifier, patch: { from: specifier, to: publicSpecifier } } };
+}
+
+const STRING_LITERAL = /'(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*"|`(?:[^`\\]|\\.)*`/;
+
+function literalValue(raw) {
+  const quote = raw[0];
+  const inner = raw.slice(1, -1);
+  if (quote === '`' && inner.includes('${')) return undefined;
+  return inner.replace(/\s+/g, ' ').trim();
+}
+
+// Brace matching skips over quoted literals so a `}` inside a description
+// (or a description containing a stray brace) never closes the object early.
+function findBalanced(text, openIndex) {
+  let depth = 0;
+  for (let i = openIndex; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "'" || ch === '"' || ch === '`') {
+      const quote = ch;
+      i++;
+      while (i < text.length && text[i] !== quote) i += text[i] === '\\' ? 2 : 1;
+      continue;
+    }
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) return { content: text.slice(openIndex + 1, i), end: i + 1 };
+    }
+  }
+  return null;
+}
+
+function parseFieldObject(body) {
+  const fields = {};
+  const re = new RegExp(`([A-Za-z_$][A-Za-z0-9_$]*)\\s*:\\s*(${STRING_LITERAL.source})`, 'g');
+  let m;
+  while ((m = re.exec(body))) {
+    if (m[1] in fields) continue;
+    const value = literalValue(m[2]);
+    if (value !== undefined) fields[m[1]] = value;
+  }
+  return fields;
+}
+
+/**
+ * Bounded, non-evaluating parse of the runtime file's `catalogue` export:
+ * `key: <string literal>` pairs inside the `<script module>` block's
+ * `export const catalogue = { ... }`, the same way `builtInIds` and
+ * `componentProps` read the rest of the vocabulary without importing the
+ * module. A field given as an identifier, a template with `${}`, or a
+ * concatenation is not a string literal, so it is silently absent rather
+ * than evaluated. Returns `null` when the file has no such export.
+ */
+export function catalogueOf(source) {
+  const moduleBlock = source.match(/<script\s+module[^>]*>([\s\S]*?)<\/script>/);
+  if (!moduleBlock) return null;
+  const exportMatch = /export\s+const\s+catalogue\s*=\s*\{/.exec(moduleBlock[1]);
+  if (!exportMatch) return null;
+  const openIndex = exportMatch.index + exportMatch[0].length - 1;
+  const balanced = findBalanced(moduleBlock[1], openIndex);
+  if (!balanced) return null;
+
+  let body = balanced.content;
+  let props;
+  const propsMatch = /\bprops\s*:\s*\{/.exec(body);
+  if (propsMatch) {
+    const propsOpen = propsMatch.index + propsMatch[0].length - 1;
+    const propsBalanced = findBalanced(body, propsOpen);
+    if (propsBalanced) {
+      const parsedProps = parseFieldObject(propsBalanced.content);
+      if (Object.keys(parsedProps).length) props = parsedProps;
+      body = body.slice(0, propsMatch.index) + body.slice(propsBalanced.end);
+    }
+  }
+
+  const fields = parseFieldObject(body);
+  const catalogue = {
+    description: fields.description,
+    useFor: fields.useFor,
+    notFor: fields.notFor,
+  };
+  if (props) catalogue.props = props;
+  return catalogue;
 }
 
 function scaleOf(name) {
@@ -33,6 +129,41 @@ function scaleOf(name) {
   return hit ?? stem.split('-')[0];
 }
 
+// Cached per vocabulary: a checker asks for a scale once per finding, and the
+// values come from re-reading tokens.css.
+const scalesCache = new WeakMap();
+
+/**
+ * Every design token grouped by its scale, each with the value tokens.css
+ * declares for it. The candidates a `color-literal` or `dimension-literal`
+ * repair picks from, and what `describeTokens` prints.
+ */
+export function tokenScales(vocab) {
+  const cached = scalesCache.get(vocab);
+  if (cached) return cached;
+
+  const values = new Map();
+  if (vocab.tokensCssPath) {
+    const css = readFileSync(vocab.tokensCssPath, 'utf8').replace(/\/\*[\s\S]*?\*\//g, ' ');
+    for (const m of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      if (!values.has(m[1])) values.set(m[1], m[2].trim());
+    }
+  }
+  const byScale = new Map();
+  for (const name of vocab.themeTokens) {
+    const scale = scaleOf(name);
+    if (!byScale.has(scale)) byScale.set(scale, []);
+    byScale.get(scale).push({ name, value: values.get(name) ?? '' });
+  }
+  scalesCache.set(vocab, byScale);
+  return byScale;
+}
+
+/** One scale's tokens, empty when the project has no such scale. */
+export function scaleTokens(vocab, scale) {
+  return (scale && tokenScales(vocab).get(scale)) || [];
+}
+
 export function describeComponents(vocab, { root = process.cwd() } = {}) {
   const out = [];
   for (const entry of vocab.components.values()) {
@@ -50,7 +181,7 @@ export function describeComponents(vocab, { root = process.cwd() } = {}) {
       origin: entry.origin,
       file: relative(root, entry.file),
       registered: vocab.builtIn.has(entry.id) || vocab.registered.has(entry.id),
-      description: descriptionOf(source),
+      catalogue: catalogueOf(source),
       variants: entry.props?.enums.get('variant') ? [...entry.props.enums.get('variant')] : [],
       props,
       tokens: [...entry.tokens].map(([name, value]) => ({ name, default: value })),
@@ -60,22 +191,9 @@ export function describeComponents(vocab, { root = process.cwd() } = {}) {
 }
 
 export function describeTokens(vocab, { root = process.cwd() } = {}) {
-  const values = new Map();
-  if (vocab.tokensCssPath) {
-    const css = readFileSync(vocab.tokensCssPath, 'utf8').replace(/\/\*[\s\S]*?\*\//g, ' ');
-    for (const m of css.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
-      if (!values.has(m[1])) values.set(m[1], m[2].trim());
-    }
-  }
-  const byScale = new Map();
-  for (const name of vocab.themeTokens) {
-    const scale = scaleOf(name);
-    if (!byScale.has(scale)) byScale.set(scale, []);
-    byScale.get(scale).push({ name, value: values.get(name) ?? '' });
-  }
   return {
     tokensCss: vocab.tokensCssPath ? relative(root, vocab.tokensCssPath) : null,
-    scales: [...byScale].map(([scale, tokens]) => ({ scale, tokens })),
+    scales: [...tokenScales(vocab)].map(([scale, tokens]) => ({ scale, tokens })),
     components: [...vocab.components.values()].map((c) => ({
       id: c.id,
       tokens: [...c.tokens].map(([name, value]) => ({ name, default: value })),
@@ -83,7 +201,16 @@ export function describeTokens(vocab, { root = process.cwd() } = {}) {
   };
 }
 
-const describeLines = (c) => (c.description ? c.description.split('\n') : []);
+function describeLines(c) {
+  if (!c.catalogue) return [];
+  const { description, useFor, notFor, props } = c.catalogue;
+  const lines = [];
+  if (description) lines.push(description);
+  if (useFor) lines.push(`Use for: ${useFor}`);
+  if (notFor) lines.push(`Not for: ${notFor}`);
+  for (const [prop, text] of Object.entries(props ?? {})) lines.push(`${prop}: ${text}`);
+  return lines;
+}
 
 export function formatComponents(list, { id } = {}) {
   const lines = [];

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;
+  }
+}