@decocms/blocks-cli 7.20.10 → 7.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.20.10",
+  "version": "7.21.1",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -30,7 +30,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.20.10",
+    "@decocms/blocks": "7.21.1",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/migrate/analyzers/tailwind-config.test.ts

@@ -0,0 +1,149 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { extractTailwindConfig } from "./tailwind-config";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "tw-config-test-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function writeConfig(content: string) {
+  fs.writeFileSync(path.join(tmpDir, "tailwind.config.ts"), content, "utf-8");
+}
+
+describe("extractTailwindConfig", () => {
+  it("returns an empty extract when no config file exists", () => {
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.colors).toEqual({});
+    expect(result.reviewItems).toEqual([]);
+  });
+
+  it("maps a DEFAULT sub-key to the bare parent color, not a literal -DEFAULT suffix", () => {
+    writeConfig(`
+      export default {
+        theme: {
+          extend: {
+            colors: {
+              primary: {
+                DEFAULT: "#112233",
+                500: "#445566",
+              },
+            },
+          },
+        },
+      };
+    `);
+
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.colors).toEqual({
+      primary: "#112233",
+      "primary-500": "#445566",
+    });
+    expect(result.colors["primary-DEFAULT"]).toBeUndefined();
+  });
+
+  it("flattens nested theme.extend.colors into dash-joined tokens", () => {
+    writeConfig(`
+      export default {
+        theme: {
+          extend: {
+            colors: {
+              perola: "#F5F0E8",
+              brand: {
+                100: "#FFEFEF",
+                500: "#B10200",
+              },
+            },
+          },
+        },
+      };
+    `);
+
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.colors).toEqual({
+      perola: "#F5F0E8",
+      "brand-100": "#FFEFEF",
+      "brand-500": "#B10200",
+    });
+    expect(result.reviewItems).toEqual([]);
+  });
+
+  it("joins fontFamily array literals with a comma", () => {
+    writeConfig(`
+      export default {
+        theme: {
+          extend: {
+            fontFamily: {
+              sans: ["Bebas Neue", "sans-serif"],
+            },
+          },
+        },
+      };
+    `);
+
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.fontFamily.sans).toBe("Bebas Neue, sans-serif");
+  });
+
+  it("splits safelist into literal strings and regex patterns", () => {
+    writeConfig(`
+      export default {
+        safelist: ["bg-red-500", /^grid-cols-/],
+      };
+    `);
+
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.safelist).toEqual(["bg-red-500"]);
+    expect(result.safelistPatterns).toEqual(["/^grid-cols-/"]);
+  });
+
+  it("flags non-literal color entries as review items instead of dropping silently", () => {
+    writeConfig(`
+      const shared = { accent: "#000" };
+      export default {
+        theme: {
+          extend: {
+            colors: {
+              ...shared,
+              primary: someFn(),
+            },
+          },
+        },
+      };
+    `);
+
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.colors.primary).toBeUndefined();
+    expect(result.reviewItems.length).toBeGreaterThan(0);
+    expect(result.reviewItems[0].severity).toBe("warning");
+  });
+
+  it("supports module.exports = {...} form", () => {
+    writeConfig(`
+      module.exports = {
+        theme: { extend: { colors: { primary: "#111111" } } },
+      };
+    `);
+
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.colors).toEqual({ primary: "#111111" });
+  });
+
+  it("reports an error review item when the export shape is unrecognized", () => {
+    writeConfig(`
+      const config = buildConfig();
+      export default config;
+    `);
+
+    const result = extractTailwindConfig(tmpDir);
+    expect(result.colors).toEqual({});
+    expect(result.reviewItems.some((r) => r.severity === "error")).toBe(true);
+  });
+});

package/scripts/migrate/analyzers/tailwind-config.ts

