canon 0.1.23 → 0.2.1

data/lib/canon/comparison/whitespace_sensitivity.rb

@@ -4,30 +4,74 @@ module Canon
   module Comparison
     # Whitespace sensitivity utilities for element-level control
     #
-    # This module provides logic to determine whether whitespace should be
-    # preserved during comparison based on:
-    # - Format-specific defaults (HTML has built-in sensitive elements)
-    # - User-configured whitelist (elements that care about whitespace)
-    # - User-configured blacklist (elements that don't care about whitespace)
-    # - xml:space attribute in the document itself
-    # - respect_xml_space flag (whether to honor or override xml:space)
+    # This module provides three-way classification of whitespace behaviour
+    # at the element level:
+    #
+    # * **:preserve** — every whitespace character is significant. `" "` ≠ `"\n"`.
+    #   Configured via +preserve_whitespace_elements+ (HTML default: pre, code,
+    #   textarea, script, style; XML default: none).
+    #
+    # * **:collapse** — presence ≠ absence, but all whitespace forms are
+    #   equivalent: `" "` == `"\n  "`. Configured via +collapse_whitespace_elements+
+    #   (HTML default: p, li, dt, dd, td, th, h1-h6, caption, figcaption, label,
+    #   legend, summary, blockquote, address; XML default: none).
+    #
+    # * **:strip** — all whitespace is structural formatting noise and is
+    #   dropped. Default for XML; HTML elements not in the above lists.
+    #
+    # Classification is **ancestor-based**: the closest matching ancestor
+    # determines the class. The strip blacklist (+strip_whitespace_elements+)
+    # overrides any sensitive ancestor.
     #
     # == Priority Order
     #
     # 1. respect_xml_space: false → User config only (ignore xml:space)
-    # 2. User whitelist → Use whitelist (user explicitly declared)
-    # 3. Format defaults → HTML: [:pre, :textarea, :script, :style], XML: []
-    # 4. User blacklist → Remove from defaults/whitelist
-    # 5. xml:space="preserve" → Element is sensitive
-    # 6. xml:space="default" → Use steps 1-4
+    # 2. Ancestor walk (strip blacklist wins; then preserve; then collapse)
+    # 3. xml:space="preserve" → preserve
+    # 4. xml:space="default" → use configured behaviour
+    # 5. Format defaults (HTML: collapse for most elements; XML: strip)
     #
     # == Usage
     #
+    #   WhitespaceSensitivity.classify_element(element, match_opts)
+    #   => :preserve, :collapse, or :strip
+    #
     #   WhitespaceSensitivity.element_sensitive?(node, opts)
-    #   => true if whitespace should be preserved for this element
+    #   => true if whitespace should be preserved (preserve or collapse)
     module WhitespaceSensitivity
+      # HTML mixed-content "leaf block" elements where whitespace presence
+      # matters but all forms are equivalent (CSS block whitespace collapsing).
+      HTML_COLLAPSE_ELEMENTS = %w[
+        p li dt dd td th caption figcaption label legend summary
+        h1 h2 h3 h4 h5 h6
+        blockquote address button
+      ].freeze
+
+      # HTML elements where every whitespace character is significant.
+      HTML_PRESERVE_ELEMENTS = %w[pre code textarea script style].freeze
+
       class << self
-        # Check if an element is whitespace-sensitive based on configuration
+        # Classify the whitespace behaviour for an element using ancestor walk.
+        #
+        # @param element [Object] The element node to classify
+        # @param match_opts [Hash] Resolved match options
+        # @return [Symbol] :preserve, :collapse, or :strip
+        def classify_element(element, match_opts)
+          return :strip unless element
+          return :strip unless element.respond_to?(:name)
+
+          preserve_set  = resolved_preserve_elements_set(match_opts)
+          collapse_set  = resolved_collapse_elements_set(match_opts)
+          strip_set = resolved_strip_elements_set(match_opts)
+
+          # Ancestor walk: start at the element itself, walk up.
+          # Strip blacklist wins over any sensitive ancestor.
+          walk_ancestor_classification(element, preserve_set, collapse_set,
+                                       strip_set, match_opts)
+        end
+
+        # Check if an element is whitespace-sensitive based on configuration.
+        # Returns true for :preserve or :collapse classification.
         #
         # @param node [Object] The element node to check
         # @param opts [Hash] Comparison options containing match_opts
