cataract 0.1.3 → 0.1.4

data/benchmarks/benchmark_runner.rb

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

data/benchmarks/benchmark_serialization.rb

@@ -1,180 +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 Serialization Performance Benchmark
-class SerializationBenchmark < BenchmarkHarness
-  def self.benchmark_name
-    'serialization'
-  end
-
-  def self.description
-    'Time to convert parsed CSS back to string format'
-  end
-
-  def self.metadata
-    instance = new
-    {
-      'test_cases' => [
-        {
-          'name' => "Full Serialization (Bootstrap CSS - #{(instance.bootstrap_css.length / 1024.0).round}KB)",
-          'key' => 'all',
-          'bytes' => instance.bootstrap_css.length
-        },
-        {
-          'name' => 'Media Type Filtering (print only)',
-          'key' => 'print',
-          'bytes' => instance.bootstrap_css.length
-        }
-      ]
-    }
-  end
-
-  # Uses default speedup_config (test_case_key differs from parsing)
-  def self.speedup_config
-    {
-      baseline_matcher: SpeedupCalculator::Matchers.css_parser,
-      comparison_matcher: SpeedupCalculator::Matchers.cataract,
-      test_case_key: :key # serialization uses 'key' not 'fixture'
-    }
-  end
-
-  def sanity_checks
-    # Check css_parser gem is available
-    require 'css_parser'
-
-    # Verify Bootstrap fixture exists
-    raise "Bootstrap CSS fixture not found at #{bootstrap_path}" unless File.exist?(bootstrap_path)
-
-    # Verify parsing and serialization work
-    cataract_sheet = Cataract.parse_css(bootstrap_css)
-    raise 'Failed to parse Bootstrap CSS' if cataract_sheet.empty?
-
-    cataract_output = cataract_sheet.to_s
-    raise 'Serialization produced empty output' if cataract_output.empty?
-
-    # Verify output can be re-parsed
-    reparsed = Cataract.parse_css(cataract_output)
-    raise 'Failed to re-parse serialized output' if reparsed.empty?
-  end
-
-  def call
-    validate_correctness
-    run_full_serialization_benchmark
-    run_media_filtering_benchmark
-  end
-
-  def bootstrap_css
-    @bootstrap_css ||= File.read(bootstrap_path)
-  end
-
-  private
-
-  def bootstrap_path
-    @bootstrap_path ||= File.expand_path('../test/fixtures/bootstrap.css', __dir__)
-  end
-
-  def validate_correctness
-    puts '=' * 80
-    puts 'CORRECTNESS VALIDATION'
-    puts '=' * 80
-    puts "Input: Bootstrap CSS (#{bootstrap_css.length} bytes)"
-
-    # Parse with both libraries
-    cataract_sheet = Cataract.parse_css(bootstrap_css)
-    css_parser = CssParser::Parser.new
-    css_parser.add_block!(bootstrap_css)
-
-    # Serialize
-    cataract_output = cataract_sheet.to_s
-    css_parser_output = css_parser.to_s
-
-    puts "Cataract output: #{cataract_output.length} bytes (#{cataract_sheet.size} rules)"
-    puts "css_parser output: #{css_parser_output.length} bytes"
-
-    # Basic sanity check - outputs should be similar in size
-    size_ratio = cataract_output.length.to_f / css_parser_output.length
-    unless size_ratio > 0.8 && size_ratio < 1.2
-      puts "⚠️  Output sizes differ significantly (ratio: #{size_ratio.round(2)})"
-    end
-
-    # Check that output can be re-parsed
-    begin
-      reparsed = Cataract.parse_css(cataract_output)
-      puts "Re-parsed output: #{reparsed.size} rules"
-    rescue StandardError => e
-      puts "❌ Failed to re-parse: #{e.message}"
-      raise
-    end
-  end
-
-  def run_full_serialization_benchmark
-    puts "\n#{'=' * 80}"
-    puts 'TEST: Full serialization (to_s)'
-    puts '=' * 80
-    puts '(Parsing done once before benchmark, not included in measurements)'
-
-    # Pre-parse CSS once (outside benchmark loop)
-    cataract_parsed = Cataract.parse_css(bootstrap_css)
-    css_parser_parsed = CssParser::Parser.new
-    css_parser_parsed.add_block!(bootstrap_css)
-
-    benchmark('all') do |x|
-      x.config(time: 5, warmup: 2)
-
-      x.report('css_parser: all') do
-        # Clear memoization if any
-        if css_parser_parsed.instance_variable_defined?(:@css_string)
-          css_parser_parsed.instance_variable_set(:@css_string, nil)
-        end
-        css_parser_parsed.to_s
-      end
-
-      x.report('cataract: all') do
-        # Clear memoization
-        cataract_parsed.instance_variable_set(:@serialized, nil)
-        cataract_parsed.to_s
-      end
-
-      x.compare!
-    end
-  end
-
-  def run_media_filtering_benchmark
-    puts "\n#{'=' * 80}"
-    puts 'TEST: Media type filtering - to_s(:print)'
-    puts '=' * 80
-    puts 'Note: Using Parser API (css_parser compatible) not Stylesheet'
-
-    # Pre-parse using Parser API for media filtering
-    cataract_parser = Cataract::Stylesheet.new
-    cataract_parser.add_block(bootstrap_css)
-
-    css_parser_for_filter = CssParser::Parser.new
-    css_parser_for_filter.add_block!(bootstrap_css)
-
-    benchmark('print') do |x|
-      x.config(time: 5, warmup: 2)
-
-      x.report('css_parser: print') do
-        if css_parser_for_filter.instance_variable_defined?(:@css_string)
-          css_parser_for_filter.instance_variable_set(:@css_string, nil)
-        end
-        css_parser_for_filter.to_s(:print)
-      end
-
-      x.report('cataract: print') do
-        cataract_parser.to_s(media: :print)
-      end
-
-      x.compare!
-    end
-  end
-end
-
-# Run if executed directly
-SerializationBenchmark.run if __FILE__ == $PROGRAM_NAME

