cataract 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a6424d26e77e0dd4e0167324dc6190f03a9ca041e51fa9e61a78163f6fe312b
-  data.tar.gz: 7c538f41ebd8e93a53caed4a5f066eea076277c26174bff7d22837730f03d90d
+  metadata.gz: 4f107809adb744598338be592626fc5ebbfdb81c2813957c7e5ed1652f37a607
+  data.tar.gz: 810a6aadbe0a8c2ce4eff7c307c17c9de354f1a3bc0d9509ae4e83f1d7e1c8b0
 SHA512:
-  metadata.gz: d2297f4139e8025ac39b9467eaa4bd0541683af7e4870813159c557df813f411d389b59f5b28adb9c46f5390aba73405b937e946d9097b943e0ba70f6cb37963
-  data.tar.gz: 0b4d9b6ec564fd674ad8558b7b4f309494c0ca12628947a8501b17ccb3567e1a2667dd0ea89f88ad82f688ac580122ec7e9505b8149433504ef40d923228b75b
+  metadata.gz: b7e85ed2f9ad0b9154e78c795bc0548ca1eaeb55f8f24b2b644852394a506173afb64042f55a3c02c13c21e1b539738695a83c8f774aaf0311bdda8f00da42b9
+  data.tar.gz: f6ea7361ad3d180aaf9e4faa72bf686906a0f81345df59f70856734e50f17b79d4dc20823d0fae520279767cd289fb8e42bbd619230f095d1d26f9ed95aa1094

data/.gitignore

@@ -4,9 +4,6 @@ tmp/
 *.so
 *.o
 
-# Generated C code from Ragel
-ext/**/cataract.c
-
 # Compiled extensions
 lib/**/*.so
 lib/**/*.bundle

data/.rubocop_todo.yml

@@ -22,21 +22,13 @@ 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
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Lint/AmbiguousOperatorPrecedence:
   Exclude:
     - 'lib/cataract/pure/flatten.rb'
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
@@ -69,7 +61,7 @@ Minitest/EmptyLineBeforeAssertionMethods:
   Exclude:
     - 'test/test_stylesheet.rb'
 
-# Offense count: 7
+# Offense count: 14
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Performance/UnfreezeString:
   Exclude:
@@ -77,7 +69,7 @@ Performance/UnfreezeString:
     - 'lib/cataract/pure/flatten.rb'
     - 'lib/cataract/pure/parser.rb'
 
-# Offense count: 4
+# Offense count: 8
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, SingleLineConditionsOnly, IncludeTernaryExpressions.
 # SupportedStyles: assign_to_condition, assign_inside_condition
@@ -86,7 +78,7 @@ Style/ConditionalAssignment:
     - 'lib/cataract/pure/imports.rb'
     - 'lib/cataract/pure/flatten.rb'
 
-# Offense count: 4
+# Offense count: 8
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
@@ -107,7 +99,7 @@ Style/HashLikeCase:
     - 'benchmarks/serialization_tests.rb'
     - 'benchmarks/specificity_tests.rb'
 
-# Offense count: 14
+# Offense count: 28
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/IdenticalConditionalBranches:
   Exclude:
@@ -118,7 +110,7 @@ Style/IdenticalConditionalBranches:
     - 'lib/cataract/pure/parser.rb'
     - 'lib/cataract/pure/serializer.rb'
 
-# Offense count: 5
+# Offense count: 10
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowIfModifier.
 Style/IfInsideElse:
@@ -127,19 +119,19 @@ Style/IfInsideElse:
     - 'lib/cataract/pure/serializer.rb'
     - 'lib/cataract/pure/specificity.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Style/NegatedIfElseCondition:
   Exclude:
     - 'lib/cataract/pure/flatten.rb'
 
-# Offense count: 1
+# Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantAssignment:
   Exclude:
     - 'lib/cataract/pure/specificity.rb'
 
-# Offense count: 2
+# Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
 Style/RedundantParentheses:
   Exclude:
@@ -152,7 +144,7 @@ Style/RedundantRegexpArgument:
   Exclude:
     - 'test/test_stylesheet.rb'
 
-# Offense count: 3
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowModifier.
 Style/SoleNestedConditional:

data/.yardopts

