canon 0.3.29 → 0.3.31

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff4b9d6b5a57176d2d382f7b0d730047161920dfb4cb4004b58d60bba9c0edab
-  data.tar.gz: ed8dfddca4d957fbc3fbb1e62dbd1b03032c661e82c06513304d2abcf4e288cc
+  metadata.gz: 7c7f349890b131b4280956b65c069369fee17b526db3ffacaa4560c3b3beb485
+  data.tar.gz: dc2179259f0a7212de6b6aaddd50e61a32fba4627d4b853d60e00172cb819c10
 SHA512:
-  metadata.gz: 778faacee321541b7d8ceef7c3497969080243acd01fc01bde3902deb68b7664e5ed966a230fc969766cfb32aefe76c81be9d7ae8a86d6b0f0ea870a6ed32cf1
-  data.tar.gz: a3a42291c8100b20362c273c34778abdb4f22eec057c616e54daa60b77e4272c9fe5742fa352874ffc1145c0800e89f6c00800d8938bfcf2af364cff9c71ba9f
+  metadata.gz: 6e3085a46f5ae85c542a419ae35b961529fc76d1f232d72f3599eb54b1f6588e0bbc9d8f1ffcdb6e31e61a5dcf4a3d8c884ddf0999f9a1f2062e22997640052a
+  data.tar.gz: 3573d0da07ad60bd4aac8a3e3ffb149d61c400a2708c10d8dcca9280abae0dc12ac7d442786fd12be62ea584345e67dd2807ca63bc598578a4013e9159cd0ad7

data/CLAUDE.md

