design-clone 2.1.0 → 2.3.0

package/src/core/css/filter-css-selector-matcher.js

@@ -0,0 +1,172 @@
+/**
+ * CSS Selector Matcher for CSS Filtering
+ *
+ * Checks whether CSS selectors match elements in analyzed HTML.
+ * Uses css-tree AST walking to evaluate TypeSelector, IdSelector,
+ * ClassSelector nodes against the HTML analysis result sets.
+ */
+
+import { ALWAYS_KEEP_PATTERNS } from './filter-css-html-analyzer.js';
+
+/**
+ * Check if a single CSS selector matches any element in the HTML.
+ * @param {Object} selectorAst - css-tree Selector AST node
+ * @param {Object} htmlAnalysis - Result from analyzeHtml
+ * @param {Object} csstree - css-tree module reference
+ * @returns {boolean}
+ */
+export function selectorMatches(selectorAst, htmlAnalysis, csstree) {
+  const { tags, ids, classes } = htmlAnalysis;
+  let matches = true;
+  let hasSpecificSelector = false;
+
+  csstree.walk(selectorAst, {
+    enter(node) {
+      switch (node.type) {
+        case 'TypeSelector':
+          hasSpecificSelector = true;
+          if (node.name !== '*' && !tags.has(node.name.toLowerCase())) {
+            matches = false;
+          }
+          break;
+
+        case 'IdSelector':
+          hasSpecificSelector = true;
+          if (!ids.has(node.name)) {
+            matches = false;
+          }
+          break;
+
+        case 'ClassSelector':
+          hasSpecificSelector = true;
+          if (!classes.has(node.name)) {
+            matches = false;
+          }
+          break;
+
+        case 'AttributeSelector':
+          // Be lenient — hard to check attribute values accurately
+          hasSpecificSelector = true;
+          break;
+
+        case 'PseudoClassSelector':
+        case 'PseudoElementSelector':
+          // Always keep — state-based or decorative
+          break;
+      }
+    }
+  });
+
+  // No specific selectors found → keep the rule
+  if (!hasSpecificSelector) return true;
+
+  return matches;
+}
+
+/**
+ * Check if any selector in a SelectorList matches the HTML.
+ * @param {Object} selectorList - css-tree SelectorList AST node
+ * @param {Object} htmlAnalysis - Result from analyzeHtml
+ * @param {Object} csstree - css-tree module reference
+ * @returns {boolean}
+ */
+export function selectorListMatches(selectorList, htmlAnalysis, csstree) {
+  let anyMatch = false;
+
+  csstree.walk(selectorList, {
+    visit: 'Selector',
+    enter(node) {
+      if (selectorMatches(node, htmlAnalysis, csstree)) {
+        anyMatch = true;
+      }
+    }
+  });
+
+  return anyMatch;
+}
+
+/**
+ * Check if a selector text should always be kept (html, body, *, :root).
+ * @param {string} selectorText
+ * @returns {boolean}
+ */
+export function shouldAlwaysKeep(selectorText) {
+  return ALWAYS_KEEP_PATTERNS.some(pattern => pattern.test(selectorText.trim()));
+}
+
+/**
+ * Filter CSS AST rules based on HTML analysis.
+ * Mutates the AST in-place by removing non-matching rules.
+ * @param {Object} cssAst - css-tree AST
+ * @param {Object} htmlAnalysis - Result from analyzeHtml
+ * @param {Object} csstree - css-tree module reference
+ * @param {boolean} verbose - Enable verbose logging
+ * @returns {Promise<{ totalRules: number, keptRules: number, removedRules: number, atRules: number, mediaQueries: number, deadCode: Object|null }>}
+ */
+export async function filterCssRules(cssAst, htmlAnalysis, csstree, verbose, aggressiveFilter = false) {
+  const stats = {
+    totalRules: 0,
+    keptRules: 0,
+    removedRules: 0,
+    atRules: 0,
+    mediaQueries: 0
+  };
+
+  const nodesToRemove = [];
+
+  csstree.walk(cssAst, {
+    visit: 'Rule',
+    enter(node, item, list) {
+      stats.totalRules++;
+
+      if (node.prelude && node.prelude.type === 'SelectorList') {
+        const selectorText = csstree.generate(node.prelude);
+
+        if (shouldAlwaysKeep(selectorText)) {
+          stats.keptRules++;
+          return;
+        }
+
+        if (!selectorListMatches(node.prelude, htmlAnalysis, csstree)) {
+          nodesToRemove.push({ item, list });
+          stats.removedRules++;
+        } else {
+          stats.keptRules++;
+        }
+      } else {
+        stats.keptRules++;
+      }
+    }
+  });
+
+  for (const { item, list } of nodesToRemove) {
+    if (list) list.remove(item);
+  }
+
+  csstree.walk(cssAst, {
+    visit: 'Atrule',
+    enter(node) {
+      stats.atRules++;
+      if (node.name === 'media') stats.mediaQueries++;
+    }
+  });
+
+  // Pass 2: dead code removal (aggressive mode only)
+  let deadCode = null;
+  if (aggressiveFilter) {
+    try {
+      const { runDeadCodePass } = await import('./filter-css-dead-code.js');
+      deadCode = runDeadCodePass(cssAst, csstree);
+    } catch { /* dead code pass optional */ }
+  }
+
+  if (verbose) {
+    console.error(`[CSS Filter] Total rules: ${stats.totalRules}`);
+    console.error(`[CSS Filter] Kept: ${stats.keptRules} (${Math.round(stats.keptRules / stats.totalRules * 100)}%)`);
+    console.error(`[CSS Filter] Removed: ${stats.removedRules}`);
+    console.error(`[CSS Filter] At-rules: ${stats.atRules} (${stats.mediaQueries} media queries)`);
+    if (deadCode) console.error(`[CSS Filter] Dead code: ${deadCode.emptyMediaRemoved} empty @media, ${deadCode.orphanKeyframesRemoved} orphan @keyframes, ${deadCode.unusedCustomPropsRemoved} unused vars`);
+  }
+
+  return { ...stats, deadCode };
+}