@@ -40,7 +84,7 @@ module Canon
           parent = node.parent
 
           # 1. Check if we should ignore xml:space (user override)
-          if !respect_xml_space?(match_opts)
+          unless respect_xml_space?(match_opts)
             return user_config_sensitive?(parent, match_opts)
           end
 
@@ -50,8 +94,9 @@ module Canon
           # 3. Check xml:space="default" (use configured behavior)
           return false if xml_space_default?(parent)
 
-          # 4. Use user configuration + format defaults
-          configured_sensitive?(parent, match_opts)
+          # 4. Three-way classification (ancestor-based)
+          classification = classify_element(parent, match_opts)
+          %i[preserve collapse].include?(classification)
         end
 
         # Check if whitespace-only text node should be filtered
@@ -66,105 +111,93 @@ module Canon
           element_sensitive?(node, opts)
         end
 
-        # Check if structural whitespace is preserved (not stripped) for an element.
+        # Return the whitespace class for a text node used during comparison.
+        #
+        # :preserve   → preserve all whitespace character-by-character
+        # :collapse   → preserve presence (normalize to single space)
+        # :strip      → drop whitespace-only text nodes
         #
-        # Uses sensitive_elements (whitelist) and insensitive_elements (blacklist)
-        # from match_opts. Blacklist takes precedence over whitelist.
-        # Format defaults apply when neither is configured.
+        # @param node [Object] Text node to classify
+        # @param opts [Hash] Comparison options containing match_opts
+        # @return [Symbol] :preserve, :collapse, or :strip
+        def classify_text_node(node, opts)
+          match_opts = opts[:match_opts]
+          return :strip unless match_opts
+          return :strip unless text_node_parent?(node)
+
+          parent = node.parent
+
+          unless respect_xml_space?(match_opts)
+            return user_config_sensitive?(parent,
+                                          match_opts) ? :preserve : :strip
+          end
+
+          return :preserve if xml_space_preserve?(parent)
+          return :strip if xml_space_default?(parent)
+
+          classify_element(parent, match_opts)
+        end
+
+        # Check if structural whitespace is preserved (not stripped) for an element.
         #
-        # No inheritance from ancestors — checks only the immediate parent element name.
+        # Uses the same priority chain as element_sensitive? / classify_text_node:
+        #   1. xml:space="preserve" → always preserved
+        #   2. xml:space="default"  → use configured behaviour
+        #   3. ancestor-walk classification (strip = dropped)
         #
         # @param element [Object] Element node to check
         # @param match_opts [Hash] Resolved match options
         # @return [Boolean] true if whitespace is preserved (not stripped)
         def whitespace_preserved?(element, match_opts)
-          return false unless element
-          return false unless element.respond_to?(:name)
-
-          elem_name = element.name.to_s
-
-          # Blacklist: always strip (highest priority)
-          insensitive_raw = match_opts[:insensitive_elements]
-          insensitive_raw ||= match_opts[:whitespace_insensitive_elements]
-          insensitive = (insensitive_raw || []).map(&:to_s)
-          return false if insensitive.include?(elem_name)
-
-          # Check if we should ignore xml:space (user override)
           if respect_xml_space?(match_opts)
-            # Check xml:space="preserve" (document declaration)
-            return true if xml_space_preserve?(element)
-
-            # Check xml:space="default" (use configured behavior)
+            return true  if xml_space_preserve?(element)
             return false if xml_space_default?(element)
           end
 
-          # Whitelist: preserve whitespace
-          sensitive = resolved_sensitive_elements(match_opts)
-          return true if sensitive.include?(elem_name)
-
-          # Default: preserve for HTML, strip for XML
-          format = match_opts[:format] || :xml
-          case format
-          when :html, :html4, :html5
-            true
-          else
-            false
-          end
+          classification = classify_element(element, match_opts)
+          %i[preserve collapse].include?(classification)
         end
 
-        # Get resolved list of whitespace-sensitive element names (strings).
+        # Get resolved list of preserve whitespace element names (strings).
         #