data/benchmarks/benchmark_shorthand.rb

@@ -1,109 +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 "Shorthand Expansion/Creation Benchmark: #{branch}"
-puts '=' * 60
-puts ''
-
-# Test cases for expansion
-expansion_tests = {
-  'margin' => '10px 20px',
-  'padding' => '5px 10px 15px 20px',
-  'border' => '1px solid red',
-  'border-color' => 'red blue',
-  'font' => 'bold 14px/1.5 Arial, sans-serif',
-  'background' => 'url(image.png) no-repeat center/cover'
-}
-
-# Test cases for shorthand creation
-creation_tests = {
-  'margin' => {
-    'margin-top' => '10px',
-    'margin-right' => '20px',
-    'margin-bottom' => '10px',
-    'margin-left' => '20px'
-  },
-  'border' => {
-    'border-width' => '1px',
-    'border-style' => 'solid',
-    'border-color' => 'red'
-  },
-  'font' => {
-    'font-style' => 'italic',
-    'font-weight' => 'bold',
-    'font-size' => '14px',
-    'line-height' => '1.5',
-    'font-family' => 'Arial, sans-serif'
-  }
-}
-
-puts 'Expansion test cases:'
-expansion_tests.each do |prop, value|
-  puts "  #{prop}: '#{value}'"
-end
-puts ''
-
-puts 'Shorthand creation test cases:'
-creation_tests.each do |name, props|
-  puts "  #{name}: #{props.length} properties"
-end
-puts ''
-
-Benchmark.ips do |x|
-  x.config(time: 10, warmup: 3)
-
-  # Benchmark expansions
-  x.report("#{branch}:expand_margin      ") do
-    Cataract.expand_margin(expansion_tests['margin'])
-  end
-
-  x.report("#{branch}:expand_padding     ") do
-    Cataract.expand_padding(expansion_tests['padding'])
-  end
-
-  x.report("#{branch}:expand_border      ") do
-    Cataract.expand_border(expansion_tests['border'])
-  end
-
-  x.report("#{branch}:expand_font        ") do
-    Cataract.expand_font(expansion_tests['font'])
-  end
-
-  x.report("#{branch}:expand_background  ") do
-    Cataract.expand_background(expansion_tests['background'])
-  end
-
-  # Benchmark shorthand creation
-  x.report("#{branch}:create_margin      ") do
-    Cataract.create_margin_shorthand(creation_tests['margin'])
-  end
-
-  x.report("#{branch}:create_border      ") do
-    Cataract.create_border_shorthand(creation_tests['border'])
-  end
-
-  x.report("#{branch}:create_font        ") do
-    Cataract.create_font_shorthand(creation_tests['font'])
-  end
-
-  x.compare!
-
-  # Save results to file for cross-branch comparison
-  x.save! 'test/.benchmark_results/shorthand.json'
-  x.hold! 'test/.benchmark_results/shorthand.json'
-end
-
-puts ''
-puts '=' * 60
-puts 'Results saved to test/.benchmark_results/shorthand.json'
-puts 'Switch git branches and run again to compare!'
-puts '=' * 60

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