canon 0.2.4 → 0.2.6

data/lib/canon/comparison/node_inspector.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    # Single source of truth for cross-backend node type operations.
+    #
+    # The comparison pipeline handles nodes from two backends:
+    # * Canon::Xml::Node (+ RootNode, ElementNode, TextNode, etc.) —
+    #   custom DOM built by SAX builder and DataModel.
+    # * Nokogiri::XML::Node (+ subclasses) — native Nokogiri nodes used
+    #   by the HTML comparator and some legacy paths.
+    #
+    # Every method here dispatches on type via +case/when+ (+is_a?+).
+    # No +respond_to?+ — the types are known at every call site.
+    module NodeInspector
+      CANON_TEXT_TYPE = :text
+      NOKOGIRI_TEXT_TYPE = defined?(Nokogiri::XML::Node::TEXT_NODE) ? Nokogiri::XML::Node::TEXT_NODE : 3
+
+      # True when +node+ is a text node (whitespace, content, etc.).
+      def self.text_node?(node)
+        case node
+        when Canon::Xml::Node
+          node.node_type == CANON_TEXT_TYPE
+        when Nokogiri::XML::Node
+          node.node_type == NOKOGIRI_TEXT_TYPE
+        else
+          false
+        end
+      end
+
+      # Extract the text content of +node+ as a String.
+      def self.text_content(node)
+        case node
+        when Canon::Xml::Node
+          node.value.to_s
+        when Nokogiri::XML::Node
+          node.content.to_s
+        else
+          node.to_s
+        end
+      end
+
+      # True when +node+ is a text node whose content is whitespace-only.
+      # Empty-string text nodes return false — those represent genuine
+      # empty-vs-content asymmetry, not pretty-print indentation.
+      def self.whitespace_only_text?(node)
+        return false unless text_node?(node)
+
+        text = text_content(node)
+        !text.empty? && text.strip.empty?
+      end
+
+      # True when +node+ is a comment node.
+      # For HTML, also detects comments that Nokogiri parses as TEXT nodes
+      # (content like "<!-- comment -->" or escaped "<\\!-- comment -->").
+      def self.comment_node?(node)
+        case node
+        when Canon::Xml::Node
+          node.node_type == :comment
+        when Nokogiri::XML::Node
+          return true if node.comment?
+
+          # HTML comments are parsed as TEXT nodes by Nokogiri
+          if node.text?
+            text_stripped = text_content(node).to_s.strip.gsub("\\", "")
+            return true if text_stripped.start_with?("<!--") && text_stripped.end_with?("-->")
+          end
+          false
+        else
+          false
+        end
+      end
+
+      # True when +node+ is an element node.
+      def self.element_node?(node)
+        case node
+        when Canon::Xml::Node
+          node.node_type == :element
+        when Nokogiri::XML::Node
+          node.element?
+        else
+          false
+        end
+      end
+
+      # Extract parse-time errors carried on a node or its owning document.
+      # Returns an Array of Strings.
+      def self.parse_errors(node)
+        case node
+        when nil
+          []
+        when Canon::Xml::Node
+          errors = node.parse_errors
+          Array(errors).map(&:to_s)
+        when Nokogiri::XML::Document, Nokogiri::HTML5::Document
+          Array(node.errors).map(&:to_s)
+        else
+          []
+        end
+      end
+    end
+  end
+end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../node_inspector"
+
 module Canon
   module Comparison
     module XmlComparatorHelpers
@@ -27,7 +29,7 @@ module Canon
           # @param differences [Array] Array to collect differences
           # @return [Integer] Comparison result code
           def compare(node1, node2, comparator, opts, child_opts,
-diff_children, differences)
+                      diff_children, differences)
             # FAST PATH: Object identity - same object means equivalent children
             return Comparison::EQUIVALENT if node1.equal?(node2)
 
@@ -40,8 +42,8 @@ diff_children, differences)
             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)
