emily-css 1.0.29 → 1.2.0-alpha.0

package/CHANGELOG.md

@@ -3,7 +3,42 @@
 All notable changes to `emily-css` are documented here.
 
 ---
+## v1.2.0-alpha.0 — May 2026
 
+### Added
+- Report-only Tailwind-to-EmilyCSS migration command: `emily-css migrate`.
+- Default semantic migration mode for design-token aligned suggestions.
+- Imported palette mode via `emily-css migrate --import-colours` for visual parity mapping suggestions.
+- Detection and reporting for arbitrary value utilities during migration analysis.
+
+### Notes
+- Migration in this alpha is analysis-only: no source files are modified by `migrate`.
+
+---
+## v1.1.0 — May 2026
+
+### Added
+- Added `emily-css doctor`, a manifest-powered project checker that scans configured source files and reports unknown EmilyCSS classes with suggestions.
+- Added variant-aware class validation for responsive, state, ARIA, data-state, motion, dark, and forced-colours variants.
+
+---
+
+## v1.1.1 — May 2026
+
+**updated changes and added**
+
+### Added
+- updted changes
+
+---
+## v1.1.0 — May 2026
+
+**add utility manifest generation): chore: release v1.1.0**
+
+### Added
+- add utility manifest generation): chore: release v1.1.0
+
+---
 ## v1.0.29 — May 2026
 
 **added json manifest for future use**

package/README.md

@@ -53,8 +53,17 @@ npx emily-css init     # Setup config + first build
 npx emily-css build    # Regenerate CSS
 npx emily-css watch    # Development watch mode
 npx emily-css purge    # Remove unused styles for production
