cataract 0.1.0

data/benchmarks/benchmark_merging.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'benchmark_harness'
+
+# Load the local development version, not installed gem
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'cataract'
+
+# CSS Merging Benchmark
+class MergingBenchmark < BenchmarkHarness
+  def self.benchmark_name
+    'merging'
+  end
+
+  def self.description
+    'Time to merge multiple CSS rule sets with same selector'
+  end
+
+  def self.metadata
+    {
+      'test_cases' => [
+        {
+          'name' => 'No shorthand properties (large)',
+          'key' => 'no_shorthand',
+          'css' => (".test { color: red; background-color: blue; display: block; position: relative; width: 100px; height: 50px; }\n" * 100)
+        },
+        {
+          'name' => 'Simple properties',
+          'key' => 'simple',
+          'css' => ".test { color: black; margin: 10px; }\n.test { padding: 5px; }"
+        },
+        {
+          'name' => 'Cascade with specificity',
+          'key' => 'cascade',
+          'css' => ".test { color: black; }\n#test { color: red; }\n.test { margin: 10px; }"
+        },
+        {
+          'name' => 'Important declarations',
+          'key' => 'important',
+          'css' => ".test { color: black !important; }\n#test { color: red; }\n.test { margin: 10px; }"
+        },
+        {
+          'name' => 'Shorthand expansion',
+          'key' => 'shorthand',
+          'css' => ".test { margin: 10px 20px; }\n.test { margin-left: 5px; }\n.test { padding: 1em 2em 3em 4em; }"
+        },
+        {
+          'name' => 'Complex merging',
+          'key' => 'complex',
+          'css' => "body { margin: 0; padding: 0; }\n.container { width: 100%; margin: 0 auto; }\n#main { background: white; color: black; }\n.button { padding: 10px 20px; border: 1px solid #ccc; }\n.button:hover { background: #f0f0f0; }\n.button.primary { background: blue !important; color: white; }"
+        }
+      ]
+    }
+  end
+
+  def self.speedup_config
+    {
+      baseline_matcher: SpeedupCalculator::Matchers.css_parser,
+      comparison_matcher: SpeedupCalculator::Matchers.cataract,
+      test_case_key: :key
+    }
+  end
+
+  def sanity_checks
+    require 'css_parser'
+
+    # Verify merging works correctly
+    css = ".test { color: black; }\n.test { margin: 10px; }"
+    cataract_rules = Cataract.parse_css(css)
+    cataract_merged = Cataract.merge(cataract_rules)
+
+    raise 'Cataract merge failed' if cataract_merged.rules.empty?
+
+    merged_decls = cataract_merged.rules.first.declarations
+    raise 'Cataract merge incorrect' unless merged_decls.any? { |d| d.property == 'color' }
+  end
+
+  def call
+    self.class.metadata['test_cases'].each do |test_case|
+      benchmark_test_case(test_case)
+    end
+  end
+
+  private
+
+  def benchmark_test_case(test_case)
+    puts '=' * 80
+    puts "TEST: #{test_case['name']}"
+    puts '=' * 80
+
+    key = test_case['key']
+    css = test_case['css']
+
+    # Pre-parse the CSS for both implementations
+    cataract_rules = Cataract.parse_css(css)
+
+    parser = CssParser::Parser.new
+    parser.add_block!(css)
+    rule_sets = []
+    parser.each_selector do |selector, declarations, _specificity|
+      rule_sets << CssParser::RuleSet.new(selectors: selector, block: declarations)
+    end
+
+    benchmark(key) do |x|
+      x.config(time: 5, warmup: 2)
+
+      x.report("css_parser: #{key}") do
+        CssParser.merge(rule_sets)
+      end
+
+      x.report("cataract: #{key}") do
+        Cataract.merge(cataract_rules)
+      end
+
+      x.compare!
+    end
+  end
+end
+
+# Run if executed directly
+MergingBenchmark.run if __FILE__ == $PROGRAM_NAME

