canon 0.1.6 → 0.1.7

data/lib/canon/comparison/xml_comparator.rb

@@ -5,6 +5,8 @@ require_relative "match_options"
 require_relative "../diff/diff_node"
 require_relative "../diff/diff_classifier"
 require_relative "comparison_result"
+require_relative "../tree_diff"
+require_relative "strategies/match_strategy_factory"
 
 module Canon
   module Comparison
@@ -67,6 +69,11 @@ module Canon
           # Store resolved match options hash for use in comparison logic
           opts[:match_opts] = match_opts_hash
 
+          # Use tree diff if semantic_diff option is enabled
+          if match_opts.semantic_diff?
+            return perform_semantic_tree_diff(n1, n2, opts, match_opts_hash)
+          end
+
           # Create child_opts with resolved options
           child_opts = opts.merge(child_opts)
 
@@ -74,6 +81,18 @@ module Canon
           node1 = parse_node(n1, match_opts_hash[:preprocessing])
           node2 = parse_node(n2, match_opts_hash[:preprocessing])
 
+          # 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
+
           differences = []
           diff_children = opts[:diff_children] || false
 
@@ -89,33 +108,110 @@ module Canon
           end
 
           if opts[:verbose]
-            # Return ComparisonResult for proper equivalence checking
-            # Format XMLfor line-by-line display by adding line breaks between elements
-            xml1 = node1.respond_to?(:to_xml) ? node1.to_xml : node1.to_s
-            xml2 = node2.respond_to?(:to_xml) ? node2.to_xml : node2.to_s
-
+            # Serialize parsed nodes for consistent formatting
+            # This ensures both sides formatted identically, showing only real differences
             preprocessed = [
-              xml1.gsub(/></, ">\n<"),
-              xml2.gsub(/></, ">\n<"),
+              serialize_node_to_xml(node1).gsub(/></, ">\n<"),
+              serialize_node_to_xml(node2).gsub(/></, ">\n<"),
             ]
 
             ComparisonResult.new(
               differences: differences,
               preprocessed_strings: preprocessed,
+              original_strings: [original1, original2],
               format: :xml,
               match_options: match_opts_hash,
+              algorithm: :dom,
             )
+          elsif result != Comparison::EQUIVALENT && !differences.empty?
+            # Non-verbose mode: check equivalence
+            # If comparison found differences, classify them to determine if normative
+            classifier = Canon::Diff::DiffClassifier.new(match_opts)
+            classifier.classify_all(differences.select do |d|
+              d.is_a?(Canon::Diff::DiffNode)
+            end)
+            # Equivalent if no normative differences (matches semantic algorithm)
+            differences.none?(&:normative?)
           else
+            # Either equivalent or no differences tracked
             result == Comparison::EQUIVALENT
           end
         end
 
         private
 
+        # Perform semantic tree diff using SemanticTreeMatchStrategy
+        #
+        # @param n1 [String, Moxml::Node] First node
+        # @param n2 [String, Moxml::Node] Second node
+        # @param opts [Hash] Comparison options
+        # @param match_opts_hash [Hash] Resolved match options
+        # @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
+
+          # Parse to Canon::Xml::Node (preserves preprocessing)
+          node1 = parse_node(n1, match_opts_hash[:preprocessing])
+          node2 = parse_node(n2, match_opts_hash[:preprocessing])
+
+          # Create strategy using factory
+          strategy = Strategies::MatchStrategyFactory.create(
+            format: :xml,
+            match_options: match_opts_hash,
+          )
+
+          # Pass Canon::Xml::Node directly - XML adapter now handles it
+          differences = strategy.match(node1, node2)
+
+          # Return based on verbose mode
+          if opts[:verbose]
+            # Get preprocessed strings for display
+            preprocessed = strategy.preprocess_for_display(node1, node2)
+
+            # Return ComparisonResult with strategy metadata
+            ComparisonResult.new(
+              differences: differences,
+              preprocessed_strings: preprocessed,
+              original_strings: [original1, original2],
+              format: :xml,
+              match_options: match_opts_hash.merge(strategy.metadata),
+              algorithm: :semantic,
+            )
+          else
+            # Simple boolean result - equivalent if no normative differences
+            differences.none?(&:normative?)
+          end
+        end
+
         # Parse a node from string or return as-is
         # Applies preprocessing transformation before parsing if specified
         def parse_node(node, preprocessing = :none)