@@ -0,0 +1,283 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { Project, SyntaxKind } from "ts-morph";
+import type { Node, ObjectLiteralExpression } from "ts-morph";
+import type { ReviewItem } from "../types";
+
+/**
+ * Static extraction of the parts of a Fresh site's `tailwind.config.ts` that
+ * the migrator needs to port into the scaffolded Tailwind v4 `@theme` block:
+ * `theme.extend.colors`, `theme.extend.fontFamily`, `theme.extend.screens`,
+ * top-level `safelist`, and `plugins` (name only, for the report).
+ *
+ * This only resolves statically-analyzable literals (string/template
+ * literals, array literals, nested object literals). Anything built via a
+ * spread, function call, or imported constant is NOT evaluated — the config
+ * is deleted after this read, and executing arbitrary site code here would
+ * make the migration non-deterministic. Unresolvable nodes become
+ * `ReviewItem`s instead, so the gap is a visible finding, not a silent drop.
+ */
+export interface TailwindConfigExtract {
+  /** Flattened color tokens, e.g. "brand-500" -> "#112233" */
+  colors: Record<string, string>;
+  /** Font family stacks, e.g. "sans" -> "Inter, ui-sans-serif, sans-serif" */
+  fontFamily: Record<string, string>;
+  /** Custom breakpoints, e.g. "3xl" -> "1920px" */
+  screens: Record<string, string>;
+  /** Literal safelist entries (string class names) */
+  safelist: string[];
+  /** Safelist regex patterns, kept as their source text */
+  safelistPatterns: string[];
+  /** Plugin expressions (source text), for the report only */
+  plugins: string[];
+  reviewItems: ReviewItem[];
+}
+
+const CONFIG_REL_PATH = "tailwind.config.ts";
+
+function emptyExtract(): TailwindConfigExtract {
+  return {
+    colors: {},
+    fontFamily: {},
+    screens: {},
+    safelist: [],
+    safelistPatterns: [],
+    plugins: [],
+    reviewItems: [],
+  };
+}
+
+function stripQuotes(name: string): string {
+  return name.replace(/^["']|["']$/g, "");
+}
+
+/** Find the config's exported object literal, handling both `export default` and `module.exports =`. */
+function findConfigObject(sourceFile: import("ts-morph").SourceFile): ObjectLiteralExpression | null {
+  const exportAssignment = sourceFile.getExportAssignments()[0];
+  if (exportAssignment) {
+    let expr: Node = exportAssignment.getExpression();
+    while (
+      expr.isKind(SyntaxKind.SatisfiesExpression) ||
+      expr.isKind(SyntaxKind.AsExpression) ||
+      expr.isKind(SyntaxKind.ParenthesizedExpression)
+    ) {
+      expr = expr.getExpression();
+    }
+    return expr.isKind(SyntaxKind.ObjectLiteralExpression) ? expr : null;
+  }
+
+  for (const stmt of sourceFile.getStatements()) {
+    if (!stmt.isKind(SyntaxKind.ExpressionStatement)) continue;
+    const expr = stmt.getExpression();
+    if (!expr.isKind(SyntaxKind.BinaryExpression)) continue;
+    if (expr.getLeft().getText() !== "module.exports") continue;
+    const right = expr.getRight();
+    if (right.isKind(SyntaxKind.ObjectLiteralExpression)) return right;
+  }
+
+  return null;
+}
+
+/** Get a direct child object-literal property by name, or undefined. */
+function getObjectChild(
+  obj: ObjectLiteralExpression,
+  name: string,
+): ObjectLiteralExpression | undefined {
+  const prop = obj.getProperty(name);
+  if (!prop || !prop.isKind(SyntaxKind.PropertyAssignment)) return undefined;
+  const init = prop.getInitializer();
+  return init?.isKind(SyntaxKind.ObjectLiteralExpression) ? init : undefined;
+}
+
+function flattenColors(
+  obj: ObjectLiteralExpression,
+  prefix: string,
+  out: Record<string, string>,
+  reviewItems: ReviewItem[],
+): void {
+  for (const prop of obj.getProperties()) {
+    if (!prop.isKind(SyntaxKind.PropertyAssignment)) {
+      reviewItems.push({
+        file: CONFIG_REL_PATH,
+        reason: `theme.extend.colors has a non-literal entry (${prop.getKindName()}) — port manually to src/styles/app.css @theme`,
+        severity: "warning",
+      });
+      continue;
+    }
+    const name = stripQuotes(prop.getName());
+    // Tailwind's `DEFAULT` sub-key (e.g. `colors: { primary: { DEFAULT: "#..." , 500: "#..." } }`)
+    // means "this IS `--color-primary`", not a nested `--color-primary-DEFAULT` token — Tailwind
+    // v4 only maps `bg-primary`/`text-primary`/etc. to the bare `--color-primary` variable.
+    const key = name === "DEFAULT" ? prefix : prefix ? `${prefix}-${name}` : name;
+    const init = prop.getInitializer();
+    if (!init) continue;
+    if (!key) continue;
+
+    if (init.isKind(SyntaxKind.ObjectLiteralExpression)) {
+      flattenColors(init, key, out, reviewItems);
+    } else if (
+      init.isKind(SyntaxKind.StringLiteral) ||
+      init.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)
+    ) {
+      out[key] = init.getLiteralText();
+    } else {
+      reviewItems.push({
+        file: CONFIG_REL_PATH,
+        reason: `Color token "${key}" is not a static string literal (${init.getKindName()}) — port manually to src/styles/app.css @theme`,
+        severity: "warning",
+      });
+    }
+  }
+}
+
+function extractFontFamily(
+  obj: ObjectLiteralExpression,
+  reviewItems: ReviewItem[],
+): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const prop of obj.getProperties()) {
+    if (!prop.isKind(SyntaxKind.PropertyAssignment)) continue;
+    const name = stripQuotes(prop.getName());
+    const init = prop.getInitializer();
+    if (!init) continue;
+
+    if (init.isKind(SyntaxKind.ArrayLiteralExpression)) {
+      const parts: string[] = [];
+      for (const el of init.getElements()) {
+        if (
+          el.isKind(SyntaxKind.StringLiteral) ||
+          el.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)
+        ) {
+          parts.push(el.getLiteralText());
+        } else {
+          reviewItems.push({
+            file: CONFIG_REL_PATH,
+            reason: `theme.extend.fontFamily.${name} has a non-literal stack entry (${el.getKindName()}) — port manually`,
+            severity: "warning",
+          });
+        }
+      }
+      if (parts.length > 0) result[name] = parts.join(", ");
+    } else if (
+      init.isKind(SyntaxKind.StringLiteral) ||
+      init.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)
+    ) {
+      result[name] = init.getLiteralText();
+    }
+  }
+  return result;
+}
+
+function extractScreens(obj: ObjectLiteralExpression): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const prop of obj.getProperties()) {
+    if (!prop.isKind(SyntaxKind.PropertyAssignment)) continue;
+    const name = stripQuotes(prop.getName());
+    const init = prop.getInitializer();
+    if (
+      init?.isKind(SyntaxKind.StringLiteral) ||
+      init?.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)
+    ) {
+      result[name] = init.getLiteralText();
+    }
+  }
+  return result;
+}
+
+function extractSafelist(
+  arr: import("ts-morph").ArrayLiteralExpression,
+  reviewItems: ReviewItem[],
+): { literals: string[]; patterns: string[] } {
+  const literals: string[] = [];
+  const patterns: string[] = [];
+  for (const el of arr.getElements()) {
+    if (
+      el.isKind(SyntaxKind.StringLiteral) ||
+      el.isKind(SyntaxKind.NoSubstitutionTemplateLiteral)
+    ) {
+      literals.push(el.getLiteralText());
+    } else if (el.isKind(SyntaxKind.RegularExpressionLiteral)) {
+      patterns.push(el.getText());
+    } else {
+      reviewItems.push({
+        file: CONFIG_REL_PATH,
+        reason: `safelist entry is not a static string or regex literal (${el.getKindName()}) — Tailwind v4 has no config-based safelist; port manually via @source inline(...) in src/styles/app.css`,
+        severity: "warning",
+      });
+    }
+  }
+  return { literals, patterns };
+}
+
+export function extractTailwindConfig(sourceDir: string): TailwindConfigExtract {
+  const configPath = path.join(sourceDir, CONFIG_REL_PATH);
+  if (!fs.existsSync(configPath)) return emptyExtract();
+
+  const reviewItems: ReviewItem[] = [];
+
+  let root: ObjectLiteralExpression | null;
+  try {
+    const project = new Project({ skipAddingFilesFromTsConfig: true });
+    const sourceFile = project.addSourceFileAtPath(configPath);
+    root = findConfigObject(sourceFile);
+  } catch (e) {
+    reviewItems.push({
+      file: CONFIG_REL_PATH,
+      reason: `Failed to parse tailwind.config.ts (${(e as Error).message}) — custom colors/fonts/safelist were NOT ported. Port manually to src/styles/app.css @theme.`,
+      severity: "error",
+    });
+    return { ...emptyExtract(), reviewItems };
+  }
+
+  if (!root) {
+    reviewItems.push({
+      file: CONFIG_REL_PATH,
+      reason:
+        "Could not statically locate the config's exported object (expected `export default {...}` or `module.exports = {...}`) — custom colors/fonts/safelist were NOT ported. Port manually to src/styles/app.css @theme.",
+      severity: "error",
+    });
+    return { ...emptyExtract(), reviewItems };
+  }
+
+  const themeObj = getObjectChild(root, "theme");
+  const extendObj = themeObj ? getObjectChild(themeObj, "extend") : undefined;
+
+  const colorsObj =
+    (extendObj && getObjectChild(extendObj, "colors")) ||
+    (themeObj && getObjectChild(themeObj, "colors"));
+  const colors: Record<string, string> = {};
+  if (colorsObj) flattenColors(colorsObj, "", colors, reviewItems);
+
+  const fontFamilyObj =
+    (extendObj && getObjectChild(extendObj, "fontFamily")) ||
+    (themeObj && getObjectChild(themeObj, "fontFamily"));
+  const fontFamily = fontFamilyObj ? extractFontFamily(fontFamilyObj, reviewItems) : {};
+
+  const screensObj =
+    (extendObj && getObjectChild(extendObj, "screens")) ||
+    (themeObj && getObjectChild(themeObj, "screens"));
+  const screens = screensObj ? extractScreens(screensObj) : {};
+
+  let safelist: string[] = [];
+  let safelistPatterns: string[] = [];
+  const safelistProp = root.getProperty("safelist");
+  if (safelistProp?.isKind(SyntaxKind.PropertyAssignment)) {
+    const init = safelistProp.getInitializer();
+    if (init?.isKind(SyntaxKind.ArrayLiteralExpression)) {
+      const r = extractSafelist(init, reviewItems);
+      safelist = r.literals;
+      safelistPatterns = r.patterns;
+    }
+  }
+
+  let plugins: string[] = [];
+  const pluginsProp = root.getProperty("plugins");
+  if (pluginsProp?.isKind(SyntaxKind.PropertyAssignment)) {
+    const init = pluginsProp.getInitializer();
+    if (init?.isKind(SyntaxKind.ArrayLiteralExpression)) {
+      plugins = init.getElements().map((el) => el.getText());
+    }
+  }
+
+  return { colors, fontFamily, screens, safelist, safelistPatterns, plugins, reviewItems };
+}

