cataract 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: afbaeaaa174e69b056a175c1a0aed5da7f52e33fcbc4859448262aff427086f9
+  data.tar.gz: dd190c243a6d494ed1e87c155cdeda2e6843bbc827e048e8df7eb992d2c8d09b
+SHA512:
+  metadata.gz: '083570d10482fe637251a7d6fa912e6ec0ea3daa3d0283fa65b6f7aa54d798c693cb359fda1c6186bc5223504d9f31d91e6b359c170d718623279f2aac615186'
+  data.tar.gz: 5bd729068d06e069f625b2fc2d034dab769707f749ee175fbc420253cac953e52f8143194c1bca51a18bcd16d6190026e1823375b9eba3a564fd39a237e065ea

data/.clang-tidy

@@ -0,0 +1,30 @@
+---
+# clang-tidy configuration for Cataract CSS parser
+# Based on Ada URL parser's config: https://github.com/ada-url/ada
+
+Checks: >
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-exception-escape,
+  -bugprone-implicit-widening-of-multiplication-result,
+  -bugprone-narrowing-conversions,
+  -bugprone-suspicious-include,
+  -bugprone-unhandled-exception-at-new,
+  clang-analyzer-*,
+  -clang-analyzer-security.insecureAPI.DeprecatedOrUnsafeBufferHandling,
+
+# Turn all the warnings from the checks above into errors.
+WarningsAsErrors: '*'
+
+# Check first-party headers only (our own code in ext/cataract/)
+HeaderFilterRegex: 'ext/cataract/.*\.h$'
+
+# Don't check system headers (Ruby C API headers)
+SystemHeaders: false
+
+# Ruby C extension specific suppressions
+# (Add more as needed based on Ruby API conventions)
+CheckOptions:
+  # Ruby API uses long parameter lists (e.g., rb_struct_define_under)
+  - key: bugprone-easily-swappable-parameters.MinimumLength
+    value: 4

data/.github/workflows/ci-macos.yml

@@ -0,0 +1,12 @@
+name: CI - macOS (Manual)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test-macos:
+    uses: ./.github/workflows/test.yml
+    with:
+      os: macos-latest
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

data/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test-ubuntu:
+    uses: ./.github/workflows/test.yml
+    with:
+      os: ubuntu-latest
+    secrets:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+  lint:
+    if: github.actor == 'jamescook'
+    needs: test-ubuntu
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Cache clang-tidy results
+        id: lint-cache
+        uses: actions/cache@v4
+        with:
+          path: .lint-passed
+          key: lint-${{ hashFiles('ext/**/*.c', 'ext/**/*.h', '.clang-tidy', 'Gemfile') }}
+
+      - name: Install clang-tidy
+        if: steps.lint-cache.outputs.cache-hit != 'true'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang-tidy
+
+      - name: Run clang-tidy
+        if: steps.lint-cache.outputs.cache-hit != 'true'
+        run: |
+          clang-tidy --version
+          bundle exec rake lint
+          touch .lint-passed
+
+  docs:
+    # Only run on push to main (not PRs)
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: test-ubuntu
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Compile extension and generate documentation
+        run: bundle exec rake compile docs
+
+      - name: Disable Jekyll processing
+        run: touch docs/.nojekyll
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          allow_empty_commit: true

data/.github/workflows/test.yml

