@motion-proto/live-tokens 0.77.0 → 0.79.0

package/bin/check-page.mjs

@@ -12,442 +12,78 @@
 
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join, relative, resolve, basename } from 'node:path';
-import { isExcluded, lineOf } from './lib/findings.mjs';
-import { blankStrings, hasColorLiteral, hasDimensionLiteral, stripVarFallbacks } from './lib/cssValues.mjs';
-import { isContractToken, loadVocabulary, walk } from './lib/tokenVocabulary.mjs';
+import { assembleRules, isExcluded, lineOf } from './lib/findings.mjs';
+import { codeRegion, inlineStyleRegions, styleRegions } from './lib/pageSource.mjs';
+import { loadVocabulary, walk } from './lib/tokenVocabulary.mjs';
 import { resolveTokensCssPath } from './migrate.mjs';
-
-export const PAGE_RULES = {
-  'unknown-component': 'error',
-  'unknown-prop': 'error',
-  'unknown-prop-value': 'error',
-  'deep-import': 'error',
-  'unknown-token': 'error',
-  'color-literal': 'error',
-  'reserved-route': 'error',
-  'site-css-in-main': 'error',
-  'raw-text-axis': 'error',
-  'dimension-literal': 'warn',
-  'hardcoded-columns': 'warn',
-  'missing-source': 'warn',
-  'control-size': 'warn',
-  'multiple-primary': 'warn',
-  'danger-without-dialog': 'warn',
-};
-
-// Directories that hold the system, not pages built on it.
-const NOT_PAGES = ['src/system', 'src/editor', 'src/lib', 'src/live-tokens'];
-
-export const COMPONENT_IMPORT =
-  /(?:@motion-proto\/live-tokens\/components|[./][^'"]*\/system\/components)\/([A-Za-z0-9]+)\.svelte$/;
-
-const DEEP_IMPORT_PATTERNS = [
-  /^@motion-proto\/live-tokens\/src\//,
-  /node_modules\/@motion-proto\/live-tokens/,
-];
-
-const TEXT_AXES = ['font-size', 'font-family', 'font-weight', 'line-height', 'letter-spacing'];
-
-// The single-axis scales in tokens.css. A text style bundle carries its axis
-// as a suffix (--body-md-font-size, --code-font-family), so no bundle name
-// matches, and neither does a custom property the page declares itself. A
-// weight alone cannot move the scale or the fonts, so --font-weight-* is not one.
-const SINGLE_AXIS_TOKEN =
-  /^--(?:font-size|line-height|letter-spacing)-|^--font-(?:sans|serif|mono|display|editorial)$/;
-
-// The geometry the theme owns: spacing, stroke, radius, and shadow all have a
-// token scale, and `set-geometry` moves them. Sizing (a hero's height, a
-// column's minimum width, a max content width) is layout, has no scale, and
-// stays literal.
-const THEMED_GEOMETRY = /^(padding|margin|gap|row-gap|column-gap|border|outline|inset|top|right|bottom|left|box-shadow|text-shadow)(-|$)|-radius$/;
-
-// A local two-up or three-up is a layout. From four columns on, a hardcoded
-// count reads as a claim about the page grid, which `--columns-count` owns.
-const PAGE_GRID_COLUMNS = 4;
-
-/** Blank out comments, url() payloads, and string contents so none of them can match a rule. */
-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. */
-function styleRegions(text, file) {
-  if (file.endsWith('.css')) return [{ text, offset: 0 }];
-  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]) });
-  }
-  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.
- */
-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]) });
-  }
-  for (const m of code.matchAll(/\sstyle:([a-z-]+)=(["'])([^"']*)\2/g)) {
-    out.push({ text: `${m[1]}: ${m[3]};`, offset: m.index + 1 });
-  }
-  return out;
-}
-
-/** Everything outside `<style>`: script and markup. */
-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`.
- */
-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 });
-  }
-  return out;
-}
-
-/**
- * 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.
- */
-function tagAttributes(code, start) {
-  let i = code.indexOf(' ', 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;
-  })();
-  if (i === -1 || i > tagEnd) 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 });
-      i = j + 1;
-      continue;
-    }
-    const name = code.slice(i).match(/^[^\s=/>]+/)?.[0];
-    if (!name) break;
-    const at = i;
-    i += name.length;
-    let value = null;
-    if (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;
-      }
-    }
-    attrs.push({ name, value, index: at });
-  }
-  return { attrs, end: tagEnd };
-}
-
-/**
- * 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 } 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(', ')}`);
-          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(', ')}`);
-        }
-        if (name === 'size' && entry.origin === 'shipped') {
-          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.`,
-          );
-        }
-      }
-    }
-  }
-}
-
-/**
- * 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(
+import * as componentUse from './rules/componentUse.mjs';
+import * as importsAndRoutes from './rules/importsAndRoutes.mjs';
+import * as testRuns from './rules/testRuns.mjs';
+import * as tokenRules from './rules/tokens.mjs';
+
+/** Every rule, with its default severity, its repair, and its guidance. Same
+ *  three fields, same meanings, as `COMPONENT_RULES`. */
+export const PAGE_RULES = assembleRules(
+  [
+    'unknown-component',
+    'unknown-prop',
+    'unknown-prop-value',
+    'deep-import',
+    'unknown-token',
+    'color-literal',
+    'reserved-route',
+    'site-css-in-main',
+    'raw-text-axis',
+    'dimension-literal',
+    'hardcoded-columns',
+    'missing-source',
+    'control-size',
     '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.`,
-  );
-}
+    'danger-without-dialog',
+    'native-control',
+    'property-override',
+    'page-component-paint',
+    'page-text-style',
+    'page-contrast',
+    'page-grid',
+    'page-overflow',
+    'tests-not-installed',
+    'tests-setup',
+    'tests-incomplete',
+  ],
+  componentUse.pageRules,
+  importsAndRoutes.pageRules,
+  tokenRules.pageRules,
+  testRuns.pageRules,
+);
 
