cataract 0.1.2 → 0.1.4

data/lib/cataract/pure/specificity.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+# Pure Ruby CSS parser - Specificity calculation
+# NO REGEXP ALLOWED - char-by-char parsing only
+
+module Cataract
+  # Calculate CSS specificity for a selector
+  #
+  # @param selector [String] CSS selector
+  # @return [Integer] Specificity value
+  #
+  # Specificity calculation (per CSS spec):
+  # - Count IDs (#id) - each worth 100
+  # - Count classes/attributes/pseudo-classes (.class, [attr], :pseudo) - each worth 10
+  # - Count elements/pseudo-elements (div, ::before) - each worth 1
+  def self.calculate_specificity(selector)
+    return 0 if selector.nil? || selector.empty?
+
+    # Counters for specificity components
+    id_count = 0
+    class_count = 0
+    attr_count = 0
+    pseudo_class_count = 0
+    pseudo_element_count = 0
+    element_count = 0
+
+    i = 0
+    len = selector.length
+
+    pseudo_element_kwords = %w[before after first-line first-letter selection]
+
+    while i < len
+      byte = selector.getbyte(i)
+
+      # Skip whitespace and combinators
+      if byte == BYTE_SPACE || byte == BYTE_TAB || byte == BYTE_NEWLINE || byte == BYTE_CR ||
+         byte == BYTE_GT || byte == BYTE_PLUS || byte == BYTE_TILDE || byte == BYTE_COMMA
+        i += 1
+        next
+      end
+
+      # ID selector: #id
+      if byte == BYTE_HASH
+        id_count += 1
+        i += 1
+        # Skip the identifier
+        while i < len && ident_char?(selector.getbyte(i))
+          i += 1
+        end
+        next
+      end
+
+      # Class selector: .class
+      if byte == BYTE_DOT
+        class_count += 1
+        i += 1
+        # Skip the identifier
+        while i < len && ident_char?(selector.getbyte(i))
+          i += 1
+        end
+        next
+      end
+
+      # Attribute selector: [attr]
+      if byte == BYTE_LBRACKET
+        attr_count += 1
+        i += 1
+        # Skip to closing bracket
+        bracket_depth = 1
+        while i < len && bracket_depth > 0
+          b = selector.getbyte(i)
+          if b == BYTE_LBRACKET
+            bracket_depth += 1
+          elsif b == BYTE_RBRACKET
+            bracket_depth -= 1
+          end
+          i += 1
+        end
+        next
+      end
+
+      # Pseudo-element (::) or pseudo-class (:)
+      if byte == BYTE_COLON
+        i += 1
+        is_pseudo_element = false
+
+        # Check for double colon (::)
+        if i < len && selector.getbyte(i) == BYTE_COLON
+          is_pseudo_element = true
+          i += 1
+        end
+
+        # Extract pseudo name
+        pseudo_start = i
+        while i < len && ident_char?(selector.getbyte(i))
+          i += 1
+        end
+        pseudo_name = selector[pseudo_start...i]
+
+        # Check for legacy pseudo-elements (single colon but should be double)
+        is_legacy_pseudo_element = false
+        if !is_pseudo_element && !pseudo_name.empty?
+          is_legacy_pseudo_element = pseudo_element_kwords.include?(pseudo_name)
+        end
+
+        # Check for :not() - it doesn't count itself, but its content does
+        is_not = (pseudo_name == 'not')
+
+        # Skip function arguments if present
+        if i < len && selector.getbyte(i) == BYTE_LPAREN
+          i += 1
+          paren_depth = 1
+
+          # If it's :not(), calculate specificity of the content
+          if is_not
+            not_content_start = i
+
+            # Find closing paren
+            while i < len && paren_depth > 0
+              b = selector.getbyte(i)
+              if b == BYTE_LPAREN
+                paren_depth += 1
+              elsif b == BYTE_RPAREN
+                paren_depth -= 1
+              end
+              i += 1 if paren_depth > 0
+            end
+
+            not_content = selector[not_content_start...i]
+
+            # Recursively calculate specificity of :not() content
+            unless not_content.empty?
+              not_specificity = calculate_specificity(not_content)
+
+              # Add :not() content's specificity to our counts
+              additional_a = not_specificity / 100
+              additional_b = (not_specificity % 100) / 10
+              additional_c = not_specificity % 10
+
+              id_count += additional_a
+              class_count += additional_b
+              element_count += additional_c
+            end
+
+            i += 1 # Skip closing paren
+          else
+            # Skip other function arguments
+            while i < len && paren_depth > 0
+              b = selector.getbyte(i)
+              if b == BYTE_LPAREN
+                paren_depth += 1
+              elsif b == BYTE_RPAREN
+                paren_depth -= 1
+              end
+              i += 1
+            end
+
+            # Count the pseudo-class/element
+            if is_pseudo_element || is_legacy_pseudo_element
+              pseudo_element_count += 1
+            else
+              pseudo_class_count += 1
+            end
+          end
+        else
+          # No function arguments - count the pseudo-class/element
+          if is_not
+            # :not without parens is invalid, but don't count it
+          elsif is_pseudo_element || is_legacy_pseudo_element
+            pseudo_element_count += 1
+          else
+            pseudo_class_count += 1
+          end
+        end
+        next
+      end
+
+      # Universal selector: *
+      if byte == BYTE_ASTERISK
+        # Universal selector has specificity 0, don't count
+        i += 1
+        next
+      end
+
+      # Type selector (element name): div, span, etc.
+      if letter?(byte)
+        element_count += 1
+        # Skip the identifier
+        while i < len && ident_char?(selector.getbyte(i))
+          i += 1
+        end
+        next
+      end
+
+      # Unknown character, skip it
+      i += 1
+    end
+
+    # Calculate specificity using W3C formula
+    specificity = (id_count * 100) +
+                  ((class_count + attr_count + pseudo_class_count) * 10) +
+                  ((element_count + pseudo_element_count) * 1)
+
+    specificity
+  end
+end