@@ -0,0 +1,9 @@
+--output-dir docs
+--readme README.md
+--title 'Cataract - Fast CSS Parser'
+--exclude lib/cataract/pure\.rb
+--exclude lib/cataract/pure/
+lib/**/*.rb
+ext/**/*.c
+-
+docs/files/EXAMPLE.md

data/BENCHMARKS.md

@@ -8,11 +8,11 @@ Performance comparison between Cataract's C extension and pure Ruby implementati
 
 ## Test Environment
 
-- **Ruby**: ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +YJIT +PRISM [arm64-darwin23]
+- **Ruby**: ruby 4.0.5 (2026-05-20 revision 64336ffd0e) +YJIT +PRISM [arm64-darwin25]
 - **CPU**: Apple M1 Pro
 - **Memory**: 32GB
-- **OS**: macOS 14.5
-- **Generated**: 2025-11-11T16:02:08-06:00
+- **OS**: macOS 26.3.1
+- **Generated**: 2026-07-08T10:35:16-05:00
 
 ## CSS Parsing
 
@@ -20,17 +20,17 @@ Time to parse CSS into internal data structures
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| Small CSS (64 lines, 1.0KB) | 37.27K i/s | 3.32K i/s | 13.48K i/s |
-| Medium CSS with @media (139 lines, 1.6KB) | 34.66K i/s | 2.06K i/s | 8.94K i/s |
-| Selector lists (3500 lines, 62.5KB, 500 lists) | 485.7 i/s | 55.7 i/s | 213.6 i/s |
+| Small CSS (64 lines, 1.0KB) | 36.76K i/s | 3.33K i/s | 13.66K i/s |
+| Medium CSS with @media (139 lines, 1.6KB) | 29.98K i/s | 2.11K i/s | 8.98K i/s |
+| Selector lists (3500 lines, 62.5KB, 500 lists) | 447.4 i/s | 58.0 i/s | 219.8 i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 14.4x faster (avg) |
-| Native vs Pure (YJIT) | 3.38x faster (avg) |
-| YJIT impact on Pure Ruby | 4.23x faster (avg) |
+| Native vs Pure (no YJIT) | 13.03x faster (avg) |
+| Native vs Pure (YJIT) | 3.12x faster (avg) |
+| YJIT impact on Pure Ruby | 4.15x faster (avg) |
 
 ### Parse Error Checking Overhead
 
@@ -38,17 +38,17 @@ Parse error detection can be enabled with `raise_parse_errors: true`. This compa
 
 | Configuration | Native | Pure (no YJIT) | Pure (YJIT) |
 |---------------|--------|----------------|-------------|
-| Medium CSS (139 lines) - no error checking | 35.18K i/s | 2.07K i/s | 9.05K i/s |
-| Medium CSS (139 lines) - with error checking | 34.84K i/s | 1.9K i/s | 8.19K i/s |
+| Medium CSS (139 lines) - no error checking | 33.57K i/s | 2.12K i/s | 9.08K i/s |
+| Medium CSS (139 lines) - with error checking | 33.09K i/s | 1.94K i/s | 8.19K i/s |
 
 **Overhead Analysis:**
 
 
 | Implementation | Overhead |
 |----------------|----------|
-| Native | ~0% (within noise) |
-| Pure (no YJIT) | 8.9% slower |
-| Pure (YJIT) | 10.4% slower |
+| Native | 1.5% slower |
+| Pure (no YJIT) | 9.2% slower |
+| Pure (YJIT) | 10.9% slower |
 
 ---
 
