cataract 0.1.4 → 0.2.0

data/lib/cataract/pure/{merge.rb → flatten.rb}

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-# Pure Ruby CSS merge implementation
+# Pure Ruby CSS flatten implementation
 # NO REGEXP ALLOWED - use string manipulation only
 
 module Cataract
-  module Merge
+  module Flatten
     # Property name constants (US-ASCII for merge output)
     PROP_MARGIN = 'margin'.encode(Encoding::US_ASCII).freeze
     PROP_MARGIN_TOP = 'margin-top'.encode(Encoding::US_ASCII).freeze
@@ -138,7 +138,7 @@ module Cataract
     # @param stylesheet [Stylesheet] Stylesheet to merge
     # @param mutate [Boolean] If true, mutate the stylesheet; otherwise create new one
     # @return [Stylesheet] Merged stylesheet
-    def self.merge(stylesheet, mutate: false)
+    def self.flatten(stylesheet, mutate: false)
       # Separate AtRules (pass-through) from regular Rules (to merge)
       at_rules = []
       regular_rules = []
@@ -152,7 +152,9 @@ module Cataract
       end
 
       # Expand shorthands in regular rules only (AtRules don't have declarations)
-      regular_rules.each { |rule| expand_shorthands!(rule) }
+      regular_rules.each do |rule|
+        rule.declarations.replace(rule.declarations.flat_map { |decl| _expand_shorthand(decl) })
+      end
 
       merged_rules = []
 
@@ -160,7 +162,7 @@ module Cataract
       # (Nesting is flattened during parsing, so we just merge by resolved selector)
       grouped = regular_rules.group_by(&:selector)
       grouped.each do |selector, rules|
-        merged_rule = merge_rules_for_selector(selector, rules)
+        merged_rule = flatten_rules_for_selector(selector, rules)
         merged_rules << merged_rule if merged_rule
       end
 
@@ -195,7 +197,7 @@ module Cataract
     # @param selector [String] The selector
     # @param rules [Array<Rule>] Rules with this selector
     # @return [Rule] Merged rule with cascaded declarations
-    def self.merge_rules_for_selector(selector, rules)
+    def self.flatten_rules_for_selector(selector, rules)
       # Build declaration map: property => [source_order, specificity, important, value]
       decl_map = {}
 
@@ -284,42 +286,39 @@ module Cataract
       Cataract.calculate_specificity(selector)
     end
 
-    # Expand shorthand properties in a rule (mutates declarations)
+    # Expand a single shorthand declaration into longhand declarations.
+    # Returns an array of longhand declarations. If the declaration is not a shorthand,
+    # returns an array with just that declaration.
     #
-    # @param rule [Rule] Rule to expand
-    def self.expand_shorthands!(rule)
-      expanded = []
-
-      rule.declarations.each do |decl|
-        prop = decl.property
-
-        case prop
-        when 'margin'
-          expanded.concat(expand_margin(decl))
-        when 'padding'
-          expanded.concat(expand_padding(decl))
-        when 'border'
-          expanded.concat(expand_border(decl))
-        when 'border-top', 'border-right', 'border-bottom', 'border-left'
-          expanded.concat(expand_border_side(decl))
-        when 'border-width'
-          expanded.concat(expand_border_width(decl))
-        when 'border-style'
-          expanded.concat(expand_border_style(decl))
-        when 'border-color'
-          expanded.concat(expand_border_color(decl))
-        when 'font'
-          expanded.concat(expand_font(decl))
-        when 'background'
-          expanded.concat(expand_background(decl))
-        when 'list-style'
-          expanded.concat(expand_list_style(decl))
-        else
-          expanded << decl
-        end
+    # @param decl [Declaration] Declaration to expand
+    # @return [Array<Declaration>] Array of expanded longhand declarations
+    # @api private
+    def self._expand_shorthand(decl)
+      case decl.property
+      when 'margin'
+        expand_margin(decl)
+      when 'padding'
+        expand_padding(decl)
+      when 'border'
+        expand_border(decl)
+      when 'border-top', 'border-right', 'border-bottom', 'border-left'
+        expand_border_side(decl)
+      when 'border-width'
+        expand_border_width(decl)
+      when 'border-style'
+        expand_border_style(decl)
+      when 'border-color'
+        expand_border_color(decl)
+      when 'font'
+        expand_font(decl)
+      when 'background'
+        expand_background(decl)
+      when 'list-style'
+        expand_list_style(decl)
+      else
+        # Not a shorthand, return as-is in an array
+        [decl]
       end
