cataract 0.1.2 → 0.1.4

data/benchmarks/benchmark_string_allocation.rb

@@ -1,151 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# Benchmark string allocation optimization impact
-# This compares parsing performance with rb_str_buf_new vs rb_str_new_cstr
-#
-# Usage:
-#   1. Run without optimization:
-#      rake compile && ruby test/benchmarks/benchmark_string_allocation.rb
-#
-#   2. Recompile with optimization:
-#      CFLAGS="-DUSE_STR_BUF_OPTIMIZATION" rake compile
-#
-#   3. Run with optimization:
-#      ruby test/benchmarks/benchmark_string_allocation.rb
-#
-# The benchmark will automatically detect which version is running and save
-# results to a JSON file for comparison.
-
-require 'benchmark/ips'
-require 'fileutils'
-
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-# State files for benchmark-ips to compare across runs
-# Store in hidden directory to keep them out of the way
-# Use separate files for each test so we only compare like-to-like
-RESULTS_DIR = File.expand_path('.benchmark_results', __dir__)
-FileUtils.mkdir_p(RESULTS_DIR)
-
-RESULTS_FILE_PARSE = File.join(RESULTS_DIR, 'string_allocation_parse.json')
-RESULTS_FILE_ITERATE = File.join(RESULTS_DIR, 'string_allocation_iterate.json')
-RESULTS_FILE_10X = File.join(RESULTS_DIR, 'string_allocation_10x.json')
-
-# Large CSS fixture - using Bootstrap 5 CSS for realistic benchmark
-LARGE_CSS_FIXTURE = File.read(File.expand_path('../test/fixtures/bootstrap.css', __dir__))
-
-# Detect which version we're running by checking the compile-time constant
-actual_mode = Cataract::STRING_ALLOC_MODE
-# Label based on what's actually running (buffer is the default/production mode)
-mode_label = actual_mode == :buffer ? 'buffer' : 'dynamic'
-
-puts '=' * 80
-puts 'String Allocation Optimization Benchmark'
-puts '=' * 80
-puts "Ruby version: #{RUBY_VERSION}"
-puts "String allocation mode: #{actual_mode.inspect}"
-if actual_mode == :buffer
-  puts '  → Using rb_str_buf_new (pre-allocated buffers, production default)'
-else
-  puts '  → Using rb_str_new_cstr (dynamic allocation, disabled for comparison)'
-end
-puts '=' * 80
-puts
-puts 'This benchmark focuses on at-rules that build selector strings:'
-puts '  - @font-face (large descriptor blocks)'
-puts '  - @property (selector with prelude)'
-puts '  - @keyframes (selector building)'
-puts '  - @page (selector with pseudo)'
-puts '  - @counter-style (selector with name)'
-puts
-puts "CSS fixture: #{LARGE_CSS_FIXTURE.lines.count} lines, #{LARGE_CSS_FIXTURE.bytesize} bytes"
-puts '=' * 80
-puts
-
-parser = Cataract::Stylesheet.new
-parser.add_block(LARGE_CSS_FIXTURE)
-GC.start
-# Verify we actually parsed everything
-raise 'Parse failed' if parser.rules_count.zero?
-
-puts "\n#{'=' * 80}"
-puts 'TEST 1: Parse CSS with many at-rules'
-puts '=' * 80
-
-Benchmark.ips do |x|
-  x.config(time: 10, warmup: 2)
-
-  x.report(mode_label) do
-    parser = Cataract::Stylesheet.new
-    parser.add_block(LARGE_CSS_FIXTURE)
-  end
-
-  x.save! RESULTS_FILE_PARSE
-  x.compare!
-end
-
-GC.start
-
-puts "\n#{'=' * 80}"
-puts 'TEST 2: Parse + iterate through all rules'
-puts '=' * 80
-
-Benchmark.ips do |x|
-  x.config(time: 10, warmup: 2)
-
-  x.report(mode_label) do
-    parser = Cataract::Stylesheet.new
-    parser.add_block(LARGE_CSS_FIXTURE)
-
-    count = 0
-    parser.select(&:selector?).each do |rule|
-      # Force string to be used
-      _ = rule.selector.length
-      _ = rule.declarations.to_s
-      count += 1
-    end
-
-    raise 'No rules found' if count.zero?
-  end
-
-  x.save! RESULTS_FILE_ITERATE
-  x.compare!
-end
-
-GC.start
-
-puts "\n#{'=' * 80}"
-puts 'TEST 3: Multiple parse operations (10x)'
-puts '=' * 80
-
-Benchmark.ips do |x|
-  x.config(time: 10, warmup: 2)
-
-  x.report(mode_label) do
-    10.times do
-      parser = Cataract::Stylesheet.new
-      parser.add_block(LARGE_CSS_FIXTURE)
-    end
-  end
-
-  x.save! RESULTS_FILE_10X
-  x.compare!
-end
-
-puts "\n#{'=' * 80}"
-puts 'Results saved to:'
-puts "  - #{RESULTS_FILE_PARSE}"
-puts "  - #{RESULTS_FILE_ITERATE}"
-puts "  - #{RESULTS_FILE_10X}"
-puts ''
-puts 'To compare dynamic vs buffer (default):'
-puts '  1. Run with dynamic: DISABLE_STR_BUF_OPTIMIZATION=1 rake compile && ruby test/benchmarks/benchmark_string_allocation.rb'
-puts '  2. Run with buffer:  rake compile && ruby test/benchmarks/benchmark_string_allocation.rb'
-puts '  3. Each test will automatically compare buffer vs dynamic'
-puts ''
-puts 'The benchmark verifies the compilation mode via Cataract::STRING_ALLOC_MODE'
-puts '  :dynamic = rb_str_new_cstr (dynamic allocation)'
-puts '  :buffer  = rb_str_buf_new (pre-allocated, production default)'
-puts '=' * 80