data/lib/cataract/pure.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+# Pure Ruby implementation of Cataract CSS parser
+#
+# This is a character-by-character parser that closely mirrors the C implementation.
+# ==================================================================
+# NO REGEXP ALLOWED - consume chars one at a time like the C version.
+# ==================================================================
+#
+# Load this instead of the C extension with:
+#   require 'cataract/pure'
+#
+# Or run tests with:
+#   CATARACT_PURE=1 rake test
+
+# Check if C extension is already loaded
+if defined?(Cataract::NATIVE_EXTENSION_LOADED)
+  raise LoadError, 'Cataract C extension is already loaded. Cannot load pure Ruby version.'
+end
+
+# Define base module and error classes first
+module Cataract
+  class Error < StandardError; end
+  class DepthError < Error; end
+  class SizeError < Error; end
+end
+
+require_relative 'version'
+
+# Load struct definitions and supporting files
+# (These are also loaded by lib/cataract.rb, but we need them here for direct require)
+require_relative 'declaration'
+require_relative 'rule'
+require_relative 'at_rule'
+require_relative 'stylesheet_scope'
+require_relative 'stylesheet'
+require_relative 'declarations'
+require_relative 'import_resolver'
+
+# Add to_s method to Declarations class for pure Ruby mode
+module Cataract
+  class Declarations
+    # Serialize declarations to CSS string
+    def to_s
+      result = String.new
+      @values.each_with_index do |decl, i|
+        result << decl.property
+        result << ': '
+        result << decl.value
+        result << ' !important' if decl.important
+        result << ';'
+        result << ' ' if i < @values.length - 1 # Add space after semicolon except for last
+      end
+      result
+    end
+  end
+end
+
+# Load pure Ruby implementation modules
+require_relative 'pure/byte_constants'
+require_relative 'pure/helpers'
+require_relative 'pure/specificity'
+require_relative 'pure/imports'
+require_relative 'pure/serializer'
+require_relative 'pure/parser'
+require_relative 'pure/merge'
+
+module Cataract
+  # Flag to indicate pure Ruby version is loaded
+  PURE_RUBY_LOADED = true
+
+  # Implementation type constant
+  IMPLEMENTATION = :ruby
+
+  # Compile flags (mimic C version)
+  COMPILE_FLAGS = {
+    debug: false,
+    str_buf_optimization: false,
+    pure_ruby: true
+  }.freeze
+
+  # Parse CSS string and return hash with rules, media_index, charset, etc.
+  #
+  # @api private
+  # @param css_string [String] CSS to parse
+  # @return [Hash] {
+  #   rules: Array<Rule>,           # Flat array of Rule/AtRule structs
+  #   _media_index: Hash,           # Symbol => Array of rule IDs
+  #   charset: String|nil,          # @charset value if present
+  #   _has_nesting: Boolean         # Whether any nested rules exist
+  # }
+  def self._parse_css(css_string)
+    parser = Parser.new(css_string)
+    parser.parse
+  end
+
+  # NOTE: Copied from cataract.rb
+  # Need to untangle this eventually
+  def self.parse_css(css, imports: false)
+    css = ImportResolver.resolve(css, imports) if imports
+
+    Stylesheet.parse(css)
+  end
+
+  # Merge stylesheet rules according to CSS cascade rules
+  #
+  # @param stylesheet [Stylesheet] Stylesheet to merge
+  # @return [Stylesheet] New stylesheet with merged rules
+  def self.merge(stylesheet)
+    Merge.merge(stylesheet, mutate: false)
+  end
+
+  # Merge stylesheet rules in-place (mutates receiver)
+  #
+  # @param stylesheet [Stylesheet] Stylesheet to merge
+  # @return [Stylesheet] Same stylesheet (mutated)
+  def self.merge!(stylesheet)
+    Merge.merge(stylesheet, mutate: true)
+  end
+
+  # Add stub method to Stylesheet for pure Ruby implementation
+  class Stylesheet
+    # Color conversion is only available in the native C extension
+    #
+    # @raise [NotImplementedError] Always raises - color conversion requires C extension
+    def convert_colors!(*_args)
+      raise NotImplementedError, 'convert_colors! is only available in the native C extension'
+    end
+  end
+end

