canon 0.2.11 → 0.3.0

data/lib/canon/xml/sax_builder.rb

@@ -1,25 +1,13 @@
 # frozen_string_literal: true
 
-require "nokogiri" unless RUBY_ENGINE == "opal"
-require_relative "nodes/root_node"
-require_relative "nodes/element_node"
-require_relative "nodes/namespace_node"
-require_relative "nodes/attribute_node"
-require_relative "nodes/text_node"
-require_relative "nodes/comment_node"
-require_relative "nodes/processing_instruction_node"
-
 module Canon
   module Xml
-    # Builds Canon::Xml::Node tree using Nokogiri SAX parser
-    #
-    # This is MUCH faster than DOM parsing + conversion because:
-    # 1. No intermediate Nokogiri DOM tree (saves ~60ms)
-    # 2. No tree traversal to build Canon (saves ~1200ms)
-    # 3. No memory overhead of two complete DOM trees
+    # Builds Canon::Xml::Node tree from SAX events.
     #
-    # Current (SLOW): XML String → Nokogiri DOM (~60ms) → Canon DOM (~1200ms) = ~1260ms
-    # Optimized (FAST): XML String → Nokogiri SAX → Canon DOM (~200ms) = ~200ms
+    # Engine-neutral: the event protocol is Nokogiri-shaped (qname +
+    # attribute pairs with xmlns declarations inline); Canon::Xml::Sax
+    # selects the driver. Much faster than DOM parsing + conversion —
+    # no intermediate engine DOM tree, no traversal conversion pass.
     #
     # Usage:
     #   root = SaxBuilder.parse(xml_string, preserve_whitespace: false)
@@ -28,7 +16,7 @@ module Canon
     # For C14N, use strip_doctype: true to avoid DTD default attribute expansion:
     #   root = SaxBuilder.parse(xml_string, strip_doctype: true)
     #
-    class SaxBuilder < (RUBY_ENGINE == "opal" ? Object : Nokogiri::XML::SAX::Document)
+    class SaxBuilder
       # Parse XML string and return Canon::Xml::Node tree
       #
       # @param xml_string [String] XML content to parse
@@ -37,7 +25,7 @@ module Canon
       # @return [Nodes::RootNode] Root of the data model tree
       def self.parse(xml_string, preserve_whitespace: false,
 strip_doctype: false)
-        # Strip DOCTYPE to prevent Nokogiri SAX from expanding DTD default attributes
+        # Strip DOCTYPE to prevent the SAX engine from expanding DTD default attributes
         # This is needed for C14N which should NOT include default attributes from DTD
         # Use string methods instead of complex regex to avoid ReDoS vulnerability
         if strip_doctype
@@ -45,8 +33,7 @@ strip_doctype: false)
         end
 
         builder = new(preserve_whitespace: preserve_whitespace)
-        parser = Nokogiri::XML::SAX::Parser.new(builder)
-        parser.parse(xml_string)
+        Canon::Xml::Sax.parse(xml_string, builder)
         builder.result
       end
 
@@ -86,7 +73,6 @@ strip_doctype: false)
       #
       # @param preserve_whitespace [Boolean] Whether to preserve whitespace-only text nodes
       def initialize(preserve_whitespace: false)
-        super()
         @preserve_whitespace = preserve_whitespace
         @root = Nodes::RootNode.new
         @stack = [@root]
@@ -175,13 +161,30 @@ strip_doctype: false)
       def characters(string)
         return if string.nil?
 
-        parent = @stack.last
+        append_text(decode_character_references(string), string)
+      end
+
+      # Called for CDATA content. CDATA is literal character data:
+      # character references inside it are NOT decoded (a literal
+      # &#65; stays as written), unlike regular text where they are
+      # resolved. Whitespace and adjacency rules match characters so
+      # the two forms of character data build identical trees.
+      #
+      # @param string [String] CDATA content
+      def cdata(string)
+        return if string.nil?
 
