@controlfront/detect 0.0.1

package/src/engine/runRules.js

@@ -0,0 +1,210 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+import { createGetLine } from "../utils/getLine.js";
+
+// Resolve paths relative to the installed package location, not CWD
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, ".."); // engine/.. = package src root (or dist root)
+
+// Built-in rules shipped with the package
+const coreRulesDir = path.join(PKG_ROOT, "rules", "core");
+
+
+const ruleSet = [];
+
+async function loadRulesFromDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter(
+    f => /\.(?:m?js|cjs)$/.test(f) && !/^index\.(?:m?js|cjs)$/.test(f)
+  );
+  const loaded = await Promise.all(
+    files.map(async file => {
+      const rulePath = path.join(dir, file);
+      const mod = await import(pathToFileURL(rulePath).href);
+      // Accept: export const rule = {...}, export default {...}, CJS default/shape, or an array of rules
+      const candidate =
+        mod.rule ||
+        (mod.default && (mod.default.rule || mod.default)) ||
+        mod.default ||
+        mod;
+
+      const asArray = Array.isArray(candidate)
+        ? candidate
+        : Array.isArray(candidate?.rules)
+        ? candidate.rules
+        : null;
+
+      const toValidate = asArray ?? [candidate?.rule ?? candidate];
+
+      const valid = toValidate.filter(
+        r => r && typeof r.evaluate === "function" && r.meta && typeof r.meta.slug === "string"
+      );
+
+      if (valid.length === 0) {
+        // Skip non-rule files (e.g., index.js barrels)
+        return null;
+      }
+      // Ensure each rule has meta fields and annotate origin for debugging
+      const withMeta = valid.map((r) => {
+        if (!r.meta) r.meta = {};
+        if (!r.meta.slug) {
+          const base = path.basename(file, path.extname(file));
+          r.meta.slug = base;
+        }
+        if (!r.meta.name) {
+          r.meta.name = r.meta.slug;
+        }
+        if (!r.meta.severity) {
+          r.meta.severity = "error"; // default
+        }
+        r.__origin = rulePath;
+        return r;
+      });
+      return withMeta;
+    })
+  );
+  return loaded.flat().filter(Boolean);
+}
+
+async function loadAllRules() {
+  const rules = await loadRulesFromDir(coreRulesDir);
+  ruleSet.length = 0;
+  ruleSet.push(...rules);
+}
+
+export async function getCoreRules() {
+  // If someone imports this module before top-level await runs (edge case), ensure rules are loaded
+  if (!ruleSet || ruleSet.length === 0) {
+    await loadAllRules();
+  }
+  // Return a shallow copy to avoid accidental mutation by callers
+  return [...ruleSet];
+}
+
+function buildStyleFocusedContent(filePath, content) {
+  const ext = path.extname(filePath).toLowerCase();
+  const templateLike = new Set([".vue", ".svelte", ".astro", ".html", ".htm", ".mdx"]);
+  if (!templateLike.has(ext)) return content;
+
+  const lines = content.split("\n");
+  let inStyle = false;
+  const out = new Array(lines.length);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const startIdx = line.indexOf("<style");
+    const endIdx = line.indexOf("</style>");
+
+    // Entering a <style> block (can be same line)
+    if (startIdx !== -1) inStyle = true;
+
+    const keep = inStyle || /style\s*=/.test(line);
+
+    out[i] = keep ? line : "";
+
+    // Exiting a </style> block (can be same line)
+    if (endIdx !== -1) inStyle = false;
+  }
+
+  return out.join("\n");
+}
+
+function ensureCIShape(v, rule, file, getLine, getContextForLine) {
+  const line =
+    v.line != null
+      ? v.line
+      : getLine(typeof v.index === "number" ? v.index : 0);
+  const severity =
+    v.severity ||
+    (v.ctx && v.ctx.config && v.ctx.config.severity) ||
+    rule.meta?.severity ||
+    "error";
+  const codeContext =
+    v.codeContext != null ? v.codeContext : getContextForLine(line);
+  return {
+    rule: v.rule || rule.meta?.slug,
+    message: v.message || "",
+    severity,
+    file: v.file || file,
+    line,
+    codeContext,
+  };
+}
+
+export async function runRules(filePaths, config) {
+  if (config && Array.isArray(config.ruleDirs) && config.ruleDirs.length > 0) {
+    const loadedRulesArrays = await Promise.all(
+      config.ruleDirs.map(dir => loadRulesFromDir(dir))
+    );
+    ruleSet.length = 0;
+    for (const arr of loadedRulesArrays) {
+      ruleSet.push(...arr);
+    }
+  } else {
+    if (!ruleSet || ruleSet.length === 0) {
+      await loadAllRules();
+    }
+  }
+  const allViolations = [];
+  const appliedRules = [];
+
+  for (const filePath of filePaths) {
+    const content = fs.readFileSync(filePath, "utf8");
+    const lines = content.split("\n");
+    const effectiveContent = buildStyleFocusedContent(filePath, content);
+
+    const getLine = createGetLine(content);
+
+    const getContextForLine = (lineNumber) => {
+      const windowLines = [
+        lines[lineNumber - 3] || "",
+        lines[lineNumber - 2] || "",
+        lines[lineNumber - 1] || "",
+        lines[lineNumber] || "",
+        lines[lineNumber + 1] || ""
+      ];
+      return windowLines.map(line => line.trimEnd()).join("\n").trim();
+    };
+
+    for (const rule of ruleSet) {
+      const bucket = [];
+      const relativePath = path.relative(process.cwd(), filePath).replace(/\\/g, "/");
+      const ctx = {
+        config,
+        report(v) {
+          bucket.push(ensureCIShape(v, rule, relativePath, getLine, getContextForLine));
+        },
+        getLine,
+      };
+      if (typeof rule.evaluate === "function") {
+        const res = rule.evaluate(relativePath, effectiveContent, ctx);
+        if (res && typeof res.then === "function") {
+          // eslint-disable-next-line no-await-in-loop
+          await res; // allow async evaluate()
+        } else if (Array.isArray(res)) {
+          for (const v of res) ctx.report(v);
+        }
+      }
+      allViolations.push(...bucket);
+
+      appliedRules.push({
+        slug: rule.meta?.slug || "unknown-rule",
+        name: rule.meta?.name || "Unknown Rule",
+        description: rule.meta?.description || "",
+        severity: rule.meta?.severity || "unspecified",
+      });
+    }
+  }
+
+  const uniqueAppliedRules = [];
+  const seenSlugs = new Set();
+  for (const rule of appliedRules) {
+    if (!seenSlugs.has(rule.slug)) {
+      seenSlugs.add(rule.slug);
+      uniqueAppliedRules.push(rule);
+    }
+  }
+
+  return { violations: allViolations, appliedRules: uniqueAppliedRules };
+}

