canon 0.1.7 → 0.1.9

data/lib/canon/comparison/profile_definition.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "match_options"
+
+module Canon
+  module Comparison
+    # Profile definition DSL with full validation
+    #
+    # Provides a clean, validated way to define custom comparison profiles.
+    # Catches errors at definition time with clear, actionable messages.
+    #
+    # @example Define a custom profile
+    #   Canon::Comparison.define_profile(:my_custom) do
+    #     text_content :normalize
+    #     comments :ignore
+    #     preprocessing :rendered
+    #   end
+    class ProfileDefinition
+      # All valid dimensions for XML/HTML comparison
+      # These must match MatchOptions::Xml::MATCH_DIMENSIONS
+      VALID_DIMENSIONS = %i[
+        text_content
+        structural_whitespace
+        attribute_presence
+        attribute_order
+        attribute_values
+        element_position
+        comments
+      ].freeze
+
+      # Behaviors valid for each dimension
+      # Maps dimension name to array of valid behavior symbols
+      DIMENSION_BEHAVIORS = {
+        text_content: %i[strict normalize ignore],
+        structural_whitespace: %i[strict normalize ignore],
+        attribute_presence: %i[strict ignore],
+        attribute_order: %i[strict ignore],
+        attribute_values: %i[strict strip compact normalize ignore],
+        element_position: %i[strict ignore],
+        comments: %i[strict ignore],
+      }.freeze
+
+      attr_reader :name, :settings
+
+      # Initialize a new profile definition
+      #
+      # @param name [Symbol] Profile name
+      def initialize(name)
+        @name = name
+        @settings = {}
+      end
+
+      # Define a profile using DSL syntax
+      #
+      # @param name [Symbol] Profile name
+      # @yield [ProfileDefinition] DSL block for defining profile
+      # @return [Hash] Profile settings hash
+      # @raise [ProfileError] if profile definition is invalid
+      def self.define(name, &block)
+        definition = new(name)
+        definition.instance_eval(&block) if block
+        definition.validate!
+        definition.to_h
+      end
+
+      # Create DSL methods for each dimension
+      VALID_DIMENSIONS.each do |dimension|
+        define_method(dimension) do |behavior|
+          @settings[dimension] = behavior
+        end
+      end
+
+      # Set preprocessing mode
+      #
+      # @param mode [Symbol] Preprocessing mode
+      # @raise [ProfileError] if mode is invalid
+      def preprocessing(mode)
+        unless MatchOptions::PREPROCESSING_OPTIONS.include?(mode)
+          raise ProfileError,
+                "Invalid preprocessing mode: #{mode}. " \
+                "Valid options: #{MatchOptions::PREPROCESSING_OPTIONS.join(', ')}"
+        end
+
+        @settings[:preprocessing] = mode
+      end
+
+      # Enable/disable semantic diff
+      #
+      # @param enabled [Boolean] Whether to enable semantic diff (default: true)
+      def semantic_diff(enabled: true)
+        @settings[:semantic_diff] = enabled
+      end
+
+      # Set similarity threshold for semantic matching
+      #
+      # @param value [Numeric] Threshold between 0 and 1
+      # @raise [ProfileError] if value is out of range
+      def similarity_threshold(value)
+        unless value.is_a?(Numeric) && value >= 0 && value <= 1
+          raise ProfileError,
+                "Similarity threshold must be between 0 and 1, got: #{value}"
+        end
+
+        @settings[:similarity_threshold] = value
+      end
+
+      # Validate the profile definition
+      #
+      # @raise [ProfileError] if profile definition is invalid
+      def validate!
+        @settings.each do |key, value|
+          validate_dimension!(key, value) if VALID_DIMENSIONS.include?(key)
+        end
+      end
+
+      # Convert to hash
+      #
+      # @return [Hash] Profile settings
+      def to_h
+        @settings.dup
+      end
+
+      private
+
+      # Validate a dimension setting
+      #
+      # @param dimension [Symbol] Dimension name
+      # @param behavior [Symbol] Behavior value
+      # @raise [ProfileError] if dimension or behavior is invalid
+      def validate_dimension!(dimension, behavior)
+        unless DIMENSION_BEHAVIORS.key?(dimension)
+          raise ProfileError,
+                "Unknown dimension: #{dimension}. " \
+                "Valid dimensions: #{VALID_DIMENSIONS.join(', ')}"
+        end
+
+        valid_behaviors = DIMENSION_BEHAVIORS[dimension]
+        unless valid_behaviors.include?(behavior)
+          raise ProfileError,
+                "Invalid behavior '#{behavior}' for dimension '#{dimension}'. " \
+                "Valid behaviors: #{valid_behaviors.join(', ')}"
+        end
+      end
+    end
+
+    # Custom error for profile definition issues
+    class ProfileError < Error; end
+  end
+end

