cataract 0.1.3 → 0.2.0

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

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