cataract 0.2.1 → 0.2.2

data/lib/cataract/pure/serializer.rb

@@ -10,8 +10,9 @@ module Cataract
   # @param media_index [Hash] Media query symbol => array of rule IDs
   # @param charset [String, nil] @charset value
   # @param has_nesting [Boolean] Whether any nested rules exist
+  # @param selector_lists [Hash] Selector list ID => array of rule IDs (for grouping)
   # @return [String] Compact CSS string
-  def self._stylesheet_to_s(rules, media_index, charset, has_nesting)
+  def self._stylesheet_to_s(rules, media_index, charset, has_nesting, selector_lists = {})
     result = +''
 
     # Add @charset if present
@@ -21,7 +22,7 @@ module Cataract
 
     # Fast path: no nesting - use simple algorithm
     unless has_nesting
-      return stylesheet_to_s_original(rules, media_index, result)
+      return stylesheet_to_s_original(rules, media_index, result, selector_lists)
     end
 
     # Build parent-child relationships
@@ -81,55 +82,20 @@ module Cataract
     result
   end
 
-  # Helper: serialize rules without nesting support
-  def self.stylesheet_to_s_original(rules, media_index, result)
-    # Build rule_id => media_symbol map
-    rule_to_media = {}
-    media_index.each do |media_sym, rule_ids|
-      rule_ids.each do |rule_id|
-        rule_to_media[rule_id] = media_sym
-      end
-    end
-
-    # Iterate through rules in insertion order, grouping consecutive media queries
-    current_media = nil
-    in_media_block = false
-
-    rules.each do |rule|
-      rule_media = rule_to_media[rule.id]
-
-      if rule_media.nil?
-        # Not in any media query - close any open media block first
-        if in_media_block
-          result << "}\n"
-          in_media_block = false
-          current_media = nil
-        end
-      else
-        # This rule is in a media query
-        # Check if media query changed from previous rule
-        if current_media.nil? || current_media != rule_media
-          # Close previous media block if open
-          if in_media_block
-            result << "}\n"
-          end
-
-          # Open new media block
-          current_media = rule_media
-          result << "@media #{current_media} {\n"
-          in_media_block = true
-        end
-      end
-
-      serialize_rule(result, rule)
-    end
-
-    # Close final media block if still open
-    if in_media_block
-      result << "}\n"
-    end
-
-    result
+  # Helper: serialize rules without nesting support (compact format)
+  def self.stylesheet_to_s_original(rules, media_index, result, selector_lists)
+    _serialize_stylesheet_with_grouping(
+      rules: rules,
+      media_index: media_index,
+      result: result,
+      selector_lists: selector_lists,
+      opening_brace: ' { ',
+      closing_brace: " }\n",
+      media_indent: '',
+      decl_indent_base: nil,
+      decl_indent_media: nil,
+      add_blank_lines: false
+    )
   end
 
   # Helper: serialize a rule with its nested children
@@ -236,6 +202,190 @@ module Cataract
     end
   end
 
