@motion-proto/live-tokens 0.78.0 → 0.80.0

package/bin/rules/componentStructure.mjs

@@ -0,0 +1,344 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { extname, join, relative } from 'node:path';
+import { catalogueOf } from '../lib/catalogue.mjs';
+import { STATE_TOKENS, editorTokenRefs, readKnownSuffixes, tokenSuffix } from '../lib/componentSource.mjs';
+import { PKG_ROOT, builtInIds } from '../lib/tokenVocabulary.mjs';
+
+const RUNTIME = 'Wire the component as the recipe in live-tokens-create-component wires it.';
+
+const PROPERTY_NAME =
+  'Rename the semantic property to the name a shipped component uses for the same role. The vocabulary and the state model are in live-tokens-create-component.';
+
+const EDITOR =
+  'Fix the editor schema, states, or preview props by the Component editor section of live-tokens-create-component.';
+
+export const componentRules = {
+  'invalid-id': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Give the component an id of lowercase letters and digits with no dashes, and use it in the runtime, the editor, and the registration. ${RUNTIME}`,
+  },
+  'missing-file': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Create the runtime or editor file the message names. ${RUNTIME}`,
+  },
+  'missing-root-block': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Declare the semantic properties in a :global(:root) block in the runtime's <style>. ${RUNTIME}`,
+  },
+  'no-tokens': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Declare the component's --<id>-* semantic properties in its :global(:root) block. ${RUNTIME}`,
+  },
+  'missing-description': {
+    severity: 'warn',
+    repair: 'authored',
+    guidance:
+      "Add the catalogue export to the runtime's <script module> block, with description, useFor, and notFor as string literals. The message names the field that is missing or malformed, and `npx live-tokens components <id>` prints the entry once it is there.",
+  },
+  'state-after-property': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Move the state ahead of the property suffix, such as -hover-surface. ${PROPERTY_NAME}`,
+  },
+  'disabled-is-terminal': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Disabled is terminal, so a name that joins disabled with another state never paints. Delete the semantic property, or rename it. ${PROPERTY_NAME}`,
+  },
+  'unknown-suffix': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `End the name in a suffix check-component accepts. references/token-naming.md in live-tokens-create-component lists every suffix, and the suffix selects the editor control. ${PROPERTY_NAME}`,
+  },
+  'phantom-editor-token': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `The editor names a semantic property the runtime never declares. Point the row at a declared property, or declare the property in the runtime's :global(:root) block. ${EDITOR}`,
+  },
+  'missing-component-const': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Declare const component = '<id>' in the editor's <script module> block. ${EDITOR}`,
+  },
+  'missing-all-tokens': {
+    severity: 'error',
+    repair: 'authored',
+    guidance: `Export allTokens from the editor's <script module> block. ${EDITOR}`,
+  },
+  'missing-registration': {
+    severity: 'error',
+    repair: 'authored',
+    guidance:
+      'Register the component in the shared module the Registration section of live-tokens-create-component wires up, importable by the app and by check-component --tests. The call is registerComponent({ id }) or an entry in bootLiveTokens({ components }).',
+  },
+  'phantom-link': {
+    severity: 'warn',
+    repair: 'authored',
+    guidance: `Pass { component, variants } to buildTypeGroupTokens or buildTypeGroupFontTokens, so each slot keeps its own font keys. ${EDITOR}`,
+  },
+};
+
+/** True when `id` is one of the package's own components. */
+function isBuiltIn(id) {
+  return builtInIds(process.cwd(), PKG_ROOT).has(id);
+}
+
+// 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'];
+
+export function checkId(id, record) {
+  if (/^[a-z][a-z0-9]*$/.test(id)) return true;
+  record('invalid-id', `id "${id}" is invalid; must be lowercase letters/digits, no dashes`);
+  return false;
+}
+
+/** The editor is checked first, so an id with neither file gets both findings
+ *  rather than stopping silently on the first. */
+export function checkFiles({ root, runtimePath, editorPath }, record) {
+  const editorMissing = !existsSync(editorPath);
+  if (editorMissing) {
+    record('missing-file', `editor missing: ${relative(root, editorPath)}`);
+  }
+  const runtimeMissing = !existsSync(runtimePath);
+  if (runtimeMissing) {
+    record('missing-file', `runtime missing: ${relative(root, runtimePath)}`);
+  }
+  return { editorMissing, runtimeMissing };
+}
+
+export function checkRuntime({ id, Id, root, runtimePath, runtime, blocks, intrinsic }, record) {
+  // Runtime: the file exports the `catalogue` that says what the component
+  // is for. Without it the component is pickable but unexplained.
+  const catalogue = catalogueOf(runtime);
+  if (!catalogue) {
+    record(
+      'missing-description',
+      `${relative(root, runtimePath)}: has no catalogue export. Say what ${Id} is for, and what it is not for`,
+    );
+  } else {
+    for (const requiredField of ['description', 'useFor', 'notFor']) {
+      if (!catalogue[requiredField]) {
+        record('missing-description', `${relative(root, runtimePath)}: catalogue has no ${requiredField}`);
+      }
+    }
+  }
+
+  // Runtime: :global(:root) block present.
+  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);
+  if (blocks.length > 0 && tokens.length === 0) {
+    record('no-tokens', `${relative(root, runtimePath)}: no --${id}-* tokens declared in :global(:root)`);
+  }
+
+  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),
+      );
+    }
+  }
+}
+
+export function checkEditor({ id, root, runtimePath, editorPath, editor, declared }, record) {
+  // 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 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.`,
+    );
+  }
+}
+
+/** The file under src/ that registers `id`, or null when none does. */
+export function checkRegistration({ id, root }, record) {
+  // 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 null;
+
+  if (!registrationFile) {
+    record(
+      'missing-registration',
+      `no registration for '${id}' under src/. Expected registerComponent({ id: '${id}', ... }) or bootLiveTokens({ components: [{ id: '${id}', ... }] })`,
+    );
+  }
+  return registrationFile;
+}
+
+/**
+ * `--<id>-*` tokens declared in the given blocks.
+ *
+ * Segments never end on a hyphen, so a trailing `-` cannot be mistaken for a
+ * token name.
+ */
+function extractTokensForId(blocks, id) {
+  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 re = new RegExp(`--${id}(?:-[a-z0-9]+)+`, 'g');
+  for (const block of blocks) {
+    for (const t of block.match(re) ?? []) tokens.add(t);
+  }
+  return [...tokens];
+}
+
+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;
+}

