emily-css 1.0.28 → 1.1.1

package/CHANGELOG.md

@@ -3,7 +3,38 @@
 All notable changes to `emily-css` are documented here.
 
 ---
+## 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**
+
+### Added
+- added json manifest for future use
+
+---
 ## v1.0.28 — May 2026
 
 **added new utilities**

package/bin/emilyui.js

@@ -14,6 +14,10 @@ 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 === "version" || command === "--version" || command === "-v") {
   console.log(packageJson.version);
 } else if (command === "help") {
@@ -24,6 +28,7 @@ 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 showcase    Launch the component showcase in your browser
     emily-css version     Show installed version
     emily-css help        Show this help text
@@ -44,9 +49,10 @@ 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 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.28",
+  "version": "1.1.1",
   "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/index.js

@@ -3,6 +3,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { generateManifest } = require('./manifest');
 
 
 // ============================================================================
@@ -1479,6 +1480,32 @@ function getProductionCssPath(config) {
   return path.join(process.cwd(), config.output?.css || 'dist/emily.min.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 ensureDirectoryForFile(filePath) {
   const dir = path.dirname(filePath);
 
@@ -1700,6 +1727,16 @@ ${bodyFont}`;
   ensureDirectoryForFile(fullCssPath);
   fs.writeFileSync(fullCssPath, css);
 
+  const manifestSettings = getManifestSettings(config);
+  if (manifestSettings.enabled) {
+    const manifestPath = getManifestOutputPath(config);
+    const manifest = generateManifest(css, config);
+
+    ensureDirectoryForFile(manifestPath);
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    console.log(`✓ Generated manifest: ${manifestPath}`);
+  }
+
   console.log(`✓ Generated CSS: ${fullCssPath}`);
   console.log(`✓ File size: ${(css.length / 1024).toFixed(2)} KB (unminified)`);
   console.log('Full framework build complete');
@@ -1808,6 +1845,7 @@ module.exports = {
   addStateVariants,
   addAriaDataVariants,
   addResponsiveVariants,
+  generateManifest,
   generateFontCSS,
   codeUtilities,
 };

package/src/manifest.js

@@ -0,0 +1,307 @@
+const MANIFEST_VERSION = '1.1.0';
+const DEFAULT_RESPONSIVE_VARIANTS = ['sm', 'md', 'lg', 'xl', '2xl'];
+const BASE_VARIANTS = [
+  'hover',
+  'focus',
+  'focus-within',
+  'focus-visible',
+  'active',
+  'disabled',
+  'motion-reduce',
+  'motion-safe',
+  'aria-expanded',
+  'aria-selected',
+  'aria-current',
+  'aria-disabled',
+  'data-open',
+  'data-closed',
+  'dark',
+  'forced-colors',
+];
+
+function parseDeclarations(block) {
+  const declarations = {};
+  const declarationRegex = /([a-zA-Z-]+)\s*:\s*([^;]+)\s*;?/g;
+  let firstProperty = null;
+  let firstValue = null;
+  let match;
+
+  while ((match = declarationRegex.exec(block)) !== null) {
+    const property = match[1].trim();
+    const value = match[2].trim();
+    declarations[property] = value;
+
+    if (!firstProperty) {
+      firstProperty = property;
+      firstValue = value;
+    }
+  }
+
+  return { declarations, firstProperty, firstValue };
+}
+
+function getTokenFromDeclarations(declarations) {
+  const values = Object.values(declarations);
+
+  for (const value of values) {
+    const tokenMatch = value.match(/var\(\s*(--[a-zA-Z0-9-_]+)\s*(?:,[^)]+)?\)/);
+    if (tokenMatch) {
+      return tokenMatch[1];
+    }
+  }
+
+  return null;
+}
+
+function isSimpleBaseClassSelector(selector) {
+  if (!selector || !selector.startsWith('.')) return false;
+  if (selector.includes(' ')) return false;
+  if (selector.includes(',')) return false;
+  if (selector.includes('[')) return false;
+  if (selector.includes(':')) return false;
+  if (selector.includes('::')) return false;
+  if (selector.includes('>')) return false;
+  if (selector.includes('+')) return false;
+  if (selector.includes('~')) return false;
+
+  return true;
+}
+
+function inferCategory(className, property) {
+  if (
+    className === 'prose' ||
+    className === 'prose-emily' ||
+    className === 'center-screen' ||
+    className === 'center-absolute' ||
+    className === 'field-container' ||
+    className === 'form-hint' ||
+    className === 'form-error-message' ||
+    className === 'error-summary' ||
+    className === 'btn' ||
+    className === 'btn-primary' ||
+    className === 'btn-secondary' ||
+    className === 'btn-ghost' ||
+    className === 'btn-danger' ||
+    className === 'btn-sm' ||
+    className === 'btn-lg' ||
+    className === 'code-window' ||
+    className === 'code-title-bar' ||
+    className === 'code-dot' ||
+    className === 'code-dot-red' ||
+    className === 'code-dot-yellow' ||
+    className === 'code-dot-green' ||
+    className === 'code-filename' ||
+    className.startsWith('token-')
+  ) {
+    return 'component';
+  }
+
+  if (className.startsWith('text-')) {
+    return property === 'color' ? 'colour' : 'typography';
+  }
+
+  if (
+    className.startsWith('font-') ||
+    className.startsWith('leading-') ||
+    className.startsWith('tracking-') ||
+    className.startsWith('list-') 
+  ) {
+    return 'typography';
+  }
+
+  if (className.startsWith('bg-')) return 'background';
+
+  if (
+    className === 'border' ||
+    className.startsWith('border-') ||
+    className.startsWith('divide-') ||
+    className === 'outline' ||
+    className.startsWith('outline-') ||
+    className === 'ring' ||
+    className.startsWith('ring-')
+  ) {
+    return 'border';
+  }
+
+  if (
+    className.startsWith('p-') ||
+    className.startsWith('px-') ||
+    className.startsWith('py-') ||
+    className.startsWith('pt-') ||
+    className.startsWith('pr-') ||
+    className.startsWith('pb-') ||
+    className.startsWith('pl-') ||
+    className.startsWith('m-') ||
+    className.startsWith('mx-') ||
+    className.startsWith('my-') ||
+    className.startsWith('mt-') ||
+    className.startsWith('mr-') ||
+    className.startsWith('mb-') ||
+    className.startsWith('ml-') ||
+    className.startsWith('gap-') ||
+    className.startsWith('space-') ||
+    className.startsWith('inset-') ||
+    className.startsWith('top-') ||
+    className.startsWith('right-') ||
+    className.startsWith('bottom-') ||
+    className.startsWith('left-')
+  ) {
+    return 'spacing';
+  }
+
+  if (
+    className.startsWith('w-') ||
+    className.startsWith('h-') ||
+    className.startsWith('min-w-') ||
+    className.startsWith('max-w-') ||
+    className.startsWith('min-h-') ||
+    className.startsWith('max-h-') ||
+    className.startsWith('size-')
+  ) {
+    return 'sizing';
+  }
+
+  if (
+    className === 'flex' ||
+    className === 'grid' ||
+    className === 'block' ||
+    className === 'inline' ||
+    className === 'inline-block' ||
+    className === 'inline-flex' ||
+    className === 'hidden' ||
+    className === 'container' ||
+    className === 'relative' ||
+    className === 'absolute' ||
+    className === 'fixed' ||
+    className === 'sticky' ||
+    className === 'static'
+  ) {
+    return 'layout';
+  }
+
+  if (
+    className.startsWith('items-') ||
+    className.startsWith('justify-') ||
+    className.startsWith('content-') ||
+    className.startsWith('self-') ||
+    className.startsWith('place-') ||
+    className.startsWith('order-') ||
+    className.startsWith('col-') ||
+    className.startsWith('row-')
+  ) {
+    return 'layout';
+  }
+
+  if (className === 'rounded' || className.startsWith('rounded-')) return 'radius';
+  if (className === 'shadow' || className.startsWith('shadow-')) return 'shadow';
+
+  if (
+    className.startsWith('opacity-') ||
+    className.startsWith('blur-') ||
+    className.startsWith('backdrop-') ||
+    className === 'filter' ||
+    className === 'grayscale' ||
+    className.startsWith('saturate-') ||
+    className.startsWith('brightness-') ||
+    className.startsWith('contrast-')
+  ) {
+    return 'effects';
+  }
+
+  if (
+    className === 'transition' ||
+    className.startsWith('transition-') ||
+    className.startsWith('duration-') ||
+    className.startsWith('ease-') ||
+    className.startsWith('delay-') ||
+    className.startsWith('animate-')
+  ) {
+    return 'motion';
+  }
+
+  if (
+    className === 'sr-only' ||
+    className === 'not-sr-only' ||
+    className === 'focus-ring' ||
+    className === 'skip-to-content' ||
+    className === 'js-hidden' ||
+    className === 'no-js'
+  ) {
+    return 'accessibility';
+  }
+
+  if (
+    className === 'input' ||
+    className === 'select' ||
+    className === 'textarea' ||
+    className === 'checkbox' ||
+    className === 'radio' ||
+    className === 'stack' ||
+    className === 'cluster' ||
+    className === 'width-container'
+  ) {
+    return 'component';
+  }
+
+  return 'utility';
+}
+
+function normalizeClassName(selector) {
+  return selector.slice(1).replace(/\\(.)/g, '$1');
+}
+
+function getVariants(config) {
+  const breakpoints =
+    config &&
+    config.breakpoints &&
+    typeof config.breakpoints === 'object' &&
+    Object.keys(config.breakpoints).length > 0
+      ? Object.keys(config.breakpoints)
+      : DEFAULT_RESPONSIVE_VARIANTS;
+
+  return [...BASE_VARIANTS, ...breakpoints];
+}
+
+function generateManifest(css, config = {}) {
+  const manifest = {
+    version: MANIFEST_VERSION,
+    generatedAt: new Date().toISOString(),
+    utilities: [],
+  };
+
+  if (typeof css !== 'string' || css.length === 0) {
+    return manifest;
+  }
+
+  const variants = getVariants(config);
+  const cleanedCss = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const ruleRegex = /([^{}]+)\{([^{}]*)\}/g;
+  let ruleMatch;
+
+  while ((ruleMatch = ruleRegex.exec(cleanedCss)) !== null) {
+    const selector = ruleMatch[1].trim();
+    const declarationBlock = ruleMatch[2].trim();
+
+    if (!isSimpleBaseClassSelector(selector)) continue;
+
+    const { declarations, firstProperty, firstValue } = parseDeclarations(declarationBlock);
+    if (!firstProperty) continue;
+
+    manifest.utilities.push({
+      class: normalizeClassName(selector),
+      category: inferCategory(normalizeClassName(selector), firstProperty),
+      property: firstProperty,
+      value: firstValue,
+      token: getTokenFromDeclarations(declarations),
+      declarations,
+      variants,
+      source: 'generated-css',
+    });
+  }
+
+  return manifest;
+}
+
+module.exports = {
+  generateManifest,
+};