-          return node unless node.is_a?(String)
+          # 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)
+            # Convert to XML string then parse through DataModel
+            xml_str = if node.respond_to?(:to_xml)
+                        node.to_xml
+                      elsif node.respond_to?(:to_s)
+                        node.to_s
+                      else
+                        raise Canon::Error,
+                              "Unable to convert node to string: #{node.class}"
+                      end
+            return Canon::Xml::DataModel.from_xml(xml_str)
+          end
 
           # Apply preprocessing to XML string before parsing
           xml_string = case preprocessing
@@ -134,8 +230,8 @@ module Canon
                          node
                        end
 
-          # Use Moxml for XML parsing
-          Moxml.new.parse(xml_string)
+          # Use Canon::Xml::DataModel for parsing to get Canon::Xml::Node instances
+          Canon::Xml::DataModel.from_xml(xml_string)
         end
 
         # Main comparison dispatcher
@@ -159,10 +255,7 @@ module Canon
               children1.zip(children2).each do |child1, child2|
                 child_result = compare_nodes(child1, child2, opts, child_opts,
                                              diff_children, differences)
-                if child_result != Comparison::EQUIVALENT
-                  result = child_result
-                  break
-                end
+                result = child_result unless child_result == Comparison::EQUIVALENT
               end
               return result
             end
@@ -187,7 +280,30 @@ module Canon
           end
 
           # Dispatch based on node type
-          if n1.respond_to?(:element?) && n1.element?
+          # Canon::Xml::Node types use .node_type method that returns symbols
+          # Nokogiri also has .node_type but returns integers, so check for Symbol
+          if n1.respond_to?(:node_type) && n2.respond_to?(:node_type) &&
+              n1.node_type.is_a?(Symbol) && n2.node_type.is_a?(Symbol)
+            case n1.node_type
+            when :root
+              compare_children(n1, n2, opts, child_opts, diff_children,
+                               differences)
+            when :element
+              compare_element_nodes(n1, n2, opts, child_opts, diff_children,
+                                    differences)
+            when :text
+              compare_text_nodes(n1, n2, opts, differences)
+            when :comment
+              compare_comment_nodes(n1, n2, opts, differences)
+            when :cdata
+              compare_text_nodes(n1, n2, opts, differences)
+            when :processing_instruction
+              compare_processing_instruction_nodes(n1, n2, opts, differences)
+            else
+              Comparison::EQUIVALENT
+            end
+          # Moxml/Nokogiri types use .element?, .text?, etc. methods
+          elsif n1.respond_to?(:element?) && n1.element?
             compare_element_nodes(n1, n2, opts, child_opts, diff_children,
                                   differences)
           elsif n1.respond_to?(:text?) && n1.text?
@@ -200,7 +316,7 @@ module Canon
               n1.processing_instruction?
             compare_processing_instruction_nodes(n1, n2, opts, differences)
           elsif n1.respond_to?(:root)
-            # Document node
+            # Document node (Moxml/Nokogiri - legacy path)
             compare_document_nodes(n1, n2, opts, child_opts, diff_children,
                                    differences)
           else
@@ -214,11 +330,34 @@ module Canon
           # Compare element names
           unless n1.name == n2.name
             add_difference(n1, n2, Comparison::UNEQUAL_ELEMENTS,
-                           Comparison::UNEQUAL_ELEMENTS, :text_content, opts,
+                           Comparison::UNEQUAL_ELEMENTS, :element_structure, opts,
                            differences)
             return Comparison::UNEQUAL_ELEMENTS
           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
+
+          unless ns1 == ns2
+            # Create descriptive reason showing the actual namespace URIs
+            ns1_display = ns1.nil? || ns1.empty? ? "(no namespace)" : ns1
+            ns2_display = ns2.nil? || ns2.empty? ? "(no namespace)" : ns2
+
+            diff_node = Canon::Diff::DiffNode.new(
+              node1: n1,
+              node2: n2,
+              dimension: :namespace_uri,
+              reason: "namespace '#{ns1_display}' vs '#{ns2_display}' on element '#{n1.name}'",
+            )
+            differences << diff_node if opts[:verbose]
+            return Comparison::UNEQUAL_ELEMENTS
+          end
+
+          # Compare namespace declarations (xmlns and xmlns:* attributes)
+          ns_result = compare_namespace_declarations(n1, n2, opts, differences)
+          return 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
@@ -231,20 +370,67 @@ module Canon
 
         # Compare attribute sets
         def compare_attribute_sets(n1, n2, opts, differences)
