canon 0.2.7 → 0.2.9

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

@@ -53,7 +53,7 @@ module Canon
         # For deleted/inserted nodes, include namespace information if available
         if dimension == :text_content && (node1.nil? || node2.nil?)
           node = node1 || node2
-          if node.is_a?(Canon::Xml::Node) || node.is_a?(Nokogiri::XML::Node)
+          if node.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(node)
             ns = node.namespace_uri
             ns_info = if ns.nil? || ns.empty?
                         ""
@@ -86,14 +86,22 @@ module Canon
           return "Attribute order changed: [#{attrs1.join(', ')}] → [#{attrs2.join(', ')}]"
         end
 
+        # For asymmetric comment nodes (#144), name the side that carries
+        # the comment and surface the comment text rather than reusing
+        # the generic "element structure mismatch" wording.
+        if dimension == :comments
+          comment_reason = build_comment_difference_reason(node1, node2)
+          return comment_reason if comment_reason
+        end
+
         # 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.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(node1)) &&
+            (node2.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(node2)) &&
             node1.name && node2.name && node1.name != node2.name
           "different element name (<#{node1.name}> vs <#{node2.name}>)"
         else
@@ -190,12 +198,14 @@ module Canon
           node.value
         when Canon::Xml::Node
           node.text_content
-        when Nokogiri::XML::Node
-          node.content.to_s
-        when String
-          node
         else
-          node.to_s
+          if Canon::XmlBackend.nokogiri? && node.is_a?(Nokogiri::XML::Node)
+            node.content.to_s
+          elsif Canon::XmlParsing.xml_node?(node)
+            Canon::XmlParsing.text_content(node)
+          else
+            node.to_s
+          end
         end
       rescue StandardError
         nil
@@ -217,6 +227,31 @@ module Canon
         "'#{truncate(text1)}' vs '#{truncate(text2)}'"
       end
 
+      # Build a Reason line for a +:comments+ diff. Returns +nil+ when
+      # neither side carries a comment (caller falls back to default).
+      def self.build_comment_difference_reason(node1, node2)
+        cm1 = node1 && Canon::Comparison::NodeInspector.comment_node?(node1)
+        cm2 = node2 && Canon::Comparison::NodeInspector.comment_node?(node2)
+
+        return nil unless cm1 || cm2
+
+        if cm1 && !cm2
+          "Comment present on EXPECTED only: " \
+            "<!--#{truncate(comment_text(node1))}-->"
+        elsif cm2 && !cm1
+          "Comment present on ACTUAL only: " \
+            "<!--#{truncate(comment_text(node2))}-->"
+        else
+          t1 = truncate(comment_text(node1))
+          t2 = truncate(comment_text(node2))
+          "Comment text differs: <!--#{t1}--> vs <!--#{t2}-->"
+        end
+      end
+
+      def self.comment_text(node)
+        Canon::Comparison::NodeInspector.text_content(node).to_s
+      end
+
       # Truncate text for display in reason messages
       #
       # @param text [String] Text to truncate

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../xml/namespace_helper"
+
 module Canon
   module Comparison
     module XmlComparatorHelpers
@@ -41,20 +43,20 @@ module Canon
         def self.extract_declarations(node)
           declarations = {}
 
-          # Handle Canon::Xml::Node (uses namespace_nodes)
-          if node.respond_to?(:namespace_nodes)
-            return extract_from_namespace_nodes(node.namespace_nodes,
-                                                declarations)
-          end
+          if node.is_a?(Canon::Xml::Node)
+            if node.namespace_nodes
+              return extract_from_namespace_nodes(node.namespace_nodes,
+                                                  declarations)
+            end
 
-          # Handle Nokogiri/Moxml nodes (use attributes)
-          raw_attrs = node.respond_to?(:attribute_nodes) ? node.attribute_nodes : node.attributes
+            raw_attrs = node.attribute_nodes
+          else
+            raw_attrs = node.attributes
+          end
 
-          # Handle Canon::Xml::Node attribute format (array of AttributeNode)
           if raw_attrs.is_a?(Array)
             extract_from_array_attributes(raw_attrs, declarations)
           else
-            # Handle Nokogiri and Moxml attribute formats (Hash-like)
             extract_from_hash_attributes(raw_attrs, declarations)
           end
 
@@ -105,23 +107,11 @@ module Canon
         # @return [Hash] Declarations hash
         def self.extract_from_hash_attributes(raw_attrs, declarations)
           raw_attrs.each do |key, val|
