@motion-proto/live-tokens 0.78.0 → 0.80.0

package/bin/cli.mjs

@@ -12,27 +12,31 @@
 //   set-geometry <ops>       Apply radius/padding/gap/border-width ops to the open buffer.
 //   set-type <pairing>       Bind Google Fonts families to the theme's font stacks.
 //   save-theme <name>        Compose the live state into themes/<slug>.json and open it.
-//   migrate [...]            Reconcile tokens.css, the data tree, and route references.
+//   migrate [...]            Reconcile tokens.css, the data tree, route references, and the build script.
 
 import { writeSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
-import { COMPONENT_RULES, COMPONENT_RULE_FIX, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
+import { COMPONENT_RULES, checkComponent, discoverComponents, formatReport } from './check-component.mjs';
 import { PAGE_RULES, checkPages, discoverPages } from './check-page.mjs';
 import { resolvePageTestTargets } from './lib/pageRoutes.mjs';
 import { describeComponents, describeTokens, formatComponents, formatTokens } from './lib/catalogue.mjs';
+import { applyFixes } from './lib/fixers.mjs';
 import { buildReport, formatReport as formatProjectReport } from './lib/report.mjs';
 import { loadVocabulary } from './lib/tokenVocabulary.mjs';
 import {
   applyCoverageSeverity,
   applySeverity,
   countBySeverity,
+  dedupeAliasFindings,
   formatFindings,
   parseCheckFlags,
   readChecksConfig,
+  resolveRuleSeverity,
   toJson,
 } from './lib/findings.mjs';
+import { checkTokensCssMigrations } from './rules/tokens.mjs';
 import {
   runMigrate,
   formatMigrateResult,
@@ -40,6 +44,7 @@ import {
   formatMigrateDataResult,
 } from './migrate.mjs';
 import { runMigrateRoutes, formatRouteResult } from './migrate-routes.mjs';
+import { runMigrateBuildScript, formatBuildScriptResult } from './migrate-build-script.mjs';
 import { runCreate, formatCreateResult } from './create.mjs';
 import { runSetupClaude, formatSetupResult } from './setup-claude.mjs';
 import { runSetColors, formatSetColorsResult } from './set-colors.mjs';
@@ -98,6 +103,16 @@ check-component and check-page also accept:
                               (or set "checks": { "rules": {...} } in
                               live-tokens.config.json; "checks": { "exclude":
                               [...] } drops paths from discovery entirely)
+  --no-fix                    Report every finding and edit nothing, for a
+                              build or CI. Without it, both checkers first
+                              apply every additive tokens.css migration and
+                              every finding whose repair is auto (a
+                              deep import into a component, a raw dimension
+                              with one nearest design token, a shipped
+                              component's size prop, a semantic property
+                              overridden in place), re-check, and list each
+                              fix beside what remains. --tests runs after
+                              the fixes land.
   set-colors <base-colors.json> [--dry-run]
                               Build the theme's whole color identity from 10
                               OKLCH base colors (see the live-tokens-set-colors
@@ -139,7 +154,8 @@ check-component and check-page also accept:
                               without writing.
   migrate [--check] [--write] [--tokens <path>]
                               Reconcile the project with the installed package:
-                              applies additive tokens.css migrations, moves a
+                              applies every tokens.css migration, breaking
+                              ones included, moves a
                               pre-0.48 data tree onto the current directory
                               names, heals what the retired pointer files named,
                               and reports source references to the
@@ -148,6 +164,9 @@ check-component and check-page also accept:
                               unambiguous route references (never /docs). --check
                               prints both plans without writing (exit 1 when
                               either is pending; route findings are advisory).
+                              Also removes the check:design script live-tokens
+                              added to the build, since vite build now runs the
+                              design checks through themeFileApi.
 `;
 
 // A large body written through console.log is cut at the pipe buffer when the
@@ -194,14 +213,14 @@ if (command === 'create') {
   }
 }
 
-function reportChecks(label, findings, checked, rules, opts, { coverage, hardFailure, fixes } = {}) {
+function reportChecks(label, findings, checked, rules, opts, { coverage, hardFailure, exclude, fix } = {}) {
   const checksConfig = readChecksConfig(process.cwd());
-  const resolved = applySeverity(findings, rules, opts, checksConfig, fixes ?? {});
+  const resolved = applySeverity(findings, rules, opts, checksConfig, { exclude });
   const resolvedCoverage = coverage ? applyCoverageSeverity(coverage, rules, opts, checksConfig) : coverage;
   console.log(
     opts.json
-      ? toJson(resolved, { label, checked, coverage: resolvedCoverage })
-      : formatFindings(resolved, { label, checked }),
+      ? toJson(resolved, { label, checked, coverage: resolvedCoverage, fix })
+      : [fix ? formatFixes(fix) : '', formatFindings(resolved, { label, checked })].filter(Boolean).join('\n'),
   );
   // Decision 2: a missing tool or a setup failure under --tests is an error
   // even if a project silenced its rule id, since silencing it would read as
@@ -209,6 +228,41 @@ function reportChecks(label, findings, checked, rules, opts, { coverage, hardFai
   process.exit(countBySeverity(resolved).errors === 0 && !hardFailure ? 0 : 1);
 }
 
+function shiftNote(f) {
+  if (f.rule !== 'dimension-literal') return '';
+  const shifts = f.details.literals.map((l) => l.candidates[0].shift).map((n) => `${n > 0 ? '+' : ''}${n}px`);
+  return `  shift ${shifts.join(', ')}`;
+}
+
+async function migrateTokensCss(rules, opts) {
+  const root = process.cwd();
+  const config = readChecksConfig(root);
+  const apply = !opts.noFix && resolveRuleSeverity('tokens-migration', rules, opts, config) !== 'off';
+  const { applied, findings } = await checkTokensCssMigrations({ root, apply });
+  return { applied: applySeverity(applied, rules, opts, config), findings };
+}
+
+/** Resolves severities and exclusions first, so a silenced rule or an excluded
+ *  file is never edited. */
+function applyStaticFixes(findings, rules, opts, { exclude } = {}) {
+  const root = process.cwd();
+  return applyFixes(applySeverity(findings, rules, opts, readChecksConfig(root), { exclude }), root);
+}
+
+function formatFixes({ applied, skipped }) {
+  const lines = [];
+  for (const f of applied) {
+    lines.push(
+      f.details.patch
+        ? `  fixed    ${f.file}:${f.line}  ${f.details.patch.from} → ${f.details.patch.to || '(removed)'}  [${f.rule}]${shiftNote(f)}`
+        : `  fixed    ${f.file}  ${f.details.migrations.map((m) => m.id).join(', ')}  [${f.rule}]`,
+    );
+  }
+  for (const f of skipped) lines.push(`  skipped  ${f.file}:${f.line}  ${f.details.patch.from}  [${f.rule}]`);
+  if (lines.length === 0) return '';
+  return [`${applied.length} fix(es) applied, ${skipped.length} skipped:`, ...lines, ''].join('\n');
+}
+
 if (command === 'components') {
   const opts = parseCheckFlags(rest);
   const list = describeComponents(loadVocabulary());
@@ -257,21 +311,28 @@ if (command === 'check-component') {
     console.log('✓ check-component: no component authored under src/system/components yet.');
     process.exit(0);
   }
-  const results = ids.map((id) => [id, checkComponent(id)]);
-  if (!opts.tests && ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
+  const migration = await migrateTokensCss(COMPONENT_RULES, opts);
+  let results = ids.map((id) => [id, checkComponent(id)]);
+  const label = ids.length === 1 ? `check-component ${ids[0]}${opts.tests ? ' --tests' : ''}` : `check-component${opts.tests ? ' --tests' : ''}`;
+  let fix;
+  if (!opts.noFix) {
+    fix = applyStaticFixes(results.flatMap(([, r]) => r.findings), COMPONENT_RULES, opts);
+    if (fix.applied.length > 0) results = ids.map((id) => [id, checkComponent(id)]);
+    fix.applied.unshift(...migration.applied);
+  }
+  if (!opts.tests && migration.findings.length === 0 && ids.length === 1 && !opts.json && !opts.strict && opts.off.length + opts.warn.length + opts.error.length === 0) {
     const [id, result] = results[0];
-    console.log(formatReport(id, result));
+    console.log([fix ? formatFixes(fix) : '', formatReport(id, result)].filter(Boolean).join('\n'));
     process.exit(result.errors.length === 0 ? 0 : 1);
   }
-  const label = ids.length === 1 ? `check-component ${ids[0]}${opts.tests ? ' --tests' : ''}` : `check-component${opts.tests ? ' --tests' : ''}`;
   if (!opts.tests) {
-    reportChecks(label, results.flatMap(([, r]) => r.findings), ids.length, COMPONENT_RULES, opts, { fixes: COMPONENT_RULE_FIX });
+    reportChecks(label, [...migration.findings, ...results.flatMap(([, r]) => r.findings)], ids.length, COMPONENT_RULES, opts, { fix });
   }
   const { hasHardFailure, runContractTests } = await import('./contractRunner.mjs');
   const testOutcome = await runContractTests(opts.rest[0], { root: process.cwd() });
-  const findings = [...results.flatMap(([, r]) => r.findings), ...testOutcome.findings];
+  const findings = dedupeAliasFindings([...migration.findings, ...results.flatMap(([, r]) => r.findings), ...testOutcome.findings]);
   reportChecks(label, findings, Math.max(ids.length, 1), COMPONENT_RULES, opts, {
-    fixes: COMPONENT_RULE_FIX,
+    fix,
     coverage: testOutcome.coverage,
     hardFailure: hasHardFailure(testOutcome.findings),
   });
@@ -280,9 +341,17 @@ if (command === 'check-component') {
 if (command === 'check-page') {
   const opts = parseCheckFlags(rest);
   const targets = opts.rest.length > 0 ? opts.rest : discoverPages(process.cwd());
-  const { findings, checked } = checkPages(targets, { root: process.cwd() });
+  const migration = await migrateTokensCss(PAGE_RULES, opts);
+  let { findings, checked } = checkPages(targets, { root: process.cwd() });
+  let fix;
+  if (!opts.noFix) {
+    fix = applyStaticFixes(findings, PAGE_RULES, opts, { exclude: true });
+    if (fix.applied.length > 0) ({ findings, checked } = checkPages(targets, { root: process.cwd() }));
+    fix.applied.unshift(...migration.applied);
+  }
+  findings = [...migration.findings, ...findings];
   if (!opts.tests) {
-    reportChecks('check-page', findings, checked, PAGE_RULES, opts);
+    reportChecks('check-page', findings, checked, PAGE_RULES, opts, { exclude: true, fix });
   }
   const { hasHardFailure, runPageTests } = await import('./contractRunner.mjs');
   const pageTargets = resolvePageTestTargets(opts.rest, process.cwd());
@@ -290,6 +359,8 @@ if (command === 'check-page') {
   const label = 'check-page --tests';
   const allFindings = [...findings, ...testOutcome.findings];
   reportChecks(label, allFindings, Math.max(checked, pageTargets.length), PAGE_RULES, opts, {
+    exclude: true,
+    fix,
     coverage: testOutcome.coverage,
     hardFailure: hasHardFailure(testOutcome.findings),
   });
@@ -412,6 +483,12 @@ if (command === 'migrate') {
     const routeOut = formatRouteResult(routes, { check });
     if (routeOut) console.log('\n' + routeOut);
 
+    // Build-script pass: removes the check:design step that themeFileApi now
+    // runs during vite build. Advisory under --check, like the data heal.
+    const buildScript = runMigrateBuildScript({ root: process.cwd(), apply: !check });
+    const buildScriptOut = formatBuildScriptResult(buildScript);
+    if (buildScriptOut) console.log('\n' + buildScriptOut);
+
     // Route findings are advisory; token migrations and the data heal gate the
     // exit code.
     if (result.status === 'no-path') process.exit(1);

package/bin/contractRunner.mjs

@@ -28,6 +28,7 @@ import { tmpdir } from 'node:os';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { discoverComponents, resolveComponentPaths } from './check-component.mjs';
+import { resolveSourceDataDir, scrapeSettingsField, settingsFilePath } from './lib/dataDir.mjs';
 import { lineOf } from './lib/findings.mjs';
 import { settingsPageViewports } from './lib/pageRoutes.mjs';
 
@@ -74,6 +75,7 @@ const HARD_FAILURE_RULES = new Set(['tests-not-installed', 'tests-setup', 'tests
  *  coverage against. */
 const ALL_CONTRACT_RULES = [
   'contract-registry',
+  'contract-behavior',
   'contract-listed',
   'contract-alias',
   'contract-states',
@@ -183,100 +185,10 @@ function resolveTestingEntry(name) {
   );
 }
 
-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. */
-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 --tests cannot read it statically. Use a literal string, or remove the key to fall back to the default.`,
-    );
-  }
-  return null;
-}
-
 function guessViteConfigPath(root, settingsPath) {
   return resolve(root, scrapeSettingsField(settingsPath, 'viteConfig') ?? 'vite.config.ts');
 }
 
-/**
- * `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 file already, at `SESSION_FILES`.
- */
-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');
-}
-
 // ─── data isolation ─────────────────────────────────────────────────────────
 
 function copyIsolatedDataDir(sourceDataDir) {
@@ -423,6 +335,7 @@ const settings = resolveTestingConfig(${settingsExpr}, ${JSON.stringify(root)});
 
 export default createVitestConfig(viteConfigModule.default ?? viteConfigModule, {
   registrySetup: settings.registrySetup,
+  contractsModule: settings.contractsModule,
 });
 `,
   );
@@ -945,6 +858,12 @@ export function mapRegistryViolation(root, sourceDataDir, componentId, text) {
   return { file: relative(root, target), line: findTokenLine(target, token) };
 }
 
+/** `component-behavior.contract.ts` shares the same `describe(id) > it(case)`
+ *  shape `registry.contract.ts` uses (see `structuralRule`'s Playwright
+ *  analogue), so the file name — not the describe titles — is what tells the
+ *  two suites' assertions apart. */
+const BEHAVIOR_FILE_PREFIX = 'component-behavior.contract';
+
 /** Mirrors the Playwright side's zero-collection check: a file that failed
  *  before it ran a single assertion (`assertionResults` empty, `status`
  *  'failed') carries its own `message` — measured against a bad
@@ -979,16 +898,43 @@ export function mapVitestResults(report, { root, sourceDataDir, stderr } = {}) {
   const coverage = {};
   for (const file of files) {
     if (collectionFailures.includes(file)) continue;
+    const isBehaviorFile = basename(file.name ?? '').startsWith(BEHAVIOR_FILE_PREFIX);
+    const passRule = isBehaviorFile ? 'contract-behavior' : 'contract-registry';
     for (const assertion of file.assertionResults ?? []) {
       const componentId = assertion.ancestorTitles.length >= 2 ? assertion.ancestorTitles[1] : null;
       if (assertion.status !== 'failed') {
         if (assertion.status === 'passed' && componentId) {
           coverage[componentId] ??= {};
-          coverage[componentId]['contract-registry'] = { status: 'passed' };
+          coverage[componentId][passRule] = { status: 'passed' };
         }
         continue;
       }
       const text = (assertion.failureMessages ?? []).join('\n');
+      // `component-behavior.contract.ts` throws `ContractViolation` directly
+      // rather than a registry-style violation array, and Vitest's own stack
+      // frames follow the message on their own line with no blank line
+      // between (measured; unlike Playwright's ANSI code frame), so only the
+      // first line is the message `messageBlock`'s blank-line split expects.
+      if (isBehaviorFile) {
+        const violation = VIOLATION_RE.exec(text.split('\n')[0].trim());
+        const finalRule = violation?.[1] ?? 'contract-behavior';
+        const id = violation?.[2] ?? componentId;
+        const message = violation?.[3] ?? text.split('\n')[0].trim();
+        const token = extractToken(message);
+        const { file: f, line } = artifactForContractRule(root, sourceDataDir, finalRule, id, token);
+        findings.push({
+          rule: finalRule,
+          file: f,
+          line,
+          message: id ? `${id}: ${message}` : message,
+          context: { suite: 'vitest', title: assertion.fullName },
+        });
+        if (id) {
+          coverage[id] ??= {};
+          coverage[id][finalRule] = { status: 'failed' };
+        }
+        continue;
+      }
       const violations = componentId ? extractViolationArray(text) : [];
       if (violations.length > 0) {
         for (const violation of violations) {

package/bin/lib/buildChecks.mjs

@@ -0,0 +1,32 @@
+// The design checks `vite build` runs through themeFileApi: both static
+// checkers with no repairs, under the project's own severities. The same bar
+// `check-page --no-fix` and `check-component --no-fix` hold.
+
+import { COMPONENT_RULES, checkComponent, discoverComponents } from '../check-component.mjs';
+import { PAGE_RULES, checkPages, discoverPages } from '../check-page.mjs';
+import { checkTokensCssMigrations } from '../rules/tokens.mjs';
+import { applySeverity, countBySeverity, formatFindings, readChecksConfig } from './findings.mjs';
+import { loadVocabulary } from './tokenVocabulary.mjs';
+
+export async function runBuildChecks({ root = process.cwd(), engine } = {}) {
+  const config = readChecksConfig(root);
+  const vocabulary = loadVocabulary({ root });
+  const migration = await checkTokensCssMigrations({ root, apply: false, engine });
+  const pages = checkPages(discoverPages(root), { root, vocabulary });
+  const ids = discoverComponents(root);
+  const components = ids.map((id) => checkComponent(id, root, { vocabulary }));
+
+  const pageFindings = applySeverity([...migration.findings, ...pages.findings], PAGE_RULES, {}, config, { exclude: true });
+  const componentFindings = applySeverity(components.flatMap((r) => r.findings), COMPONENT_RULES, {}, config);
+  const page = countBySeverity(pageFindings);
+  const component = countBySeverity(componentFindings);
+
+  return {
+    errors: page.errors + component.errors,
+    warnings: page.warnings + component.warnings,
+    report: [
+      formatFindings(pageFindings, { label: 'check-page', checked: pages.checked }),
+      formatFindings(componentFindings, { label: 'check-component', checked: ids.length }),
+    ].join('\n'),
+  };
+}

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 = [];