+            children1 = comparator.filter_children(node1.children, opts1)
+            children2 = comparator.filter_children(node2.children, opts2)
 
             # Quick check: if both have no children, they're equivalent
             return Comparison::EQUIVALENT if children1.empty? && children2.empty?
@@ -97,9 +99,9 @@ diff_children, differences)
 
             # If no matches and children exist, they're all different
             if matches.empty? && (!children1.empty? || !children2.empty?)
-              comparator.send(:add_difference, parent_node, parent_node,
-                              Comparison::MISSING_NODE, Comparison::MISSING_NODE,
-                              :text_content, opts, differences)
+              comparator.add_difference(parent_node, parent_node,
+                                        Comparison::MISSING_NODE, Comparison::MISSING_NODE,
+                                        :text_content, opts, differences)
               return Comparison::UNEQUAL_ELEMENTS
             end
 
@@ -122,30 +124,30 @@ diff_children, differences)
 
                   # Only create DiffNode if element_position is not :ignore
                   if position_behavior != :ignore
-                    comparator.send(:add_difference, match.elem1, match.elem2,
-                                    "position #{match.pos1}", "position #{match.pos2}",
-                                    :element_position, opts, differences)
+                    comparator.add_difference(match.elem1, match.elem2,
+                                              "position #{match.pos1}", "position #{match.pos2}",
+                                              :element_position, opts, differences)
                     all_equivalent = false if position_behavior == :strict
                   end
                 end
 
                 # Compare the matched elements for content/attribute differences
-                result = comparator.send(:compare_nodes, match.elem1, match.elem2,
-                                         child_opts, child_opts, diff_children, differences)
+                result = comparator.compare_nodes(match.elem1, match.elem2,
+                                                  child_opts, child_opts, diff_children, differences)
                 all_equivalent = false unless result == Comparison::EQUIVALENT
 
               when :deleted
                 # Element present in first tree but not second
-                comparator.send(:add_difference, match.elem1, nil,
-                                Comparison::MISSING_NODE, Comparison::MISSING_NODE,
-                                :element_structure, opts, differences)
+                comparator.add_difference(match.elem1, nil,
+                                          Comparison::MISSING_NODE, Comparison::MISSING_NODE,
+                                          :element_structure, opts, differences)
                 all_equivalent = false
 
               when :inserted
                 # Element present in second tree but not first
-                comparator.send(:add_difference, nil, match.elem2,
-                                Comparison::MISSING_NODE, Comparison::MISSING_NODE,
-                                :element_structure, opts, differences)
+                comparator.add_difference(nil, match.elem2,
+                                          Comparison::MISSING_NODE, Comparison::MISSING_NODE,
+                                          :element_structure, opts, differences)
                 all_equivalent = false
               end
             end
@@ -153,9 +155,16 @@ diff_children, differences)
             all_equivalent ? Comparison::EQUIVALENT : Comparison::UNEQUAL_ELEMENTS
           end
 
-          # Use simple positional comparison for children
+          # Use simple positional comparison for children, with
+          # whitespace-asymmetry-aware re-alignment.  When positional
+          # +zip()+ would pair a whitespace-only text node on one side
+          # against a content node on the other, treat the whitespace
+          # node as a single-side gap: emit one +:whitespace_adjacency+
+          # diff anchored at the whitespace node and advance only the
+          # cursor carrying the whitespace, so the next iteration aligns
+          # content against content.  See lutaml/canon#137.
           def use_positional_comparison(
-            children1, children2, _parent_node, comparator,
+            children1, children2, parent_node, comparator,
             opts, child_opts, diff_children, differences
           )
             has_mismatch = false
@@ -163,53 +172,120 @@ diff_children, differences)
             # Length check
             unless children1.length == children2.length
               has_mismatch = true
