canon 0.1.7 → 0.1.9

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

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    module XmlComparatorHelpers
+      # Attribute comparison logic
+      # Handles comparison of attribute sets with filtering and ordering
+      class AttributeComparator
+        # Compare attribute sets 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)
+          # Get attributes using the appropriate method for each node type
+          raw_attrs1 = node1.respond_to?(:attribute_nodes) ? node1.attribute_nodes : node1.attributes
+          raw_attrs2 = node2.respond_to?(:attribute_nodes) ? node2.attribute_nodes : node2.attributes
+
+          attrs1 = XmlComparatorHelpers::AttributeFilter.filter(raw_attrs1,
+                                                                opts)
+          attrs2 = XmlComparatorHelpers::AttributeFilter.filter(raw_attrs2,
+                                                                opts)
+
+          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
+            compare_strict_order(node1, node2, attrs1, attrs2, keys1, keys2, opts,
+                                 differences)
+          else
+            compare_flexible_order(node1, node2, attrs1, attrs2, keys1, keys2, opts,
+                                   differences)
+          end
+        end
+
+        # Compare with strict attribute ordering
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param attrs1 [Hash] First node's attributes
+        # @param attrs2 [Hash] Second node's attributes
+        # @param keys1 [Array<String>] First node's attribute keys
+        # @param keys2 [Array<String>] Second node's attribute keys
+        # @param opts [Hash] Comparison options
+        # @param differences [Array] Array to append differences to
+        # @return [Symbol] Comparison result
+        def self.compare_strict_order(node1, node2, attrs1, attrs2, keys1, keys2, opts,
+differences)
+          if keys1 != keys2
+            # Keys are different or in different order
+            if keys1.sort == keys2.sort
+              # Same keys, different order - attribute_order difference
+              add_attribute_difference(n1: node1, n2: node2,
+                                       diff1: Comparison::UNEQUAL_ATTRIBUTES,
+                                       diff2: Comparison::UNEQUAL_ATTRIBUTES,
+                                       dimension: :attribute_order,
+                                       opts: opts,
+                                       differences: differences)
+              return Comparison::UNEQUAL_ATTRIBUTES
+            else
+              # Different keys - attribute_presence difference
+              add_attribute_difference(n1: node1, n2: node2,
+                                       diff1: Comparison::MISSING_ATTRIBUTE,
+                                       diff2: Comparison::MISSING_ATTRIBUTE,
+                                       dimension: :attribute_presence,
+                                       opts: opts,
+                                       differences: differences)
+              return Comparison::MISSING_ATTRIBUTE
+            end
+          end
+
+          # Order matches, check values
+          compare_attribute_values(node1, node2, attrs1, attrs2, opts,
+                                   differences)
+        end
+
+        # Compare with flexible attribute ordering
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param attrs1 [Hash] First node's attributes
+        # @param attrs2 [Hash] Second node's attributes
+        # @param keys1 [Array<String>] First node's attribute keys
+        # @param keys2 [Array<String>] Second node's attribute keys
+        # @param opts [Hash] Comparison options
+        # @param differences [Array] Array to append differences to
+        # @return [Symbol] Comparison result
+        def self.compare_flexible_order(node1, node2, attrs1, attrs2, keys1, keys2, opts,
+differences)
+          # Check if order differs (but keys are the same) - track as informative
+          if keys1 != keys2 && keys1.sort == keys2.sort && opts[:verbose]
+            add_attribute_difference(n1: node1, n2: node2,
+                                     diff1: Comparison::UNEQUAL_ATTRIBUTES,
+                                     diff2: Comparison::UNEQUAL_ATTRIBUTES,
+                                     dimension: :attribute_order,
+                                     opts: opts,
+                                     differences: 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_attribute_difference(n1: node1, n2: node2,
+                                     diff1: Comparison::MISSING_ATTRIBUTE,
+                                     diff2: Comparison::MISSING_ATTRIBUTE,
+                                     dimension: :attribute_presence,
+                                     opts: opts,
+                                     differences: differences)
+            return Comparison::MISSING_ATTRIBUTE
+          end
+
+          compare_attribute_values(node1, node2, attrs1, attrs2, opts,
+                                   differences)
+        end
+
+        # Compare attribute values
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param attrs1 [Hash] First node's attributes
+        # @param attrs2 [Hash] Second node's attributes
+        # @param opts [Hash] Comparison options
+        # @param differences [Array] Array to append differences to
+        # @return [Symbol] Comparison result
+        def self.compare_attribute_values(node1, node2, attrs1, attrs2, opts,
+differences)
+          attrs1.each do |name, value|
+            unless attrs2[name] == value
+              add_attribute_difference(n1: node1, n2: node2,
+                                       diff1: Comparison::UNEQUAL_ATTRIBUTES,
+                                       diff2: Comparison::UNEQUAL_ATTRIBUTES,
+                                       dimension: :attribute_values,
+                                       opts: opts,
+                                       differences: differences)
+              return Comparison::UNEQUAL_ATTRIBUTES
+            end
+          end
+
+          Comparison::EQUIVALENT
+        end
+
+        # Add an attribute difference
+        #
+        # @param n1 [Object] First node
+        # @param n2 [Object] Second node
+        # @param diff1 [String] Difference type for node1
+        # @param diff2 [String] Difference type for node2
+        # @param dimension [Symbol] The match dimension
+        # @param opts [Hash] Options
+        # @param differences [Array] Array to append difference to
+        def self.add_attribute_difference(n1:, n2:, diff1:, diff2:,
+dimension:, differences:, **opts)
+          # Import DiffNodeBuilder to avoid circular dependency
+          require_relative "diff_node_builder"
+
+          diff_node = Canon::Comparison::DiffNodeBuilder.build(
+            node1: n1,
+            node2: n2,
+            diff1: diff1,
+            diff2: diff2,
+            dimension: dimension,
+            **opts,
+          )
+          differences << diff_node if diff_node
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "../match_options"
+
+module Canon
+  module Comparison
+    module XmlComparatorHelpers
+      # Attribute filtering logic
+      # Handles filtering of attributes based on options and match settings
+      class AttributeFilter
+        # Filter attributes based on options
+        #
+        # @param attributes [Array, Hash] Raw attributes
+        # @param opts [Hash] Comparison options
+        # @return [Hash] Filtered attributes
+        def self.filter(attributes, opts)
+          filtered = {}
+          match_opts = opts[:match_opts]
+
+          # Handle Canon::Xml::Node attribute format (array of AttributeNode)
+          if attributes.is_a?(Array)
+            filter_array_attributes(attributes, opts, match_opts, filtered)
+          else
+            # Handle Nokogiri and Moxml attribute formats (Hash-like)
+            filter_hash_attributes(attributes, opts, match_opts, filtered)
+          end
+
+          filtered
+        end
+
+        # Filter array-format attributes (Canon::Xml::Node)
+        #
+        # @param attributes [Array] Array of AttributeNode objects
+        # @param opts [Hash] Comparison options
+        # @param match_opts [Hash] Resolved match options
+        # @param filtered [Hash] Output hash to populate
+        def self.filter_array_attributes(attributes, opts, match_opts, filtered)
+          attributes.each do |attr|
+            name = attr.name
+            value = attr.value
+
+            # Skip namespace declarations - they're handled separately
+            next if namespace_declaration?(name)
+
+            # Skip if attribute name should be ignored
+            next if ignore_by_name?(name, opts)
+
+            # Skip if attribute content should be ignored
+            next if ignore_by_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
+        end
+
+        # Filter hash-format attributes (Nokogiri/Moxml)
+        #
+        # @param attributes [Hash] Hash-like attributes
+        # @param opts [Hash] Comparison options
+        # @param match_opts [Hash] Resolved match options
+        # @param filtered [Hash] Output hash to populate
+        def self.filter_hash_attributes(attributes, opts, match_opts, filtered)
+          attributes.each do |key, val|
+            # Normalize key and value
+            name, value = normalize_attribute_pair(key, val)
+
+            # Skip namespace declarations - they're handled separately
+            next if namespace_declaration?(name)
+
+            # Skip if attribute name should be ignored
+            next if ignore_by_name?(name, opts)
+
+            # Skip if attribute content should be ignored
+            next if ignore_by_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
+        end
+
+        # Normalize attribute key-value pair from different formats
+        #
+        # @param key [Object] Attribute key (String or Attribute object)
+        # @param val [Object] Attribute value
+        # @return [Array<String, String>] Normalized [name, value] pair
+        def self.normalize_attribute_pair(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
+
+          [name, value]
+        end
+
+        # Check if attribute should be ignored by name
+        #
+        # @param name [String] Attribute name
+        # @param opts [Hash] Comparison options
+        # @return [Boolean] true if should ignore
+        def self.ignore_by_name?(name, opts)
+          opts[:ignore_attrs_by_name].any? { |pattern| name.include?(pattern) }
+        end
+
+        # Check if attribute should be ignored by content
+        #
+        # @param value [String] Attribute value
+        # @param opts [Hash] Comparison options
+        # @return [Boolean] true if should ignore
+        def self.ignore_by_content?(value, opts)
+          opts[:ignore_attr_content].any? do |pattern|
+            value.to_s.include?(pattern)
+          end
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# 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? 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 }
+          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