canon 0.1.7 → 0.1.8

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

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    module XmlComparatorHelpers
+      # Child comparison service for XML nodes
+      #
+      # Handles comparison of child nodes using both semantic matching (ElementMatcher)
+      # and simple positional comparison. Delegates back to the comparator for
+      # individual node comparisons.
+      #
+      # This module encapsulates the complex child comparison logic, making the
+      # main XmlComparator cleaner and more maintainable.
+      module ChildComparison
+        class << self
+          # 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.
+          #
+          # @param node1 [Object] First parent node
+          # @param node2 [Object] Second parent node
+          # @param comparator [XmlComparator] The comparator instance for 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)
+            children1 = comparator.send(:filter_children, node1.children, opts)
+            children2 = comparator.send(:filter_children, node2.children, opts)
+
+            # 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)
+            if can_use_element_matcher?(children1, children2)
+              use_element_matcher_comparison(children1, children2, node1, comparator,
+                                             opts, child_opts, diff_children, differences)
+            else
+              use_positional_comparison(children1, children2, node1, comparator,
+                                        opts, child_opts, diff_children, differences)
+            end
+          end
+
+          private
+
+          # Check if ElementMatcher can be used for these children
+          #
+          # ElementMatcher expects Canon::Xml::DataModel nodes with .node_type
+          # method that returns symbols, and only works with element nodes.
+          def can_use_element_matcher?(children1, children2)
+            !children1.empty? && !children2.empty? &&
+              children1.all? { |c| c.is_a?(Canon::Xml::Node) && c.node_type == :element } &&
+              children2.all? { |c| c.is_a?(Canon::Xml::Node) && c.node_type == :element }
+          end
+
+          # Use ElementMatcher for semantic comparison
+          def use_element_matcher_comparison(children1, children2, parent_node, comparator,
+                                             opts, child_opts, diff_children, differences)
+            require_relative "../../xml/element_matcher"
+            require_relative "../../xml/nodes/root_node"
+
+            # Create temporary RootNode wrappers
+            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
+            matches = matches.select do |m|
+              (m.elem1.nil? || children1.include?(m.elem1)) &&
+                (m.elem2.nil? || children2.include?(m.elem2))
+            end
+
+            # If no matches and children exist, they're all different
+            if matches.empty? && (!children1.empty? || !children2.empty?)
+              comparator.send(:add_difference, parent_node, parent_node,
+                              Comparison::MISSING_NODE, Comparison::MISSING_NODE,
+                              :text_content, opts, differences)
+              return Comparison::UNEQUAL_ELEMENTS
+            end
+
+            process_matches(matches, children1, children2, parent_node, comparator,
+                            opts, child_opts, diff_children, differences)
+          end
+
+          # Process ElementMatcher results
+          def process_matches(matches, _children1, _children2, _parent_node, comparator,
+                             opts, child_opts, diff_children, differences)
+            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
+                    comparator.send(:add_difference, match.elem1, match.elem2,
+                                    "position #{match.pos1}", "position #{match.pos2}",
+                                    :element_position, opts, differences)
+                    all_equivalent = false if position_behavior == :strict
+                  end
+                end
+
+                # Compare the matched elements for content/attribute differences
+                result = comparator.send(:compare_nodes, match.elem1, match.elem2,
+                                         child_opts, child_opts, diff_children, differences)
+                all_equivalent = false unless result == Comparison::EQUIVALENT
+
+              when :deleted
+                # Element present in first tree but not second
+                comparator.send(:add_difference, match.elem1, nil,
+                                Comparison::MISSING_NODE, Comparison::MISSING_NODE,
+                                :element_structure, opts, differences)
+                all_equivalent = false
+
+              when :inserted
+                # Element present in second tree but not first
+                comparator.send(:add_difference, nil, match.elem2,
+                                Comparison::MISSING_NODE, Comparison::MISSING_NODE,
+                                :element_structure, opts, differences)
+                all_equivalent = false
+              end
+            end
+
+            all_equivalent ? Comparison::EQUIVALENT : Comparison::UNEQUAL_ELEMENTS
+          end
+
+          # Use simple positional comparison for children
+          def use_positional_comparison(children1, children2, parent_node, comparator,
+                                        opts, child_opts, diff_children, differences)
+            # Length check
+            unless children1.length == children2.length
+              dimension = determine_dimension_for_mismatch(children1, children2, comparator)
+              comparator.send(:add_difference, parent_node, parent_node,
+                              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 = comparator.send(:compare_nodes, child1, child2,
+                                             child_opts, child_opts, diff_children, differences)
+              result = child_result unless child_result == Comparison::EQUIVALENT
+            end
+
+            result
+          end
+
+          # Determine dimension for length mismatch
+          def determine_dimension_for_mismatch(children1, children2, comparator)
+            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 = comparator.send(:determine_node_dimension, children2[i])
+                break
+              elsif i >= children2.length
+                # Extra child in children1
+                dimension = comparator.send(:determine_node_dimension, children1[i])
+                break
+              elsif !comparator.send(:same_node_type?, children1[i], children2[i])
+                # Different node types at same position
+                dimension = comparator.send(:determine_node_dimension, children1[i])
+                break
+              end
+            end
+
+            dimension
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "../../diff/diff_node"
+require_relative "../../diff/path_builder"
+require_relative "../../diff/node_serializer"
+
+module Canon
+  module Comparison
+    # Builder for creating enriched DiffNode objects
+    # Handles path building, serialization, and attribute extraction
+    class DiffNodeBuilder
+      # Build an enriched DiffNode
+      #
+      # @param node1 [Object, nil] First node
+      # @param node2 [Object, nil] Second node
+      # @param diff1 [String] Difference type for node1
+      # @param diff2 [String] Difference type for node2
+      # @param dimension [Symbol] The match dimension causing this difference
+      # @return [DiffNode, nil] Enriched DiffNode or nil if dimension is nil
+      def self.build(node1:, node2:, diff1:, diff2:, dimension:, **_opts)
+        # Validate dimension is required
+        if dimension.nil?
+          raise ArgumentError,
+                "dimension required for DiffNode"
+        end
+
+        # Build informative reason message
+        reason = build_reason(node1, node2, diff1, diff2, dimension)
+
+        # Enrich with path, serialized content, and attributes for Stage 4 rendering
+        metadata = enrich_metadata(node1, node2)
+
+        Canon::Diff::DiffNode.new(
+          node1: node1,
+          node2: node2,
+          dimension: dimension,
+          reason: reason,
+          **metadata,
+        )
+      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 self.build_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
+
+      # Enrich DiffNode with canonical path, serialized content, and attributes
+      # This extracts presentation-ready metadata from nodes for Stage 4 rendering
+      #
+      # @param node1 [Object, nil] First node
+      # @param node2 [Object, nil] Second node
+      # @return [Hash] Enriched metadata hash
+      def self.enrich_metadata(node1, node2)
+        {
+          path: build_path(node1 || node2),
+          serialized_before: serialize(node1),
+          serialized_after: serialize(node2),
+          attributes_before: extract_attributes(node1),
+          attributes_after: extract_attributes(node2),
+        }
+      end
+
+      # Build canonical path for a node
+      #
+      # @param node [Object] Node to build path for
+      # @return [String, nil] Canonical path with ordinal indices
+      def self.build_path(node)
+        return nil if node.nil?
+
+        Canon::Diff::PathBuilder.build(node, format: :document)
+      end
+
+      # Serialize a node to string for display
+      #
+      # @param node [Object, nil] Node to serialize
+      # @return [String, nil] Serialized content
+      def self.serialize(node)
+        return nil if node.nil?
+
+        Canon::Diff::NodeSerializer.serialize(node)
+      end
+
+      # Extract attributes from a node as a normalized hash
+      #
+      # @param node [Object, nil] Node to extract attributes from
+      # @return [Hash, nil] Normalized attributes hash
+      def self.extract_attributes(node)
+        return nil if node.nil?
+
+        Canon::Diff::NodeSerializer.extract_attributes(node)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    module XmlComparatorHelpers
+      # Namespace declaration comparison logic
+      # Handles comparison of xmlns and xmlns:* attributes
+      class NamespaceComparator
+        # Compare namespace declarations between two nodes
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param opts [Hash] Comparison options
+        # @param differences [Array] Array to append differences to
+        # @return [Symbol] Comparison result
+        def self.compare(node1, node2, opts, differences)
+          ns_decls1 = extract_declarations(node1)
+          ns_decls2 = extract_declarations(node2)
+
+          # Find missing, extra, and changed namespace declarations
+          missing = ns_decls1.keys - ns_decls2.keys  # In node1 but not node2
+          extra = ns_decls2.keys - ns_decls1.keys    # In node2 but not node1
+          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?
+            add_namespace_difference(node1, node2, missing, extra, changed,
+                                     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 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
+
+          # Handle Nokogiri/Moxml nodes (use 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)
+            extract_from_array_attributes(raw_attrs, declarations)
+          else
+            # Handle Nokogiri and Moxml attribute formats (Hash-like)
+            extract_from_hash_attributes(raw_attrs, declarations)
+          end
+
+          declarations
+        end
+
+        # Extract from Canon::Xml::Node namespace_nodes
+        #
+        # @param namespace_nodes [Array] Array of NamespaceNode objects
+        # @param declarations [Hash] Output hash to populate
+        # @return [Hash] Declarations hash
+        def self.extract_from_namespace_nodes(namespace_nodes, declarations)
+          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
+
+          declarations
+        end
+
+        # Extract from array-format attributes
+        #
+        # @param raw_attrs [Array] Array of AttributeNode objects
+        # @param declarations [Hash] Output hash to populate
+        # @return [Hash] Declarations hash
+        def self.extract_from_array_attributes(raw_attrs, declarations)
+          raw_attrs.each do |attr|
+            name = attr.name
+            value = attr.value
+
+            if namespace_declaration?(name)
+              # Extract prefix: "xmlns" -> "", "xmlns:xmi" -> "xmi"
+              prefix = name == "xmlns" ? "" : name.split(":", 2)[1]
+              declarations[prefix] = value
+            end
+          end
+
+          declarations
+        end
+
+        # Extract from hash-format attributes
+        #
+        # @param raw_attrs [Hash] Hash-like attributes
+        # @param declarations [Hash] Output hash to populate
+        # @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
+
+            if namespace_declaration?(name)
+              value = if val.respond_to?(:value)
+                        val.value
+                      else
+                        val.to_s
+                      end
+
+              # Extract prefix: "xmlns" -> "", "xmlns:xmi" -> "xmi"
+              prefix = name == "xmlns" ? "" : name.split(":", 2)[1]
+              declarations[prefix] = value
+            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 self.namespace_declaration?(attr_name)
+          attr_name == "xmlns" || attr_name.start_with?("xmlns:")
+        end
+
+        # Add a namespace declaration difference
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param missing [Array] Missing prefixes
+        # @param extra [Array] Extra prefixes
+        # @param changed [Array] Changed prefixes
+        # @param opts [Hash] Options
+        # @param differences [Array] Array to append difference to
+        def self.add_namespace_difference(node1, node2, missing, extra,
+changed, opts, differences)
+          # 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
+
+          # Import DiffNodeBuilder to avoid circular dependency
+          require_relative "diff_node_builder"
+
+          diff_node = DiffNodeBuilder.build(
+            node1: node1,
+            node2: node2,
+            diff1: Comparison::UNEQUAL_ATTRIBUTES,
+            diff2: Comparison::UNEQUAL_ATTRIBUTES,
+            dimension: :namespace_declarations,
+            **opts,
+          )
+          differences << diff_node if diff_node
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../../xml/c14n"
+
+module Canon
+  module Comparison
+    module XmlComparatorHelpers
+      # Node parser with preprocessing support
+      # Handles conversion of strings and various node types to Canon::Xml::Node
+      class NodeParser
+        # Parse a node from string or return as-is
+        # Applies preprocessing transformation before parsing if specified
+        #
+        # @param node [String, Object] Node to parse
+        # @param preprocessing [Symbol] Preprocessing mode (:none, :normalize, :c14n, :format)
+        # @return [Canon::Xml::Node] Parsed node
+        def self.parse(node, preprocessing = :none)
+          # 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)
+            return convert_from_node(node)
+          end
+
+          # Apply preprocessing to XML string before parsing
+          xml_string = apply_preprocessing(node, preprocessing)
+
+          # Use Canon::Xml::DataModel for parsing to get Canon::Xml::Node instances
+          Canon::Xml::DataModel.from_xml(xml_string)
+        end
+
+        # Apply preprocessing transformation to XML string
+        #
+        # @param xml_string [String] XML string to preprocess
+        # @param preprocessing [Symbol] Preprocessing mode
+        # @return [String] Preprocessed XML string
+        def self.apply_preprocessing(xml_string, preprocessing)
+          case preprocessing
+          when :normalize
+            # Normalize whitespace: collapse runs, trim lines
+            xml_string.lines.map(&:strip).reject(&:empty?).join("\n")
+          when :c14n
+            # Canonicalize the XML
+            Canon::Xml::C14n.canonicalize(xml_string, with_comments: false)
+          when :format
+            # Pretty format the XML
+            Canon.format(xml_string, :xml)
+          else
+            # :none or unrecognized - use as-is
+            xml_string
+          end
+        end
+
+        # Convert from Nokogiri/Moxml node to Canon::Xml::Node
+        #
+        # @param node [Object] Nokogiri or Moxml node
+        # @return [Canon::Xml::Node] Converted node
+        def self.convert_from_node(node)
+          # 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
+          Canon::Xml::DataModel.from_xml(xml_str)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    module XmlComparatorHelpers
+      # Node type comparison strategy for XML nodes
+      #
+      # 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.
+      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)
+              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)
+            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)
+            when :element
+              comparator.send(:compare_element_nodes, node1, node2, opts, child_opts,
+                              diff_children, differences)
+            when :text
+              comparator.send(:compare_text_nodes, node1, node2, opts, differences)
+            when :comment
+              comparator.send(:compare_comment_nodes, node1, node2, opts, differences)
+            when :cdata
+              comparator.send(:compare_text_nodes, node1, node2, opts, differences)
+            when :processing_instruction
+              comparator.send(: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)
+            else
+              Comparison::EQUIVALENT
+            end
+          end
+        end
+      end
+    end
+  end
+end