@controlfront/detect 0.0.1

package/src/utils/buildRuntimeUsage.js

@@ -0,0 +1,337 @@
+import fs from "fs";
+import path from "path";
+import { classifyTailwindClass } from "./twClassify.js";
+import { parse } from "@babel/parser";
+import traverseModule from "@babel/traverse";
+const traverse = traverseModule.default;
+
+const DEBUG = false;
+
+/**
+ * Recursively scans files and extracts runtime token usage from classNames, classes, CSS var references, and inline styles.
+ * Returns an array of objects:
+ *   { type: "className" | "css-var" | "inline-style", name: string, file: string, ... }
+ */
+function camelToKebab(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+// Note: File discovery now happens in scan.js and files are passed in directly.
+export async function buildRuntimeUsage({ projectRoot, files }) {
+  if (!files?.length) return [];
+
+  const tokenUsages = [];
+  const classRegex = /class(?:Name)?=["'`]([^"'`]+)["'`]/g;
+  const cssVarRegex = /var\(--([\w-]+)\)/g;
+
+  for (const file of files) {
+    let content;
+    try {
+      content = await fs.promises.readFile(file, "utf8");
+    } catch {
+      continue;
+    }
+
+    // Detect styled-components or emotion usage
+    let detectedSource = "unknown";
+    if (/import\s+styled\s+from\s+['"]styled-components['"]/.test(content)) {
+      detectedSource = "styled-components";
+    } else if (/import\s+styled\s+from\s+['"]@emotion\/styled['"]/.test(content)) {
+      detectedSource = "emotion";
+    }
+
+    // Extract Tailwind or token-like classes
+    // Helper to extract content inside balanced brackets (handles nesting)
+    function extractBalanced(source, startIndex, openChar = '[', closeChar = ']') {
+      let depth = 0, start = -1;
+      for (let i = startIndex; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === openChar) {
+          if (start === -1) start = i;
+          depth++;
+        } else if (ch === closeChar) {
+          depth--;
+          if (depth === 0) return { block: source.slice(start + 1, i), end: i };
+        }
+      }
+      return null;
+    }
+
+    let classMatch;
+    while ((classMatch = classRegex.exec(content))) {
+      const classString = classMatch[1];
+      const fullMatch = classMatch[0]; // entire matched attribute string, e.g. className="..."
+      const classes = [];
+      let buffer = '';
+      let i = 0;
+      while (i < classString.length) {
+        const ch = classString[i];
+        if (ch === '[') {
+          const balanced = extractBalanced(classString, i);
+          if (balanced) {
+            buffer += `[${balanced.block}]`;
+            i = balanced.end + 1;
+            continue;
+          }
+        }
+        if (/\s/.test(ch)) {
+          if (buffer.trim()) classes.push(buffer.trim());
+          buffer = '';
+        } else {
+          buffer += ch;
+        }
+        i++;
+      }
+      if (buffer.trim()) classes.push(buffer.trim());
+
+      // Calculate line number for classMatch
+      const line = content.slice(0, classMatch.index).split('\n').length;
+
+      for (const cls of classes) {
+        const classification = classifyTailwindClass(cls);
+        tokenUsages.push({
+          type: "className",
+          name: cls,
+          file,
+          classification: classification.classification,
+          isTailwindDefault: classification.isTailwindDefault,
+          tokenBacked: classification.tokenBacked,
+          line,
+          instance: fullMatch,
+        });
+      }
+    }
+
+    // Extract CSS var usages
+    let varMatch;
+    while ((varMatch = cssVarRegex.exec(content))) {
+      const line = content.slice(0, varMatch.index).split('\n').length;
+      tokenUsages.push({ type: "css-var", name: `--${varMatch[1]}`, file, line });
+    }
+
+    // Extract inline styles using AST
+    try {
+      const ast = parse(content, {
+        sourceType: "module",
+        plugins: ["jsx", "typescript"],
+        locations: true,
+      });
+
+      traverse(ast, {
+        JSXAttribute(path) {
+          if (path.node.name?.name === "style" && path.node.value?.expression?.type === "ObjectExpression") {
+            const objExpr = path.node.value.expression;
+            const props = objExpr.properties;
+            const stylePairs = [];
+            for (const prop of props) {
+              if (!prop.key) continue;
+              const keyName = prop.key.name || prop.key.value;
+              if (!keyName) continue;
+              const key = camelToKebab(keyName);
+              let value = null;
+              if (prop.value.type === "StringLiteral") {
+                value = prop.value.value;
+              } else if (prop.value.type === "NumericLiteral") {
+                value = `${prop.value.value}px`;
+              } else if (prop.value.type === "TemplateLiteral") {
+                value = prop.value.quasis.map((q) => q.value.raw).join("");
+              } else if (prop.value.type === "Identifier") {
+                value = prop.value.name;
+              }
+              if (key && value) {
+                stylePairs.push(`${key}: ${value}`);
+              }
+            }
+            const instanceString = `style={{ ${stylePairs.join(", ")} }}`;
+            for (const prop of props) {
+              if (!prop.key) continue;
+              const keyName = prop.key.name || prop.key.value;
+              if (!keyName) continue;
+              const key = camelToKebab(keyName);
+              let value = null;
+              if (prop.value.type === "StringLiteral") {
+                value = prop.value.value;
+              } else if (prop.value.type === "NumericLiteral") {
+                value = `${prop.value.value}px`;
+              } else if (prop.value.type === "TemplateLiteral") {
+                value = prop.value.quasis.map((q) => q.value.raw).join("");
+              } else if (prop.value.type === "Identifier") {
+                value = prop.value.name;
+              }
+              if (key && value) {
+                const cssVarMatch = value.match(/var\(--([\w-]+)\)/);
+                if (cssVarMatch) {
+                  tokenUsages.push({
+                    type: "css-var",
+                    name: `--${cssVarMatch[1]}`,
+                    file,
+                    line: path.node.loc?.start?.line || null,
+                  });
+                } else {
+                  tokenUsages.push({
+                    type: "inline-style",
+                    name: key,
+                    value,
+                    file,
+                    line: path.node.loc?.start?.line || null,
+                    instance: instanceString,
+                  });
+                }
+              }
+            }
+          }
+        },
+        ObjectExpression(path) {
+          const parent = path.parent;
+          if (
+            parent &&
+            parent.type === "CallExpression" &&
+            parent.callee &&
+            parent.callee.object &&
+            parent.callee.object.name === "styled"
+          ) {
+            const props = path.node.properties;
+            const stylePairs = [];
+            for (const prop of props) {
+              if (!prop.key) continue;
+              const keyName = prop.key.name || prop.key.value;
+              if (!keyName) continue;
+              const key = camelToKebab(keyName);
+              let value = null;
+              if (prop.value.type === "StringLiteral") {
+                value = prop.value.value;
+              } else if (prop.value.type === "NumericLiteral") {
+                value = `${prop.value.value}px`;
+              } else if (prop.value.type === "TemplateLiteral") {
+                value = prop.value.quasis.map((q) => q.value.raw).join("");
+              } else if (prop.value.type === "Identifier") {
+                value = prop.value.name;
+              }
+              if (key && value) {
+                stylePairs.push(`${key}: ${value}`);
+              }
+            }
+            const instanceString = `styled.div({ ${stylePairs.join(", ")} })`;
+            for (const prop of props) {
+              if (!prop.key) continue;
+              const keyName = prop.key.name || prop.key.value;
+              if (!keyName) continue;
+              const key = camelToKebab(keyName);
+              let value = null;
+              if (prop.value.type === "StringLiteral") {
+                value = prop.value.value;
+              } else if (prop.value.type === "NumericLiteral") {
+                value = `${prop.value.value}px`;
+              } else if (prop.value.type === "TemplateLiteral") {
+                value = prop.value.quasis.map((q) => q.value.raw).join("");
+              } else if (prop.value.type === "Identifier") {
+                value = prop.value.name;
+              }
+              if (key && value) {
+                let sourceLabel = detectedSource === "styled-components"
+                  ? "styled-components"
+                  : detectedSource === "emotion"
+                  ? "emotion"
+                  : "unknown";
+                tokenUsages.push({
+                  type: "inline-style",
+                  name: key,
+                  value,
+                  file,
+                  source: sourceLabel,
+                  line: path.node.loc?.start?.line || null,
+                  instance: instanceString,
+                });
+              }
+            }
+          }
+        },
+        TaggedTemplateExpression(path) {
+          const tag = path.node.tag;
+          if (
+            tag.type === "MemberExpression" &&
+            tag.object &&
+            tag.object.name === "styled"
+          ) {
+            const template = path.node.quasi.quasis.map(q => q.value.raw).join("");
+            const regex = /([\w-]+)\s*:\s*([^;]+);?/g;
+            let match;
+            const stylePairs = [];
+            while ((match = regex.exec(template))) {
+              const key = match[1];
+              const value = match[2].trim();
+              stylePairs.push(`${key}: ${value}`);
+            }
+            const instanceString = `styled.div\`\n${template.trim()}\``;
+            let match2;
+            regex.lastIndex = 0;
+            while ((match2 = regex.exec(template))) {
+              const key = match2[1];
+              const value = match2[2].trim();
+              let sourceLabel = detectedSource === "styled-components"
+                ? "styled-components"
+                : detectedSource === "emotion"
+                ? "emotion-template"
+                : "unknown";
+              tokenUsages.push({
+                type: "inline-style",
+                name: key,
+                value,
+                file,
+                source: sourceLabel,
+                line: path.node.loc?.start?.line || null,
+                instance: instanceString,
+              });
+            }
+          }
+        },
+      });
+    } catch (err) {
+      if (DEBUG) console.warn(`⚠️ AST parse failed for ${file}:`, err.message);
+    }
+
+    // Step 4: Detect Tailwind inline overrides in runtime usage
+    // Look for @theme inline { ... } blocks and extract --var-name: value; pairs
+    const themeInlineRegex = /@theme\s+inline\s*{([^}]+)}/g;
+    let themeInlineMatch;
+    while ((themeInlineMatch = themeInlineRegex.exec(content))) {
+      const block = themeInlineMatch[1];
+      const line = content.slice(0, themeInlineMatch.index).split('\n').length;
+      // Find all --var-name: value; inside the block
+      const varDeclRegex = /(--[\w-]+)\s*:\s*([^;]+);/g;
+      let varDeclMatch;
+      while ((varDeclMatch = varDeclRegex.exec(block))) {
+        const varName = varDeclMatch[1];
+        const value = varDeclMatch[2];
+        tokenUsages.push({
+          type: "tailwind-inline",
+          name: varName,
+          value: value.trim(),
+          file,
+          theme: "tailwind-inline",
+          source: "css",
+          line,
+        });
+        if (DEBUG) console.log("🌈 Detected Tailwind inline var:", varName, "in", file);
+      }
+    }
+  }
+
+  const inlineStylesCount = tokenUsages.filter(
+    (t) => t.type === "inline-style"
+  ).length;
+  if (DEBUG) console.log(`✅ Runtime usage tokens detected: ${tokenUsages.length}`);
+  if (DEBUG && tokenUsages.length) {
+    console.log("🧩 Sample runtime usage tokens:", tokenUsages.slice(0, 5));
+  }
+  if (DEBUG) console.log(`🎨 Inline styles detected: ${inlineStylesCount}`);
+  if (DEBUG && inlineStylesCount) {
+    console.log(
+      "🖌️ Sample inline styles:",
+      tokenUsages.filter((t) => t.type === "inline-style").slice(0, 5)
+    );
+  }
+
+  // Return only the raw detections (no enrichment or inference)
+  return tokenUsages;
+}

