canon 0.2.11 → 0.2.12

data/lib/canon/comparison/markup_comparator.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../comparison" # Load base module with constants
-require_relative "node_inspector"
-require_relative "../diff/diff_node"
-require_relative "../diff/path_builder"
-
 module Canon
   module Comparison
     # Base class for markup document comparison (XML, HTML)
@@ -17,67 +12,16 @@ module Canon
     # inherit from this class and add format-specific behavior.
     class MarkupComparator
       class << self
-        # Add a difference to the differences array
-        #
-        # Creates a DiffNode with enriched metadata including path,
-        # serialized content, and attributes for Stage 4 rendering.
+        # Add a difference to the differences array.
         #
-        # @param node1 [Object, nil] First node
-        # @param node2 [Object, nil] Second node
-        # @param diff1 [Symbol] Difference type for node1
-        # @param diff2 [Symbol] Difference type for node2
-        # @param dimension [Symbol] The match dimension causing this difference
-        # @param _opts [Hash] Options (unused but kept for interface compatibility)
-        # @param differences [Array] Array to append difference to
+        # Delegates to DiffNodeBuilder, the single DiffNode factory for
+        # the DOM comparison path.
         def add_difference(node1, node2, diff1, diff2, dimension, _opts,
                            differences)
-          # All differences must be DiffNode objects (OO architecture)
-          if dimension.nil?
-            raise ArgumentError,
-                  "dimension required for DiffNode"
-          end
-
-          # Build informative reason message
-          reason = build_difference_reason(node1, node2, diff1, diff2,
-                                           dimension)
-
-          # Enrich with path, serialized content, and attributes for Stage 4 rendering
-          metadata = enrich_diff_metadata(node1, node2)
-
-          diff_node = Canon::Diff::DiffNode.new(
-            node1: node1,
-            node2: node2,
-            dimension: dimension,
-            reason: reason,
-            **metadata,
+          differences << Canon::Comparison::DiffNodeBuilder.build(
+            node1: node1, node2: node2, diff1: diff1, diff2: diff2,
+            dimension: dimension
           )
-          differences << diff_node
-        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 enrich_diff_metadata(node1, node2)
-          {
-            path: build_path_for_node(node1 || node2),
-            serialized_before: serialize_node(node1),
-            serialized_after: serialize_node(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 build_path_for_node(node)
-          return nil if node.nil?
-
-          Canon::Diff::PathBuilder.build(node, format: :document)
         end
 
         # Serialize a node to string for display
@@ -87,24 +31,7 @@ module Canon
         def serialize_node(node)
           return nil if node.nil?
 
-          # Canon::Xml::Node types
-          case node
-          when Canon::Xml::Nodes::RootNode
-            # Serialize all children of root
-            node.children.map { |child| serialize_node(child) }.join
-          when Canon::Xml::Nodes::ElementNode
-            serialize_element_node(node)
-          when Canon::Xml::Nodes::TextNode
-            # Use original text (with entity references) if available,
-            # otherwise fall back to value (decoded text)
-            node.original || node.value
-          when Canon::Xml::Nodes::CommentNode
-            "<!--#{node.value}-->"
-          when Canon::Xml::Nodes::ProcessingInstructionNode
-            "<?#{node.target} #{node.data}?>"
-          else
-            node.to_s
-          end
+          Canon::Diff::NodeSerializer.serialize(node)
         end
 
         # Extract attributes from a node
@@ -114,19 +41,7 @@ module Canon
         def extract_attributes(node)
           return nil if node.nil?
 
-          # Canon::Xml::Node ElementNode
-          if node.is_a?(Canon::Xml::Nodes::ElementNode)
-            node.attribute_nodes.to_h do |attr|
-              [attr.name, attr.value]
-            end
-          # Nokogiri elements
-          elsif node.is_a?(Nokogiri::XML::Element)
-            node.attributes.to_h do |_, attr|
-              [attr.name, attr.value]
-            end
-          else
-            {}
-          end
+          Canon::Diff::NodeSerializer.extract_attributes(node)
         end
 
         # Filter children based on options
@@ -278,65 +193,11 @@ module Canon
 
         # Build a human-readable reason for a difference
         #
-        # @param node1 [Object, nil] First node
-        # @param node2 [Object, nil] Second node
-        # @param diff1 [Symbol] Difference type for node1
-        # @param diff2 [Symbol] Difference type for node2
-        # @param dimension [Symbol] The dimension of the difference
-        # @return [String] Human-readable reason
+        # Delegates to DiffNodeBuilder for consistency.
         def build_difference_reason(node1, node2, diff1, diff2, dimension)
-          # For attribute presence differences, show what attributes differ
-          if dimension == :attribute_presence
-            attrs1 = extract_attributes(node1)
-            attrs2 = extract_attributes(node2)
-            return build_attribute_difference_reason(attrs1, attrs2)
-          end
-
-          # For text content differences, show the actual text (truncated if needed)
-          if dimension == :text_content
-            text1 = extract_text_content_from_node(node1)
-            text2 = extract_text_content_from_node(node2)
-            return build_text_difference_reason(text1, text2)
-          end
-
-          # Default reason - can be overridden in subclasses
-          if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
-            "element structure mismatch (children differ)"
-          else
-            Canon::Comparison.code_pair_label(diff1, diff2)
-          end
-        end
-
-        # Build a clear reason message for attribute presence differences
-        # Shows which attributes are only in node1, only in node2, or different values
-        #
-        # @param attrs1 [Hash, nil] First node's attributes
-        # @param attrs2 [Hash, nil] Second node's attributes
-        # @return [String] Clear explanation of the attribute difference
-        def build_attribute_difference_reason(attrs1, attrs2)
-          return "#{attrs1&.keys&.size || 0} vs #{attrs2&.keys&.size || 0} attributes" unless attrs1 && attrs2
-
-          require "set"
-          keys1 = attrs1.keys.to_set
-          keys2 = attrs2.keys.to_set
-
-          only_in_1 = keys1 - keys2
-          only_in_2 = keys2 - keys1
-          common = keys1 & keys2
-
-          # Check if values differ for common keys
-          different_values = common.reject { |k| attrs1[k] == attrs2[k] }
-
-          parts = []
-          parts << "only in first: #{only_in_1.to_a.sort.join(', ')}" if only_in_1.any?
-          parts << "only in second: #{only_in_2.to_a.sort.join(', ')}" if only_in_2.any?
-          parts << "different values: #{different_values.sort.join(', ')}" if different_values.any?
-
-          if parts.empty?
-            "#{keys1.size} vs #{keys2.size} attributes (same names)"
-          else
-            parts.join("; ")
-          end
+          Canon::Comparison::DiffNodeBuilder.build_reason(
+            node1, node2, diff1, diff2, dimension
+          )
         end
 
         # Extract text content from a node for diff reason
@@ -344,69 +205,12 @@ module Canon
         # @param node [Object, nil] Node to extract text from
         # @return [String, nil] Text content or nil
         def extract_text_content_from_node(node)
-          return nil if node.nil?
-
-          case node
-          when Canon::Xml::Nodes::TextNode
-            node.value
-          when Canon::Xml::Node
-            node.text_content
-          when Nokogiri::XML::Node
-            node.content.to_s
-          when String
-            node
-          else
-            node.to_s
-          end
-        rescue StandardError
-          nil
-        end
-
-        # Build a clear reason message for text content differences
-        # Shows the actual text content (truncated if too long)
-        #
-        # @param text1 [String, nil] First text content
-        # @param text2 [String, nil] Second text content
-        # @return [String] Clear explanation of the text difference
-        def build_text_difference_reason(text1, text2)
-          # Handle nil cases
-          return "missing vs '#{truncate_text(text2)}'" if text1.nil? && text2
-          return "'#{truncate_text(text1)}' vs missing" if text1 && text2.nil?
-          return "both missing" if text1.nil? && text2.nil?
-
-          # Both have content - show truncated versions
-          "'#{truncate_text(text1)}' vs '#{truncate_text(text2)}'"
+          Canon::Comparison::DiffNodeBuilder.extract_text_content(node)
         end
 
         # Truncate text for display in reason messages
-        #
-        # @param text [String] Text to truncate
-        # @param max_length [Integer] Maximum length
-        # @return [String] Truncated text
         def truncate_text(text, max_length = 40)
-          return "" if text.nil?
-
-          text = text.to_s
-          return text if text.length <= max_length
-
-          "#{text[0...max_length]}..."
-        end
-
-        # Serialize an element node to string
-        #
-        # @param node [Canon::Xml::Nodes::ElementNode] Element node
-        # @return [String] Serialized element
-        def serialize_element_node(node)
-          attrs = node.attribute_nodes.map do |a|
-            " #{a.name}=\"#{a.value}\""
-          end.join
-          children_xml = node.children.map { |c| serialize_node(c) }.join
-
-          if children_xml.empty?
-            "<#{node.name}#{attrs}/>"
-          else
-            "<#{node.name}#{attrs}>#{children_xml}</#{node.name}>"
-          end
+          Canon::Comparison::DiffNodeBuilder.truncate(text, max_length)
         end
 
         # Determine the appropriate dimension for a node type

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

@@ -84,34 +84,23 @@ module Canon
                   "#{self.class} must implement #get_profile_options"
           end
 
-          # Get valid match dimensions for this format
-          # Subclasses should override this
+          # Get valid match dimensions for this format.
+          # Delegates to the DimensionSet from the Registry.
           #
           # @return [Array<Symbol>] Valid dimensions
           def match_dimensions
-            raise NotImplementedError,
-                  "#{self.class} must implement #match_dimensions"
+            dimension_set.names
           end
 
           protected
 
-          # Valid match behaviors per dimension for this format.
-          # Override in subclasses to provide format-specific behaviors.
-          # Used for per-dimension validation in validate_match_options!
+          # The DimensionSet for this resolver's format.
+          # Subclasses override to declare which format they handle.
           #
-          # @return [Hash{Symbol => Array<Symbol>}] Dimension to valid behaviors mapping
-          def dimension_behaviors
-            # Default: XML/HTML behaviors (override in JSON/YAML resolvers)
-            {
-              text_content: %i[strict normalize ignore].freeze,
-              structural_whitespace: %i[strict normalize ignore].freeze,
-              attribute_presence: %i[strict ignore].freeze,
-              attribute_order: %i[strict ignore].freeze,
-              attribute_values: %i[strict strip compact normalize
-                                   ignore].freeze,
-              element_position: %i[strict ignore].freeze,
-              comments: %i[strict ignore].freeze,
-            }
+          # @return [Canon::Comparison::Dimensions::DimensionSet]
+          def dimension_set
+            raise NotImplementedError,
+                  "#{self.class} must implement #dimension_set"
           end
 
           # Validate preprocessing option
@@ -126,12 +115,14 @@ module Canon
             end
           end
 
-          # Validate match options using per-dimension behavior validation
+          # Validate match options using the DimensionSet for dimension
+          # and behavior validation.
           #
           # @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
+            set = dimension_set
+
             special_options = %i[
               format
               preprocessing
@@ -150,21 +141,19 @@ module Canon
             ]
 
             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)
+              dim = set[dimension]
+              unless dim
                 raise Canon::Error,
                       "Unknown match dimension: #{dimension}. " \
-                      "Valid dimensions: #{match_dimensions.join(', ')}"
+                      "Valid dimensions: #{set.names.join(', ')}"
               end
 
-              # Per-dimension behavior validation using overridable method
-              valid_behaviors = dimension_behaviors[dimension]
-              unless valid_behaviors&.include?(behavior)
+              unless dim.valid_behavior?(behavior)
                 raise Canon::Error,
                       "Unknown match behavior: #{behavior} for #{dimension}. " \
-                      "Valid behaviors for #{dimension}: #{valid_behaviors&.join(', ')}"
+                      "Valid behaviors for #{dimension}: #{dim.valid_behaviors.join(', ')}"
               end
             end
           end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base_resolver"
-
 module Canon
   module Comparison
     module MatchOptions
@@ -19,7 +17,6 @@ module Canon
 
         # Predefined match profiles for JSON
         MATCH_PROFILES = {
-          # Strict: Match exactly
           strict: {
             preprocessing: :none,
             text_content: :strict,
@@ -27,7 +24,6 @@ module Canon
             key_order: :strict,
           },
 
-          # Spec-friendly: Formatting and order don't matter
           spec_friendly: {
             preprocessing: :normalize,
             text_content: :strict,
@@ -35,7 +31,6 @@ module Canon
             key_order: :ignore,
           },
 
-          # Content-only: Only values matter
           content_only: {
             preprocessing: :normalize,
             text_content: :normalize,
@@ -45,28 +40,12 @@ module Canon
         }.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,
@@ -76,13 +55,10 @@ module Canon
             MATCH_PROFILES[profile].dup
           end
 
-          # JSON-specific dimension behaviors
-          def dimension_behaviors
-            {
-              text_content: %i[strict normalize ignore].freeze,
-              structural_whitespace: %i[strict normalize ignore].freeze,
-              key_order: %i[strict ignore].freeze,
-            }
+          protected
+
+          def dimension_set
+            Canon::Comparison::Dimensions::Registry.for(:json)
           end
         end
       end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base_resolver"
-
 module Canon
   module Comparison
     module MatchOptions
@@ -41,9 +39,6 @@ module Canon
 
         # Predefined match profiles for XML/HTML
         MATCH_PROFILES = {
-          # Strict: Match exactly as written in source (XML default).
-          # Structural whitespace is stripped by default for XML.
-          # Use preserve_whitespace_elements to preserve structural whitespace in specific elements.
           strict: {
             preprocessing: :none,
             text_content: :strict,
@@ -56,8 +51,6 @@ module Canon
             whitespace_type: :strict,
           },
 
-          # Rendered: Match rendered output (HTML default)
-          # Mimics CSS whitespace collapsing
           rendered: {
             preprocessing: :none,
             text_content: :normalize,
@@ -70,8 +63,6 @@ module Canon
             whitespace_type: :strict,
           },
 
-          # HTML4: Match HTML4 rendered output
-          # HTML4 rendering normalizes attribute whitespace
           html4: {
             preprocessing: :rendered,
             text_content: :normalize,
@@ -84,7 +75,6 @@ module Canon
             whitespace_type: :strict,
           },
 
-          # HTML5: Match HTML5 rendered output (same as rendered)
           html5: {
             preprocessing: :rendered,
             text_content: :normalize,
@@ -97,8 +87,6 @@ module Canon
             whitespace_type: :strict,
           },
 
-          # Spec-friendly: Formatting doesn't matter
-          # Uses :rendered preprocessing for HTML which normalizes via to_html
           spec_friendly: {
             preprocessing: :rendered,
             text_content: :normalize,
@@ -111,7 +99,6 @@ module Canon
             whitespace_type: :strict,
           },
 
-          # Content-only: Only content matters
           content_only: {
             preprocessing: :c14n,
             text_content: :normalize,
@@ -126,32 +113,12 @@ module Canon
         }.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,
@@ -161,18 +128,10 @@ module Canon
             MATCH_PROFILES[profile].dup
           end
 
-          # XML/HTML-specific dimension behaviors
-          def dimension_behaviors
-            {
-              text_content: %i[strict normalize ignore].freeze,
-              structural_whitespace: %i[strict normalize ignore].freeze,
-              attribute_presence: %i[strict ignore].freeze,
-              attribute_order: %i[strict ignore].freeze,
-              attribute_values: %i[strict strip compact normalize
-                                   ignore].freeze,
-              element_position: %i[strict ignore].freeze,
-              comments: %i[strict ignore].freeze,
-            }
+          protected
+
+          def dimension_set
+            Canon::Comparison::Dimensions::Registry.for(:xml)
           end
         end
       end

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "base_resolver"
-
 module Canon
   module Comparison
     module MatchOptions
@@ -20,7 +18,6 @@ module Canon
 
         # Predefined match profiles for YAML
         MATCH_PROFILES = {
-          # Strict: Match exactly
           strict: {
             preprocessing: :none,
             text_content: :strict,
@@ -29,7 +26,6 @@ module Canon
             comments: :strict,
           },
 
-          # Spec-friendly: Formatting and order don't matter
           spec_friendly: {
             preprocessing: :normalize,
             text_content: :strict,
@@ -38,7 +34,6 @@ module Canon
             comments: :ignore,
           },
 
-          # Content-only: Only values matter
           content_only: {
             preprocessing: :normalize,
             text_content: :normalize,
@@ -49,29 +44,12 @@ module Canon
         }.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,
@@ -81,14 +59,10 @@ module Canon
             MATCH_PROFILES[profile].dup
           end
 
-          # YAML-specific dimension behaviors
-          def dimension_behaviors
-            {
-              text_content: %i[strict normalize ignore].freeze,
-              structural_whitespace: %i[strict normalize ignore].freeze,
-              key_order: %i[strict ignore].freeze,
-              comments: %i[strict ignore].freeze,
-            }
+          protected
+
+          def dimension_set
+            Canon::Comparison::Dimensions::Registry.for(:yaml)
           end
         end
       end