+npx emily-css migrate  # Report-only Tailwind-to-EmilyCSS migration analysis
+  --import-colours     # Imported palette mode (visual parity class suggestions)
 ```
 
+## Migration (1.2.0-alpha)
+
+- `emily-css migrate` is report-only and does not modify files.
+- Default migration mode is semantic (`gray/slate/zinc/stone` remap toward `neutral` naming).
+- `emily-css migrate --import-colours` enables imported palette mode for parity-oriented palette suggestions.
+- Arbitrary value utilities (for example `w-[37px]`, `bg-[#0f172a]`) are detected and reported as unsupported.
+
 ## How Purge Works
 
 emilyCSS scans your templates for used class names and removes everything else.
@@ -146,4 +155,4 @@ Then import the weights you need.
 
 ## License
 
-MIT
+MIT

package/bin/emilyui.js

@@ -14,6 +14,16 @@ if (command === "init") {
   require("../src/watch.js");
 } else if (command === "showcase") {
   require("../src/showcase.js");
+} else if (command === "doctor") {
+  const { doctor } = require("../src/doctor.js");
+  const result = doctor();
+  process.exitCode = result.exitCode;
+} else if (command === "migrate") {
+  const { generateMigrationReport } = require("../src/migrate.js");
+  const { formatMigrationReport } = require("../src/reporters/migrationReporter.js");
+  const importColours = process.argv.includes("--import-colours");
+  const report = generateMigrationReport({ importColours });
+  console.log(formatMigrationReport(report, { importColours }));
 } else if (command === "version" || command === "--version" || command === "-v") {
   console.log(packageJson.version);
 } else if (command === "help") {
@@ -24,6 +34,9 @@ if (command === "init") {
     emily-css init        Set up a new project (interactive wizard)
     emily-css build       Generate production CSS to the configured output path
     emily-css watch       Dev mode: watch for changes and rebuild
+    emily-css doctor      Scan project files for unknown EmilyCSS classes
+    emily-css migrate     Generate a Tailwind-to-EmilyCSS migration report
+      --import-colours    Detect Tailwind colour palettes and suggest importedPalettes config
     emily-css showcase    Launch the component showcase in your browser
     emily-css version     Show installed version
     emily-css help        Show this help text
@@ -44,9 +57,12 @@ if (command === "init") {
     emily-css init        Set up a new project
     emily-css build       Generate production CSS to the configured output path
     emily-css watch       Dev mode: rebuild on changes
+    emily-css doctor      Scan project files for unknown EmilyCSS classes
+    emily-css migrate     Generate a Tailwind-to-EmilyCSS migration report
+      --import-colours    Detect Tailwind colour palettes and suggest importedPalettes config
     emily-css showcase    Browse components in your browser
     emily-css help        Full command reference
 
   Run emily-css help for more detail.
 `);
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emily-css",
-  "version": "1.0.29",
+  "version": "1.2.0-alpha.0",
   "description": "A config-driven utility CSS framework. Define your brand once, generate the CSS.",
   "main": "src/index.js",
   "bin": {

package/src/doctor.js

@@ -0,0 +1,293 @@
+const fs = require("fs");
+const path = require("path");
+const fg = require("fast-glob");
+const { extractClassNames } = require("./purge.js");
+const { ensureFullFramework, generateManifest } = require("./index.js");
+
+const DEFAULT_EXTENSIONS = [
+  ".html",
+  ".htm",
+  ".twig",
+  ".njk",
+  ".liquid",
+  ".hbs",
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".vue",
+  ".php",
+  ".astro",
+  ".svelte",
+  ".blade.php",
+  ".jinja",
+  ".jinja2",
+  ".j2",
+  ".md",
+];
+
+function getConfigPath() {
+  return path.join(process.cwd(), "emily.config.json");
+}
+
+function getConfig() {
+  const configPath = getConfigPath();
+
+  if (!fs.existsSync(configPath)) {
+    console.error('\n  emily-css: No config found. Run "emily-css init" first.\n');
+    process.exit(1);
+  }
+
+  return JSON.parse(fs.readFileSync(configPath, "utf8"));
+}
+
+function getFullCssPath(config) {
+  return path.join(process.cwd(), config.output?.fullCss || "dist/emily.css");
+}
+
+function getManifestSettings(config) {
+  const manifestConfig = config.manifest;
+
+  if (manifestConfig === true) {
+    return { enabled: true, output: "dist/emily.manifest.json" };
+  }
+
+  if (manifestConfig && typeof manifestConfig === "object") {
+    return {
+      enabled: manifestConfig.enabled === true,
+      output: manifestConfig.output || "dist/emily.manifest.json",
+    };
+  }
+
+  return { enabled: false, output: "dist/emily.manifest.json" };
+}
+
+function getManifestOutputPath(config) {
+  const manifestSettings = getManifestSettings(config);
+  const outputPath = manifestSettings.output || "dist/emily.manifest.json";
+
+  return path.isAbsolute(outputPath)
+    ? outputPath
+    : path.join(process.cwd(), outputPath);
+}
+
+function normaliseClassForManifest(className) {
+  if (!className || typeof className !== "string") {
+    return { original: className, baseClass: "", variants: [], variant: null };
+  }
+
+  const parts = className.split(":").filter(Boolean);
+
+  if (parts.length <= 1) {
+    return {
+      original: className,
+      baseClass: className,
+      variants: [],
+      variant: null,
+    };
+  }
+
+  const baseClass = parts[parts.length - 1];
+  const variants = parts.slice(0, -1);
+
+  return {
+    original: className,
+    baseClass,
+    variants,
+    variant: variants.join(":"),
+  };
+}
+
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+
+  const dp = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+
+  for (let i = 0; i <= a.length; i++) dp[i][0] = i;
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+
+  return dp[a.length][b.length];
+}
+
+function findClosest(target, candidates) {
+  if (!target || candidates.length === 0) return null;
+
+  let best = null;
+  let bestDistance = Infinity;
+
+  for (const candidate of candidates) {
+    const distance = levenshtein(target, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+      if (distance === 0) break;
+    }
+  }
+
+  const threshold = Math.max(2, Math.floor(target.length / 3));
+  return bestDistance <= threshold ? best : null;
+}
+
+function suggestClassName(className, utilitySet, variantSet) {
+  const utilityList = Array.isArray(utilitySet) ? utilitySet : Array.from(utilitySet);
+  const variantList = Array.isArray(variantSet) ? variantSet : Array.from(variantSet);
+  const parsed = normaliseClassForManifest(className);
+
+  if (!parsed.variants.length) {
+    return findClosest(parsed.baseClass, utilityList);
+  }
+
+  const correctedVariants = parsed.variants.map((variant) => {
+    if (variantSet.has(variant)) return variant;
+    return findClosest(variant, variantList) || variant;
+  });
+
+  const correctedBase = utilitySet.has(parsed.baseClass)
+    ? parsed.baseClass
+    : findClosest(parsed.baseClass, utilityList);
+
+  if (!correctedBase) return null;
+
+  const rebuilt = correctedVariants.length
+    ? `${correctedVariants.join(":")}:${correctedBase}`
+    : correctedBase;
+
+  return rebuilt === className ? null : rebuilt;
+}
+
+function getFilesToScan(config) {
+  const extensions = config?.purge?.extensions || DEFAULT_EXTENSIONS;
+  const ignore = config?.purge?.ignore || [];
+
+  if (config?.purge?.sourceGlobs && config.purge.sourceGlobs.length > 0) {
+    return fg.sync(config.purge.sourceGlobs, {
+      ignore,
+      onlyFiles: true,
+      unique: true,
+    });
+  }
+
+  const sourceDir = config?.purge?.sourceDir || ".";
+  const scanDir = path.isAbsolute(sourceDir)
+    ? sourceDir
+    : path.join(process.cwd(), sourceDir);
+  const patterns = extensions.map((ext) => `**/*${ext}`);
+
+  return fg.sync(patterns, {
+    cwd: scanDir,
+    ignore,
+    onlyFiles: true,
+    unique: true,
+    absolute: true,
+  });
+}
+
+function loadManifest(config, css) {
+  const manifestSettings = getManifestSettings(config);
+  const manifestOutputPath = getManifestOutputPath(config);
+
+  if (manifestSettings.enabled && fs.existsSync(manifestOutputPath)) {
+    return JSON.parse(fs.readFileSync(manifestOutputPath, "utf8"));
+  }
+
+  return generateManifest(css, config);
+}
+
+function doctor() {
+  const config = getConfig();
+
+  ensureFullFramework();
+
+  const fullCssPath = getFullCssPath(config);
+  if (!fs.existsSync(fullCssPath)) {
+    console.error("\nEmilyCSS doctor could not locate generated CSS.\n");
+    return { ok: false, issues: [], exitCode: 1 };
+  }
+
+  const css = fs.readFileSync(fullCssPath, "utf8");
+  const manifest = loadManifest(config, css);
+  const utilities = manifest.utilities || [];
+  const utilitySet = new Set(utilities.map((utility) => utility.class));
+  const variantSet = new Set();
+
+  utilities.forEach((utility) => {
+    (utility.variants || []).forEach((variant) => variantSet.add(variant));
+  });
+
+  const files = getFilesToScan(config);
+  const issues = [];
+  const suggestionCache = new Map();
+
+  files.forEach((filePath) => {
+    try {
+      const content = fs.readFileSync(filePath, "utf8");
+      const classes = extractClassNames(content);
+
+      classes.forEach((className) => {
+        const parsed = normaliseClassForManifest(className);
+        const unknownVariants = parsed.variants.filter((variant) => !variantSet.has(variant));
+        const knownBase = utilitySet.has(parsed.baseClass);
+
+        if (unknownVariants.length === 0 && knownBase) {
+          return;
+        }
+
+        if (!suggestionCache.has(className)) {
+          suggestionCache.set(className, suggestClassName(className, utilitySet, variantSet));
+        }
+
+        issues.push({
+          file: filePath,
+          className,
+          reason: unknownVariants.length > 0 ? "unknown-variant" : "unknown-class",
+          unknownVariants,
+          suggestion: suggestionCache.get(className),
+        });
+      });
+    } catch (error) {
+      // Keep parity with purge behaviour: unreadable files are skipped.
+    }
+  });
+
+  if (issues.length === 0) {
+    console.log("✓ EmilyCSS doctor found no class issues");
+    return { ok: true, issues: [], exitCode: 0 };
+  }
+
+  console.log(`EmilyCSS doctor found ${issues.length} issue${issues.length === 1 ? "" : "s"}\n`);
+
+  issues.forEach((issue) => {
+    console.log(path.relative(process.cwd(), issue.file));
+    if (issue.reason === "unknown-variant") {
+      console.log(`  Unknown variant in class: ${issue.className}`);
+    } else {
+      console.log(`  Unknown class: ${issue.className}`);
+    }
+    if (issue.suggestion) {
+      console.log(`  Did you mean: ${issue.suggestion}?`);
+    }
+    console.log("");
+  });
+
+  console.log("Run `emily-css build` after fixing classes.");
+  return { ok: false, issues, exitCode: 1 };
+}
+
+module.exports = {
+  doctor,
+  normaliseClassForManifest,
+  suggestClassName,
+};

package/src/migrate.js

@@ -0,0 +1,756 @@
+const fs = require('fs');
+const path = require('path');
+const fg = require('fast-glob');
+
+const { extractClassNames, getAllFiles } = require('./purge.js');
+const { generateManifest } = require('./manifest.js');
+const { normaliseClassForManifest, suggestClassName } = require('./doctor.js');
+
+const DEFAULT_EXTENSIONS = [
+  '.html',
+  '.htm',
+  '.twig',
+  '.njk',
+  '.liquid',
+  '.hbs',
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.vue',
+  '.php',
+  '.astro',
+  '.svelte',
+  '.blade.php',
+  '.jinja',
+  '.jinja2',
+  '.j2',
+  '.md',
+  '.mdx',
+];
+
+const TAILWIND_MAPPINGS = {
+  'text-gray-900': {
+    replacement: 'text-neutral-90',
+    aliases: ['text-zinc-900', 'text-slate-900', 'text-stone-900', 'text-neutral-900'],
+    deprecated: false,
+    metadata: { category: 'colour' },
+  },
+  'text-gray-700': {
+    replacement: 'text-neutral-70',
+    aliases: ['text-zinc-700', 'text-slate-700', 'text-stone-700', 'text-neutral-700'],
+    deprecated: false,
+    metadata: { category: 'colour' },
+  },
+  'text-gray-500': {
+    replacement: 'text-neutral-50',
+    aliases: ['text-zinc-500', 'text-slate-500', 'text-stone-500', 'text-neutral-500'],
+    deprecated: false,
+    metadata: { category: 'colour' },
+  },
+  'bg-gray-100': {
+    replacement: 'bg-neutral-10',
+    aliases: ['bg-zinc-100', 'bg-slate-100', 'bg-stone-100', 'bg-neutral-100'],
+    deprecated: false,
+    metadata: { category: 'background' },
+  },
+  'bg-gray-900': {
+    replacement: 'bg-neutral-90',
+    aliases: ['bg-zinc-900', 'bg-slate-900', 'bg-stone-900', 'bg-neutral-900'],
+    deprecated: false,
+    metadata: { category: 'background' },
+  },
+  'rounded-md': {
+    replacement: 'rounded-md',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'radius' },
+  },
+  'rounded-lg': {
+    replacement: 'rounded-lg',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'radius' },
+  },
+  'shadow-md': {
+    replacement: 'shadow-md',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'shadow' },
+  },
+  flex: {
+    replacement: 'flex',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'layout' },
+  },
+  grid: {
+    replacement: 'grid',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'layout' },
+  },
+  hidden: {
+    replacement: 'hidden',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'layout' },
+  },
+  block: {
+    replacement: 'block',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'layout' },
+  },
+  'inline-block': {
+    replacement: 'inline-block',
+    aliases: [],
+    deprecated: false,
+    metadata: { category: 'layout' },
+  },
+};
+
+const MIGRATION_MODE_SEMANTIC = 'semantic';
+const MIGRATION_MODE_IMPORTED_PALETTES = 'imported-palettes';
+
+const TAILWIND_COLOUR_UTILITY_PREFIXES = new Set([
+  'text',
+  'bg',
+  'border',
+  'accent',
+  'fill',
+  'stroke',
+  'ring',
+  'outline',
+]);
+
+const TAILWIND_COLOUR_PALETTES = new Set([
+  'slate',
+  'gray',
+  'zinc',
+  'neutral',
+  'stone',
+  'red',
+  'orange',
+  'amber',
+  'yellow',
+  'lime',
+  'green',
+  'emerald',
+  'teal',
+  'cyan',
+  'sky',
+  'blue',
+  'indigo',
+  'violet',
+  'purple',
+  'fuchsia',
+  'pink',
+  'rose',
+]);
+
+const TAILWIND_SHADE_TO_EMILY_SHADE = {
+  '50': '5',
+  '100': '10',
+  '200': '20',
+  '300': '30',
+  '400': '40',
+  '500': '50',
+  '600': '60',
+  '700': '70',
+  '800': '80',
+  '900': '90',
+  '950': '100',
+};
+
+function getConfigPath(options = {}) {
+  return options.configPath || path.join(process.cwd(), 'emily.config.json');
+}
+
+function readConfig(options = {}) {
+  if (options.config && typeof options.config === 'object') {
+    return options.config;
+  }
+
+  const configPath = getConfigPath(options);
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+function getManifestSettings(config) {
+  const manifestConfig = config && config.manifest;
+
+  if (manifestConfig === true) {
+    return { enabled: true, output: 'dist/emily.manifest.json' };
+  }
+
+  if (manifestConfig && typeof manifestConfig === 'object') {
+    return {
+      enabled: manifestConfig.enabled === true,
+      output: manifestConfig.output || 'dist/emily.manifest.json',
+    };
+  }
+
+  return { enabled: false, output: 'dist/emily.manifest.json' };
+}
+
+function getManifestOutputPath(config, options = {}) {
+  if (options.manifestPath) {
+    return path.isAbsolute(options.manifestPath)
+      ? options.manifestPath
+      : path.join(process.cwd(), options.manifestPath);
+  }
+
+  const manifestSettings = getManifestSettings(config || {});
+  const outputPath = manifestSettings.output || 'dist/emily.manifest.json';
+
+  return path.isAbsolute(outputPath)
+    ? outputPath
+    : path.join(process.cwd(), outputPath);
+}
+
+function getFullCssPath(config, options = {}) {
+  if (options.cssPath) {
+    return path.isAbsolute(options.cssPath)
+      ? options.cssPath
+      : path.join(process.cwd(), options.cssPath);
+  }
+
+  const outputPath = (config && config.output && config.output.fullCss) || 'dist/emily.css';
+  return path.isAbsolute(outputPath)
+    ? outputPath
+    : path.join(process.cwd(), outputPath);
+}
+
+function createEmptyManifest() {
+  return {
+    version: 'unknown',
+    generatedAt: new Date().toISOString(),
+    utilities: [],
+  };
+}
+
+function loadManifest(options = {}) {
+  const warnings = [];
+
+  if (options.manifest && Array.isArray(options.manifest.utilities)) {
+    return { manifest: options.manifest, warnings };
+  }
+
+  const config = readConfig(options) || {};
+  const manifestPath = getManifestOutputPath(config, options);
+
+  if (fs.existsSync(manifestPath)) {
+    try {
+      return {
+        manifest: JSON.parse(fs.readFileSync(manifestPath, 'utf8')),
+        warnings,
+      };
+    } catch (error) {
+      warnings.push(`Could not parse manifest at ${manifestPath}: ${error.message}`);
+    }
+  }
+
+  const fullCssPath = getFullCssPath(config, options);
+
+  if (fs.existsSync(fullCssPath)) {
+    try {
+      const css = fs.readFileSync(fullCssPath, 'utf8');
+      return {
+        manifest: generateManifest(css, config),
+        warnings,
+      };
+    } catch (error) {
+      warnings.push(`Could not generate manifest from CSS at ${fullCssPath}: ${error.message}`);
+    }
+  }
+
+  warnings.push(
+    'Manifest not found. Migration report will continue without full EmilyCSS support checks.',
+  );
+
+  return { manifest: createEmptyManifest(), warnings };
+}
+
+function buildManifestIndexes(manifest) {
+  const utilities = Array.isArray(manifest && manifest.utilities) ? manifest.utilities : [];
+  const utilitySet = new Set();
+  const variantSet = new Set();
+
+  utilities.forEach((utility) => {
+    if (utility && utility.class) {
+      utilitySet.add(utility.class);
+    }
+
+    const variants = Array.isArray(utility && utility.variants) ? utility.variants : [];
+    variants.forEach((variant) => variantSet.add(variant));
+  });
+
+  return { utilitySet, variantSet };
+}
+
+function resolveTailwindMapping(className, mappingTable = TAILWIND_MAPPINGS) {
+  if (!className || typeof className !== 'string') {
+    return null;
+  }
+
+  if (mappingTable[className]) {
+    return {
+      source: className,
+      ...mappingTable[className],
+    };
+  }
+
+  const entries = Object.entries(mappingTable);
+
+  for (const [sourceClass, entry] of entries) {
+    const aliases = Array.isArray(entry.aliases) ? entry.aliases : [];
+    if (aliases.includes(className)) {
+      return {
+        source: sourceClass,
+        ...entry,
+        matchedAlias: className,
+      };
+    }
+  }
+
+  return null;
+}
+
+function buildVariantClassName(variants, baseClass) {
+  if (!Array.isArray(variants) || variants.length === 0) {
+    return baseClass;
+  }
+
+  return `${variants.join(':')}:${baseClass}`;
+}
+
+function getMigrationMode(options = {}) {
+  return options.importColours === true
+    ? MIGRATION_MODE_IMPORTED_PALETTES
+    : MIGRATION_MODE_SEMANTIC;
+}
+
+function mapTailwindPaletteToEmilyPalette(paletteName, mode) {
+  if (mode === MIGRATION_MODE_IMPORTED_PALETTES) {
+    return paletteName;
+  }
+
+  const semanticPaletteRemap = {
+    gray: 'neutral',
+    slate: 'neutral',
+    zinc: 'neutral',
+    stone: 'neutral',
+  };
+
+  return semanticPaletteRemap[paletteName] || paletteName;
+}
+
+function parseTailwindColourClass(baseClass, mode) {
+  if (!baseClass || typeof baseClass !== 'string') {
+    return null;
+  }
+
+  const [baseWithoutOpacity, opacitySuffix] = baseClass.split('/');
+  const match = baseWithoutOpacity.match(
+    /^([a-z-]+)-([a-z][a-z0-9-]*)-(50|100|200|300|400|500|600|700|800|900|950)$/,
+  );
+
+  if (!match) {
+    return null;
+  }
+
+  const utility = match[1];
+  const tailwindPalette = match[2];
+  const tailwindShade = match[3];
+
+  if (!TAILWIND_COLOUR_UTILITY_PREFIXES.has(utility)) {
+    return null;
+  }
+  if (!TAILWIND_COLOUR_PALETTES.has(tailwindPalette)) {
+    return null;
+  }
+
+  const emilyShade = TAILWIND_SHADE_TO_EMILY_SHADE[tailwindShade];
+  if (!emilyShade) {
+    return null;
+  }
+
+  const emilyPalette = mapTailwindPaletteToEmilyPalette(tailwindPalette, mode);
+  const emilyBaseClass = `${utility}-${emilyPalette}-${emilyShade}`;
+
+  return {
+    utility,
+    tailwindPalette,
+    tailwindShade,
+    opacitySuffix: opacitySuffix || null,
+    emilyPalette,
+    emilyShade,
+    emilyBaseClass,
+  };
+}
+
+function isSemanticColourMapping(mapping) {
+  const category = mapping && mapping.metadata && mapping.metadata.category;
+  return category === 'colour' || category === 'background';
+}
+
+function hasArbitraryValueSyntax(baseClass) {
+  return typeof baseClass === 'string' && /\[[^\]]+\]/.test(baseClass);
+}
+
+function buildImportedPalettesConfigBlock(importedPalettes) {
+  if (!Array.isArray(importedPalettes) || importedPalettes.length === 0) {
+    return null;
+  }
+
+  const grouped = {};
+
+  importedPalettes.forEach((entry) => {
+    if (!grouped[entry.emilyPalette]) {
+      grouped[entry.emilyPalette] = new Set();
+    }
+    grouped[entry.emilyPalette].add(entry.tailwindPalette);
+  });
+
+  const lines = ['importedPalettes: {'];
+
+  Object.keys(grouped)
+    .sort()
+    .forEach((emilyPalette) => {
+      const sources = Array.from(grouped[emilyPalette]).sort();
+      if (sources.length === 1) {
+        lines.push(`  ${emilyPalette}: "tailwind-${sources[0]}",`);
+      } else {
+        const aliases = sources.map((source) => `"${source}"`).join(', ');
+        lines.push(`  ${emilyPalette}: { source: "tailwind", aliases: [${aliases}] },`);
+      }
+    });
+
+  lines.push('}');
+  return lines.join('\n');
+}
+
+function isLikelyUtilityClass(className) {
+  if (!className || typeof className !== 'string') return false;
+  if (/\s/.test(className)) return false;
+  if (className.length > 120) return false;
+  if (className.startsWith('--')) return false;
+  if (className.startsWith('.') || className.startsWith('#') || className.startsWith('@')) return false;
+  if (className.endsWith(':')) return false;
+  if (className.includes('://')) return false;
+  if (/[;()={},`]/.test(className)) return false;
+  if (!/[a-zA-Z]/.test(className)) return false;
+  if (!/^[a-zA-Z0-9:#_./\-[\]]+$/.test(className)) return false;
+
+  return true;
+}
+
+function migrateClasses(input, options = {}) {
+  const mode = getMigrationMode(options);
+
+  const report = {
+    found: [],
+    supported: [],
+    knownTailwind: [],
+    unsupported: [],
+    arbitraryValueUtilities: [],
+    suggestions: [],
+    replacements: [],
+    importedPaletteMappings: [],
+    importedPalettes: [],
+    warnings: [],
+  };
+
+  if (typeof input !== 'string') {
+    report.warnings.push('migrateClasses expected a string input; received non-string content.');
+    return report;
+  }
+
+  const classSet = extractClassNames(input);
+  const found = Array.from(classSet).filter(isLikelyUtilityClass);
+
+  report.found = found;
+
+  const { manifest, warnings } = loadManifest(options);
+  report.warnings.push(...warnings);
+
+  const { utilitySet, variantSet } = buildManifestIndexes(manifest);
+
+  for (const className of found) {
+    const parsed = normaliseClassForManifest(className);
+    const variants = parsed.variants || [];
+    const isArbitraryValueClass = hasArbitraryValueSyntax(parsed.baseClass);
+    const hasUnknownVariant = variants.some((variant) => !variantSet.has(variant));
+    const isSupported = utilitySet.has(parsed.baseClass) && !hasUnknownVariant;
+
+    if (isSupported) {
+      report.supported.push(className);
+    }
+
+    const parsedTailwindColour = parseTailwindColourClass(parsed.baseClass, mode);
+    const mapping = resolveTailwindMapping(parsed.baseClass, options.mappingTable || TAILWIND_MAPPINGS);
+    const shouldUseImportedPaletteMapping =
+      mode === MIGRATION_MODE_IMPORTED_PALETTES && !!parsedTailwindColour;
+    const effectiveSemanticMapping =
+      shouldUseImportedPaletteMapping && isSemanticColourMapping(mapping) ? null : mapping;
+
+    if (isArbitraryValueClass) {
+      report.arbitraryValueUtilities.push(className);
+      if (!isSupported) {
+        report.unsupported.push(className);
+      }
+      continue;
+    }
+
+    if (shouldUseImportedPaletteMapping) {
+      const suggestedClass = buildVariantClassName(variants, parsedTailwindColour.emilyBaseClass);
+
+      report.importedPaletteMappings.push({
+        from: className,
+        to: suggestedClass,
+        utility: parsedTailwindColour.utility,
+        tailwindPalette: parsedTailwindColour.tailwindPalette,
+        tailwindShade: parsedTailwindColour.tailwindShade,
+        emilyPalette: parsedTailwindColour.emilyPalette,
+        emilyShade: parsedTailwindColour.emilyShade,
+        hasOpacitySuffix: parsedTailwindColour.opacitySuffix !== null,
+      });
+
+      report.importedPalettes.push({
+        tailwindPalette: parsedTailwindColour.tailwindPalette,
+        emilyPalette: parsedTailwindColour.emilyPalette,
+      });
+    }
+
+    if (effectiveSemanticMapping) {
+      report.knownTailwind.push(className);
+
+      const replacementClass = buildVariantClassName(variants, effectiveSemanticMapping.replacement);
+      const hasChange = replacementClass !== className;
+
+      if (hasChange) {
+        report.replacements.push({
+          from: className,
+          to: replacementClass,
+          source: effectiveSemanticMapping.source,
+          matchedAlias: effectiveSemanticMapping.matchedAlias || null,
+          deprecated: effectiveSemanticMapping.deprecated === true,
+          metadata: effectiveSemanticMapping.metadata || {},
+        });
+
+        report.suggestions.push({
+          className,
+          suggestion: replacementClass,
+          reason: 'tailwind-mapping',
+        });
+      }
+    } else if (shouldUseImportedPaletteMapping) {
+      const replacementClass = buildVariantClassName(variants, parsedTailwindColour.emilyBaseClass);
+
+      report.knownTailwind.push(className);
+      report.replacements.push({
+        from: className,
+        to: replacementClass,
+        source: `${parsedTailwindColour.utility}-${parsedTailwindColour.tailwindPalette}-${parsedTailwindColour.tailwindShade}`,
+        matchedAlias: null,
+        deprecated: false,
+        metadata: {
+          category: 'imported-palette-colour',
+          emilyPalette: parsedTailwindColour.emilyPalette,
+          emilyShade: parsedTailwindColour.emilyShade,
+          hasOpacitySuffix: parsedTailwindColour.opacitySuffix !== null,
+        },
+      });
+      report.suggestions.push({
+        className,
+        suggestion: replacementClass,
+        reason: 'imported-palette-mapping',
+      });
+    }
+
+    if (!isSupported && !effectiveSemanticMapping) {
+      if (shouldUseImportedPaletteMapping) {
+        continue;
+      }
+
+      report.unsupported.push(className);
+
+      if (utilitySet.size > 0) {
+        const suggestion = suggestClassName(className, utilitySet, variantSet);
+        if (suggestion) {
+          report.suggestions.push({
+            className,
+            suggestion,
+            reason: 'closest-emily-class',
+          });
+        }
+      }
+    }
+  }
+
+  report.found.sort();
+  report.supported.sort();
+  report.knownTailwind.sort();
+  report.unsupported.sort();
+  report.arbitraryValueUtilities.sort();
+  report.importedPalettes = dedupeBy(
+    report.importedPalettes,
+    (item) => `${item.tailwindPalette}->${item.emilyPalette}`,
+  );
+  report.importedPaletteMappings = dedupeBy(
+    report.importedPaletteMappings,
+    (item) => `${item.from}->${item.to}`,
+  );
+
+  return report;
+}
+
+function getFilesToScan(config, options = {}) {
+  const extensions = (config && config.purge && config.purge.extensions) || DEFAULT_EXTENSIONS;
+  const ignore = (config && config.purge && config.purge.ignore) || [];
+
+  if (options.sourceGlobs && options.sourceGlobs.length > 0) {
+    return fg.sync(options.sourceGlobs, {
+      ignore,
+      onlyFiles: true,
+      unique: true,
+      absolute: true,
+    });
+  }
+
+  if (config && config.purge && config.purge.sourceGlobs && config.purge.sourceGlobs.length > 0) {
+    return fg.sync(config.purge.sourceGlobs, {
+      ignore,
+      onlyFiles: true,
+      unique: true,
+      absolute: true,
+    });
+  }
+
+  const sourceDir =
+    options.sourceDir ||
+    (config && config.purge && config.purge.sourceDir) ||
+    '.';
+
+  const scanDir = path.isAbsolute(sourceDir)
+    ? sourceDir
+    : path.join(process.cwd(), sourceDir);
+
+  if (!fs.existsSync(scanDir)) {
+    return [];
+  }
+
+  return getAllFiles(scanDir, extensions);
+}
+
+function dedupeBy(items, keyFn) {
+  const seen = new Set();
+  const result = [];
+
+  for (const item of items) {
+    const key = keyFn(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(item);
+  }
+
+  return result;
+}
+
+function generateMigrationReport(options = {}) {
+  const config = readConfig(options) || {};
+  const manifestResult = loadManifest({ ...options, config });
+  const files = getFilesToScan(config, options);
+
+  const aggregate = {
+    found: new Set(),
+    supported: new Set(),
+    knownTailwind: new Set(),
+    unsupported: new Set(),
+    arbitraryValueUtilities: new Set(),
+    suggestions: [],
+    replacements: [],
+    importedPaletteMappings: [],
+    importedPalettes: [],
+    warnings: [...manifestResult.warnings],
+  };
+
+  if (files.length === 0) {
+    aggregate.warnings.push('No source files found for migration scan.');
+  }
+
+  const fileReports = [];
+
+  files.forEach((filePath) => {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const report = migrateClasses(content, {
+        ...options,
+        config,
+        manifest: manifestResult.manifest,
+      });
+
+      report.found.forEach((className) => aggregate.found.add(className));
+      report.supported.forEach((className) => aggregate.supported.add(className));
+      report.knownTailwind.forEach((className) => aggregate.knownTailwind.add(className));
+      report.unsupported.forEach((className) => aggregate.unsupported.add(className));
+      report.arbitraryValueUtilities.forEach((className) => aggregate.arbitraryValueUtilities.add(className));
+      aggregate.suggestions.push(...report.suggestions);
+      aggregate.replacements.push(...report.replacements);
+      aggregate.importedPaletteMappings.push(...report.importedPaletteMappings);
+      aggregate.importedPalettes.push(...report.importedPalettes);
+      aggregate.warnings.push(...report.warnings);
+
+      fileReports.push({
+        file: filePath,
+        report,
+      });
+    } catch (error) {
+      aggregate.warnings.push(`Could not read ${filePath}: ${error.message}`);
+    }
+  });
+
+  return {
+    files,
+    fileReports,
+    found: Array.from(aggregate.found).sort(),
+    supported: Array.from(aggregate.supported).sort(),
+    knownTailwind: Array.from(aggregate.knownTailwind).sort(),
+    unsupported: Array.from(aggregate.unsupported).sort(),
+    arbitraryValueUtilities: Array.from(aggregate.arbitraryValueUtilities).sort(),
+    suggestions: dedupeBy(aggregate.suggestions, (item) => `${item.className}->${item.suggestion}`),
+    replacements: dedupeBy(aggregate.replacements, (item) => `${item.from}->${item.to}`),
+    importedPaletteMappings: dedupeBy(
+      aggregate.importedPaletteMappings,
+      (item) => `${item.from}->${item.to}`,
+    ),
+    importedPalettes: dedupeBy(
+      aggregate.importedPalettes,
+      (item) => `${item.tailwindPalette}->${item.emilyPalette}`,
+    ),
+    importedPalettesConfig:
+      options.importColours === true
+        ? buildImportedPalettesConfigBlock(
+            dedupeBy(
+              aggregate.importedPalettes,
+              (item) => `${item.tailwindPalette}->${item.emilyPalette}`,
+            ),
+          )
+        : null,
+    warnings: Array.from(new Set(aggregate.warnings)),
+  };
+}
+
+module.exports = {
+  migrateClasses,
+  loadManifest,
+  generateMigrationReport,
+};

package/src/reporters/migrationReporter.js

@@ -0,0 +1,71 @@
+function pushListSection(lines, title, items, limit = 20) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return;
+  }
+
+  lines.push('', `${title}:`);
+  items.slice(0, limit).forEach((item) => {
+    lines.push(`  - ${item}`);
+  });
+
+  if (items.length > limit) {
+    lines.push(`  ...and ${items.length - limit} more`);
+  }
+}
+
+function formatMigrationReport(report, options = {}) {
+  const importColours = options.importColours === true;
+  const lines = [
+    '',
+    'EmilyCSS migration report',
+    `  Files scanned: ${report.files.length}`,
+    `  Total classes found: ${report.found.length}`,
+    `  Supported EmilyCSS classes: ${report.supported.length}`,
+    `  Known Tailwind classes: ${report.knownTailwind.length}`,
+    `  Suggested replacements: ${report.replacements.length}`,
+    `  Unsupported classes: ${report.unsupported.length}`,
+  ];
+
+  if (importColours) {
+    lines.push(`  Migration mode: imported-palettes`);
+    lines.push(`  Imported palettes detected: ${report.importedPalettes.length}`);
+  } else {
+    lines.push(`  Migration mode: semantic`);
+  }
+
+  pushListSection(
+    lines,
+    'Suggested replacements',
+    report.replacements.map((entry) => `${entry.from} -> ${entry.to}`),
+  );
+
+  pushListSection(lines, 'Unsupported classes', report.unsupported);
+  pushListSection(lines, 'Unsupported arbitrary value utilities detected', report.arbitraryValueUtilities);
+
+  if (report.warnings.length > 0) {
+    lines.push('', 'Warnings:');
+    report.warnings.forEach((warning) => {
+      lines.push(`  - ${warning}`);
+    });
+  }
+
+  if (importColours) {
+    pushListSection(
+      lines,
+      'Imported palette colour mappings',
+      report.importedPaletteMappings.map((entry) => `${entry.from} -> ${entry.to}`),
+    );
+
+    if (report.importedPalettesConfig) {
+      lines.push('', 'Suggested importedPalettes config:');
+      lines.push(report.importedPalettesConfig);
+    }
+  }
+
+  lines.push('');
+  return lines.join('\n');
+}
+
+module.exports = {
+  formatMigrationReport,
+};