package/scripts/migrate/css-compile-check.test.ts

@@ -0,0 +1,115 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { CompileRunResult } from "./phase-compile";
+import { checkCssCompiles } from "./css-compile-check";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "css-compile-check-test-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function fakeRunner(
+  impl: (cmd: string, cwd: string) => CompileRunResult,
+): { calls: string[]; runner: (cmd: string, cwd: string) => CompileRunResult } {
+  const calls: string[] = [];
+  const runner = (cmd: string, cwd: string) => {
+    calls.push(cmd);
+    return impl(cmd, cwd);
+  };
+  return { calls, runner };
+}
+
+describe("checkCssCompiles", () => {
+  it("no-ops when src/styles/app.css doesn't exist", () => {
+    const { runner, calls } = fakeRunner(() => ({ ok: true }));
+    const result = checkCssCompiles({ sourceDir: tmpDir }, runner);
+    expect(result.ran).toBe(false);
+    expect(result.passed).toBe(true);
+    expect(calls).toEqual([]);
+  });
+
+  it("reports a failure with the runner's captured output", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "styles"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "src", "styles", "app.css"), "@import \"tailwindcss\";\n");
+
+    const { runner, calls } = fakeRunner(() => ({
+      ok: false,
+      output: "Cannot apply unknown utility class `font-bebas-neue`",
+    }));
+    const result = checkCssCompiles({ sourceDir: tmpDir }, runner);
+    expect(result.ran).toBe(true);
+    expect(result.passed).toBe(false);
+    expect(result.output).toContain("font-bebas-neue");
+    expect(calls[0]).toContain("@tailwindcss/cli");
+    expect(calls[0]).toContain("src/styles/app.css");
+  });
+
+  it("reports success and scans for classes missing from the compiled output", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "styles"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "src", "styles", "app.css"), "@import \"tailwindcss\";\n");
+    fs.mkdirSync(path.join(tmpDir, "src", "components"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "components", "Foo.tsx"),
+      `export default () => <div className="container-pdp flex" />;\n`,
+    );
+
+    const { runner } = fakeRunner((cmd) => {
+      const outMatch = cmd.match(/-o\s+(\S+)/);
+      const outPath = outMatch![1];
+      // Simulate Tailwind having generated CSS for `flex` but not the
+      // dropped custom `container-pdp` utility.
+      fs.writeFileSync(outPath, ".flex { display: flex; }\n");
+      return { ok: true };
+    });
+
+    const result = checkCssCompiles({ sourceDir: tmpDir }, runner);
+    expect(result.passed).toBe(true);
+    expect(result.unmatchedClassWarnings).toContain("container-pdp");
+    expect(result.unmatchedClassWarnings).not.toContain("flex");
+  });
+
+  it("does not flag classes containing variants/brackets/opacity modifiers (escaping is unreliable)", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "styles"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "src", "styles", "app.css"), "@import \"tailwindcss\";\n");
+    fs.mkdirSync(path.join(tmpDir, "src", "components"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "components", "Foo.tsx"),
+      `export default () => <div className="hover:underline bg-black/20 w-[100px]" />;\n`,
+    );
+
+    const { runner } = fakeRunner((cmd) => {
+      const outPath = cmd.match(/-o\s+(\S+)/)![1];
+      fs.writeFileSync(outPath, "");
+      return { ok: true };
+    });
+
+    const result = checkCssCompiles({ sourceDir: tmpDir }, runner);
+    expect(result.unmatchedClassWarnings).toEqual([]);
+  });
+
+  it("does not treat a data-class attribute's value as a className token", () => {
+    fs.mkdirSync(path.join(tmpDir, "src", "styles"), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, "src", "styles", "app.css"), "@import \"tailwindcss\";\n");
+    fs.mkdirSync(path.join(tmpDir, "src", "components"), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, "src", "components", "Foo.tsx"),
+      `export default () => <div data-class="tracking-widget" className="flex" />;\n`,
+    );
+
+    const { runner } = fakeRunner((cmd) => {
+      const outPath = cmd.match(/-o\s+(\S+)/)![1];
+      fs.writeFileSync(outPath, ".flex { display: flex; }\n");
+      return { ok: true };
+    });
+
+    const result = checkCssCompiles({ sourceDir: tmpDir }, runner);
+    expect(result.unmatchedClassWarnings).not.toContain("tracking-widget");
+  });
+});