package/src/core/css/filter-css.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Filter CSS to remove unused selectors
+ *
+ * Usage:
+ *   node filter-css.js --html source.html --css source-raw.css --output source.css
+ *
+ * Options:
+ *   --html     Path to cleaned HTML file (required)
+ *   --css      Path to raw CSS file (required)
+ *   --output   Path for filtered CSS output (required)
+ *   --verbose  Enable verbose logging
+ *
+ * Uses css-tree for AST parsing and selector analysis.
+ * Memory: Max 10MB CSS input. Large files may cause high memory usage during AST parsing.
+ * Reduction: Typical 20-30% reduction. Complex selectors kept conservatively.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { parseArgs } from '../../utils/helpers.js';
+import { SIZE_LIMITS } from '../../shared/config.js';
+import { filterCssRules } from './filter-css-selector-matcher.js';
+import { analyzeHtml, validatePath, sanitizeCss } from './filter-css-html-analyzer.js';
+import { createError } from '../../shared/error-codes.js';
+
+// Dependency check for css-tree
+let csstree;
+try {
+  csstree = await import('css-tree');
+} catch {
+  console.error(JSON.stringify({
+    success: false,
+    error: 'css-tree not installed',
+    hint: 'Run: npm install css-tree'
+  }, null, 2));
+  process.exit(1);
+}
+
+/**
+ * Main filtering function
+ * @param {string} htmlPath - Path to HTML file
+ * @param {string} cssPath - Path to raw CSS file
+ * @param {string} outputPath - Path for filtered CSS output
+ * @param {boolean} verbose - Enable verbose logging
+ * @param {string|null} allowedDir - Base directory for path validation (optional)
+ * @returns {Promise<Object>} Result object
+ */
+async function filterCssFile(htmlPath, cssPath, outputPath, verbose = false, allowedDir = null, aggressiveFilter = false) {
+  const startTime = Date.now();
+
+  const resolvedHtml   = allowedDir ? validatePath(htmlPath, allowedDir)   : path.resolve(htmlPath);
+  const resolvedCss    = allowedDir ? validatePath(cssPath, allowedDir)    : path.resolve(cssPath);
+  const resolvedOutput = allowedDir ? validatePath(outputPath, allowedDir) : path.resolve(outputPath);
+
+  let html, css;
+  try {
+    [html, css] = await Promise.all([
+      fs.readFile(resolvedHtml, 'utf-8'),
+      fs.readFile(resolvedCss, 'utf-8')
+    ]);
+  } catch (readError) {
+    const failedFile = readError.path || 'unknown';
+    throw new Error(`Failed to read file "${failedFile}": ${readError.message}`);
+  }
+
+  const inputSize = Buffer.byteLength(css, 'utf-8');
+
+  if (inputSize > SIZE_LIMITS.MAX_CSS_INPUT) {
+    throw createError('CSS_SIZE_EXCEEDED', {
+      file: resolvedCss,
+      size: `${(inputSize / 1024 / 1024).toFixed(1)}MB`,
+      limit: `${SIZE_LIMITS.MAX_CSS_INPUT / 1024 / 1024}MB`
+    });
+  }
+
+  if (verbose) console.error(`[CSS Filter] Input CSS size: ${(inputSize / 1024).toFixed(1)}KB`);
+
+  const htmlAnalysis = analyzeHtml(html);
+  if (verbose) {
+    console.error(`[CSS Filter] HTML Analysis:`);
+    console.error(`  Tags: ${htmlAnalysis.tags.size}`);
+    console.error(`  IDs: ${htmlAnalysis.ids.size}`);
+    console.error(`  Classes: ${htmlAnalysis.classes.size}`);
+    console.error(`  Attributes: ${htmlAnalysis.attributes.size}`);
+  }
+
+  let filteredCss, stats;
+
+  // Chunked processing for large CSS files
+  if (inputSize > (SIZE_LIMITS.CSS_CHUNK_THRESHOLD || 2 * 1024 * 1024)) {
+    if (verbose) console.error(`[CSS Filter] Large CSS (${(inputSize / 1024 / 1024).toFixed(1)}MB) — using chunked processing`);
+    try {
+      const { splitCssAtTopLevel, processChunks } = await import('./css-chunker.js');
+      const chunks = splitCssAtTopLevel(css);
+      const result = await processChunks(chunks, async (chunkCss) => {
+        const chunkAst = csstree.parse(chunkCss, { parseRulePrelude: true, parseValue: false });
+        const chunkStats = await filterCssRules(chunkAst, htmlAnalysis, csstree, false);
+        return { css: csstree.generate(chunkAst), stats: chunkStats };
+      });
+      filteredCss = sanitizeCss(result.css);
+      stats = result.stats;
+    } catch (chunkError) {
+      if (verbose) console.error(`[CSS Filter] Chunked processing failed, falling back to full parse: ${chunkError.message}`);
+      // Fall through to standard path below
+      filteredCss = null;
+    }
+  }
+
+  // Standard full-parse path (or fallback from chunked failure)
+  if (!filteredCss) {
+    let ast;
+    try {
+      ast = csstree.parse(css, { parseRulePrelude: true, parseValue: false });
+    } catch (parseError) {
+      if (verbose) {
+        console.error(`[CSS Filter] Parse error: ${parseError.message}`);
+        console.error(`[CSS Filter] Attempting lenient parse...`);
+      }
+      try {
+        ast = csstree.parse(css, { parseRulePrelude: false, parseValue: false });
+      } catch (lenientError) {
+        throw createError('CSS_PARSE_FAILED', { parseError: lenientError.message });
+      }
+    }
+
+    stats = await filterCssRules(ast, htmlAnalysis, csstree, verbose, !!aggressiveFilter);
+    filteredCss = sanitizeCss(csstree.generate(ast));
+  }
+
+  const outputSize = Buffer.byteLength(filteredCss, 'utf-8');
+
+  try {
+    await fs.writeFile(resolvedOutput, filteredCss, 'utf-8');
+  } catch (writeError) {
+    throw new Error(`Failed to write output "${resolvedOutput}": ${writeError.message}`);
+  }
+
+  const duration = Date.now() - startTime;
+  const reductionPercent = Math.round((1 - outputSize / inputSize) * 100);
+
+  if (verbose) {
+    console.error(`[CSS Filter] Output CSS size: ${(outputSize / 1024).toFixed(1)}KB`);
+    console.error(`[CSS Filter] Reduction: ${reductionPercent}%`);
+    console.error(`[CSS Filter] Duration: ${duration}ms`);
+  }
+
+  return {
+    success: true,
+    input: { html: resolvedHtml, css: resolvedCss, cssSize: inputSize },
+    output: { path: resolvedOutput, size: outputSize },
+    htmlAnalysis: {
+      tags: htmlAnalysis.tags.size,
+      ids: htmlAnalysis.ids.size,
+      classes: htmlAnalysis.classes.size
+    },
+    stats: {
+      ...stats,
+      reduction: `${reductionPercent}%`,
+      durationMs: duration
+    }
+  };
+}
+
+/**
+ * CLI entry point
+ */
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (!args.html || !args.css || !args.output) {
+    console.error('Usage: node filter-css.js --html source.html --css source-raw.css --output source.css [--verbose]');
+    process.exit(1);
+  }
+
+  try {
+    const isClonePx = process.argv.some(a => a.includes('clone-px') || a.includes('capture-hover'));
+    const aggressive = args['aggressive-filter'] === 'true' ||
+      (args['aggressive-filter'] !== 'false' && isClonePx);
+    const result = await filterCssFile(
+      args.html,
+      args.css,
+      args.output,
+      args.verbose === 'true' || args.verbose === true,
+      null,
+      aggressive
+    );
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(0);
+  } catch (error) {
+    console.error(JSON.stringify({ success: false, error: error.message }, null, 2));
+    process.exit(1);
+  }
+}
+
+// Export for module use (backward-compatible — all original exports preserved)
+export { filterCssFile, analyzeHtml, validatePath, sanitizeCss };
+
+const isMainModule = process.argv[1] && (
+  process.argv[1].endsWith('filter-css.js') ||
+  process.argv[1].includes('filter-css')
+);
+
+if (isMainModule) {
+  main();
+}