@@ -143,6 +143,10 @@ Engine parity is complete through libleptris 1.9.8 / leptris-ruby 1.9.33 / moxml
 
 Engine A/B testing: `CANON_XML_BACKEND=nokogiri bundle exec rspec` (or `=moxml` to force leptris when it isn't the resolved default). The default suite must stay green under BOTH values; the only expected pendings are the upstream-tracked ones. The benchmark header (`rake performance:quick`) reports the active engine.
 
+### C14N Engines
+
+`Canon::Xml::C14n.canonicalize` stays on canon's Ruby C14N 1.1 processor by default. leptris' native C-side C14N 1.1 is ~50x faster on large documents and byte-identical on the main corpus, but diverges from the spec on edge cases (attribute ordering, prefix preservation, `>`/tab escaping, document-level PIs — leptris#1015, all pinned in `spec/canon/xml/c14n_engine_parity_spec.rb`). `CANON_C14N_BACKEND=leptris` opts in; when the parity gate runs clean the default flips. `canonicalize_subset` and `with_comments: true` always use the Ruby processor.
+
 ### YAML Engines
 
 `Canon::YamlBackend` selects the YAML engine: `:psych` (default) or `:yeptris` (FFI over libyeptris, the YAML counterpart of the leptris XML stack — `CANON_YAML_BACKEND=yeptris` opts in; the optional `yeptris` Gemfile group must be enabled). `Canon::YamlParsing` is the single gateway for string loads; `Canon::JsonParsing` mirrors it for JSON (the same yeptris engine serves both — `Yeptris::YAML.load` auto-detects JSON and routes to the native C-API materializer; JSON falls back to stdlib unless `YamlBackend.yeptris_native?`, since the FFI ladder is ~29x slower than the stdlib C extension). `YAML.dump` stays on Psych everywhere — canonical output bytes are canon's product and the writers differ. **JSON defaults to the strict yeptris surface whenever the native materializer is installed** (yeptris 0.1.13.4 ships platform gems — zero compilation, zero env; parity spec-pinned to `JSON.parse` upstream). The YAML default stays `:psych` until the yeptris Psych-parity gaps close (yeptris-ruby#30 sexagesimal scalars, #31 >64-bit integers — #29 empty documents was fixed in 0.1.12); `spec/canon/yaml_engine_parity_spec.rb` is the executable gate, with upstream-tracked cases pending. Never `require "yeptris/psych"` — it rebinds the global `::Psych` constant for the whole process; only the namespaced `Yeptris::YAML` API is used.

data/lib/canon/comparison/xml_comparator.rb

@@ -74,6 +74,25 @@ module Canon
           # Store resolved match options hash for use in comparison logic
           opts[:match_opts] = match_opts_hash
 
+          # FAST PATH: leptris Merkle digest — equal root-subtree
+          # digests plus identical document-level skeletons prove
+          # content identity (modulo whitespace-only text nodes and
+          # attribute order), which implies equivalence wherever
+          # canon's whitespace handling is the same symmetric
+          # parse-time strip. Callers whose whitespace semantics
+          # differ from that skip the gate: strict attribute order
+          # (invisible to the digest), user-configured whitespace
+          # element lists, xml:space documents (checked inside the
+          # gate), and verbose callers who need the report.
+          if !(opts[:verbose] ||
+                 match_opts_hash[:attribute_order] == :strict ||
+                 match_opts_hash[:preserve_whitespace_elements] ||
+                 match_opts_hash[:collapse_whitespace_elements] ||
+                 match_opts_hash[:strip_whitespace_elements]) &&
+              Xml::DigestGate.equal?(n1, n2)
+            return true
+          end
+
           # Create child_opts with resolved options
           child_opts = opts.merge(child_opts)
 

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.3.29"
+  VERSION = "0.3.31"
 end

data/lib/canon/xml/c14n.rb

@@ -10,6 +10,10 @@ module Canon
       # @param with_comments [Boolean] Include comments in canonical form
       # @return [String] Canonical form in UTF-8
       def self.canonicalize(xml, with_comments: false)
+        if (native = native_canonicalize(xml, with_comments))
+          return native
+        end
+
         # Build XPath data model
         root_node = DataModel.from_xml(xml)
 
@@ -18,6 +22,46 @@ module Canon
         processor.process(root_node)
       end
 
+      # leptris' C-side C14N 1.1 — ~50x faster than the Ruby processor
+      # but NOT yet byte-identical on canon's edge-case corpus
+      # (attribute ordering, `>` escaping, document-level PIs, one
+      # prefix case — leptris#1015; the parity spec pins
+      # each). Opt-in via CANON_C14N_BACKEND=leptris until those
+      # close; comments mode keeps the Ruby path regardless (the
+      # native seam exposes no with-comments form).
+      def self.native_canonicalize(xml, with_comments)
+        return nil if with_comments
+        return nil if RUBY_ENGINE == "opal"
+        return nil unless ENV["CANON_C14N_BACKEND"].to_s.casecmp("leptris").zero?
+        return nil unless Canon::XmlBackend.moxml? &&
+          Canon::XmlParsing.moxml_adapter_name == :leptris
+        return nil unless native_c14n_available?
+
+        doc = Canon::XmlParsing.moxml_context.parse(xml, readonly: true,
+                                                         strict: false)
+        begin
+          doc.native.canonicalize(::Leptris::XML::FFI::C14N_1_1, nil,
+                                  mode: ::Leptris::XML::FFI::C14N_MODE_CANONICAL)
+        ensure
+          doc.free
+        end
+      rescue StandardError
+        # Malformed inputs are the Ruby path's domain (recovery parse
+        # + parse_errors surfacing), not the native lane's.
+        nil
+      end
+
+      def self.native_c14n_available?
+        return @native_c14n_available unless @native_c14n_available.nil?
+
+        @native_c14n_available = defined?(::Leptris::XML::FFI::C14N_1_1) &&
+          ::Leptris::XML::FFI.constants.include?(:C14N_MODE_CANONICAL)
+      end
+
+      def self.reset_native_probe!
+        @native_c14n_available = nil
+      end
+
       # Canonicalize a document subset selected by XPath expression.
       #
       # Implements W3C C14N 1.1 subset canonicalization:

data/lib/canon/xml/digest_gate.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    # Document-level Merkle-digest equivalence gate over leptris'
+    # content-defined subtree digests (libleptris #869, leptris-ruby
+    # Node#digest since 1.9.144).
+    #
+    # Equal root digests prove the root subtrees carry identical
+    # content (whitespace-only nodes dropped), and every canon match
+    # behavior is a relaxation of content identity — so equal digests
+    # imply equivalence under any option combination EXCEPT the two
+    # restrictions that compare things the digest deliberately
+    # ignores (attribute order, comments). The caller excludes those;
+    # this module answers the digest question only.
+    #
+    # A digest miss costs two readonly engine parses (no field
+    # materialization, no canon tree) — a fraction of the comparison
+    # it precedes. Any parse failure answers false and lets the full
+    # pipeline surface the error.
+    module DigestGate
+      module_function
+
+      def available?
+        return false if RUBY_ENGINE == "opal"
+        return false unless Canon::XmlBackend.moxml? &&
+          Canon::XmlParsing.moxml_adapter_name == :leptris
+
+        # Node#digest is the 1.9.144 surface; feature-detect it on a
+        # throwaway document rather than probing the class.
+        doc = Canon::XmlParsing.moxml_context.parse("<r/>", readonly: true,
+                                                            strict: false)
+        root = doc.root
+        digestable = !root.native.digest(drop_ws: true).nil?
+        doc.free
+        digestable
+      rescue StandardError
+        false
+      end
+
+      # True when both documents' root subtrees digest identically
+      # AND their document-level skeletons (prolog/epilog comments and
+      # PIs — the only doc-level nodes canon compares; doctype and
+      # whitespace-only text are excluded) serialize identically.
+      # Anything else — parse failure, missing root, digest
+      # unavailable — is false: the caller falls through to the full
+      # pipeline, which surfaces the real parse errors.
+      def equal?(xml1, xml2)
+        return false unless xml1.is_a?(String) && xml2.is_a?(String)
+
+        begin
+          # xml:space documents carry attribute-scoped whitespace canon
+          # makes normative and the digest cannot see — decline them.
+          # The scan also declines non-ASCII-compatible encodings
+          # (include? raises) — those are the full pipeline's to
+          # normalize.
+          return false if xml1.include?("xml:space") || xml2.include?("xml:space")
+        rescue Encoding::CompatibilityError
+          return false
+        end
+
+        context = Canon::XmlParsing.moxml_context
+        begin
+          left = fingerprint(context, xml1)
+          right = fingerprint(context, xml2)
+          !left.nil? && left == right
+        rescue StandardError
+          # Any engine-level surprise (encodings, broken input) is the
+          # full pipeline's domain — it normalizes and surfaces errors.
+          false
+        end
+      end
+
+      # [root digest, doc-level skeleton] or nil when unparseable.
+      def fingerprint(context, xml)
+        doc = context.parse(xml, readonly: true, strict: false)
+        root = doc.root
+        return nil unless root
+
+        skeleton = doc.children.filter_map do |child|
+          next if child.equal?(root)
+
+          case child
+          when Moxml::Comment, Moxml::ProcessingInstruction then child.to_s
+          when Moxml::Text then child.content.strip.empty? ? nil : child.to_s
+          end
+        end
+        [root.native.digest(drop_ws: true), skeleton]
+      ensure
+        doc&.free
+      end
+    end
+  end
+end

data/lib/canon/xml.rb

@@ -16,6 +16,7 @@ module Canon
   module Xml
     autoload :AttributeHandler, "canon/xml/attribute_handler"
     autoload :C14n, "canon/xml/c14n"
+    autoload :DigestGate, "canon/xml/digest_gate"
     autoload :CharacterEncoder, "canon/xml/character_encoder"
     autoload :DataModel, "canon/xml/data_model"
     autoload :ElementMatcher, "canon/xml/element_matcher"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.29
+  version: 0.3.31
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -391,6 +391,7 @@ files:
 - lib/canon/xml/c14n.rb
 - lib/canon/xml/character_encoder.rb
 - lib/canon/xml/data_model.rb
+- lib/canon/xml/digest_gate.rb
 - lib/canon/xml/element_matcher.rb
 - lib/canon/xml/line_range_mapper.rb
 - lib/canon/xml/namespace_handler.rb