emily-css 1.1.1 → 1.2.0-alpha.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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
 

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

@@ -18,6 +18,12 @@ if (command === "init") {
   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") {
@@ -29,6 +35,8 @@ if (command === "init") {
     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
@@ -50,6 +58,8 @@ if (command === "init") {
     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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emily-css",
-  "version": "1.1.1",
+  "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/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,
+};