canon 0.2.4 → 0.2.5

data/lib/canon/comparison/xml_node_comparison.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "node_inspector"
+
 module Canon
   module Comparison
     # XML Node Comparison Utilities
@@ -180,13 +182,9 @@ differences)
       # @return [Symbol] Comparison result constant
       def self.dispatch_by_node_type(node1, node2, opts, child_opts,
 diff_children, differences)
-        # 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)
           dispatch_canon_node_type(node1, node2, opts, child_opts,
                                    diff_children, differences)
-        # Moxml/Nokogiri types use .element?, .text?, etc. methods
         else
           dispatch_legacy_node_type(node1, node2, opts, child_opts,
                                     diff_children, differences)
@@ -286,8 +284,8 @@ diff_children, differences)
       def self.same_node_type?(node1, node2)
         return false if node1.class != node2.class
 
-        # For Nokogiri/Canon::Xml nodes, check node type
-        if node1.respond_to?(:node_type) && node2.respond_to?(:node_type)
+        case node1
+        when Canon::Xml::Node, Nokogiri::XML::Node
           node1.node_type == node2.node_type
         else
           true
@@ -305,34 +303,13 @@ diff_children, differences)
       # @param check_children [Boolean] Whether to check child nodes
       # @return [Boolean] true if node is a comment
       def self.comment_node?(node, check_children: false)
-        result = false
-        return true if node.respond_to?(:comment?) && node.comment?
-        return true if node.respond_to?(:node_type) && node.node_type == :comment
-
-        if node.is_a?(Nokogiri::XML::Element) && !node.children.empty? && check_children
-          node.children.each do |child|
-            # Recursively check child nodes for comments
-            # limit depth to avoid infinite recursion
-            # in case of circular structures (if any)
-            if comment_node?(child, check_children: false)
-              result = true
-              break
-            end
-          end
-        end
-        return true if result
-
-        # HTML comments are parsed as TEXT nodes by Nokogiri
-        # Check if this is a text node with HTML comment content
-        if text_node?(node)
-          text = node_text(node)
-          # Strip whitespace and backslashes for comparison
-          # Nokogiri escapes HTML comments as "<\\!-- comment -->" in full documents
-          text_stripped = text.to_s.strip.gsub("\\", "")
-          return true if text_stripped.start_with?("<!--") && text_stripped.end_with?("-->")
-        end
+        return true if NodeInspector.comment_node?(node)
 
-        result
+        if check_children && node.is_a?(Nokogiri::XML::Element) && !node.children.empty?
+          node.children.any? { |child| NodeInspector.comment_node?(child) }
+        else
+          false
+        end
       end
 
       # Check if a node is a text node
@@ -340,24 +317,7 @@ diff_children, differences)
       # @param node [Object] Node to check
       # @return [Boolean] true if node is a text node
       def self.text_node?(node)
-        return false unless node
-
-        # Nokogiri text nodes (XML, HTML4, HTML5) — call element? rather
-        # than respond_to?(:element?), which always returns true for
-        # Nokogiri::XML::Node and made this predicate vacuously false
-        # for every Nokogiri text node. See issue #118.
-        if node.is_a?(Nokogiri::XML::Node)
-          return node.text? && !node.element?
-        end
-
-        # Canon::Xml::Nodes types and other ducktyped nodes.
-        if node.respond_to?(:text?) && node.text? &&
-            !node.respond_to?(:element?)
-          return true
-        end
-
-        # Symbol-style node_type (Canon's own node objects).
-        node.respond_to?(:node_type) && node.node_type == :text
+        NodeInspector.text_node?(node)
       end
 
       # Extract text content from a node
@@ -367,15 +327,7 @@ diff_children, differences)
       def self.node_text(node)
         return "" unless node
 
-        if node.respond_to?(:content)
-          node.content.to_s
-        elsif node.respond_to?(:text)
-          node.text.to_s
-        elsif node.respond_to?(:value)
-          node.value.to_s
-        else
-          ""
-        end
+        NodeInspector.text_content(node)
       end
 
       # Dispatch by Canon::Xml::Node type