data/benchmarks/benchmark_stylesheet_to_s.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-require 'benchmark/ips'
-
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-puts '=' * 60
-puts 'Stylesheet#to_s: Ruby vs C Implementation'
-puts '=' * 60
-puts ''
-
-bootstrap_css = File.read('test/fixtures/bootstrap.css')
-stylesheet = Cataract.parse_css(bootstrap_css)
-
-puts "Parsing bootstrap.css: #{stylesheet.size} rules"
-puts ''
-
-# Verify both versions produce same output
-ruby_output = stylesheet.to_s
-c_output = Cataract._stylesheet_to_s_c(stylesheet.rules, stylesheet.charset)
-
-if ruby_output == c_output
-  puts '✓ Ruby and C versions produce identical output'
-else
-  puts '✗ WARNING: Ruby and C versions produce different output!'
-  puts "Ruby length: #{ruby_output.length}"
-  puts "C length: #{c_output.length}"
-
-  # Find first difference
-  ruby_output.chars.each_with_index do |char, i|
-    next unless char != c_output[i]
-
-    puts "First difference at position #{i}:"
-    puts "  Ruby: #{ruby_output[(i - 20)..(i + 20)].inspect}"
-    puts "  C:    #{c_output[(i - 20)..(i + 20)].inspect}"
-    break
-  end
-end
-
-puts ''
-puts 'Benchmarking to_s only (cache cleared each iteration)...'
-puts ''
-
-# Parse once outside benchmark
-PARSER = Cataract.parse_css(bootstrap_css)
-
-Benchmark.ips do |x|
-  x.config(time: 10, warmup: 3)
-
-  x.report('Ruby (serialize_to_css)') do
-    PARSER.instance_variable_set(:@serialized, nil)  # Clear cache
-    PARSER.to_s
-  end
-
-  x.report('C (_stylesheet_to_s_c)') do
-    PARSER.instance_variable_set(:@serialized, nil)  # Clear cache (apples-to-apples)
-    Cataract._stylesheet_to_s_c(PARSER.rules, PARSER.charset)
-  end
-
-  x.compare!
-end