-              dimension = determine_dimension_for_mismatch(
-                children1, children2, comparator
+
+              ws_asymmetric = asymmetric_whitespace_explains_length_diff?(
+                children1, children2
               )
 
-              mismatched_children, children1, children2 =
-                determine_mismatch_children(
+              if ws_asymmetric
+                dimension = nil
+                mismatched_children = []
+              else
+                dimension = determine_dimension_for_mismatch(
                   children1, children2, comparator
                 )
+                mismatched_children, children1, children2 =
+                  determine_mismatch_children(
+                    children1, children2, comparator
+                  )
+              end
 
               if mismatched_children.empty?
-                comparator.send(:add_difference, parent_node, parent_node,
-                                Comparison::MISSING_NODE, Comparison::MISSING_NODE,
-                                dimension, opts, differences)
+                unless ws_asymmetric
+                  comparator.add_difference(parent_node, parent_node,
+                                            Comparison::MISSING_NODE, Comparison::MISSING_NODE,
+                                            dimension, opts, differences)
+                end
               else
                 mismatched_children.each do |child|
-                  if children1.length > children2.length # rubocop:disable Metrics/BlockNesting
-                    comparator.send(:add_difference, child, nil,
-                                    Comparison::MISSING_NODE, Comparison::MISSING_NODE,
-                                    dimension, opts, differences)
+                  child_dim = comparator.determine_node_dimension(child)
+                  if children1.length > children2.length
+                    comparator.add_difference(child, nil,
+                                              Comparison::MISSING_NODE,
+                                              Comparison::MISSING_NODE,
+                                              child_dim, opts, differences)
                   else
-                    comparator.send(:add_difference, nil, child,
-                                    Comparison::MISSING_NODE, Comparison::MISSING_NODE,
-                                    dimension, opts, differences)
+                    comparator.add_difference(nil, child,
+                                              Comparison::MISSING_NODE,
+                                              Comparison::MISSING_NODE,
+                                              child_dim, opts, differences)
                   end
                 end
               end
-              # Continue comparing children to find deeper differences like attribute values
-              # Use zip to compare up to the shorter length
             end
 
-            # Compare children pairwise by position
             result = has_mismatch ? Comparison::UNEQUAL_ELEMENTS : Comparison::EQUIVALENT
-            children1.zip(children2).each do |child1, child2|
-              # Skip if one is nil (due to different lengths)
-              next if child1.nil? || child2.nil?
+            walk_result = walk_children_with_realignment(
+              children1, children2, comparator,
+              child_opts, diff_children, opts, differences
+            )
+            result = walk_result unless walk_result == Comparison::EQUIVALENT
+            result
+          end
 
-              child_result = comparator.send(:compare_nodes, child1, child2,
-                                             child_opts, child_opts, diff_children, differences)
+          # Two-cursor walk over paired children that re-aligns past
+          # asymmetric whitespace-only text nodes.  Returns the worst
+          # child result encountered.
+          def walk_children_with_realignment(
+            children1, children2, comparator,
+            child_opts, diff_children, opts, differences
+          )
+            result = Comparison::EQUIVALENT
+            i = 0
+            j = 0
+
+            while i < children1.length || j < children2.length
+              c1 = children1[i]
+              c2 = children2[j]
+
+              if c1.nil?
+                j += 1
+                next
+              elsif c2.nil?
+                i += 1
+                next
+              end
 
-              unless child_result == Comparison::EQUIVALENT
-                result = child_result
+              ws1 = NodeInspector.whitespace_only_text?(c1)
+              ws2 = NodeInspector.whitespace_only_text?(c2)
+
+              if ws1 && !ws2
+                comparator.add_difference(c1, c2,
+                                          Comparison::UNEQUAL_TEXT_CONTENTS,
+                                          Comparison::UNEQUAL_TEXT_CONTENTS,
+                                          :whitespace_adjacency, opts, differences)
+                result = Comparison::UNEQUAL_TEXT_CONTENTS
+                i += 1
+                next
+              elsif ws2 && !ws1
+                comparator.add_difference(c1, c2,
+                                          Comparison::UNEQUAL_TEXT_CONTENTS,
+                                          Comparison::UNEQUAL_TEXT_CONTENTS,
+                                          :whitespace_adjacency, opts, differences)
+                result = Comparison::UNEQUAL_TEXT_CONTENTS
+                j += 1
+                next
               end
+
+              child_result = comparator.compare_nodes(c1, c2,
+                                                      child_opts, child_opts,
+                                                      diff_children, differences)
+              result = child_result unless child_result == Comparison::EQUIVALENT
+              i += 1
+              j += 1
             end
 
             result
           end
 
+          # True when the length difference between the two child arrays
+          # is fully explained by asymmetric whitespace-only text nodes.
+          def asymmetric_whitespace_explains_length_diff?(children1, children2)
+            non_ws1 = children1.reject { |c| NodeInspector.whitespace_only_text?(c) }
+            non_ws2 = children2.reject { |c| NodeInspector.whitespace_only_text?(c) }
+            non_ws1.length == non_ws2.length
+          end
+
           # Determine dimension for length mismatch
           def determine_dimension_for_mismatch(children1, children2, comparator)
             dimension = :text_content # default
@@ -219,22 +295,17 @@ diff_children, differences)
             (0...max_len).each do |i|
               if i >= children1.length
                 # Extra child in children2
-                dimension = comparator.send(:determine_node_dimension,
-                                            children2[i])
+                dimension = comparator.determine_node_dimension(children2[i])
                 break
               elsif i >= children2.length
                 # Extra child in children1
-                dimension = comparator.send(:determine_node_dimension,
-                                            children1[i])
+                dimension = comparator.determine_node_dimension(children1[i])
                 break
-              elsif !comparator.send(:same_node_type?, children1[i],
-                                     children2[i])
+              elsif !comparator.same_node_type?(children1[i], children2[i])
                 # Different node types at same position
                 # Check both nodes - if either is a comment, use :comments dimension
-                dim1 = comparator.send(:determine_node_dimension,
-                                       children1[i])
-                dim2 = comparator.send(:determine_node_dimension,
-                                       children2[i])
+                dim1 = comparator.determine_node_dimension(children1[i])
+                dim2 = comparator.determine_node_dimension(children2[i])
                 dimension = [dim1, dim2].include?(:comments) ? :comments : dim1
                 break
               end
@@ -256,7 +327,7 @@ diff_children, differences)
             end
 
             smaller_set_names = smaller_set.filter_map do |c|
