cataract 0.1.3 → 0.2.0

data/benchmarks/benchmark_shorthand_expansion.rb

@@ -1,176 +0,0 @@
-# frozen_string_literal: true
-
-require 'benchmark/ips'
-require 'cataract'
-
-# Load css_parser for comparison
-begin
-  require 'css_parser'
-  CSS_PARSER_AVAILABLE = true
-rescue LoadError
-  CSS_PARSER_AVAILABLE = false
-  puts 'Warning: css_parser gem not found. Install with: gem install css_parser'
-  puts 'Running Cataract-only benchmarks...'
-end
-
-# Test values
-MARGIN_VALUES = [
-  '10px',
-  '10px 20px',
-  '10px 20px 30px',
-  '10px 20px 30px 40px',
-  '10px calc(100% - 20px)',
-  '10px !important'
-].freeze
-
-BORDER_VALUES = [
-  '1px solid red',
-  '2px dashed blue',
-  'thin dotted #000'
-].freeze
-
-FONT_VALUES = [
-  '12px Arial',
-  "bold 14px/1.5 'Helvetica Neue', sans-serif"
-].freeze
-
-puts "\n=== Shorthand Expansion Benchmark ==="
-puts "Comparing Cataract (C) vs css_parser (Ruby)\n\n"
-
-# Sanity check: verify both implementations produce same results
-if CSS_PARSER_AVAILABLE
-  puts '--- Sanity Check: Comparing Outputs ---'
-
-  # Test margin expansion
-  cataract_result = Cataract._expand_margin('10px 20px 30px 40px')
-  css_parser_rs = CssParser::RuleSet.new(block: 'margin: 10px 20px 30px 40px')
-  css_parser_rs.expand_shorthand!
-  css_parser_result = {}
-  css_parser_rs.each_declaration { |prop, val, _| css_parser_result[prop] = val }
-
-  if cataract_result == css_parser_result
-    puts '✓ Margin expansion: MATCH'
-  else
-    puts '✗ Margin expansion: MISMATCH'
-    puts "  Cataract: #{cataract_result.inspect}"
-    puts "  css_parser: #{css_parser_result.inspect}"
-    exit 1
-  end
-
-  # Test border expansion
-  cataract_result = Cataract._expand_border('1px solid red')
-  css_parser_rs = CssParser::RuleSet.new(block: 'border: 1px solid red')
-  css_parser_rs.expand_shorthand!
-  css_parser_result = {}
-  css_parser_rs.each_declaration { |prop, val, _| css_parser_result[prop] = val }
-
-  if cataract_result == css_parser_result
-    puts '✓ Border expansion: MATCH'
-  else
-    puts '✗ Border expansion: MISMATCH'
-    puts "  Cataract: #{cataract_result.inspect}"
-    puts "  css_parser: #{css_parser_result.inspect}"
-    exit 1
-  end
-
-  puts "All sanity checks passed!\n\n"
-end
-
-# Margin expansion
-puts '--- Margin Expansion (4 values) ---'
-Benchmark.ips do |x|
-  x.config(time: 5, warmup: 2)
-
-  x.report('Cataract (C)') do
-    Cataract._expand_margin('10px 20px 30px 40px')
-  end
-
-  if CSS_PARSER_AVAILABLE
-    x.report('css_parser (Ruby)') do
-      rs = CssParser::RuleSet.new(block: 'margin: 10px 20px 30px 40px')
-      rs.expand_shorthand!
-    end
-  end
-
-  x.compare!
-end
-
-# Margin with calc()
-puts "\n--- Margin with calc() ---"
-Benchmark.ips do |x|
-  x.config(time: 5, warmup: 2)
-
-  x.report('Cataract (C)') do
-    Cataract._expand_margin('10px calc(100% - 20px)')
-  end
-
-  if CSS_PARSER_AVAILABLE
-    x.report('css_parser (Ruby)') do
-      rs = CssParser::RuleSet.new(block: 'margin: 10px calc(100% - 20px)')
-      rs.expand_shorthand!
-    end
-  end
-
-  x.compare!
-end
-
-# Margin with !important
-puts "\n--- Margin with !important ---"
-Benchmark.ips do |x|
-  x.config(time: 5, warmup: 2)
-
-  x.report('Cataract (C)') do
-    Cataract._expand_margin('10px !important')
-  end
-
-  if CSS_PARSER_AVAILABLE
-    x.report('css_parser (Ruby)') do
-      rs = CssParser::RuleSet.new(block: 'margin: 10px !important')
-      rs.expand_shorthand!
-    end
-  end
-
-  x.compare!
-end
-
-# Border expansion
-puts "\n--- Border Expansion ---"
-Benchmark.ips do |x|
-  x.config(time: 5, warmup: 2)
-
-  x.report('Cataract (C)') do
-    Cataract._expand_border('1px solid red')
-  end
-
-  if CSS_PARSER_AVAILABLE
-    x.report('css_parser (Ruby)') do
-      rs = CssParser::RuleSet.new(block: 'border: 1px solid red')
-      rs.expand_shorthand!
-    end
-  end
-
-  x.compare!
-end
-
-# Font expansion
-puts "\n--- Font Expansion ---"
-Benchmark.ips do |x|
-  x.config(time: 5, warmup: 2)
-
-  x.report('Cataract (C)') do
-    Cataract._expand_font("bold 14px/1.5 'Helvetica Neue', sans-serif")
-  end
-
-  if CSS_PARSER_AVAILABLE
-    x.report('css_parser (Ruby)') do
-      rs = CssParser::RuleSet.new(block: "font: bold 14px/1.5 'Helvetica Neue', sans-serif")
-      rs.expand_shorthand!
-    end
-  end
-
-  x.compare!
-end
-
-puts "\n=== Summary ==="
-puts 'Cataract uses a C implementation with Ragel state machine for value splitting'
-puts 'css_parser uses pure Ruby with regex-based parsing'