data/benchmarks/benchmark_optimization_comparison.rb

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'benchmark/ips'
+require 'optparse'
+
+# Load the local development version, not installed gem
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'cataract'
+
+# =============================================================================
+# Generic Optimization Comparison Benchmark
+# =============================================================================
+#
+# This benchmark compares performance between different compile-time
+# optimizations using benchmark-ips's hold! functionality.
+#
+# Usage:
+#   1. Compile with baseline configuration:
+#      $ rake clean compile
+#      $ ruby test/benchmarks/benchmark_optimization_comparison.rb --baseline
+#
+#   2. In same terminal, compile with optimization:
+#      $ rake clean && env USE_LIKELY_UNLIKELY=1 rake compile
+#      $ ruby test/benchmarks/benchmark_optimization_comparison.rb --optimized
+#
+#   3. benchmark-ips will show comparison results from both runs
+#
+# The benchmark tests merge/cascade performance on bootstrap.css (~10k rules).
+# =============================================================================
+
+module OptimizationBenchmark
+  def self.run(variant: nil)
+    puts '=' * 80
+    puts 'OPTIMIZATION COMPARISON BENCHMARK'
+    puts '=' * 80
+
+    # Display current compile-time flags
+    puts "\nCurrently compiled with:"
+    Cataract::COMPILE_FLAGS.each do |flag, enabled|
+      status = enabled ? '✓ ENABLED' : '✗ disabled'
+      puts "  #{flag}: #{status}"
+    end
+    puts ''
+
+    # Load bootstrap.css fixture
+    fixtures_dir = File.expand_path('../test/fixtures', __dir__)
+    bootstrap_css_path = File.join(fixtures_dir, 'bootstrap.css')
+
+    unless File.exist?(bootstrap_css_path)
+      puts "❌ ERROR: bootstrap.css not found at #{bootstrap_css_path}"
+      exit 1
+    end
+
+    bootstrap_css = File.read(bootstrap_css_path)
+    puts 'Test file: bootstrap.css'
+    puts "  Lines: #{bootstrap_css.lines.count}"
+    puts "  Size: #{bootstrap_css.bytesize} bytes (#{(bootstrap_css.bytesize / 1024.0).round(1)} KB)"
+
+    # Parse once to get rules for merge benchmark
+    puts "\nParsing bootstrap.css to get rules..."
+    parser = Cataract::Stylesheet.new
+    begin
+      parser.add_block(bootstrap_css)
+      rules = parser.instance_variable_get(:@raw_rules) # Get raw rules array
+      puts "  ✅ Parsed successfully (#{rules.length} rules)"
+    rescue StandardError => e
+      puts "  ❌ ERROR: Failed to parse: #{e.message}"
+      exit 1
+    end
+
+    # Verify merge works before benchmarking
+    puts "\nVerifying merge..."
+    begin
+      merged = Cataract.apply_cascade(rules)
+      puts "  ✅ Merged successfully (#{merged.length} declarations)"
+    rescue StandardError => e
+      puts "  ❌ ERROR: Failed to merge: #{e.message}"
+      exit 1
+    end
+
+    # Auto-detect variant if not specified
+    if variant.nil?
+      # Check any optimization flag
+      has_optimization = Cataract::COMPILE_FLAGS.any? do |flag, enabled|
+        enabled && flag != :str_buf_optimization && flag != :debug
+      end
+      variant = has_optimization ? 'optimized' : 'baseline'
+    end
+
+    puts "\n#{'=' * 80}"
+    puts "RUNNING BENCHMARK (variant: #{variant})"
+    puts '=' * 80
+    puts 'Timing: 20s measurement, 5s warmup'
+    puts ''
+
+    Benchmark.ips do |x|
+      x.config(time: 20, warmup: 5)
+
+      x.report("merge_bootstrap_#{variant}") do
+        Cataract.apply_cascade(rules)
+      end
+    end
+
+    puts "\n#{'=' * 80}"
+    puts "DONE - #{variant}"
+    puts '=' * 80
+  end
+
+  def self.print_usage
+    puts <<~USAGE
+      Usage: #{$PROGRAM_NAME}
+
+      This benchmark will automatically detect which variant is compiled
+      and run the appropriate test.
+
+      Workflow:
+        # 1. Build baseline
+        rake clean && rake compile
+        ruby test/benchmarks/benchmark_optimization_comparison.rb --baseline
+
+        # 2. Build with optimization (e.g., LIKELY/UNLIKELY)
+        rake clean && USE_LIKELY_UNLIKELY=1 rake compile
+        ruby test/benchmarks/benchmark_optimization_comparison.rb --optimized
+
+        # 3. Compare results (benchmark-ips will show comparison automatically)
+
+      Specific optimization flags:
+        LIKELY/UNLIKELY:
+          USE_LIKELY_UNLIKELY=1 rake compile
+
+        Loop unrolling (raw CFLAGS still work):
+          CFLAGS="-funroll-loops" rake compile
+
+        Aggressive optimization:
+          CFLAGS="-O3 -march=native -funroll-loops" rake compile
+    USAGE
+  end
+end
+
+# =============================================================================
+# Main
+# =============================================================================
+
+if __FILE__ == $PROGRAM_NAME
+  require 'optparse'
+
+  variant = nil
+
+  OptionParser.new do |opts|
+    opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
+
+    opts.on('--baseline', 'Run benchmark labeled as baseline') do
+      variant = 'baseline'
+    end
+
+    opts.on('--optimized', 'Run benchmark labeled as optimized') do
+      variant = 'optimized'
+    end
+
+    opts.on('-h', '--help', 'Show this help message') do
+      OptimizationBenchmark.print_usage
+      exit 0
+    end
+  end.parse!
+
+  OptimizationBenchmark.run(variant: variant)
+end

