cataract 0.3.0 → 0.5.0

data/lib/cataract/pure/specificity.rb

@@ -4,159 +4,188 @@
 # NO REGEXP ALLOWED - char-by-char parsing only
 
 module Cataract
-  # Legacy CSS2 pseudo-elements written with a single colon (e.g. :before)
-  # that must still be counted as pseudo-elements, not pseudo-classes.
-  PSEUDO_ELEMENT_KEYWORDS = %w[before after first-line first-letter selection].freeze
-
-  # 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
-
-    while i < len
-      byte = selector.getbyte(i)
-
-      if byte == BYTE_HASH
-        id_count += 1
-        i = skip_identifier(selector, i + 1, len)
-      elsif byte == BYTE_DOT
-        class_count += 1
-        i = skip_identifier(selector, i + 1, len)
-      elsif byte == BYTE_LBRACKET
-        attr_count += 1
-        i = skip_attribute_selector(selector, i, len)
-      elsif byte == BYTE_COLON
-        i, is_not, not_content, counts_as_element = parse_pseudo(selector, i, len)
-        if not_content
-          # :not() doesn't count itself, but its content does
-          not_specificity = calculate_specificity(not_content)
-          id_count += not_specificity / 100
-          class_count += (not_specificity % 100) / 10
-          element_count += not_specificity % 10
-        elsif !is_not
-          if counts_as_element
-            pseudo_element_count += 1
+  module Backends
+    class PureImpl
+      # Legacy CSS2 pseudo-elements written with a single colon (e.g. :before)
+      # that must still be counted as pseudo-elements, not pseudo-classes.
+      PSEUDO_ELEMENT_KEYWORDS = %w[before after first-line first-letter selection].freeze
+
+      # Check if byte is a letter (a-z, A-Z)
+      # @param byte [Integer] Byte value from String#getbyte
+      # @return [Boolean] true if letter
+      def letter?(byte)
+        (byte >= BYTE_LOWER_A && byte <= BYTE_LOWER_Z) ||
+          (byte >= BYTE_UPPER_A && byte <= BYTE_UPPER_Z)
+      end
+      private :letter?
+
+      # 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 ident_char?(byte)
+        letter?(byte) || (byte >= BYTE_DIGIT_0 && byte <= BYTE_DIGIT_9) || byte == BYTE_HYPHEN || byte == BYTE_UNDERSCORE
+      end
+      private :ident_char?
+
+      # 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 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
+
+        while i < len
+          byte = selector.getbyte(i)
+
+          if byte == BYTE_HASH
+            id_count += 1
+            i = skip_identifier(selector, i + 1, len)
+          elsif byte == BYTE_DOT
+            class_count += 1
+            i = skip_identifier(selector, i + 1, len)
+          elsif byte == BYTE_LBRACKET
+            attr_count += 1
+            i = skip_attribute_selector(selector, i, len)
+          elsif byte == BYTE_COLON
+            i, is_not, not_content, counts_as_element = parse_pseudo(selector, i, len)
+            if not_content
+              # :not() doesn't count itself, but its content does
+              not_specificity = calculate_specificity(not_content)
+              id_count += not_specificity / 100
+              class_count += (not_specificity % 100) / 10
+              element_count += not_specificity % 10
+            elsif !is_not
+              if counts_as_element
+                pseudo_element_count += 1
+              else
+                pseudo_class_count += 1
+              end
+            end
+          elsif letter?(byte)
+            ident_end = skip_identifier(selector, i + 1, len)
+            if ident_end < len && selector.getbyte(ident_end) == BYTE_PIPE
+              # Namespace prefix (ns|E, css-namespaces-3 qname grammar) -
+              # contributes nothing itself; the local name after '|' is the
+              # real type selector and gets counted on the next iteration.
+              i = ident_end + 1
+            else
+              element_count += 1
+              i = ident_end
+            end
           else
-            pseudo_class_count += 1
+            # Whitespace, combinators, and the universal selector (*) all have
+            # zero specificity - just skip a single byte.
+            i += 1
           end
         end