@@ -411,21 +363,26 @@ diff_children, differences)
         # Import XmlComparator to use its comparison methods
         require_relative "xml_comparator"
 
-        if node1.respond_to?(:element?) && node1.element?
-          XmlComparator.compare_element_nodes(node1, node2, opts, child_opts,
-                                              diff_children, differences)
-        elsif node1.respond_to?(:text?) && node1.text?
-          XmlComparator.compare_text_nodes(node1, node2, opts, differences)
-        elsif node1.respond_to?(:comment?) && node1.comment?
-          XmlComparator.compare_comment_nodes(node1, node2, opts, differences)
-        elsif node1.respond_to?(:cdata?) && node1.cdata?
-          XmlComparator.compare_text_nodes(node1, node2, opts, differences)
-        elsif node1.respond_to?(:processing_instruction?) && node1.processing_instruction?
-          XmlComparator.compare_processing_instruction_nodes(node1, node2,
-                                                             opts, differences)
-        elsif node1.respond_to?(:root)
+        case node1
+        when Nokogiri::XML::Document
           XmlComparator.compare_document_nodes(node1, node2, opts, child_opts,
                                                diff_children, differences)
+        when Nokogiri::XML::Node
+          if node1.element?
+            XmlComparator.compare_element_nodes(node1, node2, opts, child_opts,
+                                                diff_children, differences)
+          elsif node1.text?
+            XmlComparator.compare_text_nodes(node1, node2, opts, differences)
+          elsif node1.comment?
+            XmlComparator.compare_comment_nodes(node1, node2, opts, differences)
+          elsif node1.cdata?
+            XmlComparator.compare_text_nodes(node1, node2, opts, differences)
+          elsif node1.processing_instruction?
+            XmlComparator.compare_processing_instruction_nodes(node1, node2,
+                                                               opts, differences)
+          else
+            Comparison::EQUIVALENT
+          end
         else
           Comparison::EQUIVALENT
         end
@@ -457,10 +414,11 @@ differences)
       # @param node [Canon::Xml::Node, Object] Node to serialize
       # @return [String] XML string representation
       def self.serialize_node_to_xml(node)
-        if node.is_a?(Canon::Xml::Nodes::RootNode)
+        case node
+        when 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)
+        when Canon::Xml::Nodes::ElementNode
           # Serialize element with attributes and children
           attrs = node.attribute_nodes.map do |a|
             " #{a.name}=\"#{a.value}\""
@@ -474,14 +432,12 @@ differences)
           else
             "<#{node.name}#{attrs}>#{children_xml}</#{node.name}>"
           end
-        elsif node.is_a?(Canon::Xml::Nodes::TextNode)
+        when Canon::Xml::Nodes::TextNode
           node.value
-        elsif node.is_a?(Canon::Xml::Nodes::CommentNode)
+        when Canon::Xml::Nodes::CommentNode
           "<!--#{node.value}-->"
-        elsif node.is_a?(Canon::Xml::Nodes::ProcessingInstructionNode)
+        when Canon::Xml::Nodes::ProcessingInstructionNode
           "<?#{node.target} #{node.data}?>"
-        elsif node.respond_to?(:to_xml)
-          node.to_xml
         else
           node.to_s
         end

data/lib/canon/comparison.rb

@@ -122,6 +122,65 @@ module Canon
     UNEQUAL_TYPES = 15
     UNEQUAL_PRIMITIVES = 16
 
