canon 0.2.9 → 0.2.12

data/lib/canon/comparison/match_options.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "match_options/base_resolver"
-require_relative "match_options/xml_resolver"
-require_relative "match_options/json_resolver"
-require_relative "match_options/yaml_resolver"
-
 module Canon
   module Comparison
     # Matching Options for Canon Comparison
@@ -41,12 +36,6 @@ module Canon
         @options[:preprocessing]
       end
 
-      # Check if semantic diff is enabled
-      # @return [Boolean] true if semantic diff is enabled
-      def semantic_diff?
-        @options[:semantic_diff] == true
-      end
-
       def to_h
         @options.dup
       end
@@ -54,6 +43,11 @@ module Canon
 
     # Module containing match option utilities and format-specific modules
     module MatchOptions
+      autoload :BaseResolver, "canon/comparison/match_options/base_resolver"
+      autoload :JsonResolver, "canon/comparison/match_options/json_resolver"
+      autoload :XmlResolver, "canon/comparison/match_options/xml_resolver"
+      autoload :YamlResolver, "canon/comparison/match_options/yaml_resolver"
+
       # Preprocessing options - what to do before comparison
       PREPROCESSING_OPTIONS = %i[none c14n normalize format rendered].freeze
 
@@ -90,30 +84,15 @@ module Canon
 
         # Normalize text by collapsing whitespace and trimming
         # Mimics HTML whitespace collapsing
-        #
-        # Handles both ASCII and Unicode whitespace characters including:
-        # - Regular space (U+0020)
-        # - Non-breaking space (U+00A0)
-        # - Other Unicode whitespace per \p{Space}
-        #
-        # @param text [String] Text to normalize
-        # @return [String] Normalized text
         def normalize_text(text)
           return "" if text.nil?
 
           text.to_s
-            .gsub(/[\p{Space}\u00a0]+/, " ") # Collapse all whitespace to single space
+            .gsub(/[\p{Space} ]+/, " ") # Collapse all whitespace to single space
             .strip # Remove leading/trailing whitespace
         end
 
         # Normalize text preserving Unicode whitespace type distinctions.
-        #
-        # Only ASCII whitespace (space, tab, newline, etc.) is collapsed.
-        # Unicode whitespace (NBSP, ideographic space, etc.) is preserved,
-        # so different whitespace types remain distinguishable.
-        #
-        # @param text [String] Text to normalize
-        # @return [String] Normalized text with preserved whitespace types
         def normalize_text_preserving_type(text)
           return "" if text.nil?
 
@@ -123,10 +102,6 @@ module Canon
         end
 
         # Process attribute value according to match behavior
-        #
-        # @param value [String] Attribute value to process
-        # @param behavior [Symbol] Match behavior (:strict, :strip, :compact, :normalize, :ignore)
-        # @return [String] Processed value
         def process_attribute_value(value, behavior)
           case behavior
           when :strict
@@ -134,7 +109,7 @@ module Canon
           when :strip
             value.to_s.strip
           when :compact
-            value.to_s.gsub(/[\p{Space}\u00a0]+/, " ")
+            value.to_s.gsub(/[\p{Space} ]+/, " ")
           when :normalize
             normalize_text(value)
           when :ignore
@@ -147,16 +122,8 @@ module Canon
 
       # XML/HTML-specific matching options
       module Xml
-        # Matching dimensions for XML/HTML (collectively exhaustive)
-        MATCH_DIMENSIONS = %i[
-          text_content
-          structural_whitespace
-          attribute_presence
-          attribute_order
-          attribute_values
-          element_position
-          comments
-        ].freeze
+        # Single source of truth: derived from the DimensionSet in Registry.
+        MATCH_DIMENSIONS = Dimensions::Registry.for(:xml).names.freeze
 
         # Expose FORMAT_DEFAULTS from XmlResolver (for backward compatibility)
         FORMAT_DEFAULTS = MatchOptions::XmlResolver.const_get(:FORMAT_DEFAULTS)
@@ -165,27 +132,18 @@ module Canon
         MATCH_PROFILES = MatchOptions::XmlResolver.const_get(:MATCH_PROFILES)
 
         class << self
-          # Delegate to XmlResolver
           def resolve(**kwargs)
             MatchOptions::XmlResolver.resolve(**kwargs)
           end
 
-          # Delegate to XmlResolver
           def get_profile_options(profile)
             MatchOptions::XmlResolver.get_profile_options(profile)
           end
 
-          # Get valid match dimensions for XML/HTML
-          #
-          # @return [Array<Symbol>] Valid dimensions
           def match_dimensions
             MatchOptions::XmlResolver.match_dimensions
           end
 
