cataract 0.1.3 → 0.2.0

data/README.md

@@ -34,6 +34,32 @@ gem install cataract
 
 - Ruby >= 3.1.0
 
+### Pure Ruby Implementation
+
+Cataract includes a pure Ruby implementation alongside the C extension. This is useful for:
+- Platforms where C extensions cannot be compiled
+- Development/debugging without needing to recompile C code
+- Environments with restricted native code execution
+
+**In your Gemfile:**
+```ruby
+gem 'cataract', require: 'cataract/pure'
+```
+
+**Or set environment variable:**
+```ruby
+# For CI, testing, or one-off usage
+ENV['CATARACT_PURE'] = '1'
+require 'cataract'
+```
+
+**Check which implementation is loaded:**
+```ruby
+Cataract::IMPLEMENTATION  # => :native or :ruby
+```
+
+**Note:** The pure Ruby implementation does not include color conversion functionality (`convert_colors!`), which is only available in the C extension.
+
 ## Usage
 
 ### Basic Parsing
@@ -142,9 +168,11 @@ See [BENCHMARKS.md](BENCHMARKS.md) for detailed performance comparisons.
 
 ## CSS Support
 
-Cataract aims to support all CSS specifications including:
+Cataract parses and preserves all standard CSS 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`
+- **At-rules**:
+  - **`@media`**: Special handling with indexing and filtering API (`with_media(:print)`, `with_media(:all)`)
+  - **Others** (`@font-face`, `@keyframes`, `@supports`, `@page`, `@layer`, `@container`, `@property`, `@scope`, `@counter-style`): Parsed and preserved as-is (pass-through)
 - **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
@@ -153,7 +181,10 @@ Cataract aims to support all CSS specifications including:
 
 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:
+**Note:** Color conversion is an optional extension and _not_ loaded by default.
+
+<details>
+<summary>Color conversion examples and supported formats</summary>
 
 ```ruby
 require 'cataract'
@@ -213,6 +244,8 @@ sheet.convert_colors!(to: :hex)  # Converts all formats to hex
 - 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
 
+</details>
+
 ### `@import` Support
 
 `@import` statements can be resolved with security controls:
@@ -273,7 +306,7 @@ Each `Rule` is a struct containing:
 - `specificity`: Calculated CSS specificity (cached)
 
 Implementation details:
-- **C implementation**: Critical paths implemented in C (parsing, merging, serialization)
+- **C implementation**: Critical paths implemented in C (parsing, cascade/flatten, 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

data/Rakefile

@@ -28,23 +28,58 @@ end
 # rake-compiler already adds: tmp/, lib/**/*.{so,bundle}, etc.
 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/**/*')
+namespace :test do
+  desc 'Run tests with C extension (default)'
+  Rake::TestTask.new(:c) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.ruby_opts << '-rtest_helper'
+    t.test_files = FileList['test/**/test_*.rb'].exclude('test/css_parser_compat/**/*', 'test/color/**/*')
+  end
+
+  desc 'Run tests with pure Ruby implementation'
+  task :pure do
+    # Run in subprocess to avoid conflicts with C extension
+    success = system({ 'CATARACT_PURE' => '1' }, 'rake', 'test:c')
+    abort('Pure Ruby tests failed!') unless success
+  end
+
+  desc 'Run tests for both C extension and pure Ruby'
+  task :all do
+    impls = ['pure ruby']
+
+    unless RUBY_ENGINE == 'jruby'
+      puts "\n#{'=' * 80}"
+      puts 'Running tests for C EXTENSION'
+      puts '=' * 80
+      impls << 'C extension'
+
+      Rake::Task['test:c'].invoke
+    end
+
+    puts "\n#{'=' * 80}"
+    puts 'Running tests for PURE RUBY implementation'
+    puts '=' * 80
+
+    Rake::Task['test:pure'].invoke
+
+    puts "\n#{'=' * 80}"
+    puts "✓ All tests passed for #{impls.join(' and ')}"
+    puts '=' * 80
+  end
 end
 
+# Default test task runs both implementations
+desc 'Run tests for both C extension and pure Ruby (default)'
+task test: 'test:all'
+
 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
+  Rake::Task['benchmark:flattening'].invoke
   puts "\n#{'-' * 80}"
   puts 'All benchmarks complete!'
   puts 'Generate documentation with: rake benchmark:generate_docs'
@@ -53,33 +88,27 @@ end
 
 namespace :benchmark do
   desc 'Benchmark CSS parsing performance'
-  task :parsing do
+  task parsing: :compile do
     puts 'Running parsing benchmark...'
     ruby 'benchmarks/benchmark_parsing.rb'
   end
 
   desc 'Benchmark CSS serialization (to_s) performance'
-  task :serialization do
+  task serialization: :compile do
     puts 'Running serialization benchmark...'
     ruby 'benchmarks/benchmark_serialization.rb'
   end
 
   desc 'Benchmark specificity calculation performance'
-  task :specificity do
+  task specificity: :compile 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'
+  desc 'Benchmark CSS flattening performance'
+  task flattening: :compile do
+    puts 'Running flattening benchmark...'
+    ruby 'benchmarks/benchmark_flattening.rb'
   end
 
   desc 'Benchmark string allocation optimization (buffer vs dynamic)'
@@ -166,14 +195,27 @@ task :lint do
 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)