-        # Capture raw text BEFORE entity resolution for accurate serialization
-        raw_string = string
+        append_text(string, string)
+      end
 
-        # Decode numeric character references
-        decoded_string = decode_character_references(string)
+      # Append character data to the tree: combine with an adjacent
+      # text node if present, else create one (respecting the
+      # whitespace-only skip rules).
+      #
+      # @param decoded_string [String] value with character references resolved
+      # @param raw_string [String] value as delivered (pre-resolution)
+      def append_text(decoded_string, raw_string)
+        parent = @stack.last
 
         # Combine with previous text node if adjacent (SAX can split text content)
         # This MUST happen before whitespace check, because SAX may split "foo "
@@ -215,6 +218,7 @@ strip_doctype: false)
         text = Nodes::TextNode.new(value: decoded_string, original: raw_string)
         parent.add_child(text)
       end
+      private :append_text
 
       # Called for comments
       #

data/lib/canon/xml.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Canon
+  # Native XML data model, parsing, and DOM utilities.
+  #
+  # This namespace holds Canon's own XML representation (independent of
+  # Nokogiri/Moxml), including:
+  # * the XPath data model nodes (Canon::Xml::Node and Canon::Xml::Nodes::*)
+  # * the SAX builder that produces them
+  # * element matching, line-range mapping, xpath, C14N, processors
+  # * canonicalization (C14n) and serialization helpers
+  #
+  # All children are autoloaded from this file. The nested Nodes namespace
+  # is itself a sibling and is autoloaded on first reference to
+  # Canon::Xml::Nodes.
+  module Xml
+    autoload :AttributeHandler, "canon/xml/attribute_handler"
+    autoload :C14n, "canon/xml/c14n"
+    autoload :CharacterEncoder, "canon/xml/character_encoder"
+    autoload :DataModel, "canon/xml/data_model"
+    autoload :ElementMatcher, "canon/xml/element_matcher"
+    autoload :LineRangeMapper, "canon/xml/line_range_mapper"
+    autoload :NamespaceHandler, "canon/xml/namespace_handler"
+    autoload :NamespaceHelper, "canon/xml/namespace_helper"
+    autoload :Node, "canon/xml/node"
+    autoload :Nodes, "canon/xml/nodes"
+    autoload :Processor, "canon/xml/processor"
+    autoload :Sax, "canon/xml/sax"
+    autoload :SaxBuilder, "canon/xml/sax_builder"
+    autoload :WhitespaceNormalizer, "canon/xml/whitespace_normalizer"
+    autoload :XmlBaseHandler, "canon/xml/xml_base_handler"
+    autoload :XPathEngine, "canon/xml/xpath_engine"
+  end
+end

data/lib/canon/xml_backend.rb

@@ -1,24 +1,34 @@
 # frozen_string_literal: true
 
 module Canon
-  # Centralized XML backend detection for Canon.
+  # Selection of the XML engine.
   #
-  # Canon supports two XML backends:
-  # - :nokogiri — MRI with Nokogiri installed (default, existing code path)
-  # - :moxml    — Opal runtime or MRI without Nokogiri (uses Oga via moxml)
+  # Two independent concerns, deliberately separated (MECE):
+  # - XML engine — :nokogiri (raw) or :moxml (adapter-mediated). Drives DOM
+  #   parsing and serialization of XML (see Canon::XmlParsing).
+  # - HTML support — always Nokogiri on CRuby; moxml has no HTML adapter and
+  #   leptris no HTML parser (see Canon::Html::NokogiriSupport).
   #
