@luna_ui/luna 0.3.4 → 0.4.0

package/src/css-optimizer/cooccurrence.ts

@@ -0,0 +1,100 @@
+/**
+ * Co-occurrence analysis for CSS classes
+ */
+
+import type { ClassUsage, CoOccurrence } from "./types.js";
+
+/**
+ * Build a co-occurrence matrix from class usages
+ * Returns a nested map: classA -> classB -> count
+ * Classes are stored in alphabetical order (A < B)
+ */
+export function buildCooccurrenceMatrix(
+  usages: ClassUsage[]
+): Map<string, Map<string, number>> {
+  const matrix = new Map<string, Map<string, number>>();
+
+  for (const usage of usages) {
+    const classes = usage.classes;
+    const n = classes.length;
+
+    // Count all pairs (i, j) where i < j
+    for (let i = 0; i < n; i++) {
+      for (let j = i + 1; j < n; j++) {
+        const a = classes[i];
+        const b = classes[j];
+
+        // Ensure consistent ordering (a < b alphabetically)
+        const [first, second] = a < b ? [a, b] : [b, a];
+
+        if (!matrix.has(first)) {
+          matrix.set(first, new Map());
+        }
+        const inner = matrix.get(first)!;
+        inner.set(second, (inner.get(second) || 0) + 1);
+      }
+    }
+  }
+
+  return matrix;
+}
+
+/**
+ * Convert matrix to a flat array of co-occurrences
+ * Sorted by frequency descending
+ */
+export function matrixToCooccurrences(
+  matrix: Map<string, Map<string, number>>
+): CoOccurrence[] {
+  const result: CoOccurrence[] = [];
+
+  for (const [classA, inner] of matrix) {
+    for (const [classB, frequency] of inner) {
+      result.push({ classA, classB, frequency });
+    }
+  }
+
+  // Sort by frequency descending
+  result.sort((a, b) => b.frequency - a.frequency);
+
+  return result;
+}
+
+/**
+ * Get the top N co-occurring pairs
+ */
+export function getTopCooccurrences(
+  cooccurrences: CoOccurrence[],
+  n: number
+): CoOccurrence[] {
+  return cooccurrences.slice(0, n);
+}
+
+/**
+ * Build an adjacency list for graph algorithms
+ * Only includes pairs with frequency >= minFrequency
+ */
+export function buildAdjacencyList(
+  cooccurrences: CoOccurrence[],
+  minFrequency: number
+): Map<string, Array<{ target: string; weight: number }>> {
+  const adj = new Map<string, Array<{ target: string; weight: number }>>();
+
+  for (const co of cooccurrences) {
+    if (co.frequency >= minFrequency) {
+      // Add edge a -> b
+      if (!adj.has(co.classA)) {
+        adj.set(co.classA, []);
+      }
+      adj.get(co.classA)!.push({ target: co.classB, weight: co.frequency });
+
+      // Add edge b -> a (undirected graph)
+      if (!adj.has(co.classB)) {
+        adj.set(co.classB, []);
+      }
+      adj.get(co.classB)!.push({ target: co.classA, weight: co.frequency });
+    }
+  }
+
+  return adj;
+}

package/src/css-optimizer/core.ts

