canon 0.2.7 → 0.2.9

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

@@ -23,14 +23,10 @@ module Canon
         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)
+          if Canon::XmlBackend.nokogiri?
             extract_from_nokogiri(node)
           else
-            0
+            extract_from_moxml(node)
           end
         end
 

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

@@ -25,14 +25,10 @@ module Canon
         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)
+          if Canon::XmlBackend.nokogiri?
             extract_from_nokogiri(node)
           else
-            []
+            extract_from_moxml(node)
           end
         end
 

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

@@ -23,12 +23,10 @@ module Canon
         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)
+          if Canon::XmlBackend.nokogiri?
             extract_from_nokogiri(node)
+          else
+            extract_from_moxml(node)
           end
         end
 

data/lib/canon/comparison/format_detector.rb

@@ -22,27 +22,36 @@ module Canon
         # @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
+          if XmlBackend.moxml?
+            case obj
+            when Moxml::Node, Moxml::Document
+              :xml
+            when String
+              detect_string(obj)
+            when Hash, Array
+              :ruby_object
+            else
+              raise Canon::Error, "Unknown format for object: #{obj.class}"
+            end
           else
-            raise Canon::Error, "Unknown format for object: #{obj.class}"
+            case obj
+            when Moxml::Node, Moxml::Document
+              :xml
+            when Nokogiri::HTML::DocumentFragment, Nokogiri::HTML5::DocumentFragment
+              :html
+            when Nokogiri::XML::DocumentFragment
+              obj.document&.html? ? :html : :xml
+            when Nokogiri::XML::Document, Nokogiri::XML::Node
+              obj.html? ? :html : :xml
+            when Nokogiri::HTML::Document, Nokogiri::HTML5::Document
+              :html
+            when String
+              detect_string(obj)
+            when Hash, Array
+              :ruby_object
+            else
+              raise Canon::Error, "Unknown format for object: #{obj.class}"
+            end
           end
         end
 

data/lib/canon/comparison/html_comparator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "nokogiri"
+require "nokogiri" unless RUBY_ENGINE == "opal"
 require_relative "../comparison" # Load base module with constants first
 require_relative "markup_comparator"
 require_relative "xml_comparator"
@@ -167,6 +167,11 @@ module Canon
           end
         end
 
+        # Public parsing API for external callers
+        def parse(html, preprocessing = :none)
+          parse_node_for_semantic(html, preprocessing)
+        end
+
         private
 
         # Check if both nodes are document fragments
@@ -188,32 +193,9 @@ module Canon
             node.is_a?(Nokogiri::HTML5::DocumentFragment)
         end
 
-        # Record a DiffNode for a fragment-level child-count mismatch.
-        # Each surplus child becomes its own MISSING_NODE diff so the
-        # downstream report shows what was added or removed.
-        def record_fragment_length_mismatch(_node1, _node2, children1,
-                                            children2, differences)
-          longer, shorter, side = if children1.length > children2.length
-                                    [children1, children2, :removed]
-                                  else
-                                    [children2, children1, :added]
-                                  end
-
-          longer[shorter.length...].each do |orphan|
-            n1 = side == :removed ? orphan : nil
-            n2 = side == :removed ? nil    : orphan
-            differences <<
-              Canon::Comparison::DiffNodeBuilder.build(
-                node1: n1,
-                node2: n2,
-                diff1: Comparison::MISSING_NODE,
-                diff2: Comparison::MISSING_NODE,
-                dimension: :element_structure,
-              )
-          end
-        end
-
-        # Compare children of document fragments
+        # Compare children of document fragments using the shared
+        # +ChildRealignment+ walk.  Structural orphans are emitted here
+        # (the HTML fragment path has no separate length-mismatch step).
         #
         # @param node1 [Nokogiri::DocumentFragment] First fragment
         # @param node2 [Nokogiri::DocumentFragment] Second fragment
@@ -230,29 +212,24 @@ module Canon
           children1 = XmlNodeComparison.filter_children(all_children1, opts)
           children2 = XmlNodeComparison.filter_children(all_children2, opts)
 
-          if children1.length != children2.length
-            # Record the length mismatch as a DiffNode so verbose mode
-            # surfaces it. Without this, equivalent? wraps an empty
-            # differences array and incorrectly reports the inputs as
-            # equivalent.
-            record_fragment_length_mismatch(node1, node2,
-                                            children1, children2,
-                                            differences)
-            return Comparison::UNEQUAL_ELEMENTS
-          elsif children1.empty?
-            return Comparison::EQUIVALENT
-          end
+          return Comparison::EQUIVALENT if children1.empty? && children2.empty?
 