-          # Get format-specific default options
-          #
-          # @param format [Symbol] Format type
-          # @return [Hash] Default options for the format
           def format_defaults(format)
             MatchOptions::XmlResolver.format_defaults(format)
           end
@@ -194,41 +152,25 @@ module Canon
 
       # JSON-specific matching options
       module Json
-        # Matching dimensions for JSON (collectively exhaustive)
-        MATCH_DIMENSIONS = %i[
-          text_content
-          structural_whitespace
-          key_order
-        ].freeze
-
-        # Expose FORMAT_DEFAULTS from JsonResolver (for backward compatibility)
+        MATCH_DIMENSIONS = Dimensions::Registry.for(:json).names.freeze
+
         FORMAT_DEFAULTS = MatchOptions::JsonResolver.const_get(:FORMAT_DEFAULTS)
 
-        # Expose MATCH_PROFILES from JsonResolver (for backward compatibility)
         MATCH_PROFILES = MatchOptions::JsonResolver.const_get(:MATCH_PROFILES)
 
         class << self
-          # Delegate to JsonResolver
           def resolve(**kwargs)
             MatchOptions::JsonResolver.resolve(**kwargs)
           end
 
-          # Delegate to JsonResolver
           def get_profile_options(profile)
             MatchOptions::JsonResolver.get_profile_options(profile)
           end
 
-          # Get valid match dimensions for JSON
-          #
-          # @return [Array<Symbol>] Valid dimensions
           def match_dimensions
             MatchOptions::JsonResolver.match_dimensions
           end
 
-          # Get format-specific default options
-          #
-          # @param format [Symbol] Format type
-          # @return [Hash] Default options for the format
           def format_defaults(format)
             MatchOptions::JsonResolver.format_defaults(format)
           end
@@ -237,42 +179,25 @@ module Canon
 
       # YAML-specific matching options
       module Yaml
-        # Matching dimensions for YAML (collectively exhaustive)
-        MATCH_DIMENSIONS = %i[
-          text_content
-          structural_whitespace
-          key_order
-          comments
-        ].freeze
-
-        # Expose FORMAT_DEFAULTS from YamlResolver (for backward compatibility)
+        MATCH_DIMENSIONS = Dimensions::Registry.for(:yaml).names.freeze
+
         FORMAT_DEFAULTS = MatchOptions::YamlResolver.const_get(:FORMAT_DEFAULTS)
 
-        # Expose MATCH_PROFILES from YamlResolver (for backward compatibility)
         MATCH_PROFILES = MatchOptions::YamlResolver.const_get(:MATCH_PROFILES)
 
         class << self
-          # Delegate to YamlResolver
           def resolve(**kwargs)
             MatchOptions::YamlResolver.resolve(**kwargs)
           end
 
-          # Delegate to YamlResolver
           def get_profile_options(profile)
             MatchOptions::YamlResolver.get_profile_options(profile)
           end
 
-          # Get valid match dimensions for YAML
-          #
-          # @return [Array<Symbol>] Valid dimensions
           def match_dimensions
             MatchOptions::YamlResolver.match_dimensions
           end
 
-          # Get format-specific default options
-          #
-          # @param format [Symbol] Format type
-          # @return [Hash] Default options for the format
           def format_defaults(format)
             MatchOptions::YamlResolver.format_defaults(format)
           end

data/lib/canon/comparison/node_inspector.rb

@@ -10,37 +10,25 @@ module Canon
     # * Canon::TreeDiff::Core::TreeNode — semantic tree diff nodes.
     # * Backend-specific nodes (Nokogiri or Moxml) — live parsed nodes.
     #
-    # All type dispatch uses backend-branching (`if XmlBackend.nokogiri?`)
-    # rather than `case/when` with constant references. This prevents
-    # NameError when Nokogiri constants are undefined under Opal.
-    #
-    # Every node query in the codebase should go through this module.
-    # Do not create private dispatch methods in consumers.
+    # Architecture: NodeInspector handles Canon-native types (Canon::Xml::Node,
+    # TreeNode) directly, then delegates ALL backend-specific queries to
+    # XmlParsing. No Moxml/Nokogiri constants are referenced here — that
+    # knowledge lives exclusively in XmlParsing.
     module NodeInspector