-              next nil unless c.respond_to?(:name)
+              next nil unless c.is_a?(Canon::Xml::Node) || c.is_a?(Nokogiri::XML::Node)
               # 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?("#")
@@ -271,7 +342,8 @@ diff_children, differences)
                 # If the smaller set has no child at this position,
                 # consider it a mismatch
                 mismatch_children << larger_set[i]
-              elsif larger_set[i].respond_to?(:name) &&
+              elsif (larger_set[i].is_a?(Canon::Xml::Node) ||
+                     larger_set[i].is_a?(Nokogiri::XML::Node)) &&
                   !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,

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

@@ -4,6 +4,7 @@ require "set"
 require_relative "../../diff/diff_node"
 require_relative "../../diff/path_builder"
 require_relative "../../diff/node_serializer"
+require_relative "../node_inspector"
 
 module Canon
   module Comparison
@@ -52,14 +53,15 @@ module Canon
         # For deleted/inserted nodes, include namespace information if available
         if dimension == :text_content && (node1.nil? || node2.nil?)
           node = node1 || node2
-          if node.respond_to?(:name) && node.respond_to?(:namespace_uri)
+          if node.is_a?(Canon::Xml::Node) || node.is_a?(Nokogiri::XML::Node)
             ns = node.namespace_uri
             ns_info = if ns.nil? || ns.empty?
                         ""
                       else
                         " (namespace: #{ns})"
                       end