-        # Combines format defaults + user whitelist, minus user blacklist.
-        # Supports both short names (sensitive_elements) and long names
-        # (whitespace_sensitive_elements) for backward compatibility.
+        # @param match_opts [Hash] Resolved match options
+        # @return [Array<String>] Preserve element names
+        def resolved_preserve_elements(match_opts)
+          resolved_preserve_elements_set(match_opts).to_a
+        end
+
+        # Get resolved list of collapse whitespace element names (strings).
         #
         # @param match_opts [Hash] Resolved match options
-        # @return [Array<String>] Sensitive element names
-        def resolved_sensitive_elements(match_opts)
-          sensitive = []
+        # @return [Array<String>] Collapse element names
+        def resolved_collapse_elements(match_opts)
+          resolved_collapse_elements_set(match_opts).to_a
+        end
 
-          # 1. Format defaults
+        # Get format-specific default preserve (exact-whitespace) elements.
+        # This is the SINGLE SOURCE OF TRUTH for default preserve-whitespace elements.
+        #
+        # @param match_opts [Hash] Resolved match options
+        # @return [Array<Symbol>] Default preserve element names
+        def format_default_preserve_elements(match_opts)
           format = match_opts[:format] || :xml
           case format
           when :html, :html4, :html5
-            sensitive += %w[pre code textarea script style]
-          end
-
-          # 2. User whitelist (additive to format defaults)
-          whitelist = match_opts[:sensitive_elements]
-          whitelist ||= match_opts[:whitespace_sensitive_elements]
-          if whitelist
-            sensitive += whitelist.map(&:to_s)
-          end
-
-          # 3. User blacklist removes from combined set
-          blacklist_raw = match_opts[:insensitive_elements]
-          blacklist_raw ||= match_opts[:whitespace_insensitive_elements]
-          if blacklist_raw
-            blacklist = blacklist_raw.to_set(&:to_s)
-            sensitive.reject! { |e| blacklist.include?(e) }
+            HTML_PRESERVE_ELEMENTS.map(&:to_sym).freeze
+          else
+            [].freeze
           end
-
-          sensitive.uniq
         end
 
-        # Get format-specific default sensitive elements
-        #
-        # This is the SINGLE SOURCE OF TRUTH for default whitespace-sensitive
-        # elements. All other code should use this method to get the list.
+        # Get format-specific default collapse elements.
         #
         # @param match_opts [Hash] Resolved match options
-        # @return [Array<Symbol>] Default sensitive element names
-        def format_default_sensitive_elements(match_opts)
+        # @return [Array<Symbol>] Default collapse element names
+        def format_default_collapse_elements(match_opts)
           format = match_opts[:format] || :xml
-
           case format
           when :html, :html4, :html5
-            # HTML specification: these elements preserve whitespace
-            %i[pre code textarea script style].freeze
-          when :xml
-            # XML has no default sensitive elements - purely user-controlled
-            [].freeze
+            HTML_COLLAPSE_ELEMENTS.map(&:to_sym).freeze
           else
             [].freeze
           end
@@ -172,23 +205,80 @@ module Canon
 
         # Check if an element is in the default sensitive list for its format
         #
-        # Convenience method for checking element sensitivity without building
-        # the full list first.
-        #
         # @param element_name [String, Symbol] The element name to check
         # @param match_opts [Hash] Resolved match options
         # @return [Boolean] true if element is in default sensitive list
         def default_sensitive_element?(element_name, match_opts)
-          format_default_sensitive_elements(match_opts)
+          format_default_preserve_elements(match_opts)
             .include?(element_name.to_sym)
         end
 
         private
 
