cataract 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89396bf500fc32cfa8d632d90f8b1ff5e80b93a24793cc8c6fd183ca47619f7e
-  data.tar.gz: bef49a87c354f9947616bb4d07047bb876e7a2861a7de2e2846f2dd0cd9cd8e8
+  metadata.gz: bcb5043777c52ed2a3f4bcd96966dcbe00e0f7bcf5ac410398afc855d59407f5
+  data.tar.gz: 65fabbfff1bbc559a0998f5a412800987ed2921252cdd2d4a757c6b59041c66a
 SHA512:
-  metadata.gz: 0d395bcb60f2a6646daae924eabe1c83c2aa79e174de9186b6ab3bf9f855c34a2f464fa1d221e550afa47d4e271b0aaf9d4184986ac516d0feb412fecd18772f
-  data.tar.gz: feb093da902ee218121c112471c2ea899540373c9ce74eff0db588f94ae5ab0992f7b39014bf6a3edb74a54e9b11e7f80d7c584f15dd08a56e4e4b37a63ee2c1
+  metadata.gz: cee4076685ff5a5e6ae8dbe441a9e7cefc8f1ad109fa7179373cb0bb39e4118b570ddfef68aeef573b002a683b3ca66148293f460b52a562472596d4d1e11842
+  data.tar.gz: de9ae8a5f1d684c797706b48e10e7372cda9ae280698e67ea3dac25be81331a901c9a181dd8ca04d2cb9ce46b2447fc0709501b0fd53c848bcc6981a4d286597

data/.github/workflows/ci-manual-rubies.yml

@@ -0,0 +1,44 @@
+name: CI - Manual Rubies
+
+on:
+  workflow_dispatch:
+
+jobs:
+  test-jruby:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: jruby
+        bundler-cache: true
+
+    - name: Display Ruby version
+      run: ruby --version
+
+    - name: Run tests
+      run: bundle exec rake test:pure
+
+  test-alt-rubies:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [truffleruby, ruby-head]
+
+    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

data/.overcommit.yml

@@ -8,7 +8,7 @@ PreCommit:
   RuboCop:
     enabled: true
     on_warn: fail # Treat warnings as failures
-    command: ['bundle', 'exec', 'rubocop']
+    # Remove explicit command to allow Overcommit to pass staged files only
     flags: ['--force-exclusion']
     include:
       - '**/*.rb'

data/.rubocop.yml

@@ -1,3 +1,8 @@
+inherit_from: .rubocop_todo.yml
+
+require:
+  - ./.rubocop/cataract/ban_assert_includes.rb
+
 plugins:
   - rubocop-performance
   - rubocop-minitest
@@ -44,6 +49,12 @@ Metrics/BlockLength:
 Metrics/ParameterLists:
   Enabled: false
 
+# Block nesting in byte-level parsers reflects CSS structure, not complexity
+# Extracting helper methods would add method dispatch overhead in hot path
+Metrics/BlockNesting:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
 # Keep line length for tests disabled - long test strings are fine
 Layout/LineLength:
   Exclude:
@@ -58,11 +69,17 @@ Layout/LineLength:
 Minitest/MultipleAssertions:
   Max: 10
 
-Style/Documentation:
-   Enabled: true
-   Exclude:
+# Disable ambiguous block association warnings in tests
+# Tests frequently use assert/refute with blocks that call methods with their own blocks,
+# e.g., `assert sheet.rules.any? { |r| r == '.box { color: red; }' }`
+# This compares Rule objects against CSS strings using our custom Rule#== implementation.
+# While this triggers the ambiguous block warning, it's intentional and clear in context.
+Lint/AmbiguousBlockAssociation:
+  Exclude:
     - 'test/**/*'
-    - 'benchmarks/**/*'
+
+Style/Documentation:
+   Enabled: false
 
 # Disable modifier if/unless enforcement - use it when it's clearer, not because a cop says so
 Style/IfUnlessModifier:
