cataract 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90e5adcec05553f73e5829b769d010ecda9ca5bf5eb1b2cc621b74707758c913
-  data.tar.gz: 4a82a843a72f2cc3c944798af3b7e7a8271b5ad696c1ed53247854d5ecdda7bb
+  metadata.gz: 6a6424d26e77e0dd4e0167324dc6190f03a9ca041e51fa9e61a78163f6fe312b
+  data.tar.gz: 7c538f41ebd8e93a53caed4a5f066eea076277c26174bff7d22837730f03d90d
 SHA512:
-  metadata.gz: afb9718d653c7bc0c905eb3d273afec8a364ae37de2952ea3285ecf3ef7f5ff29b40887348ef3646adedfab0baeff873211a883750e7c9b992f3e6a25b14cbb0
-  data.tar.gz: c40ba4cefa95024f34c7d9306d93ad07b8f448e847c51231381fa83833f2b97e314e5fbab9d7fb2a8edd1fe45fea0760c6db514c79225829e397c339fd5951a6
+  metadata.gz: d2297f4139e8025ac39b9467eaa4bd0541683af7e4870813159c557df813f411d389b59f5b28adb9c46f5390aba73405b937e946d9097b943e0ba70f6cb37963
+  data.tar.gz: 0b4d9b6ec564fd674ad8558b7b4f309494c0ca12628947a8501b17ccb3567e1a2667dd0ea89f88ad82f688ac580122ec7e9505b8149433504ef40d923228b75b

data/.github/workflows/test.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.1', '3.2', '3.3', '3.4']
+        ruby: ['3.1', '3.2', '3.3', '3.4', '4.0']
 
     steps:
     - uses: actions/checkout@v4
@@ -37,8 +37,8 @@ jobs:
       env:
         COVERAGE: 1
 
-    - name: Run debug test (Ruby 3.4 only)
-      if: matrix.ruby == '3.4'
+    - name: Run debug test (Ruby 4.0 only)
+      if: matrix.ruby == '4.0'
       run: |
         bundle exec rake clean compile
         bundle exec ruby -Ilib:test test/test_stylesheet.rb
@@ -46,7 +46,7 @@ jobs:
         CONFIGURE_ARGS: --enable-debug
 
     - name: Upload coverage to Codecov
-      if: runner.os == 'Linux' && matrix.ruby == '3.4'
+      if: runner.os == 'Linux' && matrix.ruby == '4.0'
       uses: codecov/codecov-action@v5
       with:
         fail_ci_if_error: false
@@ -54,7 +54,7 @@ jobs:
         verbose: true
 
     - name: Upload coverage report artifact
-      if: runner.os == 'Linux' && matrix.ruby == '3.4'
+      if: runner.os == 'Linux' && matrix.ruby == '4.0'
       uses: actions/upload-artifact@v4
       with:
         name: coverage-report
@@ -69,7 +69,7 @@ jobs:
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.4'
+        ruby-version: '4.0'
         bundler-cache: true
 
     - name: Run rubocop

data/.gitignore

@@ -10,6 +10,8 @@ ext/**/cataract.c
 # Compiled extensions
 lib/**/*.so
 lib/**/*.bundle
+ext/**/*.bundle
+ext/**/*.dSYM/
 
 # Makefile generated by extconf.rb
 ext/**/Makefile
@@ -29,19 +31,31 @@ Thumbs.db
 vendor/
 .bundle/
 
+# Node (this is a Ruby gem; no JS toolchain is tracked, but guard against stray npm installs)
+node_modules/
+
 # Test artifacts
 coverage/
 test/.benchmark_results/
-test/fuzz_last_input.css
-test/fuzz_crash_*.css
-test/fuzz_crash_*.log
+
+# Fuzzer output (crash inputs, logs, recent-input dumps)
+scripts/fuzzer/output/
 
 # Benchmark results
 benchmarks/.results/
 benchmarks/.benchmark_results/
 
+# CSS analyzer example debug output
+examples/css_analyzer/output/
+
 # Documentation (generated by YARD)
 docs/
 !docs/files/
 !docs/files/EXAMPLE.md
 .yardoc/