data/lib/canon/comparison/ruby_object_comparator.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    # Ruby Object Comparison Utilities
+    #
+    # Provides public comparison methods for Ruby objects (Hash, Array, primitives).
+    # This module extracts shared comparison logic that was previously
+    # accessed via send() from YamlComparator.
+    module RubyObjectComparator
+      # Compare Ruby objects (Hash, Array, primitives) for JSON/YAML
+      #
+      # @param obj1 [Object] First object
+      # @param obj2 [Object] Second object
+      # @param opts [Hash] Comparison options
+      # @param differences [Array] Array to append differences to
+      # @param path [String] Current path in the object structure
+      # @return [Symbol] Comparison result constant
+      def self.compare_objects(obj1, obj2, opts, differences, path)
+        # Check for type mismatch
+        unless obj1.instance_of?(obj2.class)
+          add_difference(path, obj1, obj2, Comparison::UNEQUAL_TYPES,
+                         opts, differences)
+          return Comparison::UNEQUAL_TYPES
+        end
+
+        case obj1
+        when Hash
+          compare_hashes(obj1, obj2, opts, differences, path)
+        when Array
+          compare_arrays(obj1, obj2, opts, differences, path)
+        when NilClass, TrueClass, FalseClass, Numeric, String, Symbol
+          compare_primitives(obj1, obj2, opts, differences, path)
+        else
+          # Fallback to equality comparison
+          if obj1 == obj2
+            Comparison::EQUIVALENT
+          else
+            add_difference(path, obj1, obj2,
+                           Comparison::UNEQUAL_PRIMITIVES, opts,
+                           differences)
+            Comparison::UNEQUAL_PRIMITIVES
+          end
+        end
+      end
+
+      # Compare two hashes
+      #
+      # @param hash1 [Hash] First hash
+      # @param hash2 [Hash] Second hash
+      # @param opts [Hash] Comparison options
+      # @param differences [Array] Array to append differences to
+      # @param path [String] Current path in the object structure
+      # @return [Symbol] Comparison result constant
+      def self.compare_hashes(hash1, hash2, opts, differences, path)
+        keys1 = hash1.keys
+        keys2 = hash2.keys
+
+        # Sort keys if order should be ignored (based on match options)
+        match_opts = opts[:match_opts]
+        if match_opts && match_opts[:key_order] != :strict
+          keys1 = keys1.sort_by(&:to_s)
+          keys2 = keys2.sort_by(&:to_s)
+        elsif match_opts && match_opts[:key_order] == :strict
+          # Strict mode: key order matters
+          # Check if keys are in same order
+          # Keys are different or in different order
+          # First check if it's just ordering (same keys, different order)
+          if (keys1 != keys2) && (keys1.sort_by(&:to_s) == keys2.sort_by(&:to_s))
+            # Same keys, different order - this is a key_order difference
+            key_path = path.empty? ? "(key order)" : "#{path}.(key order)"
+            add_difference(key_path, keys1, keys2,
+                           Comparison::UNEQUAL_HASH_KEY_ORDER, opts, differences)
+            return Comparison::UNEQUAL_HASH_KEY_ORDER
+          end
+        end
+
+        # Check for missing keys
+        missing_in_second = keys1 - keys2
+        missing_in_first = keys2 - keys1
+
+        missing_in_second.each do |key|
+          key_path = path.empty? ? key.to_s : "#{path}.#{key}"
+          add_difference(key_path, hash1[key], nil,
+                         Comparison::MISSING_HASH_KEY, opts, differences)
+        end
+
+        missing_in_first.each do |key|
+          key_path = path.empty? ? key.to_s : "#{path}.#{key}"
+          add_difference(key_path, nil, hash2[key],
+                         Comparison::MISSING_HASH_KEY, opts, differences)
+        end
+
+        has_missing_keys = !missing_in_first.empty? || !missing_in_second.empty?
+
+        # Compare common keys
+        common_keys = keys1 & keys2
+        all_equivalent = true
+        common_keys.each do |key|
+          key_path = path.empty? ? key.to_s : "#{path}.#{key}"
+          result = compare_objects(hash1[key], hash2[key], opts,
+                                   differences, key_path)
+          all_equivalent = false unless result == Comparison::EQUIVALENT
+        end
+
+        # Return appropriate status
+        return Comparison::MISSING_HASH_KEY if has_missing_keys && all_equivalent
+        return Comparison::UNEQUAL_HASH_VALUES unless all_equivalent
+
+        has_missing_keys ? Comparison::MISSING_HASH_KEY : Comparison::EQUIVALENT
+      end
+
+      # Compare two arrays
+      #
+      # @param arr1 [Array] First array
+      # @param arr2 [Array] Second array
+      # @param opts [Hash] Comparison options
+      # @param differences [Array] Array to append differences to
+      # @param path [String] Current path in the object structure
+      # @return [Symbol] Comparison result constant
+      def self.compare_arrays(arr1, arr2, opts, differences, path)
+        unless arr1.length == arr2.length
+          add_difference(path, arr1, arr2,
+                         Comparison::UNEQUAL_ARRAY_LENGTHS, opts,
+                         differences)
+          return Comparison::UNEQUAL_ARRAY_LENGTHS
+        end
+
+        all_equivalent = true
+        arr1.each_with_index do |elem1, index|
+          elem2 = arr2[index]
+          elem_path = "#{path}[#{index}]"
+          result = compare_objects(elem1, elem2, opts, differences,
+                                   elem_path)
+          all_equivalent = false unless result == Comparison::EQUIVALENT
+        end
+
+        all_equivalent ? Comparison::EQUIVALENT : Comparison::UNEQUAL_ARRAY_ELEMENTS
+      end
+
+      # Compare primitive values
+      #
+      # @param val1 [Object] First value
+      # @param val2 [Object] Second value
+      # @param opts [Hash] Comparison options
+      # @param differences [Array] Array to append differences to
+      # @param path [String] Current path in the object structure
+      # @return [Symbol] Comparison result constant
+      def self.compare_primitives(val1, val2, opts, differences, path)
+        if val1 == val2
+          Comparison::EQUIVALENT
+        else
+          add_difference(path, val1, val2,
+                         Comparison::UNEQUAL_PRIMITIVES, opts,
+                         differences)
+          Comparison::UNEQUAL_PRIMITIVES
+        end
+      end
+
+      # Add a Ruby object difference
+      #
+      # @param path [String] Path to the difference
+      # @param obj1 [Object] First object
+      # @param obj2 [Object] Second object
+      # @param diff_code [Symbol] Difference code
+      # @param opts [Hash] Comparison options
+      # @param differences [Array] Array to append difference to
+      def self.add_difference(path, obj1, obj2, diff_code, opts, differences)
+        return unless opts[:verbose]
+
+        differences << {
+          path: path,
+          value1: obj1,
+          value2: obj2,
+          difference: diff_code,
+        }
+      end
+    end
+  end
+end

