@motion-proto/live-tokens 0.78.0 → 0.80.0

package/bin/check-component.mjs

@@ -14,378 +14,119 @@
 //     token, so the component repaints when the theme changes. A value with no
 //     token behind it must be a declared intrinsic (a structural keyword the
 //     editor exports in `intrinsics`), never a literal.
+//   - every property the runtime declares is read by the runtime's own CSS
+//   - the runtime exports a `catalogue` the CLI and the registry both read
 //
 // Returns { errors, warnings, findings }. `errors`/`warnings` are the message
-// strings; `findings` carries the same items with a stable `rule` id and line
-// number for --json consumers.
-
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { extname, join, relative } from 'node:path';
-import { hasColorLiteral, hasDimensionLiteral, stripVarFallbacks } from './lib/cssValues.mjs';
-import { lineOf } from './lib/findings.mjs';
-import { PKG_ROOT, builtInIds, declaredCustomProperties, extractGlobalRootBlocks, isContractToken, loadVocabulary } from './lib/tokenVocabulary.mjs';
-
-export const COMPONENT_RULES = {
-  'invalid-id': 'error',
-  'missing-file': 'error',
-  'missing-root-block': 'error',
-  'no-tokens': 'error',
-  'state-after-property': 'error',
-  'disabled-is-terminal': 'error',
-  'unknown-suffix': 'error',
-  'phantom-editor-token': 'error',
-  'color-literal': 'error',
-  'missing-component-const': 'error',
-  'missing-all-tokens': 'error',
-  'deep-import': 'error',
-  'missing-registration': 'error',
-  'unknown-token-ref': 'error',
-  'default-not-token': 'error',
-  'phantom-link': 'warn',
-  'dimension-literal': 'warn',
-  // `--tests` (bin/contractRunner.mjs). Fixed by design decision 8 so
-  // `fix-findings` can map them; every one is an error, including the setup
-  // rules, which `--tests` treats as never-silenceable (see cli.mjs).
-  'contract-registry': 'error',
-  'contract-render': 'error',
-  'contract-alias': 'error',
-  'contract-persist': 'error',
-  'contract-theme': 'error',
-  'contract-states': 'error',
-  'contract-interaction': 'error',
-  'contract-listed': 'error',
-  'contract-sketch': 'error',
-  'contract-missing': 'error',
-  'tests-not-installed': 'error',
-  'tests-setup': 'error',
-  'tests-incomplete': 'error',
-};
+// strings; `findings` carries the same items with a stable `rule` id, a line
+// number, and, where a repair needs more than the message, `details`.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { declaredTokens, intrinsicMatchers } from './lib/componentSource.mjs';
+import { assembleRules, lineOf } from './lib/findings.mjs';
+import {
+  EDITOR_DIRS,
+  PKG_ROOT,
+  builtInIds,
+  componentInventory,
+  extractGlobalRootBlocks,
+  loadVocabulary,
+} from './lib/tokenVocabulary.mjs';
+import * as componentStructure from './rules/componentStructure.mjs';
+import * as importsAndRoutes from './rules/importsAndRoutes.mjs';
+import * as testRuns from './rules/testRuns.mjs';
+import * as tokenRules from './rules/tokens.mjs';
+
+export { unreadTokens } from './lib/componentSource.mjs';
 
 /**
- * Where a rule is fixed, as a stable slug carried on the finding. The skills
- * resolve the slug to one of their own headings, so adding a rule here costs
- * no skill edit as long as it reuses a slug. Two skills used to enumerate every
- * rule id in their own tables, with nothing holding the two in agreement or
- * checking either against this list.
+ * Every rule, with its default severity, its repair, and the guidance every
+ * finding of it carries.
+ *
+ * `repair` is the ceiling: `auto` when code can rewrite the site, `choice` when
+ * code can name the candidates but not pick one, `authored` when a person
+ * writes the repair. A finding may lower its rule's `repair`; none raises it.
  */