@@ -81,3 +98,78 @@ Naming/VariableNumber:
 Naming/PredicatePrefix:
   Exclude:
     - 'lib/**/*.rb'
+
+# Performance-critical hot path exclusions for lib/cataract/pure
+# These cosmetic style rules add overhead via method dispatch or allocation
+
+# Disable numeric predicates in hot path - method dispatch overhead
+# Benchmark shows `> 0` is faster than `.positive?` due to avoiding method call
+Style/NumericPredicate:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable multiple comparison style - avoid array allocation
+# `||` chain is faster than `Array#include?` which allocates an array
+Style/MultipleComparison:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable zero-length predicate in hot path - method dispatch overhead
+# Direct comparison `.length > 0` is faster than `.empty?` method call
+Style/ZeroLengthPredicate:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Benchmarked range vs offsets. Range has to allocated
+# so not ideal in the hot path
+Style/SlicingWithRange:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable modifier while/until style in parsing code - readability
+# Byte-level parsing loops are clearer with traditional while...end form
+# Example: `while i < len && ident_char?(selector.getbyte(i)); i += 1; end`
+# is more readable than `i += 1 while i < len && ident_char?(selector.getbyte(i))`
+Style/WhileUntilModifier:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable between? suggestion in hot path - method dispatch overhead
+# Benchmark shows `byte >= X && byte <= Y` is 2.60-4.82x faster than `.between?(X, Y)`
+Style/ComparableBetween:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+# Disable map suggestion for array building - performance
+# Benchmark shows `each { arr << x }` is 1.05-1.11x faster than `arr = map { x }`
+# The << pattern is faster than map's implicit array return (even without YJIT)
+Style/MapIntoArray:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/cataract/pure/**/*.rb'
+
+Style/StderrPuts:
+  Exclude:
+    - 'scripts/**/*.rb'
+
+# Disable all performance cops in tests - test clarity is more important than micro-optimizations
+# Performance suggestions often hurt readability without meaningful benefit in test code
+Performance:
+  Exclude:
+    - 'test/**/*'
+
+Style/HashLikeCase:
+  Exclude:
+    - 'benchmarks/**/*'
+
+# Custom Cataract cops
+Cataract/BanAssertIncludes:
+  Enabled: true
+  Include:
+    - 'test/**/*'
+  Exclude:
+    - 'test/test_benchmark_doc_generator.rb'
+    - 'test/support/**/*'  # Support files define assert_contains which uses assert_includes internally

data/.rubocop_todo.yml

