canon 0.1.7 → 0.1.8

data/lib/canon/comparison.rb

@@ -7,11 +7,15 @@ require_relative "comparison/xml_comparator"
 require_relative "comparison/html_comparator"
 require_relative "comparison/json_comparator"
 require_relative "comparison/yaml_comparator"
+require_relative "comparison/profile_definition"
+require_relative "comparison/format_detector"
+require_relative "comparison/html_parser"
 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"
+require_relative "cache"
 
 module Canon
   # Comparison module for XML, HTML, JSON, and YAML documents
@@ -36,25 +40,36 @@ module Canon
   # == 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)
+  # - profile: Comparison profile (Symbol for preset, Hash for custom)
+  #   * Presets: :strict, :rendered, :html4, :html5, :spec_friendly, :content_only
+  #   * Custom: { text_content: :normalize, comments: :ignore, ... }
+  # - diff_algorithm: Algorithm to use (:dom or :semantic, default: :dom)
   # - verbose: Return detailed diff array (default: false)
   #
   # == Usage Examples
   #
-  #   # XML comparison
+  #   # XML comparison with default profile
   #   Canon::Comparison.equivalent?(xml1, xml2)
-  #   Canon::Comparison.equivalent?(xml1, xml2, verbose: true)
   #
-  #   # HTML comparison
-  #   Canon::Comparison.equivalent?(html1, html2, ignore_comments: true)
+  #   # XML comparison with preset profile
+  #   Canon::Comparison.equivalent?(xml1, xml2, profile: :strict)
+  #   Canon::Comparison.equivalent?(xml1, xml2, profile: :spec_friendly)
   #
-  #   # JSON comparison
-  #   Canon::Comparison.equivalent?(json1, json2)
-  #   Canon::Comparison.equivalent?(hash1, hash2)  # Pre-parsed objects
+  #   # HTML comparison with custom inline profile
+  #   Canon::Comparison.equivalent?(html1, html2,
+  #     profile: { text_content: :normalize, comments: :ignore })
+  #
+  #   # Define and use a custom profile
+  #   Canon::Comparison.define_profile(:my_custom) do
+  #     text_content :normalize
+  #     comments :ignore
+  #     preprocessing :rendered
+  #   end
+  #   Canon::Comparison.equivalent?(doc1, doc2, profile: :my_custom)
+  #
+  #   # JSON comparison with semantic tree diff
+  #   Canon::Comparison.equivalent?(json1, json2,
+  #     diff_algorithm: :semantic, profile: :spec_friendly)
   #
   #   # With detailed output
   #   diffs = Canon::Comparison.equivalent?(doc1, doc2, verbose: true)
@@ -88,10 +103,11 @@ module Canon
     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
+    UNEQUAL_HASH_KEY_ORDER = 12
+    UNEQUAL_ARRAY_LENGTHS = 13
+    UNEQUAL_ARRAY_ELEMENTS = 14
+    UNEQUAL_TYPES = 15
+    UNEQUAL_PRIMITIVES = 16
 
     class << self
       # Auto-detect format and compare two objects
@@ -99,8 +115,10 @@ module Canon
       # @param obj1 [Object] First object to compare
       # @param obj2 [Object] Second object to compare
       # @param opts [Hash] Comparison options
+      #   - :profile - Profile to use (Symbol for preset, Hash for custom)
       #   - :format - Format hint (:xml, :html, :html4, :html5, :json, :yaml, :string)
       #   - :diff_algorithm - Algorithm to use (:dom or :semantic)
+      #   - :verbose - Return detailed diff array (default: false)
       # @return [Boolean, Array] true if equivalent, or array of diffs if verbose
       def equivalent?(obj1, obj2, opts = {})
         # Check if semantic tree diff is requested
@@ -113,6 +131,56 @@ module Canon
         dom_diff(obj1, obj2, opts)
       end
 
+      # Define a custom comparison profile with DSL syntax
+      #
+      # @param name [Symbol] Profile name
+      # @yield [ProfileDefinition] DSL block for defining profile
+      # @return [Symbol] Profile name
+      # @raise [ProfileError] if profile definition is invalid
+      #
+      # @example Define a custom profile
+      #   Canon::Comparison.define_profile(:my_custom) do
+      #     text_content :normalize
+      #     comments :ignore
+      #     preprocessing :rendered
+      #   end
+      def define_profile(name, &block)
+        definition = ProfileDefinition.define(name, &block)
+
+        @custom_profiles ||= {}
+        @custom_profiles[name] = definition
+
+        name
+      end
+
+      # Load a profile (custom or preset)
+      #
+      # @param name [Symbol] Profile name
+      # @return [Hash] Profile settings
+      def load_profile(name)
+        # Check custom profiles first
+        if @custom_profiles&.key?(name)
+          return @custom_profiles[name].dup
+        end
+
+        # Fall back to presets - try Xml first (most common)
+        begin
+          MatchOptions::Xml.get_profile_options(name)
+        rescue Error
+          # Try other formats
+          MatchOptions::Json.get_profile_options(name)
+        end
+      end
+
+      # List all available profiles (custom + presets)
+      #
+      # @return [Array<Symbol>] Available profile names
+      def available_profiles
+        custom = @custom_profiles&.keys || []
+        presets = MatchOptions::Xml::MATCH_PROFILES.keys
+        (custom + presets).sort.uniq
+      end
+
       private
 
       # Perform semantic tree diff comparison