-          attrs1 = filter_attributes(n1.attributes, opts)
-          attrs2 = filter_attributes(n2.attributes, opts)
+          # Get attributes using the appropriate method for each node type
+          raw_attrs1 = n1.respond_to?(:attribute_nodes) ? n1.attribute_nodes : n1.attributes
+          raw_attrs2 = n2.respond_to?(:attribute_nodes) ? n2.attribute_nodes : n2.attributes
 
-          # Always sort attributes since attribute order doesn't matter in XML/HTML
-          attrs1 = attrs1.sort_by { |k, _v| k.to_s }.to_h
-          attrs2 = attrs2.sort_by { |k, _v| k.to_s }.to_h
+          attrs1 = filter_attributes(raw_attrs1, opts)
+          attrs2 = filter_attributes(raw_attrs2, opts)
 
-          unless attrs1.keys.map(&:to_s).sort == attrs2.keys.map(&:to_s).sort
-            add_difference(n1, n2, Comparison::MISSING_ATTRIBUTE,
-                           Comparison::MISSING_ATTRIBUTE,
-                           :attribute_presence, opts, differences)
-            return Comparison::MISSING_ATTRIBUTE
-          end
+          match_opts = opts[:match_opts]
+          attribute_order_behavior = match_opts[:attribute_order] || :strict
+
+          # Check attribute order if not ignored
+          keys1 = attrs1.keys.map(&:to_s)
+          keys2 = attrs2.keys.map(&:to_s)
+          if attribute_order_behavior == :strict
+            # Strict mode: attribute order matters
+            # Check if keys are in same order
+
+            if keys1 != keys2
+              # Keys are different or in different order
+              # First check if it's just ordering (same keys, different order)
+              if keys1.sort == keys2.sort
+                # Same keys, different order - this is an attribute_order difference
+                add_difference(n1, n2, Comparison::UNEQUAL_ATTRIBUTES,
+                               Comparison::UNEQUAL_ATTRIBUTES,
+                               :attribute_order, opts, differences)
+                return Comparison::UNEQUAL_ATTRIBUTES
+              else
+                # Different keys - this is attribute_presence difference
+                add_difference(n1, n2, Comparison::MISSING_ATTRIBUTE,
+                               Comparison::MISSING_ATTRIBUTE,
+                               :attribute_presence, opts, differences)
+                return Comparison::MISSING_ATTRIBUTE
+              end
+            end
+
+          # Order matches, now check values in order
+          else
+            # Ignore/normalize mode: attribute order doesn't affect equivalence
+            # But in verbose mode, we should still track order differences as informative
+
+            # Check if order differs (but keys are the same)
+            if keys1 != keys2 && keys1.sort == keys2.sort && opts[:verbose]
+              # Same keys, different order - create informative DiffNode
+              # This allows line diffs to be properly classified as informative
+              add_difference(n1, n2, Comparison::UNEQUAL_ATTRIBUTES,
+                             Comparison::UNEQUAL_ATTRIBUTES,
+                             :attribute_order, opts, differences)
+            end
+
+            # Sort attributes so order doesn't matter for comparison
+            attrs1 = attrs1.sort_by { |k, _v| k.to_s }.to_h
+            attrs2 = attrs2.sort_by { |k, _v| k.to_s }.to_h
 
