cataract 0.1.3 → 0.2.0

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

data/benchmarks/system_metadata.rb

@@ -1,81 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'fileutils'
-
-# Collects system metadata for benchmark runs
-class SystemMetadata
-  RESULTS_DIR = File.expand_path('.results', __dir__)
-
-  def self.collect
-    metadata = {
-      'ruby_version' => RUBY_VERSION,
-      'ruby_description' => RUBY_DESCRIPTION,
-      'platform' => RUBY_PLATFORM,
-      'cpu' => detect_cpu,
-      'memory' => detect_memory,
-      'os' => detect_os,
-      'timestamp' => Time.now.iso8601
-    }
-
-    FileUtils.mkdir_p(RESULTS_DIR)
-    File.write(File.join(RESULTS_DIR, 'metadata.json'), JSON.pretty_generate(metadata))
-
-    metadata
-  end
-
-  def self.detect_cpu
-    if RUBY_PLATFORM.include?('darwin')
-      `sysctl -n machdep.cpu.brand_string`.strip
-    elsif File.exist?('/proc/cpuinfo')
-      cpuinfo = File.read('/proc/cpuinfo')
-      if (match = cpuinfo.match(/model name\s*:\s*(.+)/))
-        match[1].strip
-      else
-        'Unknown'
-      end
-    else
-      'Unknown'
-    end
-  rescue StandardError
-    'Unknown'
-  end
-
-  def self.detect_memory
-    if RUBY_PLATFORM.include?('darwin')
-      # Output in GB
-      bytes = `sysctl -n hw.memsize`.strip.to_i
-      "#{bytes / (1024 * 1024 * 1024)}GB"
-    elsif File.exist?('/proc/meminfo')
-      meminfo = File.read('/proc/meminfo')
-      if (match = meminfo.match(/MemTotal:\s+(\d+)\s+kB/))
-        kb = match[1].to_i
-        "#{kb / (1024 * 1024)}GB"
-      else
-        'Unknown'
-      end
-    else
-      'Unknown'
-    end
-  rescue StandardError
-    'Unknown'
-  end
-
-  def self.detect_os
-    if RUBY_PLATFORM.include?('darwin')
-      version = `sw_vers -productVersion`.strip
-      "macOS #{version}"
-    elsif File.exist?('/etc/os-release')
-      os_release = File.read('/etc/os-release')
-      if (match = os_release.match(/PRETTY_NAME="(.+)"/))
-        match[1]
-      else
-        RUBY_PLATFORM
-      end
-    else
-      RUBY_PLATFORM
-    end
-  rescue StandardError
-    RUBY_PLATFORM
-  end
-end

data/benchmarks/templates/benchmarks.md.erb

