canon 0.3.53 → 0.3.55

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f9c6ba9a065bf2695019dc0a43595144a12233a9e37441ae3509a937fb43d2c
-  data.tar.gz: c7a8258f5f73a778c0f7b7d4104e02b0f7848e27892f1f63897b237675013d07
+  metadata.gz: 50a34a46b082f7aa0555199b09780ec1e8c5f38f76656e2a6899a54b3b96a90f
+  data.tar.gz: f2b7cbf27874cc6bbd6ab5615a14ad43a2ea6cb7e8ebdd9a3894efcc112c103c
 SHA512:
-  metadata.gz: 36afd9035a4078563855537f9af8aab3e0e53e22515a9d5f85ca47ffc5f3e564ab0507bd0013e45c234b5fe02d589d50f2e0a6e2a76df86b0d8fbeb33a37e105
-  data.tar.gz: 6341a23681ca3afc20ea888b440e0ccd01037979d6815dbdd2b010ed856bb03891c79c494698a5ddef7512da9613e5f480d3028dc9a9669fa356c23650f2600d
+  metadata.gz: 5474c6581c262c497d51cebfe91b0882a096a3340acfd7f7c77d67ca064d12164cbc423b6c4865138a80a660115755597672c3e7a1dbe380ddf24f94e8c55d0d
+  data.tar.gz: 8dac986a479c7820ec6d780c116d906ef34489cbfdf15f19ebad9f013c0ec90070ad75801471e4cd8e4be4f1e9c62faaeaa8b97d42a296286f1c0842ce9d8d9b

data/lib/canon/comparison/comparison_result.rb

@@ -5,12 +5,14 @@ module Canon
     # Encapsulates the result of a comparison operation
     # Provides methods to query equivalence based on normative diffs
     class ComparisonResult
-      attr_reader :differences, :preprocessed_strings, :format, :html_version,
-                  :match_options, :algorithm, :original_strings,
+      attr_reader :differences, :format, :html_version,
+                  :match_options, :algorithm,
                   :parse_errors_expected, :parse_errors_received
 
       # @param differences [Array<DiffNode>] Array of difference nodes
-      # @param preprocessed_strings [Array<String, String>] Pre-processed content for display
+      # @param preprocessed_strings [Array<String, String>, Proc] Pre-processed
+      #   content for display, or a Proc returning the Array (materialized on
+      #   first read)
       # @param format [Symbol] Format type (:xml, :html, :json, :yaml)
       # @param html_version [Symbol, nil] HTML version (:html4 or :html5) for HTML format only
       # @param match_options [Hash, nil] Resolved match options used for comparison
@@ -23,7 +25,7 @@ html_version: nil, match_options: nil, algorithm: :dom, original_strings: nil,
 parse_errors_expected: nil, parse_errors_received: nil)
         @differences = differences
         @preprocessed_strings = preprocessed_strings
-        @original_strings = original_strings || preprocessed_strings
+        @original_strings = original_strings
         @format = format
         @html_version = html_version
         @match_options = match_options
@@ -32,6 +34,28 @@ parse_errors_expected: nil, parse_errors_received: nil)
         @parse_errors_received = Array(parse_errors_received)
       end
 
+      # Display strings for the compared inputs. When the comparator
+      # supplied a builder Proc (the display strings require serializing
+      # both parsed documents), materialization is deferred to the first
+      # read: by_object consumers never pay it, by_line and preprocessed
+      # display trigger it exactly once.
+      #
+      # @return [Array<String, String>]
+      def preprocessed_strings
+        unless @preprocessed_strings.is_a?(Array)
+          @preprocessed_strings = @preprocessed_strings.call
+        end
+        @preprocessed_strings
+      end
+
+      # Unprocessed input strings; falls back to the preprocessed pair
+      # when the comparator did not provide originals.
+      #
+      # @return [Array<String, String>]
+      def original_strings
+        @original_strings || preprocessed_strings
+      end
+
       # Whether either side reported parse errors.  Used by the diff
       # formatter to decide whether to render the parse-error banner.
       #
@@ -147,8 +171,8 @@ show_diffs: :all, diff_mode: :separate, legacy_terminal: false)
         formatter.format(
           self,
           @format,
-          doc1: @preprocessed_strings[0],
-          doc2: @preprocessed_strings[1],
+          doc1: preprocessed_strings[0],
+          doc2: preprocessed_strings[1],
           html_version: @html_version,
         )
       end

data/lib/canon/comparison/html_comparator.rb