+            unless attrs1.keys.map(&:to_s).sort == attrs2.keys.map(&:to_s).sort
+              add_difference(n1, n2, Comparison::MISSING_ATTRIBUTE,
+                             Comparison::MISSING_ATTRIBUTE,
+                             :attribute_presence, opts, differences)
+              return Comparison::MISSING_ATTRIBUTE
+            end
+
+          end
           attrs1.each do |name, value|
             unless attrs2[name] == value
               add_difference(n1, n2, Comparison::UNEQUAL_ATTRIBUTES,
@@ -262,32 +448,57 @@ module Canon
           filtered = {}
           match_opts = opts[:match_opts]
 
-          attributes.each do |key, val|
-            # Handle both Nokogiri and Moxml attribute formats:
+          # Handle Canon::Xml::Node attribute format (array of AttributeNode)
+          if attributes.is_a?(Array)
+            attributes.each do |attr|
+              name = attr.name
+              value = attr.value
+
+              # Skip namespace declarations - they're handled separately
+              next if is_namespace_declaration?(name)
+
+              # Skip if attribute name should be ignored
+              next if should_ignore_attr_by_name?(name, opts)
+
+              # Skip if attribute content should be ignored
+              next if should_ignore_attr_content?(value, opts)
+
+              # Apply match options for attribute values
+              behavior = match_opts[:attribute_values] || :strict
+              value = MatchOptions.process_attribute_value(value, behavior)
+
+              filtered[name] = value
+            end
+          else
+            # Handle Nokogiri and Moxml attribute formats (Hash-like):
             # - Nokogiri: key is String name, val is Nokogiri::XML::Attr object
             # - Moxml: key is Moxml::Attribute object, val is nil
+            attributes.each do |key, val|
+              if key.is_a?(String)
+                # Nokogiri format: key=name (String), val=attr object
+                name = key
+                value = val.respond_to?(:value) ? val.value : val.to_s
+              else
+                # Moxml format: key=attr object, val=nil
+                name = key.respond_to?(:name) ? key.name : key.to_s
+                value = key.respond_to?(:value) ? key.value : key.to_s
+              end
 
-            if key.is_a?(String)
-              # Nokogiri format: key=name (String), val=attr object
-              name = key
-              value = val.respond_to?(:value) ? val.value : val.to_s
-            else
-              # Moxml format: key=attr object, val=nil
-              name = key.respond_to?(:name) ? key.name : key.to_s
-              value = key.respond_to?(:value) ? key.value : key.to_s
-            end
+              # Skip namespace declarations - they're handled separately
+              next if is_namespace_declaration?(name)
 
-            # Skip if attribute name should be ignored
-            next if should_ignore_attr_by_name?(name, opts)
+              # Skip if attribute name should be ignored
+              next if should_ignore_attr_by_name?(name, opts)
 
-            # Skip if attribute content should be ignored
-            next if should_ignore_attr_content?(value, opts)
+              # Skip if attribute content should be ignored
+              next if should_ignore_attr_content?(value, opts)
 
-            # Apply match options for attribute values
-            behavior = match_opts[:attribute_values] || :strict
-            value = MatchOptions.process_attribute_value(value, behavior)
+              # Apply match options for attribute values
+              behavior = match_opts[:attribute_values] || :strict
+              value = MatchOptions.process_attribute_value(value, behavior)
 
-            filtered[name] = value
+              filtered[name] = value
+            end
           end
 
           filtered
@@ -324,26 +535,35 @@ module Canon
             behavior = :strict
           end
 
-          if MatchOptions.match_text?(text1, text2, behavior)
-            Comparison::EQUIVALENT
-          else
-            # Determine the correct dimension for this difference
-            # - If text_content is :strict, ALL differences use :text_content dimension
-            # - If text_content is :normalize, whitespace-only diffs use :structural_whitespace
-            # - Otherwise use :text_content
-            dimension = if behavior == :normalize && whitespace_only_difference?(
-              text1, text2
-            )
-                          :structural_whitespace
-                        else
-                          :text_content
-                        end
+          # Check if raw content differs
+          raw_differs = text1 != text2
+
+          # Check if matches according to behavior
+          matches_per_behavior = MatchOptions.match_text?(text1, text2,
+                                                          behavior)
 
+          # Determine the correct dimension for this difference
+          # - If text_content is :strict, ALL differences use :text_content dimension
+          # - If text_content is :normalize, whitespace-only diffs use :structural_whitespace
+          # - Otherwise use :text_content
+          dimension = if behavior == :normalize && whitespace_only_difference?(
+            text1, text2
+          )
+                        :structural_whitespace
+                      else
+                        :text_content
+                      end
+
+          # Create DiffNode in verbose mode when raw content differs
+          # This ensures informative diffs are created even for :ignore/:normalize
+          if raw_differs && opts[:verbose]
             add_difference(n1, n2, Comparison::UNEQUAL_TEXT_CONTENTS,
                            Comparison::UNEQUAL_TEXT_CONTENTS, dimension,
                            opts, differences)
-            Comparison::UNEQUAL_TEXT_CONTENTS
           end
+
+          # Return based on whether behavior makes difference acceptable
+          matches_per_behavior ? Comparison::EQUIVALENT : Comparison::UNEQUAL_TEXT_CONTENTS
         end
 
         # Check if the difference between two texts is only whitespace-related
@@ -396,18 +616,25 @@ module Canon
           match_opts = opts[:match_opts]
           behavior = match_opts[:comments]
 
-          # If comments are ignored, consider them equivalent
-          return Comparison::EQUIVALENT if behavior == :ignore
+          # Canon::Xml::Node CommentNode uses .value, Nokogiri uses .content
+          content1 = node_text(n1)
+          content2 = node_text(n2)
 
-          content1 = n1.content.to_s
-          content2 = n2.content.to_s
+          # Check if content differs
+          contents_differ = content1 != content2
 
-          if MatchOptions.match_text?(content1, content2, behavior)
-            Comparison::EQUIVALENT
-          else
+          # Create DiffNode in verbose mode when content differs
+          # This ensures informative diffs are created even for :ignore behavior
+          if contents_differ && opts[:verbose]
             add_difference(n1, n2, Comparison::UNEQUAL_COMMENTS,
                            Comparison::UNEQUAL_COMMENTS, :comments, opts,
                            differences)
+          end
+
+          # Return based on behavior and whether content matches
+          if behavior == :ignore || !contents_differ
+            Comparison::EQUIVALENT
+          else
             Comparison::UNEQUAL_COMMENTS
           end
         end
@@ -451,25 +678,155 @@ module Canon
                         differences)
         end
 
