cataract 0.1.2 → 0.1.4

data/benchmarks/benchmark_harness.rb

@@ -1,193 +0,0 @@
-# frozen_string_literal: true
-
-require 'benchmark/ips'
-require 'json'
-require 'fileutils'
-require_relative 'system_metadata'
-require_relative 'speedup_calculator'
-
-# Base class for all benchmarks. Provides structure and automatic JSON output.
-#
-# Usage:
-#   class MyBenchmark < BenchmarkHarness
-#     def self.benchmark_name
-#       'my_benchmark'
-#     end
-#
-#     def self.description
-#       'What this benchmark measures'
-#     end
-#
-#     def self.metadata
-#       { 'key' => 'value' } # Optional metadata for docs
-#     end
-#
-#     def self.sanity_checks
-#       # Optional: verify code works before benchmarking
-#       raise "Sanity check failed!" unless something_works
-#     end
-#
-#     def self.call
-#       run_test_case_1
-#       run_test_case_2
-#     end
-#
-#     private
-#
-#     def self.run_test_case_1
-#       benchmark('test_case_1') do |x|
-#         x.config(time: 5, warmup: 2)
-#         x.report('label') { ... }
-#         x.compare!
-#       end
-#     end
-#   end
-class BenchmarkHarness
-  RESULTS_DIR = File.expand_path('.results', __dir__)
-
-  class << self
-    # Abstract methods - must be implemented by subclasses
-    def benchmark_name
-      raise NotImplementedError, "#{self} must implement .benchmark_name"
-    end
-
-    def description
-      raise NotImplementedError, "#{self} must implement .description"
-    end
-
-    def metadata
-      {} # Optional, can be overridden
-    end
-
-    def sanity_checks
-      # Optional, can be overridden
-    end
-
-    def call
-      raise NotImplementedError, "#{self} must implement .call"
-    end
-
-    # Optional: Define how to calculate speedups for this benchmark
-    # Override this to customize speedup calculation
-    #
-    # IMPORTANT: Result names must follow convention "tool_name: test_case_id"
-    #
-    # @return [Hash] Configuration for SpeedupCalculator
-    #   {
-    #     baseline_matcher: Proc,      # Returns true for baseline results
-    #     comparison_matcher: Proc,    # Returns true for comparison results
-    #     test_case_key: Symbol        # Key in test_cases metadata matching test_case_id
-    #   }
-    def speedup_config
-      # Default: compare css_parser (baseline) vs cataract (comparison)
-      # Match to test_cases by 'fixture' key
-      {
-        baseline_matcher: SpeedupCalculator::Matchers.css_parser,
-        comparison_matcher: SpeedupCalculator::Matchers.cataract,
-        test_case_key: :fixture
-      }
-    end
-
-    # Main entry point - handles setup, execution, and cleanup
-    def run
-      instance = new
-      setup
-      instance.sanity_checks if instance.respond_to?(:sanity_checks, true)
-      instance.call
-      finalize(instance)
-    rescue StandardError => e
-      puts "❌ Benchmark failed: #{e.message}"
-      puts e.backtrace.first(5).join("\n")
-      exit 1
-    end
-
-    private
-
-    def setup
-      FileUtils.mkdir_p(RESULTS_DIR)
-
-      # Collect system metadata once per run
-      unless File.exist?(File.join(RESULTS_DIR, 'metadata.json'))
-        SystemMetadata.collect
-      end
-
-      # Print header
-      puts "\n\n"
-      puts '=' * 80
-      puts "#{benchmark_name.upcase.tr('_', ' ')} BENCHMARK"
-      puts "Measures: #{description}"
-      puts '=' * 80
-      puts
-    end
-
-    def finalize(instance)
-      # Combine all JSON files for this benchmark into one
-      return unless instance.instance_variable_defined?(:@json_files) && instance.instance_variable_get(:@json_files)&.any?
-
-      json_files = instance.instance_variable_get(:@json_files)
-
-      combined_data = {
-        'name' => benchmark_name,
-        'description' => description,
-        'metadata' => metadata,
-        'timestamp' => Time.now.iso8601,
-        'results' => []
-      }
-
-      # Read all the individual JSON files
-      json_files.each do |filename|
-        path = File.join(RESULTS_DIR, filename)
-        next unless File.exist?(path)
-
-        data = JSON.parse(File.read(path))
-        combined_data['results'].concat(data) if data.is_a?(Array)
-      end
-
-      # Calculate speedups using configured strategy
-      config = speedup_config
-      if config
-        calculator = SpeedupCalculator.new(
-          results: combined_data['results'],
-          test_cases: combined_data['metadata']['test_cases'],
-          baseline_matcher: config[:baseline_matcher],
-          comparison_matcher: config[:comparison_matcher],
-          test_case_key: config[:test_case_key]
-        )
-
-        speedup_stats = calculator.calculate
-        combined_data['metadata']['speedups'] = speedup_stats if speedup_stats
-      end
-
-      # Write combined file
-      combined_path = File.join(RESULTS_DIR, "#{benchmark_name}.json")
-      File.write(combined_path, JSON.pretty_generate(combined_data))
-
-      # Clean up individual files
-      json_files.each do |filename|
-        File.delete(File.join(RESULTS_DIR, filename))
-      end
-
-      puts "\n✓ Results saved to #{combined_path}"
-    end
-  end
-
-  # Instance methods
-  protected
-
-  def benchmark(test_case_name)
-    json_filename = "#{self.class.benchmark_name}_#{test_case_name}.json"
-    json_path = File.join(RESULTS_DIR, json_filename)
-
-    Benchmark.ips do |x|
-      # Automatically enable JSON output
-      x.json!(json_path)
-
-      # Let the benchmark configure and run
-      yield x
-    end
-
-    # Track that we created this file
-    @json_files ||= []
-    @json_files << json_filename
-  end
-end

data/benchmarks/benchmark_merging.rb

@@ -1,121 +0,0 @@
-# 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

@@ -1,168 +0,0 @@
-#!/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

@@ -1,153 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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