-  # The active backend is determined once at load time and cached.
-  # All XML-related code should check `Canon::XmlBackend.moxml?` or
-  # `Canon::XmlBackend.nokogiri?` to select the appropriate code path.
+  # SSOT: moxml owns adapter preference (Moxml::Config prefers leptris when
+  # installed and capable; see XmlParsing.moxml_adapter_name). Canon's
+  # default engine is Nokogiri on CRuby until leptris WINS somewhere
+  # measurably: conformance parity is complete (engine_parity_spec 12/12),
+  # but the leptris SAX driver is blocked by a data-corruption bug
+  # (leptris-ruby#95) and the record-based conversion runs ~0.55x Nokogiri
+  # (CI performance gate: -42..45% on from_xml) pending lighter record
+  # emission upstream. Flipping the default is the one-line change in
+  # #detect; CANON_XML_BACKEND=moxml opts in today. Under Opal the engine
+  # is moxml (rexml adapter).
   #
-  # This module intentionally does NOT wrap Nokogiri through moxml.
-  # Each backend path is independent — the Nokogiri path is the existing
-  # battle-tested code; the moxml path is a parallel implementation for
-  # environments where Nokogiri is unavailable.
+  # HTML stays on Nokogiri on CRuby (Canon::Html::NokogiriSupport) and the
+  # pretty-printers keep the Nokogiri pipeline — pretty-printed bytes are
+  # canon's product (moxml#129).
   module XmlBackend
+    VALID_BACKENDS = %i[nokogiri moxml].freeze
+
     class << self
       def active
-        @active ||= detect
+        @active ||= forced || detect
       end
 
       def nokogiri?
@@ -35,14 +45,25 @@ module Canon
 
       private
 
-      def detect
-        if RUBY_ENGINE == "opal"
-          :moxml
-        elsif defined?(Nokogiri)
-          :nokogiri
-        else
-          :moxml
+      # Escape hatch and A/B test switch: CANON_XML_BACKEND=nokogiri|moxml.
+      def forced
+        value = ENV.fetch("CANON_XML_BACKEND", nil)
+        return nil if value.nil? || value.empty?
+
+        backend = value.to_sym
+        unless VALID_BACKENDS.include?(backend)
+          raise Canon::Error,
+                "Invalid CANON_XML_BACKEND: #{value.inspect}. " \
+                "Must be one of: #{VALID_BACKENDS.join(', ')}"
         end
+
+        backend
+      end
+
+      def detect
+        return :moxml if RUBY_ENGINE == "opal"
+
+        :nokogiri
       end
     end
   end

data/lib/canon/xml_parsing.rb

@@ -3,18 +3,35 @@
 module Canon
   # Backend-agnostic XML parsing, serialization, and type dispatch.
   #
-  # Provides a unified API that delegates to the active backend
-  # (Nokogiri or moxml/Oga). Uses backend-branching (`if XmlBackend.nokogiri?`)
-  # rather than `case/when` with constant references — this ensures Nokogiri
-  # constants are never resolved under Opal, preventing NameError at runtime.
+  # Responsibilities (MECE):
+  # - Engine actions: `parse` selects the XML engine chosen by
+  #   Canon::XmlBackend (raw Nokogiri or moxml with its resolved adapter —
+  #   leptris when installed, nokogiri otherwise).
+  # - Node type dispatch: type queries and traversal answer for ANY
+  #   recognized node (Nokogiri or moxml) regardless of the active engine —
+  #   callers may hand us nodes from either library (user input, format
+  #   detection). Dispatch is by node type, never by backend.
   #
-  # OCP: adding a new backend only requires updating this module.
-  # DRY: all backend dispatch centralized here, not scattered across
-  # comparator/formatter files.
+  # `defined?(Nokogiri)` guards keep Nokogiri constants unresolved under
+  # Opal (no NameError at runtime).
+  #
+  # OCP: adding a new engine means extending Canon::XmlBackend detection
+  # plus the node-type union here; all comparator/formatter code stays
+  # untouched because it goes through this module.
   module XmlParsing
     class << self
       def moxml_context