+namespace :fuzz do
+  desc 'Run fuzzer with C extension'
+  task c: :compile do
+    iterations = ENV['ITERATIONS'] || '10000'
+    puts "Running CSS parser fuzzer with C extension (#{iterations} iterations)..."
+    system(ENV.to_h, RbConfig.ruby, '-Ilib', 'scripts/fuzzer/run.rb', iterations)
+  end
+
+  desc 'Run fuzzer with pure Ruby implementation'
+  task :pure do
+    iterations = ENV['ITERATIONS'] || '10000'
+    debug_msg = ENV['FUZZ_DEBUG'] == '1' ? ' (debug mode)' : ''
+    puts "Running CSS parser fuzzer with pure Ruby (#{iterations} iterations#{debug_msg})..."
+    env = ENV.to_h.merge('CATARACT_PURE' => '1')
+    system(env, RbConfig.ruby, '-Ilib', 'scripts/fuzzer/run.rb', iterations)
+  end
 end
 
+desc 'Run fuzzer with both C extension and pure Ruby'
+task fuzz: ['fuzz:c', 'fuzz:pure']
+
 # Documentation generation with YARD
 begin
   require 'yard'
@@ -189,10 +231,8 @@ begin
 
   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')
+    # Generate YARD documentation (uses .yardopts for configuration)
+    YARD::CLI::Yardoc.run
 
     # Open in browser (skip in CI)
     unless ENV['CI']

data/cataract.gemspec

@@ -21,7 +21,10 @@ Gem::Specification.new do |spec|
 
   # Specify which files should be added to the gem when it is released.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) || f.match(/^test_.*\.rb$/) }
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|benchmarks|scripts|\.rubocop)/}) ||
+        f.match(/^(test|benchmark)_.*\.rb$/)
+    end
   end
 
   spec.bindir        = 'exe'

data/ext/cataract/cataract.c

@@ -7,6 +7,7 @@ VALUE cRule;
 VALUE cDeclaration;
 VALUE cAtRule;
 VALUE cStylesheet;
+VALUE cImportStatement;
 
 // Error class definitions (shared with main extension)
 VALUE eCataractError;
@@ -254,7 +255,7 @@ static void serialize_at_rule_formatted(VALUE result, VALUE at_rule, const char
 }
 
 // Helper to serialize a single rule with formatting (indented, multi-line)