-      elsif letter?(byte)
-        element_count += 1
-        i = skip_identifier(selector, i + 1, len)
-      else
-        # Whitespace, combinators, and the universal selector (*) all have
-        # zero specificity - just skip a single byte.
-        i += 1
+
+        # Calculate specificity using W3C formula
+        (id_count * 100) +
+          ((class_count + attr_count + pseudo_class_count) * 10) +
+          ((element_count + pseudo_element_count) * 1)
       end
-    end
 
-    # Calculate specificity using W3C formula
-    (id_count * 100) +
-      ((class_count + attr_count + pseudo_class_count) * 10) +
-      ((element_count + pseudo_element_count) * 1)
-  end
+      # Advances past an identifier (used after #id, .class, element names, and
+      # pseudo names), returning the index of the first non-identifier byte.
+      def skip_identifier(selector, pos, len)
+        pos += 1 while pos < len && ident_char?(selector.getbyte(pos))
+        pos
+      end
+      private :skip_identifier
 
-  # Advances past an identifier (used after #id, .class, element names, and
-  # pseudo names), returning the index of the first non-identifier byte.
-  def self.skip_identifier(selector, pos, len)
-    pos += 1 while pos < len && ident_char?(selector.getbyte(pos))
-    pos
-  end
-  private_class_method :skip_identifier
+      # Advances past a bracketed [attr] selector, honoring nested brackets,
+      # returning the index just after the matching closing bracket.
+      def skip_attribute_selector(selector, pos, len)
+        skip_balanced(selector, pos + 1, len, BYTE_LBRACKET, BYTE_RBRACKET)
+      end
+      private :skip_attribute_selector
+
+      # Advances past a balanced open/close byte pair (already past the opening
+      # byte, with depth 1), returning the index just after the matching close.
+      def skip_balanced(selector, pos, len, open_byte, close_byte)
+        depth = 1
+        while pos < len && depth > 0
+          b = selector.getbyte(pos)
+          depth += 1 if b == open_byte
+          depth -= 1 if b == close_byte
+          pos += 1
+        end
+        pos
+      end
+      private :skip_balanced
+
+      # Advances past a balanced open/close byte pair (already past the opening
+      # byte, with depth 1), returning the index OF the matching close byte
+      # (rather than past it), so the caller can capture the content in between.
+      def find_balanced_close(selector, pos, len, open_byte, close_byte)
+        depth = 1
+        while pos < len && depth > 0
+          b = selector.getbyte(pos)
+          depth += 1 if b == open_byte
+          depth -= 1 if b == close_byte
+          pos += 1 if depth > 0
+        end
+        pos
+      end
+      private :find_balanced_close
+
+      # Parses a :pseudo-class, ::pseudo-element, or :not(...) token starting at
+      # the colon byte. Returns [new_pos, is_not, not_content, counts_as_element]:
+      # - new_pos: index just after the fully-consumed token (incl. any (...) args)
+      # - is_not: whether this token is :not (which never counts itself)
+      # - not_content: the non-empty content of :not(...), or nil otherwise
+      # - counts_as_element: whether this token counts toward pseudo-elements
+      #   (::foo, or a legacy single-colon pseudo-element like :before) rather
+      #   than pseudo-classes
+      def parse_pseudo(selector, pos, len)
+        pos += 1
+        is_pseudo_element = false
+        if pos < len && selector.getbyte(pos) == BYTE_COLON
+          is_pseudo_element = true
+          pos += 1
+        end
 