@@ -120,8 +188,8 @@ module Canon
         require_relative "tree_diff"
 
         # Detect format for both objects
-        format1 = opts[:format] || detect_format(obj1)
-        format2 = opts[:format] || detect_format(obj2)
+        format1 = opts[:format] || FormatDetector.detect(obj1)
+        format2 = opts[:format] || FormatDetector.detect(obj2)
 
         # Handle string format (plain text comparison) - semantic tree doesn't support it
         if format1 == :string
@@ -203,39 +271,141 @@ module Canon
       # @param opts [Hash] User options
       # @return [Hash] Resolved match options
       def resolve_match_options(format, opts)
+        # Process unified profile parameter first
+        processed_opts = process_profile_parameter(opts)
+
         case format
         when :xml, :html, :html4, :html5
           MatchOptions::Xml.resolve(
             format: format,
-            match_profile: opts[:match_profile],
-            match: opts[:match],
-            preprocessing: opts[:preprocessing],
-            global_profile: opts[:global_profile],
-            global_options: opts[:global_options],
+            match_profile: processed_opts[:match_profile],
+            match: processed_opts[:match],
+            preprocessing: processed_opts[:preprocessing],
+            global_profile: processed_opts[:global_profile],
+            global_options: processed_opts[:global_options],
           )
         when :json
           MatchOptions::Json.resolve(
             format: format,
-            match_profile: opts[:match_profile],
-            match: opts[:match],
-            preprocessing: opts[:preprocessing],
-            global_profile: opts[:global_profile],
-            global_options: opts[:global_options],
+            match_profile: processed_opts[:match_profile],
+            match: processed_opts[:match],
+            preprocessing: processed_opts[:preprocessing],
+            global_profile: processed_opts[:global_profile],
+            global_options: processed_opts[:global_options],
           )
         when :yaml
           MatchOptions::Yaml.resolve(
             format: format,
-            match_profile: opts[:match_profile],
-            match: opts[:match],
-            preprocessing: opts[:preprocessing],
-            global_profile: opts[:global_profile],
-            global_options: opts[:global_options],
+            match_profile: processed_opts[:match_profile],
+            match: processed_opts[:match],
+            preprocessing: processed_opts[:preprocessing],
+            global_profile: processed_opts[:global_profile],
+            global_options: processed_opts[:global_options],
           )
         else
-          opts[:match] || {}
+          processed_opts[:match] || {}
+        end
+      end
+
+      # Process unified profile parameter
+      #
+      # Converts the new :profile parameter into the legacy format expected
+      # by MatchOptions resolvers. Handles:
+      # - Symbol → preset profile (uses :match_profile)
+      # - Hash → custom profile (validates and uses :match)
+      #
+      # @param opts [Hash] Original user options
+      # @return [Hash] Processed options with legacy format
+      def process_profile_parameter(opts)
+        processed = opts.dup
+
+        # Handle unified :profile parameter
+        if opts.key?(:profile)
+          profile = opts[:profile]
+
+          case profile
+          when Symbol
+            # Preset profile name
+            processed[:match_profile] = profile
+          when Hash
+            # Inline custom profile - validate and use as :match
+            validate_custom_profile!(profile, format_from_opts(opts))
+            processed[:match] = profile
+          else
+            raise Canon::Error,
+                  "Invalid profile type: #{profile.class}. " \
+                  "Expected Symbol (preset name) or Hash (custom profile)."
+          end
+        end
+
+        processed
+      end
+
+      # Validate custom profile hash
+      #
+      # Ensures all dimensions and behaviors in a custom profile are valid.
+      # Uses ProfileDefinition validation logic.
+      #
+      # @param profile [Hash] Custom profile hash
+      # @param format [Symbol] Format type for validation context
+      # @raise [Canon::Error] if profile contains invalid dimensions or behaviors
+      def validate_custom_profile!(profile, format)
+        profile.each do |dimension, behavior|
+          # Skip preprocessing and special options
+          next if dimension == :preprocessing
+          next if dimension == :semantic_diff
+          next if dimension == :similarity_threshold
+
+          # Validate dimension is known
+          valid_dimensions = valid_dimensions_for_format(format)
+          unless valid_dimensions.include?(dimension)
+            raise Canon::Error,
+                  "Unknown dimension: #{dimension}. " \
+                  "Valid dimensions for #{format}: #{valid_dimensions.join(', ')}"
+          end
+
+          # Validate behavior is allowed for this dimension
+          valid_behaviors = ProfileDefinition::DIMENSION_BEHAVIORS[dimension]
+          if valid_behaviors && !valid_behaviors.include?(behavior)
+            raise Canon::Error,
+                  "Invalid behavior '#{behavior}' for dimension '#{dimension}'. " \
+                  "Valid behaviors: #{valid_behaviors.join(', ')}"
+          end
+
+          # Validate behavior is in general MATCH_BEHAVIORS
+          unless MatchOptions::MATCH_BEHAVIORS.include?(behavior)
+            raise Canon::Error,
+                  "Unknown match behavior: #{behavior}. " \
+                  "Valid behaviors: #{MatchOptions::MATCH_BEHAVIORS.join(', ')}"
+          end
         end
       end
 