-        # Compare children of two nodes
+        # Compare children of two nodes using semantic matching
+        #
+        # Uses ElementMatcher to pair children semantically (by identity attributes
+        # or position), then compares matched pairs and detects position changes.
         def compare_children(n1, n2, opts, child_opts, diff_children,
                              differences)
           children1 = filter_children(n1.children, opts)
           children2 = filter_children(n2.children, opts)
 
-          unless children1.length == children2.length
-            add_difference(n1, n2, Comparison::MISSING_NODE,
-                           Comparison::MISSING_NODE, :text_content, opts, differences)
-            return Comparison::MISSING_NODE
+          # Quick check: if both have no children, they're equivalent
+          return Comparison::EQUIVALENT if children1.empty? && children2.empty?
+
+          # Check if we can use ElementMatcher (requires Canon::Xml::DataModel nodes)
+          # ElementMatcher expects nodes with .node_type method that returns symbols
+          # and only works with element nodes (filters out text, comment, etc.)
+          can_use_matcher = 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 }
+
+          if can_use_matcher && !children1.empty? && !children2.empty?
+            # Use ElementMatcher for semantic matching with position tracking
+            use_element_matcher_comparison(children1, children2, n1, opts,
+                                           child_opts, diff_children, differences)
+          else
+            # Fall back to simple positional comparison for Moxml/Nokogiri nodes
+            # Length check
+            unless children1.length == children2.length
+              # Determine dimension based on type of first differing child
+              # When lengths differ, find which child is missing/extra
+              dimension = :text_content # default
+
+              # Compare position by position to find first difference
+              max_len = [children1.length, children2.length].max
+              (0...max_len).each do |i|
+                if i >= children1.length
+                  # Extra child in children2
+                  dimension = determine_node_dimension(children2[i])
+                  break
+                elsif i >= children2.length
+                  # Extra child in children1
+                  dimension = determine_node_dimension(children1[i])
+                  break
+                elsif !same_node_type?(children1[i], children2[i])
+                  # Different node types at same position
+                  dimension = determine_node_dimension(children1[i])
+                  break
+                end
+              end
+
+              add_difference(n1, n2, Comparison::MISSING_NODE,
+                             Comparison::MISSING_NODE, dimension, opts,
+                             differences)
+              return Comparison::MISSING_NODE
+            end
+
+            # Compare children pairwise by position
+            result = Comparison::EQUIVALENT
+            children1.zip(children2).each do |child1, child2|
+              child_result = compare_nodes(child1, child2, child_opts, child_opts,
+                                           diff_children, differences)
+              result = child_result unless child_result == Comparison::EQUIVALENT
+            end
+
+            result
           end
+        end
+
+        # Use ElementMatcher for semantic comparison (Canon::Xml::DataModel nodes)
+        def use_element_matcher_comparison(children1, children2, parent_node,
+                                          opts, child_opts, diff_children,
+                                          differences)
+          require_relative "../xml/element_matcher"
 