@@ -0,0 +1,186 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-11-12 02:24:55 UTC using RuboCop version 1.81.7.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 13
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLineAfterGuardClause:
+  Exclude:
+    - 'benchmarks/benchmark_merging.rb'
+    - 'benchmarks/benchmark_parsing.rb'
+    - 'benchmarks/benchmark_serialization.rb'
+    - 'benchmarks/benchmark_specificity.rb'
+    - 'scripts/generate_benchmarks_md.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Layout/EmptyLinesAfterModuleInclusion:
+  Exclude:
+    - 'benchmarks/parsing_tests.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/MultilineOperationIndentation:
+  Exclude:
+    - 'lib/cataract/pure/helpers.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Lint/AmbiguousOperatorPrecedence:
+  Exclude:
+    - 'lib/cataract/pure/flatten.rb'
+
+# Offense count: 2
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
+  Exclude:
+    - 'lib/cataract/pure/flatten.rb'
+
+# Offense count: 1
+Lint/IneffectiveAccessModifier:
+  Exclude:
+    - 'benchmarks/speedup_calculator.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: ContextCreatingMethods, MethodCreatingMethods.
+Lint/UselessAccessModifier:
+  Exclude:
+    - 'benchmarks/speedup_calculator.rb'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+Lint/UselessAssignment:
+  Exclude:
+    - 'benchmarks/benchmark_merging.rb'
+    - 'benchmarks/benchmark_parsing.rb'
+    - 'benchmarks/benchmark_serialization.rb'
+    - 'benchmarks/benchmark_specificity.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Minitest/EmptyLineBeforeAssertionMethods:
+  Exclude:
+    - 'test/test_stylesheet.rb'
+
+# Offense count: 7
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Performance/UnfreezeString:
+  Exclude:
+    - 'lib/cataract/pure.rb'
+    - 'lib/cataract/pure/flatten.rb'
+    - 'lib/cataract/pure/parser.rb'
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, SingleLineConditionsOnly, IncludeTernaryExpressions.
+# SupportedStyles: assign_to_condition, assign_inside_condition
+Style/ConditionalAssignment:
+  Exclude:
+    - 'lib/cataract/pure/imports.rb'
+    - 'lib/cataract/pure/flatten.rb'
+
+# Offense count: 4
+# Configuration parameters: AllowedConstants.
+Style/Documentation:
+  Exclude:
+    - 'test/**/*'
+    - 'benchmarks/**/*'
+    - 'lib/cataract/pure/**/*.rb'
+    - 'lib/cataract/pure.rb'
+    - 'lib/cataract/at_rule.rb'
+    - 'lib/cataract/declaration.rb'
+    - 'lib/cataract/rule.rb'
+
+# Offense count: 4
+# Configuration parameters: MinBranchesCount.
+Style/HashLikeCase:
+  Exclude:
+    - 'benchmarks/merging_tests.rb'
+    - 'benchmarks/parsing_tests.rb'
+    - 'benchmarks/serialization_tests.rb'
+    - 'benchmarks/specificity_tests.rb'
+
+# Offense count: 14
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/IdenticalConditionalBranches:
+  Exclude:
+    - 'benchmarks/benchmark_merging.rb'
+    - 'benchmarks/benchmark_parsing.rb'
+    - 'benchmarks/benchmark_serialization.rb'
+    - 'benchmarks/benchmark_specificity.rb'
+    - 'lib/cataract/pure/parser.rb'
+    - 'lib/cataract/pure/serializer.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowIfModifier.
+Style/IfInsideElse:
+  Exclude:
+    - 'lib/cataract/pure/flatten.rb'
+    - 'lib/cataract/pure/serializer.rb'
+    - 'lib/cataract/pure/specificity.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/NegatedIfElseCondition:
+  Exclude:
+    - 'lib/cataract/pure/flatten.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantAssignment:
+  Exclude:
+    - 'lib/cataract/pure/specificity.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantParentheses:
+  Exclude:
+    - 'lib/cataract/pure/imports.rb'
+    - 'lib/cataract/pure/parser.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantRegexpArgument:
+  Exclude:
+    - 'test/test_stylesheet.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowModifier.
+Style/SoleNestedConditional:
+  Exclude:
+    - 'lib/cataract/pure/flatten.rb'
+    - 'lib/cataract/pure/parser.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'benchmarks/merging_tests.rb'
+    - 'scripts/generate_benchmarks_md.rb'
+    - 'test/test_stylesheet.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: .
+# SupportedStyles: percent, brackets
+Style/SymbolArray:
+  EnforcedStyle: percent
+  MinSize: 3
+
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Max: 184

data/BENCHMARKS.md

@@ -4,176 +4,97 @@
 
 # Performance Benchmarks
 
-Comprehensive performance comparison between Cataract and css_parser gem.
+Performance comparison between Cataract's C extension and pure Ruby implementations, with css_parser as a reference.
 
 ## Test Environment
 
-- **Ruby**: ruby 3.4.5 (2025-07-16 revision 20cda200d3) +YJIT +PRISM [arm64-darwin23]
+- **Ruby**: ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +YJIT +PRISM [arm64-darwin23]
 - **CPU**: Apple M1 Pro
 - **Memory**: 32GB
 - **OS**: macOS 14.5
-- **Generated**: 2025-10-30T16:01:15-05:00
+- **Generated**: 2025-11-11T16:02:08-06:00
 
-<details>
-<summary><h2>CSS Parsing</h2></summary>
-
-Performance of parsing CSS into internal data structures.
+## CSS Parsing
 
 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)
