canon 0.1.3 → 0.1.5

data/lib/canon/comparison/html_comparator.rb

@@ -0,0 +1,410 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require_relative "xml_comparator"
+require_relative "match_options"
+require_relative "comparison_result"
+require_relative "../diff/diff_node"
+require_relative "../diff/diff_classifier"
+
+module Canon
+  module Comparison
+    # HTML comparison class
+    # Handles comparison of HTML nodes with various options
+    class HtmlComparator
+      # Default comparison options for HTML
+      DEFAULT_OPTS = {
+        # Structural filtering options
+        ignore_children: false,
+        ignore_text_nodes: false,
+        ignore_attr_content: [],
+        ignore_attrs: [],
+        ignore_attrs_by_name: [],
+        ignore_nodes: [],
+
+        # Output options
+        verbose: false,
+        diff_children: false,
+
+        # Match system options
+        match_profile: nil,
+        match: nil,
+        preprocessing: nil,
+        global_profile: nil,
+        global_options: nil,
+
+        # Diff display options
+        diff: nil,
+      }.freeze
+
+      class << self
+        # Compare two HTML nodes for equivalence
+        #
+        # @param html1 [String, Nokogiri::HTML::Document] First HTML
+        # @param html2 [String, Nokogiri::HTML::Document] Second HTML
+        # @param opts [Hash] Comparison options
+        # @param child_opts [Hash] Options for child comparison
+        # @return [Boolean, Array] true if equivalent, or array of diffs if
+        #   verbose
+        def equivalent?(html1, html2, opts = {}, child_opts = {})
+          opts = DEFAULT_OPTS.merge(opts)
+
+          # Resolve match options with format-specific defaults
+          match_opts_hash = MatchOptions::Xml.resolve(
+            format: :html,
+            match_profile: opts[:match_profile],
+            match: opts[:match],
+            preprocessing: opts[:preprocessing],
+            global_profile: opts[:global_profile],
+            global_options: opts[:global_options],
+          )
+
+          # Wrap in ResolvedMatchOptions for DiffClassifier
+          match_opts = Canon::Comparison::ResolvedMatchOptions.new(
+            match_opts_hash,
+            format: :html,
+          )
+
+          # Store resolved match options hash for use in comparison logic
+          opts[:match_opts] = match_opts_hash
+
+          # Create child_opts with resolved options
+          child_opts = opts.merge(child_opts)
+
+          # Parse nodes if they are strings, applying preprocessing if needed
+          node1 = parse_node(html1, match_opts_hash[:preprocessing],
+                             match_opts_hash)
+          node2 = parse_node(html2, match_opts_hash[:preprocessing],
+                             match_opts_hash)
+
+          # Serialize preprocessed nodes for diff display (avoid re-preprocessing)
+          preprocessed_str1 = serialize_for_display(node1)
+          preprocessed_str2 = serialize_for_display(node2)
+
+          differences = []
+          diff_children = opts[:diff_children] || false
+
+          # DocumentFragment nodes need special handling - compare their children
+          # instead of the fragment nodes themselves
+          if node1.is_a?(Nokogiri::HTML4::DocumentFragment) &&
+              node2.is_a?(Nokogiri::HTML4::DocumentFragment)
+            # Compare children of fragments
+            children1 = node1.children.to_a
+            children2 = node2.children.to_a
+
+            if children1.length != children2.length
+              result = Comparison::UNEQUAL_ELEMENTS
+            elsif children1.empty?
+              result = Comparison::EQUIVALENT
+            else
+              # Compare each pair of children
+              result = Comparison::EQUIVALENT
+              children1.zip(children2).each do |child1, child2|
+                child_result = XmlComparator.send(:compare_nodes, child1, child2,
+                                                  opts, child_opts, diff_children,
+                                                  differences)
+                if child_result != Comparison::EQUIVALENT
+                  result = child_result
+                  break
+                end
+              end
+            end
+          else
+            result = XmlComparator.send(:compare_nodes, node1, node2, opts,
+                                        child_opts, diff_children, differences)
+          end
+
+          # Classify DiffNodes as normative/informative if we have verbose output
+          if opts[:verbose] && !differences.empty?
+            classifier = Canon::Diff::DiffClassifier.new(match_opts)
+            classifier.classify_all(differences.select do |d|
+              d.is_a?(Canon::Diff::DiffNode)
+            end)
+          end
+
+          if opts[:verbose]
+            ComparisonResult.new(
+              differences: differences,
+              preprocessed_strings: [preprocessed_str1, preprocessed_str2],
+              format: :html,
+              html_version: detect_html_version_from_node(node1),
+              match_options: match_opts_hash,
+            )
+          else
+            result == Comparison::EQUIVALENT
+          end
+        end
+
+        private
+
+        # Parse a node from string or return as-is
+        # Applies preprocessing transformation before parsing if specified
+        def parse_node(node, preprocessing = :none, match_opts = {})
+          # If already a Nokogiri node, check for incompatible XML documents
+          # Only raise error for non-string incompatible formats
+          unless node.is_a?(String)
+            # Detect if this is an XML document (not HTML)
+            # Strings are allowed since they can be wrapped/parsed as needed
+            if is_xml_document?(node)
+              raise Canon::CompareFormatMismatchError.new(:xml, :html)
+            end
+
+            # For :rendered preprocessing, apply normalization even to pre-parsed nodes
+            if preprocessing == :rendered
+              # If already a DocumentFragment with :rendered, just normalize it
+              if node.is_a?(Nokogiri::HTML4::DocumentFragment) ||
+                  node.is_a?(Nokogiri::HTML5::DocumentFragment) ||
+                  node.is_a?(Nokogiri::XML::DocumentFragment)
+                # Normalize whitespace directly without re-parsing
+                normalize_html_style_script_comments(node)
+                normalize_rendered_whitespace(node, match_opts)
+                return node
+              end
+
+              # Normalize whitespace directly without re-parsing
+              normalize_html_style_script_comments(node)
+              normalize_rendered_whitespace(node, match_opts)
+              return node
+            end
+
+            # For other preprocessing, just return the node (including DocumentFragments)
+            return node
+          end
+
+          # Check if string contains XML declaration but is actually HTML
+          # Nokogiri::HTML4.to_s adds <?xml...?> but the content is still HTML
+          # Check if this is actually HTML content after the declaration
+          # Look for <html tag which indicates HTML
+          if node.strip.start_with?("<?xml") && !node.match?(/<html[\s>]/i)
+            # No <html> tag, this is likely pure XML
+            raise Canon::CompareFormatMismatchError.new(:xml, :html)
+          end
+
+          # Has <?xml but also <html> tag, so it's HTML with XML declaration
+          # (common output from Nokogiri::HTML4#to_s)
+
+          # For :rendered preprocessing, handle separately to avoid double-parsing
+          if preprocessing == :rendered
+            # Check if this is a full HTML document or a fragment
+            # Use full document parsing if it has <html> tag
+            if node.match?(/<html[\s>]/i)
+              doc = Nokogiri::HTML(node, &:noblanks)
+              normalize_html_style_script_comments(doc)
+              normalize_rendered_whitespace(doc, match_opts)
+              remove_whitespace_only_text_nodes(doc)
+              return doc
+            else
+              # Use fragment for partial HTML
+              frag = Nokogiri::HTML4.fragment(node)
+              normalize_html_style_script_comments(frag)
+              normalize_rendered_whitespace(frag, match_opts)
+              remove_whitespace_only_text_nodes(frag)
+              return frag
+            end
+          end
+
+          # Apply preprocessing to HTML string before parsing
+          html_string = case preprocessing
+                        when :normalize
+                          # Normalize whitespace: collapse runs, trim lines
+                          node.lines.map(&:strip).reject(&:empty?).join("\n")
+                        when :c14n
+                          # Canonicalize the HTML (use XML canonicalization)
+                          Canon::Xml::C14n.canonicalize(node,
+                                                        with_comments: false)
+                        when :format
+                          # Pretty format the HTML
+                          Canon.format(node, :html)
+                        else
+                          # :none or unrecognized - use as-is
+                          node
+                        end
+
+          # Use Nokogiri for HTML and normalize style/script comments
+          # Use noblanks to prevent Nokogiri from adding structural whitespace
+          doc = Nokogiri::HTML(html_string, &:noblanks)
+          normalize_html_style_script_comments(doc)
+          doc
+        end
+
+        # Detect HTML version from content
+        #
+        # @param content [String] HTML content
+        # @return [Symbol] :html5 or :html4
+        def detect_html_version(content)
+          # Check for HTML5 doctype (case-insensitive)
+          if content.match?(/<!DOCTYPE\s+html>/i)
+            :html5
+          # Check for HTML4 doctype patterns
+          elsif content.match?(/<!DOCTYPE\s+HTML\s+PUBLIC/i)
+            :html4
+          else
+            # Default to HTML5 for modern usage
+            :html5
+          end
+        end
+
+        # Detect HTML version from Nokogiri node
+        #
+        # @param node [Nokogiri::XML::Node] Nokogiri HTML node
+        # @return [Symbol] :html5 or :html4
+        def detect_html_version_from_node(node)
+          # Check node type
+          if node.is_a?(Nokogiri::HTML5::Document) ||
+              node.is_a?(Nokogiri::HTML5::DocumentFragment)
+            :html5
+          elsif node.is_a?(Nokogiri::HTML4::Document) ||
+              node.is_a?(Nokogiri::HTML4::DocumentFragment)
+            :html4
+          else
+            # Default to HTML4 for compatibility
+            :html4
+          end
+        end
+
+        # Serialize node to string for diff display
+        # This ensures the displayed diff matches what was compared
+        #
+        # @param node [Nokogiri::HTML::Document] Parsed HTML node
+        # @return [String] Serialized HTML string
+        def serialize_for_display(node)
+          # Get string representation with formatting for line-by-line diffs
+          # Use to_html which preserves line structure for diff display
+          node.to_html
+        end
+
+        # Normalize HTML comments within style and script tags
+        # Also removes whitespace-only CDATA children that Nokogiri creates
+        def normalize_html_style_script_comments(doc)
+          doc.css("style, script").each do |element|
+            # Remove HTML comments from style/script content
+            # SAFE: This regex operates on already-parsed DOM element content,
+            # not on raw user input. The non-greedy .*? correctly matches
+            # comment boundaries. Any remaining <!-- would be literal text
+            # (not a comment), which is safe in this context.
+            # CodeQL false positive: see https://github.com/github/codeql/issues/XXXX
+            normalized = element.content.gsub(/<!--.*?-->/m, "").strip
+
+            if normalized.empty?
+              # Remove all children (including whitespace-only CDATA nodes)
+              element.children.remove
+            else
+              element.content = normalized
+            end
+          end
+        end
+
+        # Normalize whitespace in text nodes according to HTML rendering rules
+        # In HTML rendering, sequences of whitespace (spaces, tabs, newlines)
+        # collapse to a single space, except in elements where whitespace is
+        # significant (pre, code, textarea, script, style)
+        #
+        # @param doc [Nokogiri::HTML::Document] Document to normalize
+        # @param match_opts [Hash] Match options to respect during normalization
+        def normalize_rendered_whitespace(doc, match_opts = {})
+          # If text_content is :strict, don't normalize ANY text content
+          # This allows users to explicitly request strict text matching
+          return if match_opts[:text_content] == :strict
+
+          # Elements where whitespace is significant - don't normalize
+          # This is an HTML rendering rule, not a match option
+          preserve_whitespace = %w[pre code textarea script style]
+
+          # Walk all text nodes
+          doc.xpath(".//text()").each do |text_node|
+            # Skip if this text node is inside a whitespace-preserving element
+            # Check all ancestors, not just immediate parent
+            # Whitespace preservation happens REGARDLESS of text_content setting
+            parent = text_node.parent
+            next if ancestor_preserves_whitespace?(parent, preserve_whitespace)
+
+            # Collapse whitespace sequences (spaces, tabs, newlines) to single
+            # space
+            normalized = text_node.content.gsub(/\s+/, " ")
+
+            # Trim leading/trailing whitespace if appropriate
+            normalized = normalized.strip if should_trim_text_node?(text_node)
+
+            text_node.content = normalized
+          end
+        end
+
+        # Check if any ancestor of the given node preserves whitespace
+        def ancestor_preserves_whitespace?(node, preserve_list)
+          current = node
+          while current.respond_to?(:name)
+            return true if preserve_list.include?(current.name.downcase)
+
+            # Stop at document root - documents don't have parents
+            break if current.is_a?(Nokogiri::XML::Document)
+
+            current = current.parent
+          end
+          false
+        end
+
+        # Determine if a text node should have leading/trailing whitespace
+        # trimmed Text nodes at the start or end of their parent element should
+        # be trimmed
+        def should_trim_text_node?(text_node)
+          parent = text_node.parent
+          siblings = parent.children
+
+          # Trim if text is the only child
+          return true if siblings.length == 1
+
+          # Trim if text is at the start or end of parent
+          text_node == siblings.first || text_node == siblings.last
+        end
+
+        # Remove whitespace-only text nodes from the document
+        # These are typically insignificant in HTML rendering (e.g., between
+        # block elements)
+        def remove_whitespace_only_text_nodes(doc)
+          doc.xpath(".//text()").each do |text_node|
+            # Remove if the text is only whitespace (after normalization)
+            if text_node.content.strip.empty?
+              text_node.remove
+            end
+          end
+        end
+
+        # Check if a node is an XML document (not HTML)
+        # XML documents typically have XML processing instructions or are
+        # instances of Nokogiri::XML::Document (not HTML variants)
+        def is_xml_document?(node)
+          # Check if it's a pure XML document (not HTML4/HTML5 which also
+          # inherit from XML::Document)
+          # Check both Document and DocumentFragment variants
+          return false if node.is_a?(Nokogiri::HTML4::Document) ||
+            node.is_a?(Nokogiri::HTML5::Document) ||
+            node.is_a?(Nokogiri::HTML4::DocumentFragment) ||
+            node.is_a?(Nokogiri::HTML5::DocumentFragment)
+
+          # If it's an XML document, check for XML processing instruction
+          if node.is_a?(Nokogiri::XML::Document) && node.children.any? do |child|
+            child.is_a?(Nokogiri::XML::ProcessingInstruction) &&
+                child.name == "xml"
+          end
+            # XML documents often start with <?xml ...?> processing instruction
+            return true
+
+            # Note: We don't blindly return true here because HTML documents
+            # also inherit from XML::Document. We only return true if there's
+            # an XML processing instruction above.
+          end
+
+          # Check if it's a fragment that contains XML processing instructions
+          if node.respond_to?(:children) && node.children.any? do |child|
+            child.is_a?(Nokogiri::XML::ProcessingInstruction) &&
+                child.name == "xml"
+          end
+            return true
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/json_comparator.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "match_options"
+require_relative "comparison_result"
+
+module Canon
+  module Comparison
+    # JSON comparison class
+    # Handles comparison of JSON objects with various options
+    class JsonComparator
+      # Default comparison options for JSON
+      DEFAULT_OPTS = {
+        # Output options
+        verbose: false,
+
+        # Match system options
+        match_profile: nil,
+        match: nil,
+        preprocessing: nil,
+        global_profile: nil,
+        global_options: nil,
+
+        # Diff display options
+        diff: nil,
+      }.freeze
+
+      class << self
+        # Compare two JSON objects for equivalence
+        #
+        # @param json1 [String, Hash, Array] First JSON
+        # @param json2 [String, Hash, Array] Second JSON
+        # @param opts [Hash] Comparison options
+        # @return [Boolean, ComparisonResult] true if equivalent, or ComparisonResult if verbose
+        def equivalent?(json1, json2, opts = {})
+          opts = DEFAULT_OPTS.merge(opts)
+
+          # Resolve match options with format-specific defaults
+          match_opts_hash = MatchOptions::Json.resolve(
+            format: :json,
+            match_profile: opts[:match_profile],
+            match: opts[:match],
+            preprocessing: opts[:preprocessing],
+            global_profile: opts[:global_profile],
+            global_options: opts[:global_options],
+          )
+
+          # Wrap in ResolvedMatchOptions for consistency with XML/HTML
+          Canon::Comparison::ResolvedMatchOptions.new(
+            match_opts_hash,
+            format: :json,
+          )
+
+          # Store resolved match options for use in comparison logic
+          opts[:match_opts] = match_opts_hash
+
+          # Parse JSON if strings
+          obj1 = parse_json(json1)
+          obj2 = parse_json(json2)
+
+          differences = []
+          result = compare_ruby_objects(obj1, obj2, opts, differences, "")
+
+          if opts[:verbose]
+            # Format JSON for display
+            json_str1 = obj1.is_a?(String) ? obj1 : JSON.pretty_generate(obj1)
+            json_str2 = obj2.is_a?(String) ? obj2 : JSON.pretty_generate(obj2)
+
+            ComparisonResult.new(
+              differences: differences,
+              preprocessed_strings: [json_str1, json_str2],
+              format: :json,
+              match_options: match_opts_hash,
+            )
+          else
+            result == Comparison::EQUIVALENT
+          end
+        end
+
+        private
+
+        # Parse JSON from string or return as-is
+        def parse_json(obj)
+          return obj unless obj.is_a?(String)
+
+          JSON.parse(obj)
+        end
+
+        # Compare Ruby objects (Hash, Array, primitives) for JSON/YAML
+        def compare_ruby_objects(obj1, obj2, opts, differences, path)
+          # Check for type mismatch
+          unless obj1.instance_of?(obj2.class)
+            add_ruby_difference(path, obj1, obj2, Comparison::UNEQUAL_TYPES,
+                                opts, differences)
+            return Comparison::UNEQUAL_TYPES
+          end
+
+          case obj1
+          when Hash
+            compare_hashes(obj1, obj2, opts, differences, path)
+          when Array
+            compare_arrays(obj1, obj2, opts, differences, path)
+          when NilClass, TrueClass, FalseClass, Numeric, String, Symbol
+            compare_primitives(obj1, obj2, opts, differences, path)
+          else
+            # Fallback to equality comparison
+            if obj1 == obj2
+              Comparison::EQUIVALENT
+            else
+              add_ruby_difference(path, obj1, obj2,
+                                  Comparison::UNEQUAL_PRIMITIVES, opts,
+                                  differences)
+              Comparison::UNEQUAL_PRIMITIVES
+            end
+          end
+        end
+
+        # Compare two hashes
+        def compare_hashes(hash1, hash2, opts, differences, path)
+          keys1 = hash1.keys
+          keys2 = hash2.keys
+
+          # Sort keys if order should be ignored (based on match options)
+          match_opts = opts[:match_opts]
+          if match_opts[:key_order] != :strict
+            keys1 = keys1.sort_by(&:to_s)
+            keys2 = keys2.sort_by(&:to_s)
+          end
+
+          # Check for missing keys
+          missing_in_2 = keys1 - keys2
+          missing_in_1 = keys2 - keys1
+
+          missing_in_2.each do |key|
+            key_path = path.empty? ? key.to_s : "#{path}.#{key}"
+            add_ruby_difference(key_path, hash1[key], nil,
+                                Comparison::MISSING_HASH_KEY, opts, differences)
+          end
+
+          missing_in_1.each do |key|
+            key_path = path.empty? ? key.to_s : "#{path}.#{key}"
+            add_ruby_difference(key_path, nil, hash2[key],
+                                Comparison::MISSING_HASH_KEY, opts, differences)
+          end
+
+          has_missing_keys = !missing_in_1.empty? || !missing_in_2.empty?
+
+          # Compare common keys
+          common_keys = keys1 & keys2
+          all_equivalent = true
+          common_keys.each do |key|
+            key_path = path.empty? ? key.to_s : "#{path}.#{key}"
+            result = compare_ruby_objects(hash1[key], hash2[key], opts,
+                                          differences, key_path)
+            all_equivalent = false unless result == Comparison::EQUIVALENT
+          end
+
+          # Return appropriate status
+          return Comparison::MISSING_HASH_KEY if has_missing_keys && all_equivalent
+          return Comparison::UNEQUAL_HASH_VALUES unless all_equivalent
+
+          has_missing_keys ? Comparison::MISSING_HASH_KEY : Comparison::EQUIVALENT
+        end
+
+        # Compare two arrays
+        def compare_arrays(arr1, arr2, opts, differences, path)
+          unless arr1.length == arr2.length
+            add_ruby_difference(path, arr1, arr2,
+                                Comparison::UNEQUAL_ARRAY_LENGTHS, opts,
+                                differences)
+            return Comparison::UNEQUAL_ARRAY_LENGTHS
+          end
+
+          all_equivalent = true
+          arr1.each_with_index do |elem1, index|
+            elem2 = arr2[index]
+            elem_path = "#{path}[#{index}]"
+            result = compare_ruby_objects(elem1, elem2, opts, differences,
+                                          elem_path)
+            all_equivalent = false unless result == Comparison::EQUIVALENT
+          end
+
+          all_equivalent ? Comparison::EQUIVALENT : Comparison::UNEQUAL_ARRAY_ELEMENTS
+        end
+
+        # Compare primitive values
+        def compare_primitives(val1, val2, opts, differences, path)
+          if val1 == val2
+            Comparison::EQUIVALENT
+          else
+            add_ruby_difference(path, val1, val2,
+                                Comparison::UNEQUAL_PRIMITIVES, opts,
+                                differences)
+            Comparison::UNEQUAL_PRIMITIVES
+          end
+        end
+
+        # Add a Ruby object difference
+        def add_ruby_difference(path, obj1, obj2, diff_code, opts, differences)
+          return unless opts[:verbose]
+
+          differences << {
+            path: path,
+            value1: obj1,
+            value2: obj2,
+            diff_code: diff_code,
+          }
+        end
+      end
+    end
+  end
+end