-        @moxml_context ||= Moxml.new(RUBY_ENGINE == "opal" ? :rexml : :oga)
+        # Opal needs the explicit rexml adapter: stock oga requires its
+        # C extension there. CRuby defers to moxml's preferred adapter
+        # (leptris when installed and capable, nokogiri otherwise).
+        @moxml_context ||= Moxml.new(RUBY_ENGINE == "opal" ? :rexml : nil)
+      end
+
+      # The adapter moxml resolved on this runtime. This is the single
+      # source of truth for engine capability: moxml owns the preference
+      # order, canon never probes gems itself.
+      def moxml_adapter_name
+        moxml_context.config.adapter_name
       end
 
       # --- Parsing ---
@@ -31,7 +48,7 @@ module Canon
         if XmlBackend.nokogiri?
           Nokogiri::XML.fragment(xml_string).children.to_a
         else
-          doc = moxml_context.parse("<__frag__>#{xml_string}</__frag__>")
+          doc = moxml_context.parse("<__frag__>#{xml_string}</__frag__>", readonly: true)
           doc.root.children.to_a
         end
       end
@@ -39,113 +56,88 @@ module Canon
       # --- Serialization ---
 
       def serialize(node)
-        if XmlBackend.nokogiri?
-          nokogiri_serialize(node)
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Document)
+          node.to_xml(encoding: "UTF-8")
         else
-          moxml_serialize(node)
+          node.to_xml
         end
       end
 
-      # --- Type checks (backend-safe) ---
-      #
-      # Both Nokogiri and Moxml are loaded as dependencies. XmlBackend
-      # determines which is used for *parsing*, but nodes from either
-      # library may flow through comparison code (e.g. tests, format
-      # detection). Under Nokogiri backend, both types are checked.
+      # --- Type checks (any recognized engine node) ---
 
       def document?(obj)
-        if XmlBackend.nokogiri?
-          obj.is_a?(Nokogiri::XML::Document) || obj.is_a?(Moxml::Document)
-        else
-          obj.is_a?(Moxml::Document)
-        end
+        return true if defined?(Nokogiri) && obj.is_a?(Nokogiri::XML::Document)
+
+        obj.is_a?(Moxml::Document)
       end
 
       def xml_node?(obj)
-        if XmlBackend.nokogiri?
-          obj.is_a?(Nokogiri::XML::Node) || obj.is_a?(Moxml::Node)
-        else
-          obj.is_a?(Moxml::Node)
-        end
+        return true if defined?(Nokogiri) && obj.is_a?(Nokogiri::XML::Node)
+
+        obj.is_a?(Moxml::Node)
       end
 
       def element?(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Element) || node.is_a?(Moxml::Element)
-        else
-          node.is_a?(Moxml::Element)
-        end
+        return true if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Element)
+
+        node.is_a?(Moxml::Element)
       end
 
       def text_node?(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Text) || node.is_a?(Moxml::Text)
-        else
-          node.is_a?(Moxml::Text)
-        end
+        return true if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Text)
+
+        node.is_a?(Moxml::Text)
       end
 
       def comment?(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Comment) || node.is_a?(Moxml::Comment)
-        else
-          node.is_a?(Moxml::Comment)
-        end
+        return true if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Comment)
+
+        node.is_a?(Moxml::Comment)
       end
 
       def cdata?(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::CDATA) || node.is_a?(Moxml::Cdata)
-        else
-          node.is_a?(Moxml::Cdata)
-        end
+        return true if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::CDATA)
+
+        node.is_a?(Moxml::Cdata)
       end
 
       def processing_instruction?(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::ProcessingInstruction) || node.is_a?(Moxml::ProcessingInstruction)
-        else
-          node.is_a?(Moxml::ProcessingInstruction)
-        end
+        return true if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::ProcessingInstruction)
+
+        node.is_a?(Moxml::ProcessingInstruction)
       end
 
       def document_fragment?(obj)