data/benchmarks/benchmark_to_s_cached.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-require 'benchmark/ips'
-
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-puts '=' * 60
-puts 'CACHED to_s BENCHMARK'
-puts '=' * 60
-puts ''
-
-bootstrap_css = File.read('test/fixtures/bootstrap.css')
-
-puts 'Comparing:'
-puts '  - Fresh parse → to_s (first call, uncached)'
-puts '  - Repeated to_s (cached, should be instant)'
-puts ''
-
-Benchmark.ips do |x|
-  x.config(time: 10, warmup: 3)
-
-  x.report('parse + to_s (uncached)') do
-    stylesheet = Cataract.parse_css(bootstrap_css)
-    stylesheet.to_s
-  end
-
-  x.report('to_s (cached)') do
-    # Parse once outside the benchmark
-    stylesheet = Cataract.parse_css(bootstrap_css)
-    stylesheet.to_s # Prime cache
-
-    # Now benchmark cached access
-    stylesheet.to_s
-  end
-
-  x.compare!
-end
-
-puts ''
-puts '=' * 60
-puts 'Real-world scenario: Multiple to_s calls'
-puts '=' * 60
-puts ''
-
-stylesheet = Cataract.parse_css(bootstrap_css)
-
-puts 'Calling to_s 10 times...'
-require 'benchmark'
-time = Benchmark.measure do
-  10.times { stylesheet.to_s }
-end
-
-puts "Total time: #{time.real.round(4)}s"
-puts 'First call does all work, next 9 are free!'

data/benchmarks/benchmark_value_splitter.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-require 'benchmark/ips'
-
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-# Get current git branch
-branch = `git rev-parse --abbrev-ref HEAD 2>/dev/null`.strip
-branch = 'unknown' if branch.empty?
-
-puts '=' * 60
-puts "Value Splitter Benchmark: #{branch}"
-puts '=' * 60
-puts ''
-
-# Test cases covering different scenarios
-test_cases = {
-  'simple' => '1px 2px 3px 4px',
-  'functions' => '10px calc(100% - 20px) 5px',
-  'rgb' => 'rgb(255, 0, 0) blue rgba(0, 0, 0, 0.5)',
-  'quotes' => "'Helvetica Neue', Arial, sans-serif",
-  'complex' => "10px calc(100% - 20px) 'Font Name' rgb(255, 0, 0)",
-  'long' => '1px 2px 3px 4px 5px 6px 7px 8px 9px 10px 11px 12px 13px 14px 15px'
-}
-
-puts 'Test cases:'
-test_cases.each do |name, value|
-  result = Cataract.split_value(value)
-  puts "  #{name}: '#{value}' => #{result.length} tokens"
-end
-puts ''
-
-Benchmark.ips do |x|
-  x.config(time: 10, warmup: 3)
-
-  test_cases.each do |name, value|
-    x.report("#{branch}:#{name.ljust(12)}") do
-      Cataract.split_value(value)
-    end
-  end
-
-  x.compare!
-
-  # Save results to file for cross-branch comparison
-  x.save! 'test/.benchmark_results/value_splitter.json'
-  x.hold! 'test/.benchmark_results/value_splitter.json'
-end
-
-puts ''
-puts '=' * 60
-puts 'Results saved to test/.benchmark_results/value_splitter.json'
-puts 'Switch git branches and run again to compare!'
-puts '=' * 60

data/benchmarks/benchmark_yjit.rb

