cataract 0.1.3 → 0.1.4

data/Rakefile

@@ -28,15 +28,51 @@ 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
@@ -44,7 +80,6 @@ task :benchmark do
   Rake::Task['benchmark:serialization'].invoke
   Rake::Task['benchmark:specificity'].invoke
   Rake::Task['benchmark:merging'].invoke
-  Rake::Task['benchmark:yjit'].invoke
   puts "\n#{'-' * 80}"
   puts 'All benchmarks complete!'
   puts 'Generate documentation with: rake benchmark:generate_docs'
@@ -53,35 +88,29 @@ 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
+  task merging: :compile 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'
-  end
-
   desc 'Benchmark string allocation optimization (buffer vs dynamic)'
   task :string_allocation do
     # Clean up any existing benchmark results
@@ -189,10 +218,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)/}) ||
+        f.match(/^(test|benchmark)_.*\.rb$/)
+    end
   end
 
   spec.bindir        = 'exe'

data/ext/cataract/cataract.c

@@ -254,7 +254,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 +277,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 +684,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 +694,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 +723,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 +1024,25 @@ 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'");
+    }
 
     // Define Declarations class and add to_s method
     VALUE cDeclarations = rb_define_class_under(mCataract, "Declarations", rb_cObject);
@@ -1086,4 +1080,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/css_parser.c

@@ -361,10 +361,9 @@ static void update_media_index(ParserContext *ctx, VALUE media_sym, int rule_id)
         return;  // No media query - rule applies to all media
     }
 
-    // Add to full query symbol
-    add_to_media_index(ctx->media_index, media_sym, rule_id);
-
-    // Extract media types and add to each (if different from full query)
+    // Extract media types and add to each first (if different from full query)
+    // We add these BEFORE the full query so that when iterating the media_index hash,
+    // the full query comes last and takes precedence during serialization
     VALUE media_str = rb_sym2str(media_sym);
     const char *query = RSTRING_PTR(media_str);
     long query_len = RSTRING_LEN(media_str);
@@ -380,6 +379,9 @@ static void update_media_index(ParserContext *ctx, VALUE media_sym, int rule_id)
         }
     }
 
+    // Add to full query symbol (after media types for insertion order)
+    add_to_media_index(ctx->media_index, media_sym, rule_id);
+
     // Guard media_str since we extracted C pointer and called extract_media_types (which allocates)
     RB_GC_GUARD(media_str);
 }