+    # Human-readable labels for the integer comparison-result constants
+    # above.  Used by the diff reason builders so user-facing reason text
+    # never leaks raw numeric codes (e.g. "7 vs 7" — see lutaml/canon#127).
+    # String diff codes (e.g. "position 3" emitted by ChildComparison)
+    # pass through +code_label+ unchanged.
+    CODE_LABELS = {
+      EQUIVALENT => "equivalent",
+      MISSING_ATTRIBUTE => "missing attribute",
+      MISSING_NODE => "missing",
+      UNEQUAL_ATTRIBUTES => "attributes differ",
+      UNEQUAL_COMMENTS => "comments differ",
+      UNEQUAL_DOCUMENTS => "documents differ",
+      UNEQUAL_ELEMENTS => "elements differ",
+      UNEQUAL_NODES_TYPES => "node types differ",
+      UNEQUAL_TEXT_CONTENTS => "text content differs",
+      MISSING_HASH_KEY => "missing hash key",
+      UNEQUAL_HASH_VALUES => "hash values differ",
+      UNEQUAL_HASH_KEY_ORDER => "hash key order differs",
+      UNEQUAL_ARRAY_LENGTHS => "array lengths differ",
+      UNEQUAL_ARRAY_ELEMENTS => "array elements differ",
+      UNEQUAL_TYPES => "types differ",
+      UNEQUAL_PRIMITIVES => "primitives differ",
+    }.freeze
+
+    # Translate a comparison result code (Integer constant or String label
+    # like "position 3") into a human-readable reason fragment.  Unknown
+    # values pass through via +to_s+ as a defensive fallback.
+    #
+    # @param code [Integer, String] Comparison result code
+    # @return [String] Human-readable label
+    def self.code_label(code)
+      return code if code.is_a?(String)
+
+      CODE_LABELS[code] || code.to_s
+    end
+
+    # Build a "diff1 [vs diff2]" reason fragment that never leaks raw
+    # integer constants.  When both codes are equal, returns the single
+    # label (e.g. "elements differ") rather than "elements differ vs
+    # elements differ".  See lutaml/canon#127.
+    #
+    # @param diff1 [Integer, String] First diff code
+    # @param diff2 [Integer, String] Second diff code
+    # @return [String] Reason fragment
+    def self.code_pair_label(diff1, diff2)
+      return code_label(diff1) if diff1 == diff2
+
+      "#{code_label(diff1)} vs #{code_label(diff2)}"
+    end
+
+    # Extract parse-time errors from a parsed-tree or Nokogiri fragment.
+    # Delegates to NodeInspector for cross-backend type dispatch.
+    #
+    # @param node [Object, nil] Parsed node
+    # @return [Array<String>] Parse errors as strings (empty by default)
+    def self.parse_errors_for(node)
+      NodeInspector.parse_errors(node)
+    end
+
     class << self
       # Auto-detect format and compare two objects
       #

data/lib/canon/diff/diff_classifier.rb

@@ -73,6 +73,16 @@ module Canon
           return diff_node
         end
 
+        # :whitespace_adjacency is a report-only re-label of an
+        # asymmetric whitespace mismatch emitted by ChildComparison's
+        # two-cursor walk.  Equivalence behaviour is unchanged — the
+        # underlying mismatch is normative regardless of match options.
+        if diff_node.dimension == :whitespace_adjacency
+          diff_node.formatting = false
+          diff_node.normative = true
+          return diff_node
+        end
+
         # THIRD: Determine if this dimension is normative based on CompareProfile
         # This respects the policy settings (strict/normalize/ignore)
         is_normative = profile.normative_dimension?(diff_node.dimension)
@@ -210,28 +220,21 @@ module Canon
       def extract_text_content(node)
         return nil if node.nil?
 
-        # For TextNode with value attribute (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
-        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 Moxml::Node
+          node.content.to_s
+        when String
+          node
+        else
+          node.to_s
+        end
       rescue StandardError
-        # If extraction fails, return nil (not formatting-only)
         nil
       end
 
@@ -241,25 +244,20 @@ module Canon
       def text_node?(node)
         return false if node.nil?
 
-        # Canon::Xml::Nodes::TextNode
-        return true if node.is_a?(Canon::Xml::Nodes::TextNode)
-
-        # Nokogiri text nodes (node_type returns integer constant like 3)
-        return true if node.respond_to?(:node_type) &&
-          node.node_type.is_a?(Integer) &&
+        case node
+        when Canon::Xml::Nodes::TextNode
+          true
+        when Canon::Xml::Node
+          node.node_type == :text
+        when Nokogiri::XML::Node
           node.node_type == Nokogiri::XML::Node::TEXT_NODE
-
-        # Moxml text nodes (node_type returns symbol)
-        return true if node.respond_to?(:node_type) && node.node_type == :text
-
-        # String
-        return true if node.is_a?(String)
-
-        # Test doubles or objects with text node-like interface
-        # Check if it has a value method (contains text content)
-        return true if node.respond_to?(:value)
-
-        false
+        when Moxml::Node
+          node.text?
+        when String
+          true
+        else
+          false
+        end
       end
     end
   end