data/lib/canon/comparison/strategies/semantic_tree_match_strategy.rb

@@ -3,6 +3,7 @@
 require_relative "base_match_strategy"
 require_relative "../../tree_diff/tree_diff_integrator"
 require_relative "../../tree_diff/operation_converter"
+require_relative "../xml_node_comparison"
 
 module Canon
   module Comparison
@@ -125,10 +126,9 @@ module Canon
         # @return [Array<String>] Preprocessed strings
         def preprocess_xml(doc1, doc2)
           # Serialize XML to string
-          # Use XmlComparator's serializer for Canon::Xml::Node
+          # Use XmlNodeComparison's serializer for Canon::Xml::Node
           xml1 = if doc1.is_a?(Canon::Xml::Node)
-                   require_relative "../xml_comparator"
-                   XmlComparator.send(:serialize_node_to_xml, doc1)
+                   XmlNodeComparison.serialize_node_to_xml(doc1)
                  elsif doc1.respond_to?(:to_xml)
                    doc1.to_xml
                  else
@@ -136,8 +136,7 @@ module Canon
                  end
 
           xml2 = if doc2.is_a?(Canon::Xml::Node)
-                   require_relative "../xml_comparator"
-                   XmlComparator.send(:serialize_node_to_xml, doc2)
+                   XmlNodeComparison.serialize_node_to_xml(doc2)
                  elsif doc2.respond_to?(:to_xml)
                    doc2.to_xml
                  else