-
-      rule.declarations.replace(expanded)
     end
 
     # Expand margin shorthand

data/lib/cataract/pure/imports.rb

@@ -155,7 +155,20 @@ module Cataract
         full_match = css_string[import_start...import_end]
 
         imports << { url: url, media: media, full_match: full_match }
+      elsif match_ascii_ci?(css_string, i, '@charset')
+        # Skip @charset if present - it can come before @import
+        while i < len && css_string.getbyte(i) != BYTE_SEMICOLON
+          i += 1
+        end
+        i += 1 if i < len # Skip semicolon
       else
+        # If we hit any other content (rules, other at-rules), stop scanning
+        # Per CSS spec, @import must be at the top (only @charset can come before)
+        byte = css_string.getbyte(i) if i < len
+        if i < len && !is_whitespace?(byte)
+          break
+        end
+
         i += 1
       end
     end

data/lib/cataract/pure/parser.rb

@@ -74,6 +74,7 @@ module Cataract
       # Parser state
       @rules = []                    # Flat array of Rule structs
       @_media_index = {}             # Symbol => Array of rule IDs
+      @imports = []                  # Array of ImportStatement structs
       @rule_id_counter = 0           # Next rule ID (0-indexed)
       @media_query_count = 0         # Safety limit
       @_has_nesting = false          # Set to true if any nested rules found
@@ -82,9 +83,8 @@ module Cataract
     end
 
     def parse
-      # Skip @import statements at the beginning (they're handled by ImportResolver)
-      # Per CSS spec, @import must come before all rules (except @charset)
-      skip_imports
+      # @import statements are now handled in parse_at_rule
+      # They must come before all rules (except @charset) per CSS spec
 
       # Main parsing loop - char-by-char, NO REGEXP
       until eof?
@@ -182,6 +182,7 @@ module Cataract
       {
         rules: @rules,
         _media_index: @_media_index,
+        imports: @imports,
         charset: @charset,
         _has_nesting: @_has_nesting
       }
@@ -658,6 +659,23 @@ module Cataract
         return
       end
 
+      # Handle @import - must come before rules (except @charset)
+      if at_rule_name == 'import'
+        # If we've already seen a rule, this @import is invalid
+        if @rules.size > 0
+          warn 'CSS @import ignored: @import must appear before all rules (found import after rules)'
+          # Skip to semicolon
+          while !eof? && peek_byte != BYTE_SEMICOLON
+            @pos += 1
+          end
+          @pos += 1 if peek_byte == BYTE_SEMICOLON
+          return
+        end
+
+        parse_import_statement
+        return
+      end
+
       # Handle conditional group at-rules: @supports, @layer, @container, @scope
       # These behave like @media but don't affect media context
       if AT_RULE_TYPES.include?(at_rule_name)
@@ -1123,7 +1141,93 @@ module Cataract
       @pos += 1 if peek_byte == BYTE_SEMICOLON # consume semicolon
     end
 