@@ -131,8 +131,10 @@ module Canon
           if opts[:verbose]
             ComparisonResult.new(
               differences: differences,
-              preprocessed_strings: [serialize_for_display(node1),
-                                     serialize_for_display(node2)],
+              preprocessed_strings: lambda do
+                [serialize_for_display(node1),
+                 serialize_for_display(node2)]
+              end,
               original_strings: [original_str1, original_str2],
               format: :html,
               html_version: html_version,

data/lib/canon/comparison/json_comparator.rb

@@ -44,12 +44,16 @@ module Canon
                                                         differences, "")
 
           if opts[:verbose]
-            json_str1 = obj1.is_a?(String) ? obj1 : JSON.pretty_generate(obj1)
-            json_str2 = obj2.is_a?(String) ? obj2 : JSON.pretty_generate(obj2)
+            preprocessed = lambda do
+              [
+                obj1.is_a?(String) ? obj1 : JSON.pretty_generate(obj1),
+                obj2.is_a?(String) ? obj2 : JSON.pretty_generate(obj2),
+              ]
+            end
 
             ComparisonResult.new(
               differences: differences,
-              preprocessed_strings: [json_str1, json_str2],
+              preprocessed_strings: preprocessed,
               format: :json,
               match_options: match_opts_hash,
             )

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
 
@@ -131,11 +146,14 @@ module Canon
 
           if opts[:verbose]
             # Serialize parsed nodes for consistent formatting
-            # This ensures both sides formatted identically, showing only real differences
-            preprocessed = [
-              serialize_node(node1).gsub("><", ">\n<"),
-              serialize_node(node2).gsub("><", ">\n<"),
-            ]
+            # This ensures both sides formatted identically, showing only real
+            # differences. Deferred: by_object consumers never read these.
+            # 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,
@@ -177,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
-          preserve_whitespace = true
-          node1 = parse_node(n1, :none,
-                             preserve_whitespace: preserve_whitespace)
-          node2 = parse_node(n2, :none,
-                             preserve_whitespace: preserve_whitespace)
-          preprocessed = [
-            serialize_node(node1).gsub("><", ">\n<"),
-            serialize_node(node2).gsub("><", ">\n<"),
-          ]
+          # Parse nodes for verbose display — deferred with the strings:
+          # nothing but the display pair ever reads them.
+          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/comparison/yaml_comparator.rb

@@ -69,13 +69,17 @@ module Canon
                                                         differences, "")
 
           if opts[:verbose]
-            # Format YAML for display
-            yaml_str1 = obj1.is_a?(String) ? obj1 : Canon::YamlParsing.dump(obj1)
-            yaml_str2 = obj2.is_a?(String) ? obj2 : Canon::YamlParsing.dump(obj2)
+            # Format YAML for display — deferred until first read
+            preprocessed = lambda do
+              [
+                obj1.is_a?(String) ? obj1 : Canon::YamlParsing.dump(obj1),
+                obj2.is_a?(String) ? obj2 : Canon::YamlParsing.dump(obj2),
+              ]
+            end
 
             ComparisonResult.new(
               differences: differences,
-              preprocessed_strings: [yaml_str1, yaml_str2],
+              preprocessed_strings: preprocessed,
               format: :yaml,
               match_options: match_opts_hash,
             )

data/lib/canon/comparison.rb

@@ -407,11 +407,11 @@ module Canon
 
         # CRITICAL: Use strategy's preprocess_for_display to ensure proper
         # line-breaking. This matches DOM diff preprocessing pattern
-        # (xml_comparator.rb:106-109).
+        # (xml_comparator.rb). Deferred via the lazy ComparisonResult seam:
+        # by_object consumers never pay the serialization.
         strategy = Comparison::Strategies::SemanticTreeMatchStrategy.new(
           format: format1, match_options: match_options_only,
         )
-        str1, str2 = strategy.preprocess_for_display(doc1, doc2)
 
         # Store tree diff data in match_options for access via result.
         enhanced_match_options = match_opts_hash.merge(
@@ -423,7 +423,7 @@ module Canon
         # Create ComparisonResult for unified handling.
         result = Canon::Comparison::ComparisonResult.new(
           differences: diff_nodes,
-          preprocessed_strings: [str1, str2],
+          preprocessed_strings: -> { strategy.preprocess_for_display(doc1, doc2) },
           original_strings: [original_str1, original_str2],
           format: format1,
           html_version: %i[html4 html5].include?(format1) ? format1 : nil,

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.3.53"
+  VERSION = "0.3.55"
 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,56 @@
+# 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
+
+        def cdata_block(_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.53
+  version: 0.3.55
 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