data/benchmarks/benchmark_parsing.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require_relative 'benchmark_harness'
+
+# Load the local development version, not installed gem
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'cataract'
+
+# CSS Parsing Performance Benchmark
+class ParsingBenchmark < BenchmarkHarness
+  def self.benchmark_name
+    'parsing'
+  end
+
+  def self.description
+    'Time to parse CSS into internal data structures'
+  end
+
+  def self.metadata
+    instance = new
+    {
+      'test_cases' => [
+        {
+          'name' => "Small CSS (#{instance.css1.lines.count} lines, #{(instance.css1.length / 1024.0).round(1)}KB)",
+          'fixture' => 'CSS1',
+          'lines' => instance.css1.lines.count,
+          'bytes' => instance.css1.length
+        },
+        {
+          'name' => "Medium CSS with @media (#{instance.css2.lines.count} lines, #{(instance.css2.length / 1024.0).round(1)}KB)",
+          'fixture' => 'CSS2',
+          'lines' => instance.css2.lines.count,
+          'bytes' => instance.css2.length
+        }
+      ]
+      # speedups will be calculated automatically by harness
+    }
+  end
+
+  # Uses default speedup_config from harness (css_parser vs cataract, test_case_key: :fixture)
+
+  def sanity_checks
+    # Check css_parser gem is available
+    require 'css_parser'
+
+    # Verify fixtures parse correctly
+    parser = Cataract::Stylesheet.new
+    parser.add_block(css1)
+    raise 'CSS1 sanity check failed: expected rules' if parser.rules_count.zero?
+
+    parser = Cataract::Stylesheet.new
+    parser.add_block(css2)
+    raise 'CSS2 sanity check failed: expected rules' if parser.rules_count.zero?
+  end
+
+  def call
+    run_css1_benchmark
+    run_css2_benchmark
+    show_correctness_comparison
+  end
+
+  def css1
+    @css1 ||= File.read(File.join(fixtures_dir, 'css1_sample.css'))
+  end
+
+  def css2
+    @css2 ||= File.read(File.join(fixtures_dir, 'css2_sample.css'))
+  end
+
+  private
+
+  def fixtures_dir
+    @fixtures_dir ||= File.expand_path('../test/fixtures', __dir__)
+  end
+
+  def run_css1_benchmark
+    puts '=' * 80
+    puts "TEST: CSS1 (#{css1.lines.count} lines, #{css1.length} chars)"
+    puts '=' * 80
+
+    benchmark('css1') do |x|
+      x.config(time: 5, warmup: 2)
+
+      x.report('css_parser gem: CSS1') do
+        parser = CssParser::Parser.new(import: false, io_exceptions: false)
+        parser.add_block!(css1)
+      end
+
+      x.report('cataract: CSS1') do
+        parser = Cataract::Stylesheet.new
+        parser.add_block(css1)
+      end
+
+      x.compare!
+    end
+  end
+
+  def run_css2_benchmark
+    puts "\n#{'=' * 80}"
+    puts "TEST: CSS2 with @media (#{css2.lines.count} lines, #{css2.length} chars)"
+    puts '=' * 80
+
+    benchmark('css2') do |x|
+      x.config(time: 5, warmup: 2)
+
+      x.report('css_parser gem: CSS2') do
+        parser = CssParser::Parser.new(import: false, io_exceptions: false)
+        parser.add_block!(css2)
+      end
+
+      x.report('cataract: CSS2') do
+        parser = Cataract::Stylesheet.new
+        parser.add_block(css2)
+      end
+
+      x.compare!
+    end
+  end
+
+  def show_correctness_comparison
+    puts "\n#{'=' * 80}"
+    puts 'CORRECTNESS VALIDATION (CSS2)'
+    puts '=' * 80
+
+    # Test Cataract
+    parser = Cataract::Stylesheet.new
+    parser.add_block(css2)
+    cataract_rules = parser.rules_count
+    puts "Cataract found #{cataract_rules} rules"
+
+    # Test css_parser
+    css_parser = CssParser::Parser.new(import: false, io_exceptions: false)
+    css_parser.add_block!(css2)
+    css_parser_rules = 0
+    css_parser.each_selector { css_parser_rules += 1 }
+    puts "css_parser found #{css_parser_rules} rules"
+
+    unless cataract_rules == css_parser_rules
+      puts '⚠️  Different number of rules parsed'
+      puts '    Note: css_parser has a known bug with ::after pseudo-elements'
+      puts '    (it concatenates them with previous rules instead of parsing separately)'
+    end
+
+    # Show sample output
+    puts "\nSample Cataract output:"
+    parser.select(&:selector?).first(5).each do |rule|
+      puts "  #{rule.selector}: #{rule.declarations} (spec: #{rule.specificity})"
+    end
+  end
+end
+
+# Run if executed directly
+ParsingBenchmark.run if __FILE__ == $PROGRAM_NAME

