orbital-ds 0.5.0 → 0.6.2

package/scripts/doctor.mjs

@@ -1,224 +1,301 @@
-#!/usr/bin/env node
-/**
- * orbital-ds doctor — comprueba que el sistema se cumple.
- *
- *   1. CONTRATO: cada tema (themes/*.css) define en :root todos los tokens de
- *      contract.json y la fuente `--ds-font-sans`. En .dark solo avisa.
- *   2. REPETIDOS: ninguna variable se define dos veces en el mismo bloque.
- *   3. SOMBRAS: «sin sombra» es `0 0 #0000`, nunca `none` (una variable con
- *      `none` invalida todo el box-shadow, anillo de foco incluido).
- *   4. FUGAS: el tema base (contract.baseTheme) está aplicado siempre; todo tema
- *      con ámbito debe definir cada `--ds-*` que defina el base, o su valor se
- *      colaría al cambiar de tema.
- *   5. VALORES FIJOS: ningún componente (ui/*.tsx) escribe colores, z-index,
- *      duraciones ni sombras a mano; todo sale de tokens.
- *   6. API PÚBLICA: no desaparece ningún componente ni export respecto a
- *      components.manifest.json (huella de la última versión). Lo nuevo solo avisa.
- *
- * Uso:
- *   node scripts/doctor.mjs                 # temas y componentes del paquete
- *   node scripts/doctor.mjs --css app.css   # además, un CSS de una app (repetidos)
- *
- * Sale con código 1 si hay errores (los avisos no fallan).
- */
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const contract = JSON.parse(readFileSync(join(ROOT, 'contract.json'), 'utf8'));
-
-const errors = [];
-const warnings = [];
-const read = (p) => readFileSync(p, 'utf8');
-const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
-
-/** Cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
-function blocks(css, selectorRe) {
-  const out = [];
-  const re = new RegExp(selectorRe.source + '\\s*\\{', 'g');
-  let m;
-  while ((m = re.exec(css))) {
-    let depth = 1;
-    let i = re.lastIndex;
-    const start = i;
-    while (i < css.length && depth > 0) {
-      if (css[i] === '{') depth++;
-      else if (css[i] === '}') depth--;
-      i++;
-    }
-    out.push(css.slice(start, i - 1));
-    re.lastIndex = i;
-  }
-  return out;
-}
-
-/** Declaraciones `--x: valor;` del nivel superior de un bloque (no las anidadas). */
-function declarations(body) {
-  let depth = 0;
-  let top = '';
-  for (const ch of body) {
-    if (ch === '{') depth++;
-    else if (ch === '}') depth--;
-    else if (depth === 0) top += ch;
-  }
-  return [...top.matchAll(/(^|[;\s])(--[a-z0-9-]+)\s*:\s*([^;]*);?/gi)].map((m) => ({ name: m[2], value: m[3].trim() }));
-}
-
-/** Variables --ds-* que la estructura del paquete define (las que una app puede usar). */
-function knownDsVars() {
-  const f = existsSync(join(ROOT, 'src/styles.css')) ? join(ROOT, 'src/styles.css') : join(ROOT, 'dist/styles.css');
-  return new Set([...read(f).matchAll(/(--ds-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
-}
-
-// El grupo de marca debe ser coherente con el contrato: cada variable, o es del contrato, o es --ds-*.
-for (const t of contract.brand?.tokens ?? []) {
-  const inContract =
-    contract.root.includes(t.name) ||
-    contract.fonts.includes(t.name) ||
-    (t.name.startsWith('ds-') && knownDsVars().has(`--${t.name}`));
-  if (!inContract) errors.push(`contrato: la variable de marca --${t.name} ni es del contrato ni la define la estructura`);
-}
-
-const themeInfo = {}; // nombre → { rootVars:Set, darkVars:Set }
-
-function checkTheme(file, name) {
-  const label = `tema ${name}`;
-  const css = stripComments(read(file));
-  const roots = blocks(css, /(?:^|[\s}])\:root/);
-  const darks = blocks(css, /(?:^|[\s}])\.dark/);
-
-  const rootDecl = roots.flatMap(declarations);
-  const darkDecl = darks.flatMap(declarations);
-  const rootVars = new Set(rootDecl.map((d) => d.name));
-  const darkVars = new Set(darkDecl.map((d) => d.name));
-  themeInfo[name] = { rootVars, darkVars };
-
-  for (const t of contract.root) {
-    if (!rootVars.has(`--${t}`)) errors.push(`${label}: falta el token obligatorio --${t} en :root`);
-  }
-  for (const f of contract.fonts) {
-    if (!rootVars.has(`--${f}`)) errors.push(`${label}: falta la fuente --${f} en :root`);
-  }
-  if (darks.length) {
-    for (const t of contract.dark.avisar_si_falta) {
-      if (!darkVars.has(`--${t}`)) warnings.push(`${label}: .dark no redefine --${t} (hereda el valor claro)`);
-    }
-  } else {
-    warnings.push(`${label}: no define piel .dark`);
-  }
-
-  // Repetidos (solo declaraciones del nivel superior de cada bloque)
-  for (const [kind, list] of [[':root', roots], ['.dark', darks]]) {
-    list.forEach((body, idx) => {
-      const seen = new Map();
-      for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
-      for (const [v, n] of seen) {
-        if (n > 1) errors.push(`${label}: ${v} definido ${n} veces en el mismo bloque ${kind} (#${idx + 1})`);
-      }
-    });
-  }
-
-  // Sombras: `none` invalida el box-shadow
-  for (const d of [...rootDecl, ...darkDecl]) {
-    if (/^--ds-(?:shadow|sidebar-shadow)/.test(d.name) && /^none$/i.test(d.value)) {
-      errors.push(`${label}: ${d.name}: none — usa «0 0 #0000» (none invalida todo el box-shadow)`);
-    }
-  }
-}
-
-// 1+2+3) temas
-const themesDir = join(ROOT, existsSync(join(ROOT, 'src/themes')) ? 'src/themes' : 'dist/themes');
-const themeFiles = readdirSync(themesDir).filter(
-  (n) => n.endsWith('.css') && !n.endsWith('.fonts.css') && !n.endsWith('.scoped.css'),
-);
-for (const f of themeFiles) checkTheme(join(themesDir, f), f.replace(/\.css$/, ''));
-
-// 4) fugas desde el tema base
-const base = contract.baseTheme;
-if (base && themeInfo[base]) {
-  const baseDs = [...themeInfo[base].rootVars].filter((v) => v.startsWith('--ds-'));
-  for (const [name, info] of Object.entries(themeInfo)) {
-    if (name === base) continue;
-    for (const v of baseDs) {
-      if (!info.rootVars.has(v)) {
-        errors.push(`tema ${name}: no define ${v}, que sí define el tema base «${base}» — su valor se colaría al cambiar de tema`);
-      }
-    }
-  }
-}
-
-// CSS de una app (opcional)
-const cssArgIdx = process.argv.indexOf('--css');
-if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
-  const css = stripComments(read(resolve(process.argv[cssArgIdx + 1])));
-  blocks(css, /(?:^|[\s}])\:root/).forEach((body, idx) => {
-    const seen = new Map();
-    for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
-    for (const [v, n] of seen) if (n > 1) errors.push(`app css: ${v} definido ${n} veces en :root (#${idx + 1})`);
-    // Una variable --ds-* que el paquete ya no tiene: la marca la ignoraría en silencio.
-    const known = knownDsVars();
-    for (const d of declarations(body)) {
-      if (d.name.startsWith('--ds-') && !known.has(d.name)) {
-        errors.push(`app css: ${d.name} no existe en orbital-ds (¿renombrada o retirada? mira docs/CONTRACT.md)`);
-      }
-    }
-  });
-}
-
-// 5) valores fijos en componentes
-const NO_HARDCODE = [
-  { re: /#[0-9a-fA-F]{3,8}\b/g, why: 'color hexadecimal', skip: ['chart.tsx'] },
-  { re: /\b(?:rgb|rgba|hsl|hsla|oklch)\((?!from_)/g, why: 'color literal' },
-  { re: /(?<![\w-])z-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'z-index numérico (usa --ds-z-*)' },
-  { re: /(?<![\w-])duration-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'duración fija (usa --ds-motion-*)' },
-  { re: /(?<![\w-])(?:bg|text|border)-(?:black|white)(?:\/\d+)?(?![\w-])/g, why: 'color fijo (usa un token de color)' },
-  { re: /(?<![\w-])shadow-(?:xs|sm|md|lg|xl|2xl)(?![\w-])/g, why: 'sombra de la escala Tailwind (usa shadow-card/control/raised/overlay/popover)' },
-  { re: /(?<![\w-])text-\[\d+px\]/g, why: 'tamaño de texto arbitrario (usa la escala estándar)' },
-  { re: /(?<![\w-])rounded-(?:3xl|4xl)(?![\w-])/g, why: 'radio fuera de la rampa (usa rounded-control/overlay o la rampa sm…2xl)' },
-  { re: /(?<![\w-])(?:bg|text|border|ring|fill|stroke)-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\d{2,3}(?![\w-])/g, why: 'color de la paleta Tailwind (usa tokens del tema)' },
-];
-
-const uiDir = join(ROOT, 'src/ui');
-if (existsSync(uiDir)) {
-  for (const f of readdirSync(uiDir).filter((n) => n.endsWith('.tsx'))) {
-    const lines = read(join(uiDir, f)).split(/\r?\n/);
-    lines.forEach((line, i) => {
-      const code = line.replace(/\/\/.*$/, '');
-      for (const rule of NO_HARDCODE) {
-        if (rule.skip?.includes(f)) continue;
-        const hits = code.match(rule.re);
-        if (hits) errors.push(`ui/${f}:${i + 1}: ${rule.why} → ${[...new Set(hits)].join(', ')}`);
-      }
-    });
-  }
-}
-
-// 6) API pública frente a la huella commiteada
-const manifestPath = join(ROOT, 'components.manifest.json');
-if (existsSync(manifestPath) && existsSync(uiDir)) {
-  const { buildManifest } = await import('./manifest.mjs');
-  const before = JSON.parse(read(manifestPath)).components;
-  const now = buildManifest().components;
-  for (const [name, comp] of Object.entries(before)) {
-    if (!now[name]) {
-      errors.push(`API pública: desaparece el componente «${name}» (¿versión mayor? regenera con pnpm manifest)`);
-      continue;
-    }
-    for (const e of comp.exports) {
-      if (!now[name].exports.includes(e)) {
-        errors.push(`API pública: «${name}» ya no exporta ${e} (¿versión mayor? regenera con pnpm manifest)`);
-      }
-    }
-  }
-  const added = Object.keys(now).filter((n) => !before[n]);
-  if (added.length) warnings.push(`API pública: componentes nuevos sin registrar en el manifiesto (${added.join(', ')}); ejecuta pnpm manifest`);
-}
-
-for (const w of warnings) console.log(`AVISO  ${w}`);
-for (const e of errors) console.log(`ERROR  ${e}`);
-if (errors.length) {
-  console.log(`\ndoctor: ${errors.length} error(es), ${warnings.length} aviso(s)`);
-  process.exit(1);
-}
-console.log(`doctor: contrato, repetidos, sombras, fugas, valores fijos y API pública correctos (${warnings.length} aviso(s)).`);
+#!/usr/bin/env node
+/**
+ * orbital-ds doctor — comprueba que el sistema se cumple.
+ *
+ *   1. CONTRATO: cada tema (themes/*.css) define en :root todos los tokens de
+ *      contract.json y la fuente `--ds-font-sans`. En .dark solo avisa.
+ *   2. REPETIDOS: ninguna variable se define dos veces en el mismo bloque.
+ *   3. SOMBRAS: «sin sombra» es `0 0 #0000`, nunca `none` (una variable con
+ *      `none` invalida todo el box-shadow, anillo de foco incluido).
+ *   4. FUGAS: el tema base (contract.baseTheme) está aplicado siempre; todo tema
+ *      con ámbito debe definir cada `--ds-*` que defina el base, o su valor se
+ *      colaría al cambiar de tema.
+ *   5. VALORES FIJOS: ningún componente (ui/*.tsx) escribe colores, z-index,
+ *      duraciones ni sombras a mano; todo sale de tokens.
+ *   6. API PÚBLICA: no desaparece ningún componente ni export respecto a
+ *      components.manifest.json (huella de la última versión). Lo nuevo solo avisa.
+ *
+ * Uso:
+ *   node scripts/doctor.mjs                 # temas y componentes del paquete
+ *   node scripts/doctor.mjs --css app.css   # además, un CSS de una app (repetidos)
+ *
+ * Sale con código 1 si hay errores (los avisos no fallan).
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contract = JSON.parse(readFileSync(join(ROOT, 'contract.json'), 'utf8'));
+
+const errors = [];
+const warnings = [];
+const read = (p) => readFileSync(p, 'utf8');
+const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+/** Cuerpo de cada bloque `selector { ... }` (respeta llaves anidadas). */
+function blocks(css, selectorRe) {
+  const out = [];
+  const re = new RegExp(selectorRe.source + '\\s*\\{', 'g');
+  let m;
+  while ((m = re.exec(css))) {
+    let depth = 1;
+    let i = re.lastIndex;
+    const start = i;
+    while (i < css.length && depth > 0) {
+      if (css[i] === '{') depth++;
+      else if (css[i] === '}') depth--;
+      i++;
+    }
+    out.push(css.slice(start, i - 1));
+    re.lastIndex = i;
+  }
+  return out;
+}
+
+/** Declaraciones `--x: valor;` del nivel superior de un bloque (no las anidadas). */
+function declarations(body) {
+  let depth = 0;
+  let top = '';
+  for (const ch of body) {
+    if (ch === '{') depth++;
+    else if (ch === '}') depth--;
+    else if (depth === 0) top += ch;
+  }
+  return [...top.matchAll(/(^|[;\s])(--[a-z0-9-]+)\s*:\s*([^;]*);?/gi)].map((m) => ({ name: m[2], value: m[3].trim() }));
+}
+
+/** Variables --ds-* que la estructura del paquete define (las que una app puede usar). */
+function knownDsVars() {
+  const f = existsSync(join(ROOT, 'src/styles.css')) ? join(ROOT, 'src/styles.css') : join(ROOT, 'dist/styles.css');
+  return new Set([...read(f).matchAll(/(--ds-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
+}
+
+// El grupo de marca debe ser coherente con el contrato: cada variable, o es del contrato, o es --ds-*.
+for (const t of contract.brand?.tokens ?? []) {
+  const inContract =
+    contract.root.includes(t.name) ||
+    contract.fonts.includes(t.name) ||
+    (t.name.startsWith('ds-') && knownDsVars().has(`--${t.name}`));
+  if (!inContract) errors.push(`contrato: la variable de marca --${t.name} ni es del contrato ni la define la estructura`);
+}
+
+const themeInfo = {}; // nombre → { rootVars:Set, darkVars:Set }
+
+function checkTheme(file, name) {
+  const label = `tema ${name}`;
+  const css = stripComments(read(file));
+  const roots = blocks(css, /(?:^|[\s}])\:root/);
+  const darks = blocks(css, /(?:^|[\s}])\.dark/);
+
+  const rootDecl = roots.flatMap(declarations);
+  const darkDecl = darks.flatMap(declarations);
+  const rootVars = new Set(rootDecl.map((d) => d.name));
+  const darkVars = new Set(darkDecl.map((d) => d.name));
+  themeInfo[name] = { rootVars, darkVars };
+
+  for (const t of contract.root) {
+    if (!rootVars.has(`--${t}`)) errors.push(`${label}: falta el token obligatorio --${t} en :root`);
+  }
+  for (const f of contract.fonts) {
+    if (!rootVars.has(`--${f}`)) errors.push(`${label}: falta la fuente --${f} en :root`);
+  }
+  if (darks.length) {
+    for (const t of contract.dark.avisar_si_falta) {
+      if (!darkVars.has(`--${t}`)) warnings.push(`${label}: .dark no redefine --${t} (hereda el valor claro)`);
+    }
+  } else {
+    warnings.push(`${label}: no define piel .dark`);
+  }
+
+  // Repetidos (solo declaraciones del nivel superior de cada bloque)
+  for (const [kind, list] of [[':root', roots], ['.dark', darks]]) {
+    list.forEach((body, idx) => {
+      const seen = new Map();
+      for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
+      for (const [v, n] of seen) {
+        if (n > 1) errors.push(`${label}: ${v} definido ${n} veces en el mismo bloque ${kind} (#${idx + 1})`);
+      }
+    });
+  }
+
+  // Sombras: `none` invalida el box-shadow
+  for (const d of [...rootDecl, ...darkDecl]) {
+    if (/^--ds-(?:shadow|sidebar-shadow)/.test(d.name) && /^none$/i.test(d.value)) {
+      errors.push(`${label}: ${d.name}: none — usa «0 0 #0000» (none invalida todo el box-shadow)`);
+    }
+  }
+}
+
+// 1+2+3) temas
+const themesDir = join(ROOT, existsSync(join(ROOT, 'src/themes')) ? 'src/themes' : 'dist/themes');
+const themeFiles = readdirSync(themesDir).filter(
+  (n) => n.endsWith('.css') && !n.endsWith('.fonts.css') && !n.endsWith('.scoped.css'),
+);
+for (const f of themeFiles) checkTheme(join(themesDir, f), f.replace(/\.css$/, ''));
+
+// 1b) documentación de cada tema: guía de diseño (.guide.md) + ficha legible por máquina (.meta.json)
+const META_CLAVES = ['name', 'label', 'essence', 'signature', 'fonts', 'palette', 'references', 'status', 'guide'];
+for (const f of themeFiles) {
+  const t = f.replace(/\.css$/, '');
+  if (!existsSync(join(themesDir, `${t}.guide.md`))) errors.push(`tema ${t}: falta ${t}.guide.md (guía de diseño)`);
+  const metaPath = join(themesDir, `${t}.meta.json`);
+  if (!existsSync(metaPath)) { errors.push(`tema ${t}: falta ${t}.meta.json (ficha del tema)`); continue; }
+  let meta;
+  try { meta = JSON.parse(read(metaPath)); } catch { errors.push(`tema ${t}: ${t}.meta.json no es JSON válido`); continue; }
+  for (const k of META_CLAVES) if (!(k in meta)) errors.push(`tema ${t}: ${t}.meta.json no define «${k}»`);
+  if (meta.name !== t) errors.push(`tema ${t}: ${t}.meta.json tiene name «${meta.name}»`);
+}
+
+// 1c) CONTRASTE de los textos de estado: info, danger, warning, success y neutral
+// sobre su fondo suave (compuesto sobre el lienzo), mínimo WCAG AA 4.5:1, en claro y oscuro.
+// No incluye `link` ni `primary-foreground`: dependen de colores de marca fijados por la
+// identidad (p. ej. el azul de Twitter), y se documentan como limitación en la guía del tema.
+{
+  const parseColor = (raw) => {
+    const v = raw.replace(/\s+/g, ' ').trim();
+    let m = v.match(/^#([0-9a-f]{3,8})$/i);
+    if (m) {
+      let h = m[1];
+      if (h.length === 3) h = [...h].map((c) => c + c).join('');
+      return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16), a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1 };
+    }
+    m = v.match(/^rgba?\(([^)]+)\)$/i);
+    if (m) { const p = m[1].split(/[ ,/]+/).filter(Boolean).map(Number); return { r: p[0], g: p[1], b: p[2], a: p[3] ?? 1 }; }
+    m = v.match(/^oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+%?))?\s*\)$/i);
+    if (m) {
+      const L = m[1].endsWith('%') ? parseFloat(m[1]) / 100 : +m[1];
+      const C = +m[2], H = (+m[3] * Math.PI) / 180;
+      const a = C * Math.cos(H), b = C * Math.sin(H);
+      const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+      const mm = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+      const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+      const lin = [4.0767416621 * l - 3.3077115913 * mm + 0.2309699292 * s, -1.2684380046 * l + 2.6097574011 * mm - 0.3413193965 * s, -0.0041960863 * l - 0.7034186147 * mm + 1.707614701 * s];
+      const g = (x) => Math.round(255 * Math.min(1, Math.max(0, x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055)));
+      const al = m[4] ? (m[4].endsWith('%') ? parseFloat(m[4]) / 100 : +m[4]) : 1;
+      return { r: g(lin[0]), g: g(lin[1]), b: g(lin[2]), a: al };
+    }
+    return null;
+  };
+  const lum = ({ r, g, b }) => {
+    const f = (c) => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; };
+    return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+  };
+  const over = (fg, bg) => ({ r: fg.r * fg.a + bg.r * (1 - fg.a), g: fg.g * fg.a + bg.g * (1 - fg.a), b: fg.b * fg.a + bg.b * (1 - fg.a), a: 1 });
+  const ratio = (x, y) => { const [p, q] = [lum(x), lum(y)].sort((u, w) => w - u); return (p + 0.05) / (q + 0.05); };
+  const varsDe = (css, selector) => {
+    const m = new RegExp(`(^|\\n)${selector}\\s*\\{`).exec(css);
+    if (!m) return {};
+    let i = m.index + m[0].length, d = 1, j = i;
+    while (d && j < css.length) { if (css[j] === '{') d++; else if (css[j] === '}') d--; j++; }
+    const out = {};
+    for (const mm of css.slice(i, j - 1).matchAll(/--([\w-]+):\s*([^;]+);/g)) out[mm[1]] = mm[2];
+    return out;
+  };
+  for (const f of themeFiles) {
+    const tema = f.replace(/\.css$/, '');
+    const css = stripComments(read(join(themesDir, f)));
+    const claro = varsDe(css, ':root');
+    for (const [piel, vars] of [['claro', claro], ['oscuro', { ...claro, ...varsDe(css, '\\.dark') }]]) {
+      const lienzo = parseColor(vars.background ?? '#fff');
+      if (!lienzo) continue;
+      for (const estado of ['info', 'danger', 'warning', 'success', 'neutral']) {
+        const fg = vars[estado] && parseColor(vars[estado]);
+        const suave = vars[`${estado}-soft`] && parseColor(vars[`${estado}-soft`]);
+        if (!fg || !suave) continue;
+        const fondo = over(suave, over(lienzo, { r: 255, g: 255, b: 255, a: 1 }));
+        const r = ratio(over(fg, fondo), fondo);
+        if (r < 4.5) errors.push(`tema ${tema} (${piel}): ${estado} sobre ${estado}-soft = ${r.toFixed(2)}:1 (mínimo 4.5:1)`);
+      }
+    }
+  }
+}
+
+// 4) fugas desde el tema base
+const base = contract.baseTheme;
+if (base && themeInfo[base]) {
+  const baseDs = [...themeInfo[base].rootVars].filter((v) => v.startsWith('--ds-'));
+  for (const [name, info] of Object.entries(themeInfo)) {
+    if (name === base) continue;
+    for (const v of baseDs) {
+      if (!info.rootVars.has(v)) {
+        errors.push(`tema ${name}: no define ${v}, que sí define el tema base «${base}» — su valor se colaría al cambiar de tema`);
+      }
+    }
+  }
+}
+
+// CSS de una app (opcional)
+const cssArgIdx = process.argv.indexOf('--css');
+if (cssArgIdx > -1 && process.argv[cssArgIdx + 1]) {
+  const css = stripComments(read(resolve(process.argv[cssArgIdx + 1])));
+  blocks(css, /(?:^|[\s}])\:root/).forEach((body, idx) => {
+    const seen = new Map();
+    for (const d of declarations(body)) seen.set(d.name, (seen.get(d.name) ?? 0) + 1);
+    for (const [v, n] of seen) if (n > 1) errors.push(`app css: ${v} definido ${n} veces en :root (#${idx + 1})`);
+    // Una variable --ds-* que el paquete ya no tiene: la marca la ignoraría en silencio.
+    const known = knownDsVars();
+    for (const d of declarations(body)) {
+      if (d.name.startsWith('--ds-') && !known.has(d.name)) {
+        errors.push(`app css: ${d.name} no existe en orbital-ds (¿renombrada o retirada? mira docs/CONTRACT.md)`);
+      }
+    }
+  });
+}
+
+// 5) valores fijos en componentes
+const NO_HARDCODE = [
+  { re: /#[0-9a-fA-F]{3,8}\b/g, why: 'color hexadecimal', skip: ['chart.tsx'] },
+  { re: /\b(?:rgb|rgba|hsl|hsla|oklch)\((?!from_)/g, why: 'color literal' },
+  { re: /(?<![\w-])z-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'z-index numérico (usa --ds-z-*)' },
+  { re: /(?<![\w-])duration-(?!0(?![\w-]))\d+(?![\w-])/g, why: 'duración fija (usa --ds-motion-*)' },
+  { re: /(?<![\w-])(?:bg|text|border)-(?:black|white)(?:\/\d+)?(?![\w-])/g, why: 'color fijo (usa un token de color)' },
+  { re: /(?<![\w-])shadow-(?:xs|sm|md|lg|xl|2xl)(?![\w-])/g, why: 'sombra de la escala Tailwind (usa shadow-card/control/raised/overlay/popover)' },
+  { re: /(?<![\w-])text-\[\d+px\]/g, why: 'tamaño de texto arbitrario (usa la escala estándar)' },
+  { re: /(?<![\w-])rounded-(?:3xl|4xl)(?![\w-])/g, why: 'radio fuera de la rampa (usa rounded-control/overlay o la rampa sm…2xl)' },
+  { re: /(?<![\w-])(?:bg|text|border|ring|fill|stroke)-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\d{2,3}(?![\w-])/g, why: 'color de la paleta Tailwind (usa tokens del tema)' },
+];
+
+const uiDir = join(ROOT, 'src/ui');
+if (existsSync(uiDir)) {
+  for (const f of readdirSync(uiDir).filter((n) => n.endsWith('.tsx'))) {
+    const lines = read(join(uiDir, f)).split(/\r?\n/);
+    lines.forEach((line, i) => {
+      const code = line.replace(/\/\/.*$/, '');
+      for (const rule of NO_HARDCODE) {
+        if (rule.skip?.includes(f)) continue;
+        const hits = code.match(rule.re);
+        if (hits) errors.push(`ui/${f}:${i + 1}: ${rule.why} → ${[...new Set(hits)].join(', ')}`);
+      }
+    });
+  }
+}
+
+// 6) API pública frente a la huella commiteada
+const manifestPath = join(ROOT, 'components.manifest.json');
+if (existsSync(manifestPath) && existsSync(uiDir)) {
+  const { buildManifest } = await import('./manifest.mjs');
+  const before = JSON.parse(read(manifestPath)).components;
+  const now = buildManifest().components;
+  for (const [name, comp] of Object.entries(before)) {
+    if (!now[name]) {
+      errors.push(`API pública: desaparece el componente «${name}» (¿versión mayor? regenera con pnpm manifest)`);
+      continue;
+    }
+    for (const e of comp.exports) {
+      if (!now[name].exports.includes(e)) {
+        errors.push(`API pública: «${name}» ya no exporta ${e} (¿versión mayor? regenera con pnpm manifest)`);
+      }
+    }
+  }
+  const added = Object.keys(now).filter((n) => !before[n]);
+  if (added.length) warnings.push(`API pública: componentes nuevos sin registrar en el manifiesto (${added.join(', ')}); ejecuta pnpm manifest`);
+}
+
+for (const w of warnings) console.log(`AVISO  ${w}`);
+for (const e of errors) console.log(`ERROR  ${e}`);
+if (errors.length) {
+  console.log(`\ndoctor: ${errors.length} error(es), ${warnings.length} aviso(s)`);
+  process.exit(1);
+}
+console.log(`doctor: contrato, repetidos, sombras, fugas, valores fijos y API pública correctos (${warnings.length} aviso(s)).`);