-
+| Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
+|-----------|--------|----------------|-------------|----------------------|-------------------|
+| Small CSS (64 lines, 1.0KB) | 62.47K i/s | 3.59K i/s | 15.67K i/s | 4.73K i/s | 6.17K i/s |
+| Medium CSS with @media (139 lines, 1.6KB) | 39.7K i/s | 2.05K i/s | 8.64K i/s | 2.76K i/s | 3.52K i/s |
 
-| 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** | |
+### Speedups
 
-
-</details>
+| Comparison | Speedup |
+|------------|---------|
+| Native vs Pure (no YJIT) | 18.4x faster (avg) |
+| Native vs Pure (YJIT) | 4.2x faster (avg) |
+| YJIT impact on Pure Ruby | 4.31x faster (avg) |
 
 ---
 
-<details>
-<summary><h2>CSS Serialization (to_s)</h2></summary>
-
-Performance of converting parsed CSS back to string format.
+## CSS Serialization
 
 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** | |
+| Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
+|-----------|--------|----------------|-------------|----------------------|-------------------|
+| Full Serialization (Bootstrap CSS - 191KB) | 1.77K i/s | 444.3 i/s | 676.3 i/s | 37.1 i/s | 35.9 i/s |
+| Media Type Filtering (print only) | 282.58K i/s | 114.27K i/s | 155.82K i/s | 2.67K i/s | 4.03K i/s |
 
-### Media Type Filtering (print only)
+### Speedups
 
-
-| 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>
+| Comparison | Speedup |
+|------------|---------|
+| Native vs Pure (no YJIT) | 3.23x faster (avg) |
+| Native vs Pure (YJIT) | 1.82x faster (avg) |
+| YJIT impact on Pure Ruby | 1.36x faster (avg) |
 
 ---
 
-<details>
-<summary><h2>Specificity Calculation</h2></summary>
-
-Performance of calculating CSS selector specificity values.
+## Specificity Calculation
 
 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** |
+| Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
+|-----------|--------|----------------|-------------|----------------------|-------------------|
+| Simple Selectors | 7.35M i/s | 506.04K i/s | 2.59M i/s | 357.72K i/s | 353.42K i/s |
+| Compound Selectors | 6.36M i/s | 184.96K i/s | 406.99K i/s | 216.59K i/s | 214.86K i/s |
+| Combinators | 5.04M i/s | 146.91K i/s | 252.94K i/s | 185.44K i/s | 183.71K i/s |
+| Pseudo-classes & Pseudo-elements | 5.1M i/s | 116.46K i/s | 197.06K i/s | 113.05K i/s | 113.99K i/s |
+| :not() Pseudo-class (CSS3) | 3.23M i/s | 102.63K i/s | 161.55K i/s | 144.04K i/s | 144.53K i/s |
+| Complex Real-world Selectors | 4.01M i/s | 52.03K i/s | 77.65K i/s | 83.91K i/s | 82.03K i/s |
 
-**Summary:** 22.03x faster to 49.17x faster (avg 33.3x faster)
+### Speedups
 
-</details>
+| Comparison | Speedup |
+|------------|---------|
+| Native vs Pure (no YJIT) | 39.27x faster (avg) |
+| Native vs Pure (YJIT) | 8.43x faster (avg) |
+| YJIT impact on Pure Ruby | 3.32x faster (avg) |
 
 ---
 
-<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 |
+## CSS Flattening (Cascade)
 
-### Implementation Notes
+Time to flatten multiple CSS rule sets with same selector
 
