cataract 0.1.3 → 0.2.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cataract
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - James Cook
@@ -21,12 +21,14 @@ extra_rdoc_files: []
 files:
 - ".clang-tidy"
 - ".github/workflows/ci-macos.yml"
+- ".github/workflows/ci-manual-rubies.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/docs.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
 - ".overcommit.yml"
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - BENCHMARKS.md
 - CHANGELOG.md
 - Gemfile
@@ -34,27 +36,6 @@ files:
 - RAGEL_MIGRATION.md
 - README.md
 - Rakefile
-- benchmarks/benchmark_harness.rb
-- benchmarks/benchmark_merging.rb
-- benchmarks/benchmark_optimization_comparison.rb
-- benchmarks/benchmark_parsing.rb
-- benchmarks/benchmark_ragel_removal.rb
-- benchmarks/benchmark_runner.rb
-- benchmarks/benchmark_serialization.rb
-- benchmarks/benchmark_shorthand.rb
-- benchmarks/benchmark_shorthand_expansion.rb
-- benchmarks/benchmark_specificity.rb
-- benchmarks/benchmark_string_allocation.rb
-- benchmarks/benchmark_stylesheet_to_s.rb
-- benchmarks/benchmark_to_s_cached.rb
-- benchmarks/benchmark_value_splitter.rb
-- benchmarks/benchmark_yjit.rb
-- benchmarks/benchmark_yjit_workers.rb
-- benchmarks/profile_to_s.rb
-- benchmarks/speedup_calculator.rb
-- benchmarks/system_metadata.rb
-- benchmarks/templates/benchmarks.md.erb
-- benchmarks/yjit_tests.rb
 - cataract.gemspec
 - cliff.toml
 - docs/files/EXAMPLE.md
@@ -74,8 +55,8 @@ files:
 - ext/cataract/cataract.h
 - ext/cataract/css_parser.c
 - ext/cataract/extconf.rb
+- ext/cataract/flatten.c
 - ext/cataract/import_scanner.c
-- ext/cataract/merge.c
 - ext/cataract/shorthand_expander.c
 - ext/cataract/specificity.c
 - ext/cataract/value_splitter.c
@@ -99,16 +80,23 @@ files:
 - lib/cataract.rb
 - lib/cataract/at_rule.rb
 - lib/cataract/color_conversion.rb
+- lib/cataract/declaration.rb
 - lib/cataract/declarations.rb
 - lib/cataract/import_resolver.rb
+- lib/cataract/import_statement.rb
+- lib/cataract/pure.rb
+- lib/cataract/pure/byte_constants.rb
+- lib/cataract/pure/flatten.rb
+- lib/cataract/pure/helpers.rb
+- lib/cataract/pure/imports.rb
+- lib/cataract/pure/parser.rb
+- lib/cataract/pure/serializer.rb
+- lib/cataract/pure/specificity.rb
 - lib/cataract/rule.rb
 - lib/cataract/stylesheet.rb
 - lib/cataract/stylesheet_scope.rb
 - lib/cataract/version.rb
 - lib/tasks/gem.rake
-- scripts/fuzzer/run.rb
-- scripts/fuzzer/worker.rb
-- scripts/generate_benchmarks_md.rb
 homepage: https://github.com/jamescook/cataract
 licenses:
 - MIT

data/benchmarks/benchmark_harness.rb