@@ -161,12 +160,11 @@ module Canon
         # @param doc2 [Object] Second HTML document
         # @return [Array<String>] Preprocessed strings
         def preprocess_html(doc1, doc2)
-          # For Canon::Xml::Node, use XmlComparator's serializer
+          # For Canon::Xml::Node, use XmlNodeComparison's serializer
           # For XML::DocumentFragment (from parse_node_as_fragment), use to_s
           # to avoid Nokogiri auto-inserting meta tags during to_html serialization
           html1 = if doc1.is_a?(Canon::Xml::Node)
-                    require_relative "../xml_comparator"
-                    XmlComparator.send(:serialize_node_to_xml, doc1)
+                    XmlNodeComparison.serialize_node_to_xml(doc1)
                   elsif doc1.is_a?(Nokogiri::XML::DocumentFragment)
                     doc1.to_s
                   elsif doc1.respond_to?(:to_html)
@@ -176,8 +174,7 @@ module Canon
                   end
 
           html2 = if doc2.is_a?(Canon::Xml::Node)
-                    require_relative "../xml_comparator"
-                    XmlComparator.send(:serialize_node_to_xml, doc2)
+                    XmlNodeComparison.serialize_node_to_xml(doc2)
                   elsif doc2.is_a?(Nokogiri::XML::DocumentFragment)
                     doc2.to_s
                   elsif doc2.respond_to?(:to_html)