-          children1.zip(children2).each do |child1, child2|
-            result = compare_nodes(child1, child2, child_opts, child_opts,
-                                   diff_children, differences)
-            return result unless result == Comparison::EQUIVALENT
+          # Create temporary RootNode wrappers to use ElementMatcher
+          # Don't modify parent pointers - just set @children directly
+          require_relative "../xml/nodes/root_node"
+
+          temp_root1 = Canon::Xml::Nodes::RootNode.new
+          temp_root1.instance_variable_set(:@children, children1.dup)
+
+          temp_root2 = Canon::Xml::Nodes::RootNode.new
+          temp_root2.instance_variable_set(:@children, children2.dup)
+
+          matcher = Canon::Xml::ElementMatcher.new
+          matches = matcher.match_trees(temp_root1, temp_root2)
+
+          # Filter matches to only include direct children
+          # match_trees returns ALL descendants, but we only want direct children
+          matches = matches.select do |m|
+            (m.elem1.nil? || children1.include?(m.elem1)) &&
+              (m.elem2.nil? || children2.include?(m.elem2))
           end
 
-          Comparison::EQUIVALENT
+          # If no matches and children exist, they're all different
+          if matches.empty? && (!children1.empty? || !children2.empty?)
+            add_difference(parent_node, parent_node, Comparison::MISSING_NODE,
+                           Comparison::MISSING_NODE, :text_content, opts,
+                           differences)
+            return Comparison::UNEQUAL_ELEMENTS
+          end
+
+          all_equivalent = true
+
+          matches.each do |match|
+            case match.status
+            when :matched
+              # Check if element position changed
+              if match.position_changed?
+                match_opts = opts[:match_opts]
+                position_behavior = match_opts[:element_position] || :strict
+
+                # Only create DiffNode if element_position is not :ignore
+                if position_behavior != :ignore
+                  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 = 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
+              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
+              add_difference(nil, match.elem2, Comparison::MISSING_NODE,
+                             Comparison::MISSING_NODE, :element_structure, opts,
+                             differences)
+              all_equivalent = false
+            end
+          end
+
+          all_equivalent ? Comparison::EQUIVALENT : Comparison::UNEQUAL_ELEMENTS
         end
 
         # Filter children based on options
@@ -483,20 +840,28 @@ module Canon
         def node_excluded?(node, opts)
           match_opts = opts[:match_opts]
 
-          # Ignore comments based on match options
-          if node.respond_to?(:comment?) && node.comment? && (match_opts[:comments] == :ignore)
-            return true
+          # Determine node type
+          # Canon::Xml::Node uses node_type that returns Symbol
+          # Nokogiri uses node_type that returns Integer, so check for Symbol first
+          if node.respond_to?(:node_type) && node.node_type.is_a?(Symbol)
+            node.node_type == :comment
+          else
+            node.respond_to?(:comment?) && node.comment?
           end
 
+          is_text = if node.respond_to?(:node_type) && node.node_type.is_a?(Symbol)
+                      node.node_type == :text
+                    else
+                      node.respond_to?(:text?) && node.text?
+                    end
+
           # Ignore text nodes if specified
-          return true if opts[:ignore_text_nodes] &&
-            node.respond_to?(:text?) && node.text?
+          return true if opts[:ignore_text_nodes] && is_text
 
           # Ignore whitespace-only text nodes based on structural_whitespace
           # Both :ignore and :normalize should filter out whitespace-only nodes
           if %i[ignore
-                normalize].include?(match_opts[:structural_whitespace]) &&
-              node.respond_to?(:text?) && node.text?
+                normalize].include?(match_opts[:structural_whitespace]) && is_text
             text = node_text(node)
             return true if MatchOptions.normalize_text(text).empty?
           end
@@ -504,8 +869,40 @@ module Canon
           false
         end
 
+        # Determine the appropriate dimension for a node type
+        # @param node [Object] The node to check
+        # @return [Symbol] The dimension symbol
+        def determine_node_dimension(node)
+          # Canon::Xml::Node types
+          if node.respond_to?(:node_type) && node.node_type.is_a?(Symbol)
+            case node.node_type
+            when :comment then :comments
+            when :text, :cdata then :text_content
+            when :processing_instruction then :processing_instructions
+            else :text_content
+            end
+          # Moxml/Nokogiri types
+          elsif node.respond_to?(:comment?) && node.comment?
+            :comments
+          elsif node.respond_to?(:text?) && node.text?
+            :text_content
+          elsif node.respond_to?(:cdata?) && node.cdata?
+            :text_content
+          elsif node.respond_to?(:processing_instruction?) && node.processing_instruction?
+            :processing_instructions
+          else
+            :text_content
+          end
+        end
+
         # Check if two nodes are the same type
         def same_node_type?(n1, n2)
