@motion-proto/live-tokens 0.78.0 → 0.80.0

package/bin/lib/pageSource.mjs

@@ -0,0 +1,230 @@
+import { blankStrings } from './cssValues.mjs';
+
+/** Blank out comments, url() payloads, and string contents so none of them can match a rule. */
+export function neutralise(css) {
+  return blankStrings(
+    css
+      .replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length))
+      .replace(/url\((?:[^()]|\([^()]*\))*\)/g, (m) => ' '.repeat(m.length)),
+  );
+}
+
+/** `<style>` blocks with their absolute offset in the file; whole file for .css.
+ *  `site` is what a repair would edit, which the finding carries. */
+export function styleRegions(text, file) {
+  if (file.endsWith('.css')) return [{ text, offset: 0, site: 'declaration' }];
+  const out = [];
+  for (const m of text.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)) {
+    out.push({ text: m[1], offset: m.index + m[0].indexOf(m[1]), site: 'declaration' });
+  }
+  return out;
+}
+
+/**
+ * Inline styles in markup, as declaration lists the value rules can read: a
+ * `style="..."` attribute verbatim, and a `style:prop="value"` directive
+ * rewritten as `prop: value;`. A `{...}` expression is dynamic and skipped.
+ * The directive keeps its source text as `raw`, since the rewritten
+ * declaration is not text a patch would find on disk.
+ */
+export function inlineStyleRegions(code) {
+  const out = [];
+  for (const m of code.matchAll(/\sstyle=(["'])([^"']*)\1/g)) {
+    out.push({ text: `${m[2]};`, offset: m.index + m[0].indexOf(m[2]), site: 'attribute' });
+  }
+  for (const m of code.matchAll(/\sstyle:([a-z-]+)=(["'])([^"']*)\2/g)) {
+    out.push({ text: `${m[1]}: ${m[3]};`, offset: m.index + 1, site: 'directive', raw: m[0].slice(1) });
+  }
+  return out;
+}
+
+/** Everything outside `<style>`: script and markup. */
+export function codeRegion(text, file) {
+  if (file.endsWith('.css')) return null;
+  return text.replace(/<style[^>]*>[\s\S]*?<\/style>/g, (m) => ' '.repeat(m.length));
+}
+
+/**
+ * Declarations in a stylesheet, with at-rule preludes excluded. A breakpoint in
+ * `@media (max-width: 768px)` is structural geometry, not a themeable value.
+ * A property name is read from its start, so `--heading-2xl` is one custom
+ * property and never the property `xl`.
+ */
+export function declarations(css) {
+  const body = css.replace(/@[a-z-]+[^;{]*(?=\{)/gi, (m) => ' '.repeat(m.length));
+  const out = [];
+  for (const m of body.matchAll(/(?<![\w-])((?:--)?[a-z][\w-]*)\s*:\s*([^;{}]+)[;}]/gi)) {
+    out.push({ prop: m[1].toLowerCase(), value: m[2].trim(), index: m.index, text: m[0].slice(0, -1).trimEnd() });
+  }
+  return out;
+}
+
+/** Each custom property the regions declare, passed to `at` with its offset in
+ *  the file, its region's site, and the neutralised text from the match on,
+ *  which a deletion patch bounds itself against. */
+export function styleBlockDeclarations(regionList, at) {
+  for (const region of regionList) {
+    const clean = neutralise(region.text);
+    for (const m of clean.matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gim)) {
+      at(m[1], region.offset + m.index, region.site, clean.slice(m.index));
+    }
+  }
+}
+
+/**
+ * Every custom property a page declares, at the earliest offset it appears. A
+ * page may also mint one outside its <style> block, in a `style:--x={...}`
+ * directive or an el.style.setProperty call, and those are just as declared as
+ * one written in CSS. A bare quoted name counts too, so a name the page only
+ * reads through getPropertyValue("--x") is never an unknown token.
+ */
+export function pageDeclaredNames(text, regions) {
+  const sites = new Map();
+  const declareAt = (name, index) => {
+    if (!sites.has(name) || index < sites.get(name)) sites.set(name, index);
+  };
+  styleBlockDeclarations(regions, declareAt);
+  for (const m of text.matchAll(/(?:style:|setProperty\(\s*['"`]|['"`])(--[a-z0-9-]+)/g)) {
+    declareAt(m[1], m.index);
+  }
+  return sites;
+}
+
+/** A dimension-literal patch anchored at the declaration the finding names:
+ *  its property through its value in a style block or a `style` attribute,
+ *  or the whole `style:` directive. A value-only patch (`8px` → `var(...)`)
+ *  applied at the first `8px` at or after the finding's line, which in
+ *  `width: 8px; padding: 8px` was a property the rule never flags. No patch
+ *  when the source under the declaration differs from the text the census
+ *  read (a comment or a string the neutralised copy blanked), since a `from`
+ *  built from the blanked copy would never match the file. */
+export function declarationPatch(text, region, decl, rewritten) {
+  if (region.site === 'directive') {
+    const from = region.raw;
+    const quote = from.at(-1);
+    const open = from.indexOf(quote);
+    const inner = from.slice(open + 1, -1);
+    if (inner.trim() !== decl.value) return null;
+    return { from, to: from.slice(0, open + 1) + inner.replace(decl.value, rewritten) + quote };
+  }
+  const start = region.offset + decl.index;
+  const from = text.slice(start, start + decl.text.length);
+  if (from !== decl.text) return null;
+  return { from, to: from.slice(0, -decl.value.length) + rewritten };
+}
+
+/**
+ * The attributes of one component tag starting at `start` (the `<`), read with
+ * `{}` depth and quotes tracked so an expression holding `>` does not end the
+ * tag early. Returns null when the tag spreads an object, which makes its prop
+ * set unknowable.
+ */
+export function tagAttributes(code, start) {
+  const tagEnd = (() => {
+    let depth = 0;
+    let quote = null;
+    for (let j = start; j < code.length; j++) {
+      const c = code[j];
+      if (quote) {
+        if (c === quote) quote = null;
+      } else if (c === '"' || c === "'") quote = c;
+      else if (c === '{') depth++;
+      else if (c === '}') depth--;
+      else if (c === '>' && depth === 0) return j;
+    }
+    return code.length;
+  })();
+  // The tag name carries no whitespace of its own, so the first whitespace
+  // character at or after `start` — space, tab, or a wrapped newline — is
+  // always the boundary right after it, never only a literal space on the
+  // same line.
+  let i = -1;
+  for (let k = start; k < tagEnd; k++) {
+    if (/\s/.test(code[k])) {
+      i = k;
+      break;
+    }
+  }
+  if (i === -1) return { attrs: [], end: tagEnd };
+  const attrs = [];
+  while (i < tagEnd) {
+    const c = code[i];
+    if (/\s/.test(c) || c === '/') {
+      i++;
+      continue;
+    }
+    if (c === '{') {
+      let depth = 0;
+      let j = i;
+      for (; j < tagEnd; j++) {
+        if (code[j] === '{') depth++;
+        else if (code[j] === '}' && --depth === 0) break;
+      }
+      const inner = code.slice(i + 1, j).trim();
+      if (inner.startsWith('...')) return null;
+      if (/^\w+$/.test(inner)) attrs.push({ name: inner, value: null, index: i, end: j + 1 });
+      i = j + 1;
+      continue;
+    }
+    const name = code.slice(i).match(/^[^\s=/>]+/)?.[0];
+    if (!name) break;
+    const at = i;
+    i += name.length;
+    // Horizontal whitespace around `=` reads as the same attribute — Svelte
+    // itself accepts `size = "small"` — but a newline on either side does
+    // not: that's a bare boolean attribute followed by unrelated markup.
+    let j = i;
+    while (j < tagEnd && /[^\S\n]/.test(code[j])) j++;
+    let value = null;
+    if (code[j] === '=') {
+      i = j + 1;
+      while (i < tagEnd && /[^\S\n]/.test(code[i])) i++;
+      const q = code[i];
+      if (q === '"' || q === "'") {
+        const close = code.indexOf(q, i + 1);
+        value = code.slice(i + 1, close === -1 ? tagEnd : close);
+        i = close === -1 ? tagEnd : close + 1;
+      } else if (q === '{') {
+        let depth = 0;
+        for (; i < tagEnd; i++) {
+          if (code[i] === '{') depth++;
+          else if (code[i] === '}' && --depth === 0) break;
+        }
+        i++;
+      } else {
+        const bare = code.slice(i).match(/^[^\s>]+/)?.[0] ?? '';
+        value = bare;
+        i += bare.length;
+      }
+    }
+    // `end` marks where this attribute's own text stops, so a fixer can delete
+    // exactly it without disturbing whatever follows in the tag.
+    attrs.push({ name, value, index: at, end: i });
+  }
+  return { attrs, end: tagEnd };
+}
+
+/**
+ * `{@html ...}` blanked, brace-balanced, so a tag textually present inside a
+ * raw HTML string is not mistaken for markup the page authored.
+ */
+export function blankHtmlExpressions(code) {
+  let out = code;
+  const re = /\{@html\b/g;
+  let m;
+  while ((m = re.exec(out)) !== null) {
+    const start = m.index;
+    let depth = 0;
+    let i = start;
+    for (; i < out.length; i++) {
+      if (out[i] === '{') depth++;
+      else if (out[i] === '}' && --depth === 0) {
+        i++;
+        break;
+      }
+    }
+    out = out.slice(0, start) + ' '.repeat(i - start) + out.slice(i);
+    re.lastIndex = start;
+  }
+  return out;
+}

package/bin/lib/report.mjs

@@ -9,29 +9,6 @@ import { relative } from 'node:path';
 import { COMPONENT_RULES, checkComponent, discoverComponents } from '../check-component.mjs';
 import { COMPONENT_IMPORT, PAGE_RULES, checkPages, discoverPages } from '../check-page.mjs';
 import { applySeverity, readChecksConfig } from './findings.mjs';
-import { extractGlobalRootBlocks } from './tokenVocabulary.mjs';
-
-const SIDES = ['-top', '-right', '-bottom', '-left'];
-
-/**
- * Tokens a component declares that nothing in its 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 token 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 = SIDES.find((s) => name.endsWith(s));
-    return !isRead(name) && !(side && isRead(name.slice(0, -side.length)));
-  });
-}
 
 function countByRule(findings) {
   const out = {};
@@ -39,34 +16,50 @@ function countByRule(findings) {
   return out;
 }
 
-function summarise(findings, rules, config) {
-  const resolved = applySeverity(findings, rules, {}, config);
-  const strict = applySeverity(findings, rules, { strict: true }, config);
+const SEVERITY_ORDER = { error: 0, warn: 1 };
+
+/**
+ * Errors first, then the rule with the most findings, then file and line. The
+ * rule tiebreak keeps one rule's findings together when two rules tie on count,
+ * so the list reads as a fix list rather than a file listing.
+ */
+function sortFindings(findings) {
+  const counts = countByRule(findings);
+  return [...findings].sort(
+    (a, b) =>
+      SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
+      counts[b.rule] - counts[a.rule] ||
+      a.rule.localeCompare(b.rule) ||
+      a.file.localeCompare(b.file) ||
+      a.line - b.line,
+  );
+}
+
+function summarise(findings, rules, config, exclude) {
+  const resolved = sortFindings(applySeverity(findings, rules, {}, config, { exclude }));
+  const strict = applySeverity(findings, rules, { strict: true }, config, { exclude });
   return {
     errors: resolved.filter((f) => f.severity === 'error').length,
     warnings: resolved.filter((f) => f.severity === 'warn').length,
     strictErrors: strict.filter((f) => f.severity === 'error').length,
     byRule: countByRule(resolved),
-    items: resolved.map((f) => ({ rule: f.rule, severity: f.severity, file: f.file, line: f.line, message: f.message })),
+    items: resolved,
   };
 }
 
 export function buildReport(vocab, { root = process.cwd() } = {}) {
   const config = readChecksConfig(root);
 
-  const components = [...vocab.components.values()].map((c) => {
-    const source = readFileSync(c.file, 'utf8');
-    return {
-      id: c.id,
-      name: c.name,
-      origin: c.origin,
-      file: relative(root, c.file),
-      registered: vocab.builtIn.has(c.id) || vocab.registered.has(c.id),
-      described: /^\s*<!--[\s\S]*?-->/.test(source),
-      tokens: c.tokens.size,
-      unread: unreadTokens(source, c.tokens.keys()),
-    };
-  });
+  // What a component is, as facts. What is wrong with it is a finding:
+  // unread properties, a missing description, and an unregistered project
+  // component are rules now, each carrying its own severity and repair.
+  const components = [...vocab.components.values()].map((c) => ({
+    id: c.id,
+    origin: c.origin,
+    file: relative(root, c.file),
+    registered: vocab.builtIn.has(c.id) || vocab.registered.has(c.id),
+    tokens: c.tokens.size,
+  }));
 
   const pageFiles = discoverPages(root);
   const byPage = [];
@@ -92,6 +85,9 @@ export function buildReport(vocab, { root = process.cwd() } = {}) {
   const authored = discoverComponents(root);
   const componentFindings = authored.flatMap((id) => checkComponent(id, root, { vocabulary: vocab }).findings);
 
+  // Key order is the order a reader takes the report in, and `migrations` is
+  // filled by the caller (it needs the compiled engine), so it holds its place
+  // here rather than landing last.
   return {
     project: {
       root,
@@ -100,24 +96,29 @@ export function buildReport(vocab, { root = process.cwd() } = {}) {
       components: components.length,
       pages: pageFiles.length,
     },
+    migrations: null,
     components,
+    findings: {
+      pages: summarise(pageFindings, PAGE_RULES, config, true),
+      components: { checked: authored, ...summarise(componentFindings, COMPONENT_RULES, config) },
+    },
     usage: {
       byPage,
       byComponent,
       unusedShipped: byComponent.filter((c) => c.origin === 'shipped' && c.pages.length === 0).map((c) => c.id),
-      customUnregistered: components.filter((c) => c.origin === 'custom' && !c.registered).map((c) => c.id),
       customUnused: byComponent.filter((c) => c.origin === 'custom' && c.pages.length === 0).map((c) => c.id),
     },
-    findings: {
-      pages: summarise(pageFindings, PAGE_RULES, config),
-      components: { checked: authored, ...summarise(componentFindings, COMPONENT_RULES, config) },
-    },
   };
 }
 
 const list = (items, max = 20) =>
   items.length <= max ? items.join(', ') : `${items.slice(0, max).join(', ')}, +${items.length - max} more`;
 
+/** How a rule's findings are repaired. A rule that lowered its repair on some
+ *  of them names both, so the line never overstates what code can do. */
+const repairsFor = (items, rule) =>
+  [...new Set(items.filter((f) => f.rule === rule).map((f) => f.repair))].sort().join('/');
+
 export function formatReport(r) {
   const out = [];
   out.push(`Project: ${r.project.pages} page file(s), ${r.project.components} component(s), ${r.project.themeTokens} design tokens from ${r.project.tokensCss ?? '(no tokens.css)'}`);
@@ -128,14 +129,19 @@ export function formatReport(r) {
 
   out.push('');
   out.push('Components');
-  const unread = r.components.filter((c) => c.unread.length);
-  out.push(`  tokens declared and read by their own CSS: ${r.components.reduce((n, c) => n + c.tokens - c.unread.length, 0)} of ${r.components.reduce((n, c) => n + c.tokens, 0)}`);
-  for (const c of unread) out.push(`    ${c.id}: ${c.unread.length} unread (${list(c.unread, 6)})`);
-  const undescribed = r.components.filter((c) => !c.described).map((c) => c.id);
-  if (undescribed.length) out.push(`  no description comment: ${list(undescribed)}`);
+  out.push(`  semantic properties declared: ${r.components.reduce((n, c) => n + c.tokens, 0)}`);
   const custom = r.components.filter((c) => c.origin === 'custom');
   out.push(`  custom: ${custom.length}${custom.length ? ` (${list(custom.map((c) => c.id))})` : ''}`);
-  if (r.usage.customUnregistered.length) out.push(`    not registered: ${list(r.usage.customUnregistered)}`);
+
+  const section = (label, s) => {
+    out.push('');
+    out.push(`${label}: ${s.errors} error(s), ${s.warnings} warning(s); ${s.strictErrors} under --strict`);
+    for (const [rule, n] of Object.entries(s.byRule).sort((a, b) => b[1] - a[1])) {
+      out.push(`  ${rule}: ${n}  [${repairsFor(s.items, rule)}]`);
+    }
+  };
+  section('check-page', r.findings.pages);
+  section(`check-component (${r.findings.components.checked.length} authored)`, r.findings.components);
 
   out.push('');
   out.push('Usage');
@@ -146,13 +152,5 @@ export function formatReport(r) {
   out.push(`  pages rendering no catalogue component: ${r.usage.byPage.filter((p) => p.components.length === 0).length}`);
   out.push(`  shipped components used nowhere: ${r.usage.unusedShipped.length}${r.usage.unusedShipped.length ? ` (${list(r.usage.unusedShipped)})` : ''}`);
   if (r.usage.customUnused.length) out.push(`  custom components used nowhere: ${list(r.usage.customUnused)}`);
-
-  const section = (label, s) => {
-    out.push('');
-    out.push(`${label}: ${s.errors} error(s), ${s.warnings} warning(s); ${s.strictErrors} under --strict`);
-    for (const [rule, n] of Object.entries(s.byRule).sort((a, b) => b[1] - a[1])) out.push(`  ${rule}: ${n}`);
-  };
-  section('check-page', r.findings.pages);
-  section(`check-component (${r.findings.components.checked.length} authored)`, r.findings.components);
   return out.join('\n');
 }

package/bin/lib/tokenVocabulary.mjs

@@ -16,7 +16,7 @@
 // Reads files only. Nothing here may import dist-plugin at module top: CI runs
 // the suite before the plugin is built (see bin/engineLoadsLazily.test.ts).
 
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveTokensCssPath } from '../migrate.mjs';
@@ -25,9 +25,20 @@ const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
 
 const SHIPPED_COMPONENTS_DIR = 'src/system/components';
 
-/** Token scales whose names are governed by the token contract (see TOKENS.md). */
+// Shipped components keep their editor beside the other editors; a
+// consumer-authored one sits next to its runtime. Probe both.
+export const EDITOR_DIRS = ['src/system/components', 'src/editor/component-editor'];
+
+function capitalize(id) {
+  return id.charAt(0).toUpperCase() + id.slice(1);
+}
+
+/** Token scales whose names are governed by the token contract (see TOKENS.md).
+ *  `border-width` stands apart from `border` because the two measure different
+ *  things: a stroke's width resolves on a length scale, its paint on a colour
+ *  one, and a repair that offered the other's tokens would be nonsense. */
 export const CONTRACT_SCALES = [
-  'surface', 'text', 'border', 'color', 'space', 'radius', 'font', 'line-height',
+  'surface', 'text', 'border', 'border-width', 'color', 'space', 'radius', 'font', 'line-height',
   'letter-spacing', 'shadow', 'blur', 'icon-size', 'scrim', 'tint', 'columns',
   'heading', 'body', 'editorial', 'eyebrow', 'code', 'easing', 'duration', 'zoom',
   'gradient', 'stroke',
@@ -144,26 +155,6 @@ function walk(dir, exts, out = []) {
   return out;
 }
 
-function componentFiles(roots) {
-  const seen = new Set();
-  const files = [];
-  for (const dir of roots) {
-    for (const file of walk(dir, ['.svelte'])) {
-      if (file.endsWith('Editor.svelte')) continue;
-      let key = file;
-      try {
-        key = realpathSync(file);
-      } catch {
-        // unreadable link; fall back to the path itself
-      }
-      if (seen.has(key)) continue;
-      seen.add(key);
-      files.push(file);
-    }
-  }
-  return files;
-}
-
 /** The package's own component ids, read from the frozen registry that declares
     them. A shipped component is registered by the package rather than by the
     project, so it never appears in the project's own `registerComponent` scan. */
@@ -197,6 +188,73 @@ function registeredIds(root) {
   return ids;
 }
 
+/**
+ * Every component this project can resolve on its own: a runtime under
+ * `src/system/components` or a configured `componentDirs` entry, plus every
+ * id `registeredIds` finds with no runtime anywhere, so a dangling
+ * registration is a fact in the inventory rather than a silent gap.
+ *
+ * Deliberately never looks under `pkgRoot` for a shipped id a project hasn't
+ * vendored — that is `resolveComponentPaths`'s own fallback for a single
+ * named id, not a batch this inventory would run over (a consumer's batch is
+ * their own components only; shipped runtimes sit in node_modules, where no
+ * inventory looks).
+ *
+ * The single scan every caller reads: `report`, the `check-component` batch,
+ * `resolveComponentPaths`, and the `components` verb.
+ */
+export function componentInventory(root = process.cwd(), pkgRoot = PKG_ROOT) {
+  const built = builtInIds(root, pkgRoot);
+  const registered = registeredIds(root);
+  const dirs = [SHIPPED_COMPONENTS_DIR, ...(readProjectConfig(root).componentDirs ?? [])];
+  const entries = new Map();
+
+  const guessEditorPath = (Id) =>
+    EDITOR_DIRS.map((d) => join(root, d, `${Id}Editor.svelte`)).find(existsSync) ??
+    join(root, EDITOR_DIRS[0], `${Id}Editor.svelte`);
+
+  for (const dirRel of dirs) {
+    const dir = join(root, dirRel);
+    if (!existsSync(dir)) continue;
+    for (const file of walk(dir, ['.svelte'])) {
+      const fileName = file.slice(file.lastIndexOf('/') + 1);
+      if (fileName.endsWith('Editor.svelte')) continue;
+      const Id = fileName.replace('.svelte', '');
+      const id = Id.toLowerCase();
+      if (entries.has(id)) continue;
+      const editorPath = guessEditorPath(Id);
+      entries.set(id, {
+        id,
+        Id,
+        origin: built.has(id) ? 'shipped' : 'custom',
+        runtimePath: file,
+        editorPath,
+        registered: built.has(id) || registered.has(id),
+        runtimeExists: true,
+        editorExists: existsSync(editorPath),
+      });
+    }
+  }
+
+  for (const id of registered) {
+    if (entries.has(id)) continue;
+    const Id = capitalize(id);
+    const editorPath = guessEditorPath(Id);
+    entries.set(id, {
+      id,
+      Id,
+      origin: built.has(id) ? 'shipped' : 'custom',
+      runtimePath: join(root, SHIPPED_COMPONENTS_DIR, `${Id}.svelte`),
+      editorPath,
+      registered: true,
+      runtimeExists: false,
+      editorExists: existsSync(editorPath),
+    });
+  }
+
+  return entries;
+}
+
 /**
  * Build the vocabulary for `root` (a consumer project, or this repo).
  *
@@ -217,12 +275,26 @@ export function loadVocabulary({ root = process.cwd(), pkgRoot = PKG_ROOT } = {}
 
   const componentTokens = new Set();
   const components = new Map();
-  // A project's own components sit beside the shipped ones, plus any directory
-  // `componentDirs` in live-tokens.config.json names.
-  const own = [SHIPPED_COMPONENTS_DIR, ...(readProjectConfig(root).componentDirs ?? [])].map((d) => join(root, d));
-  const shippedDir = join(pkgRoot, SHIPPED_COMPONENTS_DIR);
-  const dirs = [shippedDir, ...own];
-  for (const file of componentFiles(dirs)) {
+  const registered = registeredIds(root);
+  const builtIn = builtInIds(root, pkgRoot);
+
+  // The package's shipped directory first, so a shipped component's tokens
+  // are in the vocabulary even when a project hasn't vendored it — the one
+  // gap the inventory itself deliberately leaves, since it never looks under
+  // `pkgRoot`. Then the project's own inventory (its `src/system/components`
+  // plus any `componentDirs`), which overrides by id: a project's own copy of
+  // a shipped component wins over the package's. Reusing the inventory here,
+  // instead of a second directory scan, is what keeps `report.components` and
+  // `report.findings.components.checked` naming the same ids.
+  const filesById = new Map();
+  for (const entry of componentInventory(pkgRoot, pkgRoot).values()) {
+    if (entry.runtimeExists) filesById.set(entry.id, entry.runtimePath);
+  }
+  for (const entry of componentInventory(root, pkgRoot).values()) {
+    if (entry.runtimeExists) filesById.set(entry.id, entry.runtimePath);
+  }
+
+  for (const [id, file] of filesById) {
     const Id = file.slice(file.lastIndexOf('/') + 1).replace('.svelte', '');
     const src = readFileSync(file, 'utf8');
     const tokens = new Map();
@@ -231,17 +303,15 @@ export function loadVocabulary({ root = process.cwd(), pkgRoot = PKG_ROOT } = {}
       for (const n of declaredCustomProperties(clean)) componentTokens.add(n);
       for (const m of clean.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) if (!tokens.has(m[1])) tokens.set(m[1], m[2].trim());
     }
-    components.set(Id.toLowerCase(), {
-      id: Id.toLowerCase(),
+    components.set(id, {
+      id,
       name: Id,
       file,
-      origin: file.startsWith(shippedDir) ? 'shipped' : 'custom',
+      origin: builtIn.has(id) ? 'shipped' : 'custom',
       props: componentProps(src),
       tokens,
     });
   }
-  const registered = registeredIds(root);
-  const builtIn = builtInIds(root, pkgRoot);
 
   return {
     themeTokens,

package/bin/migrate-build-script.mjs

@@ -0,0 +1,66 @@
+// `live-tokens migrate` build-script pass.
+//
+// Through 0.79 the project template, and the check-compliance skill for an
+// existing project, ran both checkers as `npm run check:design` ahead of
+// `vite build`. themeFileApi now runs them during `vite build` itself, so the
+// script only repeats the work. This pass removes it when package.json holds
+// exactly what the template and the skill wrote and the build still gets the
+// checks from the plugin. Anything else is reported and left alone.
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const SCRIPT = 'check:design';
+const SHIPPED_SCRIPT = /^(npx )?live-tokens check-page --no-fix && (npx )?live-tokens check-component --no-fix$/;
+const BUILD_PREFIX = /^npm run check:design\s*&&\s*/;
+const VITE_CONFIGS = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.mts'];
+
+function viteConfigText(root) {
+  const file = VITE_CONFIGS.map((name) => join(root, name)).find((p) => existsSync(p));
+  return file ? readFileSync(file, 'utf8') : '';
+}
+
+export function runMigrateBuildScript({ root = process.cwd(), apply = true } = {}) {
+  const file = join(root, 'package.json');
+  if (!existsSync(file)) return { status: 'unchanged' };
+  const text = readFileSync(file, 'utf8');
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    return { status: 'unchanged' };
+  }
+  const scripts = pkg.scripts ?? {};
+  if (!(SCRIPT in scripts)) return { status: 'unchanged' };
+
+  const vite = viteConfigText(root);
+  if (!vite.includes('themeFileApi')) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": the Vite config does not use themeFileApi, so the build has no other design checks.` };
+  }
+  if (/checks\s*:\s*false/.test(vite)) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": themeFileApi is set to checks: false.` };
+  }
+  if (!SHIPPED_SCRIPT.test(String(scripts[SCRIPT]).trim())) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": it differs from the script live-tokens added. vite build now runs the design checks, so remove it by hand if it only repeats them.` };
+  }
+  const build = String(scripts.build ?? '');
+  const users = Object.keys(scripts).filter((name) => name !== SCRIPT && name !== 'build' && String(scripts[name]).includes(SCRIPT));
+  if (build.includes(SCRIPT) && !BUILD_PREFIX.test(build)) users.push('build');
+  if (users.length > 0) {
+    return { status: 'advisory', reason: `keeps "${SCRIPT}": ${users.map((u) => `"${u}"`).join(', ')} still run${users.length === 1 ? 's' : ''} it.` };
+  }
+
+  if (!apply) return { status: 'would-change' };
+  if (BUILD_PREFIX.test(build)) scripts.build = build.replace(BUILD_PREFIX, '');
+  delete scripts[SCRIPT];
+  const indent = /^([ \t]+)"/m.exec(text)?.[1] ?? '  ';
+  writeFileSync(file, JSON.stringify(pkg, null, indent) + (text.endsWith('\n') ? '\n' : ''));
+  return { status: 'changed' };
+}
+
+export function formatBuildScriptResult(result) {
+  if (result.status === 'changed') return `✓ package.json: removed "${SCRIPT}" from the build. vite build runs the design checks through themeFileApi.`;
+  if (result.status === 'would-change') return `package.json: would remove "${SCRIPT}" from the build. vite build runs the design checks through themeFileApi.`;
+  if (result.status === 'advisory') return `! package.json ${result.reason}`;
+  return '';
+}

package/bin/migrate.mjs

@@ -37,6 +37,11 @@ async function loadEngine() {
   return import(ENGINE);
 }
 
+/** Null only before build:plugin, which is this repo's own `npm test` in CI; a published package always ships the engine. */
+export async function loadBuiltEngine() {
+  return existsSync(ENGINE) ? import(ENGINE) : null;
+}
+
 /** --tokens <path> > live-tokens.config.json tokensCssPath > default scan. */
 export function resolveTokensCssPath(explicit, configPath, root = process.cwd()) {
   if (explicit) return resolve(root, explicit);