-      NOKOGIRI_TEXT_TYPE = defined?(Nokogiri::XML::Node::TEXT_NODE) ? Nokogiri::XML::Node::TEXT_NODE : 3
-
       # --- Type predicates ---
 
       def self.text_node?(node)
         return false unless node
         return node.node_type == :text if node.is_a?(Canon::Xml::Node)
 
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Text) || node.is_a?(Moxml::Text)
-        else
-          node.is_a?(Moxml::Text)
-        end
+        XmlParsing.text_node?(node)
       end
 
       def self.element_node?(node)
         return false unless node
         return node.node_type == :element if node.is_a?(Canon::Xml::Node)
 
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Element) || node.is_a?(Moxml::Element)
-        else
-          node.is_a?(Moxml::Element)
-        end
+        XmlParsing.element?(node)
       end
 
       def self.comment_node?(node)
@@ -57,7 +45,7 @@ module Canon
           end
           false
         else
-          node.is_a?(Moxml::Comment)
+          XmlParsing.comment?(node)
         end
       end
 
@@ -100,7 +88,6 @@ module Canon
 
       # --- Node queries ---
 
-      # Unified node name extraction across all node types.
       def self.name(node)
         return nil unless node
         return node.name if node.is_a?(Canon::Xml::Node)
@@ -109,7 +96,6 @@ module Canon
         XmlParsing.name(node)
       end
 
-      # Unified parent access across all node types.
       def self.parent(node)
         return nil unless node
         return node.parent if node.is_a?(Canon::Xml::Node)
@@ -118,7 +104,6 @@ module Canon
         XmlParsing.parent(node)
       end
 
-      # Unified children access across all node types.
       def self.children(node)
         return [] unless node
         return node.children if node.is_a?(Canon::Xml::Node)
@@ -127,34 +112,21 @@ module Canon
         XmlParsing.children(node)
       end
 
-      # Extract the text content of +node+ as a String.
       def self.text_content(node)
-        case node
-        when Canon::Xml::Nodes::TextNode
-          node.value.to_s
-        when Canon::Xml::Node
-          node.text_content.to_s
-        when Moxml::Text
-          node.content.to_s
-        else
-          XmlParsing.text_content(node).to_s
-        end
+        return node.value.to_s if node.is_a?(Canon::Xml::Nodes::TextNode)
+        return node.text_content.to_s if node.is_a?(Canon::Xml::Node)
+
+        XmlParsing.text_content(node).to_s
       end
 
-      # Unified node type that always returns a symbol.
-      # Returns nil for unrecognised nodes.
       def self.node_type(node)
         return nil unless node
         return node.node_type if node.is_a?(Canon::Xml::Node)
+        return node.type&.to_sym if node.is_a?(Canon::TreeDiff::Core::TreeNode)
 
-        if node.is_a?(Canon::TreeDiff::Core::TreeNode)
-          node.type&.to_sym
-        else
-          XmlParsing.node_type(node)
-        end
+        XmlParsing.node_type(node)
       end
 
-      # Unified attribute value access.
       def self.attribute_value(node, attr_name)
         return nil unless node
 
@@ -168,7 +140,6 @@ module Canon
         end
       end
 
-      # Unified namespace URI access.
       def self.namespace_uri(node)
         return nil unless node
 
@@ -179,7 +150,6 @@ module Canon
         end
       end
 
-      # Extract parse-time errors carried on a node or its owning document.
       def self.parse_errors(node)
         return [] if node.nil?
         return Array(node.parse_errors).map(&:to_s) if node.is_a?(Canon::Xml::Node)
@@ -194,11 +164,6 @@ module Canon
           []
         end
       end
-
-      # Deprecated: use NodeInspector.parent instead.
-      def self.parent_of(node)
-        parent(node)
-      end
     end
   end
 end