@@ -58,19 +58,19 @@ Time to convert parsed CSS back to string format
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| to_s (Bootstrap - 191KB) | 1.32K i/s | 360.2 i/s | 656.6 i/s |
-| to_s (Compact utilities - 2.9KB) | 1.32K i/s | 360.2 i/s | 656.6 i/s |
-| to_formatted_s (Nested CSS - 1.3KB) | 176.13K i/s | 60.97K i/s | 121.5K i/s |
-| to_s with selector_lists (3.4KB) | 19.03K i/s | 8.01K i/s | 14.2K i/s |
-| Media filtering (Bootstrap print only) | 283.24K i/s | 97.28K i/s | 161.56K i/s |
+| to_s (Bootstrap - 191KB) | 1.05K i/s | 368.6 i/s | 555.6 i/s |
+| to_s (Compact utilities - 2.9KB) | 1.05K i/s | 368.6 i/s | 555.6 i/s |
+| to_formatted_s (Nested CSS - 1.3KB) | 156.05K i/s | 53.98K i/s | 90.18K i/s |
+| to_s with selector_lists (3.4KB) | 15.37K i/s | 7.71K i/s | 12.09K i/s |
+| Media filtering (Bootstrap print only) | 1.18K i/s | 547.1 i/s | 769.2 i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 3.24x faster (avg) |
-| Native vs Pure (YJIT) | 1.73x faster (avg) |
-| YJIT impact on Pure Ruby | 1.86x faster (avg) |
+| Native vs Pure (no YJIT) | 2.71x faster (avg) |
+| Native vs Pure (YJIT) | 1.75x faster (avg) |
+| YJIT impact on Pure Ruby | 1.55x faster (avg) |
 
 ---
 
@@ -80,20 +80,20 @@ Time to calculate CSS selector specificity values
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| Simple Selectors | 7.28M i/s | 506.61K i/s | 2.45M i/s |
-| Compound Selectors | 6.4M i/s | 186.62K i/s | 405.15K i/s |
-| Combinators | 5.04M i/s | 147.07K i/s | 255.92K i/s |
-| Pseudo-classes & Pseudo-elements | 5.17M i/s | 117.16K i/s | 195.12K i/s |
-| :not() Pseudo-class (CSS3) | 3.48M i/s | 103.47K i/s | 161.34K i/s |
-| Complex Real-world Selectors | 4.01M i/s | 52.41K i/s | 77.48K i/s |
+| Simple Selectors | 1.97M i/s | 419.98K i/s | 1.44M i/s |
+| Compound Selectors | 1.89M i/s | 186.59K i/s | 523.08K i/s |
+| Combinators | 1.43M i/s | 142.61K i/s | 285.41K i/s |
+| Pseudo-classes & Pseudo-elements | 1.41M i/s | 114.7K i/s | 235.07K i/s |
+| :not() Pseudo-class (CSS3) | 1.52M i/s | 110.64K i/s | 247.84K i/s |
+| Complex Real-world Selectors | 1.62M i/s | 56.2K i/s | 126.65K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 39.54x faster (avg) |
-| Native vs Pure (YJIT) | 23.05x faster (avg) |
-| YJIT impact on Pure Ruby | 2.24x faster (avg) |
+| Native vs Pure (no YJIT) | 13.28x faster (avg) |
+| Native vs Pure (YJIT) | 5.82x faster (avg) |
+| YJIT impact on Pure Ruby | 2.46x faster (avg) |
 
 ---
 