-          # Compare each pair of children
-          children1.zip(children2).each do |child1, child2|
-            child_result = XmlNodeComparison.compare_nodes(child1, child2,
-                                                           opts, child_opts,
-                                                           diff_children,
-                                                           differences)
-            return child_result if child_result != Comparison::EQUIVALENT
+          emitter = html_diff_emitter(differences)
+          ChildRealignment.walk(children1, children2, emitter,
+                                emit_structural_orphans: true) do |c1, c2|
+            XmlNodeComparison.compare_nodes(c1, c2, opts, child_opts,
+                                            diff_children, differences)
           end
+        end
 
-          Comparison::EQUIVALENT
+        # Build a diff emitter for the HTML comparator path that
+        # creates DiffNode objects via DiffNodeBuilder.
+        def html_diff_emitter(differences)
+          proc do |n1, n2, d1, d2, dim|
+            differences << Canon::Comparison::DiffNodeBuilder.build(
+              node1: n1, node2: n2, diff1: d1, diff2: d2, dimension: dim,
+            )
+          end
         end
 
         # Perform semantic tree diff using SemanticTreeMatchStrategy
@@ -365,13 +342,10 @@ module Canon
           # Convert to string if needed
           html_string = if html.is_a?(String)
                           html
-                        elsif html.respond_to?(:to_html)
+                        elsif Canon::XmlParsing.xml_node?(html)
                           html.to_html
-                        elsif html.respond_to?(:to_s)
-                          html.to_s
                         else
-                          raise Canon::Error,
-                                "Unable to convert HTML to string: #{html.class}"
+                          html.to_s
                         end
 
           # Strip DOCTYPE for consistent parsing
@@ -520,22 +494,18 @@ module Canon
         end
 
         def find_and_normalize_style_script(node)
-          return unless node.respond_to?(:children)
+          return unless node.is_a?(Canon::Xml::Node)
 
           node.children.each do |child|
             next unless child.is_a?(Canon::Xml::Nodes::ElementNode)
 
             # If this is a style or script element, normalize its text content
             if %w[style script].include?(child.name.downcase)
-              # Get text children and remove HTML comments from them
               child.children.each do |text_child|
                 next unless text_child.is_a?(Canon::Xml::Nodes::TextNode)
 
-                # Remove HTML comments from text content without using regex
-                # to avoid ReDoS/incomplete sanitization vulnerabilities
                 normalized = remove_html_comments(text_child.value)
-                # Update the text value
-                text_child.instance_variable_set(:@value, normalized)
+                text_child.value = normalized
               end
             end
 
@@ -612,13 +582,10 @@ module Canon
         # @param node [Canon::Xml::Node, Nokogiri::HTML::Document] Parsed node
         # @return [String] Serialized HTML string
         def serialize_for_display(node)
-          # Use XmlNodeComparison's serializer for Canon::Xml::Node
           if node.is_a?(Canon::Xml::Node)
             XmlNodeComparison.serialize_node_to_xml(node)
-          elsif node.respond_to?(:to_html)
-            node.to_html
-          elsif node.respond_to?(:to_xml)
-            node.to_xml
+          elsif Canon::XmlParsing.xml_node?(node)
+            Canon::XmlBackend.nokogiri? ? node.to_html : Canon::XmlParsing.serialize(node)
           else
             node.to_s
           end
@@ -633,16 +600,11 @@ module Canon
           if html.is_a?(String)
             html
           elsif html.is_a?(Canon::Xml::Node)
-            # Serialize Canon nodes to string
             Canon::Xml::DataModel.serialize(html)
-          elsif html.respond_to?(:to_html)
-            # Nokogiri nodes - use to_html to preserve formatting
-            html.to_html
-          elsif html.respond_to?(:to_s)
-            html.to_s
+          elsif Canon::XmlParsing.xml_node?(html)
+            Canon::XmlBackend.nokogiri? ? html.to_html : html.to_s
           else
-            raise Canon::Error,
-                  "Unable to extract original string from: #{html.class}"
+            html.to_s
           end
         end
 
@@ -755,11 +717,10 @@ compare_profile = nil)
         # Check if any ancestor of the given node preserves whitespace
         def ancestor_preserves_whitespace?(node, preserve_list)
           current = node