@@ -1,221 +0,0 @@
-<!-- AUTO-GENERATED FILE - DO NOT EDIT -->
-<!-- This file is automatically generated from benchmark results. -->
-<!-- To regenerate: rake benchmark:generate_docs -->
-
-# Performance Benchmarks
-
-Comprehensive performance comparison between Cataract and css_parser gem.
-
-## Test Environment
-
-- **Ruby**: <%= metadata['ruby_description'] %>
-- **CPU**: <%= metadata['cpu'] %>
-- **Memory**: <%= metadata['memory'] %>
-- **OS**: <%= metadata['os'] %>
-- **Generated**: <%= metadata['timestamp'] %>
-
-<%- if parsing_data -%>
-<details>
-<summary><h2>CSS Parsing</h2></summary>
-
-Performance of parsing CSS into internal data structures.
-
-<%= parsing_data['description'] %>
-
-<%- parsing_data['metadata']['test_cases'].each do |test_case| -%>
-### <%= test_case['name'] %>
-
-<%- results = parsing_data['results'].select { |r| r['name'].include?(test_case['fixture']) } -%>
-<%- css_parser_result = results.find { |r| r['name'].include?('css_parser') } -%>
-<%- cataract_result = results.find { |r| r['name'].include?('cataract') } -%>
-<%- if css_parser_result && cataract_result -%>
-<%- speedup = cataract_result['central_tendency'] / css_parser_result['central_tendency'] -%>
-
-| Parser | Speed | Time per operation |
-|--------|-------|-------------------|
-| css_parser | <%= format_ips(css_parser_result, short: true) %> | <%= format_time_per_op(css_parser_result) %> |
-| **Cataract** | **<%= format_ips(cataract_result, short: true) %>** | **<%= format_time_per_op(cataract_result) %>** |
-| **Speedup** | **<%= format_speedup(speedup) %>** | |
-
-<%- end -%>
-<%- end -%>
-
-</details>
-
----
-<%- end -%>
-
-<%- if serialization_data -%>
-<details>
-<summary><h2>CSS Serialization (to_s)</h2></summary>
-
-Performance of converting parsed CSS back to string format.
-
-<%= serialization_data['description'] %>
-
-<%- serialization_data['metadata']['test_cases'].each do |test_case| -%>
-### <%= test_case['name'] %>
-
-<%- results = serialization_data['results'].select { |r| r['name'].include?(test_case['key']) } -%>
-<%- css_parser_result = results.find { |r| r['name'].include?('css_parser') } -%>
-<%- cataract_result = results.find { |r| r['name'].include?('cataract') } -%>
-<%- if css_parser_result && cataract_result -%>
-<%- speedup = cataract_result['central_tendency'] / css_parser_result['central_tendency'] -%>
-
-| Parser | Speed | Time per operation |
-|--------|-------|-------------------|
-| css_parser | <%= format_ips(css_parser_result, short: true) %> | <%= format_time_per_op(css_parser_result) %> |
-| **Cataract** | **<%= format_ips(cataract_result, short: true) %>** | **<%= format_time_per_op(cataract_result) %>** |
-| **Speedup** | **<%= format_speedup(speedup) %>** | |
-
-<%- end -%>
-<%- end -%>
-
-</details>
-
----
-<%- end -%>
-
-<%- if specificity_data -%>
-<details>
-<summary><h2>Specificity Calculation</h2></summary>
-
-Performance of calculating CSS selector specificity values.
-
-<%= specificity_data['description'] %>
-
-| Test Case | Speedup |
-|-----------|---------|
-<%- specificity_data['metadata']['test_cases'].each do |test_case| -%>
-| <%= test_case['name'] %> | **<%= format_speedup(test_case['speedup']) %>** |
-<%- end -%>
-
-**Summary:** <%= format_speedup(specificity_data['metadata']['speedups']['min']) %> to <%= format_speedup(specificity_data['metadata']['speedups']['max']) %> (avg <%= format_speedup(specificity_data['metadata']['speedups']['avg']) %>)
-
-</details>
-
----
-<%- end -%>
-
-<%- if merging_data -%>
-<details>
-<summary><h2>CSS Merging</h2></summary>
-
-Performance of merging multiple CSS rule sets with the same selector.
-
-<%= merging_data['description'] %>
-
-| Test Case | Speedup |
-|-----------|---------|
-<%- merging_data['metadata']['test_cases'].each do |test_case| -%>
-| <%= test_case['name'] %> | **<%= format_speedup(test_case['speedup']) %>** |
-<%- end -%>
-
-**Summary:** <%= format_speedup(merging_data['metadata']['speedups']['min']) %> to <%= format_speedup(merging_data['metadata']['speedups']['max']) %> (avg <%= format_speedup(merging_data['metadata']['speedups']['avg']) %>)
-
-### What's Being Tested
-- Specificity-based CSS cascade (ID > class > element)
-- `!important` declaration handling
-- Shorthand property expansion (e.g., `margin` → `margin-top`, `margin-right`, etc.)
-- Shorthand property creation from longhand properties
-
-</details>
-
----
-<%- end -%>
-
-<%- if yjit_data -%>
-<details>
-<summary><h2>YJIT Impact</h2></summary>
-
-Impact of Ruby's YJIT JIT compiler on Ruby-side operations. The C extension performance is the same regardless of YJIT.
-
-<%= yjit_data['description'] %>
-
-### Operations Per Second
-
-| Operation | Without YJIT | With YJIT | YJIT Improvement |
-|-----------|--------------|-----------|------------------|
-<%- yjit_data['metadata']['operations'].each do |operation| -%>
-<%- results = yjit_data['results'].select { |r| r['name'].include?(operation) } -%>
-<%- no_yjit = results.find { |r| r['name'].include?('no YJIT') } -%>
-<%- with_yjit = results.find { |r| r['name'].include?('YJIT') && !r['name'].include?('no YJIT') } -%>
-<%- if no_yjit && with_yjit -%>
-<%- improvement = with_yjit['central_tendency'] / no_yjit['central_tendency'] -%>
-<%- pct = ((improvement - 1) * 100).round -%>
-| <%= operation %> | <%= format_ips(no_yjit, short: true) %> | <%= format_ips(with_yjit, short: true) %> | **<%= format_speedup(improvement) %>** (<%= pct %>% faster) |
-<%- end -%>
-<%- end -%>
-
-### Key Takeaways
-- YJIT provides significant performance boost for Ruby-side operations
-- Greatest impact on declaration merging
-- Parse + iterate benefits least since most work is in C
-- Recommended: Enable YJIT in production (`--yjit` flag or `RUBY_YJIT_ENABLE=1`)
-
-</details>
-
----
-<%- end -%>
-
-## Summary
-
-### Performance Highlights
-
-| Category | Min Speedup | Max Speedup | Avg Speedup |
-|----------|-------------|-------------|-------------|
-<%- if parsing_data && parsing_data['metadata']['speedups'] -%>
-<%- sp = parsing_data['metadata']['speedups'] -%>
-| **Parsing** | <%= format_speedup(sp['min']) %> | <%= format_speedup(sp['max']) %> | <%= format_speedup(sp['avg']) %> |
-<%- end -%>
-<%- if serialization_data && serialization_data['metadata']['speedups'] -%>
-<%- sp = serialization_data['metadata']['speedups'] -%>
-| **Serialization** | <%= format_speedup(sp['min']) %> | <%= format_speedup(sp['max']) %> | <%= format_speedup(sp['avg']) %> |
-<%- end -%>
-<%- if specificity_data && specificity_data['metadata']['speedups'] -%>
-<%- sp = specificity_data['metadata']['speedups'] -%>
-| **Specificity** | <%= format_speedup(sp['min']) %> | <%= format_speedup(sp['max']) %> | <%= format_speedup(sp['avg']) %> |
-<%- end -%>
-<%- if merging_data && merging_data['metadata']['speedups'] -%>
-<%- sp = merging_data['metadata']['speedups'] -%>
-| **Merging** | <%= format_speedup(sp['min']) %> | <%= format_speedup(sp['max']) %> | <%= format_speedup(sp['avg']) %> |
-<%- end -%>
-
-### Implementation Notes
-
-1. **C Extension**: Critical paths (parsing, specificity, merging, serialization) implemented in C
-2. **Efficient Data Structures**: Rules grouped by media query for O(1) lookups
-3. **Memory Efficient**: Pre-allocated string buffers, minimal Ruby object allocations
-4. **Optimized Algorithms**: Purpose-built CSS specificity calculator
-
-### Use Cases
-
-- **Large CSS files**: Handles complex stylesheets efficiently
-- **Specificity calculations**: Optimized for selector analysis
-- **High-volume processing**: Reduced allocations minimize GC pressure
-- **Production applications**: Tested with Bootstrap CSS and real-world stylesheets
-
----
-
-## Running Benchmarks
-
-```bash
-# All benchmarks
-rake benchmark 2>&1 | tee benchmark_output.txt
-
-# Individual benchmarks
-rake benchmark:parsing
-rake benchmark:serialization
-rake benchmark:specificity
-rake benchmark:merging
-rake benchmark:yjit
-
-# Generate documentation
-rake benchmark:generate_docs
-```
-
-## Notes
-
-- All benchmarks use benchmark-ips with 3s warmup and 5-10s measurement periods
-- Measurements are median i/s (iterations per second) with standard deviation
-- css_parser gem must be installed for comparison benchmarks