package/src/utils/detectDeclaredDrift.js

@@ -0,0 +1,59 @@
+export function detectDeclaredDrift(declaredJson, declaredCssVars) {
+  const drifted = [];
+
+  const jsonMap = new Map();
+  for (const t of declaredJson) {
+    jsonMap.set(t.cssVar, t.value);
+  }
+
+  for (const css of declaredCssVars) {
+    if (jsonMap.has(css.cssVar)) {
+      const declaredValue = jsonMap.get(css.cssVar);
+
+      const normalize = (v) =>
+        v
+          ?.trim()
+          .replace(/^var\(/, "")
+          .replace(/\)$/, "")
+          .replace(/^--/, "")
+          .toLowerCase();
+
+      const declaredNorm = normalize(declaredValue);
+      const foundNorm = normalize(css.value);
+      const cssVarNorm = normalize(css.cssVar);
+
+      const isSelfRef = css.value.trim() === `var(${css.cssVar})`;
+      const isIdentical = css.value.trim() === declaredValue.trim();
+      const isAliasSelfRef = foundNorm === declaredNorm || foundNorm === cssVarNorm;
+
+      // Skip if it's a self-reference or points to itself indirectly
+      if (
+        isSelfRef ||
+        isIdentical ||
+        isAliasSelfRef ||
+        css.value.includes(`var(${css.cssVar})`)
+      ) {
+        continue;
+      }
+
+      if (declaredValue !== css.value) {
+        drifted.push({
+          name: css.name,
+          cssVar: css.cssVar,
+          declaredValue,
+          actualValue: css.value,
+          file: css.file,
+          source: css.source,
+          category: css.category,
+          theme: css.theme,
+          isTailwindOverride:
+            css.source === "tailwind" ||
+            (css.category && css.category.startsWith("tailwind")),
+          driftFromDeclared: { declared: declaredValue, actual: css.value },
+        });
+      }
+    }
+  }
+
+  return drifted;
+}

