@luna_ui/luna 0.3.3 → 0.3.5

package/src/css-optimizer/index.ts

@@ -0,0 +1,129 @@
+/**
+ * CSS Co-occurrence Optimizer
+ *
+ * A standalone, framework-agnostic library for optimizing CSS by merging
+ * frequently co-occurring classes. Works with HTML, React, Svelte, and more.
+ *
+ * ## Architecture
+ *
+ * - **Core**: Pure functions for pattern analysis (no framework dependency)
+ * - **Extractors**: Pluggable class extraction (HTML, JSX, Svelte, etc.)
+ * - **Transformers**: Pluggable output transformation
+ *
+ * ## Quick Start (Framework-agnostic)
+ *
+ * ```typescript
+ * import {
+ *   optimizeCore,
+ *   htmlExtractor,
+ *   htmlTransformer
+ * } from "@luna_ui/luna/css-optimizer";
+ *
+ * // 1. Extract class usages
+ * const usages = htmlExtractor.extract(html);
+ *
+ * // 2. Optimize
+ * const classToDecl = new Map([["_flex", "display:flex"], ...]);
+ * const result = optimizeCore(usages, css, classToDecl);
+ *
+ * // 3. Transform output
+ * const optimizedHtml = htmlTransformer.transform(html, result.mergeMap);
+ * ```
+ *
+ * ## Legacy API (Luna-specific convenience)
+ *
+ * ```typescript
+ * import { optimizeCss, optimizeHtml } from "@luna_ui/luna/css-optimizer";
+ *
+ * const result = optimizeCss(css, html, mapping, { minFrequency: 2 });
+ * const optimizedHtml = optimizeHtml(html, result.mergeMap);
+ * ```
+ */
+
+// Types
+export type {
+  ClassUsage,
+  CoOccurrence,
+  MergePattern,
+  OptimizeResult,
+  OptimizeOptions,
+  ClassNameGenerator,
+  CssRule,
+  // MoonBit analyzer types
+  ClassCooccurrence,
+  AnalyzerWarning,
+} from "./types.js";
+
+// Core (framework-agnostic)
+export {
+  optimizeCore,
+  applyMergeToClasses,
+  type CoreOptimizeOptions,
+  type CoreOptimizeResult,
+} from "./core.js";
+
+// Extractors
+export {
+  HtmlExtractor,
+  JsxExtractor,
+  SvelteExtractor,
+  MultiExtractor,
+  htmlExtractor,
+  jsxExtractor,
+  svelteExtractor,
+  multiExtractor,
+  type ClassExtractor,
+  type ExtractorOptions,
+} from "./extractors.js";
+
+// Transformers
+export {
+  HtmlTransformer,
+  JsxTransformer,
+  SvelteTransformer,
+  MultiTransformer,
+  htmlTransformer,
+  jsxTransformer,
+  svelteTransformer,
+  multiTransformer,
+  type ClassTransformer,
+  type TransformerOptions,
+} from "./transformers.js";
+
+// Hash utilities
+export { djb2Hash, toBase36, hashClassName, hashMergedClassName } from "./hash.js";
+
+// Parsing utilities (for advanced use)
+export {
+  extractClassUsages,
+  parseCssRules,
+  buildClassToDeclarationMap,
+  extractUniqueClasses,
+} from "./parser.js";
+
+// Co-occurrence analysis (for advanced use)
+export {
+  buildCooccurrenceMatrix,
+  matrixToCooccurrences,
+  getTopCooccurrences,
+  buildAdjacencyList,
+} from "./cooccurrence.js";
+
+// Pattern mining (for advanced use)
+export {
+  findFrequentPatterns,
+  removeSubsumedPatterns,
+  groupByClassSet,
+} from "./pattern.js";
+
+// Legacy API (convenience wrappers)
+export { optimizeCss, optimizeHtml, optimize } from "./merge.js";
+
+// MoonBit static analyzer (for Luna projects)
+export {
+  analyzeFile,
+  analyzeDirectory,
+  convertToOptimizerInput,
+  type MoonBitAnalysisResult,
+  type ConvertedResult,
+} from "./moonbit-analyzer.js";

package/src/css-optimizer/merge.ts