data/lib/cataract/rule.rb

@@ -1,16 +1,13 @@
 # frozen_string_literal: true
 
 module Cataract
-  # Represents a CSS rule with a selector and declarations.
-  #
-  # Rule is a C struct defined as: `Struct.new(:id, :selector, :declarations, :specificity)`
-  #
-  # Rules are created by the parser and stored in Stylesheet objects. Each rule
-  # contains:
+  # Rules are created by the parser and stored in Stylesheet objects. Each rule contains:
   # - An ID (position in the stylesheet)
   # - A CSS selector string
   # - An array of Declaration structs
   # - A specificity value (calculated lazily)
+  # - Parent rule ID for nested rules (nil if top-level)
+  # - Nesting style (0=implicit, 1=explicit, nil=not nested)
   #
   # Media query information is stored separately in Stylesheet's media_index.
   #
@@ -25,6 +22,17 @@ module Cataract
   # @attr [String] selector The CSS selector (e.g., "body", ".class", "#id")
   # @attr [Array<Declaration>] declarations Array of CSS property declarations
   # @attr [Integer, nil] specificity CSS specificity value (calculated lazily)
+  # @attr [Integer, nil] parent_rule_id Parent rule ID for nested rules
+  # @attr [Integer, nil] nesting_style 0=implicit, 1=explicit, nil=not nested
+  Rule = Struct.new(
+    :id,
+    :selector,
+    :declarations,
+    :specificity,
+    :parent_rule_id,
+    :nesting_style
+  )
+
   class Rule
     # Silence warning about method redefinition. We redefine below to lazily calculate
     # specificity
@@ -112,19 +120,20 @@ module Cataract
       end
     end
 
-    # Compare rules by their attributes rather than object identity.
+    # Compare rules for logical equality based on CSS semantics.
     #
-    # Two rules are equal if they have the same id, selector, declarations, and specificity.
+    # Two rules are equal if they have the same selector and declarations.
+    # Internal implementation details (id, specificity) are not considered
+    # since they don't affect the CSS semantics. Specificity is derived from
+    # the selector, so if selectors match, specificity must match too.
     #
     # @param other [Object] Object to compare with
-    # @return [Boolean] true if rules have same attributes
+    # @return [Boolean] true if rules have same selector and declarations
     def ==(other)
       return false unless other.is_a?(Rule)
 
-      id == other.id &&
-        selector == other.selector &&
-        declarations == other.declarations &&
-        specificity == other.specificity
+      selector == other.selector &&
+        declarations == other.declarations
     end
     alias eql? ==
   end