package/bin/rules/componentUse.mjs

@@ -0,0 +1,313 @@
+import { blankHtmlExpressions, styleBlockDeclarations, tagAttributes } from '../lib/pageSource.mjs';
+
+export const pageRules = {
+  'unknown-component': {
+    severity: 'error',
+    repair: 'authored',
+    guidance:
+      'Read the live-tokens-pick-component skill for the shipped component that fits. When none fits, author one with live-tokens-create-component.',
+  },
+  'unknown-prop': {
+    severity: 'error',
+    repair: 'choice',
+    guidance:
+      '`npx live-tokens components <id>` prints the declared props and their values, and `details.accepts` lists the props. Map the prop to one of them, or delete it.',
+  },
+  'unknown-prop-value': {
+    severity: 'error',
+    repair: 'choice',
+    guidance: 'Use a value from the union the message lists, which `details.accepts` also holds.',
+  },
+  'control-size': {
+    severity: 'warn',
+    repair: 'auto',
+    guidance:
+      "A run without --no-fix deletes each attribute it can bound whole. Delete the rest by hand. The shipped default is the page's size. When that default is wrong for the project, retune the component in /live-tokens/components.",
+  },
+  'multiple-primary': {
+    severity: 'warn',
+    repair: 'authored',
+    guidance:
+      'Keep the action that completes the main task primary. A Button with no variant counts as primary. Use secondary for supporting or related actions, and outline for unrelated or informational actions.',
+  },
+  'danger-without-dialog': {
+    severity: 'warn',
+    repair: 'authored',
+    guidance:
+      "Open a Dialog from the danger Button or IconButton, and run the action from the Dialog's confirm. The rule fires once per page, when the page imports no Dialog. For other actions, assign emphasis by the action's relationship to the main task.",
+  },
+  'native-control': {
+    severity: 'warn',
+    repair: 'authored',
+    guidance:
+      'Replace the native element with the shipped component the message names: Button or IconButton, Input, or MenuSelect.',
+  },
+  'property-override': {
+    severity: 'warn',
+    repair: 'auto',
+    guidance:
+      "A run without --no-fix deletes the declaration or the style: directive. A setProperty call is code around the value, so rewrite it by hand. Retune the component's semantic property for the whole project at /live-tokens/components.",
+  },
+};
+
+export const COMPONENT_IMPORT =
+  /(?:@motion-proto\/live-tokens\/components|[./][^'"]*\/system\/components)\/([A-Za-z0-9]+)\.svelte$/;
+
+/** `unknown-component` for one import statement. A catalogue component's local
+ *  name joins `imports`, which the tag rules read. */
+export function resolveComponentImport({ index, clause, specifier }, vocab, imports, add) {
+  const comp = specifier.match(COMPONENT_IMPORT);
+  if (!comp) return;
+  const entry = vocab.components.get(comp[1].toLowerCase());
+  if (!entry) {
+    add(
+      'unknown-component',
+      index,
+      `'${comp[1]}' is not in the component catalogue; author it with live-tokens-create-component or pick a shipped one`,
+    );
+    return;
+  }
+  const local = clause?.trim().match(/^(\w+)$/)?.[1];
+  if (local) imports.set(local, entry);
+}
+
+export function checkComponentTags(code, imports, add) {
+  checkComponentUsage(code, imports, add);
+  checkPrimaryActions(code, imports, add);
+  checkDestructiveActions(code, imports, add);
+  checkNativeControls(code, add);
+}
+
+// The shipped component that owns each native control's paint.
+const NATIVE_CONTROLS = {
+  button: 'Button or IconButton',
+  input: 'Input',
+  select: 'MenuSelect',
+  textarea: 'Input',
+};
+
+/** A raw `<button>`, `<input>`, `<select>`, or `<textarea>` where a shipped
+    component belongs. `<input type="hidden">` paints nothing and is exempt.
+    A tag inside `<script>` is markup the page assembles into a string, not
+    markup it renders, so the script block is blanked the same way
+    `codeRegion` blanks `<style>`, keeping offsets aligned with `code`. */
+function checkNativeControls(code, add) {
+  const scan = blankHtmlExpressions(code).replace(/<script[^>]*>[\s\S]*?<\/script>/g, (m) => ' '.repeat(m.length));
+  for (const tag of Object.keys(NATIVE_CONTROLS)) {
+    for (const m of scan.matchAll(new RegExp(`<${tag}(?=[\\s/>])`, 'g'))) {
+      const parsed = tagAttributes(scan, m.index);
+      if (tag === 'input' && parsed?.attrs.some((a) => a.name.toLowerCase() === 'type' && a.value?.toLowerCase() === 'hidden')) {
+        continue;
+      }
+      add(
+        'native-control',
+        m.index,
+        `<${tag}> is a native control; use ${NATIVE_CONTROLS[tag]} so it paints from the theme.`,
+      );
+    }
+  }
+}
+
+/**
+ * Props a page passes that the component does not declare, values outside a
+ * prop's union, and a shipped component the page sizes itself.
+ */
+function checkComponentUsage(code, imports, add) {
+  for (const [local, entry] of imports) {
+    const props = entry.props;
+    if (!props) continue;
+    const re = new RegExp(`<${local}(?=[\\s/>])`, 'g');
+    for (const m of code.matchAll(re)) {
+      const tag = tagAttributes(code, m.index);
+      if (!tag) continue;
+      for (const { name, value, index, end } of tag.attrs) {
+        if (name.includes(':') || name.startsWith('@') || name === 'children') continue;
+        if (!props.props.has(name)) {
+          add('unknown-prop', index, `${entry.name} has no prop '${name}'; it accepts ${[...props.props].join(', ')}`, {
+            details: { accepts: [...props.props] },
+          });
+          continue;
+        }
+        const allowed = props.enums.get(name);
+        if (allowed && value !== null && !allowed.has(value)) {
+          add('unknown-prop-value', index, `${entry.name} ${name}="${value}" is not one of ${[...allowed].join(', ')}`, {
+            details: { accepts: [...allowed] },
+          });
+        }
+        if (name === 'size' && entry.origin === 'shipped') {
+          // An attribute no fixer can delete whole has nothing auto to
+          // apply, so it lowers to a choice.
+          const patch = attributeDeletion(code, index, end);
+          add(
+            'control-size',
+            index,
+            `${entry.name} ${value === null ? 'is sized here' : `size="${value}"`}. Drop it for the shipped default, or retune ${entry.name} for the whole project in /live-tokens/components.`,
+            { details: { site: 'attribute', ...(patch ? { patch } : {}) }, ...(patch ? {} : { repair: 'choice' }) },
+          );
+        }
+      }
+    }
+  }
+}
+
+/** The exact text a fixer deletes for one attribute: its own span, plus one
+ *  leading space or tab if present, so removal doesn't leave a double space or
+ *  a lone trailing one before the tag's `>`. A span that crosses a newline
+ *  yields no patch: the patch has to stay inside the line the finding names,
+ *  and `applyFixes` applies a file's patches in line order on the assumption
+ *  that none of them moves a later line. A span stopping at its own `=` is an
+ *  attribute whose value starts on the next line, so deleting the span would
+ *  leave the value behind as orphan markup. */
+function attributeDeletion(code, index, end) {
+  const start = /[^\S\n]/.test(code[index - 1] ?? '') ? index - 1 : index;
+  const from = code.slice(start, end);
+  if (from.includes('\n') || from.endsWith('=')) return null;
+  return { from, to: '' };
+}
+
+/**
+ * One finding when a page holds more than one primary Button, at the second of
+ * them. Emphasis is what the variant carries, so a second primary leaves the
+ * page with no single most important action. A Button with no variant is
+ * primary, the component's default.
+ */
+function checkPrimaryActions(code, imports, add) {
+  const primaries = [];
+  for (const [local, entry] of imports) {
+    if (entry.id !== 'button') continue;
+    for (const m of code.matchAll(new RegExp(`<${local}(?=[\\s/>])`, 'g'))) {
+      const tag = tagAttributes(code, m.index);
+      const variant = tag?.attrs.find((a) => a.name === 'variant');
+      if (tag && (variant === undefined || variant.value === 'primary')) primaries.push(m.index);
+    }
+  }
+  if (primaries.length < 2) return;
+  primaries.sort((a, b) => a - b);
+  add(
+    'multiple-primary',
+    primaries[1],
+    `${primaries.length} primary Buttons in this page. Keep the most important action primary and make the other ${primaries.length - 1} secondary.`,
+  );
+}
+
+/**
+ * One finding when a page holds a danger Button and imports no Dialog. A
+ * danger action destroys saved work, and the page has nothing to confirm it.
+ */
+function checkDestructiveActions(code, imports, add) {
+  if ([...imports.values()].some((entry) => entry.id === 'dialog')) return;
+  for (const [local, entry] of imports) {
+    if (entry.id !== 'button' && entry.id !== 'iconbutton') continue;
+    for (const m of code.matchAll(new RegExp(`<${local}(?=[\\s/>])`, 'g'))) {
+      const tag = tagAttributes(code, m.index);
+      if (!tag?.attrs.some((a) => a.name === 'variant' && a.value === 'danger')) continue;
+      add(
+        'danger-without-dialog',
+        m.index,
+        `${entry.name} variant="danger" with no Dialog in this page. A destructive action confirms in a Dialog before it runs.`,
+      );
+      return;
+    }
+  }
+}
+
+// Which component's :global(:root) block declared each component token,
+// cached per vocabulary since checkFile runs once per page.
+const tokenOwnersCache = new WeakMap();
+function componentTokenOwners(vocab) {
+  let owners = tokenOwnersCache.get(vocab);
+  if (owners) return owners;
+  owners = new Map();
+  for (const comp of vocab.components.values()) {
+    for (const name of comp.tokens.keys()) {
+      if (!owners.has(name)) owners.set(name, comp.name);
+    }
+  }
+  tokenOwnersCache.set(vocab, owners);
+  return owners;
+}
+
+/** A `--name: value;` CSS declaration, deleted whole. The match is anchored at
+ *  `index`, which sits either on the name or on the boundary character before
+ *  it (a style-block match keeps that char as its own delimiter), and the
+ *  declaration stops at `}` and at a newline as well as at `;`, the gaps
+ *  around its colon included. Unanchored and unbounded, the search ran past
+ *  its own rule and deleted the next same-named declaration, or the text of a
+ *  string literal further down the file. A declaration no `;` terminates
+ *  inside its own block yields no patch, since deleting it whole would need
+ *  one. A declaration wrapped onto a second line yields none either: the
+ *  patch has to stay inside the line the finding names, since `applyFixes`
+ *  assumes no patch moves a later line. The match runs on `clean`, the
+ *  neutralised text from `index` on, and the span it bounds has to read the
+ *  same in the file: matched on the raw text, a `;` inside a comment in the
+ *  value ended the match there, and the deletion left the comment's tail
+ *  behind.
+ */
+function declarationDeletion(text, name, index, clean) {
+  const m = new RegExp(`^[;{]?\\s*(${name}[^\\S\\n]*:[^\\S\\n]*[^;}\\n]+;)`).exec(clean);
+  if (!m) return null;
+  const start = index + m[0].length - m[1].length;
+  const from = text.slice(start, start + m[1].length);
+  return from === m[1] ? { from, to: '' } : null;
+}
+
+/** A `style:--name="value"` directive, deleted whole. `overrideAt` always
+ *  records `index` at the start of `style:` itself, so the match is anchored
+ *  there and its length measures this directive. Unanchored, a directive whose
+ *  value is an expression (`style:--name={r}`) matched a quoted namesake
+ *  further down the file and cut that match's length out of this tag's markup.
+ *  An expression value has no patch: the value is code, not text to delete.
+ */
+function directiveDeletion(text, name, index) {
+  const m = new RegExp(`^style:${name}=(["'])[^"']*\\1`).exec(text.slice(index));
+  if (!m) return null;
+  const start = /[^\S\n]/.test(text[index - 1] ?? '') ? index - 1 : index;
+  const from = text.slice(start, index + m[0].length);
+  // A quoted value may run over a line, and deleting it would move every later
+  // finding's line out from under `applyFixes`.
+  if (from.includes('\n')) return null;
+  return { from, to: '' };
+}
+
+export function checkPropertyOverrides({ text, regions, inlineRegions, vocab }, add) {
+  // property-override needs a narrower set than `pageDeclaredNames`: its
+  // bare-quote alternative exists only to suppress unknown-token on a name any
+  // quoted string mentions, so it also matches a read like
+  // getPropertyValue("--x"). A real declaration is a style-block rule, an
+  // inline `style="--x: ..."` attribute, a `style:--x=` directive, or a
+  // setProperty('--x', ...) call.
+  const overrideSites = new Map();
+  const overrideAt = (name, index, site, clean) => {
+    if (!overrideSites.has(name) || index < overrideSites.get(name).index) overrideSites.set(name, { index, site, clean });
+  };
+  styleBlockDeclarations(regions, overrideAt);
+  styleBlockDeclarations(inlineRegions, overrideAt);
+  for (const m of text.matchAll(/(?:style:|setProperty\(\s*['"`])(--[a-z0-9-]+)/g)) {
+    overrideAt(m[1], m.index, m[0].startsWith('style:') ? 'directive' : 'script');
+  }
+
+  // A name the vocabulary already ties to a component is that component's
+  // token, so declaring it here is one instance overriding the whole
+  // project's retuning surface at /live-tokens/components.
+  for (const [name, { index, site, clean }] of overrideSites) {
+    if (!vocab.componentTokens.has(name)) continue;
+    const owner = componentTokenOwners(vocab).get(name) ?? 'a shipped component';
+    const patch =
+      site === 'declaration'
+        ? declarationDeletion(text, name, index, clean)
+        : site === 'directive'
+          ? directiveDeletion(text, name, index)
+          : null;
+    // A setProperty call is code around the value, not a value to delete, so
+    // it is always authored. Any other site with no patch (an inline
+    // attribute, or a declaration a fixer could not bound safely) has
+    // nothing auto to apply, so it is a choice rather than the rule's ceiling.
+    const repair = site === 'script' ? 'authored' : patch ? undefined : 'choice';
+    add(
+      'property-override',
+      index,
+      `${name} overrides ${owner}'s token here instead of the whole project; retune it at /live-tokens/components.`,
+      { details: { site, ...(patch ? { patch } : {}) }, ...(repair ? { repair } : {}) },
+    );
+  }
+}