canon 0.3.54 → 0.3.56

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8094be0b06c7cd2a74e5e5fa4085f2a3ac654c54ed9ec106fcfa930490d4d11
-  data.tar.gz: 71c81085b65c0648b059a9d6a4d12663d71867b2f032f42e6ed95df2c38fcb26
+  metadata.gz: 13ed2f639e9860dac532ef7dfde80a21e76306a14282adabdf0923224c7cbacf
+  data.tar.gz: ebf4db9c33fce786057bd2cb47698deca9ee3f42e85fa76df5e7e0f9429e251c
 SHA512:
-  metadata.gz: 2a2401a1455182a4c4dc9b553fdbc51f6d63b4a9153ecf99f248bbf42fe43ac2f1ee801df0e22e52aebd1d4bfbecd0409e39d35e4fa02f440de7c674ccb44777
-  data.tar.gz: 894d3d399acd98b30c8dbd6da4fcce1915f12355347e5df6f77373c37fc7a9d7a2cfd21bbafbe53617d4ab6eb0e37a0820091ce61850554da25b5741a25945e1
+  metadata.gz: cec261c87059cd1b27874937a2b801c9d77bdcc05eb346c52dcfb0b3199ac4cc501cd46ae19b54133b491feab360b2eeffebfdd4e804eba112d7a250b0959883
+  data.tar.gz: 02b82fe957da9ec3b01bf669d28c8be0187adb1ab18ffb7b37f055d223d3bff4b1f14aec19f16e8b509d4cdd07414ecd1d5003916944c3f22186d5a3e17b329c

data/CLAUDE.md

@@ -128,7 +128,7 @@ The comparison pipeline flows through four independent layers:
 - `lib/canon/formatters/` — Pretty-printers for canonicalization/formatting (distinct from diff formatters). `XmlFormatter` supports Canonical XML (C14N).
 - `lib/canon/config.rb` — Global configuration with per-format settings (profiles, preprocessing, diff options). Read at runtime via `Canon::Config.instance`.
 - `lib/canon/rspec_matchers.rb` — RSpec matchers (`be_xml_equivalent_to`, `be_json_equivalent_to`, etc.). These delegate to `Canon::Comparison.equivalent?` with the global config. Automatically included in RSpec.
-- `lib/canon/xml/sax_builder.rb` — SAX-based canon-tree builder (~6x faster than DOM parsing for large documents). Engine-neutral; `lib/canon/xml/sax.rb` selects the driver (`NokogiriDriver` on CRuby, `MoxmlDriver` under Opal).
+- `lib/canon/xml/sax_builder.rb` — SAX-based canon-tree builder (~6x faster than DOM parsing for large documents). Engine-neutral; `lib/canon/xml/sax.rb` selects the driver following the resolved adapter (`MoxmlDriver` → leptris SAX under the leptris default, `NokogiriDriver` when the adapter is nokogiri, `MoxmlDriver` under Opal).
 
 ### XML Engines
 
@@ -137,9 +137,9 @@ Canon is engine-agnostic across three seams (MECE — one concern per module):
 - `Canon::XmlBackend` — XML engine selection. The default follows moxml's resolved adapter: **leptris whenever it is installed** (parse ~1.6x, serialize ~3.8x vs Nokogiri), raw Nokogiri otherwise (wrapping Nokogiri in moxml buys nothing — the wrapper adds 2-3x overhead). `:moxml` under Opal. `CANON_XML_BACKEND=nokogiri|moxml` forces either engine.
 - `Canon::XmlParsing` — the only place that talks to engines for XML parse/serialize (moxml parses pass `readonly: true` — canon never mutates engine documents); node type queries answer for ANY recognized node (Nokogiri or moxml) by type, never by active backend — user-supplied Nokogiri nodes keep working under the moxml engine.
 - `Canon::Html::NokogiriSupport` — HTML is always Nokogiri on CRuby (moxml has no HTML adapter, leptris no HTML parser); independent of the XML engine.