data/lib/cataract/stylesheet.rb

@@ -48,6 +48,9 @@ module Cataract
       @rules = [] # Flat array of Rule structs
       @_media_index = {} # Hash: Symbol => Array of rule IDs
       @charset = nil
+      @_has_nesting = nil # Set by parser (nil or boolean)
+      @_last_rule_id = nil # Tracks next rule ID for add_block
+      @selectors = nil # Memoized cache of selectors
     end
 
     # Parse CSS and return a new Stylesheet
@@ -297,12 +300,13 @@ module Cataract
         Cataract._stylesheet_to_s(@rules, @_media_index, @charset, @_has_nesting || false)
       else
         # Collect all rule IDs that match the requested media types
-        matching_rule_ids = Set.new
+        matching_rule_ids = []
         which_media_array.each do |media_sym|
           if @_media_index[media_sym]
-            matching_rule_ids.merge(@_media_index[media_sym])
+            matching_rule_ids.concat(@_media_index[media_sym])
           end
         end
+        matching_rule_ids.uniq! # Dedupe: same rule can be in multiple media indexes
 
         # Build filtered rules array (keep original IDs, no recreation needed)
         filtered_rules = matching_rule_ids.sort.map! { |rule_id| @rules[rule_id] }
@@ -311,7 +315,7 @@ module Cataract
         filtered_media_index = {}
         which_media_array.each do |media_sym|
           if @_media_index[media_sym]
-            filtered_media_index[media_sym] = @_media_index[media_sym] & matching_rule_ids.to_a
+            filtered_media_index[media_sym] = @_media_index[media_sym] & matching_rule_ids
           end
         end
 
@@ -353,20 +357,21 @@ module Cataract
         Cataract._stylesheet_to_formatted_s(@rules, @_media_index, @charset, @_has_nesting || false)
       else
         # Collect all rule IDs that match the requested media types
-        matching_rule_ids = Set.new
+        matching_rule_ids = []
 
         # Include rules not in any media query (they apply to all media)
         media_rule_ids = @_media_index.values.flatten.uniq
         all_rule_ids = (0...@rules.length).to_a
         non_media_rule_ids = all_rule_ids - media_rule_ids
-        matching_rule_ids.merge(non_media_rule_ids)
+        matching_rule_ids.concat(non_media_rule_ids)
 
         # Include rules from requested media types
         which_media_array.each do |media_sym|
           if @_media_index[media_sym]
-            matching_rule_ids.merge(@_media_index[media_sym])
+            matching_rule_ids.concat(@_media_index[media_sym])
           end
         end
+        matching_rule_ids.uniq! # Dedupe: same rule can be in multiple media indexes
 
         # Build filtered rules array (keep original IDs, no recreation needed)
         filtered_rules = matching_rule_ids.sort.map! { |rule_id| @rules[rule_id] }
@@ -375,7 +380,7 @@ module Cataract
         filtered_media_index = {}
         which_media_array.each do |media_sym|
           if @_media_index[media_sym]
-            filtered_media_index[media_sym] = @_media_index[media_sym] & matching_rule_ids.to_a
+            filtered_media_index[media_sym] = @_media_index[media_sym] & matching_rule_ids
           end
         end
 
@@ -499,7 +504,7 @@ module Cataract
       filter_media = media_types ? Array(media_types).map(&:to_sym) : nil
 
       # Find rules to remove
-      rules_to_remove = Set.new
+      rules_to_remove = []
       @rules.each_with_index do |rule, rule_id|
         # Check selector match
         next if selector && rule.selector != selector
@@ -522,7 +527,7 @@ module Cataract
         rules_to_remove << rule_id
       end
 
-      # Remove rules and update media_index
+      # Remove rules and update media_index (sort in reverse to maintain indices during deletion)
       rules_to_remove.sort.reverse_each do |rule_id|
         @rules.delete_at(rule_id)
 

data/lib/cataract/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cataract
-  VERSION = '0.1.2'
+  VERSION = '0.1.4'
 end

data/lib/cataract.rb

@@ -1,9 +1,20 @@
 # frozen_string_literal: true
 
 require_relative 'cataract/version'