-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
+| Test Case | Native | Pure (no YJIT) | Pure (YJIT) | css_parser (no YJIT) | css_parser (YJIT) |
+|-----------|--------|----------------|-------------|----------------------|-------------------|
+| No shorthand properties (large) | 21.34K i/s | 3.11K i/s | 5.23K i/s | 1.58K i/s | 2.3K i/s |
+| Simple properties | 158.81K i/s | 75.72K i/s | 102.44K i/s | 28.29K i/s | 40.72K i/s |
+| Cascade with specificity | 204.11K i/s | 77.93K i/s | 108.77K i/s | 31.92K i/s | 46.39K i/s |
+| Important declarations | 203.43K i/s | 77.88K i/s | 109.38K i/s | 31.25K i/s | 45.25K i/s |
+| Shorthand expansion | 21.34K i/s | 3.11K i/s | 5.23K i/s | 1.58K i/s | 2.3K i/s |
+| Complex merging | 30.94K i/s | 16.09K i/s | 21.57K i/s | 11.6K i/s | 16.63K i/s |
 
-### Use Cases
+### Speedups
 
-- **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
+| Comparison | Speedup |
+|------------|---------|
+| Native vs Pure (no YJIT) | 3.03x faster (avg) |
+| Native vs Pure (YJIT) | 1.72x faster (avg) |
+| YJIT impact on Pure Ruby | 1.38x faster (avg) |
 
 ---
 
@@ -181,14 +102,13 @@ Ruby-side operations with and without YJIT
 
 ```bash
 # All benchmarks
-rake benchmark 2>&1 | tee benchmark_output.txt
+rake benchmark
 
 # Individual benchmarks
 rake benchmark:parsing
 rake benchmark:serialization
 rake benchmark:specificity
-rake benchmark:merging
-rake benchmark:yjit
+rake benchmark:flattening
 
 # Generate documentation
 rake benchmark:generate_docs
@@ -196,6 +116,7 @@ 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
+- Benchmarks use benchmark-ips with 1-2s warmup and 2-5s measurement periods
+- Measurements show median iterations per second (i/s)
+- css_parser gem is included for reference comparison
+- YJIT is enabled/disabled per subprocess for accurate comparison

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [0.2.0] - 2025-11-14
+
+- Major: CSS `@import` resolution refactored from string-concatenation to parsed-object architecture with proper charset handling, media query combining,
+and circular import detection
+- Major: Terminology change: all `merge` methods renamed to `flatten` to better represent CSS cascade behavior (old names deprecated with warnings)
+- Major: Rule equality now considers shorthand/longhand property equivalence (e.g., `margin: 10px` equals `margin-top: 10px; margin-right: 10px; ...`)
+- Performance: Flatten operation optimized with array-based property storage, pre-allocated frozen strings, and lazy specificity calculation
+- Feature: New Stylesheet collection methods (`+`, `-`, `|`, `concat`, `take`, `take_while`) with cascade rules applied
+- Feature: Added source order tracking for proper CSS cascade resolution
+
+## [0.1.4] - 2025-11-12
+- Major: Pure Ruby implementation added (#12)
+- Fix: Media query serialization bugs - parentheses now preserved per CSS spec (min-width: 768px), fixed media query ordering
+- Fix: CSS merge declaration ordering made consistent between C and pure Ruby implementations
+- Fix: Shorthand property recreation (margin, padding, border, font, background, list-style) ordering
+- Fix: Rule equality comparisons (Rule#==, AtRule#==)
+
+## [0.1.3] - 2025-11-11
+- Fix: Proper handling of at-rules (@keyframes, @font-face, etc.) during CSS merge operations
+
 ## [0.1.2] - 2025-11-11
 
 - Fix segfault in merge

data/RAGEL_MIGRATION.md

@@ -2,7 +2,7 @@
 
 ## Why We Switched
 
-Started with Ragel as an experiment for the CSS parser, but quickly moved to hand-written pure C in October 2024.
+Started with Ragel as an experiment for the CSS parser, but quickly moved to hand-written pure C in October 2025.
 
 ### Performance
 
@@ -55,6 +55,6 @@ Pure C is more verbose than Ragel's DSL, but the performance gains and simpler b
 
 ## Details
 
-- Swapped in October 2024
+- Swapped in October 2025
 - Files: `css_parser.c`, `specificity.c`, `value_splitter.c`
 - API unchanged, all tests pass