+      # Get valid dimensions for a format
+      #
+      # @param format [Symbol] Format type
+      # @return [Array<Symbol>] Valid dimensions for the format
+      def valid_dimensions_for_format(format)
+        case format
+        when :xml, :html, :html4, :html5
+          MatchOptions::Xml::MATCH_DIMENSIONS
+        when :json
+          MatchOptions::Json::MATCH_DIMENSIONS
+        when :yaml
+          MatchOptions::Yaml::MATCH_DIMENSIONS
+        else
+          []
+        end
+      end
+
+      # Helper to extract format from opts for validation
+      #
+      # @param opts [Hash] User options
+      # @return [Symbol] Format type or :xml as default
+      def format_from_opts(opts)
+        opts[:format] || :xml
+      end
+
       # Parse documents using comparator's parse logic (reuses preprocessing)
       #
       # @param obj1 [Object] First object
@@ -250,32 +420,66 @@ module Canon
         when :xml
           # Delegate to XmlComparator's parse_node - returns Canon::Xml::Node
           # Adapter now handles Canon::Xml::Node directly
-          doc1 = XmlComparator.send(:parse_node, obj1, preprocessing)
-          doc2 = XmlComparator.send(:parse_node, obj2, preprocessing)
+          doc1 = parse_with_cache(obj1, format, preprocessing) do |doc|
+            XmlComparator.send(:parse_node, doc, preprocessing)
+          end
+          doc2 = parse_with_cache(obj2, format, preprocessing) do |doc|
+            XmlComparator.send(:parse_node, doc, preprocessing)
+          end
           [doc1, doc2]
         when :html, :html4, :html5
           # Delegate to HtmlComparator's parse_node_for_semantic for Canon::Xml::Node
           [
-            HtmlComparator.send(:parse_node_for_semantic, obj1, preprocessing),
-            HtmlComparator.send(:parse_node_for_semantic, obj2, preprocessing),
+            parse_with_cache(obj1, format, preprocessing) do |doc|
+              HtmlComparator.send(:parse_node_for_semantic, doc, preprocessing)
+            end,
+            parse_with_cache(obj2, format, preprocessing) do |doc|
+              HtmlComparator.send(:parse_node_for_semantic, doc, preprocessing)
+            end,
           ]
         when :json
           # Delegate to JsonComparator's parse_json
           [
-            JsonComparator.send(:parse_json, obj1),
-            JsonComparator.send(:parse_json, obj2),
+            parse_with_cache(obj1, format, :none) do |doc|
+              JsonComparator.send(:parse_json, doc)
+            end,
+            parse_with_cache(obj2, format, :none) do |doc|
+              JsonComparator.send(:parse_json, doc)
+            end,
           ]
         when :yaml
           # Delegate to YamlComparator's parse_yaml
           [
-            YamlComparator.send(:parse_yaml, obj1),
-            YamlComparator.send(:parse_yaml, obj2),
+            parse_with_cache(obj1, format, :none) do |doc|
+              YamlComparator.send(:parse_yaml, doc)
+            end,
+            parse_with_cache(obj2, format, :none) do |doc|
+              YamlComparator.send(:parse_yaml, doc)
+            end,
           ]
         else
           [obj1, obj2]
         end
       end
 
+      # Parse a document with caching
+      #
+      # @param doc [Object] Document to parse (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)
+        # If already a parsed node, return as-is
+        return doc unless doc.is_a?(String)
+
+        # Use cache for string documents
+        Cache.fetch(:document_parse,
+                    Cache.key_for_document(doc, format, preprocessing)) do
+          yield doc
+        end
+      end
+
       # Normalize format for TreeDiff (html4/html5 -> html)
       #
       # @param format [Symbol] Original format
@@ -314,14 +518,14 @@ module Canon
           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