-require_relative 'cataract/native_extension'
+
+# Load struct definitions first (before C extension or pure Ruby)
+require_relative 'cataract/declaration'
 require_relative 'cataract/rule'
 require_relative 'cataract/at_rule'
+
+# Load pure Ruby or C extension based on ENV var
+if %w[1 true].include?(ENV.fetch('CATARACT_PURE', nil)) || RUBY_ENGINE == 'jruby'
+  require_relative 'cataract/pure'
+else
+  require_relative 'cataract/native_extension'
+end
+
+# Load supporting Ruby files (used by both implementations)
 require_relative 'cataract/stylesheet_scope'
 require_relative 'cataract/stylesheet'
 require_relative 'cataract/declarations'
@@ -60,11 +71,13 @@ module Cataract
     #
     # @see Stylesheet#parse
     # @see Stylesheet.parse
-    def parse_css(css, imports: false)
-      # Resolve @import statements if requested
-      css = ImportResolver.resolve(css, imports) if imports
+    unless method_defined?(:parse_css)
+      def parse_css(css, imports: false)
+        # Resolve @import statements if requested
+        css = ImportResolver.resolve(css, imports) if imports
 
-      Stylesheet.parse(css)
+        Stylesheet.parse(css)
+      end
     end
 
     # Merge CSS rules according to CSS cascade rules.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cataract
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - James Cook
@@ -21,12 +21,14 @@ extra_rdoc_files: []
 files:
 - ".clang-tidy"
 - ".github/workflows/ci-macos.yml"
+- ".github/workflows/ci-manual-rubies.yml"
 - ".github/workflows/ci.yml"
 - ".github/workflows/docs.yml"
 - ".github/workflows/test.yml"
 - ".gitignore"
 - ".overcommit.yml"
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - BENCHMARKS.md
 - CHANGELOG.md
 - Gemfile
@@ -34,27 +36,6 @@ files:
 - RAGEL_MIGRATION.md
 - README.md
 - Rakefile
-- benchmarks/benchmark_harness.rb
-- benchmarks/benchmark_merging.rb
-- benchmarks/benchmark_optimization_comparison.rb
-- benchmarks/benchmark_parsing.rb
-- benchmarks/benchmark_ragel_removal.rb
-- benchmarks/benchmark_runner.rb
-- benchmarks/benchmark_serialization.rb
-- benchmarks/benchmark_shorthand.rb
-- benchmarks/benchmark_shorthand_expansion.rb
-- benchmarks/benchmark_specificity.rb
-- benchmarks/benchmark_string_allocation.rb
-- benchmarks/benchmark_stylesheet_to_s.rb
-- benchmarks/benchmark_to_s_cached.rb
-- benchmarks/benchmark_value_splitter.rb
-- benchmarks/benchmark_yjit.rb
-- benchmarks/benchmark_yjit_workers.rb
-- benchmarks/profile_to_s.rb
-- benchmarks/speedup_calculator.rb
-- benchmarks/system_metadata.rb
-- benchmarks/templates/benchmarks.md.erb
-- benchmarks/yjit_tests.rb
 - cataract.gemspec
 - cliff.toml
 - docs/files/EXAMPLE.md
@@ -99,16 +80,22 @@ files:
 - lib/cataract.rb
 - lib/cataract/at_rule.rb
 - lib/cataract/color_conversion.rb
+- lib/cataract/declaration.rb
 - lib/cataract/declarations.rb
 - lib/cataract/import_resolver.rb
+- lib/cataract/pure.rb
+- lib/cataract/pure/byte_constants.rb
+- lib/cataract/pure/helpers.rb
+- lib/cataract/pure/imports.rb
+- lib/cataract/pure/merge.rb
+- lib/cataract/pure/parser.rb
+- lib/cataract/pure/serializer.rb
+- lib/cataract/pure/specificity.rb
 - lib/cataract/rule.rb
 - lib/cataract/stylesheet.rb
 - lib/cataract/stylesheet_scope.rb
 - lib/cataract/version.rb
 - lib/tasks/gem.rake
-- scripts/fuzzer/run.rb
-- scripts/fuzzer/worker.rb
-- scripts/generate_benchmarks_md.rb
 homepage: https://github.com/jamescook/cataract
 licenses:
 - MIT