@@ -1,193 +0,0 @@
-# frozen_string_literal: true
-
-require 'benchmark/ips'
-require 'json'
-require 'fileutils'
-require_relative 'system_metadata'
-require_relative 'speedup_calculator'
-
-# Base class for all benchmarks. Provides structure and automatic JSON output.
-#
-# Usage:
-#   class MyBenchmark < BenchmarkHarness
-#     def self.benchmark_name
-#       'my_benchmark'
-#     end
-#
-#     def self.description
-#       'What this benchmark measures'
-#     end
-#
-#     def self.metadata
-#       { 'key' => 'value' } # Optional metadata for docs
-#     end
-#
-#     def self.sanity_checks
-#       # Optional: verify code works before benchmarking
-#       raise "Sanity check failed!" unless something_works
-#     end
-#
-#     def self.call
-#       run_test_case_1
-#       run_test_case_2
-#     end
-#
-#     private
-#
-#     def self.run_test_case_1
-#       benchmark('test_case_1') do |x|
-#         x.config(time: 5, warmup: 2)
-#         x.report('label') { ... }
-#         x.compare!
-#       end
-#     end
-#   end
-class BenchmarkHarness
-  RESULTS_DIR = File.expand_path('.results', __dir__)
-
-  class << self
-    # Abstract methods - must be implemented by subclasses
-    def benchmark_name
-      raise NotImplementedError, "#{self} must implement .benchmark_name"
-    end
-
-    def description
-      raise NotImplementedError, "#{self} must implement .description"
-    end
-
-    def metadata
-      {} # Optional, can be overridden
-    end
-
-    def sanity_checks
-      # Optional, can be overridden
-    end
-
-    def call
-      raise NotImplementedError, "#{self} must implement .call"
-    end
-
-    # Optional: Define how to calculate speedups for this benchmark
-    # Override this to customize speedup calculation
-    #
-    # IMPORTANT: Result names must follow convention "tool_name: test_case_id"
-    #
-    # @return [Hash] Configuration for SpeedupCalculator
-    #   {
-    #     baseline_matcher: Proc,      # Returns true for baseline results
-    #     comparison_matcher: Proc,    # Returns true for comparison results
-    #     test_case_key: Symbol        # Key in test_cases metadata matching test_case_id
-    #   }
-    def speedup_config
-      # Default: compare css_parser (baseline) vs cataract (comparison)
-      # Match to test_cases by 'fixture' key
-      {
-        baseline_matcher: SpeedupCalculator::Matchers.css_parser,
-        comparison_matcher: SpeedupCalculator::Matchers.cataract,
-        test_case_key: :fixture
-      }
-    end
-
-    # Main entry point - handles setup, execution, and cleanup
-    def run
-      instance = new
-      setup
-      instance.sanity_checks if instance.respond_to?(:sanity_checks, true)
-      instance.call
-      finalize(instance)
-    rescue StandardError => e
-      puts "❌ Benchmark failed: #{e.message}"
-      puts e.backtrace.first(5).join("\n")
-      exit 1
-    end
-
-    private
-
-    def setup
-      FileUtils.mkdir_p(RESULTS_DIR)
-
-      # Collect system metadata once per run
-      unless File.exist?(File.join(RESULTS_DIR, 'metadata.json'))
-        SystemMetadata.collect
-      end
-
-      # Print header
-      puts "\n\n"
-      puts '=' * 80
-      puts "#{benchmark_name.upcase.tr('_', ' ')} BENCHMARK"
-      puts "Measures: #{description}"
-      puts '=' * 80
-      puts
-    end
-
-    def finalize(instance)
-      # Combine all JSON files for this benchmark into one
-      return unless instance.instance_variable_defined?(:@json_files) && instance.instance_variable_get(:@json_files)&.any?
-
-      json_files = instance.instance_variable_get(:@json_files)
-
-      combined_data = {
-        'name' => benchmark_name,
-        'description' => description,
-        'metadata' => metadata,
-        'timestamp' => Time.now.iso8601,
-        'results' => []
-      }
-
-      # Read all the individual JSON files
-      json_files.each do |filename|
-        path = File.join(RESULTS_DIR, filename)
-        next unless File.exist?(path)
-
-        data = JSON.parse(File.read(path))
-        combined_data['results'].concat(data) if data.is_a?(Array)
-      end
-
-      # Calculate speedups using configured strategy
-      config = speedup_config
-      if config
-        calculator = SpeedupCalculator.new(
-          results: combined_data['results'],
-          test_cases: combined_data['metadata']['test_cases'],
-          baseline_matcher: config[:baseline_matcher],
-          comparison_matcher: config[:comparison_matcher],
-          test_case_key: config[:test_case_key]
-        )
-
-        speedup_stats = calculator.calculate
-        combined_data['metadata']['speedups'] = speedup_stats if speedup_stats
-      end
-
-      # Write combined file
-      combined_path = File.join(RESULTS_DIR, "#{benchmark_name}.json")
-      File.write(combined_path, JSON.pretty_generate(combined_data))
-
-      # Clean up individual files
-      json_files.each do |filename|
-        File.delete(File.join(RESULTS_DIR, filename))
-      end
-
-      puts "\n✓ Results saved to #{combined_path}"
-    end
-  end
-
-  # Instance methods
-  protected
-
-  def benchmark(test_case_name)
-    json_filename = "#{self.class.benchmark_name}_#{test_case_name}.json"
-    json_path = File.join(RESULTS_DIR, json_filename)
-
-    Benchmark.ips do |x|
-      # Automatically enable JSON output
-      x.json!(json_path)
-
-      # Let the benchmark configure and run
-      yield x
-    end
-
-    # Track that we created this file
-    @json_files ||= []
-    @json_files << json_filename
-  end
-end

data/benchmarks/benchmark_merging.rb