data/lib/canon/comparison/whitespace_sensitivity.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    # Whitespace sensitivity utilities for element-level control
+    #
+    # This module provides logic to determine whether whitespace should be
+    # preserved during comparison based on:
+    # - Format-specific defaults (HTML has built-in sensitive elements)
+    # - User-configured whitelist (elements that care about whitespace)
+    # - User-configured blacklist (elements that don't care about whitespace)
+    # - xml:space attribute in the document itself
+    # - respect_xml_space flag (whether to honor or override xml:space)
+    #
+    # == Priority Order
+    #
+    # 1. respect_xml_space: false → User config only (ignore xml:space)
+    # 2. User whitelist → Use whitelist (user explicitly declared)
+    # 3. Format defaults → HTML: [:pre, :textarea, :script, :style], XML: []
+    # 4. User blacklist → Remove from defaults/whitelist
+    # 5. xml:space="preserve" → Element is sensitive
+    # 6. xml:space="default" → Use steps 1-4
+    #
+    # == Usage
+    #
+    #   WhitespaceSensitivity.element_sensitive?(node, opts)
+    #   => true if whitespace should be preserved for this element
+    module WhitespaceSensitivity
+      class << self
+        # Check if an element is whitespace-sensitive based on configuration
+        #
+        # @param node [Object] The element node to check
+        # @param opts [Hash] Comparison options containing match_opts
+        # @return [Boolean] true if whitespace should be preserved for this element
+        def element_sensitive?(node, opts)
+          match_opts = opts[:match_opts]
+          return false unless match_opts
+          return false unless text_node_parent?(node)
+
+          parent = node.parent
+
+          # 1. Check if we should ignore xml:space (user override)
+          if !respect_xml_space?(match_opts)
+            return user_config_sensitive?(parent, match_opts)
+          end
+
+          # 2. Check xml:space="preserve" (document declaration)
+          return true if xml_space_preserve?(parent)
+
+          # 3. Check xml:space="default" (use configured behavior)
+          return false if xml_space_default?(parent)
+
+          # 4. Use user configuration + format defaults
+          configured_sensitive?(parent, match_opts)
+        end
+
+        # Check if whitespace-only text node should be filtered
+        #
+        # @param node [Object] The text node to check
+        # @param opts [Hash] Comparison options
+        # @return [Boolean] true if node should be preserved (not filtered)
+        def preserve_whitespace_node?(node, opts)
+          return false unless node.respond_to?(:parent)
+          return false unless node.parent
+
+          element_sensitive?(node, opts)
+        end
+
+        # Get format-specific default sensitive elements
+        #
+        # This is the SINGLE SOURCE OF TRUTH for default whitespace-sensitive
+        # elements. All other code should use this method to get the list.
+        #
+        # @param match_opts [Hash] Resolved match options
+        # @return [Array<Symbol>] Default sensitive element names
+        def format_default_sensitive_elements(match_opts)
+          format = match_opts[:format] || :xml
+
+          case format
+          when :html, :html4, :html5
+            # HTML specification: these elements preserve whitespace
+            %i[pre code textarea script style].freeze
+          when :xml
+            # XML has no default sensitive elements - purely user-controlled
+            [].freeze
+          else
+            [].freeze
+          end
+        end
+
+        # Check if an element is in the default sensitive list for its format
+        #
+        # Convenience method for checking element sensitivity without building
+        # the full list first.
+        #
+        # @param element_name [String, Symbol] The element name to check
+        # @param match_opts [Hash] Resolved match options
+        # @return [Boolean] true if element is in default sensitive list
+        def default_sensitive_element?(element_name, match_opts)
+          format_default_sensitive_elements(match_opts)
+            .include?(element_name.to_sym)
+        end
+
+        private
+
+        # Check if we should respect xml:space attribute
+        #
+        # @param match_opts [Hash] Resolved match options
+        # @return [Boolean] true if xml:space should be respected
+        def respect_xml_space?(match_opts)
+          if match_opts.key?(:respect_xml_space)
+            match_opts[:respect_xml_space]
+          else
+            true
+          end
+        end
+
+        # Check if xml:space="preserve" is set
+        #
+        # @param element [Object] The element to check
+        # @return [Boolean] true if xml:space="preserve"
+        def xml_space_preserve?(element)
+          if element.is_a?(Canon::Xml::Nodes::ElementNode)
+            # Check attribute_nodes for xml:space attribute
+            # xml:space is stored with name="space" and namespace_uri="http://www.w3.org/XML/1998/namespace"
+            element.attribute_nodes.any? do |attr|
+              attr.name == "space" &&
+                attr.namespace_uri == "http://www.w3.org/XML/1998/namespace" &&
+                attr.value == "preserve"
+            end
+          elsif element.respond_to?(:[])
+            element["xml:space"] == "preserve"
+          else
+            false
+          end
+        end
+
+        # Check if xml:space="default" is set
+        #
+        # @param element [Object] The element to check
+        # @return [Boolean] true if xml:space="default"
+        def xml_space_default?(element)
+          if element.is_a?(Canon::Xml::Nodes::ElementNode)
+            # Check attribute_nodes for xml:space attribute
+            # xml:space is stored with name="space" and namespace_uri="http://www.w3.org/XML/1998/namespace"
+            element.attribute_nodes.any? do |attr|
+              attr.name == "space" &&
+                attr.namespace_uri == "http://www.w3.org/XML/1998/namespace" &&
+                attr.value == "default"
+            end
+          elsif element.respond_to?(:[])
+            element["xml:space"] == "default"
+          else
+            false
+          end
+        end
+
+        # Check sensitivity based on user configuration
+        #
+        # @param element [Object] The element to check
+        # @param match_opts [Hash] Resolved match options
+        # @return [Boolean] true if element is in whitelist
+        def user_config_sensitive?(element, match_opts)
+          return false unless match_opts[:whitespace_sensitive_elements]
+
+          match_opts[:whitespace_sensitive_elements].include?(element.name.to_sym)
+        end
+
+        # Check sensitivity based on user config + format defaults
+        #
+        # @param element [Object] The element to check
+        # @param match_opts [Hash] Resolved match options
+        # @return [Boolean] true if element should be sensitive
+        def configured_sensitive?(element, match_opts)
+          # Start with format defaults
+          sensitive = format_default_sensitive_elements(match_opts).to_set
+
+          # Apply whitelist (adds to defaults)
+          if match_opts[:whitespace_sensitive_elements]
+            sensitive |= match_opts[:whitespace_sensitive_elements]
+          end
+
+          # Apply blacklist (removes from everything)
+          if match_opts[:whitespace_insensitive_elements]
+            sensitive -= match_opts[:whitespace_insensitive_elements]
+          end
+
+          sensitive.include?(element.name.to_sym)
+        end
+
+        # Check if node has a parent that's an element (not document root)
+        #
+        # @param node [Object] The node to check
+        # @return [Boolean] true if node has an element parent
+        def text_node_parent?(node)
+          return false unless node.respond_to?(:parent)
+          return false unless node.parent
+
+          parent = node.parent
+          return true if parent.respond_to?(:element?) && parent.element?
+
+          # Nokogiri compatibility
+          parent.respond_to?(:node_type) && parent.node_type == :element
+        end
+      end
+    end
+  end
+end