package/src/core/css/merge-css-atrule-processor.js

@@ -0,0 +1,158 @@
+/**
+ * CSS At-Rule Processor for Merging
+ *
+ * Handles extraction and deduplication of @font-face, @keyframes,
+ * @charset, @import, and @media rules during CSS merging.
+ * All functions receive the css-tree module as a parameter (no top-level import)
+ * so this module stays side-effect free.
+ */
+
+/**
+ * Generate a hash key for a CSS rule (selector + declarations).
+ * @param {Object} node - css-tree Rule node
+ * @param {Object} csstree - css-tree module
+ * @returns {string}
+ */
+export function getRuleHash(node, csstree) {
+  const selector     = csstree.generate(node.prelude);
+  const declarations = csstree.generate(node.block);
+  return `${selector}|${declarations}`;
+}
+
+/**
+ * Extract font-family value from a @font-face rule.
+ * @param {Object} node - css-tree Atrule node
+ * @param {Object} csstree - css-tree module
+ * @returns {string}
+ */
+export function extractFontFamily(node, csstree) {
+  let family = '';
+  csstree.walk(node, {
+    visit: 'Declaration',
+    enter(decl) {
+      if (decl.property === 'font-family') {
+        family = csstree.generate(decl.value).replace(/["']/g, '').trim();
+      }
+    }
+  });
+  return family;
+}
+
+/**
+ * Extract src value from a @font-face rule.
+ * @param {Object} node - css-tree Atrule node
+ * @param {Object} csstree - css-tree module
+ * @returns {string}
+ */
+export function extractFontSrc(node, csstree) {
+  let src = '';
+  csstree.walk(node, {
+    visit: 'Declaration',
+    enter(decl) {
+      if (decl.property === 'src') {
+        src = csstree.generate(decl.value);
+      }
+    }
+  });
+  return src;
+}
+
+/**
+ * Extract animation name from a @keyframes rule.
+ * @param {Object} node - css-tree Atrule node
+ * @param {Object} csstree - css-tree module
+ * @returns {string}
+ */
+export function extractKeyframeName(node, csstree) {
+  return node.prelude ? csstree.generate(node.prelude).trim() : '';
+}
+
+/**
+ * Process a single at-rule node, updating the shared collections.
+ * Handles: @charset, @import, @font-face, @keyframes, @media, and others.
+ *
+ * @param {Object} node          - css-tree Atrule node
+ * @param {Object} csstree       - css-tree module
+ * @param {Object} opts          - Merge options (deduplicateFontFaces, deduplicateKeyframes, combineMediaQueries)
+ * @param {Object} collections   - Shared mutable state:
+ *   { seenFontFaces, seenKeyframes, seenCharset, imports, mediaGroups, outputNodes, stats }
+ */
+export function processAtrule(node, csstree, opts, collections) {
+  const { seenFontFaces, seenKeyframes, seenCharset, imports, mediaGroups, outputNodes, stats } = collections;
+  const name = node.name.toLowerCase();
+
+  if (name === 'charset') {
+    if (!seenCharset.found) {
+      seenCharset.found = true;
+      seenCharset.node  = node;
+    }
+    return;
+  }
+
+  if (name === 'import') {
+    imports.push(node);
+    return;
+  }
+
+  if (name === 'font-face') {
+    stats.inputRules++;
+    if (opts.deduplicateFontFaces) {
+      const family = extractFontFamily(node, csstree);
+      const src    = extractFontSrc(node, csstree);
+      const key    = `${family}|${src}`;
+      if (!seenFontFaces.has(key)) {
+        seenFontFaces.set(key, node);
+        outputNodes.push({ type: 'fontface', node });
+      } else {
+        stats.fontFacesDeduped++;
+      }
+    } else {
+      outputNodes.push({ type: 'fontface', node });
+    }
+    return;
+  }
+
+  if (name === 'keyframes' || name === '-webkit-keyframes') {
+    stats.inputRules++;
+    if (opts.deduplicateKeyframes) {
+      const animName = extractKeyframeName(node, csstree);
+      if (!seenKeyframes.has(animName)) {
+        seenKeyframes.set(animName, node);
+        outputNodes.push({ type: 'keyframes', node });
+      } else {
+        stats.keyframesDeduped++;
+      }
+    } else {
+      outputNodes.push({ type: 'keyframes', node });
+    }
+    return;
+  }
+
+  if (name === 'media') {
+    const condition = node.prelude ? csstree.generate(node.prelude) : '';
+
+    if (opts.combineMediaQueries && condition) {
+      if (!mediaGroups.has(condition)) mediaGroups.set(condition, []);
+
+      csstree.walk(node.block, {
+        visit: 'Rule',
+        enter(rule) {
+          stats.inputRules++;
+          const hash       = getRuleHash(rule, csstree);
+          const groupRules = mediaGroups.get(condition);
+          if (!groupRules.some(r => r.hash === hash)) {
+            groupRules.push({ hash, node: rule });
+          } else {
+            stats.duplicateRulesRemoved++;
+          }
+        }
+      });
+    } else {
+      outputNodes.push({ type: 'atrule', node });
+    }
+    return;
+  }
+
+  // @supports, @page, etc. — keep as-is
+  outputNodes.push({ type: 'atrule', node });
+}

package/src/core/css/merge-css-file-io.js

@@ -0,0 +1,68 @@
+/**
+ * CSS Merge File I/O
+ *
+ * Reads multiple CSS files from disk, merges them via mergeStylesheets,
+ * and writes the result. Separates file system concerns from merge logic.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { mergeStylesheets } from './merge-css.js';
+
+/**
+ * Merge multiple CSS files into a single output file.
+ * @param {string[]} cssFiles - Array of CSS file paths
+ * @param {string} outputPath - Output file path
+ * @param {Object} options - Merge options (passed through to mergeStylesheets)
+ * @returns {Promise<Object>} Merge result with success, input, output, stats
+ */
+export async function mergeCssFiles(cssFiles, outputPath, options = {}) {
+  const startTime    = Date.now();
+  const cssContents  = [];
+  let totalInputSize = 0;
+
+  for (const filePath of cssFiles) {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      cssContents.push(content);
+      totalInputSize += Buffer.byteLength(content, 'utf-8');
+    } catch (err) {
+      console.error(`[WARN] Could not read ${filePath}: ${err.message}`);
+    }
+  }
+
+  if (cssContents.length === 0) {
+    return {
+      success: false,
+      error: 'No CSS files could be read',
+      input: { files: cssFiles, totalSize: 0, totalRules: 0 },
+      output: null,
+      stats: null
+    };
+  }
+
+  const { css, stats } = mergeStylesheets(cssContents, options);
+  const outputSize    = Buffer.byteLength(css, 'utf-8');
+  await fs.writeFile(outputPath, css, 'utf-8');
+
+  const duration  = Date.now() - startTime;
+  const reduction = totalInputSize > 0
+    ? Math.round((1 - outputSize / totalInputSize) * 100)
+    : 0;
+
+  return {
+    success: true,
+    input: {
+      files:      cssFiles,
+      fileCount:  cssFiles.length,
+      totalSize:  totalInputSize,
+      totalRules: stats.inputRules
+    },
+    output: {
+      path:  path.resolve(outputPath),
+      size:  outputSize,
+      rules: stats.outputRules
+    },
+    stats: { ...stats, reduction: `${reduction}%`, durationMs: duration }
+  };
+}