@@ -0,0 +1,76 @@
+name: Test Suite
+
+on:
+  workflow_call:
+    inputs:
+      os:
+        required: true
+        type: string
+        description: 'Operating system to run tests on'
+    secrets:
+      CODECOV_TOKEN:
+        required: false
+        description: 'Codecov upload token'
+
+jobs:
+  test:
+    runs-on: ${{ inputs.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ['3.1', '3.2', '3.3', '3.4']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+
+    - name: Display Ruby version
+      run: ruby --version
+
+    - name: Run tests
+      run: bundle exec rake compile test
+      env:
+        COVERAGE: 1
+
+    - name: Run debug test (Ruby 3.4 only)
+      if: matrix.ruby == '3.4'
+      run: |
+        bundle exec rake clean compile
+        bundle exec ruby -Ilib:test test/test_stylesheet.rb
+      env:
+        CONFIGURE_ARGS: --enable-debug
+
+    - name: Upload coverage to Codecov
+      if: runner.os == 'Linux' && matrix.ruby == '3.4'
+      uses: codecov/codecov-action@v5
+      with:
+        fail_ci_if_error: false
+        token: ${{ secrets.CODECOV_TOKEN }}
+        verbose: true
+
+    - name: Upload coverage report artifact
+      if: runner.os == 'Linux' && matrix.ruby == '3.4'
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report
+        path: coverage/
+        retention-days: 30
+
+  rubocop:
+    runs-on: ${{ inputs.os }}
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.4'
+        bundler-cache: true
+
+    - name: Run rubocop
+      run: bundle exec rubocop --fail-level W

data/.gitignore

@@ -0,0 +1,45 @@
+# Build artifacts
+tmp/
+*.gem
+*.so
+*.o
+
+# Generated C code from Ragel
+ext/**/cataract.c
+
+# Compiled extensions
+lib/**/*.so
+lib/**/*.bundle
+
+# Makefile generated by extconf.rb
+ext/**/Makefile
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor files
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+
+# Bundler
+vendor/
+.bundle/
+
+# Test artifacts
+coverage/
+test/.benchmark_results/
+test/fuzz_last_input.css
+test/fuzz_crash_*.css
+test/fuzz_crash_*.log
+
+# Benchmark results
+benchmarks/.results/
+benchmarks/.benchmark_results/
+
+# Documentation (generated by YARD)
+docs/
+.yardoc/

data/.overcommit.yml

@@ -0,0 +1,38 @@
+# Use this file to configure the Overcommit hooks you wish to use.
+# This will run before git commits and prevent commits if checks fail.
+
+# Uncomment the following lines to make Overcommit install hooks on `bundle install`
+gemfile: false
+
+PreCommit:
+  RuboCop:
+    enabled: true
+    on_warn: fail # Treat warnings as failures
+    command: ['bundle', 'exec', 'rubocop']
+    flags: ['--force-exclusion']
+    include:
+      - '**/*.rb'
+      - '**/*.rake'
+      - '**/Rakefile'
+      - '**/Gemfile'
+
+  TrailingWhitespace:
+    enabled: true
+    exclude:
+      - '**/vendor/**/*'
+      - '**/docs/**/*'
+      - '**/*.html'
+      - '**/*.css'
+
+  YamlSyntax:
+    enabled: true
+
+# Don't run checks on merge commits
+CommitMsg:
+  ALL:
+    requires_files: false
+    quiet: false
+
+PostCheckout:
+  ALL:
+    enabled: false

data/.rubocop.yml

@@ -0,0 +1,83 @@
+plugins:
+  - rubocop-performance
+  - rubocop-minitest
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'tmp/**/*'
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'test/fixtures/**/*'
+    - '**/*.so'
+    - '**/*.bundle'
+
+# extconf.rb uses standard Ruby C extension global variables ($CFLAGS, etc.)
+Style/GlobalVars:
+  Exclude:
+    - 'ext/**/extconf.rb'
+
+# Disable complexity metrics - too subjective and often leads to harder-to-read code
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+# Keep line length for tests disabled - long test strings are fine
+Layout/LineLength:
+  Exclude:
+    - 'benchmarks/**/*'
+    - 'test/**/*'
+    - 'scripts/**/*'
+    - '*.gemspec'
+  AllowedPatterns:
+    - '^\s*#'  # Allow long comment lines
+
+# Allow more assertions per test - strict limit is too restrictive
+Minitest/MultipleAssertions:
+  Max: 10
+
+Style/Documentation:
+   Enabled: true
+   Exclude:
+    - 'test/**/*'
+    - 'benchmarks/**/*'
+
+# Disable modifier if/unless enforcement - use it when it's clearer, not because a cop says so
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  Exclude:
+    - 'test/**/*'
+
+# Allow numbers in test method names - they represent actual values being tested
+Naming/VariableNumber:
+  Exclude:
+    - 'test/**/*'
+
+Naming/PredicatePrefix:
+  Exclude:
+    - 'lib/**/*.rb'

data/BENCHMARKS.md

@@ -0,0 +1,201 @@
+<!-- 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**: ruby 3.4.5 (2025-07-16 revision 20cda200d3) +YJIT +PRISM [arm64-darwin23]
+- **CPU**: Apple M1 Pro
+- **Memory**: 32GB
+- **OS**: macOS 14.5
+- **Generated**: 2025-10-30T16:01:15-05:00
+
+<details>
+<summary><h2>CSS Parsing</h2></summary>
+
+Performance of parsing CSS into internal data structures.
+
+Time to parse CSS into internal data structures
+
+### Small CSS (64 lines, 1.0KB)
+
+
+| Parser | Speed | Time per operation |
+|--------|-------|-------------------|
+| css_parser | 6.16K i/s | 162.34 μs |
+| **Cataract** | **63.79K i/s** | **15.68 μs** |
+| **Speedup** | **10.36x faster** | |
+
+### Medium CSS with @media (139 lines, 1.6KB)
+
+
+| Parser | Speed | Time per operation |
+|--------|-------|-------------------|
+| css_parser | 3.44K i/s | 290.64 μs |
+| **Cataract** | **41.45K i/s** | **24.13 μs** |
+| **Speedup** | **12.05x faster** | |
+
+
+</details>
+
+---
+
+<details>
+<summary><h2>CSS Serialization (to_s)</h2></summary>
+
+Performance of converting parsed CSS back to string format.
+
+Time to convert parsed CSS back to string format
+
+### Full Serialization (Bootstrap CSS - 191KB)
+
+
+| Parser | Speed | Time per operation |
+|--------|-------|-------------------|
+| css_parser | 34.0 i/s | 29.41 ms |
+| **Cataract** | **714.8 i/s** | **1.4 ms** |
+| **Speedup** | **21.02x faster** | |
+
+### Media Type Filtering (print only)
+
+
+| Parser | Speed | Time per operation |
+|--------|-------|-------------------|
+| css_parser | 4.06K i/s | 246.56 μs |
+| **Cataract** | **232.22K i/s** | **4.31 μs** |
+| **Speedup** | **57.26x faster** | |
+
+
+</details>
+
+---
+
+<details>
+<summary><h2>Specificity Calculation</h2></summary>
+
+Performance of calculating CSS selector specificity values.
+
+Time to calculate CSS selector specificity values
+
+| Test Case | Speedup |
+|-----------|---------|
+| Simple Selectors | **22.03x faster** |
+| Compound Selectors | **30.55x faster** |
+| Combinators | **28.34x faster** |
+| Pseudo-classes & Pseudo-elements | **46.06x faster** |
+| :not() Pseudo-class (CSS3) | **23.64x faster** |
+| Complex Real-world Selectors | **49.17x faster** |
+
+**Summary:** 22.03x faster to 49.17x faster (avg 33.3x faster)
+
+</details>
+
+---
+
+<details>
+<summary><h2>CSS Merging</h2></summary>
+
+Performance of merging multiple CSS rule sets with the same selector.
+
+Time to merge multiple CSS rule sets with same selector
+
+| Test Case | Speedup |
+|-----------|---------|
+| No shorthand properties (large) | **4.14x faster** |
+| Simple properties | **3.86x faster** |
+| Cascade with specificity | **5.75x faster** |
+| Important declarations | **6.1x faster** |
+| Shorthand expansion | **4.16x faster** |
+| Complex merging | **3.07x faster** |
+
+**Summary:** 3.07x faster to 6.1x faster (avg 4.51x faster)
+
+### 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>
+
+---
+
+<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.
+
+Ruby-side operations with and without YJIT
+
+### Operations Per Second
+
+| Operation | Without YJIT | With YJIT | YJIT Improvement |
+|-----------|--------------|-----------|------------------|
+| property access | 227.18K i/s | 322.32K i/s | **1.42x faster** (42% faster) |
+| declaration merging | 204.26K i/s | 337.81K i/s | **1.65x faster** (65% faster) |
+| to_s generation | 242.66K i/s | 391.16K i/s | **1.61x faster** (61% faster) |
+| parse + iterate | 121.52K i/s | 142.77K i/s | **1.17x faster** (17% faster) |
+
+### 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>
+
+---
+
+## Summary
+
+### Performance Highlights
+
+| Category | Min Speedup | Max Speedup | Avg Speedup |
+|----------|-------------|-------------|-------------|
+| **Parsing** | 10.36x faster | 12.05x faster | 11.2x faster |
+| **Serialization** | 21.02x faster | 57.26x faster | 39.14x faster |
+| **Specificity** | 22.03x faster | 49.17x faster | 33.3x faster |
+| **Merging** | 3.07x faster | 6.1x faster | 4.51x faster |
+
+### 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/CHANGELOG.md

@@ -0,0 +1 @@
+## [0.1.0] - 2025-11-09

data/Gemfile

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cataract.gemspec
+gemspec
+
+# Build dependencies
+gem 'rake', '~> 13.0'
+gem 'rake-compiler', '~> 1.0'
+
+# Development/benchmarking dependencies (not needed by gem users)
+gem 'benchmark-ips', '~> 2.0'
+gem 'css_parser', '~> 1.0' # for benchmarking against
+gem 'minitest'
+gem 'minitest-spec'
+gem 'simplecov', require: false
+gem 'simplecov-cobertura', require: false
+gem 'webmock', '~> 3.0' # for testing URL loading
+
+gem 'overcommit', '~> 0.64', group: :development
+gem 'premailer'
+gem 'rubocop', '~> 1.81', group: :development
+gem 'rubocop-minitest', '~> 0.38.2', group: :development
+gem 'rubocop-performance', '~> 1.26', group: :development
+
+gem 'yard', '~> 0.9', group: :development

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 James Cook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/RAGEL_MIGRATION.md

@@ -0,0 +1,60 @@
+# Ragel to Pure C Migration
+
+## Why We Switched
+
+Started with Ragel as an experiment for the CSS parser, but quickly moved to hand-written pure C in October 2024.
+
+### Performance
+
+Benchmarks showed the pure C implementation was **2.08x faster** than Ragel's default style (T0):
+
+```
+Parsing bootstrap.css (10,000 iterations)
+Ragel (T0):  1.234s
+Pure C:      0.593s  (2.08x faster)
+```
+
+While Ragel's F0/F1 styles were faster than T0, they produced significantly larger binaries and had longer compile times.
+
+### Compilation Speed
+
+- **Ragel**: 2-3 seconds to generate C code, then compile
+- **Pure C**: Immediate compilation, no code generation step
+
+Some Ragel styles (G0/G1/G2) never finished compiling - waited 10+ minutes before giving up.
+
+### Ragel Complexity Issues
+
+Hit walls with non-determinism and state machine complexity:
+- Adding `@charset` support caused compile times to explode
+- Issues with entering/leaving characters in complex patterns
+- State machine became too complex for Ragel to optimize efficiently
+
+### Binary Size
+
+Hand-written C produces smaller binaries compared to Ragel's generated code, especially the faster F0/F1 styles.
+
+### Maintainability
+
+- Pure C is more familiar to contributors (no Ragel DSL to learn)
+- Easier to debug (no generated code indirection)
+- Standard C tooling works out of the box (debuggers, profilers, linters)
+- No build-time Ragel dependency for gem users
+
+### Build Simplicity
+
+Removing Ragel eliminated:
+- Build-time dependency on Ragel binary
+- Separate code generation step in CI
+- Platform-specific Ragel installation issues
+- Complexity in the build toolchain
+
+## Trade-offs
+
+Pure C is more verbose than Ragel's DSL, but the performance gains and simpler build process made it an easy choice.
+
+## Details
+
+- Swapped in October 2024
+- Files: `css_parser.c`, `specificity.c`, `value_splitter.c`
+- API unchanged, all tests pass