@@ -103,20 +103,20 @@ Time to flatten multiple CSS rule sets with same selector
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| No shorthand properties (large) | 13.91K i/s | 3.23K i/s | 6.39K i/s |
-| Simple properties | 144.19K i/s | 71.11K i/s | 101.38K i/s |
-| Cascade with specificity | 172.96K i/s | 69.16K i/s | 99.23K i/s |
-| Important declarations | 173.35K i/s | 69.12K i/s | 100.16K i/s |
-| Shorthand expansion | 13.91K i/s | 3.23K i/s | 6.39K i/s |
-| Complex flattening | 29.86K i/s | 15.77K i/s | 22.09K i/s |
+| No shorthand properties (large) | 12.75K i/s | 3.69K i/s | 6.41K i/s |
+| Simple properties | 142.64K i/s | 69.09K i/s | 100.71K i/s |
+| Cascade with specificity | 178.29K i/s | 67.87K i/s | 101.77K i/s |
+| Important declarations | 177.88K i/s | 68.12K i/s | 101.75K i/s |
+| Shorthand expansion | 12.75K i/s | 3.69K i/s | 6.41K i/s |
+| Complex flattening | 31.73K i/s | 16.04K i/s | 23.28K i/s |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 2.54x faster (avg) |
-| Native vs Pure (YJIT) | 1.63x faster (avg) |
-| YJIT impact on Pure Ruby | 1.53x faster (avg) |
+| Native vs Pure (no YJIT) | 2.45x faster (avg) |
+| Native vs Pure (YJIT) | 1.6x faster (avg) |
+| YJIT impact on Pure Ruby | 1.52x faster (avg) |
 
 ---
 

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.5.0] - 2026-07-09
+
+- Feature: `@supports (condition) { ... }` now preserves its condition and the rules it wraps through parse -> serialize, in both backends - previously the condition was discarded entirely and the wrapped rules were silently flattened into the surrounding document with no trace of ever being conditional.
+- Feature: `@container name (condition) { ... }` (container queries) now preserves its name, condition, and wrapped rules the same way - handles named, anonymous, and name-only forms, and nests correctly with `@media`/`@supports`/itself.
+- Feature: `@layer` (cascade layers) now preserves its name and wrapped rules, both in block form (`@layer name { ... }`, including anonymous and dotted/nested names like `framework.layout`) and statement form (`@layer a, b;`, which declares layer order with no wrapped rules at all - previously silently corrupted parsing of whatever rule came right after it).
+- Fix: `@media`/`@supports`/`@container`/`@scope`/`@layer` with no whitespace before a following `(` (e.g. minified `@supports(display:grid){...}`) no longer misparses the at-rule name, which silently corrupted the rest of the block. Present in both backends since `@media`/`@supports` shipped.
+- Feature: `@namespace` (default and prefixed, e.g. `@namespace svg url(http://www.w3.org/2000/svg);`) is now preserved through parse -> serialize, in both backends - previously it wasn't modelled at all. Namespaced selectors (`ns|E`, `*|E`, `|E`, and the attribute-selector equivalents) already parsed as opaque text, but their specificity was miscounted - a namespace prefix was counted as its own type selector instead of contributing nothing, e.g. `svg|rect` computed as specificity 2 instead of 1. Both are fixed now.
+
+## [0.4.0] - 2026-07-08
+
+- Fix: `Declarations.new(some_string)` (standalone CSS declaration-block parsing) now works under the pure Ruby backend (`CATARACT_PURE=1`) - previously raised `NoMethodError`.
+- Fix: a compound `@media` list (e.g. `@media screen, print { ... }`) no longer silently collapses to just its first member when the document also contains CSS nesting elsewhere.
+- Fix: `to_s`/`to_formatted_s` with a specific `media:` filter (anything but `:all`) could crash while grouping comma-separated selector lists (e.g. `h1, h2 { ... }`), if an unrelated rule elsewhere in the document was excluded by the filter. Present in both backends since at least 0.3.0.
+- Fix: `Stylesheet#flatten` (non-destructive) could silently expand shorthand properties (e.g. `margin: 0`) on the *original* stylesheet as a side effect, under the pure Ruby backend. Present since at least 0.3.0; the C extension was unaffected.
+- Breaking (minor): removed `Cataract.merge` (a long-deprecated alias for `.flatten`) and `Cataract.parse_media_types` (undocumented, no real callers) from the C extension's public surface. Use `Cataract.flatten`/`Stylesheet#flatten` instead of `.merge`.
+- Internal: `Cataract`'s own directly-callable methods are now just `.flatten` and `.parse_css`. Previously `Cataract` also exposed `calculate_specificity`, `expand_shorthand`, `parse_declarations`, `stylesheet_to_s`, `stylesheet_to_formatted_s`, and `_parse_css` directly - undocumented implementation leakage, not intended for direct use. The documented ways to reach this functionality (`Rule#specificity`, `Rule#expanded_declarations`, `Declarations.new(some_string)`, `Stylesheet#to_s`/`#to_formatted_s`) are unchanged. The native C extension and pure Ruby backend also now live under `Cataract::Backends::Native` / `Cataract::Backends::Pure`, resolved once per process and held per-`Stylesheet` - this lets both backends coexist in the same process (e.g. for direct comparison). Existing callers relying only on the documented public API should notice nothing.
+
 ## [0.3.0] - 2026-07-06
 
 - Security/Breaking: `Stylesheet#load_uri` and `#load_file` now reject `file://` paths under `/etc/`, `/proc/`, `/sys/`, and `/dev/` by default (override with `dangerous_path_prefixes: []`). Previously these methods used a separate, unvalidated fetch implementation; they now reuse `ImportResolver` (the same validation and fetching `@import` resolution already uses), which also fixes `load_uri` not following HTTP redirects.