+  # Helper: find all selectors from same list with matching declarations
+  # Returns array of selectors that can be grouped, marks rules as processed
+  def self.find_groupable_selectors(rule:, rules:, selector_lists:, processed_rule_ids:, rule_to_media:, current_media:)
+    list_id = rule.selector_list_id
+    rule_ids_in_list = selector_lists[list_id]
+
+    # If no other rules in this list, return just this selector
+    if rule_ids_in_list.nil? || rule_ids_in_list.size <= 1
+      processed_rule_ids[rule.id] = true
+      return [rule.selector]
+    end
+
+    # Find all rules in this list that have identical declarations AND same media context
+    matching_selectors = []
+    rule_ids_in_list.each do |rid|
+      # Find the rule by ID
+      other_rule = rules.find { |r| r.id == rid }
+      next unless other_rule
+      next if processed_rule_ids[rid]
+
+      # Check same media context
+      next if rule_to_media[rid] != current_media
+
+      # Check declarations match (compare arrays directly for performance)
+      if declarations_equal?(rule.declarations, other_rule.declarations)
+        matching_selectors << other_rule.selector
+        processed_rule_ids[rid] = true
+      end
+    end
+
+    matching_selectors
+  end
+
+  # Private shared implementation for stylesheet serialization with optional selector list grouping
+  # All formatting behavior controlled by kwargs to avoid mode flags and if/else branches
+  def self._serialize_stylesheet_with_grouping(
+    rules:,
+    media_index:,
+    result:,
+    selector_lists:,
+    opening_brace:,      # ' { ' (compact) vs " {\n" (formatted)
+    closing_brace:,      # " }\n" (compact) vs "}\n" (formatted)
+    media_indent:,       # '' (compact) vs '  ' (formatted)
+    decl_indent_base:,   # nil (compact) vs '  ' (formatted base rules)
+    decl_indent_media:,  # nil (compact) vs '    ' (formatted media rules)
+    add_blank_lines:     # false (compact) vs true (formatted)
+  )
+    grouping_enabled = selector_lists && !selector_lists.empty?
+
+    # Build rule_id => media_symbol map
+    rule_to_media = {}
+    media_index.each do |media_sym, rule_ids|
+      rule_ids.each do |rule_id|
+        rule_to_media[rule_id] = media_sym
+      end
+    end
+
+    # Track processed rules to avoid duplicates when grouping
+    processed_rule_ids = {}
+
+    # Iterate through rules in insertion order, grouping consecutive media queries
+    current_media = nil
+    in_media_block = false
+    rule_index = 0
+
+    rules.each do |rule|
+      # Skip if already processed (when grouped)
+      next if processed_rule_ids[rule.id]
+
+      rule_media = rule_to_media[rule.id]
+      is_first_rule = (rule_index == 0)
+
+      if rule_media.nil?
+        # Not in any media query - close any open media block first
+        if in_media_block
+          result << "}\n"
+          in_media_block = false
+          current_media = nil
+        end
+
+        # Add blank line prefix for non-first rules (formatted only)
+        result << "\n" if add_blank_lines && !is_first_rule
+
+        # Try to group with other rules from same selector list
+        if grouping_enabled && rule.is_a?(Rule) && rule.selector_list_id
+          selectors = find_groupable_selectors(
+            rule: rule,
+            rules: rules,
+            selector_lists: selector_lists,
+            processed_rule_ids: processed_rule_ids,
+            rule_to_media: rule_to_media,
+            current_media: rule_media
+          )
+
+          # Serialize with grouped selectors
+          result << selectors.join(', ') << opening_brace
+          if decl_indent_base
+            serialize_declarations_formatted(result, rule.declarations, decl_indent_base)
+          else
+            serialize_declarations(result, rule.declarations)
+          end
+          result << closing_brace
+        else
+          # Serialize individual rule
+          if decl_indent_base
+            serialize_rule_formatted(result, rule, '', true)
+          else
+            serialize_rule(result, rule)
+          end
+          processed_rule_ids[rule.id] = true
+        end
+      else
+        # This rule is in a media query
+        if current_media.nil? || current_media != rule_media
+          # Close previous media block if open
+          if in_media_block
+            result << "}\n"
+          end
+
+          # Add blank line prefix for non-first rules (formatted only)
+          result << "\n" if add_blank_lines && !is_first_rule
+
+          # Open new media block
+          current_media = rule_media
+          result << "@media #{current_media} {\n"
+          in_media_block = true
+        end
+
+        # Try to group with other rules from same selector list
+        if grouping_enabled && rule.is_a?(Rule) && rule.selector_list_id
+          selectors = find_groupable_selectors(
+            rule: rule,
+            rules: rules,
+            selector_lists: selector_lists,
+            processed_rule_ids: processed_rule_ids,
+            rule_to_media: rule_to_media,
+            current_media: rule_media
+          )
+
+          # Serialize with grouped selectors (with media indent)
+          result << media_indent << selectors.join(', ') << opening_brace
+          if decl_indent_media
+            serialize_declarations_formatted(result, rule.declarations, decl_indent_media)
+          else
+            serialize_declarations(result, rule.declarations)
+          end
+          result << media_indent << closing_brace
+        else
+          # Serialize individual rule inside media block
+          if decl_indent_media
+            serialize_rule_formatted(result, rule, media_indent, true)
+          else
+            serialize_rule(result, rule)
+          end
+          processed_rule_ids[rule.id] = true
+        end
+      end
+
+      rule_index += 1
+    end
+
+    # Close final media block if still open
+    if in_media_block
+      result << "}\n"
+    end
+
+    result
+  end
+  private_class_method :_serialize_stylesheet_with_grouping
+
+  # Helper: check if two declaration arrays are equal
+  def self.declarations_equal?(decls1, decls2)
+    return false if decls1.size != decls2.size
+
+    decls1.each_with_index do |d1, i|
+      d2 = decls2[i]
+      return false if d1.property != d2.property
+      return false if d1.value != d2.value
+      return false if d1.important != d2.important
+    end
+
+    true
+  end
+
   # Helper: serialize a single rule
   def self.serialize_rule(result, rule)
     # Check if this is an AtRule