-export const COMPONENT_RULE_FIX = {
-  'unknown-suffix': 'property-name',
-  'state-after-property': 'property-name',
-  'disabled-is-terminal': 'property-name',
-  'default-not-token': 'property-token',
-  'color-literal': 'property-token',
-  'dimension-literal': 'property-token',
-  'unknown-token-ref': 'property-token',
-  'contract-theme': 'property-token',
-  'invalid-id': 'runtime',
-  'missing-file': 'runtime',
-  'missing-root-block': 'runtime',
-  'no-tokens': 'runtime',
-  'contract-persist': 'runtime-defaults',
-  'missing-component-const': 'editor',
-  'missing-all-tokens': 'editor',
-  'phantom-editor-token': 'editor',
-  'phantom-link': 'editor',
-  'deep-import': 'editor',
-  'contract-render': 'editor',
-  'contract-alias': 'editor',
-  'contract-states': 'editor',
-  'contract-interaction': 'editor',
-  'missing-registration': 'registration',
-  'contract-registry': 'registration',
-  'contract-listed': 'registration',
-  'contract-sketch': 'sketch',
-  'contract-missing': 'coverage',
-  'tests-not-installed': 'tooling',
-  'tests-setup': 'tooling',
-  'tests-incomplete': 'coverage',
-};
-
-// Shipped components keep their editor beside the other editors; a
-// consumer-authored one sits next to its runtime. Probe both.
-const EDITOR_DIRS = ['src/system/components', 'src/editor/component-editor'];
-
-// 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';
-
-function readKnownSuffixes(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 = new Set();
-    for (const m of block[1].matchAll(/suffix:\s*\[([\s\S]*?)\]/g)) {
-      for (const n of m[1].matchAll(/'-([a-z0-9-]+)'/g)) out.add(n[1]);
-    }
-    if (out.size > 0) return [...out];
-  }
-  return [];
-}
-
-/** True when `id` is one of the package's own components. */
-function isBuiltIn(id) {
-  return builtInIds(process.cwd(), PKG_ROOT).has(id);
-}
-
-// Per-side padding names (`--card-body-padding-top`) are written by the padding
-// selector, never declared by hand, and belong with their parent.
-const SIDE_SUFFIXES = ['-top', '-right', '-bottom', '-left'];
-
-// State tokens that must come *before* the property, never after.
-const STATE_TOKENS = ['hover', 'disabled', 'selected', 'focus', 'active', 'focused'];
-
-// Disabled is terminal: a disabled component cannot be hovered, focused, or
-// selected, so a token naming both describes a state that never paints.
-const TERMINAL_CONFLICTS = ['hover', 'focus', 'focused', 'selected', 'on', 'active', 'checked'];
-
-// Deep imports into the package internals are not a supported API.
-const DEEP_IMPORT_PATTERNS = [
-  /^@motion-proto\/live-tokens\/src\//,
-  /node_modules\/@motion-proto\/live-tokens/,
-];
+export const COMPONENT_RULES = assembleRules(
+  [
+    'tokens-migration',
+    'tokens-breaking-migration',
+    'invalid-id',
+    'missing-file',
+    'missing-root-block',
+    'no-tokens',
+    'missing-description',
+    'unread-token',
+    'state-after-property',
+    'disabled-is-terminal',
+    'unknown-suffix',
+    'phantom-editor-token',
+    'color-literal',
+    'missing-component-const',
+    'missing-all-tokens',
+    'deep-import',
+    'missing-registration',
+    'unknown-token-ref',
+    'default-not-token',
+    'phantom-link',
+    'dimension-literal',
+    'config-token',
+    'contract-registry',
+    'contract-behavior',
+    'contract-render',
+    'contract-alias',
+    'contract-persist',
+    'contract-theme',
+    'contract-states',
+    'contract-interaction',
+    'contract-listed',
+    'contract-sketch',
+    'contract-missing',
+    'tests-not-installed',
+    'tests-setup',
+    'tests-incomplete',
+  ],
+  componentStructure.componentRules,
+  tokenRules.componentRules,
+  importsAndRoutes.componentRules,
+  testRuns.componentRules,
+);
 
 function capitalize(id) {
   return id.charAt(0).toUpperCase() + id.slice(1);
 }
 