@@ -1,121 +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 Merging Benchmark
-class MergingBenchmark < BenchmarkHarness
-  def self.benchmark_name
-    'merging'
-  end
-
-  def self.description
-    'Time to merge multiple CSS rule sets with same selector'
-  end
-
-  def self.metadata
-    {
-      'test_cases' => [
-        {
-          'name' => 'No shorthand properties (large)',
-          'key' => 'no_shorthand',
-          'css' => (".test { color: red; background-color: blue; display: block; position: relative; width: 100px; height: 50px; }\n" * 100)
-        },
-        {
-          'name' => 'Simple properties',
-          'key' => 'simple',
-          'css' => ".test { color: black; margin: 10px; }\n.test { padding: 5px; }"
-        },
-        {
-          'name' => 'Cascade with specificity',
-          'key' => 'cascade',
-          'css' => ".test { color: black; }\n#test { color: red; }\n.test { margin: 10px; }"
-        },
-        {
-          'name' => 'Important declarations',
-          'key' => 'important',
-          'css' => ".test { color: black !important; }\n#test { color: red; }\n.test { margin: 10px; }"
-        },
-        {
-          'name' => 'Shorthand expansion',
-          'key' => 'shorthand',
-          'css' => ".test { margin: 10px 20px; }\n.test { margin-left: 5px; }\n.test { padding: 1em 2em 3em 4em; }"
-        },
-        {
-          'name' => 'Complex merging',
-          'key' => 'complex',
-          'css' => "body { margin: 0; padding: 0; }\n.container { width: 100%; margin: 0 auto; }\n#main { background: white; color: black; }\n.button { padding: 10px 20px; border: 1px solid #ccc; }\n.button:hover { background: #f0f0f0; }\n.button.primary { background: blue !important; color: white; }"
-        }
-      ]
-    }
-  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 merging works correctly
-    css = ".test { color: black; }\n.test { margin: 10px; }"
-    cataract_rules = Cataract.parse_css(css)
-    cataract_merged = Cataract.merge(cataract_rules)
-
-    raise 'Cataract merge failed' if cataract_merged.rules.empty?
-
-    merged_decls = cataract_merged.rules.first.declarations
-    raise 'Cataract merge incorrect' unless merged_decls.any? { |d| d.property == 'color' }
-  end
-
-  def call
-    self.class.metadata['test_cases'].each do |test_case|
-      benchmark_test_case(test_case)
-    end
-  end
-
-  private
-
-  def benchmark_test_case(test_case)
-    puts '=' * 80
-    puts "TEST: #{test_case['name']}"
-    puts '=' * 80
-
-    key = test_case['key']
-    css = test_case['css']
-
-    # Pre-parse the CSS for both implementations
-    cataract_rules = Cataract.parse_css(css)
-
-    parser = CssParser::Parser.new
-    parser.add_block!(css)
-    rule_sets = []
-    parser.each_selector do |selector, declarations, _specificity|
-      rule_sets << CssParser::RuleSet.new(selectors: selector, block: declarations)
-    end
-
-    benchmark(key) do |x|
-      x.config(time: 5, warmup: 2)
-
-      x.report("css_parser: #{key}") do
-        CssParser.merge(rule_sets)
-      end
-
-      x.report("cataract: #{key}") do
-        Cataract.merge(cataract_rules)
-      end
-
-      x.compare!
-    end
-  end
-end
-
-# Run if executed directly
-MergingBenchmark.run if __FILE__ == $PROGRAM_NAME

data/benchmarks/benchmark_optimization_comparison.rb