-            # Normalize key and value
-            name = if key.is_a?(String)
-                     # Nokogiri format: key=name (String), val=attr object
-                     key
-                   else
-                     # Moxml format: key=attr object, val=nil
-                     key.respond_to?(:name) ? key.name : key.to_s
-                   end
+            name = key.is_a?(String) ? key : key.name
 
             if namespace_declaration?(name)
-              value = if val.respond_to?(:value)
-                        val.value
-                      else
-                        val.to_s
-                      end
+              value = val.is_a?(String) ? val : val.value
 
-              # Extract prefix: "xmlns" -> "", "xmlns:xmi" -> "xmi"
               prefix = name == "xmlns" ? "" : name.split(":", 2)[1]
               declarations[prefix] = value
             end
@@ -130,12 +120,8 @@ module Canon
           declarations
         end
 
-        # Check if an attribute name is a namespace declaration
-        #
-        # @param attr_name [String] Attribute name
-        # @return [Boolean] true if it's a namespace declaration
         def self.namespace_declaration?(attr_name)
-          attr_name == "xmlns" || attr_name.start_with?("xmlns:")
+          Canon::Xml::NamespaceHelper.namespace_declaration?(attr_name)
         end
 
         # Add a namespace declaration difference

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

@@ -77,21 +77,22 @@ module Canon
         # @return [Canon::Xml::Node] Converted node
         def self.convert_from_node(node, preserve_whitespace: false,
 parser: nil)
-          # FAST PATH: Convert Nokogiri/Moxml nodes directly without string round-trip
-          if defined?(Nokogiri::XML::Node) && node.is_a?(Nokogiri::XML::Node)
-            return Canon::Xml::DataModel.build_from_nokogiri(
+          if Canon::XmlBackend.nokogiri?
+            if node.is_a?(Nokogiri::XML::Node)
+              return Canon::Xml::DataModel.build_from_nokogiri(
+                node, preserve_whitespace: preserve_whitespace
+              )
+            end
+          elsif node.is_a?(Moxml::Node)
+            return Canon::Xml::DataModel.build_from_moxml(
               node, preserve_whitespace: preserve_whitespace
             )
           end
 
-          # SLOW PATH: Fallback to string serialization for unknown node types
-          xml_str = if node.respond_to?(:to_xml)
-                      node.to_xml
-                    elsif node.respond_to?(:to_s)
-                      node.to_s
+          xml_str = if node.is_a?(String)
+                      node
                     else
-                      raise Canon::Error,
-                            "Unable to convert node to string: #{node.class}"
+                      node.to_xml
                     end
 
           resolved_parser = parser || resolve_parser_config
@@ -112,7 +113,7 @@ parser: nil)
         def self.resolve_parser_config
           Canon::Config.instance.xml.diff.parser
         rescue StandardError
-          :sax
+          Canon::XmlBackend.nokogiri? ? :sax : :dom
         end
       end
     end

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

@@ -7,90 +7,62 @@ module Canon
       #
       # Handles dispatching comparison logic based on node type.
       # Supports both Canon::Xml::Node (with symbolic node_type) and
-      # Moxml/Nokogiri nodes (with predicate methods like element?, text?, etc.)
-      #
-      # This module encapsulates the complex node type detection and dispatch
-      # logic, making the main XmlComparator cleaner and more maintainable.
+      # backend nodes (Nokogiri/Moxml) via XmlParsing type checks.
       module NodeTypeComparator
         class << self
-          # Compare two nodes by dispatching to appropriate comparison method
-          #
-          # @param node1 [Object] First node
-          # @param node2 [Object] Second node
-          # @param comparator [XmlComparator] The comparator instance for method delegation
-          # @param opts [Hash] Comparison options
-          # @param child_opts [Hash] Options for child comparison
-          # @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)
-            # 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
-            if node1.respond_to?(:node_type) && node2.respond_to?(:node_type) &&
-                node1.node_type.is_a?(Symbol) && node2.node_type.is_a?(Symbol)
+            if node1.is_a?(Canon::Xml::Node) && node2.is_a?(Canon::Xml::Node)
               compare_by_symbolic_type(node1, node2, comparator, opts, child_opts,
                                        diff_children, differences)
-            # Moxml/Nokogiri types use .element?, .text?, etc. methods
             else
-              compare_by_predicate_methods(node1, node2, comparator, opts, child_opts,
-                                           diff_children, differences)
+              compare_by_backend_type(node1, node2, comparator, opts, child_opts,
+                                      diff_children, differences)
             end
           end
 
           private
 
-          # Compare nodes using symbolic node_type (Canon::Xml::Node)
           def compare_by_symbolic_type(node1, node2, comparator, opts, child_opts,
                                        diff_children, differences)
             case node1.node_type
             when :root
