@timbal-ai/timbal-react 1.6.0 → 1.7.0

package/dist/cli/timbal-ui-lint.mjs

@@ -0,0 +1,534 @@
+#!/usr/bin/env node
+
+// src/cli/ui-lint.ts
+import { readFileSync } from "fs";
+
+// src/design/ui-vocabulary.ts
+var RESERVED_GRADIENT_TOKENS = [
+  "primary-fill-from",
+  "primary-fill-to",
+  "primary-fill-hover-from",
+  "primary-fill-hover-to",
+  "primary-fill-active-from",
+  "primary-fill-active-to",
+  "secondary-fill-hover-from",
+  "secondary-fill-hover-to",
+  "secondary-fill-active-from",
+  "secondary-fill-active-to",
+  "destructive-fill-hover-from",
+  "destructive-fill-hover-to",
+  "destructive-fill-active-from",
+  "destructive-fill-active-to",
+  "ghost-fill-hover",
+  "ghost-fill-active",
+  "elevated-from",
+  "elevated-to",
+  "modal-from",
+  "modal-to",
+  "playground-from",
+  "playground-via",
+  "playground-to"
+];
+var TAILWIND_PALETTE_COLORS = [
+  "slate",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone",
+  "red",
+  "orange",
+  "amber",
+  "yellow",
+  "lime",
+  "green",
+  "emerald",
+  "teal",
+  "cyan",
+  "sky",
+  "blue",
+  "indigo",
+  "violet",
+  "purple",
+  "fuchsia",
+  "pink",
+  "rose"
+];
+var COLOR_UTILITY_PREFIXES = [
+  "bg",
+  "text",
+  "border",
+  "ring",
+  "from",
+  "via",
+  "to",
+  "fill",
+  "stroke",
+  "decoration",
+  "outline",
+  "shadow",
+  "divide",
+  "accent",
+  "caret"
+];
+var SLOP_BUDGETS = {
+  /** Max decorative/standalone icons rendered in a single generated file. */
+  maxIconsPerView: 6,
+  /** Max consecutive list rows separated by an explicit border/divider before
+   *  it reads as a "ruled table" — prefer spacing or zebra instead. */
+  maxRowDividers: 2
+};
+
+// src/design/ui-lint.ts
+var PALETTE_GROUP = TAILWIND_PALETTE_COLORS.join("|");
+var PREFIX_GROUP = COLOR_UTILITY_PREFIXES.join("|");
+var RAW_COLOR_RE = new RegExp(
+  `(?:^|[\\s"'\`:])(?:[a-z-]+:)*(?:${PREFIX_GROUP})-(?:${PALETTE_GROUP})-\\d{2,3}(?:/\\d{1,3})?`,
+  "g"
+);
+var COLOR_LITERAL_RE = /#[0-9a-fA-F]{3,8}\b|\b(?:oklch|rgba?|hsla?)\s*\(/g;
+var COLOR_FN_WRAPPING_VAR_RE = /\b(?:hsl|hsla|rgb|rgba|oklch|oklab|lab|lch|hwb|color)\s*\(\s*var\(\s*--/i;
+var INLINE_STYLE_COLOR_RE = /style=\{\{[^}]*\b(?:color|background|backgroundColor|borderColor|fill|stroke)\b/;
+var BOLD_VALUE_RE = /text-(?:xl|2xl|3xl|4xl|5xl|6xl)[^"'`]*\bfont-(?:bold|extrabold|black|semibold)|font-(?:bold|extrabold|black|semibold)[^"'`]*text-(?:xl|2xl|3xl|4xl|5xl|6xl)/;
+var GRADIENT_RE = /\bbg-(?:gradient|linear|radial|conic)-/;
+var GRADIENT_DIRECTIONS = /* @__PURE__ */ new Set([
+  "t",
+  "tr",
+  "r",
+  "br",
+  "b",
+  "bl",
+  "l",
+  "tl"
+]);
+var ICON_IMPORT_RE = /from\s+["']lucide-react["']/;
+var RAW_CONTROL_SURFACE_RE = /\bborder-input\b/;
+var COLORED_HOVER_RE = /\bhover:(?:bg|from|to|via)-(?:primary|destructive|success|warn|danger|blue|emerald|green|amber|red|indigo|violet|purple|pink|rose|sky|cyan|teal|lime|yellow|orange|fuchsia)\b/;
+var TREND_CONTEXT_RE = /\b(?:trend|delta|TrendingUp|TrendingDown|ArrowUp|ArrowDown|ArrowUpRight|ArrowDownRight|MoveUp|MoveDown)\b|[+\-]\d+(?:\.\d+)?\s*%/;
+var TREND_COLOR_RE = /\b(?:text|bg|border)-(?:success|destructive|emerald|green|lime|teal|red|rose|orange|amber)(?:-\d{2,3})?(?:\/\d{1,3})?\b/;
+var RESERVED_GRADIENT_SET = new Set(RESERVED_GRADIENT_TOKENS);
+function stripVariants(util) {
+  return util.replace(/^(?:[a-z-]+:)*/, "");
+}
+function describeArg(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "an array";
+  const t = typeof value;
+  if (t === "object") {
+    const keys = Object.keys(value).slice(0, 4);
+    return keys.length ? `an object with keys { ${keys.join(", ")} }` : "an object";
+  }
+  return `a ${t}`;
+}
+function isCommentOrImport(line) {
+  const t = line.trim();
+  return t.startsWith("//") || t.startsWith("*") || t.startsWith("/*") || t.startsWith("import ") || t.startsWith("export ");
+}
+function lintGeneratedUi(source, options = {}) {
+  if (typeof source !== "string") {
+    throw new TypeError(
+      `lintGeneratedUi(source, options?) expects the generated code as a string, but received ${describeArg(source)}. Pass the raw .tsx source \u2014 lintGeneratedUi(code) \u2014 not an object like { filename, source } and not a previous LintResult.`
+    );
+  }
+  const maxIcons = options.maxIconsPerView ?? SLOP_BUDGETS.maxIconsPerView;
+  const maxRowDividers = options.maxRowDividers ?? SLOP_BUDGETS.maxRowDividers;
+  const findings = [];
+  const lines = source.split("\n");
+  let usesLucide = false;
+  let iconUsageCount = 0;
+  let dividerRunCount = 0;
+  let pageTitle = null;
+  const pageTitleMatch = source.match(/<Page\s+[^>]*\btitle=(?:"([^"]+)"|\{["']([^"']+)["']\})/);
+  if (pageTitleMatch) {
+    pageTitle = (pageTitleMatch[1] || pageTitleMatch[2]).trim().toLowerCase();
+  }
+  const hasChat = /\b(?:TimbalChat|AppChatPanel|Thread)\b/.test(source);
+  const lucideNames = /* @__PURE__ */ new Set();
+  const openCards = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+    if (ICON_IMPORT_RE.test(line)) {
+      usesLucide = true;
+      const named = line.match(/\{([^}]*)\}/);
+      if (named) {
+        for (const raw of named[1].split(",")) {
+          const name = raw.trim().split(/\s+as\s+/)[0].trim();
+          if (name) lucideNames.add(name);
+        }
+      }
+      continue;
+    }
+    if (isCommentOrImport(line)) continue;
+    const cardMatch = line.match(/<(Card|SurfaceCard|ArtifactCard)\b/);
+    if (cardMatch) {
+      const isSelfClosing = /\/>/.test(line) && line.indexOf(cardMatch[0]) < line.indexOf("/>");
+      if (!isSelfClosing) {
+        if (openCards.length > 0) {
+          const parentCard = openCards[openCards.length - 1];
+          findings.push({
+            rule: "no-card-in-card",
+            severity: "warn",
+            line: lineNo,
+            message: `Card inside card. A <${cardMatch[1]}> is nested inside the <${parentCard.type}> opened on L${parentCard.line}. Double borders/shadows add no information \u2014 group with spacing or a <Section> instead.`,
+            snippet: line.trim().slice(0, 120)
+          });
+        }
+        openCards.push({ type: cardMatch[1], line: lineNo });
+      }
+    }
+    const closeMatch = line.match(/<\/(Card|SurfaceCard|ArtifactCard)\b/);
+    if (closeMatch && openCards.length > 0) {
+      const idx = openCards.map((c) => c.type).lastIndexOf(closeMatch[1]);
+      if (idx !== -1) {
+        openCards.splice(idx, 1);
+      }
+    }
+    if (openCards.length > 0) {
+      const tableMatch = line.match(/<(DataTable|table|Table)\b/);
+      if (tableMatch) {
+        const parentCard = openCards[openCards.length - 1];
+        findings.push({
+          rule: "no-table-in-card",
+          severity: "error",
+          line: lineNo,
+          message: `Table inside card. Never wrap a <${tableMatch[1]}> or table inside a <${parentCard.type}> (opened on L${parentCard.line}). Place the table directly on the Page or Section instead.`,
+          snippet: line.trim().slice(0, 120)
+        });
+      }
+    }
+    const rawColors = line.match(RAW_COLOR_RE);
+    if (rawColors) {
+      for (const m of rawColors) {
+        findings.push({
+          rule: "raw-color",
+          severity: "error",
+          line: lineNo,
+          message: "Hardcoded palette color. Use a semantic token (text-primary, bg-muted, border-border, text-muted-foreground, \u2026) so dark mode and rebranding work.",
+          snippet: m.trim().replace(/^["'`:\s]+/, "")
+        });
+      }
+    }
+    const wrapsTokenInColorFn = COLOR_FN_WRAPPING_VAR_RE.test(line);
+    if (wrapsTokenInColorFn) {
+      findings.push({
+        rule: "chart-token-color-fn",
+        severity: "error",
+        line: lineNo,
+        message: "Color function wrapping a token (e.g. hsl(var(--chart-1))). The --chart-N and theme tokens are already OKLCH colors \u2014 wrapping them in hsl()/rgb() is invalid CSS and renders an empty/uncolored chart (the build still passes). Pass the token directly: var(--chart-1), or let the app-kit charts use --chart-N automatically.",
+        snippet: line.trim().slice(0, 120)
+      });
+    }
+    const literals = wrapsTokenInColorFn ? null : line.match(COLOR_LITERAL_RE);
+    if (literals) {
+      findings.push({
+        rule: "color-literal",
+        severity: "error",
+        line: lineNo,
+        message: "Hardcoded color literal. Colors must come from the theme generator (createTimbalTheme) and semantic tokens \u2014 never inline hex/oklch/rgb.",
+        snippet: line.trim().slice(0, 120)
+      });
+    }
+    if (INLINE_STYLE_COLOR_RE.test(line)) {
+      findings.push({
+        rule: "inline-style-color",
+        severity: "error",
+        line: lineNo,
+        message: "Inline style color. Move color to a semantic Tailwind token on className.",
+        snippet: line.trim().slice(0, 120)
+      });
+    }
+    if (RAW_CONTROL_SURFACE_RE.test(line)) {
+      findings.push({
+        rule: "raw-control-surface",
+        severity: "warn",
+        line: lineNo,
+        message: "Hand-rolled control surface (border-input). Use a kit control \u2014 SearchInput, Select, DropdownMenu, FieldInput, FieldSelect \u2014 so it matches every other control.",
+        snippet: line.trim().slice(0, 120)
+      });
+    }
+    if (COLORED_HOVER_RE.test(line)) {
+      findings.push({
+        rule: "no-colored-hover",
+        severity: "warn",
+        line: lineNo,
+        message: "Colored hover background/gradient. House style: interactive cards and list items must use neutral hover states \u2014 never hard-code colored backgrounds or borders on hover.",
+        snippet: line.trim().slice(0, 120)
+      });
+    }
+    if (TREND_CONTEXT_RE.test(line) && TREND_COLOR_RE.test(line)) {
+      findings.push({
+        rule: "neutral-trend",
+        severity: "warn",
+        line: lineNo,
+        message: "Colored trend indicator. House style: don't tint deltas green/red on every metric \u2014 show a trend only when the change is the point, and keep it muted (text-muted-foreground).",
+        snippet: line.trim().slice(0, 120)
+      });
+    }
+    if (BOLD_VALUE_RE.test(line)) {
+      findings.push({
+        rule: "bold-metric",
+        severity: "warn",
+        line: lineNo,
+        message: "Bold large value. House style: metric values use font-normal, not bold \u2014 bold giant numbers read as a template.",
+        snippet: line.trim().slice(0, 120)
+      });
+    }
+    if (GRADIENT_RE.test(line)) {
+      const fromTo = line.match(
+        new RegExp(`(?:from|via|to)-([a-z-]+)`, "g")
+      );
+      const colorStops = (fromTo ?? []).map((u) => stripVariants(u).replace(/^(?:from|via|to)-/, "")).filter((token) => !GRADIENT_DIRECTIONS.has(token));
+      const allReserved = colorStops.length > 0 && colorStops.every((token) => RESERVED_GRADIENT_SET.has(token));
+      if (!allReserved) {
+        findings.push({
+          rule: "data-gradient",
+          severity: "warn",
+          line: lineNo,
+          message: "Gradient outside chrome. Gradients are reserved for buttons / elevated / modal / playground \u2014 never a data card, tile, or table.",
+          snippet: line.trim().slice(0, 120)
+        });
+      }
+    }
+    if (/\b(?:border-t|border-b|divide-y)\b/.test(line)) {
+      dividerRunCount++;
+      if (dividerRunCount === maxRowDividers + 1) {
+        findings.push({
+          rule: "row-divider",
+          severity: "warn",
+          line: lineNo,
+          message: "Divider on every row. Prefer spacing (gap-*) or zebra striping over a rule under each list item.",
+          snippet: line.trim().slice(0, 120)
+        });
+      }
+    } else if (line.trim() !== "" && !line.includes("className")) {
+      if (!/^\s*[)>}/]/.test(line)) dividerRunCount = 0;
+    }
+    if (usesLucide && lucideNames.size > 0) {
+      for (const name of lucideNames) {
+        const usage = new RegExp(`<${name}\\b`, "g");
+        const hits = line.match(usage);
+        if (hits) iconUsageCount += hits.length;
+      }
+    }
+    if (pageTitle) {
+      const titleMatch = line.match(/<(Section|ChartPanel|Card|DataTable|SurfaceCard)\s+[^>]*\btitle=(?:"([^"]+)"|\{["']([^"']+)["']\})/);
+      if (titleMatch) {
+        const element = titleMatch[1];
+        const titleVal = (titleMatch[2] || titleMatch[3]).trim().toLowerCase();
+        if (titleVal === pageTitle || titleVal.includes(pageTitle) || pageTitle.includes(titleVal)) {
+          findings.push({
+            rule: "no-title-repetition",
+            severity: "warn",
+            line: lineNo,
+            message: `Title repetition. The <${element}> title "${titleVal}" repeats or is very similar to the <Page> title "${pageTitle}". Drop the title from the child element or use a title-less Section to avoid redundant headings.`,
+            snippet: line.trim().slice(0, 120)
+          });
+        }
+      }
+    }
+    if (hasChat) {
+      const wrappingMatch = line.match(/<(Card|Section|SurfaceCard|FormSection|SettingsSection)\b/);
+      if (wrappingMatch) {
+        findings.push({
+          rule: "no-chat-wrapping",
+          severity: "error",
+          line: lineNo,
+          message: `Chat component wrapping. Never wrap TimbalChat or AppChatPanel inside a <${wrappingMatch[1]}> or custom bordered container. Let the chat component fill the page or slot directly.`,
+          snippet: line.trim().slice(0, 120)
+        });
+      }
+      const headingMatch = line.match(/<(h[1-6])\b/);
+      if (headingMatch) {
+        findings.push({
+          rule: "no-chat-wrapping",
+          severity: "error",
+          line: lineNo,
+          message: `Custom heading in chat view. Do not render custom <${headingMatch[1]}> headings on the chat page. Pass welcome.heading to TimbalChat if you need to customize the welcome title.`,
+          snippet: line.trim().slice(0, 120)
+        });
+      }
+    }
+  }
+  if (usesLucide && iconUsageCount > maxIcons) {
+    findings.push({
+      rule: "icon-spam",
+      severity: "warn",
+      line: 1,
+      message: `Too many icons (${iconUsageCount} > ${maxIcons}). Icons should mark actions/nav/status \u2014 not decorate every label, tile, and card.`,
+      snippet: `${iconUsageCount} lucide-react icon usages`
+    });
+  }
+  const effectiveErrors = findings.filter(
+    (f) => f.severity === "error" || options.strict && f.severity === "warn"
+  ).length;
+  return {
+    findings,
+    errorCount: findings.filter((f) => f.severity === "error").length,
+    warnCount: findings.filter((f) => f.severity === "warn").length,
+    ok: effectiveErrors === 0
+  };
+}
+function formatLintReport(findings) {
+  if (!Array.isArray(findings)) {
+    throw new TypeError(
+      `formatLintReport(findings) expects the findings array, but received ${describeArg(findings)}. Pass result.findings \u2014 formatLintReport(lintGeneratedUi(code).findings) \u2014 not the whole LintResult.`
+    );
+  }
+  if (findings.length === 0) return "";
+  const lines = findings.slice().sort((a, b) => a.line - b.line).map((f) => {
+    const tag = f.severity === "error" ? "ERROR" : "warn ";
+    return `  ${tag} L${f.line} [${f.rule}] ${f.message}
+        \u2192 ${f.snippet}`;
+  });
+  const errs = findings.filter((f) => f.severity === "error").length;
+  const warns = findings.filter((f) => f.severity === "warn").length;
+  return `Anti-slop review: ${errs} error(s), ${warns} warning(s)
+${lines.join("\n")}`;
+}
+
+// src/design/ui-review.ts
+function reviewGeneratedUi(source, options = {}) {
+  const lint = lintGeneratedUi(source, options);
+  const report = formatLintReport(lint.findings);
+  if (lint.ok) {
+    return { lint, passed: true, report, revisionPrompt: null };
+  }
+  const revisionPrompt = [
+    "The generated UI failed the Timbal anti-slop review. Fix every issue below, then return the corrected code only.",
+    "",
+    report,
+    "",
+    "Rules: colors come only from semantic tokens (text-primary, bg-muted, border-border, text-muted-foreground, \u2026) \u2014 never palette colors, hex, or oklch. Icons mark actions/nav/status, not decoration. Metric values use font-normal. No gradients on data surfaces. No divider under every row. Do not change anything that already passed."
+  ].join("\n");
+  return { lint, passed: false, report, revisionPrompt };
+}
+var UI_REVIEW_AGENT_INSTRUCTIONS = `
+## Self-review before returning UI (anti-slop)
+
+Before you output any generated UI code, silently re-read it and fix anything that matches the slop checklist \u2014 this is the same rubric an automated linter applies, so output that fails it will be rejected and sent back:
+
+- **No hardcoded colors.** Every color is a semantic token (\`text-primary\`, \`bg-muted\`, \`border-border\`, \`text-muted-foreground\`, \`bg-destructive\`, \u2026). No \`text-blue-600\`, no \`#hex\`, no \`oklch(...)\`, no \`style={{ color }}\`.
+- **No decorative icons.** An icon must mark an action, nav target, or status. Remove icons that sit beside a label that already says the thing. Aim for very few icons per view.
+- **Muted, sparse trends.** No colored up/down pill on every metric. Show a trend only when the change is the point.
+- **Normal-weight values.** Metric numbers use \`font-normal\`, never \`font-bold\` at large sizes.
+- **No card-in-card, no per-row dividers, no gradients on data surfaces.** Group with spacing/Sections; reserve gradients for chrome.
+- **Compose from blocks.** Prefer \`MetricRow\` / \`MetricChartCard\` / \`DataTable\` / \`IntegrationCard\` over hand-assembled primitives.
+
+If a check fails, fix it and re-read once more. Only return code that would pass clean.
+`.trim();
+
+// src/cli/ui-lint.ts
+function parseArgs(argv) {
+  const parsed = { strict: false, json: false, files: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case "--strict":
+        parsed.strict = true;
+        break;
+      case "--json":
+        parsed.json = true;
+        break;
+      case "--max-icons":
+        parsed.maxIcons = Number(argv[++i]);
+        break;
+      case "--max-row-dividers":
+        parsed.maxRowDividers = Number(argv[++i]);
+        break;
+      case "-h":
+      case "--help":
+        printUsage();
+        process.exit(0);
+        break;
+      default:
+        if (arg.startsWith("-")) {
+          process.stderr.write(`timbal-ui-lint: unknown flag ${arg}
+`);
+          process.exit(2);
+        }
+        parsed.files.push(arg);
+    }
+  }
+  return parsed;
+}
+function printUsage() {
+  process.stdout.write(
+    "Usage: timbal-ui-lint [--strict] [--max-icons N] [--max-row-dividers N] [--json] <file.tsx> [...]\n"
+  );
+}
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.files.length === 0) {
+    printUsage();
+    process.exit(2);
+  }
+  const reviewOptions = {
+    strict: args.strict,
+    maxIconsPerView: Number.isFinite(args.maxIcons) ? args.maxIcons : void 0,
+    maxRowDividers: Number.isFinite(args.maxRowDividers) ? args.maxRowDividers : void 0
+  };
+  const results = [];
+  for (const file of args.files) {
+    let source;
+    try {
+      source = readFileSync(file, "utf8");
+    } catch (e) {
+      results.push({
+        file,
+        passed: true,
+        report: "",
+        findings: [],
+        revisionPrompt: null,
+        error: e instanceof Error ? e.message : String(e)
+      });
+      continue;
+    }
+    const review = reviewGeneratedUi(source, reviewOptions);
+    results.push({
+      file,
+      passed: review.passed,
+      report: review.report,
+      findings: review.lint.findings,
+      revisionPrompt: review.revisionPrompt
+    });
+  }
+  const failed = results.filter((r) => !r.passed);
+  const ok = failed.length === 0;
+  if (args.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          ok,
+          files: results.map(({ revisionPrompt, ...rest }) => rest),
+          revisionPrompt: ok ? null : buildCombinedPrompt(failed)
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    process.exit(ok ? 0 : 1);
+  }
+  if (ok) {
+    process.stdout.write("Anti-slop review passed.\n");
+    process.exit(0);
+  }
+  for (const r of failed) {
+    process.stdout.write(`
+=== ${r.file} ===
+${r.report}
+`);
+  }
+  process.stdout.write(`
+${buildCombinedPrompt(failed)}
+`);
+  process.exit(1);
+}
+function buildCombinedPrompt(failed) {
+  const header = "The generated UI failed the Timbal anti-slop review. Fix every issue below, then re-check. Do not change anything that already passed.";
+  const perFile = failed.filter((r) => r.report).map((r) => `
+--- ${r.file} ---
+${r.report}`).join("\n");
+  const rules = "Rules: colors come only from semantic tokens (text-primary, bg-muted, border-border, text-muted-foreground, \u2026) \u2014 never palette colors, hex, or oklch. Icons mark actions/nav/status, not decoration. Metric values use font-normal. No card-in-card, no per-row dividers, no gradients on data surfaces. Compose from kit blocks (MetricRow, DataTable, AlertCard) instead of hand-rolled primitives.";
+  return [header, perFile, "", rules].join("\n");
+}
+main();