+          # Canon::Xml::Node types - check node_type method
+          if n1.respond_to?(:node_type) && n2.respond_to?(:node_type)
+            return n1.node_type == n2.node_type
+          end
+
+          # Moxml/Nokogiri types - check individual type methods
           return true if n1.respond_to?(:element?) && n1.element? &&
             n2.respond_to?(:element?) && n2.element?
           return true if n1.respond_to?(:text?) && n1.text? &&
@@ -525,7 +922,10 @@ module Canon
 
         # Get text content from a node
         def node_text(node)
-          if node.respond_to?(:content)
+          # Canon::Xml::Node TextNode uses .value
+          if node.respond_to?(:value)
+            node.value.to_s
+          elsif node.respond_to?(:content)
             node.content.to_s
           elsif node.respond_to?(:text)
             node.text.to_s
@@ -534,6 +934,66 @@ module Canon
           end
         end
 
+        # Extract element path for context (best effort)
+        # @param node [Object] Node to extract path from
+        # @return [Array<String>] Path components
+        def extract_element_path(node)
+          path = []
+          current = node
+          max_depth = 20
+          depth = 0
+
+          while current && depth < max_depth
+            if current.respond_to?(:name) && current.name
+              path.unshift(current.name)
+            end
+
+            break unless current.respond_to?(:parent)
+
+            current = current.parent
+            depth += 1
+
+            # Stop at document root
+            break if current.respond_to?(:root)
+          end
+
+          path
+        end
+
+        # Serialize a node to XML string
+        # @param node [Canon::Xml::Node, Object] Node to serialize
+        # @return [String] XML string representation
+        def serialize_node_to_xml(node)
+          if node.is_a?(Canon::Xml::Nodes::RootNode)
+            # Serialize all children of root
+            node.children.map { |child| serialize_node_to_xml(child) }.join
+          elsif node.is_a?(Canon::Xml::Nodes::ElementNode)
+            # Serialize element with attributes and children
+            attrs = node.attribute_nodes.map do |a|
+              " #{a.name}=\"#{a.value}\""
+            end.join
+            children_xml = node.children.map do |c|
+              serialize_node_to_xml(c)
+            end.join
+
+            if children_xml.empty?
+              "<#{node.name}#{attrs}/>"
+            else
+              "<#{node.name}#{attrs}>#{children_xml}</#{node.name}>"
+            end
+          elsif node.is_a?(Canon::Xml::Nodes::TextNode)
+            node.value
+          elsif node.is_a?(Canon::Xml::Nodes::CommentNode)
+            "<!--#{node.value}-->"
+          elsif node.is_a?(Canon::Xml::Nodes::ProcessingInstructionNode)
+            "<?#{node.target} #{node.data}?>"
+          elsif node.respond_to?(:to_xml)
+            node.to_xml
+          else
+            node.to_s
+          end
+        end
+
         # Add a difference to the differences array
         # @param node1 [Object] First node
         # @param node2 [Object] Second node
@@ -542,24 +1002,168 @@ module Canon
         # @param dimension [Symbol] The match dimension causing this difference
         # @param opts [Hash] Options
         # @param differences [Array] Array to append difference to