data/lib/canon/comparison/pipeline.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    # Shared comparison pipeline helpers used by both algorithms.
+    #
+    # Both `dom_diff` and `semantic_diff` need to:
+    # - detect document format from inputs (with optional hint)
+    # - validate that the two formats are comparable
+    # - merge global config-sourced profile / options into the opts hash
+    # - capture original-string snapshots before parsing mutates inputs
+    # - parse both inputs through the format-specific comparator
+    #
+    # These steps are pure pipeline mechanics — they have nothing to do with
+    # the comparison algorithm itself.  Keeping them here ensures the two
+    # algorithm entrypoints cannot drift out of sync (see lutaml/canon
+    # "Two Comparison Algorithms — Distinct by Design" in CLAUDE.md —
+    # the algorithm cores stay separate; only shared infrastructure is
+    # consolidated).
+    module Pipeline
+      # Formats whose Canon::Config exposes a match profile / options.
+      CONFIG_BACKED_FORMATS = %i[xml html json yaml string].freeze
+
+      # Cross-format compatibility groups.  DOM comparison accepts these
+      # pairings because both sides parse to the same Ruby structure.
+      # Semantic comparison does not — it requires exact format match.
+      COMPATIBLE_FORMAT_GROUPS = [
+        %i[json ruby_object].freeze,
+        %i[yaml ruby_object].freeze,
+      ].freeze
+
+      class << self
+        # Detect formats for both inputs, honouring an explicit hint.
+        #
+        # @param obj1 [Object] First input
+        # @param obj2 [Object] Second input
+        # @param format_hint [Symbol, nil] Explicit format override
+        # @return [Array<Symbol, Symbol>] Detected or hinted formats
+        def detect_formats(obj1, obj2, format_hint)
+          return [format_hint, format_hint] if format_hint
+
+          [FormatDetector.detect(obj1), FormatDetector.detect(obj2)]
+        end
+
+        # True when the two formats can be compared by the DOM algorithm.
+        #
+        # DOM allows `ruby_object` to be compared against `json` or `yaml`
+        # because both sides parse to the same Ruby structure.  Semantic
+        # comparison does not allow this — it requires exact format match.
+        #
+        # @param format1 [Symbol]
+        # @param format2 [Symbol]
+        # @param strict [Boolean] When true, require exact match (semantic)
+        # @return [Boolean]
+        def formats_compatible?(format1, format2, strict: false)
+          return true if format1 == format2
+          return false if strict
+
+          COMPATIBLE_FORMAT_GROUPS.any? do |group|
+            group.include?(format1) && group.include?(format2)
+          end
+        end
+
+        # Raise a helpful error if formats are incompatible.
+        #
+        # @param format1 [Symbol]
+        # @param format2 [Symbol]
+        # @param strict [Boolean] Passed to {formats_compatible?}
+        # @raise [Canon::CompareFormatMismatchError]
+        # @return [void]
+        def validate_compatible!(format1, format2, strict: false)
+          return if formats_compatible?(format1, format2, strict: strict)
+
+          raise Canon::CompareFormatMismatchError.new(format1, format2)
+        end
+
+        # Merge global config-sourced profile and options into `opts`.
+        #
+        # Reads `Canon::Config.instance.<format>.match` for a global
+        # `profile` and `profile_options`, and merges them into a copy of
+        # the supplied opts hash.  Caller-supplied values always win:
+        # config-derived `profile_options` extend rather than replace
+        # caller-supplied `global_options`.
+        #
+        # Returns the original opts hash unchanged when the format is not
+        # config-backed (e.g. `:ruby_object`).
+        #
+        # @param format [Symbol]
+        # @param opts [Hash] Caller opts (will not be mutated)
+        # @return [Hash] New opts hash with config globals merged in
+        def resolve_config(format, opts)
+          return opts unless CONFIG_BACKED_FORMATS.include?(format)
+
+          format_config = Canon::Config.instance.public_send(format)
+          match_config = format_config.match
+          profile = match_config.profile
+          profile_opts = match_config.profile_options
+
+          resolved = opts.dup
+          if resolved[:global_profile].nil? && profile
+            resolved[:global_profile] = profile
+          end
+
+          if profile_opts.any?
+            resolved[:global_options] = merge_profile_options(
+              resolved[:global_options], profile_opts
+            )
+          end
+
+          resolved
+        end
+
+        # Capture pre-parse string snapshots for diff display.
+        #
+        # Parsing (especially HTML) can mutate inputs, so originals must
+        # be captured before any parsing happens.  Strings pass through
+        # unchanged; parsed nodes are serialized via NodeSerializer.
+        #
+        # @param obj1 [Object]
+        # @param obj2 [Object]
+        # @return [Array<String, String>] Captured original strings
+        def capture_originals(obj1, obj2)
+          [extract_original_string(obj1), extract_original_string(obj2)]
+        end
+
+        # Parse both inputs through the format-specific comparator.
+        #
+        # Delegates to `XmlComparator`, `HtmlComparator`, `JsonComparator`,
+        # or `YamlComparator` based on format.  Uses `Cache` so the same
+        # string is not re-parsed across runs.
+        #
+        # @param obj1 [Object]
+        # @param obj2 [Object]
+        # @param format [Symbol]
+        # @param match_opts_hash [Hash] Resolved match options
+        # @return [Array<Object, Object>] Parsed documents
+        def parse_pair(obj1, obj2, format, match_opts_hash)
+          preprocessing = match_opts_hash[:preprocessing] || :none
+
+          case format
+          when :xml
+            [
+              parse_with_cache(obj1, format, preprocessing) do |doc|
+                XmlComparator.parse(doc, preprocessing)
+              end,
+              parse_with_cache(obj2, format, preprocessing) do |doc|
+                XmlComparator.parse(doc, preprocessing)
+              end,
+            ]
+          when :html, :html4, :html5
+            [
+              parse_with_cache(obj1, format, preprocessing) do |doc|
+                HtmlComparator.parse(doc, preprocessing)
+              end,
+              parse_with_cache(obj2, format, preprocessing) do |doc|
+                HtmlComparator.parse(doc, preprocessing)
+              end,
+            ]
+          when :json
+            [
+              parse_with_cache(obj1, format, :none) do |doc|
+                JsonComparator.parse(doc)
+              end,
+              parse_with_cache(obj2, format, :none) do |doc|
+                JsonComparator.parse(doc)
+              end,
+            ]
+          when :yaml
+            [
+              parse_with_cache(obj1, format, :none) do |doc|
+                YamlComparator.parse(doc)
+              end,
+              parse_with_cache(obj2, format, :none) do |doc|
+                YamlComparator.parse(doc)
+              end,
+            ]
+          else
+            [obj1, obj2]
+          end
+        end
+
+        # Pre-parse HTML strings through `HtmlParser.parse(_, :html5)`.
+        #
+        # The DOM comparator needs HTML4 and HTML5 inputs to share HTML's
+        # whitespace-sensitivity semantics, which means routing both
+        # through Nokogiri::HTML5.fragment up front (issue #118).
+        # The semantic comparator does not need this — it uses Canon's
+        # own HTML data model downstream — so this helper is opt-in.
+        #
+        # Returns the inputs unchanged if they are not strings.
+        #
+        # @param obj1 [Object]
+        # @param obj2 [Object]
+        # @return [Array<Object, Object>] Potentially pre-parsed HTML inputs
+        def preparse_html_pair(obj1, obj2)
+          [
+            html_string?(obj1) ? HtmlParser.parse(obj1, :html5) : obj1,
+            html_string?(obj2) ? HtmlParser.parse(obj2, :html5) : obj2,
+          ]
+        end
+
+        # True when the input is a String AND should be treated as HTML.
+        #
+        # @param obj [Object]
+        # @return [Boolean]
+        def html_string?(obj)
+          obj.is_a?(String)
+        end
+
+        private
+
+        # Merge caller-supplied global_options with config profile_opts.
+        #
+        # Caller values win on key conflict; profile_opts fill in gaps.
+        # `MatchConfig#profile_options` already returns a fresh hash
+        # (via `Hash#except`), so we can return it directly without dup.
+        #
+        # @param existing [Hash, nil] Caller-supplied options
+        # @param profile_opts [Hash] Config-sourced options
+        # @return [Hash] Merged hash
+        def merge_profile_options(existing, profile_opts)
+          return profile_opts if existing.nil?
+
+          profile_opts.merge(existing)
+        end
+
+        # Parse a single document with cache lookup.
+        #
+        # @param doc [Object] Document (string or already-parsed)
+        # @param format [Symbol] Document format
+        # @param preprocessing [Symbol] Preprocessing option
+        # @yield Block to parse the document if not cached
+        # @return [Object] Parsed document
+        def parse_with_cache(doc, format, preprocessing)
+          return doc unless doc.is_a?(String)
+
+          Cache.fetch(:document_parse,
+                      Cache.key_for_document(doc, format, preprocessing)) do # rubocop:disable Lint/UselessDefaultValueArgument
+            yield doc
+          end
+        end
+
+        # Extract a string snapshot from various input types.
+        #
+        # Strings pass through; Nokogiri documents use to_html; Canon and
+        # other XML nodes go through NodeSerializer; everything else
+        # falls back to to_s.
+        #
+        # @param obj [Object]
+        # @return [String] String snapshot
+        def extract_original_string(obj)
+          case obj
+          when String
+            obj
+          when Nokogiri::XML::Document, Nokogiri::HTML::Document,
+               Nokogiri::XML::DocumentFragment, Nokogiri::HTML::DocumentFragment
+            obj.to_html
+          else
+            if Canon::XmlParsing.xml_node?(obj) || obj.is_a?(Canon::Xml::Node)
+              Canon::XmlParsing.serialize(obj)
+            else
+              obj.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/profile_definition.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "match_options"
-
 module Canon
   module Comparison
     # Profile definition DSL with full validation

data/lib/canon/comparison/ruby_object_comparator.rb

@@ -172,7 +172,7 @@ module Canon
           path: path,
           value1: obj1,
           value2: obj2,
-          difference: diff_code,
+          diff_code: diff_code,
         }
       end
     end