data/lib/canon/diff/xml_serialization_formatter.rb

@@ -91,28 +91,20 @@ module Canon
       def self.text_node?(node)
         return false if node.nil?
 
-        # Canon::Xml::Nodes::TextNode
-        return true if node.is_a?(Canon::Xml::Nodes::TextNode)
-
-        # Moxml::Text (check before generic node_type check)
-        return true if node.is_a?(Moxml::Text)
-
-        # Nokogiri text nodes (node_type returns integer constant like 3)
-        return true if node.respond_to?(:node_type) &&
-          node.node_type.is_a?(Integer) &&
+        case node
+        when Canon::Xml::Nodes::TextNode
+          true
+        when Canon::Xml::Node
+          node.node_type == :text
+        when Nokogiri::XML::Node
           node.node_type == Nokogiri::XML::Node::TEXT_NODE
-
-        # Moxml text nodes (node_type returns symbol) - for when using Moxml adapters
-        return true if node.respond_to?(:node_type) && node.node_type == :text
-
-        # String
-        return true if node.is_a?(String)
-
-        # Test doubles or objects with text node-like interface
-        # Check if it has a value method (contains text content)
-        return true if node.respond_to?(:value)
-
-        false
+        when Moxml::Node
+          node.text?
+        when String
+          true
+        else
+          false
+        end
       end
 
       # Extract text content from a node
@@ -121,28 +113,21 @@ module Canon
       def self.extract_text_content(node)
         return nil if node.nil?
 
-        # For TextNode with value attribute (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 content method (try before text, as Moxml::Text.text returns "")
-        return node.content if node.respond_to?(:content)
-
-        # For nodes with text method
-        return node.text if node.respond_to?(:text)
-
-        # 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 Moxml::Node
+          node.content.to_s
+        when String
+          node
+        else
+          node.to_s
+        end
       rescue StandardError
-        # If extraction fails, return nil (not a serialization difference)
         nil
       end
 

data/lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb

@@ -34,6 +34,8 @@ expand_difference: false)
             format_attribute_order_details(diff, use_color)
           when :text_content
             format_text_content_details(diff, use_color, compact: compact)
+          when :whitespace_adjacency
+            format_whitespace_adjacency_details(diff, use_color)
           when :structural_whitespace
             format_structural_whitespace_details(diff, use_color)
           when :comments
@@ -366,18 +368,21 @@ expand_difference: false)
           node1 = extract_node1(diff)
           node2 = extract_node2(diff)
 
+          # Symmetric one-sided rendering for missing/extra text nodes.
+          # When exactly one side is nil, render "(not present)" on that
+          # side and the present side's raw text content (whitespace-
+          # visualised, with a brief parent open-tag hint for context).
+          # Mirrors format_element_structure_details above.  Without this
+          # short-circuit, the ambiguous-pair fallback further down would
+          # serialize the present side's *parent subtree* in full,
+          # producing a misleading diff payload.  See lutaml/canon#125.
+          if node1.nil? ^ node2.nil?
+            return format_text_content_one_sided(node1, node2, use_color)
+          end
+
           text1 = NodeUtils.node_to_display(node1, compact: compact)
           text2 = NodeUtils.node_to_display(node2, compact: compact)
 
-          # Handle cases where one node is missing (e.g. text added or removed)
-          if node1.nil? || node2.nil?
-            if node1.nil?
-              text2 = NodeUtils.node_to_display(node2, compact: compact)
-            else
-              text1 = NodeUtils.node_to_display(node1, compact: compact)
-            end
-          end
-
           if NodeUtils.inside_preserve_element?(node1) || NodeUtils.inside_preserve_element?(node2)
             detail1 = ColorHelper.colorize(
               TextUtils.visualize_whitespace(text1), :red, use_color
@@ -432,8 +437,113 @@ expand_difference: false)
           [detail1, detail2, changes]
         end
 