@@ -412,8 +414,14 @@ static VALUE parse_declarations(const char *start, const char *end) {
         // Example: "color: red; ..."
         //           ^pos  ^pos (at :)
         const char *prop_start = pos;
-        while (pos < end && *pos != ':') pos++;
-        if (pos >= end) break;  // No colon found
+        while (pos < end && *pos != ':' && *pos != ';') pos++;
+
+        // Malformed declaration - skip to next semicolon to recover
+        if (pos >= end || *pos != ':') {
+            while (pos < end && *pos != ';') pos++;
+            if (pos < end) pos++;  // Skip the semicolon
+            continue;
+        }
 
         const char *prop_end = pos;
         // Trim whitespace from property
@@ -564,7 +572,7 @@ static VALUE combine_media_queries(VALUE parent, VALUE child) {
 
 /*
  * Intern media query string to symbol with safety check
- * Strips outer parentheses from standalone conditions like "(orientation: landscape)"
+ * Keeps media query exactly as written - parentheses are required per CSS spec
  */
 static VALUE intern_media_query_safe(ParserContext *ctx, const char *query_str, long query_len) {
     if (query_len == 0) {
@@ -578,38 +586,14 @@ static VALUE intern_media_query_safe(ParserContext *ctx, const char *query_str,
                 MAX_MEDIA_QUERIES);
     }
 
-    // Strip outer parentheses from standalone conditions
-    // Example: "(orientation: landscape)" => "orientation: landscape"
-    // But keep: "screen and (min-width: 500px)" as-is
+    // Keep media query exactly as written - parentheses are required per CSS spec
     const char *start = query_str;
     const char *end = query_str + query_len;
 
-    // Trim whitespace
+    // Trim whitespace only
     while (start < end && IS_WHITESPACE(*start)) start++;
     while (end > start && IS_WHITESPACE(*(end - 1))) end--;
 
-    if (end > start && *start == '(' && *(end - 1) == ')') {
-        // Check if this is a simple wrapped condition (no other parens/operators)
-        int depth = 0;
-        int has_and_or = 0;
-        for (const char *p = start; p < end; p++) {
-            if (*p == '(') depth++;
-            else if (*p == ')') depth--;
-            // Check for "and" or "or" at depth 0 (outside our outer parens)
-            if (depth == 0 && p + 3 < end &&
-                (strncmp(p, " and ", 5) == 0 || strncmp(p, " or ", 4) == 0)) {
-                has_and_or = 1;
-                break;
-            }
-        }
-
-        // Strip outer parens if depth stays >= 1 (no operators outside) and no and/or
-        if (!has_and_or && depth == 0) {
-            start++;  // Skip opening (
-            end--;    // Skip closing )
-        }
-    }
-
     long final_len = end - start;
     VALUE query_string = rb_usascii_str_new(start, final_len);
     VALUE sym = ID2SYM(rb_intern_str(query_string));

data/ext/cataract/merge.c

@@ -943,6 +943,12 @@ static VALUE merge_rules_for_selector(VALUE rules_array, VALUE rule_indices, VAL
     }
 
     // Build declarations array from properties_hash
+    // NOTE: We don't sort by source_order here because:
+    // 1. Hash iteration order reflects insertion order
+    // 2. Declaration order doesn't affect CSS behavior (cascade is already resolved)
+    // 3. Sorting would add overhead for purely aesthetic output
+    // The output order is roughly source order but may vary when properties are
+    // overridden by later rules with higher specificity or importance.
     VALUE merged_decls = rb_ary_new();
     rb_hash_foreach(properties_hash, merge_build_result_callback, merged_decls);
 

data/lib/cataract/at_rule.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
 module Cataract
-  # Represents a CSS at-rule like @keyframes, @font-face, @supports, etc.
-  #
-  # AtRule is a C struct defined as: `Struct.new(:id, :selector, :content, :specificity)`
-  #
   # At-rules define CSS resources or control structures rather than selecting elements.
   # Unlike regular rules, they don't have CSS specificity and are filtered out when
   # using `select(&:selector?)`.
@@ -32,6 +28,8 @@ module Cataract
   # @attr [String] selector The at-rule identifier (e.g., "@keyframes fade", "@font-face")
   # @attr [Array<Rule>, Array<Declaration>] content Nested rules or declarations
   # @attr [nil] specificity Always nil for at-rules (they don't have CSS specificity)
+  AtRule = Struct.new(:id, :selector, :content, :specificity) unless const_defined?(:AtRule)
+
   class AtRule
     # Check if this is a selector-based rule (vs an at-rule like @keyframes).
     #
@@ -79,17 +77,18 @@ module Cataract
       false
     end
 
-    # Compare at-rules by their attributes rather than object identity.
+    # Compare at-rules for logical equality based on CSS semantics.
     #
-    # Two at-rules are equal if they have the same id, selector, and content.
+    # Two at-rules are equal if they have the same selector and content.
+    # Internal implementation details (id) are not considered since they
+    # don't affect the CSS semantics.
     #
     # @param other [Object] Object to compare with
-    # @return [Boolean] true if at-rules have same attributes
+    # @return [Boolean] true if at-rules have same selector and content
     def ==(other)
       return false unless other.is_a?(AtRule)
 
-      id == other.id &&
-        selector == other.selector &&
+      selector == other.selector &&
         content == other.content
     end
     alias eql? ==

data/lib/cataract/declaration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cataract
+  # Represents a CSS property declaration.
+  #
+  # Declaration is a Struct with fields: (property, value, important)
+  #
+  # @example Create a declaration
+  #   decl = Cataract::Declaration.new('color', 'red', false)
+  #   decl.property #=> "color"
+  #   decl.value #=> "red"
+  #   decl.important #=> false
+  #
+  # @attr [String] property CSS property name (lowercased)
+  # @attr [String] value CSS property value
+  # @attr [Boolean] important Whether the declaration has !important
+  Declaration = Struct.new(:property, :value, :important) unless const_defined?(:Declaration)
+end

data/lib/cataract/import_resolver.rb

@@ -2,7 +2,6 @@
 
 require 'uri'
 require 'open-uri'
-require 'set'
 
 module Cataract
   # Error raised during import resolution
@@ -26,9 +25,9 @@ module Cataract
     # @param css [String] CSS content with @import statements
     # @param options [Hash] Import resolution options
     # @param depth [Integer] Current recursion depth (internal)
-    # @param imported_urls [Set] Set of already imported URLs to prevent circular references
+    # @param imported_urls [Array] Array of already imported URLs to prevent circular references
     # @return [String] CSS with imports inlined
-    def self.resolve(css, options = {}, depth: 0, imported_urls: Set.new)
+    def self.resolve(css, options = {}, depth: 0, imported_urls: [])
       # Normalize options
       opts = normalize_options(options)
 
@@ -66,7 +65,7 @@ module Cataract
 
         # Recursively resolve imports in the imported CSS
         imported_urls_copy = imported_urls.dup
-        imported_urls_copy.add(url)
+        imported_urls_copy << url
         imported_css = resolve(imported_css, opts, depth: depth + 1, imported_urls: imported_urls_copy)
 
         # Wrap in @media if import had media query

data/lib/cataract/pure/byte_constants.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Pure Ruby CSS parser - Byte constants for fast parsing
+# Using getbyte() instead of String#[] to avoid allocating millions of string objects
+
+module Cataract
+  # Whitespace bytes
+  BYTE_SPACE     = 32  # ' '
+  BYTE_TAB       = 9   # '\t'
+  BYTE_NEWLINE   = 10  # '\n'
+  BYTE_CR        = 13  # '\r'
+
+  # CSS structural characters
+  BYTE_AT        = 64  # '@'
+  BYTE_LBRACE    = 123 # '{'
+  BYTE_RBRACE    = 125 # '}'
+  BYTE_LPAREN    = 40  # '('
+  BYTE_RPAREN    = 41  # ')'
+  BYTE_LBRACKET  = 91  # '['
+  BYTE_RBRACKET  = 93  # ']'
+  BYTE_SEMICOLON = 59  # ';'
+  BYTE_COLON     = 58  # ':'
+  BYTE_COMMA     = 44  # ','
+
+  # Comment characters
+  BYTE_SLASH     = 47  # '/'
+  BYTE_STAR      = 42  # '*'
+
+  # Quote characters
+  BYTE_SQUOTE    = 39  # "'"
+  BYTE_DQUOTE    = 34  # '"'
+
+  # Selector characters
+  BYTE_HASH      = 35  # '#'
+  BYTE_DOT       = 46  # '.'
+  BYTE_GT        = 62  # '>'
+  BYTE_PLUS      = 43  # '+'
+  BYTE_TILDE     = 126 # '~'
+  BYTE_ASTERISK  = 42  # '*'
+  BYTE_AMPERSAND = 38  # '&'
+
+  # Other
+  BYTE_HYPHEN     = 45 # '-'
+  BYTE_UNDERSCORE = 95 # '_'
+  BYTE_BACKSLASH  = 92 # '\\'
+  BYTE_BANG       = 33 # '!'
+  BYTE_PERCENT    = 37 # '%'
+  BYTE_SLASH_FWD  = 47 # '/' (also defined as BYTE_SLASH above)
+
+  # Specific lowercase letters (for keyword matching)
+  BYTE_LOWER_U    = 117 # 'u'
+  BYTE_LOWER_R    = 114 # 'r'
+  BYTE_LOWER_L    = 108 # 'l'
+
+  # Letter ranges (a-z, A-Z)
+  BYTE_LOWER_A   = 97  # 'a'
+  BYTE_LOWER_Z   = 122 # 'z'
+  BYTE_UPPER_A   = 65  # 'A'
+  BYTE_UPPER_Z   = 90  # 'Z'
+  BYTE_CASE_DIFF = 32  # Difference between lowercase and uppercase ('a' - 'A')
+
+  # Digit range (0-9)
+  BYTE_DIGIT_0   = 48  # '0'
+  BYTE_DIGIT_9   = 57  # '9'
+
+  # Nesting styles (for CSS nesting support)
+  NESTING_STYLE_IMPLICIT = 0  # Implicit nesting: .parent { .child { ... } } => .parent .child
+  NESTING_STYLE_EXPLICIT = 1  # Explicit nesting: .parent { &:hover { ... } } => .parent:hover
+end

data/lib/cataract/pure/helpers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Pure Ruby CSS parser - Helper methods
+# NO REGEXP ALLOWED - char-by-char parsing only
+
+module Cataract
+  # Check if a byte is whitespace (space, tab, newline, CR)
+  # @param byte [Integer] Byte value from String#getbyte
+  # @return [Boolean] true if whitespace
+  def self.is_whitespace?(byte)
+    byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR
+  end
+
+  # Check if byte is a letter (a-z, A-Z)
+  # @param byte [Integer] Byte value from String#getbyte
+  # @return [Boolean] true if letter
+  def self.letter?(byte)
+    (byte >= BYTE_LOWER_A && byte <= BYTE_LOWER_Z) ||
+    (byte >= BYTE_UPPER_A && byte <= BYTE_UPPER_Z)
+  end
+
+  # Check if byte is a digit (0-9)
+  # @param byte [Integer] Byte value from String#getbyte
+  # @return [Boolean] true if digit
+  def self.digit?(byte)
+    byte >= BYTE_DIGIT_0 && byte <= BYTE_DIGIT_9
+  end
+
+  # Check if byte is alphanumeric, hyphen, or underscore (CSS identifier char)
+  # @param byte [Integer] Byte value from String#getbyte
+  # @return [Boolean] true if valid identifier character
+  def self.ident_char?(byte)
+    letter?(byte) || digit?(byte) || byte == BYTE_HYPHEN || byte == BYTE_UNDERSCORE
+  end
+end