-/**
- * 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;
-    }
-  }
-}
+// Directories that hold the system, not pages built on it.
+export const NOT_PAGES = ['src/system', 'src/editor', 'src/lib', 'src/live-tokens'];
 
-/** The object literal enclosing `index`, found by balancing braces outward. */
-function enclosingObject(text, index) {
-  let depth = 0;
-  let start = -1;
-  for (let i = index; i >= 0; i--) {
-    const c = text[i];
-    if (c === '}') depth++;
-    else if (c === '{') {
-      if (depth === 0) {
-        start = i;
-        break;
-      }
-      depth--;
-    }
-  }
-  if (start === -1) return null;
-  depth = 0;
-  for (let i = start; i < text.length; i++) {
-    const c = text[i];
-    if (c === '{') depth++;
-    else if (c === '}') {
-      depth--;
-      if (depth === 0) return text.slice(start, i + 1);
-    }
-  }
-  return null;
-}
+export { COMPONENT_IMPORT } from './rules/componentUse.mjs';
 
 function checkFile(file, text, vocab, root) {
   const rel = relative(root, file);
   const findings = [];
-  const add = (rule, index, message) =>
-    findings.push({ rule, file: rel, line: lineOf(text, index), message });
+  const add = (rule, index, message, extra = {}) =>
+    findings.push({ rule, file: rel, line: lineOf(text, index), message, ...extra });
 
   const code = codeRegion(text, file);
+  const regions = styleRegions(text, file);
+  const inlineRegions = code === null ? [] : inlineStyleRegions(code);
   if (code !== null) {
     const imports = new Map();
     for (const m of code.matchAll(/import\s+(?:([^'"]*?)\s+from\s+)?['"]([^'"]+)['"]/g)) {
-      const spec = m[2];
-      for (const pattern of DEEP_IMPORT_PATTERNS) {
-        if (pattern.test(spec)) {
-          add('deep-import', m.index, `deep import into package internals: ${spec}`);
-        }
-      }
-      const comp = spec.match(COMPONENT_IMPORT);
-      if (!comp) continue;
-      const entry = vocab.components.get(comp[1].toLowerCase());
-      if (!entry) {
-        add(
-          'unknown-component',
-          m.index,
-          `'${comp[1]}' is not in the component catalogue; author it with live-tokens-create-component or pick a shipped one`,
-        );
-        continue;
-      }
-      const local = m[1]?.trim().match(/^(\w+)$/)?.[1];
-      if (local) imports.set(local, entry);
-    }
-    checkComponentUsage(code, imports, add);
-    checkPrimaryActions(code, imports, add);
-    checkDestructiveActions(code, imports, add);
-
-    for (const m of code.matchAll(/['"](\/live-tokens[^'"]*)['"]\s*:/g)) {
-      add('reserved-route', m.index, `route '${m[1]}' is inside the reserved /live-tokens/* namespace`);
-    }
-
-    for (const m of code.matchAll(/\blazy\s*:/g)) {
-      const entry = enclosingObject(code, m.index);
-      if (entry && !/\bsource\s*:/.test(entry)) {
-        add('missing-source', m.index, `route entry has no 'source', so Page Source cannot open it`);
-      }
-    }
-
-    if (/^main\.(ts|js)$/.test(basename(file))) {
-      for (const m of code.matchAll(/import\s+['"]([^'"]*site\.css)['"]/g)) {
-        add(
-          'site-css-in-main',
-          m.index,
-          `site.css imported from main; import it from each page's <script> so it cannot leak into editor routes`,
-        );
-      }
+      const statement = { index: m.index, clause: m[1], specifier: m[2] };
+      importsAndRoutes.checkPageImport(statement, add);
+      componentUse.resolveComponentImport(statement, vocab, imports, add);
     }
+    componentUse.checkComponentTags(code, imports, add);
+    importsAndRoutes.checkRoutes({ file, code }, add);
   }
 
-  // A page may also mint a custom property outside its <style> block — a
-  // `style:--x={...}` directive or an el.style.setProperty call — and those are
-  // just as declared as one written in CSS.
-  const declaredHere = new Set();
-  const regions = styleRegions(text, file);
-  for (const region of regions) {
-    for (const m of neutralise(region.text).matchAll(/(?:^|[;{])\s*(--[a-z0-9-]+)\s*:/gim)) {
-      declaredHere.add(m[1]);
-    }
-  }
-  for (const m of text.matchAll(/(?:style:|setProperty\(\s*['"`]|['"`])(--[a-z0-9-]+)/g)) {
-    declaredHere.add(m[1]);
-  }
-
-  for (const region of [...regions, ...(code === null ? [] : inlineStyleRegions(code))]) {
-    const css = neutralise(region.text);
-    const at = (i) => region.offset + i;
-
-    for (const m of css.matchAll(/var\(\s*(--[a-z0-9-]+)/g)) {
-      const name = m[1];
-      if (declaredHere.has(name) || vocab.knows(name)) continue;
-      add(
-        'unknown-token',
-        at(m.index),
-        isContractToken(name)
-          ? `${name} has the shape of a design token but no longer exists. Check tokens.css for a rename`
-          : `${name} is not a design token, a semantic property, or declared in this file`,
-      );
-    }
-
-    for (const decl of declarations(css)) {
-      const { prop, value, index } = decl;
-      if (prop.startsWith('--')) continue;
-
-      // A `var()` fallback only renders when the token is missing, so a literal
-      // inside one is not the page's value.
-      const painted = stripVarFallbacks(value);
-      if (!TEXT_AXES.includes(prop) && hasColorLiteral(painted)) {
-        add('color-literal', at(index), `${prop}: ${value}. Use a design token.`);
-        continue;
-      }
-
-      if (TEXT_AXES.includes(prop) || prop === 'font') {
-        const axis = [...painted.matchAll(/var\(\s*(--[a-z0-9-]+)/g)]
-          .map((m) => m[1])
-          .find((name) => SINGLE_AXIS_TOKEN.test(name));
-        if (axis) {
-          add(
-            'raw-text-axis',
-            at(index),
-            `${prop}: ${value}. ${axis} is one axis. Set every axis from one text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
-          );
-          continue;
-        }
-
-        // Of the literals only absolute type values are a finding. `em`, `%`,
-        // and a unitless line-height are relative to the inherited type, so
-        // they ride whatever the theme sets rather than overriding it.
-        if (
-          !value.includes('var(') &&
-          !/^(inherit|initial|unset|normal)$/.test(value) &&
-          /\d(px|rem|pt)\b|^[a-z"']/i.test(value)
-        ) {
-          add(
-            'raw-text-axis',
-            at(index),
-            `${prop}: ${value}. Set type from a text style bundle (--heading-*, --body-*, --editorial-*, --code-*).`,
-          );
-          continue;
-        }
-      }
-
-      if (THEMED_GEOMETRY.test(prop) && hasDimensionLiteral(painted)) {
-        add(
-          'dimension-literal',
-          at(index),
-          `${prop}: ${value}. Use a --space-*, --radius-*, --border-width-*, or --shadow-* token.`,
-        );
-      }
-
-      const columns = value.match(/\brepeat\(\s*(\d+)\s*,\s*1fr\s*\)/);
-      if (columns && Number(columns[1]) >= PAGE_GRID_COLUMNS) {
-        add(
-          'hardcoded-columns',
-          at(index),
-          `${prop}: ${value}. Use repeat(var(--columns-count), 1fr) so the page grid stays in step.`,
-        );
-      }
-    }
-  }
+  componentUse.checkPropertyOverrides({ text, regions, inlineRegions, vocab }, add);
+  tokenRules.checkPageValues({ text, regions, inlineRegions, vocab }, add);
 
   return findings;
 }

package/bin/cli.mjs

@@ -18,15 +18,18 @@ 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,
@@ -74,10 +77,20 @@ Commands:
                               @playwright/test, vitest, and happy-dom; a
                               missing one is a tests-not-installed finding
                               naming the install command
-  check-page [paths...]       Validate pages against the live-tokens-create-page
+  check-page [paths...] [--tests]
+                              Validate pages against the live-tokens-create-page
                               contract: catalogue components only, and every CSS
                               value a design token. Checks every page under src/
-                              when given no paths.
+                              when given no paths. --tests also opens each
+                              page's own route in the consumer's own app and
+                              proves, per shipped rule id, that the cascade
+                              painted every component from its semantic
+                              properties, every run of text sits in one shipped
+                              text style, every text/surface pair meets AA,
+                              sections sit on the page grid, and nothing
+                              overflows. Needs @playwright/test, vitest, and
+                              happy-dom; a missing one is a tests-not-installed
+                              finding naming the install command
 
 check-component and check-page also accept:
   --json                      Machine-readable findings, for a skill to iterate
@@ -87,6 +100,15 @@ 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 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
@@ -183,14 +205,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
@@ -198,6 +220,29 @@ 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(', ')}`;
+}
+
+/** 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(`  fixed    ${f.file}:${f.line}  ${f.details.patch.from} → ${f.details.patch.to || '(removed)'}  [${f.rule}]${shiftNote(f)}`);
+  }
+  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());
@@ -246,21 +291,26 @@ 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)]);
+  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)]);
+  }
   if (!opts.tests && 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, 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([...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),
   });
@@ -269,8 +319,26 @@ 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() });
-  reportChecks('check-page', findings, checked, 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() }));
+  }
+  if (!opts.tests) {
+    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());
+  const testOutcome = await runPageTests(pageTargets, { root: process.cwd() });
+  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),
+  });
 }
 
 if (command === 'set-colors') {