cataract 0.1.3 → 0.2.0

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,153 @@
+# 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 '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/imports'
+require_relative 'pure/serializer'
+require_relative 'pure/parser'
+require_relative 'pure/flatten'
+
+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
+
+  # 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
+
+  # Deprecated: Use flatten instead
+  def self.merge(stylesheet)
+    warn 'Cataract.merge is deprecated, use Cataract.flatten instead', uplevel: 1
+    flatten(stylesheet)
+  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.
+  # 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)
+  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,20 +120,66 @@ 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 selector and declarations.
+    # Shorthand properties are expanded before comparison, so
+    # `margin: 10px` equals `margin-top: 10px; margin-right: 10px; ...`
+    #
+    # Internal implementation details (id, specificity) are not considered
+    # since they don't affect the CSS semantics.
     #
-    # Two rules are equal if they have the same id, selector, declarations, and specificity.
+    # Can also compare against a CSS string, which is parsed and compared.
     #
-    # @param other [Object] Object to compare with
-    # @return [Boolean] true if rules have same attributes
+    # @param other [Object] Object to compare with (Rule or String)
+    # @return [Boolean] true if rules have same selector and declarations
     def ==(other)
-      return false unless other.is_a?(Rule)
+      case other
+      when Rule
+        return false unless selector == other.selector
 
-      id == other.id &&
-        selector == other.selector &&
-        declarations == other.declarations &&
-        specificity == other.specificity
+        expanded_declarations == other.expanded_declarations
+      when String
+        # Parse CSS string and compare to first rule
+        parsed = Cataract.parse_css(other)
+        return false unless parsed.rules.size == 1
+
+        self == parsed.rules.first
+      else
+        false
+      end
     end
     alias eql? ==
+
+    # Generate hash code for this rule.
+    #
+    # Hash is based on selector and expanded declarations to match the
+    # equality semantics. This allows rules to be used as Hash keys or
+    # in Sets correctly.
+    #
+    # @return [Integer] hash code
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+    def hash
+      @_hash ||= [self.class, selector, expanded_declarations].hash
+    end
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    protected
+
+    # Get expanded and normalized declarations for this rule.
+    #
+    # Shorthands are expanded into their longhand equivalents and sorted
+    # to enable semantic comparison. Result is cached.
+    #
+    # @return [Array<Declaration>] expanded declarations
+    # rubocop:disable Naming/MemoizedInstanceVariableName
+    def expanded_declarations
+      @_expanded_declarations ||= begin
+        expanded = declarations.flat_map { |decl| Cataract._expand_shorthand(decl) }
+        expanded.sort_by! { |d| [d.property, d.value, d.important ? 1 : 0] }
+        expanded
+      end
+    end
+    # rubocop:enable Naming/MemoizedInstanceVariableName
   end
 end