@iclips/ui 2.0.3 → 3.1.0

package/scripts/check-colors.mjs

@@ -0,0 +1,208 @@
+// Aponta cor crua — `bg-gray-100`, `text-purple-600`, `bg-zinc-900`, `var(--teal-500)` —
+// e sugere o token semântico da paleta iClips. Não altera nenhum arquivo.
+//
+// Na lib roda no `npm run lint` (sem argumentos varre `src`). Num app que usa a
+// @iclips/ui, depois de subir para a 3.0.0:
+//
+//   node node_modules/@iclips/ui/scripts/check-colors.mjs src
+//
+// Exit: 0 nada encontrado · 1 encontrou cor crua · 2 algum caminho não pôde ser
+// lido (e nada foi encontrado). Uma linha com `check-colors-ignore` é pulada —
+// para documentação que precisa mostrar o que não fazer.
+//
+//   node scripts/check-colors.mjs --self-test   checa as regras e o CLI
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+
+// Paleta padrão do Tailwind v4 — nenhuma gera classe com o preset da 3.0.0.
+const FAMILIAS = "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose";
+const PREFIXOS = "bg|text|border(?:-[xytrblse])?|ring(?:-offset)?|outline|fill|stroke|from|via|to|divide|placeholder|caret|accent|decoration|shadow";
+const CLASSE = new RegExp(`(?<![\\w-])((?:[\\w\\[\\]&=.-]+:)*(${PREFIXOS})-(${FAMILIAS})-(\\d{2,3})(?:\\/\\d+)?)(?![\\w-])`, "g");
+// Custom properties que deixaram de existir na 3.0.0.
+const VAR_REMOVIDA = /var\(--((?:pink|blue|teal|orange)-\d+|purple-600|(?:red|green|cyan)-(?:50|100|200|500|700)|yellow-(?:50|100|200|700)|cta(?:-foreground)?)\)/g;
+
+const EXTENSOES = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".mdx", ".html", ".vue", ".svelte", ".css"]);
+const PULAR_DIR = new Set(["node_modules", "dist", ".git", "storybook-static", "coverage"]);
+
+const ESTADO = { red: "destructive", green: "success", emerald: "success", yellow: "warning", amber: "warning", cyan: "info", sky: "info", blue: "info" };
+const NEUTRO = new Set(["slate", "gray", "zinc", "neutral", "stone"]);
+
+export function sugerir(classe) {
+  const m = new RegExp(`^(?:.*:)?(${PREFIXOS})-(${FAMILIAS})-(\\d{2,3})`).exec(classe);
+  if (!m) return null;
+  const [, prefixo, familia, degrauTxt] = m;
+  const degrau = Number(degrauTxt);
+  const base = prefixo.replace(/-[xytrblse]$/, "");
+  if (NEUTRO.has(familia)) {
+    if (base === "bg") return degrau <= 50 ? "bg-background ou bg-muted/40" : degrau <= 200 ? "bg-muted" : degrau >= 700 ? "bg-card (superfície escura)" : "bg-muted";
+    if (base === "text") return degrau >= 700 ? "text-foreground" : degrau >= 400 ? "text-muted-foreground" : "text-muted-foreground (400 ou mais claro nunca em texto)";
+    if (base === "border" || base === "divide" || base === "outline") return degrau >= 300 ? `${base}-input` : `${base}-border`;
+    if (base === "ring") return "ring-ring";
+  }
+  if (familia === "purple") {
+    if (base === "bg") return degrau <= 100 ? "bg-secondary (seleção)" : "bg-primary";
+    if (base === "text") return degrau >= 700 ? "text-secondary-foreground" : "text-primary";
+    if (base === "ring") return "ring-ring";
+    if (base === "border" || base === "outline") return `${base}-primary`;
+  }
+  const estado = ESTADO[familia];
+  if (estado) {
+    if (base === "text") return `text-${estado}-emphasis`;
+    if (base === "bg") return degrau <= 100 ? `bg-${estado}/10` : `bg-${estado}`;
+    if (base === "border") return `border-${estado}/20`;
+    return `${base}-${estado}`;
+  }
+  return "sem equivalente — a paleta iClips não tem esta cor; use um token semântico ou var(--chart-N) em dados";
+}
+
+export function varrerTexto(texto) {
+  const achados = [];
+  texto.split(/\r?\n/).forEach((linha, i) => {
+    if (linha.includes("check-colors-ignore")) return;
+    for (const m of linha.matchAll(CLASSE)) achados.push({ linha: i + 1, classe: m[1], sugestao: sugerir(m[1]) });
+    for (const m of linha.matchAll(VAR_REMOVIDA)) achados.push({ linha: i + 1, classe: m[0], sugestao: "removida na 3.0.0 — use o token semântico" });
+  });
+  return achados;
+}
+
+function arquivos(caminho, erros) {
+  let st;
+  try {
+    st = statSync(caminho);
+  } catch {
+    erros.push(caminho);
+    return [];
+  }
+  if (st.isFile()) return [caminho];
+  const out = [];
+  for (const e of readdirSync(caminho, { withFileTypes: true })) {
+    if (e.isDirectory()) {
+      if (!PULAR_DIR.has(e.name)) out.push(...arquivos(join(caminho, e.name), erros));
+    } else if (EXTENSOES.has(extname(e.name)) && !/\.test\.[jt]sx?$/.test(e.name)) {
+      out.push(join(caminho, e.name));
+    }
+  }
+  return out;
+}
+
+export function executar(caminhos, { out = console.log, err = console.error } = {}) {
+  const erros = [];
+  let total = 0;
+  for (const alvo of caminhos.length ? caminhos : ["src"]) {
+    for (const f of arquivos(alvo, erros)) {
+      let texto;
+      try {
+        texto = readFileSync(f, "utf8");
+      } catch {
+        erros.push(f);
+        continue;
+      }
+      for (const a of varrerTexto(texto)) {
+        total++;
+        out(`${relative(process.cwd(), f).replace(/\\/g, "/")}:${a.linha}  ${a.classe}  → ${a.sugestao}`);
+      }
+    }
+  }
+  for (const e of erros) err(`check-colors: não foi possível ler ${e}`);
+  if (total) err(`check-colors: ${total} cor(es) crua(s) — a paleta iClips só aceita tokens semânticos.`);
+  return total ? 1 : erros.length ? 2 : 0;
+}
+
+async function selfTest() {
+  const assert = (await import("node:assert/strict")).default;
+  const { mkdtempSync, writeFileSync, statSync: st, rmSync } = await import("node:fs");
+  const { tmpdir } = await import("node:os");
+  const { spawnSync } = await import("node:child_process");
+  const { fileURLToPath } = await import("node:url");
+
+  // detecção: toda família × todo prefixo base, com variante e opacidade
+  // lista literal (não derivada da regex): renomear ou esquecer uma família no FAMILIAS falha aqui
+  const familias = ["slate", "gray", "zinc", "neutral", "stone", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose"];
+  assert.deepEqual(FAMILIAS.split("|"), familias, "FAMILIAS cobre exatamente a paleta padrão do Tailwind v4");
+  const prefixos = ["bg", "text", "border", ...["x", "y", "t", "r", "b", "l", "s", "e"].map((l) => `border-${l}`), "ring", "ring-offset", "outline", "fill", "stroke", "from", "via", "to", "divide", "placeholder", "caret", "accent", "decoration", "shadow"];
+  assert.equal(familias.length, 22, "22 famílias do Tailwind");
+  for (const f of familias)
+    for (const p of prefixos) {
+      const c = `${p}-${f}-500`;
+      const achados = varrerTexto(`<div className="hover:${c}/40" />`);
+      assert.equal(achados.length, 1, `detecta ${c}`);
+      assert.equal(achados[0].classe, `hover:${c}/40`, `cita a classe inteira: ${c}`);
+    }
+  for (const ok of ["bg-primary", "text-muted-foreground", "bg-black/50", "text-white", "bg-white", "border-border", "text-success-emphasis", "bg-chart-2/15", "bg-[#24292F]", "grayscale", "text-gray", "blue-500", "bg-gray-5000"])
+    assert.equal(varrerTexto(`<div className="${ok}" />`).length, 0, `não acusa ${ok}`);
+  assert.equal(varrerTexto('style={{ color: "var(--teal-500)" }}').length, 1, "var removida");
+  assert.equal(varrerTexto('style={{ color: "var(--cta)" }}').length, 1, "var --cta removida");
+  assert.equal(varrerTexto('style={{ color: "var(--gray-100)" }}').length, 0, "var mantida");
+  assert.equal(varrerTexto('<p className="bg-teal-500" /> {/* check-colors-ignore */}').length, 0, "ignore");
+
+  // sugestões: um caso por ramo de sugerir(); as linhas marcadas (guia) espelham a tabela do MIGRATION-v3.md
+  const tabela = {
+    // neutros
+    "bg-gray-50": "bg-background ou bg-muted/40", /* guia */ "bg-gray-100": "bg-muted", /* guia */ "bg-gray-200": "bg-muted",
+    "bg-gray-400": "bg-muted", "bg-zinc-900": "bg-card (superfície escura)", /* guia */ "bg-gray-700": "bg-card (superfície escura)",
+    "text-gray-800": "text-foreground", /* guia */ "text-gray-900": "text-foreground", "text-gray-500": "text-muted-foreground", /* guia */
+    "text-gray-400": "text-muted-foreground", "text-gray-300": "text-muted-foreground (400 ou mais claro nunca em texto)",
+    "border-gray-200": "border-border", /* guia */ "border-gray-100": "border-border", "border-gray-300": "border-input", /* guia */
+    "divide-gray-200": "divide-border", "outline-slate-300": "outline-input", "ring-gray-300": "ring-ring",
+    // roxo = ação
+    "bg-purple-500": "bg-primary", /* guia */ "bg-purple-600": "bg-primary", "bg-purple-50": "bg-secondary (seleção)", /* guia */ "bg-purple-100": "bg-secondary (seleção)",
+    "text-purple-600": "text-primary", /* guia */ "text-purple-500": "text-primary", "text-purple-700": "text-secondary-foreground", /* guia */
+    "border-purple-500": "border-primary", /* guia */ "ring-purple-500": "ring-ring", /* guia */ "outline-purple-400": "outline-primary",
+    // estado
+    "text-red-600": "text-destructive-emphasis", /* guia */ "text-green-600": "text-success-emphasis", "text-yellow-700": "text-warning-emphasis", "text-blue-600": "text-info-emphasis",
+    "text-amber-700": "text-warning-emphasis", "text-emerald-600": "text-success-emphasis", "text-sky-600": "text-info-emphasis", "text-cyan-600": "text-info-emphasis",
+    "bg-red-600": "bg-destructive", /* guia */ "bg-red-50": "bg-destructive/10", "bg-green-100": "bg-success/10", "bg-blue-500": "bg-info",
+    "border-red-200": "border-destructive/20", /* guia */ "fill-green-600": "fill-success", "hover:bg-gray-100": "bg-muted", "dark:bg-zinc-900": "bg-card (superfície escura)",
+  };
+  for (const [c, esperado] of Object.entries(tabela)) assert.equal(sugerir(c), esperado, c);
+  for (const semEquivalente of ["bg-teal-500", "text-orange-600", "bg-pink-500", "text-indigo-500", "bg-violet-500", "text-violet-600", "border-rose-300", "fill-lime-400", "bg-fuchsia-500"])
+    assert.match(sugerir(semEquivalente), /^sem equivalente/, `${semEquivalente} sem equivalente`);
+
+  // CLI de verdade
+  const script = fileURLToPath(import.meta.url);
+  const run = (args, cwd) => spawnSync(process.execPath, [script, ...args], { cwd, encoding: "utf8" });
+  const dir = mkdtempSync(join(tmpdir(), "check-colors-"));
+  try {
+    const limpo = join(dir, "limpo");
+    const sujo = join(dir, "sujo");
+    for (const d of [limpo, sujo]) spawnSync(process.execPath, ["-e", `require("fs").mkdirSync(${JSON.stringify(d)})`]);
+    writeFileSync(join(limpo, "a.tsx"), '<div className="bg-primary text-white" />\n');
+    const alvo = join(sujo, "b.tsx");
+    writeFileSync(alvo, 'const x = 1;\n<div className="bg-teal-500" />\n<p className="text-gray-600" />\n');
+    writeFileSync(join(sujo, "b.test.tsx"), '<div className="bg-teal-500" />\n');
+    const antes = { txt: readFileSync(alvo, "utf8"), mtime: st(alvo).mtimeMs };
+
+    let r = run([limpo], dir);
+    assert.equal(r.status, 0, "dir limpo → exit 0");
+
+    r = run([sujo], dir);
+    assert.equal(r.status, 1, "dir sujo → exit 1");
+    const linhas = r.stdout.trim().split("\n");
+    assert.equal(linhas.length, 2, "lista todas as ocorrências (e ignora *.test.*)");
+    assert.match(linhas[0], /sujo\/b\.tsx:2 {2}bg-teal-500 {2}→ sem equivalente/, "cita arquivo:linha e a classe");
+    assert.match(linhas[1], /sujo\/b\.tsx:3 {2}text-gray-600 {2}→ text-muted-foreground/, "sugere o token");
+
+    assert.equal(readFileSync(alvo, "utf8"), antes.txt, "não altera o conteúdo");
+    assert.equal(st(alvo).mtimeMs, antes.mtime, "não toca o arquivo");
+
+    r = run([join(dir, "nao-existe")], dir);
+    assert.equal(r.status, 2, "caminho ilegível sem achado → exit 2");
+    assert.match(r.stderr, /não foi possível ler/, "avisa no stderr");
+    r = run([join(dir, "nao-existe"), sujo], dir);
+    assert.equal(r.status, 1, "ilegível + achado → continua e sai 1");
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+
+  // o lint da lib encadeia o script
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  assert.match(pkg.scripts.lint, /node scripts\/check-colors\.mjs/, "npm run lint roda check-colors");
+
+  console.log("check-colors: self-test ok");
+}
+
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/").split("/").pop())) {
+  if (process.argv.includes("--self-test")) await selfTest();
+  else process.exitCode = executar(process.argv.slice(2));
+}