canon 0.1.7 → 0.1.8

data/lib/canon/comparison/match_options/base_resolver.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    module MatchOptions
+      # Base class for match option resolvers
+      # Provides common resolve logic with format-specific customization
+      class BaseResolver
+        class << self
+          # Resolve match options with precedence handling
+          #
+          # Precedence order (highest to lowest):
+          # 1. Explicit match parameter
+          # 2. Profile from match_profile parameter
+          # 3. Global configuration
+          # 4. Format-specific defaults
+          #
+          # @param format [Symbol] Format type
+          # @param match_profile [Symbol, nil] Profile name
+          # @param match [Hash, nil] Explicit options per dimension
+          # @param preprocessing [Symbol, nil] Preprocessing option
+          # @param global_profile [Symbol, nil] Global configured profile
+          # @param global_options [Hash, nil] Global configured options
+          # @return [Hash] Resolved options for all dimensions
+          def resolve(format:, match_profile: nil, match: nil, preprocessing: nil,
+                      global_profile: nil, global_options: nil)
+            # Start with format-specific defaults
+            options = format_defaults(format).dup
+
+            # Apply global profile if specified
+            if global_profile
+              profile_opts = get_profile_options(global_profile)
+              options.merge!(profile_opts)
+            end
+
+            # Apply global options if specified
+            if global_options
+              validate_match_options!(global_options)
+              options.merge!(global_options)
+            end
+
+            # Apply per-call profile if specified (overrides global)
+            if match_profile
+              profile_opts = get_profile_options(match_profile)
+              options.merge!(profile_opts)
+            end
+
+            # Apply per-call preprocessing if specified (overrides profile)
+            if preprocessing
+              validate_preprocessing!(preprocessing)
+              options[:preprocessing] = preprocessing
+            end
+
+            # Apply per-call explicit options if specified (highest priority)
+            if match
+              validate_match_options!(match)
+              options.merge!(match)
+            end
+
+            options
+          end
+
+          # Get format-specific default options
+          # Subclasses should override this
+          #
+          # @param format [Symbol] Format type
+          # @return [Hash] Default options for the format
+          def format_defaults(format)
+            raise NotImplementedError,
+                  "#{self.class} must implement #format_defaults"
+          end
+
+          # Get options for a named profile
+          # Subclasses should override this
+          #
+          # @param profile [Symbol] Profile name
+          # @return [Hash] Profile options
+          # @raise [Canon::Error] If profile is unknown
+          def get_profile_options(profile)
+            raise NotImplementedError,
+                  "#{self.class} must implement #get_profile_options"
+          end
+
+          # Get valid match dimensions for this format
+          # Subclasses should override this
+          #
+          # @return [Array<Symbol>] Valid dimensions
+          def match_dimensions
+            raise NotImplementedError,
+                  "#{self.class} must implement #match_dimensions"
+          end
+
+          protected
+
+          # Validate preprocessing option
+          #
+          # @param preprocessing [Symbol] Preprocessing option
+          # @raise [Canon::Error] If invalid
+          def validate_preprocessing!(preprocessing)
+            unless MatchOptions::PREPROCESSING_OPTIONS.include?(preprocessing)
+              raise Canon::Error,
+                    "Unknown preprocessing option: #{preprocessing}. " \
+                    "Valid options: #{MatchOptions::PREPROCESSING_OPTIONS.join(', ')}"
+            end
+          end
+
+          # Validate match options
+          #
+          # @param match_options [Hash] Options to validate
+          # @raise [Canon::Error] If invalid dimension or behavior
+          def validate_match_options!(match_options)
+            # Special options that don't need validation as dimensions
+            special_options = %i[
+              preprocessing
+              semantic_diff
+              similarity_threshold
+              hash_matching
+              similarity_matching
+              propagation
+            ]
+
+            match_options.each do |dimension, behavior|
+              # Skip special options (validated elsewhere or passed through)
+              next if special_options.include?(dimension)
+
+              unless match_dimensions.include?(dimension)
+                raise Canon::Error,
+                      "Unknown match dimension: #{dimension}. " \
+                      "Valid dimensions: #{match_dimensions.join(', ')}"
+              end
+
+              unless MatchOptions::MATCH_BEHAVIORS.include?(behavior)
+                raise Canon::Error,
+                      "Unknown match behavior: #{behavior} for #{dimension}. " \
+                      "Valid behaviors: #{MatchOptions::MATCH_BEHAVIORS.join(', ')}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/match_options/json_resolver.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "base_resolver"
+
+module Canon
+  module Comparison
+    module MatchOptions
+      # JSON-specific match options resolver
+      class JsonResolver < BaseResolver
+        # Format defaults for JSON
+        FORMAT_DEFAULTS = {
+          json: {
+            preprocessing: :none,
+            text_content: :strict,
+            structural_whitespace: :ignore,
+            key_order: :ignore,
+          },
+        }.freeze
+
+        # Predefined match profiles for JSON
+        MATCH_PROFILES = {
+          # Strict: Match exactly
+          strict: {
+            preprocessing: :none,
+            text_content: :strict,
+            structural_whitespace: :strict,
+            key_order: :strict,
+          },
+
+          # Spec-friendly: Formatting and order don't matter
+          spec_friendly: {
+            preprocessing: :normalize,
+            text_content: :strict,
+            structural_whitespace: :ignore,
+            key_order: :ignore,
+          },
+
+          # Content-only: Only values matter
+          content_only: {
+            preprocessing: :normalize,
+            text_content: :normalize,
+            structural_whitespace: :ignore,
+            key_order: :ignore,
+          },
+        }.freeze
+
+        class << self
+          # Matching dimensions for JSON (collectively exhaustive)
+          def match_dimensions
+            %i[
+              text_content
+              structural_whitespace
+              key_order
+            ].freeze
+          end
+
+          # Get format-specific default options
+          #
+          # @param format [Symbol] Format type (:json)
+          # @return [Hash] Default options for the format
+          def format_defaults(format)
+            FORMAT_DEFAULTS[format]&.dup || FORMAT_DEFAULTS[:json].dup
+          end
+
+          # Get options for a named profile
+          #
+          # @param profile [Symbol] Profile name
+          # @return [Hash] Profile options
+          # @raise [Canon::Error] If profile is unknown
+          def get_profile_options(profile)
+            unless MATCH_PROFILES.key?(profile)
+              raise Canon::Error,
+                    "Unknown match profile: #{profile}. " \
+                    "Valid profiles: #{MATCH_PROFILES.keys.join(', ')}"
+            end
+            MATCH_PROFILES[profile].dup
+          end
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/match_options/xml_resolver.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "base_resolver"
+
+module Canon
+  module Comparison
+    module MatchOptions
+      # XML/HTML-specific match options resolver
+      class XmlResolver < BaseResolver
+        # Format-specific defaults for XML/HTML
+        FORMAT_DEFAULTS = {
+          html: {
+            preprocessing: :rendered,
+            text_content: :normalize,
+            structural_whitespace: :normalize,
+            attribute_presence: :strict,
+            attribute_order: :ignore,
+            attribute_values: :strict,
+            element_position: :ignore,
+            comments: :ignore,
+          },
+          xml: {
+            preprocessing: :none,
+            text_content: :strict,
+            structural_whitespace: :strict,
+            attribute_presence: :strict,
+            attribute_order: :ignore,
+            attribute_values: :strict,
+            element_position: :strict,
+            comments: :strict,
+          },
+        }.freeze
+
+        # Predefined match profiles for XML/HTML
+        MATCH_PROFILES = {
+          # Strict: Match exactly as written in source (XML default)
+          strict: {
+            preprocessing: :none,
+            text_content: :strict,
+            structural_whitespace: :strict,
+            attribute_presence: :strict,
+            attribute_order: :strict,
+            attribute_values: :strict,
+            element_position: :strict,
+            comments: :strict,
+          },
+
+          # Rendered: Match rendered output (HTML default)
+          # Mimics CSS whitespace collapsing
+          rendered: {
+            preprocessing: :none,
+            text_content: :normalize,
+            structural_whitespace: :normalize,
+            attribute_presence: :strict,
+            attribute_order: :strict,
+            attribute_values: :strict,
+            element_position: :strict,
+            comments: :ignore,
+          },
+
+          # HTML4: Match HTML4 rendered output
+          # HTML4 rendering normalizes attribute whitespace
+          html4: {
+            preprocessing: :rendered,
+            text_content: :normalize,
+            structural_whitespace: :normalize,
+            attribute_presence: :strict,
+            attribute_order: :strict,
+            attribute_values: :normalize,
+            element_position: :ignore,
+            comments: :ignore,
+          },
+
+          # HTML5: Match HTML5 rendered output (same as rendered)
+          html5: {
+            preprocessing: :rendered,
+            text_content: :normalize,
+            structural_whitespace: :normalize,
+            attribute_presence: :strict,
+            attribute_order: :strict,
+            attribute_values: :strict,
+            element_position: :ignore,
+            comments: :ignore,
+          },
+
+          # Spec-friendly: Formatting doesn't matter
+          # Uses :rendered preprocessing for HTML which normalizes via to_html
+          spec_friendly: {
+            preprocessing: :rendered,
+            text_content: :normalize,
+            structural_whitespace: :ignore,
+            attribute_presence: :strict,
+            attribute_order: :ignore,
+            attribute_values: :normalize,
+            element_position: :ignore,
+            comments: :ignore,
+          },
+
+          # Content-only: Only content matters
+          content_only: {
+            preprocessing: :c14n,
+            text_content: :normalize,
+            structural_whitespace: :ignore,
+            attribute_presence: :strict,
+            attribute_order: :ignore,
+            attribute_values: :normalize,
+            element_position: :ignore,
+            comments: :ignore,
+          },
+        }.freeze
+
+        class << self
+          # Matching dimensions for XML/HTML (collectively exhaustive)
+          def match_dimensions
+            %i[
+              text_content
+              structural_whitespace
+              attribute_presence
+              attribute_order
+              attribute_values
+              element_position
+              comments
+            ].freeze
+          end
+
+          # Get format-specific default options
+          #
+          # @param format [Symbol] Format type (:xml or :html)
+          # @return [Hash] Default options for the format
+          def format_defaults(format)
+            FORMAT_DEFAULTS[format]&.dup || FORMAT_DEFAULTS[:xml].dup
+          end
+
+          # Get options for a named profile
+          #
+          # @param profile [Symbol] Profile name
+          # @return [Hash] Profile options
+          # @raise [Canon::Error] If profile is unknown
+          def get_profile_options(profile)
+            unless MATCH_PROFILES.key?(profile)
+              raise Canon::Error,
+                    "Unknown match profile: #{profile}. " \
+                    "Valid profiles: #{MATCH_PROFILES.keys.join(', ')}"
+            end
+            MATCH_PROFILES[profile].dup
+          end
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/match_options/yaml_resolver.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "base_resolver"
+
+module Canon
+  module Comparison
+    module MatchOptions
+      # YAML-specific match options resolver
+      class YamlResolver < BaseResolver
+        # Format defaults for YAML
+        FORMAT_DEFAULTS = {
+          yaml: {
+            preprocessing: :none,
+            text_content: :strict,
+            structural_whitespace: :ignore,
+            key_order: :ignore,
+            comments: :ignore,
+          },
+        }.freeze
+
+        # Predefined match profiles for YAML
+        MATCH_PROFILES = {
+          # Strict: Match exactly
+          strict: {
+            preprocessing: :none,
+            text_content: :strict,
+            structural_whitespace: :strict,
+            key_order: :strict,
+            comments: :strict,
+          },
+
+          # Spec-friendly: Formatting and order don't matter
+          spec_friendly: {
+            preprocessing: :normalize,
+            text_content: :strict,
+            structural_whitespace: :ignore,
+            key_order: :ignore,
+            comments: :ignore,
+          },
+
+          # Content-only: Only values matter
+          content_only: {
+            preprocessing: :normalize,
+            text_content: :normalize,
+            structural_whitespace: :ignore,
+            key_order: :ignore,
+            comments: :ignore,
+          },
+        }.freeze
+
+        class << self
+          # Matching dimensions for YAML (collectively exhaustive)
+          def match_dimensions
+            %i[
+              text_content
+              structural_whitespace
+              key_order
+              comments
+            ].freeze
+          end
+
+          # Get format-specific default options
+          #
+          # @param format [Symbol] Format type (:yaml)
+          # @return [Hash] Default options for the format
+          def format_defaults(format)
+            FORMAT_DEFAULTS[format]&.dup || FORMAT_DEFAULTS[:yaml].dup
+          end
+
+          # Get options for a named profile
+          #
+          # @param profile [Symbol] Profile name
+          # @return [Hash] Profile options
+          # @raise [Canon::Error] If profile is unknown
+          def get_profile_options(profile)
+            unless MATCH_PROFILES.key?(profile)
+              raise Canon::Error,
+                    "Unknown match profile: #{profile}. " \
+                    "Valid profiles: #{MATCH_PROFILES.keys.join(', ')}"
+            end
+            MATCH_PROFILES[profile].dup
+          end
+        end
+      end
+    end
+  end
+end