-            return "element '#{node.name}'#{ns_info}: #{diff1} vs #{diff2}"
+            label = Canon::Comparison.code_pair_label(diff1, diff2)
+            return "element '#{node.name}'#{ns_info}: #{label}"
           end
         end
 
@@ -87,8 +89,15 @@ module Canon
         # Default reason
         if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
           "element structure mismatch (children differ)"
+        elsif dimension == :element_structure &&
+            diff1 == Canon::Comparison::UNEQUAL_ELEMENTS &&
+            diff2 == Canon::Comparison::UNEQUAL_ELEMENTS &&
+            (node1.is_a?(Canon::Xml::Node) || node1.is_a?(Nokogiri::XML::Node)) &&
+            (node2.is_a?(Canon::Xml::Node) || node2.is_a?(Nokogiri::XML::Node)) &&
+            node1.name && node2.name && node1.name != node2.name
+          "different element name (<#{node1.name}> vs <#{node2.name}>)"
         else
-          "#{diff1} vs #{diff2}"
+          Canon::Comparison.code_pair_label(diff1, diff2)
         end
       end
 
@@ -176,26 +185,18 @@ module Canon
       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
+        case node
+        when Canon::Xml::Nodes::TextNode
+          node.value
+        when Canon::Xml::Node
+          node.text_content
+        when Nokogiri::XML::Node
+          node.content.to_s
+        when String
+          node
+        else
+          node.to_s
+        end
       rescue StandardError
         nil
       end

data/lib/canon/comparison/xml_comparator.rb

@@ -160,6 +160,8 @@ module Canon
               format: :xml,
               match_options: match_opts_hash,
               algorithm: :dom,
+              parse_errors_expected: Comparison.parse_errors_for(node1),
+              parse_errors_received: Comparison.parse_errors_for(node2),
             )
           elsif result != Comparison::EQUIVALENT && !differences.empty?
             # Non-verbose mode: check equivalence
@@ -222,6 +224,8 @@ module Canon
               format: :xml,
               match_options: match_opts_hash.merge(strategy.metadata),
               algorithm: :semantic,
+              parse_errors_expected: Comparison.parse_errors_for(node1),
+              parse_errors_received: Comparison.parse_errors_for(node2),
             )
           else
             # Simple boolean result - equivalent if no normative differences
@@ -283,6 +287,8 @@ module Canon
           )
         end
 
+        public
+
         # Main comparison dispatcher
         def compare_nodes(n1, n2, opts, child_opts, diff_children, differences)
           # FAST PATH: Object identity - same object is always equivalent
@@ -373,7 +379,6 @@ module Canon
         end
 
         # Public comparison methods - exposed for XmlNodeComparison module
-        public
 
         # Compare two element nodes
         def compare_element_nodes(n1, n2, opts, child_opts, diff_children,
@@ -667,7 +672,8 @@ differences)
                         else
                           " (namespace: #{ns})"
                         end
-              return "element '#{node.name}'#{ns_info}: #{diff1} vs #{diff2}"
+              label = Canon::Comparison.code_pair_label(diff1, diff2)
+              return "element '#{node.name}'#{ns_info}: #{label}"
             elsif node.respond_to?(:name) && !node.respond_to?(:namespace_uri)
               # TextNode and other nodes without namespace_uri
               display = if node.respond_to?(:value) && node.node_type == :text
@@ -693,6 +699,10 @@ differences)
             return build_text_diff_reason(text1, text2)
           end
 
+          if dimension == :whitespace_adjacency
+            return build_whitespace_adjacency_reason(node1, node2)
+          end
+
           # For attribute values differences, show the actual values
           if dimension == :attribute_values
             attrs1 = extract_attributes(node1)
@@ -709,8 +719,17 @@ differences)
 
           if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
             "element structure mismatch (children differ)"