@@ -0,0 +1,263 @@
+/**
+ * CSS Co-occurrence Optimizer - Core Module
+ *
+ * Framework-agnostic core functions for CSS class co-occurrence analysis.
+ * This module contains pure functions with no framework dependencies.
+ */
+
+import type { ClassUsage, MergePattern, OptimizeResult } from "./types.js";
+import { hashMergedClassName } from "./hash.js";
+import { findFrequentPatterns } from "./pattern.js";
+
+/**
+ * Core optimization options (framework-agnostic)
+ */
+export interface CoreOptimizeOptions {
+  /** Minimum frequency for a pattern to be merged (default: 2) */
+  minFrequency?: number;
+  /** Maximum pattern size to consider (default: 5) */
+  maxPatternSize?: number;
+  /** Pretty print CSS output (default: false) */
+  pretty?: boolean;
+  /** Enable verbose logging (default: false) */
+  verbose?: boolean;
+}
+
+/**
+ * Core optimization result
+ */
+export interface CoreOptimizeResult {
+  /** Optimized CSS string */
+  css: string;
+  /** Mapping from sorted class combination to merged class name */
+  mergeMap: Map<string, string>;
+  /** Detected patterns */
+  patterns: MergePattern[];
+  /** Statistics */
+  stats: {
+    originalClasses: number;
+    mergedPatterns: number;
+    estimatedBytesSaved: number;
+  };
+}
+
+/**
+ * Core optimizer - performs pattern analysis and CSS generation
+ *
+ * This is the framework-agnostic core that:
+ * 1. Analyzes class usages to find frequent patterns
+ * 2. Generates merged CSS rules
+ * 3. Returns a merge map for HTML transformation
+ *
+ * @param usages - Array of class usages extracted from source
+ * @param css - Original CSS content
+ * @param classToDeclaration - Map from class name to CSS declaration
+ * @param options - Optimization options
+ */
+export function optimizeCore(
+  usages: ClassUsage[],
+  css: string,
+  classToDeclaration: Map<string, string>,
+  options: CoreOptimizeOptions = {}
+): CoreOptimizeResult {
+  const {
+    minFrequency = 2,
+    maxPatternSize = 5,
+    pretty = false,
+    verbose = false,
+  } = options;
+
+  const log = (msg: string) => {
+    if (verbose) {
+      console.log(`[css-optimizer] ${msg}`);
+    }
+  };
+
+  // Early return for empty input
+  if (usages.length === 0) {
+    return {
+      css,
+      mergeMap: new Map(),
+      patterns: [],
+      stats: {
+        originalClasses: classToDeclaration.size,
+        mergedPatterns: 0,
+        estimatedBytesSaved: 0,
+      },
+    };
+  }
+
+  log(`Analyzing ${usages.length} class usage sites`);
+
+  // Step 1: Find frequent patterns
+  const patterns = findFrequentPatterns(usages, minFrequency, maxPatternSize);
+  log(`Found ${patterns.length} frequent patterns`);
+
+  // Step 2: Generate merged classes
+  const mergeMap = new Map<string, string>();
+  const cssRules: string[] = [];
+  const usedClasses = new Set<string>();
+  let totalBytesSaved = 0;
+
+  for (const pattern of patterns) {
+    // Collect declarations for all classes in pattern
+    const declarations: string[] = [];
+    let allFound = true;
+
+    for (const cls of pattern.originalClasses) {
+      const decl = classToDeclaration.get(cls);
+      if (decl) {
+        declarations.push(decl);
+      } else {
+        allFound = false;
+        break;
+      }
+    }
+
+    if (!allFound || declarations.length === 0) {
+      continue;
+    }
+
+    // Check for conflicts (class already used in another merge)
+    let hasConflict = false;
+    for (const cls of pattern.originalClasses) {
+      if (usedClasses.has(cls)) {
+        hasConflict = true;
+        break;
+      }
+    }
+
+    if (hasConflict) {
+      continue;
+    }
+
+    // Generate merged class name
+    const mergedClass = hashMergedClassName(declarations);
+
+    pattern.mergedClass = mergedClass;
+    pattern.declarations = declarations;
+
+    // Create merge key (sorted classes joined by space)
+    const mergeKey = pattern.originalClasses.join(" ");
+    mergeMap.set(mergeKey, mergedClass);
+
+    // Mark classes as used
+    for (const cls of pattern.originalClasses) {
+      usedClasses.add(cls);
+    }
+
+    // Generate CSS rule
+    const declStr = declarations.join(";");
+    if (pretty) {
+      cssRules.push(`.${mergedClass} { ${declStr.replace(/;/g, "; ")} }`);
+    } else {
+      cssRules.push(`.${mergedClass}{${declStr}}`);
+    }
+
+    totalBytesSaved += pattern.bytesSaved;
+  }
+
+  // Step 3: Filter out merged classes from original CSS
+  const originalRules: string[] = [];
+  const rulePattern = /\.([a-zA-Z_][a-zA-Z0-9_-]*)\{([^}]+)\}/g;
+
+  let match: RegExpExecArray | null;
+  rulePattern.lastIndex = 0;
+  while ((match = rulePattern.exec(css)) !== null) {
+    const cls = match[1];
+    if (!usedClasses.has(cls)) {
+      originalRules.push(match[0]);
+    }
+  }
+
+  // Preserve @media rules
+  const mediaPattern = /@media[^{]+\{[^}]+\}/g;
+  mediaPattern.lastIndex = 0;
+  while ((match = mediaPattern.exec(css)) !== null) {
+    originalRules.push(match[0]);
+  }
+
+  // Preserve pseudo-class rules
+  const pseudoPattern = /\.([a-zA-Z_][a-zA-Z0-9_-]*)(:[a-zA-Z-]+)\{([^}]+)\}/g;
+  pseudoPattern.lastIndex = 0;
+  while ((match = pseudoPattern.exec(css)) !== null) {
+    originalRules.push(match[0]);
+  }
+
+  // Combine merged + remaining original rules
+  const separator = pretty ? "\n" : "";
+  const optimizedCss = [...cssRules, ...originalRules].join(separator);
+
+  const actualPatterns = patterns.filter((p) => p.mergedClass !== "");
+
+  log(`Merged ${actualPatterns.length} patterns`);
+  log(`Estimated savings: ${totalBytesSaved} bytes`);
+
+  return {
+    css: optimizedCss,
+    mergeMap,
+    patterns: actualPatterns,
+    stats: {
+      originalClasses: classToDeclaration.size,
+      mergedPatterns: actualPatterns.length,
+      estimatedBytesSaved: totalBytesSaved,
+    },
+  };
+}
+
+/**
+ * Apply merge map to class list
+ *
+ * Takes a list of classes and returns the optimized list
+ * with merged classes replacing original combinations.
+ *
+ * @param classes - Array of class names
+ * @param mergeMap - Merge map from optimizeCore
+ * @param classPrefix - Prefix for classes to consider for merging
+ */
+export function applyMergeToClasses(
+  classes: string[],
+  mergeMap: Map<string, string>,
+  classPrefix = "_"
+): string[] {
+  if (mergeMap.size === 0) {
+    return classes;
+  }
+
+  // Separate prefixed and non-prefixed classes
+  const prefixedClasses = classes.filter((c) => c.startsWith(classPrefix));
+  const otherClasses = classes.filter((c) => !c.startsWith(classPrefix));
+
+  // Sort for consistent matching
+  prefixedClasses.sort();
+
+  let result = [...prefixedClasses];
+  const merged: string[] = [];
+
+  // Sort merge keys by length descending (longer patterns first)
+  const sortedKeys = [...mergeMap.keys()].sort((a, b) => b.length - a.length);
+
+  // Try to apply each merge pattern
+  for (const key of sortedKeys) {
+    const patternClasses = key.split(" ");
+    const mergedClass = mergeMap.get(key)!;
+
+    // Check if all pattern classes are present
+    let allPresent = true;
+    for (const cls of patternClasses) {
+      if (!result.includes(cls)) {
+        allPresent = false;
+        break;
+      }
+    }
+
+    if (allPresent) {
+      // Remove pattern classes and add merged class
+      result = result.filter((c) => !patternClasses.includes(c));
+      merged.push(mergedClass);
+    }
+  }
+
+  // Return: merged classes + remaining prefixed + other classes
+  return [...merged, ...result, ...otherClasses];
+}