@@ -0,0 +1,109 @@
+/**
+ * CSS class merging utilities
+ *
+ * This module provides Luna-specific convenience wrappers around the
+ * framework-agnostic core optimizer.
+ */
+
+import type { ClassUsage, OptimizeResult, OptimizeOptions } from "./types.js";
+import { optimizeCore } from "./core.js";
+import { htmlExtractor } from "./extractors.js";
+import { htmlTransformer } from "./transformers.js";
+
+/**
+ * Framework-agnostic optimize function
+ *
+ * This is the recommended API for non-Luna projects.
+ * It takes pre-extracted class usages and a class-to-declaration map.
+ *
+ * @param usages - Class usages extracted from your source files
+ * @param css - Original CSS content
+ * @param classToDeclaration - Map from class name to CSS declaration
+ * @param options - Optimization options
+ */
+export function optimize(
+  usages: ClassUsage[],
+  css: string,
+  classToDeclaration: Map<string, string>,
+  options: OptimizeOptions = {}
+): OptimizeResult {
+  return optimizeCore(usages, css, classToDeclaration, options);
+}
+
+/**
+ * Optimize CSS by merging co-occurring classes (Luna convenience wrapper)
+ *
+ * This is a convenience function that:
+ * 1. Extracts class usages from HTML using HtmlExtractor
+ * 2. Converts Luna's declaration mapping format
+ * 3. Calls the core optimizer
+ *
+ * For non-Luna projects, use the `optimize` function instead.
+ *
+ * @param css - Original CSS content
+ * @param html - HTML content to analyze
+ * @param declarationMapping - Luna's declaration -> class name mapping
+ * @param options - Optimization options
+ */
+export function optimizeCss(
+  css: string,
+  html: string,
+  declarationMapping: Record<string, string>,
+  options: OptimizeOptions = {}
+): OptimizeResult {
+  const { classPrefix = "_", verbose = false } = options;
+
+  const log = (msg: string) => {
+    if (verbose) {
+      console.log(`[optimizer] ${msg}`);
+    }
+  };
+
+  // Step 1: Extract class usages using the HTML extractor
+  const usages = htmlExtractor.extract(html, {
+    classPrefix,
+    source: "html",
+  });
+
+  log(`Found ${usages.length} class usage sites`);
+
+  if (usages.length === 0) {
+    return {
+      css,
+      mergeMap: new Map(),
+      patterns: [],
+      stats: {
+        originalClasses: Object.keys(declarationMapping).length,
+        mergedPatterns: 0,
+        estimatedBytesSaved: 0,
+      },
+    };
+  }
+
+  // Step 2: Build class -> declaration map (reverse of Luna's mapping)
+  const classToDecl = new Map<string, string>();
+  for (const [decl, cls] of Object.entries(declarationMapping)) {
+    classToDecl.set(cls, decl);
+  }
+
+  // Step 3: Call core optimizer
+  return optimizeCore(usages, css, classToDecl, options);
+}
+
+/**
+ * Apply optimization to HTML by replacing class combinations (Luna convenience wrapper)
+ *
+ * This is a convenience function that uses HtmlTransformer.
+ * For non-Luna projects, use the transformer directly.
+ *
+ * @param html - HTML content to transform
+ * @param mergeMap - Merge map from optimizeCss result
+ * @param classPrefix - Class prefix (default: "_")
+ */
+export function optimizeHtml(
+  html: string,
+  mergeMap: Map<string, string>,
+  classPrefix = "_"
+): string {
+  return htmlTransformer.transform(html, mergeMap, { classPrefix });
+}

package/src/css-optimizer/moonbit-analyzer.ts