+        # Whether a node is an element (Canon or Nokogiri), used to
+        # detect element-shaped diffs that have been misclassified as
+        # :text_content and route them to element-structure rendering.
+        # See lutaml/canon#125 follow-up.
+        def self.present_is_element?(node)
+          return false unless node
+
+          case node
+          when Canon::Xml::Node
+            node.node_type == :element
+          when Nokogiri::XML::Node
+            node.element?
+          else
+            false
+          end
+        end
+
+        # Render a one-sided text-content diff (one node nil, the other a
+        # text node).  Mirrors the +has1+/+has2+ branches of
+        # +format_element_structure_details+: "(not present)" on the nil
+        # side, the present side's raw text content (whitespace-visualised
+        # and quoted) plus a brief parent open-tag hint for context.
+        #
+        # @param node1 [Object, nil] First node (nil if removed)
+        # @param node2 [Object, nil] Second node (nil if added)
+        # @param use_color [Boolean] Whether to apply ANSI colours
+        # @return [Array<String>] Tuple of [detail1, detail2, changes]
+        def self.format_text_content_one_sided(node1, node2, use_color)
+          require_relative "color_helper"
+          require_relative "node_utils"
+          require_relative "text_utils"
+
+          present = node1 || node2
+
+          # Defensive: if a one-sided text-content diff carries an
+          # *element* on the present side (e.g. because an upstream
+          # comparator misclassified an element orphan as
+          # :text_content), delegate to the element-structure
+          # formatter rather than rendering the element as +text ""+.
+          # The construction-side fix in lutaml/canon#125 follow-up
+          # removes the immediate failure mode, but other paths could
+          # still misclassify and the formatter must produce a
+          # best-effort element representation, never +text ""+.
+          if present_is_element?(present)
+            return format_element_structure_details(
+              { node1: node1, node2: node2 }, use_color
+            )
+          end
+
+          removed = node2.nil?
+
+          raw     = NodeUtils.raw_text_value(present)
+          visible = TextUtils.visualize_whitespace(raw)
+          parent  = NodeUtils.parent_of(present)
+          context = parent ? " in #{NodeUtils.serialize_open_tag(parent)}" : ""
+          present_str = "text \"#{visible}\"#{context}"
+
+          if removed
+            detail1 = ColorHelper.colorize(present_str, :red, use_color)
+            detail2 = ColorHelper.colorize("(not present)", :green, use_color)
+            changes = "Text removed: #{detail1}"
+          else
+            detail1 = ColorHelper.colorize("(not present)", :red, use_color)
+            detail2 = ColorHelper.colorize(present_str, :green, use_color)
+            changes = "Text added: #{detail2}"
+          end
+
+          [detail1, detail2, changes]
+        end
+
         # Format structural whitespace differences
         #
+        # Format a :whitespace_adjacency diff (#137).
+        #
+        # @param diff [DiffNode, Hash] Difference node
+        # @param use_color [Boolean] Whether to use colors
+        # @return [Array] Tuple of [detail1, detail2, changes]
+        def self.format_whitespace_adjacency_details(diff, use_color)
+          require_relative "color_helper"
+          require_relative "node_utils"
+          require_relative "text_utils"
+
+          node1 = extract_node1(diff)
+          node2 = extract_node2(diff)
+
+          text1 = NodeUtils.get_node_text(node1).to_s
+          text2 = NodeUtils.get_node_text(node2).to_s
+
+          detail1 = ColorHelper.colorize(
+            "\"#{TextUtils.visualize_whitespace(text1)}\"",
+            :red, use_color
+          )
+          detail2 = ColorHelper.colorize(
+            "\"#{TextUtils.visualize_whitespace(text2)}\"",
+            :green, use_color
+          )
+
+          reason = if diff.is_a?(Canon::Diff::DiffNode)
+                     diff.reason
+                   else
+                     diff.is_a?(Hash) ? diff[:reason] : nil
+                   end
+          changes = reason.to_s
+
+          [detail1, detail2, changes]
+        end
+
         # @param diff [DiffNode, Hash] Difference node
         # @param use_color [Boolean] Whether to use colors
         # @return [Array] Tuple of [detail1, detail2, changes]