-        if XmlBackend.nokogiri?
-          obj.is_a?(Nokogiri::XML::DocumentFragment)
-        else
-          false
-        end
+        defined?(Nokogiri) && obj.is_a?(Nokogiri::XML::DocumentFragment)
       end
 
       def dtd?(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::DTD)
-        else
-          false
-        end
+        defined?(Nokogiri) && node.is_a?(Nokogiri::XML::DTD)
       end
 
       # --- Node traversal ---
 
       def children(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Node) ? node.children.to_a : []
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Node)
+          node.children.to_a
+        elsif node.is_a?(Moxml::Node)
+          node.children.to_a
         else
-          node.is_a?(Moxml::Node) ? node.children.to_a : []
+          []
         end
       end
 
       def name(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Node) ? node.name : nil
-        else
-          node.is_a?(Moxml::Node) ? node.name : nil
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Node)
+          node.name
+        elsif node.is_a?(Moxml::Node)
+          node.name
         end
       end
 
       def text_content(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Node) ? node.content : node.to_s
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Node)
+          node.content
         else
           case node
           when Moxml::Text, Moxml::Cdata, Moxml::Comment
@@ -159,26 +151,30 @@ module Canon
       end
 
       def attributes(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Element) ? node.attributes.values : []
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Element)
+          node.attributes.values
+        elsif node.is_a?(Moxml::Element)
+          node.attributes
         else
-          node.is_a?(Moxml::Element) ? node.attributes : []
+          []
         end
       end
 
       def attribute_value(node, attr_name)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Element) ? node[attr_name.to_s] : nil
-        else
-          node.is_a?(Moxml::Element) ? node[attr_name.to_s] : nil
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Element)
+          node[attr_name.to_s]
+        elsif node.is_a?(Moxml::Element)
+          node[attr_name.to_s]
         end
       end
 
       def namespace_definitions(node)
-        if XmlBackend.nokogiri?
-          node.is_a?(Nokogiri::XML::Element) ? node.namespace_definitions : []
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Element)
+          node.namespace_definitions
+        elsif node.is_a?(Moxml::Element)
+          node.namespace_definitions
         else
-          node.is_a?(Moxml::Element) ? node.namespace_definitions : []
+          []
         end
       end
 
@@ -191,34 +187,26 @@ module Canon
       end
 
       def namespace_uri(node)
-        if XmlBackend.nokogiri?
-          node.namespace&.href if node.is_a?(Nokogiri::XML::Element)
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Element)
+          node.namespace&.href
         elsif node.is_a?(Moxml::Element)
           node.namespace_uri
         end
       end
 
-      # Returns a symbol for all backends (:element, :text, :comment, etc.)
+      # Returns a symbol for all engines (:element, :text, :comment, etc.)
       # or nil for unrecognised nodes.
       def node_type(node)
-        if XmlBackend.nokogiri?
+        if defined?(Nokogiri) && node.is_a?(Nokogiri::XML::Node)
           nokogiri_node_type(node)
-        else
+        elsif node.is_a?(Moxml::Node)
           moxml_node_type(node)
         end
       end
 
-      def canonicalize(node, options = {})
-        if XmlBackend.nokogiri?
-          node.canonicalize(options)
-        else
-          moxml_canonicalize(node, options)
-        end
-      end
-
       private
 