-          while current.respond_to?(:name)
+          while current.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(current)
             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)
+            break if Canon::XmlParsing.document?(current)
 
             current = current.parent
           end
@@ -839,7 +800,7 @@ compare_profile = nil)
           end
 
           # Check if it's a fragment that contains XML processing instructions
-          if node.respond_to?(:children) && node.children.any? do |child|
+          if (node.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(node)) && node.children.any? do |child|
             child.is_a?(Nokogiri::XML::ProcessingInstruction) &&
                 child.name == "xml"
           end

data/lib/canon/comparison/html_compare_profile.rb

@@ -48,9 +48,8 @@ module Canon
 
             # If key exists, check if it's :strict
             return match_options[:comments] == :strict
-          elsif match_options.respond_to?(:behavior_for)
+          elsif match_options.is_a?(ResolvedMatchOptions)
             behavior = behavior_for(dimension)
-            # In HTML, only :strict makes comments affect equivalence
             return behavior == :strict
           end
           # Default: comments don't affect equivalence in HTML
@@ -106,14 +105,8 @@ module Canon
       def has_explicit_option?(dimension)
         if match_options.is_a?(Hash)
           match_options.key?(dimension)
-        elsif match_options.respond_to?(:[])
-          # For ResolvedMatchOptions, check if key exists
-          begin
-            match_options[dimension]
-            true
-          rescue StandardError
-            false
-          end
+        elsif match_options.is_a?(ResolvedMatchOptions)
+          !match_options.options[dimension].nil?
         else
           false
         end

data/lib/canon/comparison/html_parser.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "nokogiri"
+require "nokogiri" unless RUBY_ENGINE == "opal"
 
 module Canon
   module Comparison

data/lib/canon/comparison/json_comparator.rb

@@ -26,6 +26,14 @@ module Canon
       }.freeze
 
       class << self
+        # Parse JSON from string or return as-is
+        #
+        # @param obj [String, Hash, Array] JSON string or parsed object
+        # @return [Object] Parsed JSON object
+        def parse(obj)
+          parse_json(obj)
+        end
+
         # Compare two JSON objects for equivalence
         #
         # @param json1 [String, Hash, Array] First JSON

data/lib/canon/comparison/node_inspector.rb

@@ -4,42 +4,76 @@ module Canon
   module Comparison
     # Single source of truth for cross-backend node type operations.
     #
-    # The comparison pipeline handles nodes from two backends:
+    # The comparison pipeline handles nodes from multiple sources:
     # * Canon::Xml::Node (+ RootNode, ElementNode, TextNode, etc.) —
     #   custom DOM built by SAX builder and DataModel.
-    # * Nokogiri::XML::Node (+ subclasses) — native Nokogiri nodes used
-    #   by the HTML comparator and some legacy paths.
+    # * Canon::TreeDiff::Core::TreeNode — semantic tree diff nodes.
+    # * Backend-specific nodes (Nokogiri or Moxml) — live parsed nodes.
     #
-    # Every method here dispatches on type via +case/when+ (+is_a?+).
-    # No +respond_to?+ — the types are known at every call site.
+    # All type dispatch uses backend-branching (`if XmlBackend.nokogiri?`)
+    # rather than `case/when` with constant references. This prevents
+    # NameError when Nokogiri constants are undefined under Opal.
+    #
+    # Every node query in the codebase should go through this module.
+    # Do not create private dispatch methods in consumers.
     module NodeInspector
-      CANON_TEXT_TYPE = :text
       NOKOGIRI_TEXT_TYPE = defined?(Nokogiri::XML::Node::TEXT_NODE) ? Nokogiri::XML::Node::TEXT_NODE : 3
 
-      # True when +node+ is a text node (whitespace, content, etc.).
+      # --- Type predicates ---
+
       def self.text_node?(node)
-        case node
-        when Canon::Xml::Node
-          node.node_type == CANON_TEXT_TYPE
-        when Nokogiri::XML::Node
-          node.node_type == NOKOGIRI_TEXT_TYPE
+        return false unless node
+        return node.node_type == :text if node.is_a?(Canon::Xml::Node)
+
+        if XmlBackend.nokogiri?
+          node.is_a?(Nokogiri::XML::Text) || node.is_a?(Moxml::Text)
         else
-          false
+          node.is_a?(Moxml::Text)
         end
       end
 
