canon 0.1.9 → 0.1.11

data/lib/canon/comparison/xml_comparator.rb

@@ -568,9 +568,201 @@ differences)
             end
           end
 
+          # For attribute presence differences, show what attributes differ
+          if dimension == :attribute_presence
+            attrs1 = extract_attributes(node1)
+            attrs2 = extract_attributes(node2)
+            return build_attribute_diff_reason(attrs1, attrs2)
+          end
+
+          # For text content differences, show the actual text (truncated if needed)
+          if dimension == :text_content
+            text1 = extract_text_from_node(node1)
+            text2 = extract_text_from_node(node2)
+            return build_text_diff_reason(text1, text2)
+          end
+
           "#{diff1} vs #{diff2}"
         end
 
+        # Build a clear reason message for attribute presence differences
+        #
+        # @param attrs1 [Hash, nil] First node's attributes
+        # @param attrs2 [Hash, nil] Second node's attributes
+        # @return [String] Clear explanation of the attribute difference
+        def build_attribute_diff_reason(attrs1, attrs2)
+          return "#{attrs1&.keys&.size || 0} vs #{attrs2&.keys&.size || 0} attributes" unless attrs1 && attrs2
+
+          require "set"
+          keys1 = attrs1.keys.to_set
+          keys2 = attrs2.keys.to_set
+
+          only_in_first = keys1 - keys2
+          only_in_second = keys2 - keys1
+          common = keys1 & keys2
+
+          # Check if values differ for common keys
+          different_values = common.reject { |k| attrs1[k] == attrs2[k] }
+
+          parts = []
+          parts << "only in first: #{only_in_first.to_a.sort.join(', ')}" if only_in_first.any?
+          parts << "only in second: #{only_in_second.to_a.sort.join(', ')}" if only_in_second.any?
+          parts << "different values: #{different_values.sort.join(', ')}" if different_values.any?
+
+          if parts.empty?
+            "#{keys1.size} vs #{keys2.size} attributes (same names)"
+          else
+            parts.join("; ")
+          end
+        end
+
+        # Extract text from a node for diff reason
+        #
+        # @param node [Object, nil] Node to extract text from
+        # @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
+        rescue StandardError
+          nil
+        end
+
+        # Build a clear reason message for text content differences
+        #
+        # @param text1 [String, nil] First text content
+        # @param text2 [String, nil] Second text content
+        # @return [String] Clear explanation of the text difference
+        def build_text_diff_reason(text1, text2)
+          # Handle nil cases
+          return "missing vs '#{truncate_text(text2)}'" if text1.nil? && text2
+          return "'#{truncate_text(text2)}' vs missing" if text1 && text2.nil?
+          return "both missing" if text1.nil? && text2.nil?
+
+          # Check if both are whitespace-only
+          if whitespace_only?(text1) && whitespace_only?(text2)
+            return "whitespace: #{describe_whitespace(text1)} vs #{describe_whitespace(text2)}"
+          end
+
+          # Show text with visible whitespace markers
+          # Use escaped representations for clarity: \n for newline, \t for tab, · for spaces
+          vis1 = visualize_whitespace(text1)
+          vis2 = visualize_whitespace(text2)
+
+          "Text: \"#{vis1}\" vs \"#{vis2}\""
+        end
+
+        # Check if text is only whitespace
+        #
+        # @param text [String] Text to check
+        # @return [Boolean] true if whitespace-only
+        def whitespace_only?(text)
+          return false if text.nil?
+
+          text.to_s.strip.empty?
+        end
+
+        # Make whitespace visible in text content
+        # Uses the existing character visualization map from DiffFormatter (single source of truth)
+        #
+        # @param text [String] Text to visualize
+        # @return [String] Text with visible whitespace markers
+        def visualize_whitespace(text)
+          return "" if text.nil?
+
+          # Use the character map loader as the single source of truth
+          viz_map = character_visualization_map
+
+          # Replace each character with its visualization
+          text.chars.map { |char| viz_map[char] || char }.join
+        end
+
+        # Get the character visualization map (lazy-loaded to avoid circular dependency)
+        #
+        # @return [Hash] Character to visualization symbol mapping
+        def character_visualization_map
+          @character_visualization_map ||= begin
+            # Load the YAML file directly to avoid circular dependency
+            require "yaml"
+            lib_root = File.expand_path("../..", __dir__)
+            yaml_path = File.join(lib_root,
+                                  "canon/diff_formatter/character_map.yml")
+            data = YAML.load_file(yaml_path)
+
+            # Build visualization map from the YAML data
+            visualization_map = {}
+            data["characters"].each do |char_data|
+              # Get the character from either unicode code point or character field
+              char = if char_data["unicode"]
+                       # Convert hex string to character
+                       [char_data["unicode"].to_i(16)].pack("U")
+                     else
+                       # Use character field directly (handles \n, \t, etc.)
+                       char_data["character"]
+                     end
+
+              vis = char_data["visualization"]
+              visualization_map[char] = vis
+            end
+
+            visualization_map
+          end
+        end
+
+        # Describe whitespace content in a readable way
+        #
+        # @param text [String] Whitespace text
+        # @return [String] Description like "4 chars (2 newlines, 2 spaces)"
+        def describe_whitespace(text)
+          return "0 chars" if text.nil? || text.empty?
+
+          char_count = text.length
+          newline_count = text.count("\n")
+          space_count = text.count(" ")
+          tab_count = text.count("\t")
+
+          parts = []
+          parts << "#{newline_count} newlines" if newline_count.positive?
+          parts << "#{space_count} spaces" if space_count.positive?
+          parts << "#{tab_count} tabs" if tab_count.positive?
+
+          description = parts.join(", ")
+          "#{char_count} chars (#{description})"
+        end
+
+        # Truncate text for display in reason messages
+        #
+        # @param text [String] Text to truncate
+        # @param max_length [Integer] Maximum length
+        # @return [String] Truncated text
+        def truncate_text(text, max_length = 40)
+          return "" if text.nil?
+
+          text = text.to_s
+          return text if text.length <= max_length
+
+          "#{text[0...max_length]}..."
+        end
+
         # Compare namespace declarations (xmlns and xmlns:* attributes)
         # Delegates to XmlComparatorHelpers::NamespaceComparator
         def compare_namespace_declarations(n1, n2, opts, differences)