-  # Advances past a bracketed [attr] selector, honoring nested brackets,
-  # returning the index just after the matching closing bracket.
-  def self.skip_attribute_selector(selector, pos, len)
-    skip_balanced(selector, pos + 1, len, BYTE_LBRACKET, BYTE_RBRACKET)
-  end
-  private_class_method :skip_attribute_selector
-
-  # Advances past a balanced open/close byte pair (already past the opening
-  # byte, with depth 1), returning the index just after the matching close.
-  def self.skip_balanced(selector, pos, len, open_byte, close_byte)
-    depth = 1
-    while pos < len && depth > 0
-      b = selector.getbyte(pos)
-      depth += 1 if b == open_byte
-      depth -= 1 if b == close_byte
-      pos += 1
-    end
-    pos
-  end
-  private_class_method :skip_balanced
-
-  # Advances past a balanced open/close byte pair (already past the opening
-  # byte, with depth 1), returning the index OF the matching close byte
-  # (rather than past it), so the caller can capture the content in between.
-  def self.find_balanced_close(selector, pos, len, open_byte, close_byte)
-    depth = 1
-    while pos < len && depth > 0
-      b = selector.getbyte(pos)
-      depth += 1 if b == open_byte
-      depth -= 1 if b == close_byte
-      pos += 1 if depth > 0
-    end
-    pos
-  end
-  private_class_method :find_balanced_close
-
-  # Parses a :pseudo-class, ::pseudo-element, or :not(...) token starting at
-  # the colon byte. Returns [new_pos, is_not, not_content, counts_as_element]:
-  # - new_pos: index just after the fully-consumed token (incl. any (...) args)
-  # - is_not: whether this token is :not (which never counts itself)
-  # - not_content: the non-empty content of :not(...), or nil otherwise
-  # - counts_as_element: whether this token counts toward pseudo-elements
-  #   (::foo, or a legacy single-colon pseudo-element like :before) rather
-  #   than pseudo-classes
-  def self.parse_pseudo(selector, pos, len)
-    pos += 1
-    is_pseudo_element = false
-    if pos < len && selector.getbyte(pos) == BYTE_COLON
-      is_pseudo_element = true
-      pos += 1
-    end
+        pseudo_start = pos
+        pos = skip_identifier(selector, pos, len)
+        pseudo_name = selector[pseudo_start...pos]
+
+        is_legacy_pseudo_element = !is_pseudo_element && !pseudo_name.empty? &&
+                                   PSEUDO_ELEMENT_KEYWORDS.include?(pseudo_name)
+        is_not = (pseudo_name == 'not')
+        not_content = nil
+
+        if pos < len && selector.getbyte(pos) == BYTE_LPAREN
+          pos += 1
+          if is_not
+            content_start = pos
+            pos = find_balanced_close(selector, pos, len, BYTE_LPAREN, BYTE_RPAREN)
+            content = selector[content_start...pos]
+            not_content = content unless content.empty?
+            pos += 1 # Skip closing paren
+          else
+            pos = skip_balanced(selector, pos, len, BYTE_LPAREN, BYTE_RPAREN)
+          end
+        end
 
-    pseudo_start = pos
-    pos = skip_identifier(selector, pos, len)
-    pseudo_name = selector[pseudo_start...pos]
-
-    is_legacy_pseudo_element = !is_pseudo_element && !pseudo_name.empty? &&
-                               PSEUDO_ELEMENT_KEYWORDS.include?(pseudo_name)
-    is_not = (pseudo_name == 'not')
-    not_content = nil
-
-    if pos < len && selector.getbyte(pos) == BYTE_LPAREN
-      pos += 1
-      if is_not
-        content_start = pos
-        pos = find_balanced_close(selector, pos, len, BYTE_LPAREN, BYTE_RPAREN)
-        content = selector[content_start...pos]
-        not_content = content unless content.empty?
-        pos += 1 # Skip closing paren
-      else
-        pos = skip_balanced(selector, pos, len, BYTE_LPAREN, BYTE_RPAREN)
+        [pos, is_not, not_content, is_pseudo_element || is_legacy_pseudo_element]
       end
+      private :parse_pseudo
     end
-
-    [pos, is_not, not_content, is_pseudo_element || is_legacy_pseudo_element]
   end
-  private_class_method :parse_pseudo
 end

data/lib/cataract/pure.rb

@@ -7,16 +7,24 @@
 # NO REGEXP ALLOWED - consume chars one at a time like the C version.
 # ==================================================================
 #
-# Load this instead of the C extension with:
-#   require 'cataract/pure'
+# Load this instead of the C extension by setting CATARACT_PURE before
+# requiring 'cataract' (not by requiring this file directly - lib/cataract.rb
+# is what sets up Cataract::Backends.active and the top-level identity
+# constants like IMPLEMENTATION; this file alone does not):
+#   ENV['CATARACT_PURE'] = '1'
+#   require 'cataract'
 #
 # 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
