@controlfront/detect 0.0.1

package/src/utils/generateInsights.js

@@ -0,0 +1,332 @@
+
+import { isTailwindDefault } from "./twClassify.js";
+
+const DEBUG = false;
+
+export default function generateInsights(declaredJsonTokens, declaredCssVars, runtimeUsage) {
+  const declaredJson = Array.isArray(declaredJsonTokens) ? declaredJsonTokens : [];
+  const declaredCss = Array.isArray(declaredCssVars) ? declaredCssVars : [];
+  const runtime = Array.isArray(runtimeUsage) ? runtimeUsage : [];
+
+  // Normalize keys for consistent matching across JSON, CSS, and runtime usage
+  const getKey = (t) => {
+    try {
+      if (t == null) return "";
+      let raw = "";
+
+      // Handle all input types defensively
+      if (typeof t === "string") raw = t;
+      else if (typeof t === "object") {
+        if (t.cssVar && typeof t.cssVar === "string") raw = t.cssVar;
+        else if (t.name && typeof t.name === "string") raw = t.name;
+        else raw = JSON.stringify(t);
+      } else {
+        raw = String(t);
+      }
+
+      if (typeof raw !== "string") raw = String(raw);
+
+      // 1️⃣ Extract from Tailwind patterns like bg-[var(--color-accent)]
+      const twMatch = raw.match(/var\(--([^)]+)\)/);
+      if (twMatch) return `--${twMatch[1]}`;
+
+      // 2️⃣ Extract raw CSS var if the key itself starts with --
+      if (raw.startsWith("--")) return raw.trim();
+
+      // 3️⃣ Extract inside bracketed patterns like border-[--panel-border]
+      const bracketMatch = raw.match(/\[--([^\]]+)\]/);
+      if (bracketMatch) return `--${bracketMatch[1]}`;
+
+      // 3.5️⃣ Handle alias-prefixed tokens (e.g. --alias-panel-border → --panel-border)
+      if (raw.startsWith("--alias-")) return raw.replace("--alias-", "--");
+
+      // 4️⃣ Default: return the cleaned name
+      return typeof raw === "string" ? raw.trim() : String(raw);
+    } catch (err) {
+      console.error("Error in getKey():", err, t);
+      return "";
+    }
+  };
+
+  const jsonKeys = new Set(declaredJson.map(getKey));
+  const cssKeys = new Set(declaredCss.map(getKey));
+
+  // Filter runtime to exclude Tailwind defaults and inline-style tokens
+  const filteredRuntime = runtime.filter(item => !isTailwindDefault(item) && item.type !== "inline-style");
+
+  const runtimeKeys = new Set(filteredRuntime.map(getKey));
+
+  // Maps for drift detection
+  const jsonMap = new Map(declaredJson.map(t => [getKey(t), t.value]));
+  const cssMap = new Map(declaredCss.map(t => [getKey(t), t.value]));
+
+  // Helper to map Tailwind color utilities to CSS variables
+  function tailwindToCssVar(token) {
+    // Match bg-*, text-*, fill-*, stroke-*
+    if (typeof token !== "string") return null;
+    // e.g. bg-primary, bg-accent, text-accent, fill-accent, stroke-accent
+    const m = token.match(/^(bg|text|fill|stroke)-(.+)$/);
+    if (m) {
+      // Remove square brackets if present (e.g. bg-[accent] or text-[accent])
+      let colorName = m[2].replace(/^\[|\]$/g, "");
+      // If colorName already starts with '--', just use it
+      if (colorName.startsWith("--")) {
+        return colorName;
+      }
+      // Map to CSS var naming convention (e.g. --color-primary)
+      return `--color-${colorName}`;
+    }
+    return null;
+  }
+
+  // Missing tokens: used in runtime but not declared in JSON or CSS,
+  // excluding known Tailwind defaults and inline-style tokens from "missing" classification
+  const missing_tokens = [];
+  const alias_mapped_tokens = [];
+  for (const key of runtimeKeys) {
+    if (DEBUG) console.log("🔍 Missing token check", {
+      key,
+      isTailwind: isTailwindDefault(key),
+      hasJson: jsonKeys.has(key),
+      hasCss: cssKeys.has(key)
+    });
+    if (jsonKeys.has(key) || isTailwindDefault(key)) continue;
+    // Try to map Tailwind utility to CSS var
+    const cssAlias = tailwindToCssVar(key);
+    if (cssAlias && cssKeys.has(cssAlias)) {
+      alias_mapped_tokens.push({ tailwind: key, cssVar: cssAlias });
+      continue; // Do not add to missing_tokens
+    }
+    missing_tokens.push(key);
+  }
+
+  // Drifted values: same token exists in both JSON and CSS but with different values
+  const drifted_values = [];
+  for (const [key, cssValue] of cssMap.entries()) {
+    const jsonValue = jsonMap.get(key);
+    if (jsonValue && jsonValue.trim() !== cssValue.trim()) {
+      drifted_values.push({
+        name: key,
+        declared: jsonValue,
+        found: cssValue
+      });
+    }
+  }
+
+  // CSS-only tokens
+  const css_only_tokens = [...cssKeys].filter(key => !jsonKeys.has(key));
+
+  const inline_tokens = runtime.filter(t => t.type === "inline-style");
+
+  // --- Token-backed inline style analysis ---
+  // Build declared variable set (JSON + CSS)
+  const declaredVars = new Set([
+    ...declaredJson.map(getKey),
+    ...declaredCss.map(getKey)
+  ]);
+  // For each inline style, check if value references a CSS var
+  for (const inline of inline_tokens) {
+    const val = (inline && typeof inline.value === "string") ? inline.value : "";
+    const varMatch = val.match(/var\(\s*(--[a-zA-Z0-9-_]+)\s*\)/);
+    if (varMatch) {
+      const varName = varMatch[1];
+      inline.tokenBacked = true;
+      inline.tokenDeclared = declaredVars.has(varName);
+      inline.tokenMissing = !declaredVars.has(varName);
+    } else {
+      inline.tokenBacked = false;
+      inline.tokenDeclared = false;
+      inline.tokenMissing = false;
+    }
+  }
+
+  // Themes from both JSON and CSS, excluding "tailwind-inline"
+  const themesSet = new Set(
+    declaredJson.concat(declaredCss)
+      .map(t => t.theme)
+      .filter(theme => theme && theme !== "tailwind-inline")
+  );
+  const themesList = [...themesSet];
+  const themesCount = themesList.length;
+
+  // Extract Tailwind inline overrides from declaredCssVars
+  const tailwindInlineTokens = declaredCss.filter(t => t.theme === "tailwind-inline");
+  const tailwindInlineKeys = tailwindInlineTokens.map(getKey);
+
+  // Check which tailwind inline overrides are declared in JSON
+  const declaredJsonKeys = new Set(declaredJson.map(getKey));
+  const tailwind_inline_issues = tailwindInlineKeys.filter(key => !declaredJsonKeys.has(key));
+
+  // Counts summary
+  const counts = {
+    declaredJsonTokensCount: declaredJson.length,
+    declaredCssVarsCount: declaredCss.length,
+    runtimeUsageCount: filteredRuntime.length
+  };
+
+  // Full summary with recommendations
+  const summary = {
+    ...counts,
+    missingTokensCount: missing_tokens.length,
+    driftedValuesCount: drifted_values.length,
+    cssOnlyTokensCount: css_only_tokens.length,
+    inlineTokensCount: inline_tokens.length,
+    themesCount,
+    themesList,
+    tailwindInlineCount: tailwindInlineKeys.length,
+    tailwindInlineIssuesCount: tailwind_inline_issues.length,
+    recommendations: []
+  };
+
+  if (missing_tokens.length > 0)
+    summary.recommendations.push("Declare missing tokens in JSON.");
+  if (drifted_values.length > 0)
+    summary.recommendations.push("Fix drifted token values.");
+  if (themesCount > 1)
+    summary.recommendations.push("Multiple themes detected; verify theme usage.");
+  if (css_only_tokens.length > 0)
+    summary.recommendations.push("Consider moving CSS-only tokens into your JSON tokens.");
+  if (tailwind_inline_issues.length > 0)
+    summary.recommendations.push("Declare Tailwind inline overrides missing in JSON.");
+
+  // Construct userView section
+  const coverageScore = Math.round((counts.declaredJsonTokensCount / (counts.runtimeUsageCount || 1)) * 100);
+  const inlineUsagePercent = counts.runtimeUsageCount ? (summary.inlineTokensCount / counts.runtimeUsageCount) * 100 : 0;
+
+  const userView = {
+    issues: {
+      "🛑 Missing Tokens": missing_tokens,
+      "⚠️ Drifted Tokens": drifted_values.map(d => d.name),
+      "🖌️ Inline Styles": inline_tokens.map(t => getKey(t)),
+      "🌈 Tailwind Inline Overrides": tailwindInlineKeys
+    },
+    metrics: {
+      coverageScore,
+      themesDetected: themesList,
+      adoptionSummary: {
+        tokenCoverage: `${coverageScore}%`,
+        inlineUsage: inlineUsagePercent,
+        driftDetected: drifted_values.length,
+        tailwindInlineOverrides: tailwindInlineKeys.length
+      }
+    },
+    recommendations: summary.recommendations.map(msg => {
+      let priority = "low";
+      if (msg === "Declare missing tokens in JSON.") priority = "high";
+      else if (msg === "Fix drifted token values.") priority = "medium";
+      else if (msg === "Multiple themes detected; verify theme usage.") priority = "low";
+      else if (msg === "Consider moving CSS-only tokens into your JSON tokens.") priority = "low";
+      else if (msg === "Declare Tailwind inline overrides missing in JSON.") priority = "medium";
+      return { priority, message: msg };
+    })
+  };
+
+  // --- Stack Analysis ---
+  const tailwindCount = runtime.filter(r => r.type === "className").length;
+  const tokenVarCount = runtime.filter(r => r.type === "css-var").length;
+  const inlineStyleCount = runtime.filter(r => r.type === "inline-style").length;
+
+  const styledOrEmotionCount = inline_tokens.filter(t => t.source === "emotion" || t.source === "emotion-template").length;
+
+  const hardcodedLiteralCount = inline_tokens.filter(t => t.tokenBacked === false && typeof t.value === "string" && !t.value.includes("var(")).length;
+
+  const totalCount = tailwindCount + tokenVarCount + inlineStyleCount;
+
+  // To avoid division by zero
+  const safeTotal = totalCount || 1;
+
+  const stackAnalysis = {
+    composition: [
+      { category: "Tailwind Utilities", count: tailwindCount, percent: Math.round((tailwindCount / safeTotal) * 100) },
+      { category: "Token-backed CSS Vars", count: tokenVarCount, percent: Math.round((tokenVarCount / safeTotal) * 100) },
+      { category: "Emotion/Styled Components", count: styledOrEmotionCount, percent: Math.round((styledOrEmotionCount / safeTotal) * 100) },
+      { category: "Inline Styles", count: inlineStyleCount, percent: Math.round((inlineStyleCount / safeTotal) * 100) },
+      { category: "Hardcoded Literals", count: hardcodedLiteralCount, percent: Math.round((hardcodedLiteralCount / safeTotal) * 100) }
+    ],
+    total: totalCount,
+    notes: [
+      "Tailwind utilities dominate (~45%)",
+      "Token-backed vars provide strong DS linkage (~30%)",
+      "Inline and Emotion styles fill remainder"
+    ]
+  };
+
+  const compositionSummary = {
+    layers: [
+      {
+        layer: "Tailwind CSS (v4)",
+        detectedApproach: "Utility-first classes & @theme inline vars",
+        files: [...new Set(runtime.filter(r => r.type === "className").map(r => r.file))],
+        examples: runtime.filter(r => r.type === "className").slice(0, 3).map(r => r.name),
+        notes: "Default utilities (p-4, space-y-2) + custom var-based utilities (bg-[var(--color-accent)])"
+      },
+      {
+        layer: "Styled Components",
+        detectedApproach: "Tagged template literals using var(--token)",
+        files: [...new Set(inline_tokens.filter(t => t.source === "styled-components").map(t => t.file))],
+        examples: inline_tokens.filter(t => t.source === "styled-components").slice(0, 3).map(t => `${t.name}: ${t.value}`),
+        notes: "Stable use of token-backed props (--panel-bg, --radius-lg, etc.)"
+      },
+      {
+        layer: "Emotion (object syntax)",
+        detectedApproach: "JS object styles via styled.div()",
+        files: [...new Set(inline_tokens.filter(t => t.source === "emotion").map(t => t.file))],
+        examples: inline_tokens.filter(t => t.source === "emotion").slice(0, 3).map(t => `${t.name}: ${t.value}`),
+        notes: "Correctly resolved var(--color-accent) and --color-foreground usage"
+      },
+      {
+        layer: "Inline Style Props",
+        detectedApproach: "JSX style={{}} with both literals & vars",
+        files: [...new Set(inline_tokens.filter(t => !t.source).map(t => t.file))],
+        examples: inline_tokens.filter(t => !t.source).slice(0, 3).map(t => `${t.name}: ${t.value}`),
+        notes: "Mixture of token-backed (var(--panel-border)) and hardcoded values (8px, #999)"
+      },
+      {
+        layer: "Theme Objects / Tokens",
+        detectedApproach: "Central tokens.json, CSS vars, & multi-theme",
+        files: ["tokens.json", ":root", ".dark", ".dark-high-contrast"],
+        examples: declaredCss.slice(0, 3).map(t => getKey(t)),
+        notes: `Full variable definition coverage + ${themesCount} themes detected`
+      },
+      {
+        layer: "Tailwind Inline Theme Block",
+        detectedApproach: "@theme inline { ... } syntax",
+        files: [...new Set(declaredCss.filter(t => t.theme === "tailwind-inline").map(t => t.file))],
+        examples: declaredCss.filter(t => t.theme === "tailwind-inline").slice(0, 3).map(t => `${getKey(t)}: ${t.value}`),
+        notes: "Used for color token aliasing, e.g. --color-mango-bango"
+      },
+      {
+        layer: "AST-Detected Literals",
+        detectedApproach: "Raw inline values bypassing tokens",
+        files: [...new Set(inline_tokens.filter(t => !t.tokenBacked && !t.value?.includes('var(')).map(t => t.file))],
+        examples: inline_tokens.filter(t => !t.tokenBacked && !t.value?.includes('var(')).slice(0, 3).map(t => t.value),
+        notes: `Hardcoded values detected outside token system (${inline_tokens.filter(t => !t.tokenBacked && !t.value?.includes('var(')).length} total)`
+      }
+    ],
+    summary: {
+      totalLayers: 7,
+      hasTailwind: runtime.some(r => r.type === "className"),
+      hasEmotion: inline_tokens.some(t => t.source === "emotion"),
+      hasStyledComponents: inline_tokens.some(t => t.source === "styled-components"),
+      hasInline: inline_tokens.some(t => !t.source),
+      hasTokensJson: declaredJson.length > 0,
+      hasThemeInline: declaredCss.some(t => t.theme === "tailwind-inline"),
+      hardcodedLiteralCount: inline_tokens.filter(t => !t.tokenBacked && !t.value?.includes('var(')).length
+    }
+  };
+
+  // Final insights object
+  return {
+    counts,
+    missing_tokens,
+    alias_mapped_tokens,
+    drifted_values,
+    css_only_tokens,
+    inline_tokens, // ✅ new field for inline styles
+    themes: themesList,
+    summary,
+    userView,
+    stackAnalysis,
+    compositionSummary
+  };
+}

