canon 0.1.3 → 0.1.5

data/lib/canon/comparison.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "moxml"
+require "nokogiri"
+require_relative "xml/whitespace_normalizer"
+require_relative "comparison/xml_comparator"
+require_relative "comparison/html_comparator"
+require_relative "comparison/json_comparator"
+require_relative "comparison/yaml_comparator"
+require_relative "diff/diff_node_mapper"
+require_relative "diff/diff_line"
+require_relative "diff/diff_block_builder"
+require_relative "diff/diff_context_builder"
+require_relative "diff/diff_report_builder"
+
+module Canon
+  # Comparison module for XML, HTML, JSON, and YAML documents
+  #
+  # This module provides a unified comparison API for multiple serialization formats.
+  # It auto-detects the format and delegates to specialized comparators while
+  # maintaining a CompareXML-compatible API.
+  #
+  # == Supported Formats
+  #
+  # - **XML**: Uses Moxml for parsing, supports namespaces
+  # - **HTML**: Uses Nokogiri, handles HTML4/HTML5 differences
+  # - **JSON**: Direct Ruby object comparison with deep equality
+  # - **YAML**: Parses to Ruby objects, compares semantically
+  #
+  # == Format Detection
+  #
+  # The module automatically detects format from:
+  # - Object type (Moxml::Node, Nokogiri::HTML::Document, Hash, Array)
+  # - String content (DOCTYPE, opening tags, YAML/JSON syntax)
+  #
+  # == Comparison Options
+  #
+  # Common options across all formats:
+  # - collapse_whitespace: Normalize whitespace in text (default: true)
+  # - ignore_attr_order: Ignore attribute/key ordering (default: true)
+  # - ignore_comments: Skip comment nodes (default: true)
+  # - ignore_text_nodes: Skip all text content (default: false)
+  # - ignore_children: Skip child nodes (default: false)
+  # - verbose: Return detailed diff array (default: false)
+  #
+  # == Usage Examples
+  #
+  #   # XML comparison
+  #   Canon::Comparison.equivalent?(xml1, xml2)
+  #   Canon::Comparison.equivalent?(xml1, xml2, verbose: true)
+  #
+  #   # HTML comparison
+  #   Canon::Comparison.equivalent?(html1, html2, ignore_comments: true)
+  #
+  #   # JSON comparison
+  #   Canon::Comparison.equivalent?(json1, json2)
+  #   Canon::Comparison.equivalent?(hash1, hash2)  # Pre-parsed objects
+  #
+  #   # With detailed output
+  #   diffs = Canon::Comparison.equivalent?(doc1, doc2, verbose: true)
+  #   diffs.each { |diff| puts diff.inspect }
+  #
+  # == Return Values
+  #
+  # - When verbose: false (default) → Boolean (true if equivalent)
+  # - When verbose: true → Array of difference hashes with details
+  #
+  # == Difference Hash Format
+  #
+  # Each difference contains:
+  # - node1, node2: The nodes being compared (XML/HTML)
+  # - diff1, diff2: Comparison result codes
+  # - OR for JSON/YAML:
+  # - path: String path to the difference (e.g., "user.address.city")
+  # - value1, value2: The differing values
+  # - diff_code: Type of difference
+  #
+  module Comparison
+    # Comparison result constants
+    EQUIVALENT = 1
+    MISSING_ATTRIBUTE = 2
+    MISSING_NODE = 3
+    UNEQUAL_ATTRIBUTES = 4
+    UNEQUAL_COMMENTS = 5
+    UNEQUAL_DOCUMENTS = 6
+    UNEQUAL_ELEMENTS = 7
+    UNEQUAL_NODES_TYPES = 8
+    UNEQUAL_TEXT_CONTENTS = 9
+    MISSING_HASH_KEY = 10
+    UNEQUAL_HASH_VALUES = 11
+    UNEQUAL_ARRAY_LENGTHS = 12
+    UNEQUAL_ARRAY_ELEMENTS = 13
+    UNEQUAL_TYPES = 14
+    UNEQUAL_PRIMITIVES = 15
+
+    class << self
+      # Auto-detect format and compare two objects
+      #
+      # @param obj1 [Object] First object to compare
+      # @param obj2 [Object] Second object to compare
+      # @param opts [Hash] Comparison options
+      #   - :format - Format hint (:xml, :html, :html4, :html5, :json, :yaml, :string)
+      # @return [Boolean, Array] true if equivalent, or array of diffs if verbose
+      def equivalent?(obj1, obj2, opts = {})
+        # Use format hint if provided
+        if opts[:format]
+          format1 = format2 = opts[:format]
+          # Parse HTML strings if format is html/html4/html5
+          if %i[html html4 html5].include?(opts[:format])
+            obj1 = parse_html(obj1, opts[:format]) if obj1.is_a?(String)
+            obj2 = parse_html(obj2, opts[:format]) if obj2.is_a?(String)
+            # Normalize html4/html5 to html for comparison
+            format1 = format2 = :html
+          end
+        else
+          format1 = detect_format(obj1)
+          format2 = detect_format(obj2)
+        end
+
+        # Handle string format (plain text comparison)
+        if format1 == :string
+          if opts[:verbose]
+            return obj1.to_s == obj2.to_s ? [] : [:different]
+          else
+            return obj1.to_s == obj2.to_s
+          end
+        end
+
+        # Allow comparing json/yaml strings with ruby objects
+        # since they parse to the same structure
+        formats_compatible = format1 == format2 ||
+          (%i[json ruby_object].include?(format1) &&
+           %i[json ruby_object].include?(format2)) ||
+          (%i[yaml ruby_object].include?(format1) &&
+           %i[yaml ruby_object].include?(format2))
+
+        unless formats_compatible
+          raise Canon::CompareFormatMismatchError.new(format1, format2)
+        end
+
+        # Normalize format for comparison
+        comparison_format = case format1
+                            when :ruby_object
+                              # If comparing ruby_object with json/yaml, use that format
+                              %i[json yaml].include?(format2) ? format2 : :json
+                            else
+                              format1
+                            end
+
+        case comparison_format
+        when :xml
+          XmlComparator.equivalent?(obj1, obj2, opts)
+        when :html
+          HtmlComparator.equivalent?(obj1, obj2, opts)
+        when :json
+          JsonComparator.equivalent?(obj1, obj2, opts)
+        when :yaml
+          YamlComparator.equivalent?(obj1, obj2, opts)
+        end
+      end
+
+      private
+
+      # Parse HTML string into Nokogiri document
+      #
+      # @param content [String, Object] Content to parse (returns as-is if not a string)
+      # @param format [Symbol] HTML format (:html, :html4, :html5)
+      # @return [Nokogiri::HTML::Document, Nokogiri::HTML5::Document, Nokogiri::HTML::DocumentFragment, Object]
+      def parse_html(content, _format)
+        return content unless content.is_a?(String)
+        return content if content.is_a?(Nokogiri::HTML::Document) ||
+          content.is_a?(Nokogiri::HTML5::Document) ||
+          content.is_a?(Nokogiri::XML::Document) ||
+          content.is_a?(Nokogiri::HTML::DocumentFragment) ||
+          content.is_a?(Nokogiri::HTML5::DocumentFragment) ||
+          content.is_a?(Nokogiri::XML::DocumentFragment)
+
+        # Let HtmlComparator's parse_node handle parsing with preprocessing
+        # For now, just return the string and let it be parsed by HtmlComparator
+        content
+      rescue StandardError
+        content
+      end
+
+      # Detect the format of an object
+      #
+      # @param obj [Object] Object to detect format of
+      # @return [Symbol] Format type
+      def detect_format(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_format(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
+      #
+      # @param str [String] String to detect format of
+      # @return [Symbol] Format type
+      def detect_string_format(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

data/lib/canon/config.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Canon
+  # Global configuration for Canon
+  # Provides unified configuration across CLI, Ruby API, and RSpec interfaces
+  class Config
+    class << self
+      def instance
+        @instance ||= new
+      end
+
+      def configure
+        yield instance if block_given?
+        instance
+      end
+
+      def reset!
+        @instance = new
+      end
+
+      # Delegate to instance
+      def method_missing(method, ...)
+        if @instance.respond_to?(method)
+          @instance.send(method, ...)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @instance.respond_to?(method) || super
+      end
+    end
+
+    attr_reader :xml, :html, :json, :yaml, :string
+
+    def initialize
+      @xml = FormatConfig.new(:xml)
+      @html = FormatConfig.new(:html)
+      @json = FormatConfig.new(:json)
+      @yaml = FormatConfig.new(:yaml)
+      @string = FormatConfig.new(:string)
+    end
+
+    def reset!
+      @xml.reset!
+      @html.reset!
+      @json.reset!
+      @yaml.reset!
+      @string.reset!
+    end
+
+    # Backward compatibility methods for top-level diff configuration
+    # These delegate to XML diff config for backward compatibility
+    def diff_mode
+      @xml.diff.mode
+    end
+
+    def diff_mode=(value)
+      @xml.diff.mode = value
+    end
+
+    def use_color
+      @xml.diff.use_color
+    end
+
+    def use_color=(value)
+      @xml.diff.use_color = value
+    end
+
+    # Backward compatibility methods for match profile configuration
+    def xml_match_profile
+      @xml.match.profile
+    end
+
+    def xml_match_profile=(value)
+      @xml.match.profile = value
+    end
+
+    def html_match_profile
+      @html.match.profile
+    end
+
+    def html_match_profile=(value)
+      @html.match.profile = value
+    end
+
+    # Format-specific configuration
+    # Each format (XML, HTML, JSON, YAML) has its own instance
+    class FormatConfig
+      attr_reader :format, :match, :diff
+      attr_accessor :preprocessing
+
+      def initialize(format)
+        @format = format
+        @match = MatchConfig.new
+        @diff = DiffConfig.new
+        @preprocessing = nil
+      end
+
+      def reset!
+        @match.reset!
+        @diff.reset!
+        @preprocessing = nil
+      end
+    end
+
+    # Match configuration for comparison behavior
+    class MatchConfig
+      attr_accessor :profile
+      attr_reader :options
+
+      def initialize
+        @profile = nil
+        @options = {}
+      end
+
+      def options=(value)
+        @options = value || {}
+      end
+
+      def reset!
+        @profile = nil
+        @options = {}
+      end
+
+      # Build match options from profile and options
+      def to_h
+        result = {}
+        result[:match_profile] = @profile if @profile
+        result[:match] = @options if @options && !@options.empty?
+        result
+      end
+    end
+
+    # Diff configuration for output formatting
+    class DiffConfig
+      attr_accessor :mode, :use_color, :context_lines, :grouping_lines,
+                    :show_diffs, :verbose_diff
+
+      def initialize
+        @mode = :by_line
+        @use_color = true
+        @context_lines = 3
+        @grouping_lines = 10
+        @show_diffs = :all
+        @verbose_diff = false
+      end
+
+      def reset!
+        @mode = :by_line
+        @use_color = true
+        @context_lines = 3
+        @grouping_lines = 10
+        @show_diffs = :all
+        @verbose_diff = false
+      end
+
+      # Build diff options
+      def to_h
+        {
+          diff: @mode,
+          use_color: @use_color,
+          context_lines: @context_lines,
+          grouping_lines: @grouping_lines,
+          show_diffs: @show_diffs,
+          verbose_diff: @verbose_diff,
+        }
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_block.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Represents a contiguous block of changes in a diff
+    # A diff block is a run of consecutive change lines (-, +, !)
+    class DiffBlock
+      attr_reader :start_idx, :end_idx, :types, :diff_lines, :diff_node
+      attr_accessor :normative
+
+      def initialize(start_idx:, end_idx:, types: [], diff_lines: [],
+diff_node: nil)
+        @start_idx = start_idx
+        @end_idx = end_idx
+        @types = types
+        @diff_lines = diff_lines
+        @diff_node = diff_node
+        @normative = nil
+      end
+
+      # Number of lines in this block
+      def size
+        end_idx - start_idx + 1
+      end
+
+      # @return [Boolean] true if this block represents a normative difference
+      def normative?
+        return @normative unless @normative.nil?
+
+        # If we have a diff_node, use its normative status
+        return diff_node.normative? if diff_node
+
+        # If we have diff_lines, check if any are normative
+        return diff_lines.any?(&:normative?) if diff_lines&.any?
+
+        # Default to true (treat as normative if we can't determine)
+        true
+      end
+
+      # @return [Boolean] true if this block represents an informative-only difference
+      def informative?
+        !normative?
+      end
+
+      # Check if this block contains a specific type of change
+      def includes_type?(type)
+        types.include?(type)
+      end
+
+      def to_h
+        {
+          start_idx: start_idx,
+          end_idx: end_idx,
+          types: types,
+          diff_lines: diff_lines.map(&:to_h),
+          diff_node: diff_node&.to_h,
+          normative: normative?,
+        }
+      end
+
+      def ==(other)
+        other.is_a?(DiffBlock) &&
+          start_idx == other.start_idx &&
+          end_idx == other.end_idx &&
+          types == other.types &&
+          diff_lines == other.diff_lines &&
+          diff_node == other.diff_node
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_block_builder.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "diff_block"
+
+module Canon
+  module Diff
+    # Builds DiffBlocks from DiffLines
+    # Handles grouping of contiguous changed lines and filtering by normative/informative
+    class DiffBlockBuilder
+      # Build diff blocks from diff lines
+      #
+      # @param diff_lines [Array<DiffLine>] The diff lines to process
+      # @param show_diffs [Symbol] Filter setting (:normative, :informative, :all)
+      # @return [Array<DiffBlock>] Filtered diff blocks
+      def self.build_blocks(diff_lines, show_diffs: :all)
+        new(diff_lines, show_diffs).build
+      end
+
+      def initialize(diff_lines, show_diffs)
+        @diff_lines = diff_lines
+        @show_diffs = show_diffs
+      end
+
+      def build
+        # Group contiguous changed lines into blocks
+        blocks = group_into_blocks
+
+        # Filter blocks based on show_diffs setting
+        filter_blocks(blocks)
+      end
+
+      private
+
+      # Group contiguous changed lines into DiffBlock objects
+      def group_into_blocks
+        blocks = []
+        current_block_lines = []
+        current_start_idx = nil
+
+        @diff_lines.each_with_index do |line, idx|
+          if line.unchanged?
+            # End current block if any
+            if !current_block_lines.empty?
+              blocks << create_block(current_start_idx, idx - 1,
+                                     current_block_lines)
+              current_block_lines = []
+              current_start_idx = nil
+            end
+          else
+            # Start or continue block
+            current_start_idx = idx if current_start_idx.nil?
+            current_block_lines << line
+          end
+        end
+
+        # Don't forget last block
+        unless current_block_lines.empty?
+          blocks << create_block(current_start_idx,
+                                 @diff_lines.length - 1,
+                                 current_block_lines)
+        end
+
+        blocks
+      end
+
+      # Create a DiffBlock from lines
+      def create_block(start_idx, end_idx, diff_lines)
+        # Determine types from diff_lines
+        types = diff_lines.map(&:type).uniq.map do |t|
+          case t
+          when :added then "+"
+          when :removed then "-"
+          when :changed then "!"
+          end
+        end.compact
+
+        # Create block
+        block = DiffBlock.new(
+          start_idx: start_idx,
+          end_idx: end_idx,
+          types: types,
+          diff_lines: diff_lines,
+        )
+
+        # Determine if block is normative
+        # A block is normative if ANY of its lines are normative
+        block.normative = diff_lines.any?(&:normative?)
+
+        block
+      end
+
+      # Filter blocks based on show_diffs setting
+      def filter_blocks(blocks)
+        case @show_diffs
+        when :normative
+          blocks.select(&:normative?)
+        when :informative
+          blocks.select(&:informative?)
+        else # :all
+          blocks
+        end
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_classifier.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Classifies DiffNodes as normative (affects equivalence) or informative (doesn't affect equivalence)
+    # based on the match options in effect
+    class DiffClassifier
+      attr_reader :match_options
+
+      # @param match_options [Canon::Comparison::ResolvedMatchOptions] The match options
+      def initialize(match_options)
+        @match_options = match_options
+      end
+
+      # Classify a single DiffNode as normative or informative
+      # @param diff_node [DiffNode] The diff node to classify
+      # @return [DiffNode] The same diff node with normative attribute set
+      def classify(diff_node)
+        diff_node.normative = normative_for_dimension?(diff_node.dimension)
+        diff_node
+      end
+
+      # Classify multiple DiffNodes
+      # @param diff_nodes [Array<DiffNode>] The diff nodes to classify
+      # @return [Array<DiffNode>] The same diff nodes with normative attributes set
+      def classify_all(diff_nodes)
+        diff_nodes.each { |node| classify(node) }
+      end
+
+      private
+
+      # Determine if a difference in a given dimension is normative
+      # @param dimension [Symbol] The match dimension
+      # @return [Boolean] true if differences in this dimension are normative
+      def normative_for_dimension?(dimension)
+        behavior = match_options.behavior_for(dimension)
+
+        # :ignore → informative (difference doesn't matter)
+        # :strict or :normalize → normative (difference persisted through matching)
+        # Note: If a DiffNode exists, it means the comparison FAILED even after
+        # applying normalization, so it's a real (normative) difference
+        behavior != :ignore
+      end
+    end
+  end
+end