+#
+# Everything backend-specific here lives under Cataract::Backends::Pure -
+# nothing is defined directly on Cataract itself, so this file can be loaded
+# in the same process as the native backend without either clobbering the
+# other. The one exception is Stylesheet#convert_colors! below: color
+# conversion has no pure-Ruby implementation at all, so the stub simply
+# raises - native's real implementation (ext/cataract_color, loaded
+# separately and only opt-in) defines its own convert_colors! and is
+# unaffected by this file being loaded or not.
 
 require_relative 'error'
 
@@ -24,126 +32,91 @@ require_relative 'version'
 require_relative 'constants'
 
 # Load struct definitions and supporting files
-# (These are also loaded by lib/cataract.rb, but we need them here for direct require)
+# (These are also loaded by lib/cataract/native.rb, but we need them here for direct require)
 require_relative 'declaration'
 require_relative 'rule'
 require_relative 'at_rule'
 require_relative 'media_query'
+require_relative 'conditional_group'
 require_relative 'import_statement'
 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/serializer'
 require_relative 'pure/parser'
 require_relative 'pure/flatten'
+require_relative 'pure/declarations'
 
 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
-  # @param parser_options [Hash] Parser configuration options
-  # @option parser_options [Boolean] :selector_lists (true) Track selector lists
-  # @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_options = {})
-    parser = Parser.new(css_string, parser_options: parser_options)
-    parser.parse
-  end
-
-  # NOTE: Copied from cataract.rb
-  # Need to untangle this eventually
-  def self.parse_css(css, **options)
-    Stylesheet.parse(css, **options)
-  end
-
-  # Flatten stylesheet rules according to CSS cascade rules
-  #
-  # @param stylesheet [Stylesheet] Stylesheet to flatten
-  # @return [Stylesheet] New stylesheet with flattened rules
-  def self.flatten(stylesheet)
-    Flatten.flatten(stylesheet, mutate: false)
-  end
-
-  # Flatten stylesheet rules in-place (mutates receiver)
-  #
-  # @param stylesheet [Stylesheet] Stylesheet to flatten
-  # @return [Stylesheet] Same stylesheet (mutated)
-  def self.flatten!(stylesheet)
-    Flatten.flatten(stylesheet, mutate: true)
-  end
+  module Backends
+    class PureImpl
+      # Flag to indicate the pure Ruby backend 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.
+      # Called by Stylesheet#add_block - not meant for direct use.
+      #
+      # @param css_string [String] CSS to parse
+      # @param parser_options [Hash] Parser configuration options
+      # @option parser_options [Boolean] :selector_lists (true) Track selector lists
+      # @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 parse(css_string, parser_options = {})
+        parser = Parser.new(css_string, parser_options: parser_options)
+        parser.parse
+      end
 
-  # Deprecated: Use flatten instead
-  def self.merge(stylesheet)
-    warn 'Cataract.merge is deprecated, use Cataract.flatten instead', uplevel: 1
-    flatten(stylesheet)
-  end
+      # Flatten stylesheet rules according to CSS cascade rules
+      #
+      # @param stylesheet [Stylesheet] Stylesheet to flatten
+      # @return [Stylesheet] New stylesheet with flattened rules
+      def flatten(stylesheet)
+        Flatten.flatten(stylesheet, mutate: false)
+      end
 
-  # Deprecated: Use flatten! instead
-  def self.merge!(stylesheet)
-    warn 'Cataract.merge! is deprecated, use Cataract.flatten! instead', uplevel: 1
-    flatten!(stylesheet)
-  end
+      # Expand a single shorthand declaration into longhand declarations.
+      # Called by Rule#expanded_declarations - not meant for direct use.
+      #
+      # @param decl [Declaration] Declaration to expand
+      # @return [Array<Declaration>] Array of expanded longhand declarations
+      def expand_shorthand(decl)
+        Flatten.expand_shorthand(decl)
+      end
+    end
 
-  # Expand a single shorthand declaration into longhand declarations.
-  # Underscore prefix indicates semi-private API - use with caution.
-  #
-  # @param decl [Declaration] Declaration to expand
-  # @return [Array<Declaration>] Array of expanded longhand declarations
-  # @api private
-  def self.expand_shorthand(decl)
-    Flatten.expand_shorthand(decl)
+    # The active-facing constant is a single frozen instance, not the class
+    # itself - none of PureImpl's methods touch instance state, so one shared
+    # instance is exactly as safe as the bare module this replaces, while
+    # giving its methods genuine instance-level `private` instead of
+    # `private_class_method`.
+    Pure = PureImpl.new.freeze
   end
 
