@nurix/etna 0.19.10 → 0.19.12

package/data/harnesses/code/skills/design/scripts/lib/checks.mjs

@@ -1,1092 +0,0 @@
-// skills/design/scripts/lib/checks.mjs — the machine-check engine (beam 2, D19): every detector=source catalog rule as pure regex/token analysis over .tsx/.ts/.css/.html text, plus the lever-manifest drift check (cod-02, D10) whose vocabulary is read from the project's design-tokens artifact (design.tokens.json). Pure library — no argv, no CLI banner, no process.exit; fired at structural boundaries by phase-gate.mjs, preship-sweep.mjs, and self-integrity.mjs. Findings are [{rule, file, line, excerpt, fix}].
-import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-import { findBudgetStamps, MOTION_STAGGER_CLASS, STAGGER_CHILD_CAP } from './vocabulary.mjs';
-
-// ---------------------------------------------------------------------------
-// File-type routing
-// ---------------------------------------------------------------------------
-
-export const CHECKABLE_EXTS = ['.tsx', '.ts', '.css', '.html'];
-
-// Detect the file's extension bucket, or null when it is not a checkable type.
-export function extOf(path) {
-  const m = path.toLowerCase().match(/\.(tsx|ts|css|html)$/);
-  return m ? m[1] : null;
-}
-
-// Recursively collect checkable UI files under a dir, skipping node_modules and dotfiles.
-export function walkUiFiles(dir, acc = []) {
-  if (!existsSync(dir)) return acc;
-  let entries;
-  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
-  for (const ent of entries) {
-    if (ent.name === 'node_modules' || ent.name.startsWith('.')) continue;
-    const full = join(dir, ent.name);
-    if (ent.isDirectory()) walkUiFiles(full, acc);
-    else if (CHECKABLE_EXTS.some((e) => ent.name.endsWith(e))) acc.push(full);
-  }
-  return acc;
-}
-
-// Read the passed files into check-ready docs, skipping unreadable and uncheckable ones.
-export function loadDocs(files) {
-  const docs = [];
-  for (const file of files) {
-    const ext = extOf(file);
-    if (!ext) continue;
-    let text;
-    try { text = readFileSync(file, 'utf8'); } catch { continue; }
-    docs.push({ file, ext, text, lines: text.split('\n') });
-  }
-  return docs;
-}
-
-// ---------------------------------------------------------------------------
-// Color parsing (zero-dep): hex / rgb / hsl / oklch -> saturation signal
-// ---------------------------------------------------------------------------
-
-// Expand a 3- or 4-nibble hex to its 6/8-nibble form; return the lowercased hex digits.
-function expandHex(hex) {
-  let h = hex.replace('#', '').toLowerCase();
-  if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('');
-  return h;
-}
-
-// Convert an r/g/b triple (0-255) to HSL saturation and lightness (both 0-1).
-function rgbToSl(r, g, b) {
-  const rr = r / 255, gg = g / 255, bb = b / 255;
-  const max = Math.max(rr, gg, bb), min = Math.min(rr, gg, bb);
-  const l = (max + min) / 2;
-  const d = max - min;
-  const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
-  return { s, l };
-}
-
-// Parse one color literal into { sat, light } (HSL, 0-1) or { oklchChroma } or null.
-function parseColor(lit) {
-  const s = lit.trim().toLowerCase();
-  if (s.startsWith('#')) {
-    const h = expandHex(s.match(/#[0-9a-f]{3,8}/i)?.[0] || s);
-    if (h.length < 6) return null;
-    const r = parseInt(h.slice(0, 2), 16);
-    const g = parseInt(h.slice(2, 4), 16);
-    const b = parseInt(h.slice(4, 6), 16);
-    if ([r, g, b].some(Number.isNaN)) return null;
-    const { s: sat, l } = rgbToSl(r, g, b);
-    return { sat, light: l };
-  }
-  const rgb = s.match(/rgba?\(([^)]*)\)/);
-  if (rgb) {
-    const parts = rgb[1].split(/[\s,/]+/).filter(Boolean).slice(0, 3).map(Number);
-    if (parts.length < 3 || parts.some(Number.isNaN)) return null;
-    const { s: sat, l } = rgbToSl(parts[0], parts[1], parts[2]);
-    return { sat, light: l };
-  }
-  const hsl = s.match(/hsla?\(([^)]*)\)/);
-  if (hsl) {
-    const parts = hsl[1].split(/[\s,/]+/).filter(Boolean);
-    if (parts.length < 3) return null;
-    const sat = parseFloat(parts[1]) / 100;
-    const light = parseFloat(parts[2]) / 100;
-    if (Number.isNaN(sat) || Number.isNaN(light)) return null;
-    return { sat, light };
-  }
-  const okl = s.match(/oklch\(([^)]*)\)/);
-  if (okl) {
-    const parts = okl[1].split(/[\s,/]+/).filter(Boolean);
-    if (parts.length < 2) return null;
-    const chroma = parseFloat(parts[1]);
-    if (Number.isNaN(chroma)) return null;
-    return { oklchChroma: chroma };
-  }
-  return null;
-}
-
-// Decide whether a parsed color exceeds the accent saturation ceiling (col-02, <80%).
-function overAccentSaturation(parsed) {
-  if (!parsed) return false;
-  if (typeof parsed.oklchChroma === 'number') return parsed.oklchChroma > 0.37 * 0.8; // 0.296 heuristic
-  if (parsed.light == null || parsed.light < 0.12 || parsed.light > 0.92) return false; // sat is unstable near black/white
-  return parsed.sat >= 0.8;
-}
-
-// Normalize a color literal for set membership (drift compare): strip inner spaces, lowercase, expand short hex.
-function normColor(lit) {
-  let s = lit.trim().toLowerCase().replace(/\s+/g, '');
-  const hx = s.match(/^#[0-9a-f]{3,8}$/);
-  if (hx) return '#' + expandHex(s);
-  return s;
-}
-
-// ---------------------------------------------------------------------------
-// Value regexes shared by several rules
-// ---------------------------------------------------------------------------
-
-const RE_COLOR_LITERAL = /#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)|oklch\([^)]*\)/g;
-
-// CSS generic + system family keywords — never counted as declared app families (typ-06);
-// narrower than SYSTEM_FONT_KEYWORDS, whose web-safe named fonts (Roboto, Arial…) DO count.
-const GENERIC_FAMILY_KEYWORDS = new Set([
-  'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy', 'math', 'emoji', 'fangsong',
-  'system-ui', 'ui-sans-serif', 'ui-serif', 'ui-monospace', 'ui-rounded',
-  '-apple-system', 'blinkmacsystemfont', 'sfmono-regular',
-]);
-
-// Base signature of a color literal — the first three channels with the alpha slot stripped,
-// hex unified onto rgb — so an emitted color whose alpha rides var()/calc() (the intensity-
-// multiplied shadow layers, which RE_COLOR_LITERAL truncates mid-calc) can still be matched
-// against the manifest vocabulary.
-function colorBaseSig(lit) {
-  const s = lit.trim().toLowerCase();
-  if (/^#[0-9a-f]{3,8}$/.test(s)) {
-    const h = expandHex(s);
-    return `rgb:${parseInt(h.slice(0, 2), 16)},${parseInt(h.slice(2, 4), 16)},${parseInt(h.slice(4, 6), 16)}`;
-  }
-  const fn = s.match(/^(rgba?|hsla?|oklch)\(([^/)]*)/);
-  if (!fn) return null;
-  const nums = fn[2].match(/-?\d*\.?\d+%?/g);
-  if (!nums || nums.length < 3) return null;
-  const kind = fn[1].startsWith('rgb') ? 'rgb' : fn[1].startsWith('hsl') ? 'hsl' : 'oklch';
-  return `${kind}:${nums.slice(0, 3).join(',')}`;
-}
-const TW_UTILITY = '(?:bg|text|border|ring|ring-offset|fill|stroke|from|via|to|outline|divide|decoration|caret|accent|placeholder|shadow)';
-const PALETTE_HUES = 'red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|grey|zinc|neutral|stone';
-const RE_PALETTE_CLASS = new RegExp(`\\b${TW_UTILITY}-(${PALETTE_HUES})-(\\d{2,3})\\b`, 'g');
-const STATUS_HUES = new Set(['red', 'rose', 'orange', 'amber', 'yellow', 'green', 'emerald', 'lime']);
-
-// A spacing value in px is on the 4/8 scale (or the dense 2px step) when it is 0, 2, or a multiple of 4.
-function spacingOnScale(px) { return px === 0 || px === 2 || px % 4 === 0; }
-const RADIUS_SCALE = new Set([0, 2, 4, 6, 8, 12, 16, 24, 9999]);
-const ZINDEX_SCALE = new Set([0, 10, 20, 40, 100, 1000]);
-
-// Convert a rem or px length token to px (16px root); return null when it is neither.
-function toPx(numStr, unit) {
-  const n = parseFloat(numStr);
-  if (Number.isNaN(n)) return null;
-  if (unit === 'rem') return n * 16;
-  if (unit === 'px' || unit === '') return n;
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Findings sink
-// ---------------------------------------------------------------------------
-
-// Build a findings collector that de-dupes on (rule, file, line, excerpt).
-export function makeSink() {
-  const seen = new Set();
-  const list = [];
-  return {
-    add(rule, file, line, excerpt, fix) {
-      const ex = (excerpt || '').trim().slice(0, 200);
-      const key = `${rule}|${file}|${line}|${ex}`;
-      if (seen.has(key)) return;
-      seen.add(key);
-      list.push({ rule, file, line, excerpt: ex, fix });
-    },
-    list,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Per-line checks (run once per source line)
-// ---------------------------------------------------------------------------
-
-// Run every single-line source check against one line and record any violations.
-export function checkLine(add, file, ext, lineNo, line, fileText) {
-  const isJsx = ext === 'tsx' || ext === 'ts' || ext === 'html';
-  const isCss = ext === 'css';
-
-  // --- Color ---
-  if (isJsx) {
-    // col-05: literal palette classes, hex/rgb/oklch literals, and dark: prefixes in JSX.
-    for (const m of line.matchAll(RE_PALETTE_CLASS)) {
-      add('col-05', file, lineNo, m[0], 'Replace the literal palette class with a semantic token class (bg-primary, text-muted-foreground, border-border).');
-      if (STATUS_HUES.has(m[1])) add('col-04', file, lineNo, m[0], 'Route status color through a semantic token: --success, --warning, or --destructive (e.g. text-success), never a raw palette hue.');
-    }
-    if (/\bdark:/.test(line)) add('col-05', file, lineNo, (line.match(/\bdark:[\w[\]/.-]+/) || ['dark:'])[0], 'Drop the dark: prefix; light is the default theme and dark is opted in at the token layer, not per class.');
-    for (const m of line.matchAll(RE_COLOR_LITERAL)) {
-      add('col-05', file, lineNo, m[0], 'Move the color literal into a semantic token; components consume tokens (bg-card, text-foreground), never raw hex/rgb/oklch.');
-    }
-  }
-  // col-02: accent saturation ceiling. JSX: any literal; CSS: only accent-role token definitions.
-  if (isJsx) {
-    for (const m of line.matchAll(RE_COLOR_LITERAL)) {
-      if (overAccentSaturation(parseColor(m[0]))) add('col-02', file, lineNo, m[0], 'Desaturate the accent below the 80% saturation ceiling (or oklch chroma <= 0.30); reserve one restrained accent.');
-    }
-  } else if (isCss && /--(?:primary|accent|ring)\b/.test(line)) {
-    for (const m of line.matchAll(RE_COLOR_LITERAL)) {
-      if (overAccentSaturation(parseColor(m[0]))) add('col-02', file, lineNo, m[0], 'The accent/primary/ring token exceeds the 80% saturation ceiling (oklch chroma <= 0.30); pull it down a step.');
-    }
-  }
-  // col-06: pure black / pure white literals.
-  {
-    const pm = line.match(/#000000\b|#000\b|#ffffff\b|#fff\b|rgb\(\s*0\s*,\s*0\s*,\s*0\s*\)|rgb\(\s*255\s*,\s*255\s*,\s*255\s*\)/i);
-    if (pm) add('col-06', file, lineNo, pm[0], 'Never pure #000000/#ffffff; start near #111827/#1F2937 for ink and an off-white surface, declared as a token.');
-  }
-  // col-07: opacity- or rgba-fabricated shades (rgba/hsla with alpha, 8-digit hex).
-  {
-    const fm = line.match(/#[0-9a-fA-F]{8}\b|rgba\([^)]*\)|hsla\([^)]*\)/);
-    if (fm && !/\b(?:overlay|scrim|backdrop|modal)\b/i.test(line)) add('col-07', file, lineNo, fm[0], 'Do not fabricate a shade via alpha; declare the shade as an explicit hex/oklch token instead.');
-  }
-  // col-09: disabled-state opacity band (0.38-0.5).
-  for (const m of line.matchAll(/(?:disabled:opacity-|opacity-)(\d{1,3})\b/g)) {
-    if (!/disabled/.test(line)) continue;
-    const o = parseInt(m[1], 10) / 100;
-    if (o < 0.38 || o > 0.5) add('col-09', file, lineNo, m[0], 'Set the disabled opacity into the 0.38-0.5 muted band (Tailwind opacity-40/45).');
-  }
-  // col-10: modal scrim opacity band (40-60% black).
-  if (/\b(?:overlay|scrim|backdrop)\b/i.test(line)) {
-    for (const m of line.matchAll(/bg-black\/(\d{1,3})\b/g)) {
-      const p = parseInt(m[1], 10);
-      if (p < 40 || p > 60) add('col-10', file, lineNo, m[0], 'Put the modal scrim in the 40-60% black band (bg-black/50).');
-    }
-  }
-  // col-13: semantic status color used as a solid fill (never a fill).
-  {
-    const cm = line.match(/\bbg-(?:success|warning)\b|\bbg-(?:green|emerald|amber|yellow|orange|rose)-\d{2,3}\b/);
-    if (cm && !/\/\d/.test(cm[0])) add('col-13', file, lineNo, cm[0], 'Status/price color is text-only, never a solid fill; use the token as text/border (text-success) or a low-opacity tint on a badge.');
-  }
-
-  // --- Typography ---
-  // typ-02: any explicit font-size below 11px.
-  for (const m of line.matchAll(/(?:font-size\s*:\s*|text-\[)(\d*\.?\d+)(px|rem)?/g)) {
-    const px = toPx(m[1], m[2] || 'px');
-    if (px != null && px < 11) add('typ-02', file, lineNo, m[0], 'Never render below 11px; body sits at 14px+ on operator surfaces.');
-  }
-  // typ-03: input font-size below 16px, only on a touch/mobile surface (scope-guarded).
-  if (/<(?:input|textarea)\b/i.test(line) && /(?:touch|mobile|viewport-fit|maximum-scale)/i.test(fileText)) {
-    for (const m of line.matchAll(/text-\[(\d*\.?\d+)(px|rem)?\]/g)) {
-      const px = toPx(m[1], m[2] || 'px');
-      if (px != null && px < 16) add('typ-03', file, lineNo, m[0], 'Form inputs on touch/mobile surfaces are >= 16px to defeat iOS zoom.');
-    }
-  }
-  // typ-05: prose measure declared in ch, outside 45-75.
-  for (const m of line.matchAll(/(?:max-width\s*:\s*|max-w-\[)(\d+)ch/g)) {
-    const ch = parseInt(m[1], 10);
-    if (ch < 45 || ch > 75) add('typ-05', file, lineNo, m[0], 'Keep prose measure in the 45-75ch readable band (data tables are exempt).');
-  }
-  // typ-08: uppercase micro-label tracking and the negative tracking floor.
-  {
-    const neg = line.match(/(?:letter-spacing\s*:\s*|tracking-\[)(-?\d*\.?\d+)em/);
-    if (neg && parseFloat(neg[1]) < -0.04) add('typ-08', file, lineNo, neg[0], 'Letter-spacing never below the -0.04em floor.');
-    // A `--tracking-tighter: var(…)` @theme line REMAPS the utility onto an authored token —
-    // that definition is the fix for this rule, not a violation; literal values still fall
-    // to the numeric floor check above.
-    if (/\btracking-tighter\b/.test(line) && !/--tracking-tighter\s*:\s*var\(/.test(line)) add('typ-08', file, lineNo, 'tracking-tighter', 'tracking-tighter (-0.05em) is below the -0.04em floor; use tracking-tight at most.');
-    if (/\buppercase\b/.test(line) && !/tracking-(?:wide|wider|widest|\[)/.test(line)) add('typ-08', file, lineNo, 'uppercase', 'All-caps micro-labels carry positive tracking (>= 0.02em, caps band 0.05-0.12em); add tracking-wide.');
-  }
-  // typ-09: viewport-fluid font sizing.
-  {
-    const vm = line.match(/(?:font-size\s*:[^;]*|text-\[[^\]]*)(?:\d*\.?\d+(?:vw|vh)|clamp\()/);
-    if (vm) add('typ-09', file, lineNo, vm[0], 'Font sizes come from a fixed rem scale; ban vw/vh/clamp on font-size.');
-  }
-  // typ-11: UI font weight below 400.
-  {
-    const wm = line.match(/(?:font-weight\s*:\s*|font-\[)(\d{3})\]?/);
-    if (wm && parseInt(wm[1], 10) < 400) add('typ-11', file, lineNo, wm[0], 'No UI font weight below 400.');
-    if (/\bfont-(?:thin|extralight|light)\b/.test(line)) add('typ-11', file, lineNo, (line.match(/font-(?:thin|extralight|light)/) || [''])[0], 'No UI font weight below 400 (font-thin/extralight/light are 100-300).');
-  }
-  // typ-12: type sized in em.
-  {
-    const em = line.match(/(?:font-size\s*:\s*|text-\[)(\d*\.?\d+)em/);
-    if (em) add('typ-12', file, lineNo, em[0], 'Never size type in em (it compounds); use px or rem.');
-  }
-  // typ-16: serif font family (not sans-serif).
-  {
-    const sf = line.match(/font-?family\s*:\s*[^;}]*\bserif\b|font-serif\b/i);
-    if (sf && !/sans-serif/i.test(sf[0])) add('typ-16', file, lineNo, sf[0].trim(), 'Serif faces are banned in dashboards/software UIs; use the sans family.');
-  }
-  // typ-19: mono/code type sized below 16px.
-  if (/font-mono\b|font-family\s*:[^;]*monospace|<(?:code|pre)\b/i.test(line)) {
-    for (const m of line.matchAll(/text-\[(\d*\.?\d+)(px|rem)?\]|text-(xs|sm)\b/g)) {
-      if (m[3]) { add('typ-19', file, lineNo, m[0], 'Code/mono type is fixed at 16px; long lines scroll horizontally, never shrink.'); continue; }
-      const px = toPx(m[1], m[2] || 'px');
-      if (px != null && px < 16) add('typ-19', file, lineNo, m[0], 'Code/mono type is fixed at 16px; long lines scroll horizontally, never shrink.');
-    }
-  }
-
-  // --- Spatial ---
-  // spc-01: explicit (arbitrary/CSS) spacing value off the 4/8 scale.
-  for (const m of line.matchAll(/(?:[pm][trblxy]?|gap(?:-[xy])?|space-[xy]|inset)-\[(\d*\.?\d+)(px|rem)?\]/g)) {
-    const px = toPx(m[1], m[2] || 'px');
-    if (px != null && !spacingOnScale(px)) add('spc-01', file, lineNo, m[0], `Land the spacing on the 4/8 scale (nearest step to ${px}px); ${px}px is off-scale.`);
-  }
-  if (isCss) {
-    for (const m of line.matchAll(/(?:padding|margin|gap|top|left|right|bottom)\s*:\s*([^;]+);/g)) {
-      for (const v of m[1].matchAll(/(\d*\.?\d+)(px|rem)/g)) {
-        const px = toPx(v[1], v[2]);
-        if (px != null && px !== 1 && !spacingOnScale(px)) add('spc-01', file, lineNo, v[0], `Land the spacing on the 4/8 scale (nearest step to ${px}px); ${px}px is off-scale.`);
-      }
-    }
-  }
-  // spc-04: center-aligned data column.
-  if (/<t[dh]\b/i.test(line) && /\btext-center\b/.test(line)) add('spc-04', file, lineNo, 'text-center', 'Numeric columns right-align, text left-aligns; never center-align a data column.');
-  // spc-06: corner radius off the fixed scale.
-  for (const m of line.matchAll(/(?:border-radius\s*:\s*|rounded-\[)(\d*\.?\d+)(px|rem)?/g)) {
-    const px = toPx(m[1], m[2] || 'px');
-    if (px != null && !RADIUS_SCALE.has(px)) add('spc-06', file, lineNo, m[0], `Corners land on the fixed radius scale (0/2/4/6/8/12/16/24/full); ${px}px is off-scale.`);
-  }
-  // spc-07: a button taller than the 28px dense-row cap sitting inside a table row.
-  if (/<t[dh]\b/i.test(line) && /<[Bb]utton\b/.test(line)) {
-    const bh = line.match(/\bh-(?:8|9|10|11|12|14|16|20)\b|\bh-\[(\d+)px\]|\bmin-h-\[(\d+)px\]/);
-    if (bh) {
-      const px = (bh[1] || bh[2]) ? parseInt(bh[1] || bh[2], 10) : 99;
-      if (px > 28) add('spc-07', file, lineNo, bh[0], 'Dense table rows compact their buttons to 28px (h-7); trim the control height and keep mono numerals on figures.');
-    }
-  }
-  // spc-08: full-viewport height via h-screen / 100vh instead of dvh.
-  {
-    const hm = line.match(/\b(?:min-)?h-screen\b|100vh|h-\[100vh\]/);
-    if (hm) add('spc-08', file, lineNo, hm[0], 'Full-viewport height uses min-h-[100dvh]; never h-screen or 100vh.');
-  }
-  // spc-09: calc-percentage layout arithmetic.
-  {
-    const cm = line.match(/calc\([^)]*%[^)]*\)/);
-    if (cm) add('spc-09', file, lineNo, cm[0], 'Ban calc-percentage layout arithmetic; use CSS Grid instead.');
-  }
-
-  // --- Depth ---
-  // dep-01: z-index off the declared scale, or the banned 999/9999.
-  for (const m of line.matchAll(/(?:z-index\s*:\s*|z-\[)(\d{1,4})/g)) {
-    const z = parseInt(m[1], 10);
-    if (z === 999 || z === 9999 || !ZINDEX_SCALE.has(z)) add('dep-01', file, lineNo, m[0], 'z-index only from the declared scale (0/10/20/40/100/1000); ban 999 and 9999.');
-  }
-  // dep-04: a border and a heavy elevation shadow doing the same separation job.
-  if (/\bborder(?:-[24]|-solid|-\w+-\d)?\b/.test(line) && /\bshadow-(?:lg|xl|2xl)\b/.test(line)) {
-    add('dep-04', file, lineNo, (line.match(/shadow-(?:lg|xl|2xl)/) || [''])[0], 'Border and shadow are doing the same separation job; keep one (a hairline border or a shadow), not both heavy.');
-  }
-
-  // --- Interaction ---
-  // int-12: a non-button clickable element without cursor:pointer.
-  if (/<(?:div|span|li)\b[^>]*\bonClick=/.test(line) && !/cursor-pointer/.test(line)) {
-    add('int-12', file, lineNo, (line.match(/<(?:div|span|li)\b[^>]*onClick=[^ >]*/) || ['onClick'])[0], 'cursor:pointer on every clickable element; add cursor-pointer (or use a real <button>).');
-  }
-  // int-03: a hover-revealed control with no keyboard/focus path.
-  if (/(?:group-hover|hover):(?:opacity-100|block|flex|visible)\b/.test(line) && !/(?:group-focus-within|focus-within|focus-visible|group-focus):/.test(fileText)) {
-    add('int-03', file, lineNo, (line.match(/(?:group-hover|hover):(?:opacity-100|block|flex|visible)/) || [''])[0], 'No pointer-only affordances; give the hover-revealed control a focus/keyboard path (group-focus-within:).');
-  }
-  // int-04: a modal built on a div role="dialog" instead of native <dialog>.
-  if (/<div\b[^>]*role=["']dialog["']/.test(line)) add('int-04', file, lineNo, 'role="dialog"', 'Modals use native <dialog> with inert focus containment; prefer a side panel before a modal.');
-  // int-08: placeholder-as-label on a non-search input.
-  if (/<input\b/i.test(line) && /placeholder=/.test(line) && !/aria-label|aria-labelledby|type=["']search["']/.test(line) && !/placeholder=["'][^"']*[Ss]earch/.test(line) && !/<label/i.test(fileText)) {
-    add('int-08', file, lineNo, (line.match(/placeholder=["'][^"']*["']/) || ['placeholder'])[0], 'Labels stay visible above the input; ban placeholder-as-label (errors render inline below).');
-  }
-  // int-09: a sortable header with no aria-sort.
-  if (/<th\b/i.test(line) && /(?:onClick=|cursor-pointer|sortable)/.test(line) && !/aria-sort/.test(line)) {
-    add('int-09', file, lineNo, '<th> sortable', 'Sortable headers carry aria-sort; give the sortable <th> an aria-sort state.');
-  }
-  // int-11: a button group with a sub-8px gap between targets.
-  {
-    const gm = line.match(/\b(?:gap|space-x)-\[(\d*\.?\d+)px\]|\b(?:gap|space-x)-0(?:\.5)?\b|gap-px\b/);
-    if (gm && /<button|role=["']button["']|<a\b/.test(line)) {
-      const n = gm[1] != null ? parseFloat(gm[1]) : 0;
-      if (n < 8) add('int-11', file, lineNo, gm[0], 'Target-to-target spacing clears the 8px minimum gap.');
-    }
-  }
-  // int-02: outline removed with no replacement focus style anywhere in the file.
-  if (/\boutline-none\b|outline\s*:\s*none/.test(line) && !/(?:focus-visible:|focus:ring|:focus-visible|ring-[12]|focus:outline-\[)/.test(fileText)) {
-    add('int-02', file, lineNo, (line.match(/outline-none|outline\s*:\s*none/) || [''])[0], 'Ban outline:none without a replacement; add a :focus-visible ring (focus-visible:ring-2).');
-  }
-  // int-14: a raw button styling hover but neither focus nor disabled states.
-  if (/<button\b/i.test(line) && /hover:/.test(line) && !/(?:focus-visible:|focus:)/.test(line) && !/disabled:/.test(line)) {
-    add('int-14', file, lineNo, '<button>', 'All five button states are required: default, hover, active, focus, disabled; this button is missing focus/disabled.');
-  }
-
-  // --- Motion ---
-  // mot-01: an animation/transition duration over the 500ms ceiling.
-  for (const m of line.matchAll(/duration-\[(\d+)ms\]|duration-(700|1000)\b|(?:transition|animation)(?:-duration)?\s*:[^;]*?(\d*\.?\d+)(ms|s)/g)) {
-    let ms = null;
-    if (m[1]) ms = parseInt(m[1], 10);
-    else if (m[2]) ms = parseInt(m[2], 10);
-    else if (m[3]) ms = m[4] === 's' ? parseFloat(m[3]) * 1000 : parseFloat(m[3]);
-    if (ms != null && ms > 500) add('mot-01', file, lineNo, m[0], `UI transitions hold under the 500ms ceiling; ${ms}ms is too long.`);
-  }
-  // mot-04: banned easing (spring/bounce on operator surfaces, linear everywhere).
-  {
-    const lm = line.match(/\bease-linear\b|transition-timing-function\s*:\s*linear|animation-timing-function\s*:\s*linear/);
-    if (lm) add('mot-04', file, lineNo, lm[0], 'Ban linear easing; use the token ease-out (cubic-bezier(0,0,0.2,1)).');
-    if (/cubic-bezier\(\s*-?\d/.test(line)) {
-      const cb = line.match(/cubic-bezier\([^)]*\)/)[0];
-      const nums = cb.match(/-?\d*\.?\d+/g).map(Number);
-      if (nums.some((n) => n < 0 || n > 1)) add('mot-04', file, lineNo, cb, 'Ban spring/bounce easing (control points outside 0-1) on operator surfaces; use the token ease-out.');
-    }
-    if (/\b(?:ease-spring|ease-bounce|spring\()/.test(line)) add('mot-04', file, lineNo, (line.match(/ease-spring|ease-bounce|spring\(/) || [''])[0], 'Ban spring/bounce easing on operator surfaces; use the token ease-out.');
-  }
-  // mot-05: animating a layout property instead of transform/opacity.
-  {
-    const am = line.match(/transition-(?:all|left|top|width|height|margin)\b|transition\s*:\s*[^;]*\b(?:left|top|width|height|margin)\b|animate-\[[^\]]*\b(?:left|top|width|height|margin)\b/);
-    if (am) add('mot-05', file, lineNo, am[0], 'Animate only transform and opacity, never top/left/width/height/margin (transition-all included).');
-  }
-  // mot-06: will-change on a layout property or left standing without an animation.
-  {
-    const wm = line.match(/will-change\s*:\s*([^;]+)|will-change-\[?([\w,-]+)/);
-    if (wm) {
-      const val = (wm[1] || wm[2] || '').toLowerCase();
-      if (/left|top|width|height|margin|auto|all|scroll/.test(val) || (!/transform|opacity/.test(val))) {
-        add('mot-06', file, lineNo, wm[0], 'will-change only rides an in-progress transform/opacity animation; never blanket, never on a layout property, never left dangling.');
-      }
-    }
-  }
-  // mot-07: a loading indicator delay outside the 150-300ms band.
-  if (/skeleton|spinner|loading/i.test(line)) {
-    for (const m of line.matchAll(/(?:animation-delay|transition-delay|delay-\[)\s*:?\s*(\d+)ms/g)) {
-      const d = parseInt(m[1], 10);
-      if (d > 0 && (d < 150 || d > 300)) add('mot-07', file, lineNo, m[0], 'Loading-indicator delay sits in the 150-300ms band (nothing appears under 500ms).');
-    }
-  }
-  // mot-08 (numeric half): the per-item stagger unit holds the 0-60ms band, a declared cascade never
-  // reaches past the child cap, and no stagger delay lands at or over the 1s sequence ceiling. Child
-  // count and the actual total are confirmed on the rendered DOM at the render rung.
-  {
-    const unit = line.match(/--stagger-unit\s*:\s*(-?\d*\.?\d+)ms/);
-    if (unit && (parseFloat(unit[1]) < 0 || parseFloat(unit[1]) > 60)) {
-      add('mot-08', file, lineNo, unit[0], 'The stagger-unit token holds 0-60ms per item; pull the unit back into the band.');
-    }
-    const idxDelay = line.match(/(?:animationDelay|animation-delay|transitionDelay|transition-delay)[^;,}]*?(?:\b(?:i|idx|index)\s*\*\s*(\d*\.?\d+)|(\d*\.?\d+)\s*\*\s*(?:i|idx|index)\b)/);
-    if (idxDelay && parseFloat(idxDelay[1] ?? idxDelay[2]) > 60) {
-      add('mot-08', file, lineNo, idxDelay[0].slice(0, 60), 'Per-item stagger delay exceeds the 0-60ms unit band; derive it from the stagger-unit token (0-60ms).');
-    }
-    const calcUnit = line.match(/(?:animation|transition)-delay\s*:\s*calc\(\s*(\d*\.?\d+)ms\s*\*/);
-    if (calcUnit && parseFloat(calcUnit[1]) > 60) {
-      add('mot-08', file, lineNo, calcUnit[0], 'Per-item stagger delay exceeds the 0-60ms unit band; ride the stagger-unit token instead of a raw multiplier.');
-    }
-    if (/(?:animation|transition)-delay/.test(line)) {
-      const nth = line.match(/nth-child\((\d+)\)/);
-      if (nth && parseInt(nth[1], 10) > STAGGER_CHILD_CAP) {
-        add('mot-08', file, lineNo, nth[0], `Stagger cascades cap at ${STAGGER_CHILD_CAP} children; children past the cap arrive together.`);
-      }
-      if (/stagger|nth-child/i.test(line)) {
-        for (const m of line.matchAll(/(?:animation|transition)-delay\s*:\s*(\d*\.?\d+)(ms|s)\b/g)) {
-          const ms = m[2] === 's' ? parseFloat(m[1]) * 1000 : parseFloat(m[1]);
-          if (ms >= 1000) add('mot-08', file, lineNo, m[0], 'A stagger sequence totals under 1s; this per-item delay alone reaches the ceiling.');
-        }
-      }
-    }
-  }
-  // mot-09: scroll-event listener driving animation.
-  if (/addEventListener\(\s*["']scroll["']/.test(line)) add('mot-09', file, lineNo, 'addEventListener("scroll")', 'Ban scroll-event listeners for animation; use IntersectionObserver or scroll-linked scrubbing.');
-  // mot-10: useState fed by a continuous scroll/pointer value.
-  if (/set\w+\(/.test(line) && /on(?:Scroll|MouseMove|PointerMove)=/.test(line)) {
-    add('mot-10', file, lineNo, (line.match(/on(?:Scroll|MouseMove|PointerMove)=[^ >]*/) || [''])[0], 'Ban useState for continuous scroll/pointer values; drive them with motion values instead.');
-  }
-
-  // --- States ---
-  // sta-05: a toast duration outside the 3-5s band.
-  for (const m of line.matchAll(/duration\s*[:=]\s*\{?\s*(\d{3,5})/g)) {
-    if (!/toast|Toaster|sonner/i.test(line)) continue;
-    const d = parseInt(m[1], 10);
-    if (d < 3000 || d > 5000) add('sta-05', file, lineNo, m[0], 'Toasts auto-dismiss in the 3-5s band, announce politely (aria-live="polite"), and never steal focus.');
-  }
-
-  // --- Code & tokens ---
-  // cod-03: a raw color/spacing/radius/duration literal inside an inline style object.
-  if (isJsx && /style=\{\{/.test(line)) {
-    const sm = line.match(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|oklch\([^)]*\)|:\s*['"]?\d+px|:\s*['"]?\d+ms/);
-    if (sm) add('cod-03', file, lineNo, sm[0], 'Every color/spacing/radius/duration resolves to an emitted token; do not inline a raw literal in a style prop.');
-  }
-  // cod-04: elision comments and brevity markers.
-  {
-    const cm = line.match(/\/\/\s*\.\.\.|\/\/\s*(?:rest of|remaining|existing)\b|\{\s*\/\*\s*\.\.\.|\/\*\s*\.\.\.\s*\*\/|\bfor brevity\b|\/\/\s*TODO\b/i);
-    if (cm) add('cod-04', file, lineNo, cm[0], 'No elision/brevity/TODO comments; emit the whole file, compiling.');
-  }
-  // cod-05: fabricated names, placeholder companies, and fake round metrics.
-  {
-    const fm = line.match(/\bJohn Doe\b|\bJane Doe\b|\bAcme\b|\bLorem ipsum\b|\bBY THE NUMBERS\b|\b99\.9[89]%|\b100% (?:uptime|guaranteed)\b/i);
-    if (fm) add('cod-05', file, lineNo, fm[0], 'Anti-fabrication: no invented metrics or placeholder names; use real data, a [bracket] placeholder, or mark mock numbers.');
-  }
-  // cod-07: a Google Fonts <link>/@import in production.
-  if (/fonts\.googleapis\.com|fonts\.gstatic\.com/.test(line)) add('cod-07', file, lineNo, (line.match(/https?:\/\/fonts\.[^"'\s)]+/) || ['fonts.googleapis.com'])[0], 'Never a Google Fonts link in prod; self-host or use next/font with font-display: swap.');
-  // cod-08: an <img> hotlinked or without declared dimensions / lazy-load.
-  if (/<img\b/i.test(line)) {
-    if (!/\bwidth=|\bheight=/.test(line)) add('cod-08', file, lineNo, '<img>', 'Images declare width/height (avoid CLS); below-the-fold images add loading="lazy".');
-    const src = line.match(/src=["'](https?:\/\/[^"']+)["']/);
-    if (src && !/picsum\.photos\/seed\//.test(src[1])) add('cod-08', file, lineNo, src[1], 'Image placeholders are deterministic seeds (picsum.photos/seed/{seed}/{w}/{h}), never a live hotlink.');
-  }
-  // cod-06: emoji character in source.
-  if (RE_EMOJI.test(line)) add('cod-06', file, lineNo, (line.match(RE_EMOJI) || [''])[0], 'No emoji anywhere and no emoji-as-icons; use inline SVG from one icon family.');
-  RE_EMOJI.lastIndex = 0;
-}
-
-const RE_EMOJI = /[\u{1F300}-\u{1FAFF}\u{1F1E6}-\u{1F1FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{2B00}-\u{2BFF}\u{FE0F}]/u;
-
-// Blank out // line comments and /* */ (incl. JSX {/* */}) block comments, preserving line count, so copy checks skip commentary.
-export function cleanComments(lines) {
-  const out = [];
-  let inBlock = false;
-  for (let raw of lines) {
-    let s = raw;
-    if (inBlock) {
-      const end = s.indexOf('*/');
-      if (end < 0) { out.push(''); continue; }
-      s = ' '.repeat(end + 2) + s.slice(end + 2);
-      inBlock = false;
-    }
-    // strip inline /* ... */ occurrences
-    s = s.replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length));
-    const openBlock = s.indexOf('/*');
-    if (openBlock >= 0 && s.indexOf('*/', openBlock) < 0) { s = s.slice(0, openBlock); inBlock = true; }
-    // strip // line comment when not part of :// (a URL scheme)
-    const lc = s.match(/(^|[^:])\/\/.*$/);
-    if (lc) s = s.slice(0, lc.index + lc[1].length);
-    out.push(s);
-  }
-  return out;
-}
-
-// Scan comment-stripped copy for em-dashes (typ-15) and three-period ellipses (typ-14).
-export function checkCopy(add, file, cleaned) {
-  cleaned.forEach((line, i) => {
-    if (line.includes('—')) add('typ-15', file, i + 1, line.trim(), 'Zero em-dashes in UI copy; recast the sentence or use a colon/en-dash.');
-    const el = line.match(/\.\.\.(?![\w$.([{])/);
-    if (el) add('typ-14', file, i + 1, '...', 'Use the ellipsis glyph (or an explicit loading label), not three periods.');
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Whole-file checks (need more than one line of context)
-// ---------------------------------------------------------------------------
-
-// Run the file-scoped source checks over one file's full text.
-export function checkFile(add, file, ext, text, lines) {
-  const isJsx = ext === 'tsx' || ext === 'ts';
-
-  // dep-02: more than one <h1> in a view.
-  const h1s = [...text.matchAll(/<h1\b/gi)];
-  if (h1s.length > 1) {
-    const idx = text.slice(0, h1s[1].index).split('\n').length;
-    add('dep-02', file, idx, `${h1s.length} <h1> elements`, 'One h1 per view; keep a single <h1> and never skip heading levels.');
-  }
-
-  // mot-03: an animation present with no prefers-reduced-motion guard.
-  const hasAnim = /@keyframes\b|\banimate-(?!none\b)[\w[\]-]+|\.animate\(|animation\s*:/i.test(text);
-  const hasGuard = /prefers-reduced-motion|motion-reduce:|useReducedMotion/i.test(text);
-  if (hasAnim && !hasGuard) {
-    const idx = (text.match(/@keyframes|animate-|animation\s*:/i) ? text.slice(0, text.search(/@keyframes|animate-|animation\s*:/i)).split('\n').length : 1);
-    add('mot-03', file, idx, 'animation without reduced-motion guard', 'Every animation is gated on prefers-reduced-motion (0.01ms reset / motion-reduce:).');
-  }
-
-  // typ-07: a numeric table context with no tabular figures anywhere in the file.
-  if (isJsx && /<td\b/i.test(text)) {
-    const numeric = /toLocaleString\(|toFixed\(|Intl\.NumberFormat|\$\{?[\w.]+\}?\s*(?:USD|amount|price|total)|\bformatCurrency\b/i.test(text);
-    const tabular = /tabular-nums|font-variant-numeric|lining-nums|slashed-zero|tnum/i.test(text);
-    if (numeric && !tabular) {
-      const idx = text.slice(0, text.search(/<td\b/i)).split('\n').length;
-      add('typ-07', file, idx, 'numeric table cells without tabular-nums', 'Tabular lining numerals (tabular-nums) on every numeric column, KPI, timer, and ID.');
-    }
-  }
-
-  // sta-01: a collection render with none of loading/empty/error handling.
-  // A module-local literal array (e.g. a static nav constant) is not a data
-  // surface — only collections that arrive as data (imports, props, hooks,
-  // fetches) demand lifecycle states.
-  if (isJsx && /\.map\(/.test(text)) {
-    const hasState = /length\s*===?\s*0|isEmpty|Empty|isLoading|\bloading\b|Skeleton|Spinner|isError|\berror\b|catch\b/i.test(text);
-    if (!hasState) {
-      const mapRe = /(\w+)(?:\.\w+)*\.map\(/g;
-      let m;
-      let firstDataMapIdx = -1;
-      while ((m = mapRe.exec(text)) !== null) {
-        const localLiteral = new RegExp(`const\\s+${m[1]}(?:\\s*:\\s*[^=]+)?=\\s*\\[`).test(text);
-        if (!localLiteral) { firstDataMapIdx = m.index; break; }
-      }
-      if (firstDataMapIdx !== -1) {
-        const idx = text.slice(0, firstDataMapIdx).split('\n').length;
-        add('sta-01', file, idx, 'collection render with no loading/empty/error state', 'Every data surface ships loading, empty, error, and partial/degraded states; none are present here.');
-      }
-    }
-  }
-  // sta-02: an empty state that dead-ends (literal no-data message) or carries >1 action.
-  if (isJsx && /(?:isEmpty|length\s*===?\s*0|Empty)/i.test(text)) {
-    const deadEnd = text.match(/>\s*(?:No data(?:\s+available)?|Nothing (?:here|to show)|No results found\.?)\s*</i);
-    if (deadEnd) add('sta-02', file, text.slice(0, deadEnd.index).split('\n').length, deadEnd[0].trim(), 'Empty states are text-first with a next step, never a literal no-data dead-end; 1-2 sentences and at most one action.');
-  }
-  // sta-03: an error-state render that dead-ends — no recovery affordance in the rendered error block.
-  // The three-part error copy (what / why / how) stays judged; this shell flags only the mechanical dead
-  // end that an error state offers the operator no way forward. Matches the canonical error-render forms
-  // (an early return, an inline &&/? render, or a catch that returns JSX) and looks for any recovery
-  // affordance (retry / reload / link / action / handler) in the block that follows.
-  if (isJsx) {
-    const errorRender = /if\s*\(\s*(?:isError|hasError|loadError)\b[^)]*\)\s*(?:\{[^}]*)?return|(?:isError|hasError|loadError)\s*(?:&&|\?)\s*\(?\s*<|if\s*\(\s*status\s*===?\s*['"](?:error|failed)['"][^)]*\)\s*(?:\{[^}]*)?return|\}\s*catch\s*(?:\([^)]*\))?\s*\{[^}]*return\s*[<(]/g;
-    const RECOVERY = /onClick|onRetry|onReload|onRefresh|href=|<a\b|<Button\b|<button\b|\bretry\b|\breload\b|\brefresh\b|\brefetch\b|try again|go back/i;
-    let em;
-    while ((em = errorRender.exec(text)) !== null) {
-      const windowText = text.slice(em.index, em.index + 600);
-      if (!RECOVERY.test(windowText)) {
-        add('sta-03', file, text.slice(0, em.index).split('\n').length, 'error state with no recovery affordance', 'Error states never dead-end: state what happened, why, and how to recover, and give a way forward (retry, reload, or a link out) — not a bare failure message.');
-        break;
-      }
-    }
-  }
-
-  // typ-20 / col-16 / mot-08 (orchestration half): budget-gated vocabulary against the surface's
-  // budget stamp (lib/vocabulary.mjs). The display ramp step, wash consumption, and arrival cascades
-  // are legal only on a file stamped brand-forward; a baseline-stamped or unstamped file consuming
-  // them is the deterministic violation. Fired at the surfaces gate and the preship sweep through
-  // this shared engine.
-  if (ext === 'tsx' || ext === 'html') {
-    const brandForward = findBudgetStamps(text).includes('brand-forward');
-    const lineOf = (idx) => text.slice(0, idx).split('\n').length;
-    const displayUses = [...text.matchAll(/\btext-display\b|var\(--text-display\b/g)];
-    if (displayUses.length && !brandForward) {
-      add('typ-20', file, lineOf(displayUses[0].index), displayUses[0][0], 'The display ramp step appears only on surfaces stamped brand-forward; re-classify the surface with a recorded reason, or step this element down the ramp (text-h1).');
-    } else if (displayUses.length > 1) {
-      add('typ-20', file, lineOf(displayUses[1].index), `${displayUses.length} display-step elements`, 'At most one display-step element per surface; keep the focal one and step the rest down the ramp.');
-    }
-    const washUse = text.match(/var\(--wash-[a-z-]+\)/);
-    if (washUse && !brandForward) {
-      add('col-16', file, lineOf(washUse.index), washUse[0], 'A wash token is consumed only on brand-forward-stamped surfaces; re-classify the surface with a recorded reason, or remove the wash.');
-    }
-    const staggerUse = text.match(new RegExp(`\\b${MOTION_STAGGER_CLASS}\\b`));
-    if (staggerUse && !brandForward) {
-      add('mot-08', file, lineOf(staggerUse.index), staggerUse[0], 'Baseline-stamped surfaces skip arrival cascades; remove motion-stagger, or re-classify the surface with a recorded reason.');
-    }
-  }
-
-  // int-01: a :focus / :focus-visible CSS rule that removes the outline with no visible ring replacement.
-  if (ext === 'css') {
-    for (const m of text.matchAll(/:focus(?:-visible)?\s*\{([^}]*)\}/g)) {
-      const body = m[1];
-      const removesOutline = /outline\s*:\s*(?:none|0)\b/.test(body);
-      const hasRing = /box-shadow\s*:\s*[^;]*\d/.test(body) || /outline-width\s*:/.test(body) || /outline-offset\s*:/.test(body) || /outline\s*:\s*[^;]*(?:px|rem|em|solid|auto|\d)/i.test(body) || /border(?:-\w+)?\s*:\s*[^;]*(?:px|solid|\d)/i.test(body) || /\bring-/.test(body);
-      if (removesOutline && !hasRing) add('int-01', file, text.slice(0, m.index).split('\n').length, m[0].replace(/\s+/g, ' ').slice(0, 60), 'Every interactive element ships a visible :focus-visible ring (>= 2px with offset); add a ring, do not merely remove the outline.');
-    }
-  }
-
-  // int-10: live-updating status (polling) with no aria-live region present.
-  if (isJsx && /setInterval\(/.test(text) && !/aria-live|role=["'](?:status|alert)["']/.test(text)) {
-    add('int-10', file, text.slice(0, text.search(/setInterval\(/)).split('\n').length, 'polling status update without aria-live', 'An aria-live region is present wherever async status updates render; wrap the live status in role="status" / aria-live="polite".');
-  }
-
-  // cod-01: a token-defining CSS file that omits some of the 36 consumed tokens. The trigger
-  // requires DEFINITIONS at property position — a consumer file's `--color-background: var(--background)`
-  // @theme mapping must not read as a token-defining file.
-  if (ext === 'css' && /^\s*--background\s*:/m.test(text) && /^\s*--foreground\s*:/m.test(text)) {
-    const missing = REQUIRED_TOKENS.filter((t) => !new RegExp(`--${t}\\s*:`).test(text));
-    if (missing.length) add('cod-01', file, 1, `missing tokens: ${missing.slice(0, 6).join(', ')}${missing.length > 6 ? '…' : ''}`, 'Emitted CSS defines every token the substrate consumes; add the missing --token definitions.');
-  }
-
-  // cod-09: a component file well over the line ceiling.
-  if (isJsx && lines.length > 250) add('cod-09', file, lines.length, `${lines.length} lines`, 'Component line ceilings hold (< 120 ln table, < 80 ln section); split this file.');
-
-  // cod-11: an exported component that takes props with no typed Props.
-  if (ext === 'tsx') {
-    const untyped = text.match(/export\s+(?:default\s+)?function\s+[A-Z]\w*\(\s*\{[^}]*\}\s*\)(?!\s*:)/) ||
-      text.match(/export\s+(?:default\s+)?function\s+[A-Z]\w*\(\s*props\s*\)/);
-    const hasTypedProps = /interface\s+\w*Props\b|type\s+\w*Props\b|:\s*\w*Props\b|React\.FC</.test(text);
-    if (untyped && !hasTypedProps) {
-      add('cod-11', file, text.slice(0, untyped.index).split('\n').length, untyped[0].slice(0, 60), 'Every emitted component exports a typed Props interface; annotate the props.');
-    }
-  }
-}
-
-const REQUIRED_TOKENS = [
-  'background', 'foreground', 'card', 'card-foreground', 'muted', 'muted-foreground', 'border', 'input', 'ring',
-  'primary', 'primary-foreground', 'accent', 'accent-foreground', 'destructive', 'destructive-foreground', 'success', 'warning',
-  'surface-raised', 'surface-overlay',
-  'popover', 'popover-foreground', 'secondary', 'secondary-foreground',
-  'chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5',
-  'sidebar', 'sidebar-foreground', 'sidebar-primary', 'sidebar-primary-foreground',
-  'sidebar-accent', 'sidebar-accent-foreground', 'sidebar-border', 'sidebar-ring',
-];
-
-// ---------------------------------------------------------------------------
-// Cross-file checks (aggregate over all files passed this invocation)
-// ---------------------------------------------------------------------------
-
-// Run the checks that need the whole passed-in file set (token-set counts, distinct sizes).
-export function checkCrossFile(add, docs) {
-  // typ-06: more than three font families declared across the passed files (fourth banned), or three
-  // families none of which carries the numeric-mono job.
-  const families = new Set();
-  const monoFamilies = new Set();
-  const iconLibs = new Set();
-  const explicitSizes = new Map(); // px -> {file,line,text}
-  const hexByHue = new Map();      // hue bucket -> Set(normHex)
-  let sectionCount = 0;
-  let capsTrackCount = 0;
-  let capsTrackAnchor = null;
-
-  for (const d of docs) {
-    d.lines.forEach((line, i) => {
-      // font families from declarations / --font-* family slots / font-[Family].
-      // --font-weight-*/--font-size-* carry numbers, not families; a stack whose first entry
-      // is a CSS generic (the emitted baseline's generics-only stacks) declares no family.
-      for (const m of line.matchAll(/font-family\s*:\s*([^;{}]+)[;}]?|--font-(?!weight-|size-)[\w-]+\s*:\s*([^;]+);|font-\[["']?([A-Za-z][\w\s-]+)["']?\]/g)) {
-        const raw = (m[1] || m[2] || m[3] || '').trim();
-        const first = raw.split(',')[0].replace(/["']/g, '').trim().toLowerCase();
-        if (first && !/^var\(/.test(first) && !GENERIC_FAMILY_KEYWORDS.has(first)) {
-          families.add(first);
-          // The numeric-mono job: declared as the mono slot or stacked onto a monospace generic.
-          if (/^--font-mono/.test(m[0]) || /\b(?:ui-)?monospace\b/i.test(raw)) monoFamilies.add(first);
-        }
-      }
-      // icon libraries from imports
-      const imp = line.match(/from\s+["'](lucide-react|@heroicons\/\w+|react-icons(?:\/\w+)?|@phosphor-icons\/\w+|phosphor-react)["']/);
-      if (imp) iconLibs.add(imp[1].split('/')[0]);
-      // explicit numeric font sizes (arbitrary tailwind or CSS), for typ-10
-      for (const m of line.matchAll(/text-\[(\d*\.?\d+)(px|rem)\]|font-size\s*:\s*(\d*\.?\d+)(px|rem)/g)) {
-        const px = m[1] ? toPx(m[1], m[2]) : toPx(m[3], m[4]);
-        if (px != null && !explicitSizes.has(px)) explicitSizes.set(px, { file: d.file, line: i + 1, text: (m[0]) });
-      }
-      // hex color families for col-08 over-count
-      for (const m of line.matchAll(/#[0-9a-fA-F]{6}\b/g)) {
-        const hue = hexHueBucket(m[0]);
-        if (!hexByHue.has(hue)) hexByHue.set(hue, new Set());
-        hexByHue.get(hue).add(normColor(m[0]));
-      }
-      // typ-18 section + caps-tracking tally
-      if (/<section\b/i.test(line)) sectionCount += (line.match(/<section\b/gi) || []).length;
-      if (/\buppercase\b/.test(line) && /tracking-(?:wide|wider|widest)/.test(line)) {
-        capsTrackCount++;
-        if (!capsTrackAnchor) capsTrackAnchor = { file: d.file, line: i + 1 };
-      }
-    });
-  }
-
-  if (families.size > 3) {
-    const d = docs[0];
-    add('typ-06', d.file, 1, `${families.size} font families: ${[...families].join(', ')}`, 'At most three font families per app, each with a distinct job (display / body / numeric-mono); a fourth family is banned — drop the extra.');
-  } else if (families.size === 3 && monoFamilies.size === 0) {
-    const d = docs[0];
-    add('typ-06', d.file, 1, `3 font families, none mono: ${[...families].join(', ')}`, 'Three families need three distinct jobs (display / body / numeric-mono); none of these is a declared mono — give the third family a real job or drop it.');
-  }
-
-  // typ-06 (scale half): distinct explicit sizes beyond the declared ramp's step count.
-  if (explicitSizes.size > 7) {
-    const anchorPx = [...explicitSizes.keys()].sort((a, b) => a - b)[7];
-    const anc = explicitSizes.get(anchorPx);
-    add('typ-06', anc.file, anc.line, `${explicitSizes.size} distinct explicit sizes`, 'The type scale holds the declared ramp\'s steps (<= 7); collapse the extras onto the ramp utilities (text-h1 … text-display).');
-  }
-
-  // typ-10: adjacent explicitly-declared type-scale steps closer than 25%.
-  const sizes = [...explicitSizes.keys()].sort((a, b) => a - b);
-  if (sizes.length >= 3) {
-    for (let i = 1; i < sizes.length; i++) {
-      if (sizes[i] / sizes[i - 1] < 1.25) {
-        const anc = explicitSizes.get(sizes[i]);
-        add('typ-10', anc.file, anc.line, `${sizes[i - 1]}px and ${sizes[i]}px`, 'Adjacent type-scale steps stay >= 25% apart; merge these near-duplicate steps.');
-      }
-    }
-  }
-  // spc-02 is checked with the same near-duplicate logic over explicit spacing (checkSpacingScale).
-
-  // col-08: a color family exceeding the 10-shade ceiling.
-  for (const [hue, set] of hexByHue) {
-    if (set.size > 10) {
-      const d = docs[0];
-      add('col-08', d.file, 1, `${set.size} ${hue} shades`, 'Shade counts stay bounded (greys 8-10, each accent family 5-10); this family exceeds 10.');
-    }
-  }
-
-  // typ-18: uppercase-tracking instances beyond ceil(sectionCount/3).
-  if (sectionCount > 0 && capsTrackCount > Math.ceil(sectionCount / 3) && capsTrackAnchor) {
-    add('typ-18', capsTrackAnchor.file, capsTrackAnchor.line, `${capsTrackCount} caps-tracked labels vs ${sectionCount} sections`, 'Ration eyebrow/micro-label uppercase-tracking against section count (<= ceil(sectionCount/3)).');
-  }
-
-  if (iconLibs.size > 1) {
-    const d = docs[0];
-    add('cod-06', d.file, 1, `icon families: ${[...iconLibs].join(', ')}`, 'One icon family per app; consolidate onto a single family (lucide).');
-  }
-}
-
-// Run spc-02 over explicit spacing values collected across files.
-export function checkSpacingScale(add, docs) {
-  const spacings = new Map();
-  for (const d of docs) {
-    d.lines.forEach((line, i) => {
-      for (const m of line.matchAll(/(?:[pm][trblxy]?|gap(?:-[xy])?|space-[xy]|inset)-\[(\d*\.?\d+)(px|rem)\]/g)) {
-        const px = toPx(m[1], m[2]);
-        if (px != null && !spacings.has(px)) spacings.set(px, { file: d.file, line: i + 1 });
-      }
-    });
-  }
-  const vals = [...spacings.keys()].sort((a, b) => a - b);
-  if (vals.length >= 3) {
-    for (let i = 1; i < vals.length; i++) {
-      if (vals[i] / vals[i - 1] < 1.25) {
-        const anc = spacings.get(vals[i]);
-        add('spc-02', anc.file, anc.line, `${vals[i - 1]}px and ${vals[i]}px`, 'Adjacent spacing values stay >= 25% apart; these declared steps are too close.');
-      }
-    }
-  }
-}
-
-// CSS generic families, the ui-* keywords, and the conventional OS fallback faces that need no
-// package to render — the only stack entries cod-16 accepts without a registering import/@font-face.
-// Exported so the fail-closed cod-16 gate at derive-personality --emit (stack vs package.json
-// binding) reads the same vocabulary as this source shell.
-export const SYSTEM_FONT_KEYWORDS = new Set([
-  'sans-serif', 'serif', 'monospace', 'cursive', 'fantasy', 'math', 'emoji', 'fangsong',
-  'system-ui', 'ui-sans-serif', 'ui-serif', 'ui-monospace', 'ui-rounded',
-  '-apple-system', 'blinkmacsystemfont', 'segoe ui', 'roboto', 'helvetica', 'helvetica neue', 'arial',
-  'sfmono-regular', 'sf mono', 'menlo', 'consolas', 'courier new', 'liberation mono', 'monaco',
-  'georgia', 'times new roman', 'inherit', 'initial', 'unset',
-]);
-
-// Slugify a family name the way a fontsource package specifier spells it ("Inter Variable" -> inter).
-export function familySlug(name) {
-  return name.toLowerCase().replace(/\s+variable$/, '').trim().replace(/[^a-z0-9]+/g, '-');
-}
-
-// cod-16 (source shell): every named family in an emitted font stack binds to a registered family or
-// a system generic. Registration is an @font-face declaring the family or an @import whose package
-// specifier carries the family's slug (@fontsource/<slug>). The check arms only when the passed file
-// set carries at least one registration — the no-fonts-css-at-all case belongs to the fail-closed
-// package.json binding at derive-personality --emit, which owns this rule's gate.
-export function checkFontBinding(add, docs) {
-  const cssDocs = docs.filter((d) => d.ext === 'css');
-  const importSpecs = [];
-  const registered = new Set();
-  for (const d of cssDocs) {
-    for (const m of d.text.matchAll(/@import\s+(?:url\(\s*)?["']([^"']+)["']/g)) importSpecs.push(m[1].toLowerCase());
-    for (const m of d.text.matchAll(/@font-face\s*\{[^}]*font-family\s*:\s*["']?([^;"'}]+)/g)) registered.add(m[1].trim().toLowerCase());
-  }
-  if (!importSpecs.length && !registered.size) return;
-  const isBound = (name) => {
-    const n = name.toLowerCase();
-    if (SYSTEM_FONT_KEYWORDS.has(n) || registered.has(n)) return true;
-    const slug = familySlug(name);
-    return slug !== '' && importSpecs.some((spec) => spec.includes(`/${slug}`) || spec === slug);
-  };
-  for (const d of cssDocs) {
-    d.lines.forEach((line, i) => {
-      for (const m of line.matchAll(/(?:--font-[\w-]+|font-family)\s*:\s*([^;}]+)/g)) {
-        for (const fam of m[1].split(',')) {
-          const name = fam.replace(/["']/g, '').trim();
-          if (!name || /^var\(/.test(name)) continue;
-          if (!isBound(name)) add('cod-16', d.file, i + 1, name, `Font family "${name}" binds to nothing installed: add its registering @fontsource import (or @font-face) to the emitted CSS, or fall back to a system generic.`);
-        }
-      }
-    });
-  }
-}
-
-// Bucket a 6-digit hex into a coarse hue family name for shade counting.
-function hexHueBucket(hex) {
-  const h = expandHex(hex);
-  const r = parseInt(h.slice(0, 2), 16), g = parseInt(h.slice(2, 4), 16), b = parseInt(h.slice(4, 6), 16);
-  const max = Math.max(r, g, b), min = Math.min(r, g, b);
-  if (max - min < 24) return 'grey';
-  let hue;
-  const d = max - min;
-  if (max === r) hue = ((g - b) / d) % 6;
-  else if (max === g) hue = (b - r) / d + 2;
-  else hue = (r - g) / d + 4;
-  hue = (hue * 60 + 360) % 360;
-  if (hue < 20 || hue >= 340) return 'red';
-  if (hue < 45) return 'orange';
-  if (hue < 70) return 'yellow';
-  if (hue < 165) return 'green';
-  if (hue < 200) return 'teal';
-  if (hue < 255) return 'blue';
-  if (hue < 290) return 'violet';
-  return 'pink';
-}
-
-// ---------------------------------------------------------------------------
-// cod-02 — lever-manifest drift check (D10), vocabulary from the design-tokens artifact
-// ---------------------------------------------------------------------------
-
-// Resolve a manifest argument (a design.tokens.json path or a directory holding one) to the tokens file, or null.
-function resolveTokensFile(path) {
-  if (!path || !existsSync(path)) return null;
-  let st;
-  try { st = statSync(path); } catch { return null; }
-  if (st.isDirectory()) {
-    const candidate = join(path, 'design.tokens.json');
-    return existsSync(candidate) ? candidate : null;
-  }
-  return path;
-}
-
-// Follow {path.to.token} alias strings within the artifact to the target token (hop-bounded against cycles).
-function resolveAlias(root, token) {
-  let cur = token;
-  for (let hops = 0; hops < 8 && cur && typeof cur.$value === 'string' && /^\{[^}]+\}$/.test(cur.$value.trim()); hops++) {
-    let node = root;
-    for (const seg of cur.$value.trim().slice(1, -1).split('.')) node = node && typeof node === 'object' ? node[seg] : undefined;
-    if (!node || typeof node !== 'object') return cur;
-    cur = node;
-  }
-  return cur;
-}
-
-// Pull a token's preserved source string from $extensions["com.nurix.design"].css, or null.
-function preservedCss(token) {
-  const css = token && token.$extensions && token.$extensions['com.nurix.design'] && token.$extensions['com.nurix.design'].css;
-  return typeof css === 'string' ? css : null;
-}
-
-// Load the drift-check vocabulary from a design-tokens artifact (a design.tokens.json path, or its directory):
-// scales come from the payload's lever-manifest; colors, font stacks, and icon stroke are read from the tokens
-// themselves (data/design-tokens/SCHEMA.md — token-valued allowlists are never restated in the manifest).
-// Each color enters in both spellings — the preserved .css string and the typed value's hex — so either passes
-// drift. Returns null when no parseable artifact is found; never runs the coverage gate.
-export function loadManifestVocab(manifestPath) {
-  const file = resolveTokensFile(manifestPath);
-  if (!file) return null;
-  let root;
-  try { root = JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
-  if (!root || typeof root !== 'object') return null;
-  const payload = (root.$extensions && root.$extensions['com.nurix.design']) || {};
-  const manifest = payload['lever-manifest'] || {};
-
-  const numSet = (arr) => (Array.isArray(arr) ? new Set(arr.map(Number).filter((n) => !Number.isNaN(n))) : null);
-  const spacing = numSet(manifest['spacing-scale']);
-  const radius = numSet(manifest['radius-scale']);
-  const durations = numSet(manifest.motion && manifest.motion.durations);
-
-  const colors = new Set();
-  for (const token of Object.values(root.color || {})) {
-    if (!token || typeof token !== 'object') continue;
-    const resolved = resolveAlias(root, token);
-    const css = preservedCss(token) || preservedCss(resolved);
-    if (css) colors.add(normColor(css));
-    const value = resolved && resolved.$value;
-    if (value && typeof value === 'object' && typeof value.hex === 'string') colors.add(normColor(value.hex));
-  }
-
-  const fonts = new Set();
-  // Add every family name in a fontFamily token's own stack (alias-valued tokens contribute nothing new).
-  const addStack = (token) => {
-    if (!token || !Array.isArray(token.$value)) return;
-    for (const fam of token.$value) if (typeof fam === 'string' && fam.trim()) fonts.add(fam.trim().toLowerCase());
-  };
-  const primitive = root.primitive || {};
-  addStack(primitive['font-sans']);
-  addStack(primitive['font-mono']);
-  for (const token of Object.values((root.typography && root.typography.family) || {})) addStack(token);
-
-  const strokeToken = primitive['icon-stroke'] ? resolveAlias(root, primitive['icon-stroke']) : null;
-  const iconStroke = strokeToken && typeof strokeToken.$value === 'number' ? strokeToken.$value : null;
-
-  // The v2 elevation/wash vocabularies: every color literal inside a shadow composite's or a wash
-  // gradient's preserved .css enters the color allowlist — both as the drift extractor will match it
-  // in emitted CSS (the raw RE_COLOR_LITERAL slice) and as the layer's own typed hex — so consuming
-  // the artifact's designed shadows/washes never reads as drift.
-  const addExpressiveGroup = (group) => {
-    for (const token of Object.values(group || {})) {
-      if (!token || typeof token !== 'object') continue;
-      const css = preservedCss(token);
-      if (css) {
-        for (const m of css.matchAll(RE_COLOR_LITERAL)) colors.add(normColor(m[0]));
-      }
-      const layers = Array.isArray(token.$value) ? token.$value : [];
-      for (const layer of layers) {
-        const c = layer && (layer.color || null);
-        if (c && typeof c === 'object' && typeof c.hex === 'string') colors.add(normColor(c.hex));
-      }
-    }
-  };
-  addExpressiveGroup(root.elevation);
-  addExpressiveGroup(root.wash);
-
-  // Alpha-stripped base signatures of every manifest color, plus the emitter's fixed neutral
-  // hairline base rgb(15 23 42) (the 2xs/xs shadow utilities the library leans on) — consulted
-  // only for literals whose alpha slot rides var()/calc(), where exact normalization is defeated.
-  const colorBases = new Set(['rgb:15,23,42']);
-  for (const c of colors) {
-    const b = colorBaseSig(c);
-    if (b) colorBases.add(b);
-  }
-
-  return { colors, spacing, radius, durations, fonts, iconStroke, colorBases };
-}
-
-// Flag any color/spacing/radius/duration/font literal in the diff files outside the manifest vocabulary (cod-02).
-export function checkDrift(add, docs, vocab) {
-  for (const d of docs) {
-    if (d.ext === 'css' && vocab.colors.size) {
-      // token-definition files legitimately hold the manifest's own literals; only flag component-side drift
-    }
-    d.lines.forEach((line, i) => {
-      const isJsx = d.ext === 'tsx' || d.ext === 'ts' || d.ext === 'html';
-      // colors
-      if (vocab.colors.size) {
-        for (const m of line.matchAll(RE_COLOR_LITERAL)) {
-          if (vocab.colors.has(normColor(m[0]))) continue;
-          // A var()/calc() alpha slot truncates the regex match mid-function and defeats exact
-          // normalization; such intensity-riding literals match on their base channels instead.
-          if (/(?:var|calc)\(/.test(m[0]) && vocab.colorBases && vocab.colorBases.has(colorBaseSig(m[0]))) continue;
-          add('cod-02', d.file, i + 1, m[0], "Value drifts from the lever manifest; use a color already in the artifact's color tokens, not a fresh literal.");
-        }
-      }
-      // spacing (explicit only)
-      if (vocab.spacing && vocab.spacing.size) {
-        for (const m of line.matchAll(/(?:[pm][trblxy]?|gap(?:-[xy])?|space-[xy]|inset)-\[(\d*\.?\d+)(px|rem)\]/g)) {
-          const px = toPx(m[1], m[2]);
-          if (px != null && !vocab.spacing.has(px)) add('cod-02', d.file, i + 1, m[0], `Spacing ${px}px is off the manifest spacing-scale; snap to a listed step.`);
-        }
-      }
-      // radius (explicit only)
-      if (vocab.radius && vocab.radius.size) {
-        for (const m of line.matchAll(/rounded-\[(\d*\.?\d+)(px|rem)?\]|border-radius\s*:\s*(\d*\.?\d+)(px|rem)/g)) {
-          const px = m[1] ? toPx(m[1], m[2] || 'px') : toPx(m[3], m[4]);
-          if (px != null && !vocab.radius.has(px)) add('cod-02', d.file, i + 1, m[0], `Radius ${px}px is off the manifest radius-scale; use a listed radius.`);
-        }
-      }
-      // durations (explicit only)
-      if (vocab.durations && vocab.durations.size) {
-        for (const m of line.matchAll(/duration-\[(\d+)ms\]|duration-(\d{2,4})\b/g)) {
-          const ms = m[1] ? parseInt(m[1], 10) : parseInt(m[2], 10);
-          if (!vocab.durations.has(ms)) add('cod-02', d.file, i + 1, m[0], `Duration ${ms}ms is off the manifest motion.durations; use a listed duration.`);
-        }
-      }
-      // fonts (declared families)
-      if (isJsx && vocab.fonts.size) {
-        for (const m of line.matchAll(/font-\[["']?([A-Za-z][\w\s-]+)["']?\]/g)) {
-          const fam = m[1].split(',')[0].replace(/["']/g, '').trim().toLowerCase();
-          if (!vocab.fonts.has(fam)) add('cod-02', d.file, i + 1, m[0], `Font "${m[1]}" is not in the manifest fonts; use the declared sans/mono.`);
-        }
-      }
-    });
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Orchestration + output formatting
-// ---------------------------------------------------------------------------
-
-// Run the full engine (per-line, per-file, copy, cross-file, spacing, drift) over loaded docs; returns sorted findings.
-export function checkDocs(docs, { vocab = null } = {}) {
-  const sink = makeSink();
-  for (const d of docs) {
-    d.lines.forEach((line, i) => checkLine(sink.add, d.file, d.ext, i + 1, line, d.text));
-    checkFile(sink.add, d.file, d.ext, d.text, d.lines);
-    checkCopy(sink.add, d.file, cleanComments(d.lines));
-  }
-  checkCrossFile(sink.add, docs);
-  checkSpacingScale(sink.add, docs);
-  checkFontBinding(sink.add, docs);
-  if (vocab) checkDrift(sink.add, docs, vocab);
-  // Stable sort: by file, then line, then rule id.
-  sink.list.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.rule.localeCompare(b.rule));
-  return sink.list;
-}
-
-// Convenience entry: read the passed file paths (and the optional design-tokens artifact) and run the full engine.
-export function runChecks(files, { manifestPath = null, vocab = null } = {}) {
-  const loaded = vocab || (manifestPath ? loadManifestVocab(manifestPath) : null);
-  return checkDocs(loadDocs(files), { vocab: loaded });
-}
-
-// Render findings as the fix-or-classify block (the caller prints it and decides the exit code).
-export function formatFindings(findings, { color = false, label = 'machine checks' } = {}) {
-  const bold = (s) => (color ? `\x1b[1m${s}\x1b[0m` : s);
-  const red = (s) => (color ? `\x1b[31m${s}\x1b[0m` : s);
-  const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
-  const out = [];
-  out.push(bold(red(`${label}: ${findings.length} source violation${findings.length === 1 ? '' : 's'}`)));
-  out.push('');
-  for (const f of findings) {
-    out.push(`${bold(red('[' + f.rule + ']'))} ${f.file}:${f.line}`);
-    out.push(`  ${dim('offending:')} ${f.excerpt}`);
-    out.push(`  ${dim('fix:')}       ${f.fix}`);
-    out.push('');
-  }
-  out.push(bold('Fix each now, or classify why the rule does not apply and record that classification'));
-  out.push(bold('in the decay ledger (docs/memory/design-decay.md) — never ignore silently.'));
-  return out.join('\n');
-}