data/benchmarks/benchmark_ragel_removal.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'benchmark/ips'
+
+# Load the local development version, not installed gem
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'cataract'
+
+# Get current branch name
+branch = `git rev-parse --abbrev-ref HEAD`.strip
+
+puts '=' * 80
+puts 'RAGEL REMOVAL BENCHMARK - Parsing Performance Comparison'
+puts '=' * 80
+puts "Current branch: #{branch}"
+puts
+
+# Load bootstrap.css fixture (large real-world CSS file)
+fixtures_dir = File.expand_path('../test/fixtures', __dir__)
+bootstrap_css = File.read(File.join(fixtures_dir, 'bootstrap.css'))
+
+puts "Bootstrap CSS: #{bootstrap_css.lines.count} lines, #{bootstrap_css.bytesize} bytes"
+puts
+
+# Verify parsing works
+puts 'Verifying parsing works...'
+parser = Cataract::Stylesheet.new
+parser.add_block(bootstrap_css)
+puts "  ✅ Parsed successfully (#{parser.rules_count} rules)"
+puts
+
+puts '=' * 80
+puts 'BENCHMARK: Bootstrap CSS Parsing'
+puts '=' * 80
+puts
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("#{branch}:parse_bootstrap") do
+    parser = Cataract::Stylesheet.new
+    parser.add_block(bootstrap_css)
+  end
+
+  x.compare!
+
+  # Save results to file for cross-branch comparison
+  x.save! 'test/.benchmark_results/ragel_removal.json'
+  x.hold! 'test/.benchmark_results/ragel_removal.json'
+end
+
+puts
+puts '=' * 80
+puts 'Results saved to test/.benchmark_results/ragel_removal.json'
+puts 'Switch git branches, recompile, and run again to compare!'
+puts '=' * 80

data/benchmarks/benchmark_runner.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'benchmark/ips'
+require 'json'
+require 'fileutils'
+
+# Unified benchmark runner that outputs both human-readable console output
+# and structured JSON for documentation generation.
+class BenchmarkRunner
+  RESULTS_DIR = File.expand_path('.results', __dir__)
+
+  attr_reader :name, :description, :metadata
+
+  # @param name [String] Short name for this benchmark (e.g., "parsing", "specificity")
+  # @param description [String] One-line description of what's being measured
+  # @param metadata [Hash] Additional metadata (fixture info, test cases, etc.)
+  def initialize(name:, description:, metadata: {})
+    @name = name
+    @description = description
+    @metadata = metadata
+    @results = []
+
+    FileUtils.mkdir_p(RESULTS_DIR)
+  end
+
+  # Run a benchmark-ips block and capture results
+  # @yield [Benchmark::IPS::Job] The benchmark-ips job
+  def run
+    json_path = File.join(RESULTS_DIR, "#{@name}.json")
+
+    Benchmark.ips do |x|
+      # Allow benchmark to configure itself
+      yield x
+
+      # Enable JSON output
+      x.json!(json_path)
+    end
+
+    # Read the generated JSON and enhance with metadata
+    raw_data = JSON.parse(File.read(json_path))
+    enhanced_data = {
+      'name' => @name,
+      'description' => @description,
+      'metadata' => @metadata,
+      'timestamp' => Time.now.iso8601,
+      'results' => raw_data
+    }
+
+    File.write(json_path, JSON.pretty_generate(enhanced_data))
+  end
+
+  # Helper to format results as a comparison hash
+  # @param label [String] Label for this result
+  # @param baseline [String] Baseline label to compare against
+  # @return [Hash] Structured comparison data
+  def self.format_comparison(label:, baseline:, results:)
+    baseline_result = results.find { |r| r['name'] == baseline }
+    comparison_result = results.find { |r| r['name'] == label }
+
+    return nil unless baseline_result && comparison_result
+
+    speedup = comparison_result['central_tendency'].to_f / baseline_result['central_tendency']
+
+    {
+      'label' => label,
+      'baseline' => baseline,
+      'speedup' => speedup.round(2)
+    }
+  end
+end