canon 0.1.8 → 0.1.10

data/lib/canon/comparison/whitespace_sensitivity.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+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)
+    #
+    # == 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
+    #
+    # == Usage
+    #
+    #   WhitespaceSensitivity.element_sensitive?(node, opts)
+    #   => true if whitespace should be preserved for this element
+    module WhitespaceSensitivity
+      class << self
+        # Check if an element is whitespace-sensitive based on configuration
+        #
+        # @param node [Object] The element node to check
+        # @param opts [Hash] Comparison options containing match_opts
+        # @return [Boolean] true if whitespace should be preserved for this element
+        def element_sensitive?(node, opts)
+          match_opts = opts[:match_opts]
+          return false unless match_opts
+          return false unless text_node_parent?(node)
+
+          parent = node.parent
+
+          # 1. Check if we should ignore xml:space (user override)
+          if !respect_xml_space?(match_opts)
+            return user_config_sensitive?(parent, match_opts)
+          end
+
+          # 2. Check xml:space="preserve" (document declaration)
+          return true if xml_space_preserve?(parent)
+
+          # 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)
+        end
+
+        # Check if whitespace-only text node should be filtered
+        #
+        # @param node [Object] The text node to check
+        # @param opts [Hash] Comparison options
+        # @return [Boolean] true if node should be preserved (not filtered)
+        def preserve_whitespace_node?(node, opts)
+          return false unless node.respond_to?(:parent)
+          return false unless node.parent
+
+          element_sensitive?(node, opts)
+        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.
+        #
+        # @param match_opts [Hash] Resolved match options
+        # @return [Array<Symbol>] Default sensitive element names
+        def format_default_sensitive_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
+          else
+            [].freeze
+          end
+        end
+
+        # 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)
+            .include?(element_name.to_sym)
+        end
+
+        private
+
+        # 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]
+          else
+            true
+          end
+        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" &&
+                attr.value == "preserve"
+            end
+          elsif element.respond_to?(:[])
+            element["xml:space"] == "preserve"
+          else
+            false
+          end
+        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" &&
+                attr.value == "default"
+            end
+          elsif element.respond_to?(:[])
+            element["xml:space"] == "default"
+          else
+            false
+          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
+        def user_config_sensitive?(element, match_opts)
+          return false unless match_opts[:whitespace_sensitive_elements]
+
+          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)
+        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
+
+          parent = node.parent
+          return true if parent.respond_to?(:element?) && parent.element?
+
+          # Nokogiri compatibility
+          parent.respond_to?(:node_type) && parent.node_type == :element
+        end
+      end
+    end
+  end
+end

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

@@ -26,7 +26,8 @@ module Canon
           # @param diff_children [Boolean] Whether to diff children
           # @param differences [Array] Array to collect differences
           # @return [Integer] Comparison result code
-          def compare(node1, node2, comparator, opts, child_opts, diff_children, differences)
+          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)
 
@@ -51,7 +52,9 @@ module Canon
           # method that returns symbols, and only works with element nodes.
           def can_use_element_matcher?(children1, children2)
             !children1.empty? && !children2.empty? &&
-              children1.all? { |c| c.is_a?(Canon::Xml::Node) && c.node_type == :element } &&
+              children1.all? do |c|
+                c.is_a?(Canon::Xml::Node) && c.node_type == :element
+              end &&
               children2.all? { |c| c.is_a?(Canon::Xml::Node) && c.node_type == :element }
           end
 
@@ -140,7 +143,8 @@ module Canon
                                         opts, child_opts, diff_children, differences)
             # Length check
             unless children1.length == children2.length
-              dimension = determine_dimension_for_mismatch(children1, children2, comparator)
+              dimension = determine_dimension_for_mismatch(children1,
+                                                           children2, comparator)
               comparator.send(:add_difference, parent_node, parent_node,
                               Comparison::MISSING_NODE, Comparison::MISSING_NODE,
                               dimension, opts, differences)
@@ -167,15 +171,19 @@ module Canon
             (0...max_len).each do |i|
               if i >= children1.length
                 # Extra child in children2
-                dimension = comparator.send(:determine_node_dimension, children2[i])
+                dimension = comparator.send(:determine_node_dimension,
+                                            children2[i])
                 break
               elsif i >= children2.length
                 # Extra child in children1
-                dimension = comparator.send(:determine_node_dimension, children1[i])
+                dimension = comparator.send(:determine_node_dimension,
+                                            children1[i])
                 break
-              elsif !comparator.send(:same_node_type?, children1[i], children2[i])
+              elsif !comparator.send(:same_node_type?, children1[i],
+                                     children2[i])
                 # Different node types at same position