@@ -1,168 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'benchmark/ips'
-require 'optparse'
-
-# Load the local development version, not installed gem
-$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
-require 'cataract'
-
-# =============================================================================
-# Generic Optimization Comparison Benchmark
-# =============================================================================
-#
-# This benchmark compares performance between different compile-time
-# optimizations using benchmark-ips's hold! functionality.
-#
-# Usage:
-#   1. Compile with baseline configuration:
-#      $ rake clean compile
-#      $ ruby test/benchmarks/benchmark_optimization_comparison.rb --baseline
-#
-#   2. In same terminal, compile with optimization:
-#      $ rake clean && env USE_LIKELY_UNLIKELY=1 rake compile
-#      $ ruby test/benchmarks/benchmark_optimization_comparison.rb --optimized
-#
-#   3. benchmark-ips will show comparison results from both runs
-#
-# The benchmark tests merge/cascade performance on bootstrap.css (~10k rules).
-# =============================================================================
-
-module OptimizationBenchmark
-  def self.run(variant: nil)
-    puts '=' * 80
-    puts 'OPTIMIZATION COMPARISON BENCHMARK'
-    puts '=' * 80
-
-    # Display current compile-time flags
-    puts "\nCurrently compiled with:"
-    Cataract::COMPILE_FLAGS.each do |flag, enabled|
-      status = enabled ? '✓ ENABLED' : '✗ disabled'
-      puts "  #{flag}: #{status}"
-    end
-    puts ''
-
-    # Load bootstrap.css fixture
-    fixtures_dir = File.expand_path('../test/fixtures', __dir__)
-    bootstrap_css_path = File.join(fixtures_dir, 'bootstrap.css')
-
-    unless File.exist?(bootstrap_css_path)
-      puts "❌ ERROR: bootstrap.css not found at #{bootstrap_css_path}"
-      exit 1
-    end
-
-    bootstrap_css = File.read(bootstrap_css_path)
-    puts 'Test file: bootstrap.css'
-    puts "  Lines: #{bootstrap_css.lines.count}"
-    puts "  Size: #{bootstrap_css.bytesize} bytes (#{(bootstrap_css.bytesize / 1024.0).round(1)} KB)"
-
-    # Parse once to get rules for merge benchmark
-    puts "\nParsing bootstrap.css to get rules..."
-    parser = Cataract::Stylesheet.new
-    begin
-      parser.add_block(bootstrap_css)
-      rules = parser.instance_variable_get(:@raw_rules) # Get raw rules array
-      puts "  ✅ Parsed successfully (#{rules.length} rules)"
-    rescue StandardError => e
-      puts "  ❌ ERROR: Failed to parse: #{e.message}"
-      exit 1
-    end
-
-    # Verify merge works before benchmarking
-    puts "\nVerifying merge..."
-    begin
-      merged = Cataract.apply_cascade(rules)
-      puts "  ✅ Merged successfully (#{merged.length} declarations)"
-    rescue StandardError => e
-      puts "  ❌ ERROR: Failed to merge: #{e.message}"
-      exit 1
-    end
-
-    # Auto-detect variant if not specified
-    if variant.nil?
-      # Check any optimization flag
-      has_optimization = Cataract::COMPILE_FLAGS.any? do |flag, enabled|
-        enabled && flag != :str_buf_optimization && flag != :debug
-      end
-      variant = has_optimization ? 'optimized' : 'baseline'
-    end
-
-    puts "\n#{'=' * 80}"
-    puts "RUNNING BENCHMARK (variant: #{variant})"
-    puts '=' * 80
-    puts 'Timing: 20s measurement, 5s warmup'
-    puts ''
-
-    Benchmark.ips do |x|
-      x.config(time: 20, warmup: 5)
-
-      x.report("merge_bootstrap_#{variant}") do
-        Cataract.apply_cascade(rules)
-      end
-    end
-
-    puts "\n#{'=' * 80}"
-    puts "DONE - #{variant}"
-    puts '=' * 80
-  end
-
-  def self.print_usage
-    puts <<~USAGE
-      Usage: #{$PROGRAM_NAME}
-
-      This benchmark will automatically detect which variant is compiled
-      and run the appropriate test.
-
-      Workflow:
-        # 1. Build baseline
-        rake clean && rake compile
-        ruby test/benchmarks/benchmark_optimization_comparison.rb --baseline
-
-        # 2. Build with optimization (e.g., LIKELY/UNLIKELY)
-        rake clean && USE_LIKELY_UNLIKELY=1 rake compile
-        ruby test/benchmarks/benchmark_optimization_comparison.rb --optimized
-
-        # 3. Compare results (benchmark-ips will show comparison automatically)
-
-      Specific optimization flags:
-        LIKELY/UNLIKELY:
-          USE_LIKELY_UNLIKELY=1 rake compile
-
-        Loop unrolling (raw CFLAGS still work):
-          CFLAGS="-funroll-loops" rake compile
-
-        Aggressive optimization:
-          CFLAGS="-O3 -march=native -funroll-loops" rake compile
-    USAGE
-  end
-end
-
-# =============================================================================
-# Main
-# =============================================================================
-
-if __FILE__ == $PROGRAM_NAME
-  require 'optparse'
-
-  variant = nil
-
-  OptionParser.new do |opts|
-    opts.banner = "Usage: #{$PROGRAM_NAME} [options]"
-
-    opts.on('--baseline', 'Run benchmark labeled as baseline') do
-      variant = 'baseline'
-    end
-
-    opts.on('--optimized', 'Run benchmark labeled as optimized') do
-      variant = 'optimized'
-    end
-
-    opts.on('-h', '--help', 'Show this help message') do
-      OptimizationBenchmark.print_usage
-      exit 0
-    end
-  end.parse!
-
-  OptimizationBenchmark.run(variant: variant)
-end