-  # Add stub method to Stylesheet for pure Ruby implementation
   class Stylesheet
-    # Color conversion is only available in the native C extension
+    # Color conversion has no pure-Ruby implementation.
     #
-    # @raise [NotImplementedError] Always raises - color conversion requires C extension
+    # @raise [NotImplementedError] Always raises - not implemented for pure Ruby
     def convert_colors!(*_args)
-      raise NotImplementedError, 'convert_colors! is only available in the native C extension'
+      raise NotImplementedError, 'convert_colors! is not yet implemented in Cataract'
     end
   end
 end

data/lib/cataract/rule.rb

@@ -26,6 +26,7 @@ module Cataract
   # @attr [Integer, nil] nesting_style 0=implicit, 1=explicit, nil=not nested
   # @attr [Integer, nil] selector_list_id ID linking rules from same selector list (e.g., "h1, h2")
   # @attr [Integer, nil] media_query_id ID of the MediaQuery this rule belongs to (nil if not in media query)
+  # @attr [Integer, nil] conditional_group_id ID of the ConditionalGroup (@supports/@layer/@container/@scope) this rule belongs to (nil if not in one)
   Rule = Struct.new(
     :id,
     :selector,
@@ -34,7 +35,8 @@ module Cataract
     :parent_rule_id,
     :nesting_style,
     :selector_list_id,
-    :media_query_id
+    :media_query_id,
+    :conditional_group_id
   )
 
   class Rule
@@ -49,6 +51,7 @@ module Cataract
     # @param nesting_style [Integer, nil] Nesting style (0=implicit, 1=explicit, nil=not nested)
     # @param selector_list_id [Integer, nil] Selector list ID for grouping
     # @param media_query_id [Integer, nil] MediaQuery ID for rules in media queries
+    # @param conditional_group_id [Integer, nil] ConditionalGroup ID for rules in @supports/@layer/@container/@scope
     # @return [Rule] New rule instance
     #
     # @example Create a rule with keyword arguments
@@ -60,10 +63,11 @@ module Cataract
     #     parent_rule_id: nil,
     #     nesting_style: nil,
     #     selector_list_id: nil,
-    #     media_query_id: nil
+    #     media_query_id: nil,
+    #     conditional_group_id: nil
     #   )
-    def self.make(id:, selector:, declarations:, specificity: nil, parent_rule_id: nil, nesting_style: nil, selector_list_id: nil, media_query_id: nil)
-      new(id, selector, declarations, specificity, parent_rule_id, nesting_style, selector_list_id, media_query_id)
+    def self.make(id:, selector:, declarations:, specificity: nil, parent_rule_id: nil, nesting_style: nil, selector_list_id: nil, media_query_id: nil, conditional_group_id: nil)
+      new(id, selector, declarations, specificity, parent_rule_id, nesting_style, selector_list_id, media_query_id, conditional_group_id)
     end
 
     # Silence warning about method redefinition. We redefine below to lazily calculate
@@ -87,8 +91,11 @@ module Cataract
     def specificity
       return self[:specificity] unless self[:specificity].nil?
 
-      # Calculate and cache
-      calculated = Cataract.calculate_specificity(selector)
+      # Calculate and cache. Specificity is a pure function of the selector
+      # string, identical across backends by design, so this always goes
+      # through the process's active backend regardless of which backend
+      # actually produced this Rule.
+      calculated = Cataract::Backends.active.calculate_specificity(selector)
       self[:specificity] = calculated
       calculated
     end
@@ -215,7 +222,7 @@ module Cataract
     # rubocop:disable Naming/MemoizedInstanceVariableName
     def expanded_declarations
       @_expanded_declarations ||= begin
-        expanded = declarations.flat_map { |decl| Cataract.expand_shorthand(decl) }
+        expanded = declarations.flat_map { |decl| Cataract::Backends.active.expand_shorthand(decl) }
         expanded.sort_by! { |d| [d.property, d.value, d.important ? 1 : 0] }
         expanded
       end