package/scripts/migrate/css-compile-check.ts

@@ -0,0 +1,137 @@
+/**
+ * Real Tailwind v4 CSS compilation, run as part of phase-compile.
+ *
+ * Every other CSS-migration transform is a heuristic (regex renames,
+ * static tailwind.config.ts extraction, best-effort oklch fixes). This is
+ * the safety net: it actually compiles `src/styles/app.css` with the
+ * site's own installed `tailwindcss` via the official `@tailwindcss/cli`,
+ * so an unknown-utility-class error (the exact failure mode of
+ * decocms/blocks#369 / skill gotcha #48) surfaces during migration instead
+ * of at runtime in the browser.
+ *
+ * Uses the CLI (not `@tailwindcss/node`'s internal compile() API) on
+ * purpose — it's the officially documented, version-stable entry point,
+ * where the internal package APIs are not.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { CompileRunResult } from "./phase-compile";
+import type { MigrationContext } from "./types";
+
+export interface CssCompileResult {
+  ran: boolean;
+  passed: boolean;
+  output?: string;
+  /** Best-effort warnings — classes used in src/ that don't appear as selectors in the compiled CSS. Never fails the build. */
+  unmatchedClassWarnings: string[];
+}
+
+const APP_CSS_REL_PATH = "src/styles/app.css";
+
+/**
+ * Compile `src/styles/app.css` with the site's own Tailwind v4 install.
+ * No-ops (ran: false) if the file or `@tailwindcss/cli` isn't present —
+ * callers should treat that the same as "nothing to check", not a failure.
+ */
+export function checkCssCompiles(
+  ctx: Pick<MigrationContext, "sourceDir">,
+  runner: (cmd: string, cwd: string) => CompileRunResult,
+): CssCompileResult {
+  const cssPath = path.join(ctx.sourceDir, APP_CSS_REL_PATH);
+  if (!fs.existsSync(cssPath)) {
+    return { ran: false, passed: true, unmatchedClassWarnings: [] };
+  }
+
+  const outPath = path.join(
+    os.tmpdir(),
+    `deco-migrate-css-check-${process.pid}-${Date.now()}.css`,
+  );
+
+  try {
+    const result = runner(
+      `npx @tailwindcss/cli -i ${APP_CSS_REL_PATH} -o ${outPath}`,
+      ctx.sourceDir,
+    );
+
+    if (!result.ok) {
+      return { ran: true, passed: false, output: result.output, unmatchedClassWarnings: [] };
+    }
+
+    let unmatchedClassWarnings: string[] = [];
+    try {
+      const compiledCss = fs.readFileSync(outPath, "utf-8");
+      unmatchedClassWarnings = scanUnmatchedUtilityClasses(ctx.sourceDir, compiledCss);
+    } catch {
+      // Coverage scan is best-effort only — never let it fail the check.
+    }
+
+    return { ran: true, passed: true, unmatchedClassWarnings };
+  } finally {
+    try {
+      fs.rmSync(outPath, { force: true });
+    } catch {
+      // tmp cleanup best-effort
+    }
+  }
+}
+
+// Negative lookbehind guards against matching mid-attribute-name, e.g.
+// `data-class="..."` — without it, "class" (a substring of "data-class")
+// would match and pull an unrelated attribute value into the class scan.
+const CLASS_ATTR_RE = /(?<![\w-])(?:className|class)\s*=\s*"([^"]+)"/g;
+
+/**
+ * Best-effort cross-check: className tokens used in src/ that don't show
+ * up as a CSS selector anywhere in the compiled output. Purely
+ * informational — dynamic class construction (template literals, `clx()`
+ * with variables, conditional classes) produces false positives here, so
+ * this never fails the migration, only surfaces warnings for a human to
+ * triage.
+ */
+function scanUnmatchedUtilityClasses(sourceDir: string, compiledCss: string): string[] {
+  const srcDir = path.join(sourceDir, "src");
+  if (!fs.existsSync(srcDir)) return [];
+
+  const usedClasses = new Set<string>();
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+        continue;
+      }
+      if (!/\.(tsx|ts)$/.test(entry.name)) continue;
+      const content = fs.readFileSync(full, "utf-8");
+      let m: RegExpExecArray | null;
+      const re = new RegExp(CLASS_ATTR_RE);
+      while ((m = re.exec(content)) !== null) {
+        for (const cls of m[1].split(/\s+/).filter(Boolean)) {
+          usedClasses.add(cls);
+        }
+      }
+    }
+  };
+  walk(srcDir);
+
+  const warnings: string[] = [];
+  for (const cls of usedClasses) {
+    // Only cross-check plain word/hyphen tokens (no variants, arbitrary
+    // values, opacity modifiers, or template-interpolated fragments) —
+    // Tailwind v4 escapes those characters in the compiled selector
+    // (`.hover\:underline`, `.bg-black\/20`), which would make a naive
+    // string match unreliable. Plain tokens are exactly the case that
+    // matters most here: a dropped custom color/font/component class
+    // (e.g. `font-bebas-neue`, `container-pdp`) compiles to nothing,
+    // silently, with no error from the CLI.
+    if (/[:\[\]{}$/.]/.test(cls)) continue;
+    const selectorRe = new RegExp(`\\.${cls}(?:[^\\w-]|$)`);
+    if (!selectorRe.test(compiledCss)) {
+      warnings.push(cls);
+    }
+  }
+
+  return warnings.sort();
+}