@@ -307,8 +457,9 @@ module Cataract
   # @param media_index [Hash] Media query symbol => array of rule IDs
   # @param charset [String, nil] @charset value
   # @param has_nesting [Boolean] Whether any nested rules exist
+  # @param selector_lists [Hash] Selector list ID => array of rule IDs (for grouping)
   # @return [String] Formatted CSS string
-  def self._stylesheet_to_formatted_s(rules, media_index, charset, has_nesting)
+  def self._stylesheet_to_formatted_s(rules, media_index, charset, has_nesting, selector_lists = {})
     result = +''
 
     # Add @charset if present
@@ -318,7 +469,7 @@ module Cataract
 
     # Fast path: no nesting - use simple algorithm
     unless has_nesting
-      return stylesheet_to_formatted_s_original(rules, media_index, result)
+      return stylesheet_to_formatted_s_original(rules, media_index, result, selector_lists)
     end
 
     # Build parent-child relationships
@@ -383,68 +534,19 @@ module Cataract
   end
 
   # Helper: formatted serialization without nesting support
-  def self.stylesheet_to_formatted_s_original(rules, media_index, result)
-    # Build rule_id => media_symbol map
-    rule_to_media = {}
-    media_index.each do |media_sym, rule_ids|
-      rule_ids.each do |rule_id|
-        rule_to_media[rule_id] = media_sym
-      end
-    end
-
-    # Iterate through rules, grouping consecutive media queries
-    current_media = nil
-    in_media_block = false
-    rule_index = 0
-
-    rules.each do |rule|
-      rule_media = rule_to_media[rule.id]
-      is_first_rule = (rule_index == 0)
-
-      if rule_media.nil?
-        # Not in any media query - close any open media block first
-        if in_media_block
-          result << "}\n"
-          in_media_block = false
-          current_media = nil
-        end
-
-        # Add blank line prefix for non-first rules
-        result << "\n" unless is_first_rule
-
-        # Output rule with no indentation (always single newline suffix)
-        serialize_rule_formatted(result, rule, '', true)
-      else
-        # This rule is in a media query
-        if current_media.nil? || current_media != rule_media
-          # Close previous media block if open
-          if in_media_block
-            result << "}\n"
-          end
-
-          # Add blank line prefix for non-first rules
-          result << "\n" unless is_first_rule
-
-          # Open new media block
-          current_media = rule_media
-          result << "@media #{current_media} {\n"
-          in_media_block = true
-        end
-
-        # Serialize rule inside media block with 2-space indentation
-        # Rules inside media blocks always get single newline (is_last=true)
-        serialize_rule_formatted(result, rule, '  ', true)
-      end
-
-      rule_index += 1
-    end
-
-    # Close final media block if still open
-    if in_media_block
-      result << "}\n"
-    end
-
-    result
+  def self.stylesheet_to_formatted_s_original(rules, media_index, result, selector_lists)
+    _serialize_stylesheet_with_grouping(
+      rules: rules,
+      media_index: media_index,
+      result: result,
+      selector_lists: selector_lists,
+      opening_brace: " {\n",
+      closing_brace: "}\n",
+      media_indent: '  ',
+      decl_indent_base: '  ',
+      decl_indent_media: '    ',
+      add_blank_lines: true
+    )
   end
 
   # Helper: serialize a rule with nested children (formatted)