+
+# Claude Code local project instructions (personal, not shared)
+.claude/CLAUDE.md
+
+.cache/
+.cocci/

data/.rubocop.yml

@@ -178,4 +178,5 @@ Cataract/BanAssertIncludes:
     - 'test/color/**/*.rb'
     - 'test/test_benchmark_doc_generator.rb'
     - 'test/test_speedup_calculator.rb'
+    - 'test/test_parse_errors.rb'  # Parse error tests check error messages with assert_match
     - 'test/support/**/*'  # Support files define assert_contains which uses assert_includes internally

data/BENCHMARKS.md

@@ -20,17 +20,35 @@ Time to parse CSS into internal data structures
 
 | Test Case | Native | Pure (no YJIT) | Pure (YJIT) |
 |-----------|--------|----------------|-------------|
-| Small CSS (64 lines, 1.0KB) | 37.4K i/s | 3.25K i/s | 13.43K i/s |
-| Medium CSS with @media (139 lines, 1.6KB) | 34.71K i/s | 2.04K i/s | 9.15K i/s |
-| Selector lists (3500 lines, 62.5KB, 500 lists) | 471.8 i/s | 56.7 i/s | 214.1 i/s |
+| 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 |
 
 ### Speedups
 
 | Comparison | Speedup |
 |------------|---------|
-| Native vs Pure (no YJIT) | 12.76x faster (avg) |
-| Native vs Pure (YJIT) | 2.99x faster (avg) |
-| YJIT impact on Pure Ruby | 4.22x faster (avg) |
+| 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) |
+
+### Parse Error Checking Overhead
+
+Parse error detection can be enabled with `raise_parse_errors: true`. This compares performance impact:
+
+| 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 |
+
+**Overhead Analysis:**
+
+
+| Implementation | Overhead |
+|----------------|----------|
+| Native | ~0% (within noise) |
+| Pure (no YJIT) | 8.9% slower |
+| Pure (YJIT) | 10.4% slower |
 
 ---
 

data/CHANGELOG.md

@@ -1,4 +1,32 @@
-## [ Unreleased ]
+## [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.
+- Fix: rules nested 3+ levels deep, or nested inside a top-level `@media`/`@supports`/`@container`/`@scope` block, could serialize incorrectly (silently flattened, or printed as an unrelated top-level rule) in the pure Ruby backend.
+- Fix: a bare type selector nested without `&` (invalid CSS nesting) no longer corrupts serialized output with unbalanced braces, in both the C and pure Ruby parsers.
+- Fix: `@keyframes` parsing no longer pollutes the outer rule list with its own inner selectors.
+- Fix: at-rules (`@keyframes`, `@font-face`, etc.) nested inside `@media` blocks now correctly keep their media context across parsing, merging (`add_block`, `concat`/`+`), `@import` resolution, and serialization - previously this could be lost, misattributed, or (combined with CSS nesting) raise `NoMethodError` in the pure Ruby serializer.
+- Fix: `remove_rules!` and the `-` operator no longer desync media query ids from the rules that reference them.
+- Fix: resolving `@import`s no longer leaves duplicate/colliding rule ids.
+- Fix: a plain `@import "file.css";` (no media qualifier) no longer loses that file's own `@media` rules.
+- Fix: `Stylesheet#concat`/`+` now merges the other stylesheet's media queries and selector-list groupings too - previously this silently dropped `h1, h2`-style grouping and corrupted media attribution.
+- Fix: `@import` media queries with a type keyword (e.g. `"screen and (min-width: 500px)"`) no longer keep a stray `"and"` in the parsed conditions.
+- Fix: `to_s`/`to_formatted_s` media filtering is now consistent between the two - both include base (non-media) rules when filtering to a specific media type; previously `to_s` excluded them while `to_formatted_s` included them.
+- Fix: values containing `url(...;...)` no longer lose everything after the first semicolon when the rule also uses CSS nesting.
+- Fix: `!important` now parses correctly with whitespace between `!` and `important`, per the CSS grammar.
+- Fix: expanding `border`, `border-{top,right,bottom,left}`, `font`, `background`, and `list-style` shorthands (used when comparing rules for equality) no longer silently drops `!important`.
+- Fix: `Declarations`/`Stylesheet` `#dup`/`#clone` now produce fully independent copies; previously mutating a copy could mutate the original.
+- Performance: CSS selector specificity calculation is ~30% faster (no longer re-allocates an internal lookup array on every call).
+- Performance: native (C extension) CSS flattening is ~1-5% faster (fewer string allocations when recreating shorthand properties).
+
+## [0.2.5 - 2025-11-25]
+
+- Feature: Parse error detection with `raise_parse_errors` option - validates CSS structure and raises `ParseError` exceptions for malformed input with line/column tracking
+- Feature: Granular error control - enable specific checks (empty values, malformed declarations, invalid selectors, invalid selector syntax, malformed at-rules, unclosed blocks)
+- Feature: Type safety validation for C extension - `Stylesheet.parse` and `Stylesheet.new` now validate argument types and raise clear `TypeError` instead of segfaulting
+- Feature: Selector syntax validation using whitelist approach - catches invalid characters and sequences like `..class`, `##id`, `???`
+- Fix: `add_block` with multiple `@import` statements now correctly tracks media type for each import instead of reusing the first import's media context
+- Performance: Parse error checking adds minimal overhead (effectively zero for C/Pure Ruby, ~5% for Pure Ruby with YJIT)
+- Testing: Fuzzer corpus enhanced with invalid CSS patterns for crash testing
 
 ## [0.2.4 - 2025-11-23]
 - MediaQuery first-class objects: Refactored media queries from simple symbols to proper structs with id, type, and conditions, enabling accurate