-              comparator.send(:compare_children, node1, node2, opts, child_opts,
-                              diff_children, differences)
+              comparator.compare_children(node1, node2, opts, child_opts,
+                                          diff_children, differences)
             when :element
-              comparator.send(:compare_element_nodes, node1, node2, opts, child_opts,
-                              diff_children, differences)
+              comparator.compare_element_nodes(node1, node2, opts, child_opts,
+                                               diff_children, differences)
             when :text
-              comparator.send(:compare_text_nodes, node1, node2, opts,
-                              differences)
+              comparator.compare_text_nodes(node1, node2, opts, differences)
             when :comment
-              comparator.send(:compare_comment_nodes, node1, node2, opts,
-                              differences)
+              comparator.compare_comment_nodes(node1, node2, opts, differences)
             when :cdata
-              comparator.send(:compare_text_nodes, node1, node2, opts,
-                              differences)
+              comparator.compare_text_nodes(node1, node2, opts, differences)
             when :processing_instruction
-              comparator.send(:compare_processing_instruction_nodes, node1, node2, opts,
-                              differences)
+              comparator.compare_processing_instruction_nodes(node1, node2, opts,
+                                                              differences)
             else
               Comparison::EQUIVALENT
             end
           end
 
-          # Compare nodes using predicate methods (Moxml/Nokogiri)
-          def compare_by_predicate_methods(node1, node2, comparator, opts, child_opts,
-                                           diff_children, differences)
-            if node1.respond_to?(:element?) && node1.element?
-              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)
-            elsif node1.respond_to?(:comment?) && node1.comment?
-              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)
-            elsif node1.respond_to?(:processing_instruction?) &&
-                node1.processing_instruction?
-              comparator.send(:compare_processing_instruction_nodes, node1, node2, opts,
-                              differences)
-            elsif node1.respond_to?(:root)
-              # Document node (Moxml/Nokogiri - legacy path)
-              comparator.send(:compare_document_nodes, node1, node2, opts, child_opts,
-                              diff_children, differences)
+          def compare_by_backend_type(node1, node2, comparator, opts, child_opts,
+                                      diff_children, differences)
+            if Canon::XmlParsing.element?(node1)
+              comparator.compare_element_nodes(node1, node2, opts, child_opts,
+                                               diff_children, differences)
+            elsif Canon::XmlParsing.text_node?(node1)
+              comparator.compare_text_nodes(node1, node2, opts, differences)
+            elsif Canon::XmlParsing.comment?(node1)
+              comparator.compare_comment_nodes(node1, node2, opts, differences)
+            elsif Canon::XmlParsing.cdata?(node1)
+              comparator.compare_text_nodes(node1, node2, opts, differences)
+            elsif Canon::XmlParsing.processing_instruction?(node1)
+              comparator.compare_processing_instruction_nodes(node1, node2, opts,
+                                                              differences)
+            elsif Canon::XmlParsing.document?(node1)
+              comparator.compare_document_nodes(node1, node2, opts, child_opts,
+                                                diff_children, differences)
             else
               Comparison::EQUIVALENT
             end

data/lib/canon/comparison/xml_comparator.rb

@@ -122,16 +122,8 @@ module Canon
                              preserve_whitespace: preserve_whitespace)
 
           # Store original strings for line diff display (before preprocessing)
-          original1 = if n1.is_a?(String)
-                        n1
-                      else
-                        (n1.respond_to?(:to_xml) ? n1.to_xml : n1.to_s)
-                      end
-          original2 = if n2.is_a?(String)
-                        n2
-                      else
-                        (n2.respond_to?(:to_xml) ? n2.to_xml : n2.to_s)
-                      end
+          original1 = n1.is_a?(String) ? n1 : serialize_node(n1)
+          original2 = n2.is_a?(String) ? n2 : serialize_node(n2)
 
           differences = []
           diff_children = opts[:diff_children] || false
@@ -187,16 +179,9 @@ module Canon
         # @return [Boolean, ComparisonResult] Result of tree diff comparison
         def perform_semantic_tree_diff(n1, n2, opts, match_opts_hash)
           # Store original strings for line diff display (before preprocessing)
-          original1 = if n1.is_a?(String)
-                        n1
-                      else
-                        (n1.respond_to?(:to_xml) ? n1.to_xml : n1.to_s)
-                      end
-          original2 = if n2.is_a?(String)
-                        n2
-                      else
-                        (n2.respond_to?(:to_xml) ? n2.to_xml : n2.to_s)
-                      end
+          # Store original strings for line diff display (before preprocessing)
+          original1 = n1.is_a?(String) ? n1 : serialize_node(n1)
+          original2 = n2.is_a?(String) ? n2 : serialize_node(n2)
 
           # Parse to Canon::Xml::Node (preserves preprocessing)
           node1 = parse_node(n1, match_opts_hash[:preprocessing])