-                dimension = comparator.send(:determine_node_dimension, children1[i])
+                dimension = comparator.send(:determine_node_dimension,
+                                            children1[i])
                 break
               end
             end

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "set"
 require_relative "../../diff/diff_node"
 require_relative "../../diff/path_builder"
 require_relative "../../diff/node_serializer"
@@ -62,6 +63,21 @@ module Canon
           end
         end
 
+        # For attribute presence differences, show what attributes differ
+        if dimension == :attribute_presence
+          attrs1 = extract_attributes(node1)
+          attrs2 = extract_attributes(node2)
+          return build_attribute_difference_reason(attrs1, attrs2)
+        end
+
+        # For text content differences, show the actual text (truncated if needed)
+        if dimension == :text_content
+          text1 = extract_text_content(node1)
+          text2 = extract_text_content(node2)
+          return build_text_difference_reason(text1, text2)
+        end
+
+        # Default reason
         "#{diff1} vs #{diff2}"
       end
 
@@ -110,6 +126,98 @@ module Canon
 
         Canon::Diff::NodeSerializer.extract_attributes(node)
       end
+
+      # Build a clear reason message for attribute presence differences
+      # Shows which attributes are only in node1, only in node2, or different values
+      #
+      # @param attrs1 [Hash, nil] First node's attributes
+      # @param attrs2 [Hash, nil] Second node's attributes
+      # @return [String] Clear explanation of the attribute difference
+      def self.build_attribute_difference_reason(attrs1, attrs2)
+        return "#{attrs1&.keys&.size || 0} vs #{attrs2&.keys&.size || 0} attributes" unless attrs1 && attrs2
+
+        keys1 = attrs1.keys.to_set
+        keys2 = attrs2.keys.to_set
+
+        only_in_1 = keys1 - keys2
+        only_in_2 = keys2 - keys1
+        common = keys1 & keys2
+
+        # Check if values differ for common keys
+        different_values = common.reject { |k| attrs1[k] == attrs2[k] }
+
+        parts = []
+        parts << "only in first: #{only_in_1.to_a.sort.join(', ')}" if only_in_1.any?
+        parts << "only in second: #{only_in_2.to_a.sort.join(', ')}" if only_in_2.any?
+        parts << "different values: #{different_values.sort.join(', ')}" if different_values.any?
+
+        if parts.empty?
+          "#{keys1.size} vs #{keys2.size} attributes (same names)"
+        else
+          parts.join("; ")
+        end
+      end
+
+      # Extract text content from a node
+      #
+      # @param node [Object, nil] Node to extract text from
+      # @return [String, nil] Text content or nil
+      def self.extract_text_content(node)
+        return nil if node.nil?
+
+        # For Canon::Xml::Nodes::TextNode
+        return node.value if node.respond_to?(:value) && node.is_a?(Canon::Xml::Nodes::TextNode)
+
+        # For XML/HTML nodes with text_content method
+        return node.text_content if node.respond_to?(:text_content)
+
+        # For nodes with text method
+        return node.text if node.respond_to?(:text)
+
+        # For nodes with content method (Moxml::Text)
+        return node.content if node.respond_to?(:content)
+
+        # For nodes with value method (other types)
+        return node.value if node.respond_to?(:value)
+
+        # For simple text nodes or strings
+        return node.to_s if node.is_a?(String)
+
+        # For other node types, try to_s
+        node.to_s
+      rescue StandardError
+        nil
+      end
+
+      # Build a clear reason message for text content differences
+      # Shows the actual text content (truncated if too long)
+      #
+      # @param text1 [String, nil] First text content
+      # @param text2 [String, nil] Second text content
+      # @return [String] Clear explanation of the text difference
+      def self.build_text_difference_reason(text1, text2)
+        # Handle nil cases
+        return "missing vs '#{truncate(text2)}'" if text1.nil? && text2
+        return "'#{truncate(text1)}' vs missing" if text1 && text2.nil?
+        return "both missing" if text1.nil? && text2.nil?
+
+        # Both have content - show truncated versions
+        "'#{truncate(text1)}' vs '#{truncate(text2)}'"
+      end
+
+      # Truncate text for display in reason messages
+      #
+      # @param text [String] Text to truncate
+      # @param max_length [Integer] Maximum length
+      # @return [String] Truncated text
+      def self.truncate(text, max_length = 40)
+        return "" if text.nil?
+
+        text = text.to_s
+        return text if text.length <= max_length
+
+        "#{text[0...max_length]}..."
+      end
     end
   end
 end

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