-static void serialize_rule_formatted(VALUE result, VALUE rule, const char *indent) {
+static void serialize_rule_formatted(VALUE result, VALUE rule, const char *indent, int is_last) {
     // Check if this is an AtRule
     if (rb_obj_is_kind_of(rule, cAtRule)) {
         serialize_at_rule_formatted(result, rule, indent);
@@ -277,9 +278,13 @@ static void serialize_rule_formatted(VALUE result, VALUE rule, const char *inden
     serialize_declarations_formatted(result, declarations, decl_indent_ptr);
     RB_GC_GUARD(decl_indent);
 
-    // Closing brace
+    // Closing brace - double newline for all except last rule
     rb_str_cat2(result, indent);
-    rb_str_cat2(result, "}\n");
+    if (is_last) {
+        rb_str_cat2(result, "}\n");
+    } else {
+        rb_str_cat2(result, "}\n\n");
+    }
 }
 
 // Context for building rule_to_media map
@@ -680,6 +685,7 @@ static VALUE stylesheet_to_formatted_s_original(VALUE rules_array, VALUE media_i
         VALUE rule = rb_ary_entry(rules_array, i);
         VALUE rule_id = rb_struct_aref(rule, INT2FIX(RULE_ID));
         VALUE rule_media = rb_hash_aref(rule_to_media, rule_id);
+        int is_first_rule = (i == 0);
 
         if (NIL_P(rule_media)) {
             // Not in any media query - close any open media block first
@@ -689,19 +695,24 @@ static VALUE stylesheet_to_formatted_s_original(VALUE rules_array, VALUE media_i
                 current_media = Qnil;
             }
 
-            // Output rule with no indentation
-            serialize_rule_formatted(result, rule, "");
+            // Add blank line prefix for non-first rules
+            if (!is_first_rule) {
+                rb_str_cat2(result, "\n");
+            }
+
+            // Output rule with no indentation (always single newline suffix)
+            serialize_rule_formatted(result, rule, "", 1);
         } else {
             // This rule is in a media query
             if (NIL_P(current_media) || !rb_equal(current_media, rule_media)) {
                 // Close previous media block if open
                 if (in_media_block) {
                     rb_str_cat2(result, "}\n");
-                } else {
-                    // Add blank line before @media if transitioning from non-media rules
-                    if (RSTRING_LEN(result) > 0) {
-                        rb_str_cat2(result, "\n");
-                    }
+                }
+
+                // Add blank line prefix for non-first rules
+                if (!is_first_rule) {
+                    rb_str_cat2(result, "\n");
                 }
 
                 // Open new media block
@@ -713,7 +724,8 @@ static VALUE stylesheet_to_formatted_s_original(VALUE rules_array, VALUE media_i
             }
 
             // Serialize rule inside media block with 2-space indentation
-            serialize_rule_formatted(result, rule, "  ");
+            // Rules inside media blocks always get single newline (is_last=1)
+            serialize_rule_formatted(result, rule, "  ", 1);
         }
     }
 
@@ -1013,42 +1025,31 @@ void Init_native_extension(void) {
         eSizeError = rb_define_class_under(mCataract, "SizeError", eCataractError);
     }
 
-    // Define Rule struct: (id, selector, declarations, specificity, parent_rule_id, nesting_style)
-    cRule = rb_struct_define_under(
-        mCataract,
-        "Rule",
-        "id",                 // Integer (0-indexed position in @rules array)
-        "selector",           // String (fully resolved/flattened selector)
-        "declarations",       // Array of Declaration
-        "specificity",        // Integer (nil = not calculated yet)
-        "parent_rule_id",     // Integer | nil (parent rule ID for nested rules)
-        "nesting_style",      // Integer | nil (0=implicit, 1=explicit, nil=not nested)
-        NULL
-    );
-
-    // Define Declaration struct: (property, value, important)
-    cDeclaration = rb_struct_define_under(
-        mCataract,
-        "Declaration",
-        "property",    // String
-        "value",       // String
-        "important",   // Boolean
-        NULL
-    );
-
-    // Define AtRule struct: (id, selector, content, specificity)
-    // Matches Rule interface for duck-typing
-    // - For @keyframes: content is Array of Rule (keyframe blocks)
-    // - For @font-face: content is Array of Declaration
-    cAtRule = rb_struct_define_under(
-        mCataract,
-        "AtRule",
-        "id",                 // Integer (0-indexed position in @rules array)
-        "selector",           // String (e.g., "@keyframes fade", "@font-face")
-        "content",            // Array of Rule or Declaration
-        "specificity",        // Always nil for at-rules
-        NULL
-    );
+    // Reuse Ruby-defined structs (they must be defined before loading this extension)
+    // If they don't exist, someone required the extension directly instead of via lib/cataract.rb
+    if (rb_const_defined(mCataract, rb_intern("Rule"))) {
+        cRule = rb_const_get(mCataract, rb_intern("Rule"));
+    } else {
+        rb_raise(rb_eLoadError, "Cataract::Rule not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
+    }
+
+    if (rb_const_defined(mCataract, rb_intern("Declaration"))) {
+        cDeclaration = rb_const_get(mCataract, rb_intern("Declaration"));
+    } else {
+        rb_raise(rb_eLoadError, "Cataract::Declaration not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
+    }
+
+    if (rb_const_defined(mCataract, rb_intern("AtRule"))) {
+        cAtRule = rb_const_get(mCataract, rb_intern("AtRule"));
+    } else {
+        rb_raise(rb_eLoadError, "Cataract::AtRule not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
+    }
+
+    if (rb_const_defined(mCataract, rb_intern("ImportStatement"))) {
+        cImportStatement = rb_const_get(mCataract, rb_intern("ImportStatement"));
+    } else {
+        rb_raise(rb_eLoadError, "Cataract::ImportStatement not defined. Do not require 'cataract/native_extension' directly, use require 'cataract'");
+    }
 
     // Define Declarations class and add to_s method
     VALUE cDeclarations = rb_define_class_under(mCataract, "Declarations", rb_cObject);
@@ -1063,12 +1064,14 @@ void Init_native_extension(void) {
     rb_define_module_function(mCataract, "_stylesheet_to_formatted_s", stylesheet_to_formatted_s_new, 4);
     rb_define_module_function(mCataract, "parse_media_types", parse_media_types, 1);
     rb_define_module_function(mCataract, "parse_declarations", new_parse_declarations, 1);
-    rb_define_module_function(mCataract, "merge", cataract_merge_new, 1);
+    rb_define_module_function(mCataract, "flatten", cataract_flatten, 1);
+    rb_define_module_function(mCataract, "merge", cataract_flatten, 1); // Deprecated alias for backwards compatibility
     rb_define_module_function(mCataract, "extract_imports", extract_imports, 1);
     rb_define_module_function(mCataract, "calculate_specificity", calculate_specificity, 1);
+    rb_define_module_function(mCataract, "_expand_shorthand", cataract_expand_shorthand, 1);
 
-    // Initialize merge constants (cached property strings)
-    init_merge_constants();
+    // Initialize flatten constants (cached property strings)
+    init_flatten_constants();
 
     // Export compile-time flags as a hash for runtime introspection
     VALUE compile_flags = rb_hash_new();
@@ -1086,4 +1089,10 @@ void Init_native_extension(void) {
     #endif
 
     rb_define_const(mCataract, "COMPILE_FLAGS", compile_flags);
+
+    // Flag to indicate native extension is loaded (for pure Ruby fallback detection)
+    rb_define_const(mCataract, "NATIVE_EXTENSION_LOADED", Qtrue);
+
+    // Implementation type constant
+    rb_define_const(mCataract, "IMPLEMENTATION", ID2SYM(rb_intern("native")));
 }

data/ext/cataract/cataract.h

@@ -12,6 +12,7 @@ extern VALUE cRule;
 extern VALUE cDeclaration;
 extern VALUE cAtRule;
 extern VALUE cStylesheet;
+extern VALUE cImportStatement;
 
 // Error class references
 extern VALUE eCataractError;
@@ -140,9 +141,9 @@ VALUE parse_css_new(VALUE self, VALUE css_string);
 VALUE parse_css_new_impl(VALUE css_string, int rule_id_offset);
 VALUE parse_media_types(VALUE self, VALUE media_query_sym);
 
-// Merge (merge_new.c)
-VALUE cataract_merge_new(VALUE self, VALUE rules_array);
-void init_merge_constants(void);
+// Flatten (flatten.c)
+VALUE cataract_flatten(VALUE self, VALUE rules_array);
+void init_flatten_constants(void);
 
 // Specificity (specificity.c)
 VALUE calculate_specificity(VALUE self, VALUE selector);
@@ -162,6 +163,7 @@ VALUE cataract_expand_border_side(VALUE self, VALUE side, VALUE value);
 VALUE cataract_expand_font(VALUE self, VALUE value);
 VALUE cataract_expand_list_style(VALUE self, VALUE value);
 VALUE cataract_expand_background(VALUE self, VALUE value);
+VALUE cataract_expand_shorthand(VALUE self, VALUE decl);
 VALUE cataract_create_margin_shorthand(VALUE self, VALUE properties);
 VALUE cataract_create_padding_shorthand(VALUE self, VALUE properties);
 VALUE cataract_create_border_width_shorthand(VALUE self, VALUE properties);