+        # Build the Set of preserve whitespace element names (strings).
+        def resolved_preserve_elements_set(match_opts)
+          set = Set.new(format_default_preserve_elements(match_opts).map(&:to_s))
+
+          if match_opts[:preserve_whitespace_elements]
+            set |= match_opts[:preserve_whitespace_elements].map(&:to_s)
+          end
+
+          # Remove blacklisted elements
+          strip_set = resolved_strip_elements_set(match_opts)
+          set.reject { |e| strip_set.include?(e) }.to_set
+        end
+
+        # Build the Set of collapse whitespace element names (strings).
+        def resolved_collapse_elements_set(match_opts)
+          set = Set.new(format_default_collapse_elements(match_opts).map(&:to_s))
+
+          if match_opts[:collapse_whitespace_elements]
+            set |= match_opts[:collapse_whitespace_elements].map(&:to_s)
+          end
+
+          # Remove blacklisted elements
+          strip_set = resolved_strip_elements_set(match_opts)
+          set.reject { |e| strip_set.include?(e) }.to_set
+        end
+
+        # Build the Set of strip (blacklist) element names (strings).
+        def resolved_strip_elements_set(match_opts)
+          raw = match_opts[:strip_whitespace_elements]
+          Set.new((raw || []).map(&:to_s))
+        end
+
+        # Perform the ancestor walk classification.
+        # The element itself is checked first, then its ancestors.
+        # Strip blacklist wins over any sensitive ancestor.
+        def walk_ancestor_classification(element, preserve_set, collapse_set,
+                                         strip_set, _match_opts)
+          current = element
+          while current.respond_to?(:name)
+            name = current.name.to_s
+
+            return :strip    if strip_set.include?(name)
+            return :preserve if preserve_set.include?(name)
+            return :collapse if collapse_set.include?(name)
+
+            # Walk up
+            break unless current.respond_to?(:parent)
+
+            parent = current.parent
+            break if parent.nil?
+            break unless parent.respond_to?(:name)
+            break if parent == current # guard infinite loop
+
+            current = parent
+          end
+
+          # No matching ancestor — whitespace sensitivity is always opt-in.
+          # Elements not in any list are strip regardless of format.
+          # (HTML_COLLAPSE_ELEMENTS are already merged into the collapse_set
+          #  by resolved_collapse_elements_set, so they are found during the walk.)
+          :strip
+        end
+
         # Check if we should respect xml:space attribute
-        #
-        # @param match_opts [Hash] Resolved match options
-        # @return [Boolean] true if xml:space should be respected
         def respect_xml_space?(match_opts)
           if match_opts.key?(:respect_xml_space)
             match_opts[:respect_xml_space]
@@ -198,13 +288,8 @@ module Canon
         end
 
         # Check if xml:space="preserve" is set
-        #
-        # @param element [Object] The element to check
-        # @return [Boolean] true if xml:space="preserve"
         def xml_space_preserve?(element)
           if element.is_a?(Canon::Xml::Nodes::ElementNode)
-            # Check attribute_nodes for xml:space attribute
-            # xml:space is stored with name="space" and namespace_uri="http://www.w3.org/XML/1998/namespace"
             element.attribute_nodes.any? do |attr|
               attr.name == "space" &&
                 attr.namespace_uri == "http://www.w3.org/XML/1998/namespace" &&
@@ -218,13 +303,8 @@ module Canon
         end
 
         # Check if xml:space="default" is set
-        #
-        # @param element [Object] The element to check
-        # @return [Boolean] true if xml:space="default"
         def xml_space_default?(element)
           if element.is_a?(Canon::Xml::Nodes::ElementNode)
-            # Check attribute_nodes for xml:space attribute
-            # xml:space is stored with name="space" and namespace_uri="http://www.w3.org/XML/1998/namespace"
             element.attribute_nodes.any? do |attr|
               attr.name == "space" &&
                 attr.namespace_uri == "http://www.w3.org/XML/1998/namespace" &&
@@ -237,43 +317,15 @@ module Canon
           end
         end
 
-        # Check sensitivity based on user configuration
-        #
-        # @param element [Object] The element to check
-        # @param match_opts [Hash] Resolved match options
-        # @return [Boolean] true if element is in whitelist
+        # Check sensitivity based on user configuration (binary, no ancestor)
         def user_config_sensitive?(element, match_opts)
-          return false unless match_opts[:whitespace_sensitive_elements]
+          list = match_opts[:preserve_whitespace_elements]
+          return false unless list
 