@@ -13,21 +13,24 @@ module Canon
         #
         # @param node [String, Object] Node to parse
         # @param preprocessing [Symbol] Preprocessing mode (:none, :normalize, :c14n, :format)
+        # @param preserve_whitespace [Boolean] Whether to preserve whitespace-only text nodes
         # @return [Canon::Xml::Node] Parsed node
-        def self.parse(node, preprocessing = :none)
+        def self.parse(node, preprocessing = :none, preserve_whitespace: false)
           # If already a Canon::Xml::Node, return as-is
           return node if node.is_a?(Canon::Xml::Node)
 
           # If it's a Nokogiri or Moxml node, convert to DataModel
           unless node.is_a?(String)
-            return convert_from_node(node)
+            return convert_from_node(node,
+                                     preserve_whitespace: preserve_whitespace)
           end
 
           # Apply preprocessing to XML string before parsing
           xml_string = apply_preprocessing(node, preprocessing)
 
           # Use Canon::Xml::DataModel for parsing to get Canon::Xml::Node instances
-          Canon::Xml::DataModel.from_xml(xml_string)
+          Canon::Xml::DataModel.from_xml(xml_string,
+                                         preserve_whitespace: preserve_whitespace)
         end
 
         # Apply preprocessing transformation to XML string
@@ -55,8 +58,9 @@ module Canon
         # Convert from Nokogiri/Moxml node to Canon::Xml::Node
         #
         # @param node [Object] Nokogiri or Moxml node
+        # @param preserve_whitespace [Boolean] Whether to preserve whitespace-only text nodes
         # @return [Canon::Xml::Node] Converted node
-        def self.convert_from_node(node)
+        def self.convert_from_node(node, preserve_whitespace: false)
           # Convert to XML string then parse through DataModel
           xml_str = if node.respond_to?(:to_xml)
                       node.to_xml
@@ -66,7 +70,8 @@ module Canon
                       raise Canon::Error,
                             "Unable to convert node to string: #{node.class}"
                     end
-          Canon::Xml::DataModel.from_xml(xml_str)
+          Canon::Xml::DataModel.from_xml(xml_str,
+                                         preserve_whitespace: preserve_whitespace)
         end
       end
     end

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

@@ -23,7 +23,8 @@ module Canon
           # @param diff_children [Boolean] Whether to diff children
           # @param differences [Array] Array to collect differences
           # @return [Integer] Comparison result code
-          def compare(node1, node2, comparator, opts, child_opts, diff_children, differences)
+          def compare(node1, node2, comparator, opts, child_opts,
+diff_children, differences)
             # Dispatch based on node type
             # Canon::Xml::Node types use .node_type method that returns symbols
             # Nokogiri also has .node_type but returns integers, so check for Symbol
@@ -51,11 +52,14 @@ module Canon
               comparator.send(:compare_element_nodes, node1, node2, opts, child_opts,
                               diff_children, differences)
             when :text
-              comparator.send(:compare_text_nodes, node1, node2, opts, differences)
+              comparator.send(:compare_text_nodes, node1, node2, opts,
+                              differences)
             when :comment
-              comparator.send(:compare_comment_nodes, node1, node2, opts, differences)
+              comparator.send(:compare_comment_nodes, node1, node2, opts,
+                              differences)
             when :cdata
-              comparator.send(:compare_text_nodes, node1, node2, opts, differences)
+              comparator.send(:compare_text_nodes, node1, node2, opts,
+                              differences)
             when :processing_instruction
               comparator.send(:compare_processing_instruction_nodes, node1, node2, opts,
                               differences)
@@ -71,11 +75,14 @@ module Canon
               comparator.send(:compare_element_nodes, node1, node2, opts, child_opts,
                               diff_children, differences)
             elsif node1.respond_to?(:text?) && node1.text?
-              comparator.send(:compare_text_nodes, node1, node2, opts, differences)
+              comparator.send(:compare_text_nodes, node1, node2, opts,
+                              differences)
             elsif node1.respond_to?(:comment?) && node1.comment?
-              comparator.send(:compare_comment_nodes, node1, node2, opts, differences)
+              comparator.send(:compare_comment_nodes, node1, node2, opts,
+                              differences)
             elsif node1.respond_to?(:cdata?) && node1.cdata?
-              comparator.send(:compare_text_nodes, node1, node2, opts, differences)
+              comparator.send(:compare_text_nodes, node1, node2, opts,
+                              differences)
             elsif node1.respond_to?(:processing_instruction?) &&
                 node1.processing_instruction?
               comparator.send(:compare_processing_instruction_nodes, node1, node2, opts,