canon 0.1.7 → 0.1.9

data/lib/canon/comparison/dimensions/comments_dimension.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative "base_dimension"
+
+module Canon
+  module Comparison
+    module Dimensions
+      # Comments dimension
+      #
+      # Handles comparison of comment nodes.
+      # Supports :strict and :ignore behaviors.
+      #
+      # Behaviors:
+      # - :strict - Exact comment comparison including whitespace
+      # - :ignore - Skip comment comparison
+      class CommentsDimension < BaseDimension
+        # Extract comments from a node
+        #
+        # @param node [Moxml::Node, Nokogiri::XML::Node] Node to extract from
+        # @return [Array<String>] Array of comment strings
+        def extract_data(node)
+          return [] unless node
+
+          # Handle Moxml nodes
+          if node.is_a?(Moxml::Node)
+            extract_from_moxml(node)
+          # Handle Nokogiri nodes
+          elsif node.is_a?(Nokogiri::XML::Node)
+            extract_from_nokogiri(node)
+          else
+            []
+          end
+        end
+
+        # Strict comment comparison
+        #
+        # @param comments1 [Array<String>] First comments array
+        # @param comments2 [Array<String>] Second comments array
+        # @return [Boolean] true if comments are exactly equal
+        def compare_strict(comments1, comments2)
+          comments1 == comments2
+        end
+
+        # Normalized comment comparison
+        #
+        # For comments, normalized comparison collapses whitespace in each comment.
+        #
+        # @param comments1 [Array<String>] First comments array
+        # @param comments2 [Array<String>] Second comments array
+        # @return [Boolean] true if normalized comments are equal
+        def compare_normalize(comments1, comments2)
+          normalize_comments(comments1) == normalize_comments(comments2)
+        end
+
+        private
+
+        # Extract comments from Moxml node
+        #
+        # @param node [Moxml::Node] Moxml node
+        # @return [Array<String>] Array of comment strings
+        def extract_from_moxml(node)
+          comments = []
+
+          # If node itself is a comment
+          if node.node_type == :comment
+            comments << node.content
+          end
+
+          # Extract child comments
+          node.children.each do |child|
+            comments << child.content if child.node_type == :comment
+          end
+
+          comments
+        end
+
+        # Extract comments from Nokogiri node
+        #
+        # @param node [Nokogiri::XML::Node] Nokogiri node
+        # @return [Array<String>] Array of comment strings
+        def extract_from_nokogiri(node)
+          comments = []
+
+          # If node itself is a comment
+          if node.node_type == Nokogiri::XML::Node::COMMENT_NODE
+            comments << node.content
+          end
+
+          # Extract child comments
+          node.children.each do |child|
+            if child.node_type == Nokogiri::XML::Node::COMMENT_NODE
+              comments << child.content
+            end
+          end
+
+          comments
+        end
+
+        # Normalize comments by collapsing whitespace
+        #
+        # @param comments [Array<String>] Comments to normalize
+        # @return [Array<String>] Normalized comments
+        def normalize_comments(comments)
+          comments.map { |c| normalize_text(c) }
+        end
+
+        # Normalize text by collapsing whitespace
+        #
+        # @param text [String, nil] Text to normalize
+        # @return [String] Normalized text
+        def normalize_text(text)
+          return "" if text.nil?
+
+          text.to_s
+            .gsub(/[\p{Space}\u00a0]+/, " ")
+            .strip
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/dimensions/element_position_dimension.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "base_dimension"
+
+module Canon
+  module Comparison
+    module Dimensions
+      # Element position dimension
+      #
+      # Handles comparison of element positions within their parent.
+      # Supports :strict and :ignore behaviors.
+      #
+      # Behaviors:
+      # - :strict - Elements must appear in the same position (index)
+      # - :ignore - Element position doesn't matter
+      class ElementPositionDimension < BaseDimension
+        # Extract element position from a node
+        #
+        # Returns the index of this node among its siblings of the same type.
+        #
+        # @param node [Moxml::Node, Nokogiri::XML::Node] Node to extract from
+        # @return [Integer] Position index (0-based)
+        def extract_data(node)
+          return 0 unless node
+
+          # Handle Moxml nodes
+          if node.is_a?(Moxml::Node)
+            extract_from_moxml(node)
+          # Handle Nokogiri nodes
+          elsif node.is_a?(Nokogiri::XML::Node)
+            extract_from_nokogiri(node)
+          else
+            0
+          end
+        end
+
+        # Strict element position comparison
+        #
+        # @param pos1 [Integer] First position
+        # @param pos2 [Integer] Second position
+        # @return [Boolean] true if positions are equal
+        def compare_strict(pos1, pos2)
+          pos1 == pos2
+        end
+
+        private
+
+        # Extract position from Moxml node
+        #
+        # @param node [Moxml::Node] Moxml node
+        # @return [Integer] Position index
+        def extract_from_moxml(node)
+          return 0 unless node.parent
+
+          # Find position among siblings of the same element name
+          siblings = node.parent.children
+          node.name
+
+          siblings.each_with_index do |sibling, index|
+            if sibling == node
+              return index
+            end
+          end
+
+          0
+        end
+
+        # Extract position from Nokogiri node
+        #
+        # @param node [Nokogiri::XML::Node] Nokogiri node
+        # @return [Integer] Position index
+        def extract_from_nokogiri(node)
+          return 0 unless node.parent
+
+          # Find position among siblings
+          siblings = node.parent.children
+          node.name
+
+          siblings.each_with_index do |sibling, index|
+            if sibling == node
+              return index
+            end
+          end
+
+          0
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/dimensions/registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "base_dimension"
+require_relative "text_content_dimension"
+require_relative "comments_dimension"
+require_relative "attribute_values_dimension"
+require_relative "attribute_presence_dimension"
+require_relative "attribute_order_dimension"
+require_relative "element_position_dimension"
+require_relative "structural_whitespace_dimension"
+
+module Canon
+  module Comparison
+    module Dimensions
+      # Registry for comparison dimensions
+      #
+      # Provides a central access point for all dimension classes
+      # and maps dimension symbols to their implementations.
+      module Registry
+        # Dimension class mappings
+        DIMENSION_CLASSES = {
+          text_content: TextContentDimension,
+          comments: CommentsDimension,
+          attribute_values: AttributeValuesDimension,
+          attribute_presence: AttributePresenceDimension,
+          attribute_order: AttributeOrderDimension,
+          element_position: ElementPositionDimension,
+          structural_whitespace: StructuralWhitespaceDimension,
+        }.freeze
+
+        # Get a dimension instance by name
+        #
+        # @param dimension_name [Symbol] Dimension name
+        # @return [BaseDimension] Dimension instance
+        # @raise [Canon::Error] if dimension is unknown
+        def self.get(dimension_name)
+          dimension_class = DIMENSION_CLASSES[dimension_name]
+
+          unless dimension_class
+            raise Canon::Error,
+                  "Unknown dimension: #{dimension_name}. " \
+                  "Valid dimensions: #{DIMENSION_CLASSES.keys.join(', ')}"
+          end
+
+          dimension_class.new
+        end
+
+        # Get all available dimension names
+        #
+        # @return [Array<Symbol>] Available dimension names
+        def self.available_dimensions
+          DIMENSION_CLASSES.keys
+        end
+
+        # Check if a dimension is available
+        #
+        # @param dimension_name [Symbol] Dimension name
+        # @return [Boolean] true if dimension is available
+        def self.dimension_exists?(dimension_name)
+          DIMENSION_CLASSES.key?(dimension_name)
+        end
+
+        # Compare two nodes for a specific dimension
+        #
+        # @param dimension_name [Symbol] Dimension name
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param behavior [Symbol] Comparison behavior
+        # @return [Boolean] true if nodes match for this dimension
+        def self.compare(dimension_name, node1, node2, behavior)
+          dimension = get(dimension_name)
+          dimension.equivalent?(node1, node2, behavior)
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/dimensions/structural_whitespace_dimension.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative "base_dimension"
+require_relative "../match_options"
+
+module Canon
+  module Comparison
+    module Dimensions
+      # Structural whitespace dimension
+      #
+      # Handles comparison of structural whitespace (whitespace between elements).
+      # Supports :strict, :normalize, and :ignore behaviors.
+      #
+      # Behaviors:
+      # - :strict - Exact whitespace comparison
+      # - :normalize - Collapse whitespace and compare
+      # - :ignore - Skip structural whitespace comparison
+      class StructuralWhitespaceDimension < BaseDimension
+        # Extract structural whitespace from a node
+        #
+        # Returns whitespace text nodes that are between elements (structural).
+        #
+        # @param node [Moxml::Node, Nokogiri::XML::Node] Node to extract from
+        # @return [Array<String>] Array of structural whitespace strings
+        def extract_data(node)
+          return [] unless node
+
+          # Handle Moxml nodes
+          if node.is_a?(Moxml::Node)
+            extract_from_moxml(node)
+          # Handle Nokogiri nodes
+          elsif node.is_a?(Nokogiri::XML::Node)
+            extract_from_nokogiri(node)
+          else
+            []
+          end
+        end
+
+        # Strict structural whitespace comparison
+        #
+        # @param ws1 [Array<String>] First whitespace array
+        # @param ws2 [Array<String>] Second whitespace array
+        # @return [Boolean] true if structural whitespace is exactly equal
+        def compare_strict(ws1, ws2)
+          ws1 == ws2
+        end
+
+        # Normalized structural whitespace comparison
+        #
+        # Collapses whitespace in each entry and compares.
+        #
+        # @param ws1 [Array<String>] First whitespace array
+        # @param ws2 [Array<String>] Second whitespace array
+        # @return [Boolean] true if normalized structural whitespace is equal
+        def compare_normalize(ws1, ws2)
+          normalize_whitespace(ws1) == normalize_whitespace(ws2)
+        end
+
+        private
+
+        # Extract structural whitespace from Moxml node
+        #
+        # @param node [Moxml::Node] Moxml node
+        # @return [Array<String>] Array of structural whitespace strings
+        def extract_from_moxml(node)
+          whitespace = []
+
+          node.children.each do |child|
+            if child.node_type == :text
+              text = child.content.strip
+              # Check if this is purely whitespace (structural)
+              if text.empty? || child.content =~ /\A\s*\z/
+                whitespace << child.content
+              end
+            end
+          end
+
+          whitespace
+        end
+
+        # Extract structural whitespace from Nokogiri node
+        #
+        # @param node [Nokogiri::XML::Node] Nokogiri node
+        # @return [Array<String>] Array of structural whitespace strings
+        def extract_from_nokogiri(node)
+          whitespace = []
+
+          node.children.each do |child|
+            if child.node_type == Nokogiri::XML::Node::TEXT_NODE
+              text = child.content.strip
+              # Check if this is purely whitespace (structural)
+              if text.empty? || child.content =~ /\A\s*\z/
+                whitespace << child.content
+              end
+            end
+          end
+
+          whitespace
+        end
+
+        # Normalize whitespace array
+        #
+        # @param whitespace [Array<String>] Whitespace strings
+        # @return [Array<String>] Normalized whitespace strings
+        def normalize_whitespace(whitespace)
+          whitespace.map { |ws| normalize_text(ws) }
+        end
+
+        # Normalize text
+        #
+        # @param text [String, nil] Text to normalize
+        # @return [String] Normalized text
+        def normalize_text(text)
+          MatchOptions.normalize_text(text)
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/dimensions/text_content_dimension.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "base_dimension"
+require_relative "../match_options"
+
+module Canon
+  module Comparison
+    module Dimensions
+      # Text content dimension
+      #
+      # Handles comparison of text content in nodes.
+      # Supports :strict, :normalize, and :ignore behaviors.
+      #
+      # Behaviors:
+      # - :strict - Exact text comparison including whitespace
+      # - :normalize - Collapse whitespace and compare
+      # - :ignore - Skip text content comparison
+      class TextContentDimension < BaseDimension
+        # Extract text content from a node
+        #
+        # @param node [Moxml::Node, Nokogiri::XML::Node] Node to extract from
+        # @return [String, nil] Text content or nil if not a text node
+        def extract_data(node)
+          return nil unless node
+
+          # Handle Moxml nodes
+          if node.is_a?(Moxml::Node)
+            extract_from_moxml(node)
+          # Handle Nokogiri nodes
+          elsif node.is_a?(Nokogiri::XML::Node)
+            extract_from_nokogiri(node)
+          end
+        end
+
+        # Strict text comparison
+        #
+        # @param text1 [String, nil] First text
+        # @param text2 [String, nil] Second text
+        # @return [Boolean] true if texts are exactly equal
+        def compare_strict(text1, text2)
+          text1.to_s == text2.to_s
+        end
+
+        # Normalized text comparison
+        #
+        # Collapses whitespace and compares.
+        #
+        # @param text1 [String, nil] First text
+        # @param text2 [String, nil] Second text
+        # @return [Boolean] true if normalized texts are equal
+        def compare_normalize(text1, text2)
+          normalize_text(text1) == normalize_text(text2)
+        end
+
+        private
+
+        # Extract text from Moxml node
+        #
+        # @param node [Moxml::Node] Moxml node
+        # @return [String, nil] Text content
+        def extract_from_moxml(node)
+          case node.node_type
+          when :text, :cdata
+            node.content
+          when :element
+            # For element nodes, extract concatenated text from children
+            node.text
+          end
+        end
+
+        # Extract text from Nokogiri node
+        #
+        # @param node [Nokogiri::XML::Node] Nokogiri node
+        # @return [String, nil] Text content
+        def extract_from_nokogiri(node)
+          case node.node_type
+          when Nokogiri::XML::Node::TEXT_NODE, Nokogiri::XML::Node::CDATA_SECTION_NODE
+            node.content
+          when Nokogiri::XML::Node::ELEMENT_NODE
+            node.content
+          end
+        end
+
+        # Normalize text by collapsing whitespace
+        #
+        # Uses MatchOptions.normalize_text for consistency.
+        #
+        # @param text [String, nil] Text to normalize
+        # @return [String] Normalized text
+        def normalize_text(text)
+          MatchOptions.normalize_text(text)
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/dimensions.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Comparison dimensions
+#
+# Provides dimension classes for comparing specific aspects of documents.
+# Each dimension knows how to extract and compare data according to different behaviors.
+#
+# == Architecture
+#
+# Dimensions represent "WHAT to compare" - specific aspects of a document that can be compared:
+# - Text content
+# - Comments
+# - Attribute values
+# - Attribute presence
+# - Attribute order
+# - Element position
+# - Structural whitespace
+#
+# == Behaviors
+#
+# Each dimension supports comparison behaviors:
+# - :strict - Exact comparison
+# - :normalize - Normalized comparison (e.g., collapse whitespace)
+# - :ignore - Skip comparison
+#
+# == Usage
+#
+#   # Get a dimension instance
+#   dimension = Canon::Comparison::Dimensions::Registry.get(:text_content)
+#
+#   # Compare two nodes
+#   dimension.equivalent?(node1, node2, :normalize)
+#
+#   # Or use the registry directly
+#   Canon::Comparison::Dimensions::Registry.compare(:text_content, node1, node2, :normalize)
+
+require_relative "dimensions/base_dimension"
+require_relative "dimensions/registry"
+require_relative "dimensions/text_content_dimension"
+require_relative "dimensions/comments_dimension"
+require_relative "dimensions/attribute_values_dimension"
+require_relative "dimensions/attribute_presence_dimension"
+require_relative "dimensions/attribute_order_dimension"
+require_relative "dimensions/element_position_dimension"
+require_relative "dimensions/structural_whitespace_dimension"
+
+module Canon
+  module Comparison
+    module Dimensions
+      # Version constant for the dimensions module
+      VERSION = "1.0.0"
+    end
+  end
+end