data/Gemfile

@@ -16,10 +16,10 @@ gem 'css_parser', '~> 1.0' # for benchmarking against
 gem 'minitest'
 gem 'minitest-spec'
 gem 'nokogiri' # for docs
-gem 'ruby-prof', require: false # for profiling
+gem 'ruby-prof', require: false, platforms: :ruby # for profiling (MRI only)
 gem 'simplecov', require: false
 gem 'simplecov-cobertura', require: false
-gem 'stackprof', require: false # for profiling
+gem 'stackprof', require: false, platforms: :ruby # for profiling (MRI only)
 gem 'webmock', '~> 3.0' # for testing URL loading
 
 gem 'overcommit', '~> 0.64', group: :development

data/examples/css_analyzer/analyzer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'erb'
+require 'fileutils'
 require 'uri'
 require_relative '../../lib/cataract'
 require_relative 'analyzers/properties'
@@ -71,13 +72,18 @@ module CSSAnalyzer
     def save_parsed_css
       # Generate a unique filename based on source
       source_slug = @source.gsub(%r{[:/]}, '_').gsub(/[^a-zA-Z0-9_.-]/, '')
-      filename = "parsed-css-#{source_slug}.css"
+
+      # Write next to this script (not the caller's cwd) so running the
+      # analyzer from repo root doesn't scatter debug output there.
+      output_dir = File.join(__dir__, 'output')
+      FileUtils.mkdir_p(output_dir)
+      path = File.join(output_dir, "parsed-css-#{source_slug}.css")
 
       # Serialize stylesheet to CSS
       css_output = @stylesheet.to_s
 
-      File.write(filename, css_output)
-      warn "Parsed CSS saved to #{filename} (#{@stylesheet.size} rules, #{css_output.length} bytes)"
+      File.write(path, css_output)
+      warn "Parsed CSS saved to #{path} (#{@stylesheet.size} rules, #{css_output.length} bytes)"
     end
 
     private

data/examples/css_analyzer/analyzers/base.rb

@@ -26,7 +26,7 @@ module CSSAnalyzer
       # @param rule [Cataract::Rule] The rule to check
       # @return [Array<Symbol>] Array of media query symbols this rule appears in
       def media_queries_for_rule(rule)
-        stylesheet.instance_variable_get(:@_media_index).select { |_media, ids| ids.include?(rule.id) }.keys
+        stylesheet.media_index.select { |_media, ids| ids.include?(rule.id) }.keys
       end
     end
   end