cataract 0.1.0

data/benchmarks/system_metadata.rb

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

@@ -0,0 +1,221 @@
+<!-- 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

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

data/cataract.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/cataract/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'cataract'
+  spec.version       = Cataract::VERSION
+  spec.authors       = ['Your Name']
+  spec.email         = ['your.email@example.com']
+
+  spec.summary       = 'CSS parser built with Ragel state machines'
+  spec.description   = 'A high-performance CSS parser using Ragel finite state machines for accurate parsing of complex CSS structures'
+  spec.homepage      = 'https://github.com/jamescook/cataract'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.1.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) || f.match(/^test_.*\.rb$/) }
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # C extension configuration
+  # Two separate extensions: core parser and optional color conversion
+  spec.extensions = ['ext/cataract/extconf.rb', 'ext/cataract_color/extconf.rb']
+end

data/cliff.toml

@@ -0,0 +1,92 @@
+# git-cliff ~ configuration file
+# https://git-cliff.org/docs/configuration
+
+
+[changelog]
+# A Tera template to be rendered for each release in the changelog.
+# See https://keats.github.io/tera/docs/#introduction
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | striptags | trim | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.scope %}*({{ commit.scope }})* {% endif %}\
+            {% if commit.breaking %}[**breaking**] {% endif %}\
+            {{ commit.message | upper_first }}\
+    {% endfor %}
+{% endfor %}
+"""
+# Remove leading and trailing whitespaces from the changelog's body.
+trim = true
+# Render body even when there are no releases to process.
+render_always = true
+# An array of regex based postprocessors to modify the changelog.
+postprocessors = [
+    # Replace the placeholder <REPO> with a URL.
+    #{ pattern = '<REPO>', replace = "https://github.com/orhun/git-cliff" },
+]
+# render body even when there are no releases to process
+# render_always = true
+# output file path
+# output = "test.md"
+
+[git]
+# Parse commits according to the conventional commits specification.
+# See https://www.conventionalcommits.org
+conventional_commits = true
+# Exclude commits that do not match the conventional commits specification.
+filter_unconventional = true
+# Require all commits to be conventional.
+# Takes precedence over filter_unconventional.
+require_conventional = false
+# Split commits on newlines, treating each line as an individual commit.
+split_commits = false
+# An array of regex based parsers to modify commit messages prior to further processing.
+commit_preprocessors = [
+    # Replace issue numbers with link templates to be updated in `changelog.postprocessors`.
+    #{ pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))"},
+    # Check spelling of the commit message using https://github.com/crate-ci/typos.
+    # If the spelling is incorrect, it will be fixed automatically.
+    #{ pattern = '.*', replace_command = 'typos --write-changes -' },
+]
+# Prevent commits that are breaking from being excluded by commit parsers.
+protect_breaking_commits = false
+# An array of regex based parsers for extracting data from the commit message.
+# Assigns commits to groups.
+# Optionally sets the commit's scope and can decide to exclude commits from further processing.
+commit_parsers = [
+    { message = "^feat", group = "<!-- 0 -->🚀 Features" },
+    { message = "^fix", group = "<!-- 1 -->🐛 Bug Fixes" },
+    { message = "^doc", group = "<!-- 3 -->📚 Documentation" },
+    { message = "^perf", group = "<!-- 4 -->⚡ Performance" },
+    { message = "^refactor", group = "<!-- 2 -->🚜 Refactor" },
+    { message = "^style", group = "<!-- 5 -->🎨 Styling" },
+    { message = "^test", group = "<!-- 6 -->🧪 Testing" },
+    { message = "^chore\\(release\\): prepare for", skip = true },
+    { message = "^chore\\(deps.*\\)", skip = true },
+    { message = "^chore\\(pr\\)", skip = true },
+    { message = "^chore\\(pull\\)", skip = true },
+    { message = "^chore|^ci", group = "<!-- 7 -->⚙️ Miscellaneous Tasks" },
+    { body = ".*security", group = "<!-- 8 -->🛡️ Security" },
+    { message = "^revert", group = "<!-- 9 -->◀️ Revert" },
+    { message = ".*", group = "<!-- 10 -->💼 Other" },
+]
+# Exclude commits that are not matched by any commit parser.
+filter_commits = false
+# An array of link parsers for extracting external references, and turning them into URLs, using regex.
+link_parsers = []
+# Include only the tags that belong to the current branch.
+use_branch_tags = false
+# Order releases topologically instead of chronologically.
+topo_order = false
+# Order releases topologically instead of chronologically.
+topo_order_commits = true
+# Order of commits in each group/release within the changelog.
+# Allowed values: newest, oldest
+sort_commits = "oldest"
+# Process submodules commits
+recurse_submodules = false