data/lib/canon/comparison/format_detector.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    # Format detection service for auto-detecting document formats
+    #
+    # Provides format detection for various document types including XML, HTML,
+    # JSON, YAML, and plain text. Uses caching for performance optimization.
+    #
+    # @example Detect format from a string
+    #   FormatDetector.detect("<root>content</root>") # => :xml
+    #
+    # @example Detect format from an object
+    #   FormatDetector.detect(Moxml::Document.new) # => :xml
+    class FormatDetector
+      # Supported format types
+      FORMATS = %i[xml html json yaml ruby_object string].freeze
+
+      class << self
+        # Detect the format of an object
+        #
+        # @param obj [Object] Object to detect format of
+        # @return [Symbol] Format type (:xml, :html, :json, :yaml, :ruby_object, :string)
+        def detect(obj)
+          case obj
+          when Moxml::Node, Moxml::Document
+            :xml
+          when Nokogiri::HTML::DocumentFragment, Nokogiri::HTML5::DocumentFragment
+            # HTML DocumentFragments
+            :html
+          when Nokogiri::XML::DocumentFragment
+            # XML DocumentFragments - check if it's actually HTML
+            obj.document&.html? ? :html : :xml
+          when Nokogiri::XML::Document, Nokogiri::XML::Node
+            # Check if it's HTML by looking at the document type
+            obj.html? ? :html : :xml
+          when Nokogiri::HTML::Document, Nokogiri::HTML5::Document
+            :html
+          when String
+            detect_string(obj)
+          when Hash, Array
+            # Raw Ruby objects (from parsed JSON/YAML)
+            :ruby_object
+          else
+            raise Canon::Error, "Unknown format for object: #{obj.class}"
+          end
+        end
+
+        # Detect the format of a string with caching
+        #
+        # @param str [String] String to detect format of
+        # @return [Symbol] Format type
+        def detect_string(str)
+          # Use cache for format detection
+          Cache.fetch(:format_detect, Cache.key_for_format_detection(str)) do
+            detect_string_uncached(str)
+          end
+        end
+
+        # Detect the format of a string without caching
+        #
+        # @param str [String] String to detect format of
+        # @return [Symbol] Format type
+        def detect_string_uncached(str)
+          trimmed = str.strip
+
+          # YAML indicators
+          return :yaml if trimmed.start_with?("---")
+          return :yaml if trimmed.match?(/^[a-zA-Z_]\w*:\s/)
+
+          # JSON indicators
+          return :json if trimmed.start_with?("{", "[")
+
+          # HTML indicators
+          return :html if trimmed.start_with?("<!DOCTYPE html", "<html",
+                                              "<HTML")
+
+          # XML indicators - must start with < and end with >
+          return :xml if trimmed.start_with?("<") && trimmed.end_with?(">")
+
+          # Default to plain string for everything else
+          :string
+        end
+      end
+    end
+  end
+end