@@ -1,158 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'benchmark_harness'
-require 'open3'
-require 'json'
-
-# Load the local development version, not installed gem
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-# YJIT Benchmark Supervisor
-# Spawns two subprocesses (with/without YJIT) and combines results
-class YjitBenchmark < BenchmarkHarness
-  def self.benchmark_name
-    'yjit'
-  end
-
-  def self.description
-    'Ruby-side operations with and without YJIT'
-  end
-
-  def self.metadata
-    {
-      'operations' => [
-        'property access',
-        'declaration merging',
-        'to_s generation',
-        'parse + iterate'
-      ],
-      'note' => 'C extension performance is the same regardless of YJIT. This measures Ruby code.'
-    }
-  end
-
-  def self.speedup_config
-    # Compare without YJIT (baseline) vs with YJIT (comparison)
-    {
-      baseline_matcher: SpeedupCalculator::Matchers.without_yjit,
-      comparison_matcher: SpeedupCalculator::Matchers.with_yjit,
-      test_case_key: nil # No test_cases array, just operations
-    }
-  end
-
-  def sanity_checks
-    # Verify basic operations work
-    decls = Cataract::Declarations.new
-    decls['color'] = 'red'
-    raise 'Property access failed' unless decls['color']
-
-    parser = Cataract::Stylesheet.new
-    sample_css = 'body { margin: 0; }'
-    parser.add_block(sample_css)
-    raise 'Parse failed' if parser.rules_count.zero?
-  end
-
-  def call
-    worker_script = File.expand_path('benchmark_yjit_workers.rb', __dir__)
-
-    # Clean up any leftover worker files from previous runs
-    without_path = File.join(RESULTS_DIR, 'yjit_without.json')
-    with_path = File.join(RESULTS_DIR, 'yjit_with.json')
-    FileUtils.rm_f(without_path)
-    FileUtils.rm_f(with_path)
-
-    puts 'Running YJIT benchmarks via subprocesses...'
-    puts
-
-    # Run without YJIT
-    puts '→ Running without YJIT (--disable-yjit)...'
-    stdout_without, status_without = run_subprocess(['ruby', '--disable-yjit', worker_script])
-    unless status_without.success?
-      raise "Worker without YJIT failed:\n#{stdout_without}"
-    end
-
-    puts stdout_without
-    puts
-
-    # Run with YJIT
-    puts '→ Running with YJIT (--yjit)...'
-    stdout_with, status_with = run_subprocess(['ruby', '--yjit', worker_script])
-    unless status_with.success?
-      raise "Worker with YJIT failed:\n#{stdout_with}"
-    end
-
-    puts stdout_with
-    puts
-
-    # Combine results
-    combine_worker_results
-  end
-
-  private
-
-  def run_subprocess(command)
-    stdout, stderr, status = Open3.capture3(*command)
-
-    # Print stderr if present (warnings, etc)
-    unless stderr.empty?
-      puts "⚠️  stderr: #{stderr}"
-    end
-
-    [stdout, status]
-  end
-
-  def combine_worker_results
-    without_path = File.join(RESULTS_DIR, 'yjit_without.json')
-    with_path = File.join(RESULTS_DIR, 'yjit_with.json')
-
-    # Check both files exist
-    unless File.exist?(without_path) && File.exist?(with_path)
-      raise "Worker results not found:\n  #{without_path}\n  #{with_path}"
-    end
-
-    # Read both JSON files
-    without_data = JSON.parse(File.read(without_path))
-    with_data = JSON.parse(File.read(with_path))
-
-    # Combine into single benchmark result
-    combined_data = {
-      'name' => self.class.benchmark_name,
-      'description' => self.class.description,
-      'metadata' => self.class.metadata,
-      'timestamp' => Time.now.iso8601,
-      'results' => []
-    }
-
-    # Merge results from both workers
-    combined_data['results'].concat(without_data['results']) if without_data['results']
-    combined_data['results'].concat(with_data['results']) if with_data['results']
-
-    # Calculate speedups using configured strategy
-    config = self.class.speedup_config
-    if config
-      calculator = SpeedupCalculator.new(
-        results: combined_data['results'],
-        test_cases: combined_data['metadata']['operations'],
-        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, "#{self.class.benchmark_name}.json")
-    File.write(combined_path, JSON.pretty_generate(combined_data))
-
-    # Clean up worker files
-    File.delete(without_path)
-    File.delete(with_path)
-
-    puts "✓ Combined results saved to #{combined_path}"
-  end
-end
-
-# Run if executed directly
-YjitBenchmark.run if __FILE__ == $PROGRAM_NAME

data/benchmarks/benchmark_yjit_workers.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'benchmark_harness'
-require_relative 'yjit_tests'
-
-# Load the local development version, not installed gem
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-# Worker benchmark: YJIT disabled
-# Called via subprocess with --disable-yjit flag
-class YjitWithoutBenchmark < BenchmarkHarness
-  include YjitTests
-
-  def self.benchmark_name
-    'yjit_without'
-  end
-
-  def self.description
-    'Ruby-side operations without YJIT'
-  end
-
-  def self.metadata
-    YjitTests.metadata
-  end
-
-  def self.speedup_config
-    YjitTests.speedup_config
-  end
-end
-
-# Worker benchmark: YJIT enabled
-# Called via subprocess with --yjit flag
-class YjitWithBenchmark < BenchmarkHarness
-  include YjitTests
-
-  def self.benchmark_name
-    'yjit_with'
-  end
-
-  def self.description
-    'Ruby-side operations with YJIT'
-  end
-
-  def self.metadata
-    YjitTests.metadata
-  end
-
-  def self.speedup_config
-    YjitTests.speedup_config
-  end
-end
-
-# CLI entry point - run the appropriate worker based on YJIT status
-if __FILE__ == $PROGRAM_NAME
-  if defined?(RubyVM::YJIT.enabled?) && RubyVM::YJIT.enabled?
-    YjitWithBenchmark.run
-  else
-    YjitWithoutBenchmark.run
-  end
-end