data/benchmarks/benchmark_specificity.rb

@@ -1,124 +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 Specificity Calculation Benchmark
-class SpecificityBenchmark < BenchmarkHarness
-  def self.benchmark_name
-    'specificity'
-  end
-
-  def self.description
-    'Time to calculate CSS selector specificity values'
-  end
-
-  def self.metadata
-    {
-      'test_cases' => [
-        {
-          'name' => 'Simple Selectors',
-          'key' => 'simple',
-          'selectors' => { 'div' => 1, '.class' => 10, '#id' => 100 }
-        },
-        {
-          'name' => 'Compound Selectors',
-          'key' => 'compound',
-          'selectors' => { 'div.container' => 11, 'div#main' => 101, 'div.container#main' => 111 }
-        },
-        {
-          'name' => 'Combinators',
-          'key' => 'combinators',
-          'selectors' => { 'div p' => 2, 'div > p' => 2, 'h1 + p' => 2, 'div.container > p.intro' => 22 }
-        },
-        {
-          'name' => 'Pseudo-classes & Pseudo-elements',
-          'key' => 'pseudo',
-          'selectors' => { 'a:hover' => 11, 'p::before' => 2, 'li:first-child' => 11, 'p:first-child::before' => 12 }
-        },
-        {
-          'name' => ':not() Pseudo-class (CSS3)',
-          'key' => 'not',
-          'selectors' => { '#s12:not(foo)' => 101, 'div:not(.active)' => 11, '.button:not([disabled])' => 20 },
-          'note' => "css_parser has a bug - doesn't parse :not() content"
-        },
-        {
-          'name' => 'Complex Real-world Selectors',
-          'key' => 'complex',
-          'selectors' => {
-            'ul#nav li.active a:hover' => 122,
-            'div.wrapper > article#main > section.content > p:first-child' => 123,
-            "[data-theme='dark'] body.admin #dashboard .widget a[href^='http']::before" => 143
-          }
-        }
-      ]
-    }
-  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 Cataract calculations
-    raise 'Cataract simple selector failed' unless Cataract.calculate_specificity('div') == 1
-    raise 'Cataract class selector failed' unless Cataract.calculate_specificity('.class') == 10
-    raise 'Cataract id selector failed' unless Cataract.calculate_specificity('#id') == 100
-  end
-
-  def call
-    self.class.metadata['test_cases'].each do |test_case|
-      benchmark_category(test_case)
-    end
-  end
-
-  private
-
-  def benchmark_category(test_case)
-    puts '=' * 80
-    puts "TEST: #{test_case['name']}"
-    puts test_case['note'] if test_case['note']
-    puts '=' * 80
-
-    key = test_case['key']
-    selectors = test_case['selectors']
-
-    # Show individual selector examples in terminal output
-    puts 'Selectors tested:'
-    selectors.each do |selector, expected_specificity|
-      puts "  #{selector} => #{expected_specificity}"
-    end
-    puts
-
-    benchmark(key) do |x|
-      x.config(time: 2, warmup: 1)
-
-      # Report aggregated results per test case for speedup calculation
-      x.report("css_parser: #{key}") do
-        selectors.each_key do |selector|
-          CssParser.calculate_specificity(selector)
-        end
-      end
-
-      x.report("cataract: #{key}") do
-        selectors.each_key do |selector|
-          Cataract.calculate_specificity(selector)
-        end
-      end
-
-      x.compare!
-    end
-  end
-end
-
-# Run if executed directly
-SpecificityBenchmark.run if __FILE__ == $PROGRAM_NAME

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