@@ -262,20 +247,8 @@ module Canon
             serialize_node(node1).gsub("><", ">\n<"),
             serialize_node(node2).gsub("><", ">\n<"),
           ]
-          original1 = if n1.is_a?(String)
-                        n1
-                      elsif n1.respond_to?(:to_xml)
-                        n1.to_xml
-                      else
-                        n1.to_s
-                      end
-          original2 = if n2.is_a?(String)
-                        n2
-                      elsif n2.respond_to?(:to_xml)
-                        n2.to_xml
-                      else
-                        n2.to_s
-                      end
+          original1 = n1.is_a?(String) ? n1 : serialize_node(n1)
+          original2 = n2.is_a?(String) ? n2 : serialize_node(n2)
 
           ComparisonResult.new(
             differences: [],
@@ -289,14 +262,20 @@ module Canon
 
         public
 
+        # Public parsing API for external callers
+        def parse(node, preprocessing = :none, preserve_whitespace: false)
+          parse_node(node, preprocessing,
+                     preserve_whitespace: preserve_whitespace)
+        end
+
         # Main comparison dispatcher
         def compare_nodes(n1, n2, opts, child_opts, diff_children, differences)
           # FAST PATH: Object identity - same object is always equivalent
           return Comparison::EQUIVALENT if n1.equal?(n2)
 
           # Handle DocumentFragment nodes - compare their children instead
-          if n1.is_a?(Nokogiri::XML::DocumentFragment) &&
-              n2.is_a?(Nokogiri::XML::DocumentFragment)
+          if Canon::XmlParsing.document_fragment?(n1) &&
+              Canon::XmlParsing.document_fragment?(n2)
             children1 = n1.children.to_a
             children2 = n2.children.to_a
 
@@ -392,8 +371,8 @@ module Canon
           end
 
           # Compare namespace URIs - elements with different namespaces are different elements
-          ns1 = n1.respond_to?(:namespace_uri) ? n1.namespace_uri : nil
-          ns2 = n2.respond_to?(:namespace_uri) ? n2.namespace_uri : nil
+          ns1 = Canon::XmlParsing.namespace_uri(n1)
+          ns2 = Canon::XmlParsing.namespace_uri(n2)
 
           unless ns1 == ns2
             # Create descriptive reason showing the actual namespace URIs
@@ -410,18 +389,30 @@ module Canon
             return Comparison::UNEQUAL_ELEMENTS
           end
 
+          # Track the worst result across namespace, attribute, and children
+          # comparisons. Do NOT return early on attribute/namespace mismatches —
+          # children must still be compared so structural differences in the
+          # subtree are reported. Early returns caused the comparator to skip
+          # entire subtrees when a root or intermediate element had different
+          # attributes, missing all nested structural changes.
+          worst_result = Comparison::EQUIVALENT
+
           # Compare namespace declarations (xmlns and xmlns:* attributes)
           ns_result = compare_namespace_declarations(n1, n2, opts, differences)
-          return ns_result unless ns_result == Comparison::EQUIVALENT
+          worst_result = ns_result unless ns_result == Comparison::EQUIVALENT
 
           # Compare attributes
           attr_result = compare_attribute_sets(n1, n2, opts, differences)
-          return attr_result unless attr_result == Comparison::EQUIVALENT
+          worst_result = attr_result unless attr_result == Comparison::EQUIVALENT
 
           # Compare children if not ignored
-          return Comparison::EQUIVALENT if opts[:ignore_children]
+          unless opts[:ignore_children]
+            child_result = compare_children(n1, n2, opts, child_opts,
+                                            diff_children, differences)
+            worst_result = child_result unless child_result == Comparison::EQUIVALENT
+          end
 
-          compare_children(n1, n2, opts, child_opts, diff_children, differences)
+          worst_result
         end
 
         # Compare attribute sets
@@ -500,7 +491,7 @@ module Canon
         def should_preserve_whitespace_strictly?(n1, n2, opts)
           # 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)
+            next unless Canon::XmlParsing.xml_node?(node) || node.is_a?(Canon::Xml::Node)
 
             parent = node.parent
             next unless parent
@@ -516,15 +507,12 @@ module Canon
         # Check if a node is inside a whitespace-preserving element
         def in_preserve_element?(node, preserve_list)
           current = node.parent
-          while current.respond_to?(:name)
+          while Canon::XmlParsing.xml_node?(current) || current.is_a?(Canon::Xml::Node)
             return true if preserve_list.include?(current.name.downcase)
 
-            # Stop at document root
-            break if current.is_a?(Nokogiri::XML::Document) ||
-              current.is_a?(Nokogiri::HTML4::Document) ||
-              current.is_a?(Nokogiri::HTML5::Document)
+            break if Canon::XmlParsing.document?(current)
 
-            current = current.parent if current.respond_to?(:parent)
+            current = current.parent
             break unless current
           end
           false
@@ -567,8 +555,8 @@ module Canon
             return Comparison::UNEQUAL_NODES_TYPES
           end
 
-          content1 = n1.respond_to?(:content) ? n1.content.to_s.strip : ""
-          content2 = n2.respond_to?(:content) ? n2.content.to_s.strip : ""
+          content1 = Canon::XmlParsing.xml_node?(n1) ? n1.content.to_s.strip : ""
+          content2 = Canon::XmlParsing.xml_node?(n2) ? n2.content.to_s.strip : ""
 
           if content1 == content2
             Comparison::EQUIVALENT
@@ -618,17 +606,19 @@ differences)
           depth = 0
 
           while current && depth < max_depth