data/benchmarks/profile_to_s.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-require 'ruby-prof'
-
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-bootstrap_css = File.read('test/fixtures/bootstrap.css')
-stylesheet = Cataract.parse_css(bootstrap_css)
-
-puts "Profiling Stylesheet#to_s on bootstrap.css (#{stylesheet.size} rules)"
-puts ''
-
-# Profile
-RubyProf.start
-
-10.times { stylesheet.to_s }
-
-result = RubyProf.stop
-
-# Print flat profile
-printer = RubyProf::FlatPrinter.new(result)
-printer.print($stdout, min_percent: 1)

data/benchmarks/speedup_calculator.rb

@@ -1,83 +0,0 @@
-# frozen_string_literal: true
-
-# Generic speedup calculator for benchmark results
-# Compares "baseline" vs "comparison" results and calculates speedup stats
-#
-# CONVENTION: Result names must use format "tool_name: test_case_id"
-# Example: "css_parser: CSS1", "cataract: CSS1"
-class SpeedupCalculator
-  # @param results [Array<Hash>] Array of benchmark results with 'name' and 'central_tendency'
-  # @param test_cases [Array<Hash>] Array of test case metadata to annotate with speedups
-  # @param baseline_matcher [Proc] Block that returns true if result is baseline (e.g., css_parser)
-  # @param comparison_matcher [Proc] Block that returns true if result is comparison (e.g., cataract)
-  # @param test_case_key [Symbol] Key in test_cases hash to match against test case id from result name
-  def initialize(results:, test_cases:, baseline_matcher:, comparison_matcher:, test_case_key: nil)
-    @results = results
-    @test_cases = test_cases
-    @baseline_matcher = baseline_matcher
-    @comparison_matcher = comparison_matcher
-    @test_case_key = test_case_key
-  end
-
-  # Calculate speedups and return stats hash
-  # Also annotates test_cases with individual speedups if test_case_key provided
-  # @return [Hash] { min: Float, max: Float, avg: Float } or nil if no pairs found
-  def calculate
-    speedups = []
-
-    # Group results by test case (everything after ':')
-    grouped = @results.group_by { |result| extract_test_case(result['name']) }
-
-    grouped.each do |test_case_id, group_results|
-      baseline = group_results.find(&@baseline_matcher)
-      comparison = group_results.find(&@comparison_matcher)
-
-      next unless baseline && comparison
-
-      speedup = comparison['central_tendency'].to_f / baseline['central_tendency']
-      speedups << speedup
-
-      # Annotate test case metadata if provided
-      if @test_case_key && @test_cases
-        test_case = @test_cases.find { |tc| tc[@test_case_key.to_s] == test_case_id }
-        test_case['speedup'] = speedup.round(2) if test_case
-      end
-    end
-
-    return nil if speedups.empty?
-
-    {
-      'min' => speedups.min.round(2),
-      'max' => speedups.max.round(2),
-      'avg' => (speedups.sum / speedups.size).round(2)
-    }
-  end
-
-  private
-
-  # Extract test case id from result name
-  # "css_parser: CSS1" -> "CSS1"
-  # "cataract gem: all" -> "all"
-  def extract_test_case(name)
-    name.split(':').last.strip
-  end
-
-  # Common matchers
-  class Matchers
-    def self.css_parser
-      ->(result) { result['name'].include?('css_parser') }
-    end
-
-    def self.cataract
-      ->(result) { result['name'].include?('cataract') }
-    end
-
-    def self.with_yjit
-      ->(result) { result['name'].include?('YJIT') && !result['name'].include?('no YJIT') }
-    end
-
-    def self.without_yjit
-      ->(result) { result['name'].include?('no YJIT') }
-    end
-  end
-end