-      # Extract the text content of +node+ as a String.
-      def self.text_content(node)
-        case node
-        when Canon::Xml::Node
-          node.value.to_s
-        when Nokogiri::XML::Node
-          node.content.to_s
+      def self.element_node?(node)
+        return false unless node
+        return node.node_type == :element if node.is_a?(Canon::Xml::Node)
+
+        if XmlBackend.nokogiri?
+          node.is_a?(Nokogiri::XML::Element) || node.is_a?(Moxml::Element)
+        else
+          node.is_a?(Moxml::Element)
+        end
+      end
+
+      def self.comment_node?(node)
+        return false unless node
+        return node.node_type == :comment if node.is_a?(Canon::Xml::Node)
+
+        if XmlBackend.nokogiri?
+          return true if node.is_a?(Nokogiri::XML::Node) && node.comment?
+
+          # HTML comments are parsed as TEXT nodes by Nokogiri
+          if node.is_a?(Nokogiri::XML::Node) && node.text?
+            text_stripped = text_content(node).to_s.strip.gsub("\\", "")
+            return true if text_stripped.start_with?("<!--") && text_stripped.end_with?("-->")
+          end
+          false
         else
-          node.to_s
+          node.is_a?(Moxml::Comment)
         end
       end
 
+      def self.document?(node)
+        return node.node_type == :root if node.is_a?(Canon::Xml::Node)
+
+        XmlParsing.document?(node)
+      end
+
+      def self.document_fragment?(node)
+        return false unless node
+        return false unless node.is_a?(Canon::Xml::Nodes::RootNode)
+
+        node.fragment?
+      end
+
       # True when +node+ is a text node whose content is whitespace-only.
       # Empty-string text nodes return false — those represent genuine
       # empty-vs-content asymmetry, not pretty-print indentation.
@@ -50,62 +84,120 @@ module Canon
         !text.empty? && text.strip.empty?
       end
 
-      # True when +node+ is a comment node.
-      # For HTML, also detects comments that Nokogiri parses as TEXT nodes
-      # (content like "<!-- comment -->" or escaped "<\\!-- comment -->").
-      def self.comment_node?(node)
+      # --- Noise classification ---
+
+      def self.noise_dimension_for(node)
+        if whitespace_only_text?(node)
+          :whitespace_adjacency
+        elsif comment_node?(node)
+          :comments
+        end
+      end
+
+      def self.noise_node?(node)
+        !noise_dimension_for(node).nil?
+      end
+
+      # --- Node queries ---
+
+      # Unified node name extraction across all node types.
+      def self.name(node)
+        return nil unless node
+        return node.name if node.is_a?(Canon::Xml::Node)
+        return node.label if node.is_a?(Canon::TreeDiff::Core::TreeNode)
+
+        XmlParsing.name(node)
+      end
+
+      # Unified parent access across all node types.
+      def self.parent(node)
+        return nil unless node
+        return node.parent if node.is_a?(Canon::Xml::Node)
+        return node.parent if node.is_a?(Canon::TreeDiff::Core::TreeNode)
+
+        XmlParsing.parent(node)
+      end
+
+      # Unified children access across all node types.
+      def self.children(node)
+        return [] unless node
+        return node.children if node.is_a?(Canon::Xml::Node)
+        return node.children || [] if node.is_a?(Canon::TreeDiff::Core::TreeNode)
+
+        XmlParsing.children(node)
+      end
+
+      # Extract the text content of +node+ as a String.
+      def self.text_content(node)
         case node
+        when Canon::Xml::Nodes::TextNode
+          node.value.to_s
         when Canon::Xml::Node
-          node.node_type == :comment
-        when Nokogiri::XML::Node
-          return true if node.comment?
+          node.text_content.to_s
+        when Moxml::Text
+          node.content.to_s
+        else
+          XmlParsing.text_content(node).to_s
+        end
+      end
 
-          # HTML comments are parsed as TEXT nodes by Nokogiri
-          if node.text?
-            text_stripped = text_content(node).to_s.strip.gsub("\\", "")
-            return true if text_stripped.start_with?("<!--") && text_stripped.end_with?("-->")
-          end
-          false
+      # Unified node type that always returns a symbol.
+      # Returns nil for unrecognised nodes.
+      def self.node_type(node)
+        return nil unless node
+        return node.node_type if node.is_a?(Canon::Xml::Node)
+
+        if node.is_a?(Canon::TreeDiff::Core::TreeNode)
+          node.type&.to_sym
         else