-      # --- Nokogiri backend ---
+      # --- Nokogiri engine ---
 
       def nokogiri_type_map
         @nokogiri_type_map ||= {
@@ -235,8 +223,6 @@ module Canon
       end
 
       def nokogiri_node_type(node)
-        return nil unless node.is_a?(Nokogiri::XML::Node)
-
         nokogiri_type_map[node.node_type]
       end
 
@@ -246,26 +232,13 @@ module Canon
         doc
       end
 
-      def nokogiri_serialize(node)
-        if node.is_a?(Nokogiri::XML::Document)
-          node.to_xml(encoding: "UTF-8")
-        else
-          node.to_xml
-        end
-      end
-
-      # --- Moxml backend ---
+      # --- Moxml engine ---
 
+      # Readonly: canon only ever reads engine documents (conversion,
+      # serialization) — leptris memoizes reads on readonly documents,
+      # and mutation is refused loudly rather than silently corrupting.
       def moxml_parse(xml_string, _options)
-        moxml_context.parse(xml_string)
-      end
-
-      def moxml_serialize(node)
-        node.to_xml
-      end
-
-      def moxml_canonicalize(node, _options)
-        node.to_xml
+        moxml_context.parse(xml_string, readonly: true)
       end
 
       def moxml_node_type(node)

data/lib/canon.rb

@@ -1,23 +1,31 @@
 # frozen_string_literal: true
 
-require_relative "canon/version"
-require_relative "canon/errors"
-require_relative "canon/xml_backend"
-require_relative "canon/xml_parsing"
-require_relative "canon/config"
-require_relative "canon/data_model"
-require_relative "canon/html"
-require_relative "canon/formatters/xml_formatter"
-require_relative "canon/formatters/yaml_formatter"
-require_relative "canon/formatters/json_formatter"
-require_relative "canon/formatters/html_formatter"
-require_relative "canon/formatters/html4_formatter"
-require_relative "canon/formatters/html5_formatter"
-require_relative "canon/comparison"
+require "canon/version"
+require "canon/errors"
+require "nokogiri" unless RUBY_ENGINE == "opal"
+require "canon/xml_backend"
+require "canon/xml_parsing"
+require "canon/config"
+require "canon/data_model"
+require "canon/xml"
+require "canon/html"
+require "canon/formatters"
+require "canon/comparison"
+require "canon/diff"
+require "canon/tree_diff"
+require "canon/validators"
+require "canon/pretty_printer"
+require "canon/options"
+require "canon/commands"
 
-require_relative "canon/rspec_matchers" if defined?(RSpec.configure)
+require "canon/rspec_matchers" if defined?(RSpec.configure)
 
 module Canon
+  autoload :Cache, "canon/cache"
+  autoload :Cli, "canon/cli"
+  autoload :ColorDetector, "canon/color_detector"
+  autoload :DiffFormatter, "canon/diff_formatter"
+
   SUPPORTED_FORMATS = %i[xml yaml json html html4 html5 string].freeze
 
   # Format content based on the specified format type
@@ -36,7 +44,7 @@ module Canon
     get_formatter(format).parse(content)
   end
 
-  # rubocop:disable Metrics/MethodLength
+  # rubocop:disable-next Metrics/MethodLength
   def self.get_formatter(format)
     case format.to_sym
     when :xml
@@ -55,11 +63,12 @@ module Canon
       raise Error, "Unsupported format: #{format}"
     end
   end
-  # rubocop:enable Metrics/MethodLength
 
   # Define shorthand methods for each supported format
   # Creates parse_{format} and format_{format} methods
   SUPPORTED_FORMATS.each do |format|
+    next if format == :string # comparison-only format, no formatter
+
     define_singleton_method("parse_#{format}") do |content|
       parse(content, format)
     end

data/lib/tasks/benchmark_runner.rb

@@ -96,7 +96,11 @@ class BenchmarkRunner
     def self.env_info(ruby_version, platform)
       puts
       puts "  #{DIM}Environment:#{CLEAR}"
+      engine = Canon::XmlBackend.active
+      engine_info = "XML engine: #{engine}"
+      engine_info += " (forced)" unless ENV["CANON_XML_BACKEND"].to_s.empty?
       puts "  #{VL}  Ruby #{ruby_version} on #{platform}#{' ' * (60 - ruby_version.length - platform.length)}#{VL}"
+      puts "  #{VL}  #{engine_info}#{' ' * (60 - engine_info.length)}#{VL}"
       puts "  #{DIM}#{BL}#{HL * 76}#{BR}#{CLEAR}"
       puts
     end