data/lib/canon/config/env_schema.rb

@@ -14,6 +14,9 @@ module Canon
         show_diffs: :symbol,
         verbose_diff: :boolean,
         algorithm: :symbol,
+        show_raw_inputs: :boolean,
+        show_preprocessed_inputs: :boolean,
+        show_line_numbered_inputs: :boolean,
 
         # MatchConfig attributes
         profile: :symbol,
@@ -42,7 +45,8 @@ module Canon
 
         def all_diff_attributes
           %i[mode use_color context_lines grouping_lines show_diffs
-             verbose_diff algorithm max_file_size max_node_count max_diff_lines]
+             verbose_diff algorithm show_raw_inputs show_preprocessed_inputs
+             show_line_numbered_inputs max_file_size max_node_count max_diff_lines]
         end
 
         def all_match_attributes

data/lib/canon/config.rb

@@ -221,6 +221,30 @@ module Canon
         @resolver.set_programmatic(:verbose_diff, value)
       end
 
+      def show_raw_inputs
+        @resolver.resolve(:show_raw_inputs)
+      end
+
+      def show_raw_inputs=(value)
+        @resolver.set_programmatic(:show_raw_inputs, value)
+      end
+
+      def show_preprocessed_inputs
+        @resolver.resolve(:show_preprocessed_inputs)
+      end
+
+      def show_preprocessed_inputs=(value)
+        @resolver.set_programmatic(:show_preprocessed_inputs, value)
+      end
+
+      def show_line_numbered_inputs
+        @resolver.resolve(:show_line_numbered_inputs)
+      end
+
+      def show_line_numbered_inputs=(value)
+        @resolver.set_programmatic(:show_line_numbered_inputs, value)
+      end
+
       def algorithm
         @resolver.resolve(:algorithm)
       end
@@ -266,6 +290,9 @@ module Canon
           show_diffs: show_diffs,
           verbose_diff: verbose_diff,
           diff_algorithm: algorithm,
+          show_raw_inputs: show_raw_inputs,
+          show_preprocessed_inputs: show_preprocessed_inputs,
+          show_line_numbered_inputs: show_line_numbered_inputs,
           max_file_size: max_file_size,
           max_node_count: max_node_count,
           max_diff_lines: max_diff_lines,
