cataract 0.1.0

data/README.md

@@ -0,0 +1,292 @@
+# Cataract
+
+A performant CSS parser for accurate parsing of complex CSS structures.
+
+[![codecov](https://codecov.io/github/jamescook/cataract/graph/badge.svg?token=1PTVV1QTV5)](https://codecov.io/github/jamescook/cataract)
+
+**[API Documentation](https://jamescook.github.io/cataract/)**
+
+## Features
+
+- **C Extension**: Performance-focused C implementation for parsing and serialization
+- **CSS2 Support**: Selectors, combinators, pseudo-classes, pseudo-elements, @media queries
+- **CSS3 Support**: Attribute selectors (`^=`, `$=`, `*=`)
+- **CSS Color Level 4**: Supports hex, rgb, hsl, hwb, oklab, oklch, and named colors with high precision
+- **Specificity Calculation**: Automatic CSS specificity computation
+- **Media Query Filtering**: Query rules by media type
+- **Zero Runtime Dependencies**: Pure C extension with no runtime gem dependencies
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem 'cataract'
+```
+
+Or install directly:
+
+```bash
+gem install cataract
+```
+
+### Requirements
+
+- Ruby >= 3.1.0
+
+## Usage
+
+### Basic Parsing
+
+```ruby
+require 'cataract'
+
+# Parse CSS
+sheet = Cataract::Stylesheet.parse(<<~CSS)
+  body { margin: 0; padding: 0 }
+
+  @media screen and (min-width: 768px) {
+    .container { width: 750px }
+  }
+
+  div.header > h1:hover { color: blue }
+CSS
+
+# Get all selectors
+sheet.selectors
+# => ["body", ".container", "div.header > h1:hover"]
+
+# Get all rules
+sheet.rules.each do |rule|
+  puts "#{rule.selector}: #{rule.declarations.length} declarations"
+end
+
+# Access specific rule
+body_rule = sheet.rules.first
+body_rule.selector       # => "body"
+body_rule.specificity    # => 1
+body_rule.declarations   # => [#<Declaration property="margin" value="0">, ...]
+
+# Count rules
+sheet.rules_count
+# => 3
+
+# Serialize back to CSS
+sheet.to_s
+# => "body { margin: 0; padding: 0; } @media screen and (min-width: 768px) { .container { width: 750px; } } ..."
+```
+
+### Advanced Filtering with Enumerable
+
+`Cataracy::Stylesheet` implements `Enumerable`, providing standard Ruby collection methods plus chainable scopes:
+
+```ruby
+sheet = Cataract::Stylesheet.parse(css)
+
+# Basic Enumerable methods work
+sheet.map(&:selector)                    # => ["body", ".container", "div.header > h1:hover"]
+sheet.select(&:selector?).count          # => Count only selector-based rules (excludes @keyframes, etc.)
+sheet.find { |r| r.selector == 'body' }  # => First rule matching selector
+
+# Filter to selector-based rules only (excludes at-rules like @keyframes, @font-face)
+sheet.select(&:selector?).each do |rule|
+  puts "#{rule.selector}: specificity #{rule.specificity}"
+end
+
+# Filter by media query (returns chainable scope)
+sheet.with_media(:print).each do |rule|
+  puts "Print rule: #{rule.selector}"
+end
+
+# Filter by selector (returns chainable scope)
+sheet.with_selector('body').each do |rule|
+  puts "Body rule has #{rule.declarations.length} declarations"
+end
+
+# Filter by specificity (returns chainable scope)
+sheet.with_specificity(100..).each do |rule|
+  puts "High specificity: #{rule.selector} (#{rule.specificity})"
+end
+
+# Chain filters together
+sheet.with_media(:screen)
+     .with_specificity(50..200)
+     .select(&:selector?)
+     .map(&:selector)
+# => ["#header .nav", ".sidebar > ul li"]
+
+# Find all rules with a specific property
+sheet.select(&:selector?).select do |rule|
+  rule.declarations.any? { |d| d.property == 'color' }
+end
+
+# Find high-specificity selectors (potential refactoring targets)
+sheet.with_specificity(100..).select(&:selector?).each do |rule|
+  puts "Refactor candidate: #{rule.selector} (specificity: #{rule.specificity})"
+end
+
+# Find positioned elements in screen media
+sheet.with_media(:screen).select do |rule|
+  rule.selector? && rule.declarations.any? do |d|
+    d.property == 'position' && d.value == 'relative'
+  end
+end
+
+# Terminal operations force evaluation
+sheet.with_media(:print).to_a         # => Array of rules
+sheet.with_selector('.header').size   # => 3
+sheet.with_specificity(10..50).empty? # => false
+```
+
+See [BENCHMARKS.md](BENCHMARKS.md) for detailed performance comparisons.
+
+## CSS Support
+
+Cataract aims to support all CSS specifications including:
+- **Selectors**: All CSS2/CSS3 selectors (type, class, ID, attribute, pseudo-classes, pseudo-elements, combinators)
+- **At-rules**: `@media`, `@font-face`, `@keyframes`, `@supports`, `@page`, `@layer`, `@container`, `@property`, `@scope`, `@counter-style`
+- **Media Queries**: Full support including nested queries and media features
+- **Special syntax**: Data URIs, `calc()`, `url()`, CSS functions with parentheses
+- **!important**: Full support with correct cascade behavior
+
+### Color Conversion
+
+Cataract supports converting colors between multiple CSS color formats with high precision.
+
+**Note:** Color conversion is an optional extension. Load it explicitly to reduce memory footprint:
+
+```ruby
+require 'cataract'
+require 'cataract/color_conversion'
+
+# Convert hex to RGB
+sheet = Cataract::Stylesheet.parse('.button { color: #ff0000; background: #00ff00; }')
+sheet.convert_colors!(from: :hex, to: :rgb)
+sheet.to_s
+# => ".button { color: rgb(255 0 0); background: rgb(0 255 0); }"
+
+# Convert RGB to HSL for easier color manipulation
+sheet = Cataract::Stylesheet.parse('.card { color: rgb(255, 128, 0); }')
+sheet.convert_colors!(from: :rgb, to: :hsl)
+sheet.to_s
+# => ".card { color: hsl(30, 100%, 50%); }"
+
+# Convert to Oklab for perceptually uniform colors
+sheet = Cataract::Stylesheet.parse('.gradient { background: linear-gradient(#ff0000, #0000ff); }')
+sheet.convert_colors!(to: :oklab)
+sheet.to_s
+# => ".gradient { background: linear-gradient(oklab(0.6280 0.2249 0.1258), oklab(0.4520 -0.0325 -0.3115)); }"
+
+# Auto-detect source format and convert all colors
+sheet = Cataract::Stylesheet.parse(<<~CSS)
+  .mixed {
+    color: #ff0000;
+    background: rgb(0, 255, 0);
+    border-color: hsl(240, 100%, 50%);
+  }
+CSS
+sheet.convert_colors!(to: :hex)  # Converts all formats to hex
+```
+
+#### Supported Color Formats
+
+| Format | From | To | Alpha | Example | Notes |
+|--------|------|-----|-------|---------|-------|
+| **hex** | ✓ | ✓ | ✓ | `#ff0000`, `#f00`, `#ff000080` | 3, 6, or 8 digit hex |
+| **rgb** | ✓ | ✓ | ✓ | `rgb(255 0 0)`, `rgb(255, 0, 0)` | Modern & legacy syntax |
+| **hsl** | ✓ | ✓ | ✓ | `hsl(0, 100%, 50%)` | Hue, saturation, lightness |
+| **hwb** | ✓ | ✓ | ✓ | `hwb(0 0% 0%)` | Hue, whiteness, blackness |
+| **oklab** | ✓ | ✓ | ✓ | `oklab(0.628 0.225 0.126)` | Perceptually uniform color space |
+| **oklch** | ✓ | ✓ | ✓ | `oklch(0.628 0.258 29.2)` | Cylindrical Oklab (LCh) |
+| **lab** | ✓ | ✓ | ✓ | `lab(53.2% 80.1 67.2)` | CIE L\*a\*b\* color space (D50) |
+| **lch** | ✓ | ✓ | ✓ | `lch(53.2% 104.5 40)` | Cylindrical Lab (polar coordinates) |
+| **named** | ✓ | ✓ | – | `red`, `blue`, `rebeccapurple` | 147 CSS named colors |
+| **color()** | – | – | – | `color(display-p3 1 0 0)` | Absolute color spaces (planned) |
+
+**Format aliases:**
+- `:rgba` → uses `rgb()` syntax with alpha
+- `:hsla` → uses `hsl()` syntax with alpha
+- `:hwba` → uses `hwb()` syntax with alpha
+
+**Limitations:**
+- Math functions (`calc()`, `min()`, `max()`, `clamp()`) are not evaluated and will be preserved unchanged
+- CSS Color Level 5 features (`none`, `infinity`, relative color syntax with `from`) are preserved but not converted
+- Unknown or future color functions are passed through unchanged
+
+### `@import` Support
+
+`@import` statements can be resolved with security controls:
+
+```ruby
+# Disabled by default
+sheet = Cataract::Stylesheet.parse(css)  # @import statements are ignored
+
+# Enable with safe defaults (HTTPS only, .css files only, max depth 5)
+sheet = Cataract::Stylesheet.parse(css, import: true)
+
+# Custom options for full control
+sheet = Cataract::Stylesheet.parse(css, import: {
+  allowed_schemes: ['https', 'file'],   # Default: ['https']
+  extensions: ['css'],                   # Default: ['css']
+  max_depth: 3,                          # Default: 5
+  timeout: 10,                           # Default: 10 seconds
+  follow_redirects: true                 # Default: true
+})
+```
+
+**Security note**: Import resolution includes protections against:
+- Unauthorized schemes (file://, data://, etc.)
+- Non-CSS file extensions
+- Circular references
+- Excessive nesting depth
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Compile the C extension
+rake compile
+
+# Run tests
+rake test
+
+# Run benchmarks
+rake benchmark
+
+# Run fuzzer to test parser robustness
+rake fuzz                      # 10,000 iterations (default)
+rake fuzz ITERATIONS=100000    # Custom iteration count
+```
+
+**Fuzzer**: Generates random CSS input to test parser robustness against malformed or edge-case CSS. Helps catch crashes, memory leaks, and parsing edge cases.
+
+## How It Works
+
+Cataract uses a high-performance C implementation for CSS parsing and serialization.
+
+Each `Rule` is a struct containing:
+- `id`: Integer ID (position in rules array)
+- `selector`: The CSS selector string
+- `declarations`: Array of `Declaration` structs (property, value, important flag)
+- `specificity`: Calculated CSS specificity (cached)
+
+Implementation details:
+- **C implementation**: Critical paths implemented in C (parsing, merging, serialization)
+- **Flat rule array**: All rules stored in a single array, preserving source order
+- **Efficient media query handling**: O(1) lookup via internal media index
+- **Memory efficient**: Minimal allocations, reuses string buffers where possible
+- **Comprehensive parsing**: Preserves complex CSS structures including nested media queries, nested selectors, data URIs, CSS functions (calc(), var(), etc.)
+
+## Development Notes
+
+Significant portions of this codebase were generated with assistance from [Claude Code](https://claude.com/claude-code), including the benchmark infrastructure, test suite, and documentation generation system.
+
+## License
+
+MIT
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jamescook/cataract.

data/Rakefile

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'rake/clean'
+
+# Load tasks from lib/tasks/
+Dir.glob('lib/tasks/**/*.rake').each { |r| load r }
+
+# Only load extension task if rake-compiler is available
+begin
+  require 'rake/extensiontask'
+
+  # Configure the main extension
+  Rake::ExtensionTask.new('cataract') do |ext|
+    ext.lib_dir = 'lib/cataract'
+    ext.ext_dir = 'ext/cataract'
+  end
+
+  # Configure the color conversion extension (optional, loaded on-demand)
+  Rake::ExtensionTask.new('cataract_color') do |ext|
+    ext.lib_dir = 'lib/cataract'
+    ext.ext_dir = 'ext/cataract_color'
+  end
+end
+
+# Configure CLEAN to run before compilation
+# rake-compiler already adds: tmp/, lib/**/*.{so,bundle}, etc.
+# All C files are now hand-written (Ragel removed), so only clean build artifacts
+CLEAN.include('ext/**/Makefile', 'ext/**/*.o')
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  # Load test_helper before running tests (handles SimpleCov setup)
+  t.ruby_opts << '-rtest_helper'
+  # Exclude css_parser_compat directory (reference tests only, not run)
+  t.test_files = FileList['test/**/test_*.rb'].exclude('test/css_parser_compat/**/*')
+end
+
+desc 'Run all benchmarks'
+task :benchmark do
+  Rake::Task[:compile].invoke
+  Rake::Task['benchmark:parsing'].invoke
+  Rake::Task['benchmark:serialization'].invoke
+  Rake::Task['benchmark:specificity'].invoke
+  Rake::Task['benchmark:merging'].invoke
+  Rake::Task['benchmark:yjit'].invoke
+  puts "\n#{'-' * 80}"
+  puts 'All benchmarks complete!'
+  puts 'Generate documentation with: rake benchmark:generate_docs'
+  puts '-' * 80
+end
+
+namespace :benchmark do
+  desc 'Benchmark CSS parsing performance'
+  task :parsing do
+    puts 'Running parsing benchmark...'
+    ruby 'benchmarks/benchmark_parsing.rb'
+  end
+
+  desc 'Benchmark CSS serialization (to_s) performance'
+  task :serialization do
+    puts 'Running serialization benchmark...'
+    ruby 'benchmarks/benchmark_serialization.rb'
+  end
+
+  desc 'Benchmark specificity calculation performance'
+  task :specificity do
+    puts 'Running specificity benchmark...'
+    ruby 'benchmarks/benchmark_specificity.rb'
+  end
+
+  desc 'Benchmark CSS merging performance'
+  task :merging do
+    puts 'Running merging benchmark...'
+    ruby 'benchmarks/benchmark_merging.rb'
+  end
+
+  desc 'Benchmark Ruby-side operations with YJIT on vs off'
+  task :yjit do
+    puts 'Running YJIT benchmark...'
+    ruby 'benchmarks/benchmark_yjit.rb'
+  end
+
+  desc 'Benchmark string allocation optimization (buffer vs dynamic)'
+  task :string_allocation do
+    # Clean up any existing benchmark results
+    results_dir = 'benchmarks/.benchmark_results'
+    if Dir.exist?(results_dir)
+      Dir.glob(File.join(results_dir, 'string_allocation_*.json')).each do |file|
+        puts "Removing old benchmark results: #{file}"
+        FileUtils.rm_f(file)
+      end
+    end
+
+    puts "\n#{'=' * 80}"
+    puts 'Compiling with DYNAMIC allocation (rb_str_new_cstr)'
+    puts '=' * 80
+    system({ 'CONFIGURE_ARGS' => '--disable-str-buf-optimization' }, 'rake', 'compile')
+    system({}, RbConfig.ruby, 'benchmarks/benchmark_string_allocation.rb')
+
+    puts "\n\n#{'=' * 80}"
+    puts 'Compiling with BUFFER allocation (rb_str_buf_new, production default)'
+    puts '=' * 80
+    system({}, 'rake', 'compile')
+    system({}, RbConfig.ruby, 'benchmarks/benchmark_string_allocation.rb')
+  end
+
+  desc 'Generate BENCHMARKS.md from benchmark results'
+  task :generate_docs do
+    ruby 'scripts/generate_benchmarks_md.rb'
+  end
+end
+
+task compile: :clean
+
+task default: :test
+
+# Lint task - runs clang-tidy on C code
+desc 'Run clang-tidy on C code'
+task :lint do
+  # Find clang-tidy binary
+  clang_tidy = nil
+
+  # Try system PATH first (Linux, or if user has llvm in PATH)
+  if system('which clang-tidy > /dev/null 2>&1')
+    clang_tidy = 'clang-tidy'
+  # On macOS, check Homebrew LLVM (keg-only, not in PATH by default)
+  elsif system('which brew > /dev/null 2>&1')
+    llvm_prefix = `brew --prefix llvm 2>/dev/null`.strip
+    clang_tidy = "#{llvm_prefix}/bin/clang-tidy" if !llvm_prefix.empty? && File.exist?("#{llvm_prefix}/bin/clang-tidy")
+  end
+
+  unless clang_tidy
+    abort("clang-tidy not installed.\n  " \
+          "macOS: brew install llvm\n  " \
+          "Ubuntu/Debian: apt-get install clang-tidy\n  " \
+          'Fedora/RHEL: dnf install clang-tools-extra')
+  end
+
+  puts 'Running clang-tidy on C code...'
+
+  # Find all .c files in ext/cataract/ and ext/cataract_color/
+  c_files = Dir.glob('ext/cataract/*.c') + Dir.glob('ext/cataract_color/*.c')
+
+  # Run clang-tidy on each file
+  # Note: clang-tidy uses the .clang-tidy config file automatically
+  # We pass Ruby include path so it can find ruby.h
+  ruby_include = RbConfig::CONFIG['rubyhdrdir']
+  ruby_arch_include = RbConfig::CONFIG['rubyarchhdrdir']
+
+  success = c_files.all? do |file|
+    puts "  Checking #{file}..."
+    system(clang_tidy, '--quiet', file, '--',
+           "-I#{ruby_include}",
+           "-I#{ruby_arch_include}",
+           '-Iext/cataract',
+           '-Iext/cataract_color')
+  end
+
+  if success
+    puts '✓ clang-tidy passed'
+  else
+    abort('clang-tidy found issues!')
+  end
+end
+
+# Fuzz testing
+desc 'Run fuzzer to test parser robustness (including color conversion)'
+task fuzz: :compile do
+  iterations = ENV['ITERATIONS'] || '10000'
+  puts "Running CSS parser fuzzer (#{iterations} iterations)..."
+  # Use system with ENV.to_h to preserve environment variables like FUZZ_GC_STRESS
+  system(ENV.to_h, RbConfig.ruby, '-Ilib', 'scripts/fuzzer/run.rb', iterations)
+end
+
+# Documentation generation with YARD
+begin
+  require 'yard'
+
+  desc 'Generate example CSS analysis for documentation'
+  task :generate_example do
+    puts 'Generating GitHub CSS analysis example...'
+    # Generate with file. prefix for YARD compatibility
+    system('ruby examples/css_analyzer.rb https://github.com -o docs/file.github_analysis.html')
+  end
+
+  desc 'Generate documentation and open in browser'
+  task docs: :generate_example do
+    # Generate YARD documentation
+    YARD::CLI::Yardoc.run('--output-dir', 'docs', '--readme', 'README.md',
+                          '--title', 'Cataract - Fast CSS Parser',
+                          'lib/**/*.rb', 'ext/**/*.c', '-', 'docs/files/EXAMPLE.md')
+
+    # Open in browser (skip in CI)
+    unless ENV['CI']
+      system('open docs/index.html') if RUBY_PLATFORM.include?('darwin')
+      system('xdg-open docs/index.html') if RUBY_PLATFORM.include?('linux')
+    end
+  end
+
+  desc 'List undocumented code'
+  task :undoc do
+    system('yard stats --list-undoc')
+  end
+rescue LoadError
+  # YARD not available - skip doc tasks
+end

data/benchmarks/benchmark_harness.rb

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