package/src/css-optimizer/extractors.ts

@@ -0,0 +1,243 @@
+/**
+ * CSS Co-occurrence Optimizer - Extractors
+ *
+ * Pluggable class extraction strategies for different source formats.
+ * Each extractor takes source content and returns ClassUsage arrays.
+ */
+
+import type { ClassUsage } from "./types.js";
+
+/**
+ * Extractor interface - implement this for custom source formats
+ */
+export interface ClassExtractor {
+  /** Extractor name for debugging */
+  name: string;
+
+  /**
+   * Extract class usages from source content
+   * @param content - Source content (HTML, JSX, etc.)
+   * @param options - Extractor-specific options
+   */
+  extract(content: string, options?: ExtractorOptions): ClassUsage[];
+}
+
+/**
+ * Common extractor options
+ */
+export interface ExtractorOptions {
+  /** Only extract classes starting with this prefix (default: "_") */
+  classPrefix?: string;
+  /** Minimum classes per element to include (default: 2) */
+  minClasses?: number;
+  /** Source identifier for debugging */
+  source?: string;
+}
+
+/**
+ * HTML Class Extractor
+ *
+ * Extracts class usages from HTML content by parsing class="" attributes.
+ * Works with static HTML, SSR output, template strings, etc.
+ */
+export class HtmlExtractor implements ClassExtractor {
+  name = "html";
+
+  private pattern = /class\s*=\s*"([^"]+)"/g;
+
+  extract(content: string, options: ExtractorOptions = {}): ClassUsage[] {
+    const { classPrefix = "_", minClasses = 2, source = "html" } = options;
+
+    const usages: ClassUsage[] = [];
+    let match: RegExpExecArray | null;
+
+    this.pattern.lastIndex = 0;
+    while ((match = this.pattern.exec(content)) !== null) {
+      const classValue = match[1].trim();
+      if (!classValue) continue;
+
+      // Split by whitespace and filter by prefix
+      const classes = classValue
+        .split(/\s+/)
+        .filter((c) => c.startsWith(classPrefix) && c.length > classPrefix.length);
+
+      // Only include elements with minClasses or more matching classes
+      if (classes.length >= minClasses) {
+        classes.sort();
+        usages.push({ classes, source: `${source}:${match.index}` });
+      }
+    }
+
+    return usages;
+  }
+}
+
+/**
+ * JSX Class Extractor (simplified)
+ *
+ * Extracts class usages from JSX/TSX by finding className attributes.
+ * Note: This is a simplified regex-based extractor. For full AST support,
+ * consider using @babel/parser or TypeScript compiler.
+ */
+export class JsxExtractor implements ClassExtractor {
+  name = "jsx";
+
+  // Match className="..." and className={'...'}
+  private stringPattern = /className\s*=\s*"([^"]+)"/g;
+  private templatePattern = /className\s*=\s*\{['"`]([^'"`]+)['"`]\}/g;
+
+  extract(content: string, options: ExtractorOptions = {}): ClassUsage[] {
+    const { classPrefix = "_", minClasses = 2, source = "jsx" } = options;
+
+    const usages: ClassUsage[] = [];
+
+    // Extract from string literals
+    this.extractFromPattern(content, this.stringPattern, classPrefix, minClasses, source, usages);
+    // Extract from template literals
+    this.extractFromPattern(content, this.templatePattern, classPrefix, minClasses, source, usages);
+
+    return usages;
+  }
+
+  private extractFromPattern(
+    content: string,
+    pattern: RegExp,
+    classPrefix: string,
+    minClasses: number,
+    source: string,
+    usages: ClassUsage[]
+  ): void {
+    let match: RegExpExecArray | null;
+
+    pattern.lastIndex = 0;
+    while ((match = pattern.exec(content)) !== null) {
+      const classValue = match[1].trim();
+      if (!classValue) continue;
+
+      const classes = classValue
+        .split(/\s+/)
+        .filter((c) => c.startsWith(classPrefix) && c.length > classPrefix.length);
+
+      if (classes.length >= minClasses) {
+        classes.sort();
+        usages.push({ classes, source: `${source}:${match.index}` });
+      }
+    }
+  }
+}
+
+/**
+ * Svelte Class Extractor (simplified)
+ *
+ * Extracts class usages from Svelte templates.
+ * Handles both class="..." and class:directive syntax.
+ */
+export class SvelteExtractor implements ClassExtractor {
+  name = "svelte";
+
+  private classPattern = /class\s*=\s*"([^"]+)"/g;
+
+  extract(content: string, options: ExtractorOptions = {}): ClassUsage[] {
+    const { classPrefix = "_", minClasses = 2, source = "svelte" } = options;
+
+    const usages: ClassUsage[] = [];
+    let match: RegExpExecArray | null;
+
+    this.classPattern.lastIndex = 0;
+    while ((match = this.classPattern.exec(content)) !== null) {
+      const classValue = match[1].trim();
+      if (!classValue) continue;
+
+      // Handle Svelte's {expression} syntax by removing them
+      const cleanValue = classValue.replace(/\{[^}]+\}/g, " ");
+
+      const classes = cleanValue
+        .split(/\s+/)
+        .filter((c) => c.startsWith(classPrefix) && c.length > classPrefix.length);
+
+      if (classes.length >= minClasses) {
+        classes.sort();
+        usages.push({ classes, source: `${source}:${match.index}` });
+      }
+    }
+
+    return usages;
+  }
+}
+
+/**
+ * Multi-source extractor
+ *
+ * Combines usages from multiple sources/extractors.
+ * Useful for analyzing entire projects with mixed file types.
+ */
+export class MultiExtractor implements ClassExtractor {
+  name = "multi";
+
+  private extractors: Map<string, ClassExtractor>;
+
+  constructor() {
+    this.extractors = new Map<string, ClassExtractor>([
+      ["html", new HtmlExtractor()],
+      ["jsx", new JsxExtractor()],
+      ["tsx", new JsxExtractor()],
+      ["svelte", new SvelteExtractor()],
+    ]);
+  }
+
+  /**
+   * Register a custom extractor for a file extension
+   */
+  register(extension: string, extractor: ClassExtractor): void {
+    this.extractors.set(extension, extractor);
+  }
+
+  /**
+   * Extract from content using the appropriate extractor
+   */
+  extract(content: string, options: ExtractorOptions = {}): ClassUsage[] {
+    // Default to HTML extractor
+    const htmlExtractor = this.extractors.get("html")!;
+    return htmlExtractor.extract(content, options);
+  }
+
+  /**
+   * Extract from content with explicit file type
+   */
+  extractWithType(
+    content: string,
+    fileType: string,
+    options: ExtractorOptions = {}
+  ): ClassUsage[] {
+    const extractor = this.extractors.get(fileType) || this.extractors.get("html")!;
+    return extractor.extract(content, options);
+  }
+
+  /**
+   * Extract from multiple files
+   */
+  extractFromFiles(
+    files: Array<{ content: string; path: string }>,
+    options: ExtractorOptions = {}
+  ): ClassUsage[] {
+    const allUsages: ClassUsage[] = [];
+
+    for (const file of files) {
+      const ext = file.path.split(".").pop() || "html";
+      const extractor = this.extractors.get(ext) || this.extractors.get("html")!;
+      const usages = extractor.extract(file.content, {
+        ...options,
+        source: file.path,
+      });
+      allUsages.push(...usages);
+    }
+
+    return allUsages;
+  }
+}
+
+// Default extractors
+export const htmlExtractor = new HtmlExtractor();
+export const jsxExtractor = new JsxExtractor();
+export const svelteExtractor = new SvelteExtractor();
+export const multiExtractor = new MultiExtractor();

package/src/css-optimizer/hash.ts

@@ -0,0 +1,54 @@
+/**
+ * Hash functions for CSS class name generation
+ */
+
+/**
+ * DJB2 hash function
+ * A simple but effective string hashing algorithm
+ */
+export function djb2Hash(s: string): number {
+  let hash = 5381;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    // hash * 33 + c (using unsigned 32-bit arithmetic)
+    hash = ((hash << 5) + hash + c) >>> 0;
+  }
+  return hash;
+}
+
+/**
+ * Convert a number to base36 string (0-9a-z)
+ * Takes lower 24 bits to keep class names short (4-5 chars)
+ */
+export function toBase36(n: number): string {
+  const chars = "0123456789abcdefghijklmnopqrstuvwxyz";
+  // Take lower 24 bits
+  n = n & 0xffffff;
+  if (n === 0) return "0";
+  let result = "";
+  while (n > 0) {
+    result = chars[n % 36] + result;
+    n = Math.floor(n / 36);
+  }
+  return result;
+}
+
+/**
+ * Generate a class name from a CSS declaration string
+ * @param decl - CSS declaration like "display:flex"
+ * @param prefix - Class name prefix (default: "_")
+ */
+export function hashClassName(decl: string, prefix = "_"): string {
+  const hash = djb2Hash(decl);
+  return prefix + toBase36(hash);
+}
+
+/**
+ * Generate a merged class name from combined declarations
+ * @param declarations - Array of CSS declarations
+ * @param prefix - Class name prefix (default: "_m" for merged)
+ */
+export function hashMergedClassName(declarations: string[], prefix = "_m"): string {
+  const combined = declarations.sort().join(";");
+  return prefix + toBase36(djb2Hash(combined));
+}