-          match_opts[:whitespace_sensitive_elements].include?(element.name.to_sym)
-        end
-
-        # Check sensitivity based on user config + format defaults
-        #
-        # @param element [Object] The element to check
-        # @param match_opts [Hash] Resolved match options
-        # @return [Boolean] true if element should be sensitive
-        def configured_sensitive?(element, match_opts)
-          # Start with format defaults
-          sensitive = format_default_sensitive_elements(match_opts).to_set
-
-          # Apply whitelist (adds to defaults)
-          if match_opts[:whitespace_sensitive_elements]
-            sensitive |= match_opts[:whitespace_sensitive_elements]
-          end
-
-          # Apply blacklist (removes from everything)
-          if match_opts[:whitespace_insensitive_elements]
-            sensitive -= match_opts[:whitespace_insensitive_elements]
-          end
-
-          sensitive.include?(element.name.to_sym)
+          list.map(&:to_s).include?(element.name.to_s)
         end
 
         # Check if node has a parent that's an element (not document root)
-        #
-        # @param node [Object] The node to check
-        # @return [Boolean] true if node has an element parent
         def text_node_parent?(node)
           return false unless node.respond_to?(:parent)
           return false unless node.parent

data/lib/canon/comparison/xml_comparator/child_comparison.rb

@@ -28,8 +28,17 @@ module Canon
           # @return [Integer] Comparison result code
           def compare(node1, node2, comparator, opts, child_opts,
 diff_children, differences)
-            children1 = comparator.send(:filter_children, node1.children, opts)
-            children2 = comparator.send(:filter_children, node2.children, opts)
+            # Apply side-specific pretty-print heuristic when either flag is set:
+            # pretty_printed_expected → drop \n-starting whitespace nodes from node1
+            # pretty_printed_received → drop \n-starting whitespace nodes from node2
+            # The ephemeral _pretty_print_side_active flag is consumed by node_excluded?
+            # and must NOT be forwarded into recursive compare_nodes calls.
+            require_relative "../xml_node_comparison"
+            opts1 = XmlNodeComparison.opts_for_side(opts, :expected)
+            opts2 = XmlNodeComparison.opts_for_side(opts, :received)
+
+            children1 = comparator.send(:filter_children, node1.children, opts1)
+            children2 = comparator.send(:filter_children, node2.children, opts2)
 
             # Quick check: if both have no children, they're equivalent
             return Comparison::EQUIVALENT if children1.empty? && children2.empty?
@@ -241,7 +250,12 @@ diff_children, differences)
             end
 
             smaller_set_names = smaller_set.filter_map do |c|
-              c.respond_to?(:name) ? c.name : nil
+              next nil unless c.respond_to?(:name)
+              # Exclude generic node-type names (e.g. "#text") that are
+              # shared by all text nodes and cannot be used for matching.
+              next nil if c.name.start_with?("#")
+
+              c.name
             end
 
             new_larger_set = []
@@ -252,9 +266,12 @@ diff_children, differences)
                 # consider it a mismatch
                 mismatch_children << larger_set[i]
               elsif larger_set[i].respond_to?(:name) &&
+                  !larger_set[i].name.start_with?("#") &&
                   !smaller_set_names.include?(larger_set[i].name)
                 # If the name of the node is not found in the smaller set,
-                # consider it a mismatch
+                # consider it a mismatch. Skip nodes with generic names
+                # starting with "#" (e.g. "#text") since those names are
+                # shared by all nodes of that type and not useful for matching.
                 mismatch_children << larger_set[i]
               else
                 new_larger_set << larger_set[i]

data/lib/canon/comparison/xml_comparator.rb

@@ -417,20 +417,22 @@ module Canon
 
         # Check if whitespace should be preserved strictly for these text nodes
         # This applies to HTML elements like pre, code, textarea, script, style
-        # and elements with xml:space="preserve" or in user-configured whitelist
+        # and elements with xml:space="preserve" or in user-configured preserve list.
+        #
+        # IMPORTANT: This returns true ONLY for :preserve classification.
+        # For :collapse classification, whitespace differences ARE acceptable
+        # (they are detected as formatting-only by DiffClassifier).
         def should_preserve_whitespace_strictly?(n1, n2, opts)
-          # Use WhitespaceSensitivity module to check if element is sensitive
-          # Check both n1 and n2 - if either is in a sensitive element, preserve strictly
-          if n1.respond_to?(:parent)
-            sensitivity_opts = { match_opts: opts[:match_opts] }
-            return true if WhitespaceSensitivity.element_sensitive?(n1,
-                                                                    sensitivity_opts)
-          end
+          # Check both n1 and n2 - if either is in a preserve whitespace element, preserve strictly
+          [n1, n2].each do |node|
+            next unless node.respond_to?(:parent)
+
+            parent = node.parent
+            next unless parent
 