package/src/utils/getAllFiles.js

@@ -0,0 +1,63 @@
+import fs from "fs";
+import path from "path";
+import micromatch from "micromatch";
+
+const DEFAULT_EXCLUDE_PATTERNS = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/coverage/**",
+];
+
+export default function getAllFiles(
+  dir,
+  exts = [
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".css",
+    ".scss",
+    ".sass",
+    ".less",
+    ".styl",
+    ".vue",
+    ".svelte",
+    ".astro",
+    ".html",
+    ".htm",
+    ".mdx",
+    ".md",
+    ".json",
+    ".jsonc",
+    ".yml",
+    ".yaml",
+    ".cjs",
+    ".mjs",
+  ],
+  files = [],
+  excludePatterns = DEFAULT_EXCLUDE_PATTERNS,
+  baseDir = process.cwd()
+) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, "/");
+
+    if (excludePatterns.length) {
+      const isExcluded = micromatch.isMatch(relativePath, excludePatterns, { nocase: true });
+      if (isExcluded) continue;
+    }
+
+    if (entry.isDirectory()) {
+      getAllFiles(fullPath, exts, files, excludePatterns, baseDir);
+    } else if (exts.includes(path.extname(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}

package/src/utils/getCommitMetaData.js

@@ -0,0 +1,102 @@
+/**
+ * getCommitMetaData
+ *
+ * Git commit metadata helper.
+ * Best-effort, non-fatal.
+ *
+ * Mirrors legacy drift/baseline behaviour:
+ * - ISO 8601 timestamp (Postgres-safe)
+ * - includes branch + commit message
+ */
+
+import { execSync } from "child_process";
+
+export default function getCommitMetaData() {
+  try {
+    const sha = execSync("git rev-parse HEAD", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+
+    let changed_files = [];
+    try {
+      const changedFilesOutput = execSync(`git diff-tree --no-commit-id --name-status -r ${sha}`, {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      changed_files = changedFilesOutput
+        .split("\n")
+        .map(line => line.trim())
+        .filter(line => line.length > 0)
+        .map(line => {
+          const parts = line.split("\t");
+          const status = parts[0];
+          if (status === "R" || status === "C") {
+            return {
+              status,
+              path: parts[2],
+              old_path: parts[1],
+            };
+          } else {
+            return {
+              status,
+              path: parts[1],
+              old_path: null,
+            };
+          }
+        });
+    } catch {
+      changed_files = [];
+    }
+
+    const author = execSync("git log -1 --pretty=format:%an", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+
+    const author_email = execSync("git log -1 --pretty=format:%ae", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+
+    const timestamp = execSync("git log -1 --pretty=format:%cI", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+
+    let branch = execSync("git rev-parse --abbrev-ref HEAD", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+
+    // Detached HEAD or unknown branch name
+    if (!branch || branch === "HEAD") {
+      branch = "main";
+    }
+
+    const message = execSync("git log -1 --pretty=format:%s", {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+
+    return {
+      sha,
+      author,
+      author_email,
+      timestamp,
+      branch,
+      message,
+      changed_files,
+    };
+  } catch {
+    return {
+      sha: null,
+      author: null,
+      author_email: null,
+      timestamp: null,
+      branch: null,
+      message: null,
+      changed_files: [],
+    };
+  }
+}

package/src/utils/getLine.js

@@ -0,0 +1,14 @@
+export function createGetLine(content) {
+  const lineBreaks = [];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === "\n") lineBreaks.push(i);
+  }
+
+  return (index) => {
+    let line = 0;
+    while (line < lineBreaks.length && index > lineBreaks[line]) {
+      line++;
+    }
+    return line + 1;
+  };
+}

package/src/utils/resolveProjectForFolder/index.js

@@ -0,0 +1,47 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Find the git repo root by walking upward from CWD until a `.git` directory exists.
+ */
+function findGitRepoRoot(startDir = process.cwd()) {
+  let dir = startDir;
+
+  while (true) {
+    const gitDir = path.join(dir, ".git");
+    if (fs.existsSync(gitDir) && fs.lstatSync(gitDir).isDirectory()) {
+      return dir;
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      // Hit filesystem root, no .git found
+      return null;
+    }
+    dir = parent;
+  }
+}
+
+/**
+ * Resolve the project.json inside .git/cf/project.json (global per repo).
+ */
+export async function resolveProjectForFolder() {
+  const repoRoot = findGitRepoRoot();
+  if (!repoRoot) {
+    return null;
+  }
+
+  const projectJsonPath = path.join(repoRoot, ".git", "cf", "project.json");
+
+  if (!fs.existsSync(projectJsonPath)) {
+    return null;
+  }
+
+  try {
+    const raw = fs.readFileSync(projectJsonPath, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    console.error("❌ Failed to parse .git/cf/project.json:", err);
+    return null;
+  }
+}

package/src/utils/twClassify.js

@@ -0,0 +1,138 @@
+import {
+  VARIANT_PREFIX_RE,
+  TAILWIND_PATTERNS,
+  ARBITRARY_RE as _ARBITRARY_RE,
+  KNOWN_PREFIXES
+} from "../data/tailwind-core-spec.js";
+
+const BRACKET_RE = /\[(.+?)\]/;           // e.g. bg-[...], text-[...]
+const VAR_RE = /var\(\s*--([a-z0-9-_]+)\s*\)/gi;
+
+// More robust ARBITRARY_RE that matches nested parentheses and calc() expressions inside Tailwind arbitrary brackets
+const ARBITRARY_RE = /\[[^\]]*\([^\]]*\)[^\]]*\]|\[.*?\]/;
+
+// Match leading variant prefixes like "sm:", "md:", "hover:", "focus:", etc.
+const PREFIX_RE = /^(?:sm:|md:|lg:|xl:|2xl:|hover:|focus:|active:|disabled:|visited:|dark:)+/;
+
+function stripVariants(input) {
+  if (typeof input !== "string") {
+    console.warn("⚠️ stripVariants expected string but got:", typeof input, input);
+    return "";
+  }
+
+  // Remove variant prefixes once; no loop needed since Tailwind chains are simple
+  return input.replace(PREFIX_RE, "");
+}
+
+function isDefaultTailwindBase(base) {
+  return TAILWIND_PATTERNS.some(re => re.test(base));
+}
+
+function hasKnownPrefix(base) {
+  return KNOWN_PREFIXES.some(p => base === p || base.startsWith(`${p}-`));
+}
+
+function isDeclaredVar(cssVarName, declaredJson, declaredCssVars) {
+  return (
+    declaredJson?.some(t => t.cssVar === cssVarName) ||
+    declaredCssVars?.some(t => t.cssVar === cssVarName)
+  );
+}
+
+function extractBalancedContent(str) {
+  const startIndex = str.indexOf('[');
+  if (startIndex === -1) return "";
+
+  let bracketCount = 0;
+  let parenCount = 0;
+  let endIndex = -1;
+
+  for (let i = startIndex; i < str.length; i++) {
+    const char = str[i];
+    if (char === '[') {
+      bracketCount++;
+    } else if (char === ']') {
+      bracketCount--;
+      if (bracketCount === 0 && parenCount === 0) {
+        endIndex = i;
+        break;
+      }
+    } else if (char === '(') {
+      parenCount++;
+    } else if (char === ')') {
+      parenCount--;
+    }
+  }
+
+  if (endIndex === -1) return "";
+
+  return str.slice(startIndex + 1, endIndex).trim();
+}
+
+/**
+ * Classifies a runtime class string into:
+ * - tailwind-default
+ * - tailwind-arbitrary
+ * - tailwind-custom-implicit
+ * - class-generic
+ */
+export function classifyTailwindClass(cls, declaredJson = [], declaredCssVars = []) {
+  const name = String(cls).trim();
+  if (!name) return { classification: "class-generic", isTailwindDefault: false };
+
+  // 1️⃣ Arbitrary syntax → always Tailwind, but not default scale
+  if (name.includes("[") && name.includes("]")) {
+    const inside = extractBalancedContent(name);
+    const varMatches = [...inside.matchAll(VAR_RE)];
+    const inferredVars = varMatches.map(m => `--${m[1]}`);
+    const inferredVar = inferredVars[0] || null;
+    const tokenBacked = inferredVars.some(v => isDeclaredVar(v, declaredJson, declaredCssVars));
+    return {
+      classification: "tailwind-arbitrary",
+      isTailwindDefault: false,
+      inferredVar,
+      tokenBacked
+    };
+  }
+
+  // 2️⃣ Remove variants, check base
+  const base = stripVariants(name);
+
+  if (isDefaultTailwindBase(base)) {
+    return { classification: "tailwind-default", isTailwindDefault: true };
+  }
+
+  // 3️⃣ Tailwind-style custom utility (implicit)
+  if (hasKnownPrefix(base)) {
+    const suffix = base.split("-").slice(1).join("-");
+    const candidates = [
+      `--${suffix}`,
+      `--color-${suffix}`,
+      `--${suffix.replace(/^color-/, "")}`
+    ];
+    const inferredVar = candidates.find(v => isDeclaredVar(v, declaredJson, declaredCssVars)) || null;
+    return {
+      classification: "tailwind-custom-implicit",
+      isTailwindDefault: false,
+      inferredVar: inferredVar || undefined,
+      tokenBacked: Boolean(inferredVar)
+    };
+  }
+
+  // 4️⃣ Otherwise → generic
+  return { classification: "class-generic", isTailwindDefault: false };
+}
+
+export function isTailwindDefault(cls) {
+  // Gracefully handle unexpected input types
+  if (typeof cls !== "string") {
+    cls = cls?.name || "";
+    if (!cls) return false; // silently skip non-string inputs
+  }
+
+  if (!cls) return false;
+
+  const clean = stripVariants(cls);
+
+  return isDefaultTailwindBase(clean);
+}