@@ -283,6 +310,9 @@ module Canon
           show_diffs: :all,
           verbose_diff: false,
           algorithm: :dom,
+          show_raw_inputs: false,
+          show_preprocessed_inputs: false,
+          show_line_numbered_inputs: false,
           max_file_size: 5_242_880, # 5MB in bytes
           max_node_count: 10_000,   # Maximum nodes in tree
           max_diff_lines: 10_000,   # Maximum diff output lines

data/lib/canon/diff/diff_classifier.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "formatting_detector"
+require_relative "xml_serialization_formatter"
 require_relative "../comparison/compare_profile"
 require_relative "../comparison/whitespace_sensitivity"
 
@@ -8,6 +9,11 @@ module Canon
   module Diff
     # Classifies DiffNodes as normative (affects equivalence) or informative (doesn't affect equivalence)
     # based on the match options in effect
+    #
+    # Classification hierarchy (three distinct kinds of differences):
+    # 1. Serialization formatting: XML syntax differences (always non-normative)
+    # 2. Content formatting: Whitespace differences in content (non-normative when normalized)
+    # 3. Normative: Semantic content differences (affect equivalence)
     class DiffClassifier
       attr_reader :match_options, :profile
 
@@ -25,11 +31,20 @@ module Canon
 
       # Classify a single DiffNode as normative or informative
       # Hierarchy: formatting-only < informative < normative
-      # CompareProfile determines base classification, FormattingDetector refines informative differences
+      # CompareProfile determines base classification, XmlSerializationFormatter handles serialization formatting
       # @param diff_node [DiffNode] The diff node to classify
       # @return [DiffNode] The same diff node with normative/formatting attributes set
       def classify(diff_node)
-        # SPECIAL CASE: text_content with :normalize behavior
+        # FIRST: Check for XML serialization-level formatting differences
+        # These are ALWAYS non-normative (formatting-only) regardless of match options
+        # Examples: self-closing tags (<tag/>) vs explicit closing tags (<tag></tag>)
+        if XmlSerializationFormatter.serialization_formatting?(diff_node)
+          diff_node.formatting = true
+          diff_node.normative = false
+          return diff_node
+        end
+
+        # SECOND: Handle content-level formatting for text_content with :normalize behavior
         # When text_content is :normalize and the difference is formatting-only,
         # it should be marked as non-normative (informative)
         # This ensures that verbose and non-verbose modes give consistent results
@@ -38,7 +53,7 @@ module Canon
         # (like <pre>, <code>, <textarea> in HTML), don't apply formatting detection
         # because whitespace should be preserved in these elements
         #
-        # This check must come FIRST, before normative_dimension? is called,
+        # This check must come BEFORE normative_dimension? is called,
         # because normative_dimension? returns true for text_content: :normalize
         # (since the dimension affects equivalence), which would prevent formatting
         # detection from being applied.
@@ -51,11 +66,11 @@ module Canon
           return diff_node
         end
 
-        # FIRST: Determine if this dimension is normative based on CompareProfile
+        # 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)
 
-        # SECOND: Check if FormattingDetector should be consulted
+        # FOURTH: Check if FormattingDetector should be consulted for non-normative dimensions
         # Only check for formatting-only when dimension is NOT normative
         # This ensures strict mode differences remain normative
         should_check_formatting = !is_normative &&
@@ -68,7 +83,7 @@ module Canon
           return diff_node
         end
 
-        # THIRD: Apply the normative determination from CompareProfile
+        # FIFTH: Apply the normative determination from CompareProfile
         diff_node.formatting = false
         diff_node.normative = is_normative
 
@@ -127,33 +142,6 @@ module Canon
         normalized1 == normalized2 && text1 != text2
       end
 
-      # Check if a node is a text node
-      # @param node [Object] The node to check
-      # @return [Boolean] true if the node is a text node
-      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) &&
-                       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
-      end
-
       # Check if the text node is inside a whitespace-sensitive element
       # @param diff_node [DiffNode] The diff node to check
       # @return [Boolean] true if inside a whitespace-sensitive element
@@ -200,6 +188,33 @@ module Canon
         # If extraction fails, return nil (not formatting-only)
         nil
       end