+          elsif dimension == :element_structure &&
+              diff1 == Canon::Comparison::UNEQUAL_ELEMENTS &&
+              diff2 == Canon::Comparison::UNEQUAL_ELEMENTS &&
+              (node1.is_a?(Canon::Xml::Node) || node1.is_a?(Nokogiri::XML::Node)) &&
+              (node2.is_a?(Canon::Xml::Node) || node2.is_a?(Nokogiri::XML::Node)) &&
+              node1.name && node2.name && node1.name != node2.name
+            # Most common case: differing element names.  Surface the
+            # actual names rather than a generic "elements differ".
+            "different element name (<#{node1.name}> vs <#{node2.name}>)"
           else
-            "#{diff1} vs #{diff2}"
+            Canon::Comparison.code_pair_label(diff1, diff2)
           end
         end
 
@@ -824,6 +843,81 @@ differences)
           "Text: \"#{vis1}\" vs \"#{vis2}\""
         end
 
+        # Build a Reason line for a +:whitespace_adjacency+ diff (#137).
+        # Names which side carries the whitespace, the adjacency position
+        # relative to content neighbours, and surfaces the whitespace
+        # with visible markers.
+        def build_whitespace_adjacency_reason(node1, node2)
+          text1 = extract_text_from_node(node1)
+          text2 = extract_text_from_node(node2)
+
+          ni = NodeInspector
+          ws_on_first = ni.whitespace_only_text?(node1) &&
+            !ni.whitespace_only_text?(node2)
+          ws_on_second = ni.whitespace_only_text?(node2) &&
+            !ni.whitespace_only_text?(node1)
+
+          if ws_on_first
+            ws_text = text1
+            content_text = text2
+            present_side = "EXPECTED"
+            absent_side = "ACTUAL"
+            ws_node = node1
+          elsif ws_on_second
+            ws_text = text2
+            content_text = text1
+            present_side = "ACTUAL"
+            absent_side = "EXPECTED"
+            ws_node = node2
+          else
+            return build_text_diff_reason(text1, text2)
+          end
+
+          direction = whitespace_partner_direction(ws_node)
+          ws_vis = visualize_whitespace(ws_text)
+          content_vis = content_text ? visualize_whitespace(truncate_text(content_text)) : "(none)"
+
+          "Whitespace #{direction} \"#{content_vis}\": " \
+            "present on #{present_side} (\"#{ws_vis}\"), absent on #{absent_side}"
+        end
+
+        # Direction of the partner content relative to the whitespace node,
+        # phrased from the partner's point of view: "before" when the
+        # whitespace immediately precedes its next non-whitespace sibling
+        # (the alignment partner on the other side), "after" when the
+        # whitespace trails the previous non-whitespace sibling, or
+        # "adjacent to" as a degenerate fallback when neither neighbour
+        # exists.
+        def whitespace_partner_direction(ws_node)
+          return "adjacent to" unless ws_node.is_a?(Canon::Xml::Node) ||
+            ws_node.is_a?(Nokogiri::XML::Node)
+
+          parent = ws_node.parent
+          return "adjacent to" if parent.nil?
+
+          siblings = parent.children
+          idx = siblings.index(ws_node)
+          return "adjacent to" unless idx
+
+          if non_ws_sibling_exists?(siblings, idx, 1) then "before"
+          elsif non_ws_sibling_exists?(siblings, idx, -1) then "after"
+          else "adjacent to"
+          end
+        end
+
+        def non_ws_sibling_exists?(siblings, idx, direction)
+          i = idx + direction
+          while i >= 0 && i < siblings.length
+            s = siblings[i]
+            is_ws_text = NodeInspector.text_node?(s) &&
+              NodeInspector.text_content(s).strip.empty?
+            return true unless is_ws_text
+
+            i += direction
+          end
+          false
+        end
+
         # Check if text is only whitespace
         #
         # @param text [String] Text to check