cataract 0.1.3 → 0.1.4

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

data/benchmarks/yjit_tests.rb

@@ -1,141 +0,0 @@
-# frozen_string_literal: true
-
-# Shared test logic for YJIT benchmarks
-# Extended by both YjitWithoutBenchmark and YjitWithBenchmark
-module YjitTests
-  SAMPLE_CSS = <<~CSS
-    body { margin: 0; padding: 0; font-family: Arial, sans-serif; }
-    .header { color: #333; padding: 20px; background: #f8f9fa; }
-    .container { max-width: 1200px; margin: 0 auto; }
-    div p { line-height: 1.6; }
-    .container > .item { margin-bottom: 20px; }
-    h1 + p { margin-top: 0; font-size: 1.2em; }
-  CSS
-
-  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
-    parser.add_block(SAMPLE_CSS)
-    raise 'Parse failed' if parser.rules_count.zero?
-  end
-
-  def call
-    run_property_access_benchmark
-    run_declaration_merging_benchmark
-    run_to_s_benchmark
-    run_parse_iterate_benchmark
-  end
-
-  private
-
-  def yjit_label
-    @yjit_label ||= defined?(RubyVM::YJIT.enabled?) && RubyVM::YJIT.enabled? ? 'YJIT' : 'no YJIT'
-  end
-
-  def run_property_access_benchmark
-    puts '=' * 80
-    puts "TEST: Property access (get/set) - #{yjit_label}"
-    puts '=' * 80
-
-    benchmark('property_access') do |x|
-      x.config(time: 3, warmup: 1)
-
-      x.report("#{yjit_label}: property access") do
-        decls = Cataract::Declarations.new
-        decls['color'] = 'red'
-        decls['background'] = 'blue'
-        decls['font-size'] = '16px'
-        decls['margin'] = '10px'
-        decls['padding'] = '5px'
-        _ = decls['color']
-        _ = decls['background']
-        _ = decls['font-size']
-      end
-    end
-  end
-
-  def run_declaration_merging_benchmark
-    puts "\n#{'=' * 80}"
-    puts "TEST: Declaration merging - #{yjit_label}"
-    puts '=' * 80
-
-    benchmark('declaration_merging') do |x|
-      x.config(time: 3, warmup: 1)
-
-      x.report("#{yjit_label}: declaration merging") do
-        decls1 = Cataract::Declarations.new
-        decls1['color'] = 'red'
-        decls1['font-size'] = '16px'
-
-        decls2 = Cataract::Declarations.new
-        decls2['background'] = 'blue'
-        decls2['margin'] = '10px'
-
-        decls1.merge(decls2)
-      end
-    end
-  end
-
-  def run_to_s_benchmark
-    puts "\n#{'=' * 80}"
-    puts "TEST: to_s generation - #{yjit_label}"
-    puts '=' * 80
-
-    benchmark('to_s') do |x|
-      x.config(time: 3, warmup: 1)
-
-      x.report("#{yjit_label}: to_s generation") do
-        decls = Cataract::Declarations.new
-        decls['color'] = 'red'
-        decls['background'] = 'blue'
-        decls['font-size'] = '16px'
-        decls['margin'] = '10px'
-        decls['padding'] = '5px'
-        decls.to_s
-      end
-    end
-  end
-
-  def run_parse_iterate_benchmark
-    puts "\n#{'=' * 80}"
-    puts "TEST: Parse + iterate - #{yjit_label}"
-    puts '=' * 80
-
-    benchmark('parse_iterate') do |x|
-      x.config(time: 3, warmup: 1)
-
-      x.report("#{yjit_label}: parse + iterate") do
-        parser = Cataract::Stylesheet.new
-        parser.add_block(SAMPLE_CSS)
-        parser.select(&:selector?).each do |rule|
-          _ = rule.declarations
-        end
-      end
-    end
-  end
-end