package/src/utils/extractImports.js

@@ -0,0 +1,178 @@
+/**
+ * extractImports.js
+ *
+ * Extract import statements from JavaScript/TypeScript files.
+ * Returns relative paths that the file imports.
+ */
+
+import fs from "fs";
+import path from "path";
+import { IMPORTABLE_EXTENSIONS, RESOLVABLE_EXTENSIONS } from "./fileExtensions.js";
+
+const IMPORT_PATTERNS = [
+  // ES6 imports
+  /import\s+(?:(?:[\w*\s{},]*)\s+from\s+)?['"]([^'"]+)['"]/g,
+  // Dynamic imports
+  /import\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  // CommonJS require
+  /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  // TypeScript type imports
+  /import\s+type\s+(?:[\w*\s{},]*)\s+from\s+['"]([^'"]+)['"]/g,
+];
+
+/**
+ * Extract import paths from file content.
+ * @param {string} content - File content
+ * @returns {string[]} - Array of imported module paths
+ */
+function parseImports(content) {
+  const imports = new Set();
+  
+  for (const pattern of IMPORT_PATTERNS) {
+    const matches = content.matchAll(pattern);
+    for (const match of matches) {
+      const importPath = match[1];
+      // Only include relative imports (exclude node_modules)
+      if (importPath.startsWith('.') || importPath.startsWith('/')) {
+        imports.add(importPath);
+      }
+    }
+  }
+  
+  return Array.from(imports);
+}
+
+/**
+ * Resolve import path to absolute path (optimized with caching).
+ */
+function resolveImportPath(fromFile, importPath, repoRoot, fileSetCache) {
+  const fromDir = path.dirname(fromFile);
+  let resolved = path.resolve(fromDir, importPath);
+  
+  // Check cache first (Set lookup is O(1))
+  const relativeResolved = path.relative(repoRoot, resolved).replace(/\\/g, '/');
+  if (fileSetCache.has(relativeResolved)) {
+    return relativeResolved;
+  }
+  
+  // Try extensions
+  for (const ext of RESOLVABLE_EXTENSIONS) {
+    const candidate = resolved + ext;
+    const relativeCandidate = path.relative(repoRoot, candidate).replace(/\\/g, '/');
+    
+    if (fileSetCache.has(relativeCandidate)) {
+      return relativeCandidate;
+    }
+  }
+  
+  // Try index files in directory (only if directory exists in cache)
+  const relativeDir = path.relative(repoRoot, resolved).replace(/\\/g, '/');
+  for (const ext of ['.js', '.ts', '.jsx', '.tsx']) {
+    const indexPath = `${relativeDir}/index${ext}`;
+    if (fileSetCache.has(indexPath)) {
+      return indexPath;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Extract imports from a file (optimized).
+ */
+export function extractImports(filePath, repoRoot, fileSetCache) {
+  const ext = path.extname(filePath).toLowerCase();
+  
+  if (!IMPORTABLE_EXTENSIONS.includes(ext)) {
+    return [];
+  }
+  
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const importPaths = parseImports(content);
+    
+    // Resolve all import paths using cache
+    const resolved = importPaths
+      .map(imp => resolveImportPath(filePath, imp, repoRoot, fileSetCache))
+      .filter(Boolean);
+    
+    return resolved;
+  } catch (err) {
+    // Don't log every failure, just return empty
+    return [];
+  }
+}
+
+/**
+ * Build bidirectional dependency map for all files (optimized).
+ */
+export function buildDependencyMap(files, repoRoot) {
+  const startTime = Date.now();
+  
+  // Pre-build a Set of all files for O(1) lookups
+  const fileSet = new Set(files.map(f => f.replace(/\\/g, '/')));
+  
+  const depMap = {};
+  
+  // Initialize map
+  for (const file of files) {
+    const normalizedFile = file.replace(/\\/g, '/');
+    depMap[normalizedFile] = { imports: [], imported_by: [] };
+  }
+  
+  // Track stats
+  let processedCount = 0;
+  let skippedCount = 0;
+  let importsFoundCount = 0;
+  
+  // Batch process importable files only
+  const importableFiles = files.filter(file => {
+    const ext = path.extname(file).toLowerCase();
+    return IMPORTABLE_EXTENSIONS.includes(ext);
+  });
+  
+  console.log(`📦 Processing ${importableFiles.length} importable files...`);
+  
+  // Process in batches to show progress
+  const batchSize = 100;
+  for (let i = 0; i < importableFiles.length; i += batchSize) {
+    const batch = importableFiles.slice(i, i + batchSize);
+    
+    for (const file of batch) {
+      const normalizedFile = file.replace(/\\/g, '/');
+      const absolutePath = path.resolve(repoRoot, file);
+      const imports = extractImports(absolutePath, repoRoot, fileSet);
+      
+      if (imports.length > 0) {
+        importsFoundCount++;
+      }
+      processedCount++;
+      
+      depMap[normalizedFile].imports = imports;
+      
+      // Build reverse mapping
+      for (const importedFile of imports) {
+        if (depMap[importedFile]) {
+          if (!depMap[importedFile].imported_by.includes(normalizedFile)) {
+            depMap[importedFile].imported_by.push(normalizedFile);
+          }
+        }
+      }
+    }
+    
+    // Progress indicator
+    if ((i + batchSize) % 500 === 0 || i + batchSize >= importableFiles.length) {
+      const progress = Math.min(i + batchSize, importableFiles.length);
+      console.log(`📦 Progress: ${progress}/${importableFiles.length} files processed`);
+    }
+  }
+  
+  skippedCount = files.length - processedCount;
+  
+  const elapsed = Date.now() - startTime;
+  console.log(`📦 Dependency stats: ${processedCount} importable files, ${importsFoundCount} with imports, ${skippedCount} skipped (${elapsed}ms)`);
+  
+  return depMap;
+}
+
+export default extractImports;

package/src/utils/fileExtensions.js

@@ -0,0 +1,65 @@
+/**
+ * fileExtensions.js
+ *
+ * Shared file extension whitelist used across scanner and dependency extraction.
+ * Ensures consistency in which files are processed.
+ */
+
+export const SCANNABLE_EXTENSIONS = [
+  ".js",
+  ".ts",
+  ".jsx",
+  ".tsx",
+  ".css",
+  ".scss",
+  ".sass",
+  ".less",
+  ".styl",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".html",
+  ".htm",
+  ".mdx",
+  ".md",
+  ".json",
+  ".jsonc",
+  ".yml",
+  ".yaml",
+  ".cjs",
+  ".mjs",
+];
+
+// Files that can contain import statements (JS/TS/framework files + MDX)
+export const IMPORTABLE_EXTENSIONS = [
+  ".js",
+  ".ts",
+  ".jsx",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".mdx", // MDX can have imports
+];
+
+// Extensions to try when resolving import paths
+// (empty string first to handle imports with explicit extensions)
+export const RESOLVABLE_EXTENSIONS = [
+  "",
+  ".js",
+  ".ts",
+  ".jsx",
+  ".tsx",
+  ".mjs",
+  ".cjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".mdx",
+  ".json",
+  ".jsonc",
+];
+
+export default SCANNABLE_EXTENSIONS;