data/lib/cataract/pure.rb

@@ -84,14 +84,16 @@ module Cataract
   #
   # @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 = Parser.new(css_string)
+  def self._parse_css(css_string, parser_options = {})
+    parser = Parser.new(css_string, parser_options: parser_options)
     parser.parse
   end
 

data/lib/cataract/rule.rb

@@ -24,16 +24,44 @@ module Cataract
   # @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
+  # @attr [Integer, nil] selector_list_id ID linking rules from same selector list (e.g., "h1, h2")
   Rule = Struct.new(
     :id,
     :selector,
     :declarations,
     :specificity,
     :parent_rule_id,
-    :nesting_style
+    :nesting_style,
+    :selector_list_id
   )
 
   class Rule
+    # Factory method for creating Rules with keyword arguments (for tests/readability).
+    # C code and hot paths should use positional arguments directly via Rule.new.
+    #
+    # @param id [Integer] The rule's position in the stylesheet
+    # @param selector [String] CSS selector
+    # @param declarations [Array<Declaration>] Array of declarations
+    # @param specificity [Integer, nil] Specificity value (nil to calculate lazily)
+    # @param parent_rule_id [Integer, nil] Parent rule ID for nested rules
+    # @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
+    # @return [Rule] New rule instance
+    #
+    # @example Create a rule with keyword arguments
+    #   Rule.make(
+    #     id: 0,
+    #     selector: '.foo',
+    #     declarations: [Declaration.new('color', 'red', false)],
+    #     specificity: 10,
+    #     parent_rule_id: nil,
+    #     nesting_style: nil,
+    #     selector_list_id: nil
+    #   )
+    def self.make(id:, selector:, declarations:, specificity: nil, parent_rule_id: nil, nesting_style: nil, selector_list_id: nil)
+      new(id, selector, declarations, specificity, parent_rule_id, nesting_style, selector_list_id)
+    end
+
     # Silence warning about method redefinition. We redefine below to lazily calculate
     # specificity
     undef_method :specificity if method_defined?(:specificity)
@@ -87,6 +115,7 @@ module Cataract
     #
     # @param property [String] CSS property name to match
     # @param value [String, nil] Optional value to match
+    # @param prefix_match [Boolean] Whether to match by prefix (default: false)
     # @return [Boolean] true if rule has matching declaration
     #
     # @example Check for color property
@@ -94,9 +123,16 @@ module Cataract
     #
     # @example Check for specific property value
     #   rule.has_property?('color', 'red') #=> true
-    def has_property?(property, value = nil)
+    #
+    # @example Check for any margin-related property
+    #   rule.has_property?('margin', prefix_match: true) #=> true if has margin, margin-top, etc.
+    def has_property?(property, value = nil, prefix_match: false)
       declarations.any? do |decl|
-        property_matches = decl.property == property
+        property_matches = if prefix_match
+                             decl.property.start_with?(property)
+                           else
+                             decl.property == property
+                           end
         value_matches = value.nil? || decl.value == value
         property_matches && value_matches
       end