-        def add_difference(node1, node2, diff1, diff2, dimension, opts,
+        def add_difference(node1, node2, diff1, diff2, dimension, _opts,
                            differences)
-          return unless opts[:verbose]
-
           # All differences must be DiffNode objects (OO architecture)
           if dimension.nil?
             raise ArgumentError,
                   "dimension required for DiffNode"
           end
 
+          # Build informative reason message
+          reason = build_difference_reason(node1, node2, diff1, diff2,
+                                           dimension)
+
           diff_node = Canon::Diff::DiffNode.new(
             node1: node1,
             node2: node2,
             dimension: dimension,
-            reason: "#{diff1} vs #{diff2}",
+            reason: reason,
           )
           differences << diff_node
         end
+
+        # Build a human-readable reason for a difference
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param diff1 [String] Difference type for node1
+        # @param diff2 [String] Difference type for node2
+        # @param dimension [Symbol] The dimension of the difference
+        # @return [String] Human-readable reason
+        def build_difference_reason(node1, node2, diff1, diff2, dimension)
+          # 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
+              ns_info = if ns.nil? || ns.empty?
+                          ""
+                        else
+                          " (namespace: #{ns})"
+                        end
+              return "element '#{node.name}'#{ns_info}: #{diff1} vs #{diff2}"
+            end
+          end
+
+          "#{diff1} vs #{diff2}"
+        end
+
+        # Compare namespace declarations (xmlns and xmlns:* attributes)
+        # @param n1 [Object] First node
+        # @param n2 [Object] Second node
+        # @param opts [Hash] Options
+        # @param differences [Array] Array to append differences to
+        # @return [Symbol] Comparison result
+        def compare_namespace_declarations(n1, n2, opts, differences)
+          ns_decls1 = extract_namespace_declarations(n1)
+          ns_decls2 = extract_namespace_declarations(n2)
+
+          # Find missing, extra, and changed namespace declarations
+          missing = ns_decls1.keys - ns_decls2.keys  # In n1 but not n2
+          extra = ns_decls2.keys - ns_decls1.keys    # In n2 but not n1
+          changed = ns_decls1.select do |prefix, uri|
+            ns_decls2[prefix] && ns_decls2[prefix] != uri
+          end.keys
+
+          # If there are any differences, create a DiffNode
+          if missing.any? || extra.any? || changed.any?
+            # Build a descriptive reason
+            reasons = []
+            if missing.any?
+              reasons << "removed: #{missing.map do |p|
+                p.empty? ? 'xmlns' : "xmlns:#{p}"
+              end.join(', ')}"
+            end
+            if extra.any?
+              reasons << "added: #{extra.map do |p|
+                p.empty? ? 'xmlns' : "xmlns:#{p}"
+              end.join(', ')}"
+            end
+            if changed.any?
+              reasons << "changed: #{changed.map do |p|
+                p.empty? ? 'xmlns' : "xmlns:#{p}"
+              end.join(', ')}"
+            end
+
+            add_difference(
+              n1,
+              n2,
+              Comparison::UNEQUAL_ATTRIBUTES,
+              Comparison::UNEQUAL_ATTRIBUTES,
+              :namespace_declarations,
+              opts,
+              differences,
+            )
+            return Comparison::UNEQUAL_ATTRIBUTES
+          end
+
+          Comparison::EQUIVALENT
+        end
+
+        # Extract namespace declarations from a node
+        # @param node [Object] Node to extract namespace declarations from
+        # @return [Hash] Hash of prefix => URI mappings
+        def extract_namespace_declarations(node)
+          declarations = {}
+
+          # Handle Canon::Xml::Node (uses namespace_nodes)
+          if node.respond_to?(:namespace_nodes)
+            node.namespace_nodes.each do |ns|
+              # Skip the implicit xml namespace (always present)
+              next if ns.prefix == "xml" && ns.uri == "http://www.w3.org/XML/1998/namespace"
+
+              prefix = ns.prefix || ""
+              declarations[prefix] = ns.uri
+            end
+            return declarations
+          end
+
+          # Handle Nokogiri/Moxml nodes (use attributes)
+          # Get raw attributes
+          raw_attrs = node.respond_to?(:attribute_nodes) ? node.attribute_nodes : node.attributes
+
+          # Handle Canon::Xml::Node attribute format (array of AttributeNode)
+          if raw_attrs.is_a?(Array)
+            raw_attrs.each do |attr|
+              name = attr.name
+              value = attr.value
+
+              if is_namespace_declaration?(name)
+                # Extract prefix: "xmlns" -> "", "xmlns:xmi" -> "xmi"
+                prefix = name == "xmlns" ? "" : name.split(":", 2)[1]
+                declarations[prefix] = value
+              end
+            end
+          else
+            # Handle Nokogiri and Moxml attribute formats (Hash-like)
+            raw_attrs.each do |key, val|
+              if key.is_a?(String)
+                # Nokogiri format: key=name (String), val=attr object
+                name = key
+                value = val.respond_to?(:value) ? val.value : val.to_s
+              else
+                # Moxml format: key=attr object, val=nil
+                name = key.respond_to?(:name) ? key.name : key.to_s
+                value = key.respond_to?(:value) ? key.value : key.to_s
+              end
+
+              if is_namespace_declaration?(name)
+                # Extract prefix: "xmlns" -> "", "xmlns:xmi" -> "xmi"
+                prefix = name == "xmlns" ? "" : name.split(":", 2)[1]
+                declarations[prefix] = value
+              end
+            end
+          end
+
+          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 is_namespace_declaration?(attr_name)
+          attr_name == "xmlns" || attr_name.start_with?("xmlns:")
+        end
       end
     end
   end