-          false
+          XmlParsing.node_type(node)
         end
       end
 
-      # True when +node+ is an element node.
-      def self.element_node?(node)
-        case node
-        when Canon::Xml::Node
-          node.node_type == :element
-        when Nokogiri::XML::Node
-          node.element?
+      # Unified attribute value access.
+      def self.attribute_value(node, attr_name)
+        return nil unless node
+
+        if node.is_a?(Canon::Xml::Nodes::ElementNode)
+          attr = node.attribute_nodes.find { |a| a.name == attr_name.to_s }
+          attr&.value
+        elsif node.is_a?(Canon::Xml::Node)
+          nil
         else
-          false
+          XmlParsing.attribute_value(node, attr_name)
+        end
+      end
+
+      # Unified namespace URI access.
+      def self.namespace_uri(node)
+        return nil unless node
+
+        if node.is_a?(Canon::Xml::Node)
+          node.is_a?(Canon::Xml::Nodes::ElementNode) ? node.namespace_uri : nil
+        else
+          XmlParsing.namespace_uri(node)
         end
       end
 
       # Extract parse-time errors carried on a node or its owning document.
-      # Returns an Array of Strings.
       def self.parse_errors(node)
-        case node
-        when nil
-          []
-        when Canon::Xml::Node
-          errors = node.parse_errors
-          Array(errors).map(&:to_s)
-        when Nokogiri::XML::Document, Nokogiri::HTML5::Document
-          Array(node.errors).map(&:to_s)
+        return [] if node.nil?
+        return Array(node.parse_errors).map(&:to_s) if node.is_a?(Canon::Xml::Node)
+
+        if XmlBackend.nokogiri?
+          if node.is_a?(Nokogiri::XML::Document) || node.is_a?(Nokogiri::HTML5::Document)
+            Array(node.errors).map(&:to_s)
+          else
+            []
+          end
         else
           []
         end
       end
 
-      # Return the parent node of +node+, or nil when +node+ is not a
-      # recognised DOM backend type or has no parent.
+      # Deprecated: use NodeInspector.parent instead.
       def self.parent_of(node)
-        case node
-        when Canon::Xml::Node, Nokogiri::XML::Node
-          node.parent
-        end
+        parent(node)
       end
     end
   end

data/lib/canon/comparison/strategies/semantic_tree_match_strategy.rb

@@ -125,20 +125,18 @@ module Canon
         # @param doc2 [Object] Second XML document
         # @return [Array<String>] Preprocessed strings
         def preprocess_xml(doc1, doc2)
-          # Serialize XML to string
-          # Use XmlNodeComparison's serializer for Canon::Xml::Node
           xml1 = if doc1.is_a?(Canon::Xml::Node)
                    XmlNodeComparison.serialize_node_to_xml(doc1)
-                 elsif doc1.respond_to?(:to_xml)
-                   doc1.to_xml
+                 elsif Canon::XmlParsing.xml_node?(doc1)
+                   Canon::XmlParsing.serialize(doc1)
                  else
                    doc1.to_s
                  end
 
           xml2 = if doc2.is_a?(Canon::Xml::Node)
                    XmlNodeComparison.serialize_node_to_xml(doc2)
-                 elsif doc2.respond_to?(:to_xml)
-                   doc2.to_xml
+                 elsif Canon::XmlParsing.xml_node?(doc2)
+                   Canon::XmlParsing.serialize(doc2)
                  else
                    doc2.to_s
                  end
@@ -167,7 +165,7 @@ module Canon
                     XmlNodeComparison.serialize_node_to_xml(doc1)
                   elsif doc1.is_a?(Nokogiri::XML::DocumentFragment)
                     doc1.to_s
-                  elsif doc1.respond_to?(:to_html)
+                  elsif Canon::XmlParsing.xml_node?(doc1)
                     doc1.to_html
                   else
                     doc1.to_s
@@ -177,7 +175,7 @@ module Canon
                     XmlNodeComparison.serialize_node_to_xml(doc2)
                   elsif doc2.is_a?(Nokogiri::XML::DocumentFragment)
                     doc2.to_s
-                  elsif doc2.respond_to?(:to_html)
+                  elsif Canon::XmlParsing.xml_node?(doc2)
                     doc2.to_html
                   else
                     doc2.to_s