+
+      # Check if a node is a text node
+      # @param node [Object] The node to check
+      # @return [Boolean] true if the node is a text node
+      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) &&
+          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
+      end
     end
   end
 end

data/lib/canon/diff/xml_serialization_formatter.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Detects and classifies XML serialization-level formatting differences.
+    #
+    # Serialization-level formatting differences are differences in XML syntax
+    # that do not affect the semantic content of the document. These differences
+    # arise from different valid ways to serialize the same semantic content.
+    #
+    # These differences are ALWAYS non-normative (formatting-only) regardless
+    # of match options, because they are purely syntactic variations.
+    #
+    # Examples:
+    # - Self-closing vs explicit closing tags: <tag/> vs <tag></tag>
+    # - Attribute quote style: attr="value" vs attr='value' (parser-normalized)
+    # - Whitespace within tags: <tag a="1" b="2"> vs <tag a="1"  b="2"> (parser-normalized)
+    #
+    # Note: Some serialization differences are normalized away by XML parsers
+    # (attribute quotes, tag spacing). This class focuses on differences that
+    # survive parsing and comparison, such as self-closing vs explicit closing.
+    class XmlSerializationFormatter
+      # Detect if a diff node represents an XML serialization formatting difference.
+      #
+      # Serialization formatting differences are ALWAYS non-normative because they
+      # represent different valid serializations of the same semantic content.
+      #
+      # @param diff_node [DiffNode] The diff node to check
+      # @return [Boolean] true if this is a serialization formatting difference
+      def self.serialization_formatting?(diff_node)
+        # Currently only handles text_content dimension
+        # Future: add detection for other dimensions
+        return false unless diff_node.dimension == :text_content
+
+        empty_text_content_serialization_diff?(diff_node)
+      end
+
+      # Check if a text_content difference is from XML serialization format.
+      #
+      # Specifically detects self-closing tags (<tag/>) vs explicit closing tags
+      # (<tag></tag>), which create different text node structures:
+      # - Self-closing: no text node (nil)
+      # - Explicit closing: empty or whitespace-only text node ("", " ", "\n", etc.)
+      #
+      # Per XML standards, these forms are semantically equivalent.
+      #
+      # @param diff_node [DiffNode] The diff node to check
+      # @return [Boolean] true if this is a serialization formatting difference
+      def self.empty_text_content_serialization_diff?(diff_node)
+        return false unless diff_node.dimension == :text_content
+
+        node1 = diff_node.node1
+        node2 = diff_node.node2
+
+        # Both nodes are nil - no actual difference, not a serialization formatting diff
+        return false if node1.nil? && node2.nil?
+
+        # Only one is nil (e.g., one doc has self-closing, other has text)
+        # If the non-nil one is blank, it's still serialization formatting
+        if node1.nil? || node2.nil?
+          non_nil = node1 || node2
+          return false unless text_node?(non_nil)
+
+          text = extract_text_content(non_nil)
+          return blank?(text)
+        end
+
+        # Both must be text nodes
+        return false unless text_node?(node1) && text_node?(node2)
+
+        text1 = extract_text_content(node1)
+        text2 = extract_text_content(node2)
+
+        # Check if both texts are blank/whitespace-only
+        # This indicates self-closing vs explicit closing tag syntax
+        blank?(text1) && blank?(text2)
+      end
+
+      # Check if a value is blank (nil or whitespace-only)
+      # @param value [String, nil] Value to check
+      # @return [Boolean] true if blank
+      def self.blank?(value)
+        value.nil? ||
+          (value.respond_to?(:empty?) && value.empty?) ||
+          (value.respond_to?(:strip) && value.strip.empty?)
+      end
+
+      # Check if a node is a text node
+      # @param node [Object] The node to check
+      # @return [Boolean] true if the node is a text node
+      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) &&
+          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
+      end
+
+      # Extract text content from a node
+      # @param node [Object] The node to extract text from
+      # @return [String, nil] The text content or nil
+      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
+      rescue StandardError
+        # If extraction fails, return nil (not a serialization difference)
+        nil
+      end
+
+      private_class_method :blank?, :text_node?, :extract_text_content,
+                           :empty_text_content_serialization_diff?
+    end
+  end
+end