-            if current.respond_to?(:name) && current.name
-              path.unshift(current.name)
-            end
+            n = if current.is_a?(Canon::Xml::Node)
+                  current.name
+                elsif Canon::XmlParsing.xml_node?(current)
+                  current.name
+                end
+            path.unshift(n) if n
 
-            break unless current.respond_to?(:parent)
+            break unless Canon::XmlParsing.xml_node?(current) || current.is_a?(Canon::Xml::Node)
 
             current = current.parent
             depth += 1
 
-            # Stop at document root
-            break if current.respond_to?(:root)
+            break if Canon::XmlParsing.document?(current)
           end
 
           path
@@ -665,8 +655,8 @@ differences)
           # 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)
-              ns = node.namespace_uri
+            if Canon::XmlParsing.xml_node?(node)
+              ns = Canon::XmlParsing.namespace_uri(node)
               ns_info = if ns.nil? || ns.empty?
                           ""
                         else
@@ -674,9 +664,8 @@ differences)
                         end
               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
+            elsif node.is_a?(Canon::Xml::Node)
+              display = if node.is_a?(Canon::Xml::Nodes::TextNode)
                           "\"#{truncate_text(node.value)}\""
                         else
                           node.name.to_s
@@ -703,6 +692,10 @@ differences)
             return build_whitespace_adjacency_reason(node1, node2)
           end
 
+          if dimension == :comments
+            return build_comments_reason(node1, node2)
+          end
+
           # For attribute values differences, show the actual values
           if dimension == :attribute_values
             attrs1 = extract_attributes(node1)
@@ -722,8 +715,8 @@ differences)
           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.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(node1)) &&
+              (node2.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(node2)) &&
               node1.name && node2.name && node1.name != node2.name
             # Most common case: differing element names.  Surface the
             # actual names rather than a generic "elements differ".
@@ -794,27 +787,16 @@ differences)
         # @return [String, nil] Text content or nil
         def extract_text_from_node(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
+          else
+            Canon::XmlParsing.xml_node?(node) ? Canon::XmlParsing.text_content(node).to_s : node.to_s
+          end
         rescue StandardError
           nil
         end
@@ -934,6 +916,30 @@ differences)
           false
         end
 
+        # Build a Reason line for a +:comments+ diff (#144).
+        # Names the side that carries the comment and surfaces the
+        # comment text.
+        def build_comments_reason(node1, node2)
+          cm1 = node1 && NodeInspector.comment_node?(node1)
+          cm2 = node2 && NodeInspector.comment_node?(node2)
+
+          if cm1 && !cm2
+            "Comment present on EXPECTED only: <!--#{truncate_text(comment_text(node1))}-->"
+          elsif cm2 && !cm1
+            "Comment present on ACTUAL only: <!--#{truncate_text(comment_text(node2))}-->"
+          elsif cm1 && cm2
+            t1 = truncate_text(comment_text(node1))
+            t2 = truncate_text(comment_text(node2))
+            "Comment text differs: <!--#{t1}--> vs <!--#{t2}-->"
+          else
+            "element structure mismatch (children differ)"
+          end
+        end
+
+        def comment_text(node)
+          NodeInspector.text_content(node).to_s
+        end
+
         # Check if text is only whitespace
         #
         # @param text [String] Text to check