package/src/lib/collectDeclaredTokensAuto.js

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Recursively searches the project for JSON files that appear to contain declared design tokens
+ * (based on the presence of $value, value, $type, or type fields).
+ * Returns a merged object of all detected token files keyed by relative file path.
+ */
+function looksLikeTokenFile(json) {
+  if (!json || typeof json !== "object") return false;
+  const str = JSON.stringify(json);
+  return (
+    str.includes('"$value"') ||
+    str.includes('"value"') ||
+    str.includes('"$type"') ||
+    str.includes('"type"')
+  );
+}
+
+export function collectDeclaredTokensAuto(projectRoot) {
+  const declaredFiles = [];
+
+  function walk(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const e of entries) {
+      const fullPath = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+        walk(fullPath);
+      } else if (e.isFile() && e.name.endsWith(".json")) {
+        if (
+          e.name === "scan-report.json" ||
+          e.name === "cf-violations.json" ||
+          fullPath.includes(`${path.sep}.cf${path.sep}`)
+        ) {
+          continue;
+        }
+        try {
+          const raw = fs.readFileSync(fullPath, "utf8");
+          const parsed = JSON.parse(raw);
+          if (looksLikeTokenFile(parsed)) {
+            declaredFiles.push(fullPath);
+          }
+        } catch {
+          // ignore unreadable or invalid JSON files
+        }
+      }
+    }
+  }
+
+  walk(projectRoot);
+
+  if (declaredFiles.length === 0) return null;
+
+  const result = {};
+  for (const file of declaredFiles) {
+    try {
+      result[path.relative(projectRoot, file)] = JSON.parse(
+        fs.readFileSync(file, "utf8")
+      );
+    } catch {
+      // skip broken files
+    }
+  }
+
+  return result;
+}

package/src/lib/collectTokenMatches.js