@@ -0,0 +1,210 @@
+/**
+ * MoonBit Static Analyzer Integration
+ *
+ * Calls the MoonBit-based CSS static analyzer to extract class co-occurrences
+ * from MoonBit source files.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ClassCooccurrence, AnalyzerWarning, ClassUsage } from "./types.js";
+
+// Lazy-loaded MoonBit analyzer module
+let analyzerModule: { analyze_file_json: (source: string, file: string) => string } | null = null;
+
+/**
+ * Get the path to the MoonBit analyzer JS module
+ */
+function getAnalyzerPath(): string {
+  // When running from dist, the analyzer is relative to the package
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+  // Try multiple possible locations
+  const candidates = [
+    // Development: from dist/ to target/ (bundled cli.mjs)
+    path.resolve(__dirname, "../../../target/js/release/build/luna/css/analyzer/analyzer.js"),
+    // Development: from src/css-optimizer/ to target/
+    path.resolve(__dirname, "../../../../target/js/release/build/luna/css/analyzer/analyzer.js"),
+    // Installed package
+    path.resolve(__dirname, "../moonbit/analyzer.js"),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  throw new Error(
+    `MoonBit analyzer not found. Tried:\n${candidates.join("\n")}\nRun 'moon build --target js src/luna/css/analyzer' first.`
+  );
+}
+
+/**
+ * Load the MoonBit analyzer module
+ */
+async function loadAnalyzer(): Promise<typeof analyzerModule> {
+  if (analyzerModule) {
+    return analyzerModule;
+  }
+
+  const analyzerPath = getAnalyzerPath();
+  analyzerModule = await import(analyzerPath);
+  return analyzerModule;
+}
+
+/**
+ * Result from analyzing a single file
+ */
+export interface MoonBitAnalysisResult {
+  cooccurrences: ClassCooccurrence[];
+  warnings: AnalyzerWarning[];
+}
+
+/**
+ * Analyze a single MoonBit source file
+ */
+export async function analyzeFile(
+  source: string,
+  filePath: string
+): Promise<MoonBitAnalysisResult> {
+  const analyzer = await loadAnalyzer();
+  if (!analyzer) {
+    throw new Error("Failed to load MoonBit analyzer");
+  }
+
+  const jsonResult = analyzer.analyze_file_json(source, filePath);
+  return JSON.parse(jsonResult);
+}
+
+/**
+ * Analyze all .mbt files in a directory
+ */
+export async function analyzeDirectory(
+  dir: string,
+  options: { recursive?: boolean } = {}
+): Promise<MoonBitAnalysisResult> {
+  const { recursive = true } = options;
+  const allCooccurrences: ClassCooccurrence[] = [];
+  const allWarnings: AnalyzerWarning[] = [];
+
+  const files = findMbtFiles(dir, recursive);
+
+  for (const file of files) {
+    const source = fs.readFileSync(file, "utf-8");
+    const result = await analyzeFile(source, file);
+    allCooccurrences.push(...result.cooccurrences);
+    allWarnings.push(...result.warnings);
+  }
+
+  return {
+    cooccurrences: allCooccurrences,
+    warnings: allWarnings,
+  };
+}
+
+/**
+ * Find all .mbt files in a directory
+ */
+function findMbtFiles(dir: string, recursive: boolean): string[] {
+  const files: string[] = [];
+
+  function walk(currentDir: string) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        // Skip common non-source directories
+        if (
+          entry.name === "node_modules" ||
+          entry.name === "target" ||
+          entry.name === ".git" ||
+          entry.name === ".mooncakes"
+        ) {
+          continue;
+        }
+
+        if (recursive) {
+          walk(fullPath);
+        }
+      } else if (entry.isFile() && entry.name.endsWith(".mbt")) {
+        // Skip test files
+        if (!entry.name.endsWith("_test.mbt")) {
+          files.push(fullPath);
+        }
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+/**
+ * Convert MoonBit analysis result to css-optimizer input format
+ */
+export interface ConvertedResult {
+  /** Class usages in css-optimizer format */
+  usages: ClassUsage[];
+  /** Map from class name to CSS declaration */
+  classToDeclaration: Map<string, string>;
+}
+
+/**
+ * Convert MoonBit analyzer output to css-optimizer format
+ *
+ * @param result - MoonBit analysis result
+ * @param hashFn - Function to generate class name from declaration
+ */
+export function convertToOptimizerInput(
+  result: MoonBitAnalysisResult,
+  hashFn: (decl: string) => string
+): ConvertedResult {
+  const classToDeclaration = new Map<string, string>();
+  const usages: ClassUsage[] = [];
+
+  for (const co of result.cooccurrences) {
+    // Only process static patterns (can be safely optimized)
+    if (!co.isStatic) continue;
+
+    const classes: string[] = [];
+
+    for (const decl of co.classes) {
+      const className = hashFn(decl);
+      classToDeclaration.set(className, decl);
+      classes.push(className);
+    }
+
+    usages.push({
+      classes,
+      source: `${co.file}:${co.line}`,
+    });
+  }
+
+  return { usages, classToDeclaration };
+}
+
+/**
+ * CLI entry point for testing
+ */
+export async function main(args: string[]): Promise<void> {
+  const dir = args[0] || ".";
+
+  console.error(`Analyzing MoonBit files in: ${dir}`);
+
+  const result = await analyzeDirectory(dir);
+
+  console.log(JSON.stringify(result, null, 2));
+
+  if (result.warnings.length > 0) {
+    console.error(`\nWarnings: ${result.warnings.length}`);
+    for (const w of result.warnings) {
+      console.error(`  ${w.file}:${w.line} - ${w.kind}: ${w.message}`);
+    }
+  }
+
+  console.error(`\nFound ${result.cooccurrences.length} class co-occurrences`);
+}

package/src/css-optimizer/parser.ts

@@ -0,0 +1,120 @@
+/**
+ * HTML and CSS parsing utilities
+ */
+
+import type { ClassUsage, CssRule } from "./types.js";
+
+/**
+ * Pattern to match class attributes in HTML
+ */
+const CLASS_ATTR_PATTERN = /class\s*=\s*"([^"]+)"/g;
+
+/**
+ * Pattern to match CSS rules
+ */
+const CSS_RULE_PATTERN = /\.([a-zA-Z_][a-zA-Z0-9_-]*)\s*\{([^}]+)\}/g;
+
+/**
+ * Extract class usages from HTML content
+ * @param html - HTML content
+ * @param source - Source identifier for debugging
+ * @param classPrefix - Only extract classes starting with this prefix
+ */
+export function extractClassUsages(
+  html: string,
+  source = "html",
+  classPrefix = "_"
+): ClassUsage[] {
+  const usages: ClassUsage[] = [];
+  let match: RegExpExecArray | null;
+
+  CLASS_ATTR_PATTERN.lastIndex = 0;
+  while ((match = CLASS_ATTR_PATTERN.exec(html)) !== 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 consider elements with 2+ matching classes
+    if (classes.length >= 2) {
+      // Sort for consistent ordering
+      classes.sort();
+      usages.push({ classes, source: `${source}:${match.index}` });
+    }
+  }
+
+  return usages;
+}
+
+/**
+ * Parse CSS rules from CSS content
+ * @param css - CSS content
+ */
+export function parseCssRules(css: string): CssRule[] {
+  const rules: CssRule[] = [];
+  let match: RegExpExecArray | null;
+
+  CSS_RULE_PATTERN.lastIndex = 0;
+  while ((match = CSS_RULE_PATTERN.exec(css)) !== null) {
+    rules.push({
+      selector: match[1],
+      declarations: match[2].trim(),
+    });
+  }
+
+  return rules;
+}
+
+/**
+ * Build a mapping from class name to CSS declaration
+ * @param css - CSS content
+ * @param classPrefix - Class prefix filter
+ */
+export function buildClassToDeclarationMap(
+  css: string,
+  classPrefix = "_"
+): Map<string, string> {
+  const map = new Map<string, string>();
+  const rules = parseCssRules(css);
+
+  for (const rule of rules) {
+    if (rule.selector.startsWith(classPrefix)) {
+      // Normalize declarations (remove extra whitespace)
+      const normalized = rule.declarations
+        .split(";")
+        .map((d) => d.trim())
+        .filter((d) => d)
+        .join(";");
+      map.set(rule.selector, normalized);
+    }
+  }
+
+  return map;
+}
+
+/**
+ * Extract all unique classes from HTML
+ * @param html - HTML content
+ * @param classPrefix - Class prefix filter
+ */
+export function extractUniqueClasses(html: string, classPrefix = "_"): Set<string> {
+  const classes = new Set<string>();
+  let match: RegExpExecArray | null;
+
+  CLASS_ATTR_PATTERN.lastIndex = 0;
+  while ((match = CLASS_ATTR_PATTERN.exec(html)) !== null) {
+    const classValue = match[1].trim();
+    if (!classValue) continue;
+
+    for (const cls of classValue.split(/\s+/)) {
+      if (cls.startsWith(classPrefix) && cls.length > classPrefix.length) {
+        classes.add(cls);
+      }
+    }
+  }
+
+  return classes;
+}