+            obj1 = HtmlParser.parse(obj1, opts[:format]) if obj1.is_a?(String)
+            obj2 = HtmlParser.parse(obj2, opts[:format]) if obj2.is_a?(String)
+            # Note: We preserve html4/html5 format instead of normalizing to :html
+            # This allows HtmlComparator to use the correct parsing behavior
           end
         else
-          format1 = detect_format(obj1)
-          format2 = detect_format(obj2)
+          format1 = FormatDetector.detect(obj1)
+          format2 = FormatDetector.detect(obj2)
         end
 
         # Handle string format (plain text comparison)
@@ -357,7 +561,7 @@ module Canon
         case comparison_format
         when :xml
           XmlComparator.equivalent?(obj1, obj2, opts)
-        when :html
+        when :html, :html4, :html5
           HtmlComparator.equivalent?(obj1, obj2, opts)
         when :json
           JsonComparator.equivalent?(obj1, obj2, opts)
@@ -366,78 +570,29 @@ module Canon
         end
       end
 
-      # 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
+      # Detect the format of an object (delegates to FormatDetector)
       #
       # @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
+        FormatDetector.detect(obj)
       end
 
-      # Detect the format of a string
+      # Detect the format of a string (delegates to FormatDetector)
       #
       # @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?(">")
+        FormatDetector.detect_string(str)
+      end
 
-        # Default to plain string for everything else
-        :string
+      # Parse HTML string into Nokogiri document (delegates to HtmlParser)
+      #
+      # @param content [String, Object] Content to parse
+      # @param format [Symbol] HTML format (:html, :html4, :html5)
+      # @return [Object] Parsed document
+      def parse_html(content, format)
+        HtmlParser.parse(content, format)
       end
     end
   end

data/lib/canon/diff/diff_node.rb

@@ -5,9 +5,19 @@ module Canon
     # Represents a semantic difference between two nodes in a comparison tree
     # This is created during the Comparison Layer and carries information about
     # which dimension caused the difference and whether it's normative or informative
+    #
+    # DiffNode is library-agnostic - it works with data extracted from nodes,
+    # not the raw node references themselves. This allows Canon to work with
+    # any parsing library (Nokogiri, Moxml, etc.) without being tied to it.
     class DiffNode
       attr_reader :node1, :node2
-      attr_accessor :dimension, :reason, :normative, :formatting
+      attr_accessor :dimension, :reason, :normative, :formatting,
+                    # Enriched metadata for Stage 4 rendering
+                    :path, # Canonical path with ordinal indices
+                    :serialized_before,  # Serialized content for display (before)
+                    :serialized_after,   # Serialized content for display (after)
+                    :attributes_before,  # Normalized attributes hash (before)
+                    :attributes_after    # Normalized attributes hash (after)
 
       # @param node1 [Object] The first node being compared
       # @param node2 [Object] The second node being compared
@@ -15,13 +25,26 @@ module Canon
       #   (e.g., :text_content, :attribute_whitespace, :structural_whitespace,
       #   :comments, :key_order)
       # @param reason [String] Human-readable explanation of the difference
-      def initialize(node1:, node2:, dimension:, reason:)
+      # @param path [String, nil] Optional canonical path with ordinal indices
+      # @param serialized_before [String, nil] Optional serialized content for display
+      # @param serialized_after [String, nil] Optional serialized content for display
+      # @param attributes_before [Hash, nil] Optional normalized attributes hash
+      # @param attributes_after [Hash, nil] Optional normalized attributes hash
+      def initialize(node1:, node2:, dimension:, reason:,
+                     path: nil, serialized_before: nil, serialized_after: nil,
+                     attributes_before: nil, attributes_after: nil)
         @node1 = node1
         @node2 = node2
         @dimension = dimension
         @reason = reason
         @normative = nil # Will be set by DiffClassifier
         @formatting = nil # Will be set by DiffClassifier
+        # Enriched metadata (optional, populated by PathBuilder and NodeSerializer)
+        @path = path
+        @serialized_before = serialized_before
+        @serialized_after = serialized_after
+        @attributes_before = attributes_before
+        @attributes_after = attributes_after
       end
 
       # @return [Boolean] true if this diff is normative (affects equivalence)
@@ -54,6 +77,11 @@ module Canon
           reason: reason,
           normative: normative,
           formatting: formatting,
+          path: path,
+          serialized_before: serialized_before,
+          serialized_after: serialized_after,
+          attributes_before: attributes_before,
+          attributes_after: attributes_after,
         }
       end
 
@@ -65,6 +93,8 @@ module Canon
           reason == other.reason &&
           normative == other.normative &&
           formatting == other.formatting
+        # Note: path and serialized content are not part of equality
+        # since they're derived from nodes, not independent properties
       end
     end
   end