-    # Skip @import statements at the beginning of CSS
+    # Parse an @import statement
+    # @import "url" [media-query];
+    # @import url("url") [media-query];
+    def parse_import_statement
+      skip_ws_and_comments
+
+      # Check for optional url(
+      has_url_function = false
+      if @pos + 4 <= @len && match_ascii_ci?(@css, @pos, 'url(')
+        has_url_function = true
+        @pos += 4
+        skip_ws_and_comments
+      end
+
+      # Find opening quote
+      byte = peek_byte
+      if eof? || (byte != BYTE_DQUOTE && byte != BYTE_SQUOTE)
+        # Invalid @import, skip to semicolon
+        while !eof? && peek_byte != BYTE_SEMICOLON
+          @pos += 1
+        end
+        @pos += 1 unless eof?
+        return
+      end
+
+      quote_char = byte
+      @pos += 1 # Skip opening quote
+
+      url_start = @pos
+
+      # Find closing quote (handle escaped quotes)
+      while !eof? && peek_byte != quote_char
+        @pos += if peek_byte == BYTE_BACKSLASH && @pos + 1 < @len
+                  2 # Skip escaped character
+                else
+                  1
+                end
+      end
+
+      if eof?
+        # Unterminated string
+        return
+      end
+
+      url = byteslice_encoded(url_start, @pos - url_start)
+      @pos += 1 # Skip closing quote
+
+      # Skip closing paren if we had url(
+      if has_url_function
+        skip_ws_and_comments
+        @pos += 1 if peek_byte == BYTE_RPAREN
+      end
+
+      skip_ws_and_comments
+
+      # Check for optional media query (everything until semicolon)
+      media = nil
+      if !eof? && peek_byte != BYTE_SEMICOLON
+        media_start = @pos
+
+        # Find semicolon
+        while !eof? && peek_byte != BYTE_SEMICOLON
+          @pos += 1
+        end
+
+        media_end = @pos
+
+        # Trim trailing whitespace from media query
+        while media_end > media_start && whitespace?(@css.getbyte(media_end - 1))
+          media_end -= 1
+        end
+
+        if media_end > media_start
+          media = byteslice_encoded(media_start, media_end - media_start).to_sym
+        end
+      end
+
+      # Skip semicolon
+      @pos += 1 if peek_byte == BYTE_SEMICOLON
+
+      # Create ImportStatement (resolved: false by default)
+      import_stmt = ImportStatement.new(@rule_id_counter, url, media, false)
+      @imports << import_stmt
+      @rule_id_counter += 1
+    end
+
+    # Skip @import statements at the beginning of CSS (DEPRECATED - now parsed)
     # Per CSS spec, @import must come before all rules (except @charset)
     def skip_imports
       until eof?

data/lib/cataract/pure.rb

@@ -32,6 +32,7 @@ require_relative 'version'
 require_relative 'declaration'
 require_relative 'rule'
 require_relative 'at_rule'
+require_relative 'import_statement'
 require_relative 'stylesheet_scope'
 require_relative 'stylesheet'
 require_relative 'declarations'
@@ -63,7 +64,7 @@ require_relative 'pure/specificity'
 require_relative 'pure/imports'
 require_relative 'pure/serializer'
 require_relative 'pure/parser'
-require_relative 'pure/merge'
+require_relative 'pure/flatten'
 
 module Cataract
   # Flag to indicate pure Ruby version is loaded
@@ -102,20 +103,42 @@ module Cataract
     Stylesheet.parse(css)
   end
 
-  # Merge stylesheet rules according to CSS cascade rules
+  # Flatten 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)
+  # @param stylesheet [Stylesheet] Stylesheet to flatten
+  # @return [Stylesheet] New stylesheet with flattened rules
+  def self.flatten(stylesheet)
+    Flatten.flatten(stylesheet, mutate: false)
   end
 
-  # Merge stylesheet rules in-place (mutates receiver)
+  # Flatten stylesheet rules in-place (mutates receiver)
   #
-  # @param stylesheet [Stylesheet] Stylesheet to merge
+  # @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)
-    Merge.merge(stylesheet, mutate: true)
+    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

data/lib/cataract/rule.rb

@@ -123,18 +123,63 @@ module Cataract
     # 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. Specificity is derived from
-    # the selector, so if selectors match, specificity must match too.
+    # since they don't affect the CSS semantics.
+    #
+    # Can also compare against a CSS string, which is parsed and compared.
     #
-    # @param other [Object] Object to compare with
+    # @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
 
-      selector == other.selector &&
-        declarations == other.declarations
+        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