-          if n2.respond_to?(:parent)
-            sensitivity_opts = { match_opts: opts[:match_opts] }
-            return true if WhitespaceSensitivity.element_sensitive?(n2,
-                                                                    sensitivity_opts)
+            classification = WhitespaceSensitivity.classify_element(parent,
+                                                                    opts[:match_opts])
+            return true if classification == :preserve
           end
 
           false

data/lib/canon/comparison/xml_node_comparison.rb

@@ -90,6 +90,39 @@ differences)
         end
       end
 
+      # Build a side-specific opts copy that activates the pretty-print
+      # structural-whitespace heuristic for the given side.
+      #
+      # When +pretty_printed_expected+ (side :expected) or
+      # +pretty_printed_received+ (side :received) is truthy in match_opts,
+      # returns a shallow copy of +opts+ with an ephemeral
+      # +_pretty_print_side_active: true+ flag merged into +:match_opts+.
+      # Otherwise returns +opts+ unchanged (no allocation overhead).
+      #
+      # The flag is consumed by +node_excluded?+ to drop whitespace-only text
+      # nodes that start with "\n" in +:normalize+ whitespace elements.
+      # It is intentionally NOT propagated to recursive +compare_nodes+ calls —
+      # each level of +ChildComparison.compare+ re-evaluates it from the
+      # original +pretty_printed_*+ flags.
+      #
+      # @param opts  [Hash]   Full comparison options hash
+      # @param side  [Symbol] :expected or :received
+      # @return [Hash] opts copy with ephemeral flag, or opts itself
+      def self.opts_for_side(opts, side)
+        match_opts = opts[:match_opts]
+        return opts unless match_opts
+
+        active = case side
+                 when :expected then match_opts[:pretty_printed_expected]
+                 when :received then match_opts[:pretty_printed_received]
+                 else false
+                 end
+
+        return opts unless active
+
+        opts.merge(match_opts: match_opts.merge(_pretty_print_side_active: true))
+      end
+
       # Compare document fragments by comparing their children
       #
       # @param node1 [Nokogiri::XML::DocumentFragment] First fragment
@@ -104,9 +137,12 @@ differences)
         childrenode1 = node1.children.to_a
         childrenode2 = node2.children.to_a
 
-        # Filter children before comparison to handle ignored nodes (like comments with :ignore)
-        children1 = filter_children(childrenode1, opts)
-        children2 = filter_children(childrenode2, opts)
+        # Filter children before comparison to handle ignored nodes (like comments with :ignore).
+        # Apply side-specific pretty-print heuristic when the relevant flag is active.
+        children1 = filter_children(childrenode1,
+                                    opts_for_side(opts, :expected))
+        children2 = filter_children(childrenode2,
+                                    opts_for_side(opts, :received))
 
         if children1.length != children2.length
           add_difference(node1, node2, Comparison::UNEQUAL_ELEMENTS,
@@ -191,8 +227,8 @@ diff_children, differences)
         end
 
         # Strip whitespace-only text nodes based on parent element configuration.
-        # Use sensitive_elements / insensitive_elements to control.
-        # Blacklist (insensitive) > whitelist (sensitive) > format defaults.
+        # Use preserve_whitespace_elements / strip_whitespace_elements to control.
+        # Blacklist (strip) > preserve > collapse > format defaults.
         return false unless text_node?(node) && node.parent
         return false unless MatchOptions.normalize_text(node_text(node)).empty?
 
@@ -200,7 +236,16 @@ diff_children, differences)
           node.parent, match_opts
         )
 
-        false
+        # When the pretty-print-side flag is active (set by opts_for_side in
+        # ChildComparison.compare), drop whitespace-only text nodes that start
+        # with "\n" inside :collapse elements — they are structural indentation
+        # from the pretty-printer, not content.  Space-only nodes (no "\n") are
+        # real inline content and are kept for normalised comparison.
+        # :preserve elements are always left unchanged.
+        if match_opts[:_pretty_print_side_active]
+          ws_class = WhitespaceSensitivity.classify_text_node(node, opts)
+          return true if ws_class == :collapse && node_text(node).start_with?("\n")
+        end
 
         false
       end