@fairfox/polly 0.23.0 → 0.25.0

package/dist/tools/quality/src/cli.js

@@ -17,6 +17,539 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
+// tools/quality/src/css/shared.ts
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+
+// tools/quality/src/logger.ts
+function defaultLog(message) {
+  console.log(message);
+}
+function defaultError(message) {
+  console.error(message);
+}
+function defaultInfo(message) {
+  console.info(message);
+}
+function defaultWarn(message) {
+  console.warn(message);
+}
+var logger = {
+  log: defaultLog,
+  error: defaultError,
+  info: defaultInfo,
+  warn: defaultWarn
+};
+function resetLogger() {
+  logger.log = defaultLog;
+  logger.error = defaultError;
+  logger.info = defaultInfo;
+  logger.warn = defaultWarn;
+}
+
+// tools/quality/src/css/shared.ts
+var DEFAULT_SKIP_DIRS = ["node_modules", ".git", "dist", "dist-test", "build", "coverage"];
+async function walkDirectory(dir, visit, opts) {
+  const skipDirs = new Set(opts.skipDirs ?? DEFAULT_SKIP_DIRS);
+  const skipFiles = new Set(opts.skipFiles ?? []);
+  const rootDir = opts.rootDir;
+  async function walk(current) {
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name))
+          continue;
+        await walk(full);
+      } else if (entry.isFile()) {
+        if (skipFiles.has(entry.name))
+          continue;
+        const rel = relative(rootDir, full);
+        await visit(full, rel);
+      }
+    }
+  }
+  await walk(dir);
+}
+function formatViolations(kind, violations, rootDir) {
+  const lines = [];
+  if (violations.length === 0) {
+    lines.push(`✅ ${kind}: no violations`);
+    return lines;
+  }
+  lines.push(`❌ ${kind}: ${violations.length} violation(s)`);
+  const byFile = new Map;
+  for (const v of violations) {
+    const bucket = byFile.get(v.file) ?? [];
+    bucket.push(v);
+    byFile.set(v.file, bucket);
+  }
+  for (const [file, fileViolations] of byFile) {
+    lines.push(`  ${relative(rootDir, file)}`);
+    for (const v of fileViolations) {
+      lines.push(`    L${v.line}: ${v.content}`);
+      lines.push(`          → ${v.suggestion} [${v.rule}]`);
+    }
+  }
+  return lines;
+}
+function makeResult(kind, rootDir, violations) {
+  return {
+    violations,
+    print() {
+      for (const line of formatViolations(kind, violations, rootDir)) {
+        if (line.startsWith("❌")) {
+          logger.error(line);
+        } else {
+          logger.log(line);
+        }
+      }
+    }
+  };
+}
+function isInsideComment(line) {
+  const trimmed = line.trim();
+  return trimmed.startsWith("/*") || trimmed.startsWith("*") || trimmed.startsWith("//");
+}
+function isInsideKeyframes(lineNum, allLines) {
+  for (let i = lineNum - 1;i >= 0; i -= 1) {
+    const l = allLines[i]?.trim() ?? "";
+    if (l.startsWith("@keyframes"))
+      return true;
+    if (l === "}" && i < lineNum - 1)
+      return false;
+  }
+  return false;
+}
+
+// tools/quality/src/css/check-layout.ts
+var CSS_PATTERNS = [
+  { pattern: /display\s*:\s*flex/, kind: "display: flex in CSS" },
+  { pattern: /display\s*:\s*grid/, kind: "display: grid in CSS" }
+];
+var TSX_PATTERNS = [
+  {
+    pattern: /display\s*:\s*['"]flex['"]/,
+    kind: "display: flex in inline style"
+  },
+  {
+    pattern: /display\s*:\s*['"]grid['"]/,
+    kind: "display: grid in inline style"
+  }
+];
+var SUPPRESS = "layout-ignore";
+async function checkCssLayout(options) {
+  const rootDir = options.rootDir;
+  const exempt = options.layoutExemptPaths ?? ["Layout.module.css", "Layout.tsx"];
+  const violations = [];
+  await walkDirectory(rootDir, async (full) => {
+    const isCss = full.endsWith(".module.css");
+    const isTsx = full.endsWith(".tsx");
+    if (!isCss && !isTsx)
+      return;
+    if (exempt.some((fragment) => full.includes(fragment)))
+      return;
+    const patterns = isCss ? CSS_PATTERNS : TSX_PATTERNS;
+    const content = await Bun.file(full).text();
+    const lines = content.split(`
+`);
+    for (let i = 0;i < lines.length; i += 1) {
+      const line = lines[i];
+      if (!line)
+        continue;
+      const trimmed = line.trim();
+      if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*"))
+        continue;
+      if (trimmed.includes(SUPPRESS))
+        continue;
+      const prev = i > 0 ? lines[i - 1]?.trim() ?? "" : "";
+      if (prev.includes(SUPPRESS))
+        continue;
+      for (const rule of patterns) {
+        if (rule.pattern.test(line)) {
+          violations.push({
+            file: full,
+            line: i + 1,
+            rule: rule.kind,
+            content: trimmed,
+            suggestion: "Use the <Layout> component instead"
+          });
+          break;
+        }
+      }
+    }
+  }, {
+    rootDir,
+    skipDirs: options.skipDirs
+  });
+  return makeResult("css-layout", rootDir, violations);
+}
+// tools/quality/src/css/check-quality.ts
+var DEFAULT_RULES = [
+  {
+    id: "no-hardcoded-color",
+    check: (line) => {
+      if (isInsideComment(line))
+        return null;
+      if (line.includes("var("))
+        return null;
+      if (/\bcolor:\s*(white|black|#[0-9a-fA-F]{3,8})\b/.test(line)) {
+        return "Use a semantic colour token (--polly-text, --polly-text-muted, …)";
+      }
+      if (/background(-color)?:\s*#[0-9a-fA-F]{3,8}/.test(line) && !line.includes("var(")) {
+        return "Use a semantic surface token (--polly-surface, --polly-surface-raised, …)";
+      }
+      return null;
+    }
+  },
+  {
+    id: "no-hardcoded-rgba",
+    check: (line) => {
+      if (isInsideComment(line))
+        return null;
+      if (!line.includes("rgba("))
+        return null;
+      if (line.includes("var("))
+        return null;
+      if (line.includes("color-mix("))
+        return null;
+      if (/background.*rgba/.test(line)) {
+        return "Use a semantic surface or overlay token";
+      }
+      if (/box-shadow.*rgba/.test(line)) {
+        return "Use a semantic shadow token";
+      }
+      return "Use a semantic token instead of raw rgba()";
+    }
+  },
+  {
+    id: "no-hardcoded-z-index",
+    check: (line) => {
+      const m = line.match(/z-index:\s*(\d+)/);
+      if (!m?.[1])
+        return null;
+      if (line.includes("var("))
+        return null;
+      if (Number.parseInt(m[1], 10) < 10)
+        return null;
+      return "Use a --polly-z-* token";
+    }
+  },
+  {
+    id: "no-hardcoded-opacity",
+    check: (line) => {
+      if (!/opacity:\s*0\.\d/.test(line))
+        return null;
+      if (line.includes("var("))
+        return null;
+      const m = line.match(/opacity:\s*(0\.\d+)/);
+      if (!m?.[1])
+        return null;
+      const v = Number.parseFloat(m[1]);
+      if (v >= 0.5 && v <= 0.7) {
+        return "Use var(--polly-opacity-disabled) for disabled states";
+      }
+      return null;
+    }
+  },
+  {
+    id: "no-hardcoded-transition",
+    check: (line, lineNum, allLines) => {
+      if (isInsideKeyframes(lineNum, allLines))
+        return null;
+      if (line.includes("var(--polly-motion"))
+        return null;
+      if (!/(?:transition|animation)/.test(line))
+        return null;
+      if (/\d+(\.\d+)?(ms|s)\s+(ease|linear|ease-in|ease-out|ease-in-out)/.test(line) && !line.includes("infinite")) {
+        return "Use var(--polly-motion-fast|base|slow)";
+      }
+      if (/\s\d+(\.\d+)?s[;\s,]/.test(line) && !line.includes("infinite")) {
+        return "Use var(--polly-motion-fast|base|slow)";
+      }
+      return null;
+    }
+  },
+  {
+    id: "no-important",
+    check: (line) => {
+      if (isInsideComment(line))
+        return null;
+      if (!line.includes("!important"))
+        return null;
+      return "Refactor specificity instead of using !important";
+    }
+  },
+  {
+    id: "no-rem-units",
+    check: (line, lineNum, allLines) => {
+      if (isInsideComment(line))
+        return null;
+      if (isInsideKeyframes(lineNum, allLines))
+        return null;
+      if (/:\s*[^;]*\d+(\.\d+)?rem[;\s]/.test(line)) {
+        if (line.includes("calc(") || line.includes("translateY(")) {
+          return null;
+        }
+        return "Use --polly-space-* or --polly-text-* tokens instead of rem";
+      }
+      return null;
+    }
+  },
+  {
+    id: "no-hardcoded-border-width",
+    check: (line) => {
+      if (isInsideComment(line))
+        return null;
+      if (line.includes("var(--polly-border-width"))
+        return null;
+      const m = line.match(/border(?:-(?:top|right|bottom|left))?:\s*(\d+)px\s+solid/);
+      if (!m?.[1])
+        return null;
+      return "Use a --polly-border-width-* token";
+    }
+  },
+  {
+    id: "no-hardcoded-border-radius",
+    check: (line) => {
+      if (isInsideComment(line))
+        return null;
+      if (line.includes("var("))
+        return null;
+      const m = line.match(/border-radius:\s*(\d+)px/);
+      if (!m?.[1])
+        return null;
+      if (m[1] === "0")
+        return null;
+      return "Use a --polly-radius-{sm,md,lg} token";
+    }
+  },
+  {
+    id: "no-hardcoded-box-shadow",
+    check: (line) => {
+      if (isInsideComment(line))
+        return null;
+      if (!line.includes("box-shadow:"))
+        return null;
+      if (line.includes("var(--polly-shadow"))
+        return null;
+      if (line.includes("var(--polly-focus-ring"))
+        return null;
+      if (line.includes("var("))
+        return null;
+      if (/box-shadow:\s*none/.test(line))
+        return null;
+      return "Use var(--polly-shadow-*) or var(--polly-focus-ring)";
+    }
+  },
+  {
+    id: "no-hardcoded-font-weight",
+    check: (line) => {
+      if (!/font-weight:\s*\d{3}/.test(line))
+        return null;
+      if (line.includes("var("))
+        return null;
+      return "Use var(--polly-weight-normal|medium|bold)";
+    }
+  }
+];
+async function checkCssQuality(options) {
+  const rootDir = options.rootDir;
+  const extensions = options.extensions ?? [".module.css"];
+  const skipFiles = options.skipFiles ?? ["theme.css", "tokens.css"];
+  const disabled = new Set(options.disableRules ?? []);
+  const rules = DEFAULT_RULES.filter((r) => !disabled.has(r.id));
+  const violations = [];
+  await walkDirectory(rootDir, async (full) => {
+    if (!extensions.some((ext) => full.endsWith(ext)))
+      return;
+    const content = await Bun.file(full).text();
+    const lines = content.split(`
+`);
+    const hasFileIgnore = lines[0]?.includes("polly-ignore-all");
+    if (hasFileIgnore)
+      return;
+    for (let i = 0;i < lines.length; i += 1) {
+      const line = lines[i];
+      if (!line)
+        continue;
+      const trimmed = line.trim();
+      if (trimmed === "" || trimmed === "{" || trimmed === "}")
+        continue;
+      for (const rule of rules) {
+        const suggestion = rule.check(line, i, lines);
+        if (suggestion) {
+          violations.push({
+            file: full,
+            line: i + 1,
+            rule: rule.id,
+            content: trimmed,
+            suggestion
+          });
+        }
+      }
+    }
+  }, {
+    rootDir,
+    skipDirs: options.skipDirs,
+    skipFiles
+  });
+  return makeResult("css-quality", rootDir, violations);
+}
+// tools/quality/src/css/check-unused.ts
+async function checkCssUnused(options) {
+  const rootDir = options.rootDir;
+  const alwaysUsed = new Set(options.alwaysUsedClasses ?? []);
+  const definitions = [];
+  const tsContents = [];
+  const cssContents = [];
+  await walkDirectory(rootDir, async (full) => {
+    if (full.endsWith(".module.css")) {
+      const content = await Bun.file(full).text();
+      const lines = content.split(`
+`);
+      for (let i = 0;i < lines.length; i += 1) {
+        const line = lines[i];
+        if (!line)
+          continue;
+        for (const m of line.matchAll(/(?:^|[\s,>+~])\.([\w-]+)/g)) {
+          if (m[1]) {
+            definitions.push({
+              file: full,
+              name: m[1],
+              line: i + 1,
+              type: "class"
+            });
+          }
+        }
+        for (const m of line.matchAll(/^\s+--([\w-]+)\s*:/g)) {
+          if (m[1]) {
+            definitions.push({
+              file: full,
+              name: `--${m[1]}`,
+              line: i + 1,
+              type: "variable"
+            });
+          }
+        }
+      }
+      cssContents.push({ file: full, content });
+    } else if (full.endsWith(".css") && !full.endsWith(".css.d.ts")) {
+      const content = await Bun.file(full).text();
+      cssContents.push({ file: full, content });
+    } else if ((full.endsWith(".ts") || full.endsWith(".tsx")) && !full.endsWith(".css.d.ts")) {
+      const content = await Bun.file(full).text();
+      tsContents.push({ file: full, content });
+    }
+  }, { rootDir, skipDirs: options.skipDirs });
+  const seen = new Set;
+  const uniqueDefs = definitions.filter((d) => {
+    const key = `${d.file}:${d.type}:${d.name}`;
+    if (seen.has(key))
+      return false;
+    seen.add(key);
+    return true;
+  });
+  function classReferenced(name) {
+    if (alwaysUsed.has(name))
+      return true;
+    for (const { content } of tsContents) {
+      if (content.includes(`.${name}`) || content.includes(`['${name}']`) || content.includes(`["${name}"]`)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  function variableReferenced(name, defFile) {
+    for (const { file, content } of cssContents) {
+      if (file === defFile)
+        continue;
+      if (content.includes(`var(${name})`))
+        return true;
+    }
+    const self = cssContents.find((f) => f.file === defFile);
+    if (self) {
+      const occurrences = self.content.split(name).length - 1;
+      if (occurrences > 1)
+        return true;
+    }
+    for (const { content } of tsContents) {
+      if (content.includes(name))
+        return true;
+    }
+    return false;
+  }
+  const violations = [];
+  for (const def of uniqueDefs) {
+    if (def.type === "class" && !classReferenced(def.name)) {
+      violations.push({
+        file: def.file,
+        line: def.line,
+        rule: "unused-class",
+        content: `.${def.name}`,
+        suggestion: "Delete the selector or reference the class from a component"
+      });
+    } else if (def.type === "variable" && !variableReferenced(def.name, def.file)) {
+      violations.push({
+        file: def.file,
+        line: def.line,
+        rule: "unused-variable",
+        content: def.name,
+        suggestion: "Delete the definition or reference the variable"
+      });
+    }
+  }
+  return makeResult("css-unused (advisory)", rootDir, violations);
+}
+// tools/quality/src/css/check-vars.ts
+async function checkCssVars(options) {
+  const rootDir = options.rootDir;
+  const scanExts = options.scanExtensions ?? [".ts", ".tsx", ".css"];
+  const dynamic = new Set(options.dynamicVars ?? []);
+  const definitions = new Set(dynamic);
+  const violations = [];
+  await walkDirectory(rootDir, async (full) => {
+    if (!full.endsWith(".css"))
+      return;
+    const content = await Bun.file(full).text();
+    for (const m of content.matchAll(/--([\w-]+)\s*:/g)) {
+      if (m[1])
+        definitions.add(`--${m[1]}`);
+    }
+  }, { rootDir, skipDirs: options.skipDirs });
+  await walkDirectory(rootDir, async (full) => {
+    if (full.endsWith(".css.d.ts"))
+      return;
+    if (!scanExts.some((ext) => full.endsWith(ext)))
+      return;
+    const content = await Bun.file(full).text();
+    const lines = content.split(`
+`);
+    for (let i = 0;i < lines.length; i += 1) {
+      const line = lines[i];
+      if (!line)
+        continue;
+      for (const m of line.matchAll(/var\(--([\w-]+)\)/g)) {
+        const name = `--${m[1]}`;
+        if (!definitions.has(name)) {
+          violations.push({
+            file: full,
+            line: i + 1,
+            rule: "undefined-var",
+            content: line.trim(),
+            suggestion: `Define ${name} in a CSS file or add to dynamicVars`
+          });
+        }
+      }
+    }
+  }, { rootDir, skipDirs: options.skipDirs });
+  return makeResult("css-vars", rootDir, violations);
+}
 // tools/quality/src/no-as-casting.ts
 import { readFileSync } from "node:fs";
 import { Glob } from "bun";
@@ -121,24 +654,31 @@ function suggestFix(line) {
   }
   return;
 }
-function isFileExcluded(relative, excludeDirs, excludePackages, excludeFiles) {
-  const segments = relative.split("/");
+function isFileExcluded(relative2, excludeDirs, excludePackages, excludeFiles) {
+  const segments = relative2.split("/");
   if (segments.some((s) => excludeDirs.has(s)))
     return true;
   if (excludePackages.size > 0 && segments.some((s) => excludePackages.has(s)))
     return true;
   const basename = segments[segments.length - 1] ?? "";
-  return excludeFiles.has(basename) || excludeFiles.has(relative);
+  return excludeFiles.has(basename) || excludeFiles.has(relative2);
 }
-function findViolations(relative, content) {
+function findViolations(relative2, content) {
   const results = [];
   const lines = content.split(`
 `);
+  let insideTemplate = false;
   for (let i = 0;i < lines.length; i++) {
     const line = lines[i] ?? "";
+    const backticks = (line.match(/`/g) ?? []).length;
+    const startedInTemplate = insideTemplate;
+    if (backticks % 2 === 1)
+      insideTemplate = !insideTemplate;
+    if (startedInTemplate && backticks === 0 && !line.includes("${"))
+      continue;
     if (!isLineClean(line)) {
       results.push({
-        file: relative,
+        file: relative2,
         line: i + 1,
         content: line.trim(),
         advice: suggestFix(line.trim())
@@ -149,20 +689,20 @@ function findViolations(relative, content) {
 }
 function printViolations(violations) {
   if (violations.length === 0) {
-    console.log("[no-as-casting] ✅ No violations found.");
+    logger.log("[no-as-casting] ✅ No violations found.");
     return;
   }
-  console.log(`[no-as-casting] ❌ ${violations.length} violation(s) found:
+  logger.log(`[no-as-casting] ❌ ${violations.length} violation(s) found:
 `);
   for (const v of violations) {
-    console.log(`  ${v.file}:${v.line}`);
-    console.log(`    ${v.content}`);
+    logger.log(`  ${v.file}:${v.line}`);
+    logger.log(`    ${v.content}`);
     if (v.advice)
-      console.log(`    \uD83D\uDCA1 ${v.advice}`);
-    console.log();
+      logger.log(`    \uD83D\uDCA1 ${v.advice}`);
+    logger.log("");
   }
-  console.log("[no-as-casting] Use type guards, validation, or fix the types at the source.");
-  console.log('[no-as-casting] Only "as const" and "as unknown as" are allowed.');
+  logger.log("[no-as-casting] Use type guards, validation, or fix the types at the source.");
+  logger.log('[no-as-casting] Only "as const" and "as unknown as" are allowed.');
 }
 async function checkNoAsCasting(options) {
   const rootDir = options.rootDir;
@@ -173,34 +713,113 @@ async function checkNoAsCasting(options) {
   const glob = new Glob(pattern);
   const violations = [];
   for await (const file of glob.scan({ cwd: rootDir, absolute: true })) {
-    const relative = file.replace(`${rootDir}/`, "");
-    if (isFileExcluded(relative, excludeDirs, excludePackages, excludeFiles))
+    const relative2 = file.replace(`${rootDir}/`, "");
+    if (isFileExcluded(relative2, excludeDirs, excludePackages, excludeFiles))
       continue;
     const content = readFileSync(file, "utf-8");
-    violations.push(...findViolations(relative, content));
+    violations.push(...findViolations(relative2, content));
   }
   return { violations, print: () => printViolations(violations) };
 }
-
 // tools/quality/src/cli.ts
 var args = process.argv.slice(2);
 function getFlag(name) {
   const idx = args.indexOf(`--${name}`);
   return idx >= 0 ? args[idx + 1] : undefined;
 }
+function getSubcommand() {
+  for (const arg of args) {
+    if (!arg.startsWith("--"))
+      return arg;
+  }
+  return "all";
+}
+var subcommand = getSubcommand();
 var rootDir = getFlag("root") ?? process.cwd();
-var exclude = getFlag("exclude")?.split(",") ?? ["node_modules", "dist", ".git", ".bun"];
+var exclude = getFlag("exclude")?.split(",") ?? [
+  "node_modules",
+  "dist",
+  ".git",
+  ".bun",
+  "dist-test",
+  "build",
+  "coverage"
+];
 var excludePackages = getFlag("exclude-packages")?.split(",");
 var excludeFiles = getFlag("exclude-files")?.split(",");
 var filePatterns = getFlag("pattern");
-var result = await checkNoAsCasting({
-  rootDir,
-  exclude,
-  ...excludePackages ? { excludePackages } : {},
-  ...excludeFiles ? { excludeFiles } : {},
-  ...filePatterns ? { filePatterns } : {}
-});
-result.print();
-process.exit(result.violations.length > 0 ? 1 : 0);
+async function runNoAsCasting() {
+  const result = await checkNoAsCasting({
+    rootDir,
+    exclude,
+    ...excludePackages ? { excludePackages } : {},
+    ...excludeFiles ? { excludeFiles } : {},
+    ...filePatterns ? { filePatterns } : {}
+  });
+  result.print();
+  return result.violations.length > 0 ? 1 : 0;
+}
+async function runCssQuality() {
+  const r = await checkCssQuality({ rootDir, skipDirs: exclude });
+  r.print();
+  return r.violations.length > 0 ? 1 : 0;
+}
+async function runCssLayout() {
+  const r = await checkCssLayout({ rootDir, skipDirs: exclude });
+  r.print();
+  return r.violations.length > 0 ? 1 : 0;
+}
+async function runCssVars() {
+  const r = await checkCssVars({ rootDir, skipDirs: exclude });
+  r.print();
+  return r.violations.length > 0 ? 1 : 0;
+}
+async function runCssUnused() {
+  const r = await checkCssUnused({ rootDir, skipDirs: exclude });
+  r.print();
+  return 0;
+}
+async function runCssAll() {
+  const results = [
+    await runCssQuality(),
+    await runCssLayout(),
+    await runCssVars(),
+    await runCssUnused()
+  ];
+  return results.some((code) => code !== 0) ? 1 : 0;
+}
+async function runAll() {
+  const results = [await runNoAsCasting(), await runCssAll()];
+  return results.some((code) => code !== 0) ? 1 : 0;
+}
+var exitCode = 0;
+switch (subcommand) {
+  case "no-as-casting":
+    exitCode = await runNoAsCasting();
+    break;
+  case "css":
+    exitCode = await runCssAll();
+    break;
+  case "css-quality":
+    exitCode = await runCssQuality();
+    break;
+  case "css-layout":
+    exitCode = await runCssLayout();
+    break;
+  case "css-vars":
+    exitCode = await runCssVars();
+    break;
+  case "css-unused":
+    exitCode = await runCssUnused();
+    break;
+  case "all":
+    exitCode = await runAll();
+    break;
+  default:
+    logger.error(`Unknown quality subcommand: ${subcommand}`);
+    logger.error("Expected one of: no-as-casting, css, css-quality, css-layout, css-vars, css-unused");
+    exitCode = 2;
+}
+process.exit(exitCode);
 
-//# debugId=E6501402C1BD2E6764756E2164756E21
+//# debugId=33FEF60F0C8A440B64756E2164756E21