@@ -0,0 +1,330 @@
+import * as babelParser from "@babel/parser";
+import traverseModule from "@babel/traverse";
+import postcss from "postcss";
+import safeParser from "postcss-safe-parser";
+
+const traverse = traverseModule.default;
+
+function isCssVarUsage(value) {
+  return value.includes("var(--");
+}
+
+function extractCssVars(value) {
+  return (value.match(/var\((--[a-zA-Z0-9-_]+)\)/g) || []);
+}
+
+function isColorValue(value) {
+  return /#([0-9a-f]{3,8})\b|oklch\(|hsl\(|rgb\(/i.test(value);
+}
+
+function isLengthValue(value) {
+  return /\b\d+(px|rem|em|%)\b/.test(value);
+}
+
+function extractClassesFromNode(node, filePath) {
+  if (!node) return [];
+
+  switch (node.type) {
+    case "StringLiteral":
+      return node.value.split(/\s+/).filter(Boolean);
+
+    case "TemplateLiteral":
+      {
+        let combined = "";
+        for (let i = 0; i < node.quasis.length; i++) {
+          combined += node.quasis[i].value.cooked;
+          if (i < node.expressions.length) {
+            combined += "${expr}";
+          }
+        }
+        return combined.split(/\s+/).filter(Boolean);
+      }
+
+    case "ArrayExpression":
+      {
+        return node.elements.flatMap((el) => extractClassesFromNode(el, filePath));
+      }
+
+    case "ObjectExpression":
+      {
+        const classes = [];
+        node.properties.forEach((prop) => {
+          if (prop.key) {
+            const line = prop.loc?.start.line || node.loc?.start.line || null;
+            if (prop.key.type === "StringLiteral") {
+              const keyValue = prop.key.value;
+              console.log("DEBUG cn() object key encountered:", keyValue, "at", filePath);
+              if (
+                (prop.value.type === "BooleanLiteral" && prop.value.value === true) ||
+                prop.value.type === "Identifier"
+              ) {
+                classes.push(...keyValue.split(/\s+/).filter(Boolean));
+              }
+            } else if (prop.key.type === "TemplateLiteral") {
+              const text = prop.key.quasis.map(q => q.value.cooked).join("");
+              console.log("DEBUG cn() object key encountered:", text, "at", filePath);
+              classes.push(...text.split(/\s+/).filter(Boolean));
+            } else if (prop.key.type === "Identifier") {
+              const keyValue = prop.key.name;
+              console.log("DEBUG cn() object key encountered:", keyValue, "at", filePath);
+              classes.push(...keyValue.split(/\s+/).filter(Boolean));
+            }
+          }
+        });
+        return classes;
+      }
+
+    case "Identifier":
+      return [node.name];
+
+    case "ConditionalExpression":
+      return [
+        ...extractClassesFromNode(node.consequent, filePath),
+        ...extractClassesFromNode(node.alternate, filePath),
+      ];
+
+    default:
+      return [];
+  }
+}
+
+export function collectTokenMatches(filePath, content) {
+  const matches = [];
+  console.log("DEBUG collectTokenMatches running for", filePath);
+
+  //
+  // --- AST: Tailwind class detection (cn, classnames, clsx)
+  //
+  if (filePath.endsWith(".js") || filePath.endsWith(".jsx") || filePath.endsWith(".ts") || filePath.endsWith(".tsx")) {
+    try {
+      const ast = babelParser.parse(content, {
+        sourceType: "module",
+        plugins: ["jsx", "typescript"],
+      });
+
+      traverse(ast, {
+        CallExpression(path) {
+          const callee = path.node.callee;
+          if (
+            callee.type === "Identifier" &&
+            ["cn", "classnames", "clsx"].includes(callee.name)
+          ) {
+            path.node.arguments.forEach((arg) => {
+              const line = arg.loc?.start.line || path.node.loc?.start.line || null;
+              extractClassesFromNode(arg, filePath).forEach((cls) => {
+                if (cls) {
+                  const normalized = cls; // (normalization would happen later)
+                  console.log("DEBUG normalizeToken input:", cls, "=>", normalized);
+                  matches.push({
+                    file: filePath,
+                    raw: cls,
+                    value: normalized,
+                    category: "tailwind-class",
+                    source: "inferred",
+                    line,
+                  });
+                }
+              });
+            });
+          }
+        },
+        JSXAttribute(path) {
+          if (path.node.name.name === "className") {
+            const value = path.node.value;
+            if (!value) return;
+            if (value.type === "StringLiteral") {
+              const line = value.loc?.start.line || path.node.loc?.start.line || null;
+              extractClassesFromNode(value, filePath).forEach((cls) => {
+                if (cls) {
+                  const normalized = cls; // (normalization would happen later)
+                  console.log("DEBUG normalizeToken input:", cls, "=>", normalized);
+                  matches.push({
+                    file: filePath,
+                    raw: cls,
+                    value: normalized,
+                    category: "tailwind-class",
+                    source: "inferred",
+                    line,
+                  });
+                }
+              });
+            } else if (value.type === "JSXExpressionContainer") {
+              const expr = value.expression;
+              if (!expr) return;
+              const line = expr.loc?.start.line || path.node.loc?.start.line || null;
+              extractClassesFromNode(expr, filePath).forEach((cls) => {
+                if (cls) {
+                  const normalized = cls; // (normalization would happen later)
+                  console.log("DEBUG normalizeToken input:", cls, "=>", normalized);
+                  matches.push({
+                    file: filePath,
+                    raw: cls,
+                    value: normalized,
+                    category: "tailwind-class",
+                    source: "inferred",
+                    line,
+                  });
+                }
+              });
+            }
+          }
+        },
+        TaggedTemplateExpression(path) {
+          const tag = path.node.tag;
+
+          // Check if tag is styled.* or styled(...) or css
+          let isStyled = false;
+          if (tag.type === "MemberExpression" && tag.object.name === "styled") {
+            isStyled = true;
+          } else if (tag.type === "CallExpression" && tag.callee.name === "styled") {
+            isStyled = true;
+          } else if (tag.type === "Identifier" && tag.name === "css") {
+            isStyled = true;
+          }
+
+          if (!isStyled) return;
+
+          const quasi = path.node.quasi;
+          quasi.quasis.forEach((templateElement) => {
+            const cssText = templateElement.value.cooked;
+            if (!cssText) return;
+
+            const line = templateElement.loc?.start.line || path.node.loc?.start.line || null;
+
+            try {
+              const root = postcss().process(cssText, { parser: safeParser }).root;
+
+              root.walkDecls((decl) => {
+                // CSS variable declarations
+                if (decl.prop.startsWith("--")) {
+                  const selector = decl.parent?.selector || null;
+                  matches.push({
+                    file: filePath,
+                    raw: `${decl.prop}: ${decl.value}`,
+                    value: decl.value,
+                    category: "css-var-decl",
+                    source: "explicit",
+                    line,
+                    context: selector,
+                  });
+                }
+
+                // CSS variable usage
+                if (isCssVarUsage(decl.value)) {
+                  const varMatches = extractCssVars(decl.value);
+                  varMatches.forEach((vm) => {
+                    matches.push({
+                      file: filePath,
+                      raw: vm,
+                      value: vm,
+                      category: "css-var",
+                      source: "explicit",
+                      line,
+                    });
+                  });
+                }
+
+                // Hardcoded colors
+                if (isColorValue(decl.value)) {
+                  matches.push({
+                    file: filePath,
+                    raw: decl.value,
+                    value: decl.value,
+                    category: "color",
+                    source: "explicit",
+                    line,
+                  });
+                }
+
+                // Hardcoded spacing
+                if (isLengthValue(decl.value)) {
+                  matches.push({
+                    file: filePath,
+                    raw: decl.value,
+                    value: decl.value,
+                    category: "length",
+                    source: "explicit",
+                    line,
+                  });
+                }
+              });
+            } catch (err) {
+              console.warn("PostCSS parse failed for styled template in", filePath, err.message);
+            }
+          });
+        },
+      });
+    } catch (err) {
+      console.warn("AST parse failed for", filePath, err.message);
+    }
+  }
+
+  //
+  // --- PostCSS: CSS parsing (variables, colors, spacing)
+  //
+  if (filePath.endsWith(".css") || filePath.endsWith(".scss")) {
+    try {
+      const root = postcss().process(content, { parser: safeParser }).root;
+
+      root.walkDecls((decl) => {
+        const line = decl.source?.start?.line || null;
+        // CSS variable declarations
+        if (decl.prop.startsWith("--")) {
+          const selector = decl.parent?.selector || null;
+          matches.push({
+            file: filePath,
+            raw: `${decl.prop}: ${decl.value}`,
+            value: decl.value,
+            category: "css-var-decl",
+            source: "explicit",
+            line,
+            context: selector,
+          });
+        }
+
+        // CSS variable usage
+        if (isCssVarUsage(decl.value)) {
+          const varMatches = extractCssVars(decl.value);
+          varMatches.forEach((vm) => {
+            matches.push({
+              file: filePath,
+              raw: vm,
+              value: vm,
+              category: "css-var",
+              source: "explicit",
+              line,
+            });
+          });
+        }
+
+        // Hardcoded colors
+        if (isColorValue(decl.value)) {
+          matches.push({
+            file: filePath,
+            raw: decl.value,
+            value: decl.value,
+            category: "color",
+            source: "explicit",
+            line,
+          });
+        }
+
+        // Hardcoded spacing
+        if (isLengthValue(decl.value)) {
+          matches.push({
+            file: filePath,
+            raw: decl.value,
+            value: decl.value,
+            category: "length",
+            source: "explicit",
+            line,
+          });
+        }
+      });
+    } catch (err) {
+      console.warn("PostCSS parse failed for", filePath, err.message);
+    }
+  }
+
+  return matches;
+}