-- `Canon::Xml::Sax` — SAX driver selection: `NokogiriDriver` on CRuby (per-event C callbacks beat FFI SAX today), `MoxmlDriver` under Opal. The builder (`SaxBuilder`) is engine-neutral.
+- `Canon::Xml::Sax` — SAX driver selection follows the resolved adapter: `MoxmlDriver` (leptris SAX — the comparison hot path, CI-gated in the split flip) under the leptris default, `NokogiriDriver` when the resolved adapter is nokogiri, `MoxmlDriver` under Opal. The builder (`SaxBuilder`) is engine-neutral.
 
-Engine parity is complete through libleptris 1.9.8 / leptris-ruby 1.9.33 / moxml 0.5.12: attribute-value normalization, prolog/epilog PIs and comments, DTD ATTLIST defaults off by default (opt-in via `ParseOptions::DTDATTR`), PI-data whitespace matching libxml2, materialize with namespace declarations and a root-subtree-only record contract (moxml#140), readonly parse, deterministic `Document#free` (wired into `from_moxml_xml` — moxml#134). Canon's moxml conversion is record-based (`build_from_moxml` consumes `materialize` records — no per-node wrapper allocation; ~0.55x the Nokogiri conversion). `spec/canon/xml/engine_parity_spec.rb` is fully green. Remaining product gaps: moxml#129 (serializer byte parity — last blocker for pretty-printing on leptris) and leptris#594 (SAX at parity, not faster — the SAX driver stays Nokogiri). Pretty-printers (`PrettyPrinter::Xml`, `XmlNormalized`) deliberately stay on the Nokogiri pipeline — pretty-printed bytes are canon's product.
+Engine parity is complete through libleptris 1.9.8 / leptris-ruby 1.9.33 / moxml 0.5.12: attribute-value normalization, prolog/epilog PIs and comments, DTD ATTLIST defaults off by default (opt-in via `ParseOptions::DTDATTR`), PI-data whitespace matching libxml2, materialize with namespace declarations and a root-subtree-only record contract (moxml#140), readonly parse, deterministic `Document#free` (wired into `from_moxml_xml` — moxml#134). Canon's moxml conversion is record-based (`build_from_moxml` consumes `materialize` records — no per-node wrapper allocation; ~0.55x the Nokogiri conversion). `spec/canon/xml/engine_parity_spec.rb` is fully green. Pretty-printing runs the leptris serializer through `PrettyPrinter::Xml#moxml_format` (byte parity via moxml#153/#155/#156; the #167 escaping race fixed in 0.5.28), with Nokogiri serving the fallback engine and Opal — pretty-printed bytes are canon's product, gated by the fixture-integrity suite and the CI performance gate.
 
 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.
 

data/lib/canon/comparison/xml_comparator.rb

@@ -82,14 +82,29 @@ module Canon
           # 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 ||
+          # element lists, and xml:space documents (checked inside the
+          # gate). Attribute order is invisible to the digest, so
+          # :strict always falls through for the verdict itself.
+          # Verbose reports additionally carry two digest-invisible
+          # entries: informative attribute-order DiffNodes (emitted
+          # even under :ignore for order-differing documents) and the
+          # SAX lane's parse-error banner (issue #130). The verbose
+          # lane therefore re-scans both sides through the SAX probe —
+          # identical attribute-order signatures and no recover errors
+          # prove both entries empty, and a hit returns the same shape
+          # the pipeline builds for equivalent documents (empty
+          # differences, deferred display strings) without the two
+          # full parses and the walk.
+          if !(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)
+              Xml::DigestGate.certify(n1, n2) &&
+              verbose_report_proven_empty?(n1, n2, opts)
+            if opts[:verbose]
+              return build_digest_equivalent_result(n1, n2, match_opts_hash)
+            end
+
             return true
           end
 
@@ -133,12 +148,12 @@ module Canon
             # Serialize parsed nodes for consistent formatting
             # This ensures both sides formatted identically, showing only real
             # differences. Deferred: by_object consumers never read these.
-            preprocessed = lambda do
-              [
-                serialize_node(node1).gsub("><", ">\n<"),
-                serialize_node(node2).gsub("><", ">\n<"),
-              ]
-            end
+            # node1/node2 are parsed Canon nodes, so the deferred
+            # re-parse inside is a pass-through.
+            preprocessed = deferred_preprocessed(
+              node1, node2,
+              match_opts_hash[:preprocessing], preserve_whitespace
+            )
 
             ComparisonResult.new(
               differences: differences,
@@ -180,20 +195,71 @@ module Canon
         # @param n1 [Object] First input
         # @param n2 [Object] Second input
         # @param opts [Hash] Raw options (before merge with DEFAULT_OPTS)
+        # The verbose-report half of the gate: the digest cannot see
+        # attribute order (informative DiffNodes) or SAX recover
+        # errors (parse-error banner). One tree-free probe scan per
+        # side answers both; any hit falls through to the pipeline.
+        def verbose_report_proven_empty?(n1, n2, opts)
+          return true unless opts[:verbose]
+          # Identical input parses identically — differences and
+          # attribute order coincide by construction; only the SAX
+          # recover-error surface (parse-error banner, issue #130)
+          # needs its one scan.
+          return !Xml::Sax.probe(n1).saw_error? if n1 == n2
+
+          left = Xml::Sax.probe(n1)
+          return false if left.saw_error?
+
+          right = Xml::Sax.probe(n2)
+          !right.saw_error? && left.signature == right.signature
+        end
+
+        # Digest-proven equivalence for verbose callers. The report is
+        # indistinguishable from the full pipeline's for such inputs —
+        # certify guarantees no recover errors, the digest guarantees
+        # no differences — with display strings deferred exactly like
+        # the pipeline's lazy lane.
+        #
+        # @return [ComparisonResult]
+        def build_digest_equivalent_result(n1, n2, match_opts_hash)
+          preserve_whitespace = match_opts_hash[:structural_whitespace] == :strict
+          ComparisonResult.new(
+            differences: [],
+            preprocessed_strings: deferred_preprocessed(
+              n1, n2,
+              match_opts_hash[:preprocessing], preserve_whitespace
+            ),
+            original_strings: [n1, n2],
+            format: :xml,
+            match_options: match_opts_hash,
+            algorithm: :dom,
+          )
+        end
+
+        # Deferred display-string pair. Inputs may be raw strings
+        # (trivial/digest paths — parsed on materialization with the
+        # caller's preprocessing) or already-parsed Canon nodes
+        # (compare path — NodeParser passes them through unchanged).
+        #
+        # @return [Proc] Array<String, String> on call
+        def deferred_preprocessed(n1, n2, preprocessing, preserve_whitespace)
+          lambda do
+            [
+              serialize_node(parse_node(n1, preprocessing,
+                                        preserve_whitespace: preserve_whitespace)).gsub("><", ">\n<"),
+              serialize_node(parse_node(n2, preprocessing,
+                                        preserve_whitespace: preserve_whitespace)).gsub("><", ">\n<"),
+            ]
+          end
+        end
+
         # @return [Boolean, ComparisonResult]
         def build_trivial_equivalent_result(n1, n2, opts)
           return true unless opts[:verbose]
 
           # Parse nodes for verbose display — deferred with the strings:
           # nothing but the display pair ever reads them.
-          preprocessed = lambda do
-            [
-              serialize_node(parse_node(n1, :none,
-                                        preserve_whitespace: true)).gsub("><", ">\n<"),
-              serialize_node(parse_node(n2, :none,
-                                        preserve_whitespace: true)).gsub("><", ">\n<"),
-            ]
-          end
+          preprocessed = deferred_preprocessed(n1, n2, :none, true)
           original1 = n1.is_a?(String) ? n1 : serialize_node(n1)
           original2 = n2.is_a?(String) ? n2 : serialize_node(n2)
 

data/lib/canon/version.rb

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

data/lib/canon/xml/digest_gate.rb

@@ -71,11 +71,42 @@ module Canon
         end
       end
 
+      # The shared fingerprint ([root digest, doc-level skeleton])
+      # when both documents digest identically AND both parse clean of
+      # recover errors; nil otherwise. The verbose lane certifies
+      # before skipping the pipeline: error-bearing documents decline
+      # so the pipeline can produce the identical verbose report
+      # (parse-error banner included) it always has.
+      def certify(xml1, xml2)
+        return nil unless xml1.is_a?(String) && xml2.is_a?(String)
+
+        begin
+          return nil if xml1.include?("xml:space") || xml2.include?("xml:space")
+        rescue Encoding::CompatibilityError
+          return nil
+        end
+
+        context = Canon::XmlParsing.moxml_context
+        begin
+          left = fingerprint(context, xml1, clean: true)
+          right = fingerprint(context, xml2, clean: true)
+          return nil if left.nil? || left != right
+
+          left
+        rescue StandardError
+          nil
+        end
+      end
+
       # [root digest, doc-level skeleton] or nil when unparseable.
-      def fingerprint(context, xml)
+      # With `clean:` a document carrying recover errors also answers
+      # nil — only certify uses that; the boolean lane keeps the
+      # historical verdict for recovered-equal pairs.
+      def fingerprint(context, xml, clean: false)
         doc = context.parse(xml, readonly: true, strict: false)
         root = doc.root
         return nil unless root
+        return nil if clean && doc.parse_errors.any?
 
         skeleton = doc.children.filter_map do |child|
           next if Canon::XmlParsing.same_engine_node?(child, root)

data/lib/canon/xml/sax/probe.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    module Sax
+      # Tree-free scan stand-in for the builder protocol. Records
+      # recover errors and accumulates an attribute-name-order
+      # signature (element open/close tokens plus each non-xmlns
+      # attribute name in document order); content itself is ignored —
+      # the digest gate covers it. The verbose lane compares the two
+      # sides' signatures to prove the absence of the two
+      # digest-invisible report entries: informative attribute-order
+      # DiffNodes and the SAX-lane parse-error banner (issue #130).
+      class Probe
+        attr_reader :signature
+
+        def initialize
+          @saw_error = false
+          @signature = +""
+        end
+
+        def saw_error?
+          @saw_error
+        end
+
+        def error(_string)
+          @saw_error = true
+        end
+
+        def warning(_string); end
+
+        def start_element(name, attrs = [])
+          @signature << "/" << name << "\0"
+          attrs.each do |attr|
+            attr_name = attr[0].to_s
+            next if attr_name == "xmlns" || attr_name.start_with?("xmlns:")
+
+            @signature << "@" << attr_name << "\0"
+          end
+        end
+
+        def end_element(_name)
+          @signature << "\\"
+        end
+
+        def characters(_string); end
+
+        # The builder protocol the SAX drivers forward to is `cdata`
+        # (MoxmlDriver#on_cdata and NokogiriDriver#cdata_block both call
+        # builder.cdata); the nokogiri-style name here made every
+        # CDATA-bearing probe raise NoMethodError under the flipped
+        # leptris SAX engine.
+        def cdata(_string); end
+
+        def comment(_string); end
+
+        def processing_instruction(_name, _content); end
+      end
+    end
+  end
+end

data/lib/canon/xml/sax.rb

@@ -20,6 +20,7 @@ module Canon
     module Sax
       autoload :NokogiriDriver, "canon/xml/sax/nokogiri_driver"
       autoload :MoxmlDriver, "canon/xml/sax/moxml_driver"
+      autoload :Probe, "canon/xml/sax/probe"
 
       class << self
         # Drive `builder` with the runtime's SAX engine.
@@ -31,6 +32,19 @@ module Canon
           end
           nil
         end
+
+        # Tree-free scan through the runtime's SAX engine: answers
+        # recover errors and an attribute-name-order signature for
+        # `xml_string` without building anything.
+        def probe(xml_string)
+          probe = Probe.new
+          if RUBY_ENGINE == "opal" || Canon::XmlParsing.moxml_adapter_name != :nokogiri
+            MoxmlDriver.new(probe).parse(xml_string)
+          else
+            NokogiriDriver.new(probe).parse(xml_string)
+          end
+          probe
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.54
+  version: 0.3.56
 platform: ruby
 authors:
 - Ribose Inc.
@@ -437,6 +437,7 @@ files:
 - lib/canon/xml/sax.rb
 - lib/canon/xml/sax/moxml_driver.rb
 - lib/canon/xml/sax/nokogiri_driver.rb
+- lib/canon/xml/sax/probe.rb
 - lib/canon/xml/sax_builder.rb
 - lib/canon/xml/tree_builder.rb
 - lib/canon/xml/whitespace_normalizer.rb