+const pick = (entry) => ({ Id: entry.Id, runtimePath: entry.runtimePath, editorPath: entry.editorPath });
+
 /**
- * Where `id`'s runtime and editor files live, resolved the same way
- * `checkComponent` does: the real on-disk filename rather than a capitalised
- * guess, since `cornerbadge` ships as `CornerBadge.svelte`. Exported so a
- * caller outside the lint (the `--tests` runner, attributing a contract
- * finding to a consumer artifact) doesn't re-derive it differently.
+ * Where `id`'s runtime and editor files live, resolved from `root`'s own
+ * inventory first, the real on-disk filename rather than a capitalised guess,
+ * since `cornerbadge` ships as `CornerBadge.svelte`. Exported so a caller
+ * outside the lint (the `--tests` runner, attributing a contract finding to a
+ * consumer artifact) doesn't re-derive it differently.
  */
 export function resolveComponentPaths(id, root = process.cwd()) {
+  const local = componentInventory(root).get(id);
+  if (local?.runtimeExists) return pick(local);
+
   // A consumer names a shipped id and owns no copy of its files. Falling back
   // to the package keeps the lint reading the same source the contract run
   // resolves, instead of reporting the component's own files missing. In this
-  // repo the consumer paths always exist, so the fallback never fires here.
-  const roots = builtInIds(root).has(id) ? [root, PKG_ROOT] : [root];
-  for (const base of roots) {
-    const dir = join(base, 'src/system/components');
-    const Id =
-      (existsSync(dir) ? readdirSync(dir) : [])
-        .find((f) => f.toLowerCase() === `${id}.svelte`)
-        ?.replace('.svelte', '') ?? capitalize(id);
-    const runtimePath = join(dir, `${Id}.svelte`);
-    const editorPath =
-      EDITOR_DIRS.map((d) => join(base, d, `${Id}Editor.svelte`)).find(existsSync) ??
-      join(base, EDITOR_DIRS[0], `${Id}Editor.svelte`);
-    if (base === roots.at(-1) || (existsSync(runtimePath) && existsSync(editorPath))) {
-      return { Id, runtimePath, editorPath };
-    }
-  }
-}
-
-function extractImports(source) {
-  const out = [];
-  const re = /import\s+(?:[^'"]*\s+from\s+)?['"]([^'"]+)['"]/g;
-  let m;
-  while ((m = re.exec(source)) !== null) {
-    out.push(m[1]);
-  }
-  return out;
-}
-
-/**
- * `--<id>-*` tokens declared in the given blocks.
- *
- * The prefix may also be the hyphenated word form of the id: CornerBadge is
- * registered as `cornerbadge` but names its tokens `--corner-badge-*`, and the
- * whole system (config, theme, editor) follows that. Segments never end on a
- * hyphen, so a trailing `-` cannot be mistaken for a token name.
- */
-function extractTokensForId(blocks, id, kebab) {
-  const tokens = new Set();
-  // Comments name tokens too (`the --card-hover-* tokens`); they are prose.
-  blocks = blocks.map((b) => b.replace(/\/\*[\s\S]*?\*\//g, ' '));
-  const prefixes = kebab && kebab !== id ? [id, kebab] : [id];
-  for (const prefix of prefixes) {
-    const re = new RegExp(`--${prefix}(?:-[a-z0-9]+)+`, 'g');
-    for (const block of blocks) {
-      for (const t of block.match(re) ?? []) tokens.add(t);
-    }
-  }
-  return [...tokens];
-}
-
-/** `CornerBadge` -> `corner-badge`; the other accepted token prefix. */
-function kebabOf(name) {
-  return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-}
-
-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;
-}
-
-function detectStateAfterProperty(token, known) {
-  // e.g. --comp-part-surface-hover (wrong) vs --comp-part-hover-surface (right)
-  for (const state of STATE_TOKENS) {
-    if (token.endsWith(`-${state}`)) {
-      const head = token.slice(0, -(state.length + 1));
-      if (tokenSuffix(head, known)) return state;
-    }
-  }
-  return null;
-}
-
-// True if `source` calls `fnName(` at least once with a single argument (no
-// top-level comma before the matching close paren). Brackets/braces are balanced
-// so commas inside nested objects/arrays/calls don't count.
-function hasBareCall(source, fnName) {
-  const needle = fnName + '(';
-  let idx = 0;
-  while ((idx = source.indexOf(needle, idx)) !== -1) {
-    let i = idx + needle.length;
-    let depth = 1;
-    let topComma = false;
-    for (; i < source.length && depth > 0; i++) {
-      const c = source[i];
-      if (c === '(' || c === '[' || c === '{') depth++;
-      else if (c === ')' || c === ']' || c === '}') depth--;
-      else if (c === ',' && depth === 1) topComma = true;
-    }
-    if (!topComma) return true;
-    idx = i;
-  }
-  return false;
-}
-
-function findFilesRecursive(dir, exts) {
-  if (!existsSync(dir)) return [];
-  const out = [];
-  for (const ent of readdirSync(dir, { withFileTypes: true })) {
-    if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
-    const full = join(dir, ent.name);
-    if (ent.isDirectory()) {
-      out.push(...findFilesRecursive(full, exts));
-    } else if (exts.includes(extname(ent.name))) {
-      out.push(full);
-    }
-  }
-  return out;
-}
-
-/**
- * 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.
- */
-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;
-}
-
-/**
- * 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.
- */
-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;
-}
-
-/**
- * The semantic half of the contract: a component token is a *property name*, and
- * its default is the theme token that property reads. So every default must
- * resolve to a real token — otherwise the component stops repainting when the
- * theme changes, which is the whole point of declaring it.
- */
-function checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath, record, vocabulary }) {
-  const vocab = vocabulary ?? loadVocabulary({ root });
-  const matchers = intrinsicMatchers(editor);
-  const rel = relative(root, runtimePath);
-
-  const own = new Set();
-  for (const block of blocks) {
-    for (const m of block.matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gm)) own.add(m[1]);
+  // repo the consumer paths always exist, so this fallback never fires here.
+  if (root !== PKG_ROOT && builtInIds(root, PKG_ROOT).has(id)) {
+    const shipped = componentInventory(PKG_ROOT).get(id);
+    if (shipped?.runtimeExists) return pick(shipped);
   }
 
-  for (const block of blocks) {
-    for (const m of block.matchAll(/(--[a-z0-9-]+)\s*:\s*([^;]+);/g)) {
-      const [decl, name, raw] = m;
-      const value = raw.trim();
-      const at = runtime.indexOf(decl);
+  // A registered id with no runtime anywhere: report where it would live.
+  if (local) return pick(local);
 
-      const painted = stripVarFallbacks(value);
-      const refs = [...painted.matchAll(/var\(\s*(--[a-z0-9-]+)/g)].map((x) => x[1]);
-      for (const ref of refs) {
-        if (own.has(ref) || vocab.knows(ref)) continue;
-        record(
-          'unknown-token-ref',
-          STATE_TOKENS.includes(ref.replace(/^--/, '').split('-')[0])
-            ? `${rel}: ${name} reads ${ref}, but a state is a segment of a property name. Read the token the state should paint`
-            : isContractToken(ref)
-              ? `${rel}: ${name} reads ${ref}, which has the shape of a design token but no longer exists. Check tokens.css for a rename`
-              : `${rel}: ${name} reads ${ref}, which is not a design token or a semantic property`,
-          at,
-        );
-      }
-
-      if (hasColorLiteral(painted)) {
-        record(
-          'color-literal',
-          `${rel}: ${name}: ${value} is a colour literal; defaults must reference design tokens (e.g. var(--surface-primary))`,
-          at,
-        );
-        continue;
-      }
-
-      if (refs.length === 0 && !matchers.some((re) => re.test(name))) {
-        record(
-          'default-not-token',
-          `${rel}: ${name}: ${value} has no design token behind it. Back it with a token, or declare it in the editor's \`intrinsics\` when it is a structural keyword`,
-          at,
-        );
-      }
-
-      if (hasDimensionLiteral(painted)) {
-        record(
-          'dimension-literal',
-          `${rel}: ${name}: ${value} pins a raw dimension; use a --space-*, --radius-*, or --border-width-* token`,
-          at,
-        );
-      }
-    }
-  }
+  const Id = capitalize(id);
+  const editorPath =
+    EDITOR_DIRS.map((d) => join(root, d, `${Id}Editor.svelte`)).find(existsSync) ??
+    join(root, EDITOR_DIRS[0], `${Id}Editor.svelte`);
+  return { Id, runtimePath: join(root, 'src/system/components', `${Id}.svelte`), editorPath };
 }
 
 export function checkComponent(id, root = process.cwd(), { vocabulary } = {}) {
@@ -395,227 +136,82 @@ export function checkComponent(id, root = process.cwd(), { vocabulary } = {}) {
   let file = '';
   let source = '';
 
-  const record = (rule, message, index = -1) => {
+  const record = (rule, message, index = -1, extra = {}) => {
     findings.push({
       rule,
       file,
       line: index >= 0 && source ? lineOf(source, index) : 1,
       message,
+      ...extra,
     });
-    (COMPONENT_RULES[rule] === 'warn' ? warnings : errors).push(message);
+    (COMPONENT_RULES[rule]?.severity === 'warn' ? warnings : errors).push(message);
+  };
+  // For a finding about a file other than the runtime (config-token against
+  // the saved alias config, deep-import against the editor or the registration
+  // file): the line is already resolved against that file's own text, never
+  // `source` (the runtime).
+  const recordAt = (rule, message, atFile, line = 1, extra = {}) => {
+    findings.push({ rule, file: atFile, line, message, ...extra });
+    (COMPONENT_RULES[rule]?.severity === 'warn' ? warnings : errors).push(message);
   };
   const done = () => ({ errors, warnings, findings });
 
-  if (!/^[a-z][a-z0-9]*$/.test(id)) {
-    record('invalid-id', `id "${id}" is invalid; must be lowercase letters/digits, no dashes`);
-    return done();
-  }
+  if (!componentStructure.checkId(id, record)) return done();
 
   const { Id, runtimePath, editorPath } = resolveComponentPaths(id, root);
-
   file = relative(root, runtimePath);
-  if (!existsSync(runtimePath)) {
-    record('missing-file', `runtime missing: ${relative(root, runtimePath)}`);
-  }
-  if (!existsSync(editorPath)) {
-    record('missing-file', `editor missing: ${relative(root, editorPath)}`);
-  }
-  if (errors.length) return done();
+  const { editorMissing, runtimeMissing } = componentStructure.checkFiles({ root, runtimePath, editorPath }, record);
+  if (runtimeMissing) return done();
+  // A missing editor still gets its own finding, but the rules that need only
+  // the runtime (token shape, semantics, config, registration) still run —
+  // an editor-less component is exactly the case those rules exist to catch.
 
   const runtime = readFileSync(runtimePath, 'utf8');
-  const editor = readFileSync(editorPath, 'utf8');
+  const editor = editorMissing ? '' : readFileSync(editorPath, 'utf8');
   source = runtime;
-
-  // Runtime: :global(:root) block present.
   const blocks = extractGlobalRootBlocks(runtime);
-  if (blocks.length === 0) {
-    record('missing-root-block', `${relative(root, runtimePath)}: missing :global(:root) declaration block`);
-  }
-
-  // Runtime: at least one --<id>-* token.
-  const tokens = extractTokensForId(blocks, id, kebabOf(Id));
-  if (blocks.length > 0 && tokens.length === 0) {
-    record('no-tokens', `${relative(root, runtimePath)}: no --${id}-* tokens declared in :global(:root)`);
-  }
-
-  // A token the editor declares as an intrinsic carries a structural keyword,
-  // not a themeable value, so a property-suffix rule is the wrong test for it.
-  const intrinsic = intrinsicMatchers(editor);
-  const known = readKnownSuffixes(root);
-
-  // Runtime: state-after-property anti-pattern. Report this first; if it fires
-  // for a token, skip the unknown-suffix error for the same token (the state-
-  // suffix wouldn't be in the suffix list anyway, so it's the same root cause).
-  const stateAfterTokens = new Set();
-  for (const token of tokens) {
-    if (intrinsic.some((re) => re.test(token))) continue;
-    const trailingState = detectStateAfterProperty(token, known);
-    if (trailingState) {
-      stateAfterTokens.add(token);
-      record(
-        'state-after-property',
-        `${relative(root, runtimePath)}: ${token} has '${trailingState}' after the property; ` +
-          `state must come before property (e.g. -${trailingState}-surface)`,
-        runtime.indexOf(token),
-      );
-    }
-  }
-
-  for (const token of tokens) {
-    const segments = token.slice(2).split('-');
-    if (!segments.includes('disabled')) continue;
-    const conflict = TERMINAL_CONFLICTS.find((s) => segments.includes(s));
-    if (conflict) {
-      record(
-        'disabled-is-terminal',
-        `${relative(root, runtimePath)}: ${token} combines 'disabled' with '${conflict}'; disabled is terminal, so that state never paints. Drop the token.`,
-        runtime.indexOf(token),
-      );
-    }
-  }
-
-  // Runtime: every token ends in a known suffix.
-  for (const token of tokens) {
-    if (stateAfterTokens.has(token) || intrinsic.some((re) => re.test(token))) continue;
-    if (!tokenSuffix(token, known)) {
-      record(
-        'unknown-suffix',
-        `${relative(root, runtimePath)}: ${token} doesn't end in a known suffix`,
-        runtime.indexOf(token),
-      );
-    }
-  }
-
-  checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath, record, vocabulary });
-
-  // Editor: declares `const component = '<id>'` (module block).
-  const componentDecl = new RegExp(`\\bconst\\s+component\\s*=\\s*['"]${id}['"]`);
-  if (!componentDecl.test(editor)) {
-    record(
-      'missing-component-const',
-      `${relative(root, editorPath)}: missing 'const component = "${id}"' in <script module>`,
-    );
-  }
-
-  // Editor: exports allTokens.
-  if (!/\bexport\s+const\s+allTokens\b/.test(editor)) {
-    record('missing-all-tokens', `${relative(root, editorPath)}: missing 'export const allTokens'`);
-  }
-
-  // Editor: every token a row names is one the runtime declares. A row that
-  // names nothing renders a control that edits nothing.
-  const declared = new Set();
-  for (const block of blocks) {
-    for (const n of declaredCustomProperties(block.replace(/\/\*[\s\S]*?\*\//g, ' '))) declared.add(n);
-  }
-  const refs = editorTokenRefs(editor);
-  for (const name of refs.literals) {
-    if (!declared.has(name)) {
-      record(
-        'phantom-editor-token',
-        `${relative(root, editorPath)}: names ${name}, which ${relative(root, runtimePath)} never declares in :global(:root)`,
-      );
-    }
-  }
-  for (const [name, re] of refs.patterns) {
-    if (![...declared].some((d) => re.test(d))) {
-      record(
-        'phantom-editor-token',
-        `${relative(root, editorPath)}: names ${name}, which matches nothing ${relative(root, runtimePath)} declares in :global(:root)`,
-      );
-    }
-  }
-
-  // Editor: phantom-link guard. The font type-group helpers fall back to bare
-  // `font-family`/`font-size`/… keys when called with a single argument (no
-  // derivation). Across more than one slot that silently links every slot's fonts
-  // into one tree. Passing `{ component, variants }` (a second arg) opts into
-  // distinct, structural keys and suppresses the check, so this only fires on the
-  // silent inference path. (The color helper no longer infers — a bare call there
-  // emits solo, un-grouped colors, which can't phantom-link.)
-  const colorPatterns = new Set();
-  for (const m of editor.matchAll(/colorVariable\s*:\s*[`'"]([^`'"]+)[`'"]/g)) {
-    colorPatterns.add(m[1].replace(/\$\{[^}]*\}/g, '*'));
-  }
-  const slots = colorPatterns.size;
-  const fontBare =
-    hasBareCall(editor, 'buildTypeGroupFontTokens') || hasBareCall(editor, 'buildTypeGroupTokens');
-  if (slots > 1 && fontBare) {
-    record(
-      'phantom-link',
-      `${relative(root, editorPath)}: a type-group font helper is called across ${slots} slots without a derivation; ` +
-        `its bare font-family/font-size/… keys would phantom-link every slot's fonts. Pass { component, variants } to buildTypeGroupTokens/buildTypeGroupFontTokens.`,
-    );
-  }
-
-  // Imports across runtime + editor: reject deep imports into the package.
-  for (const [path, source] of [[runtimePath, runtime], [editorPath, editor]]) {
-    for (const imp of extractImports(source)) {
-      for (const pattern of DEEP_IMPORT_PATTERNS) {
-        if (pattern.test(imp)) {
-          record('deep-import', `${relative(root, path)}: deep import not supported: ${imp}`);
-        }
-      }
-    }
-  }
-
-  // Registration: either a direct registerComponent({ id }) call or the id
-  // passed through bootLiveTokens({ components: [{ id }] }) — the standard
-  // scaffold boot. Accept both, somewhere under src/.
-  const srcFiles = findFilesRecursive(join(root, 'src'), ['.ts', '.js', '.svelte', '.mjs']);
-  const idLiteral = `id\\s*:\\s*['"]${id}['"]`;
-  const directPattern = new RegExp(`registerComponent\\s*\\(\\s*\\{[^}]*${idLiteral}`, 's');
-  const bootPattern = new RegExp(`bootLiveTokens\\s*\\([\\s\\S]*?components\\s*:\\s*\\[[\\s\\S]*?${idLiteral}`, 's');
-  let registrationFile = null;
-  for (const file of srcFiles) {
-    try {
-      const src = readFileSync(file, 'utf8');
-      if (directPattern.test(src) || bootPattern.test(src)) {
-        registrationFile = file;
-        break;
-      }
-    } catch {
-      // ignore unreadable files
-    }
-  }
-  // A first-party component is registered by membership in the package's own
-  // `builtInRegistry`, not by a `registerComponent` call, so look there too
-  // before calling it unregistered.
-  if (!registrationFile && isBuiltIn(id)) return done();
+  const context = {
+    id,
+    Id,
+    root,
+    runtimePath,
+    editorPath,
+    runtime,
+    editor,
+    blocks,
+    vocab: vocabulary ?? loadVocabulary({ root }),
+    // A token the editor declares as an intrinsic carries a structural keyword,
+    // not a themeable value, so a property-suffix rule is the wrong test for it.
+    intrinsic: intrinsicMatchers(editor),
+    declared: declaredTokens(blocks),
+  };
 
-  if (!registrationFile) {
-    record(
-      'missing-registration',
-      `no registration for '${id}' under src/. Expected registerComponent({ id: '${id}', ... }) or bootLiveTokens({ components: [{ id: '${id}', ... }] })`,
-    );
-  } else {
-    // Check the registration file's imports too.
-    const regSource = readFileSync(registrationFile, 'utf8');
-    for (const imp of extractImports(regSource)) {
-      for (const pattern of DEEP_IMPORT_PATTERNS) {
-        if (pattern.test(imp)) {
-          record('deep-import', `${relative(root, registrationFile)}: deep import not supported: ${imp}`);
-        }
-      }
-    }
+  componentStructure.checkRuntime(context, record);
+  tokenRules.checkDefaultsAreSemantic(context, record);
+  tokenRules.checkConfigTokens(context, recordAt);
+  tokenRules.checkUnreadTokens(context, record);
+  // The editor rules need real editor content; a missing editor already has
+  // its own `missing-file` finding, and running them against an empty string
+  // would only restate it under different rules.
+  if (!editorMissing) componentStructure.checkEditor(context, record);
+  importsAndRoutes.checkComponentImports(root, [[runtimePath, runtime], [editorPath, editor]], recordAt);
+
+  const registrationFile = componentStructure.checkRegistration(context, record);
+  if (registrationFile) {
+    importsAndRoutes.checkComponentImports(root, [[registrationFile, readFileSync(registrationFile, 'utf8')]], recordAt);
   }
-
   return done();
 }
 
 /**
  * Every component authored in `root`: a runtime file under
- * src/system/components with an editor beside it or in the package's editor
- * directory. What `check-component` runs over when no id is named.
+ * `src/system/components` or a configured `componentDirs` entry, editor or
+ * not — a runtime with no editor is still in the batch, so `checkComponent`
+ * can report its own `missing-file`. What `check-component` runs over when no
+ * id is named.
  */
 export function discoverComponents(root = process.cwd()) {
-  const dir = join(root, 'src/system/components');
-  if (!existsSync(dir)) return [];
-  return readdirSync(dir)
-    .filter((f) => f.endsWith('.svelte') && !f.endsWith('Editor.svelte'))
-    .map((f) => f.replace('.svelte', ''))
-    .filter((Id) => EDITOR_DIRS.some((d) => existsSync(join(root, d, `${Id}Editor.svelte`))))
-    .map((Id) => Id.toLowerCase());
+  return [...componentInventory(root).values()].filter((e) => e.runtimeExists).map((e) => e.id);
 }
 
 export function formatReport(id, result) {
@@ -655,7 +251,14 @@ export function checkComponentDefaults(runtimePath, { root = process.cwd(), voca
   const editorPath = EDITOR_DIRS.map((d) => join(root, d, `${name}Editor.svelte`)).find(existsSync);
   const editor = editorPath ? readFileSync(editorPath, 'utf8') : '';
 
-  const blocks = extractGlobalRootBlocks(runtime);
-  checkDefaultsAreSemantic({ blocks, runtime, editor, root, runtimePath, record, vocabulary });
+  const context = {
+    blocks: extractGlobalRootBlocks(runtime),
+    runtime,
+    root,
+    runtimePath,
+    vocab: vocabulary ?? loadVocabulary({ root }),
+    intrinsic: intrinsicMatchers(editor),
+  };
+  tokenRules.checkDefaultsAreSemantic(context, record);
   return findings;
 }