canon 0.3.66 → 0.3.68

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04a82e16556af6e2b31b4a137e5beef44d499df0d20a019f5406c9c127e94207
-  data.tar.gz: 998418423acb82ccca419c02b4f7c0abf6574e3ba9e370a9d463b51ae3409d76
+  metadata.gz: 590320aa865898c6342d5c96566e6313e678a6d6f31a4d1e9463a50c9f434052
+  data.tar.gz: 6daacd998c4d52ae54096bc91329cd48686d33b7942970313891f8d69edf2141
 SHA512:
-  metadata.gz: 259638f0ce661b7c766787071fa5b6174e3a0f2ca5d0b027375717e1f191315c44d10308819fd7d17ee019fde9d7418f01c8f13614c9c83154616ca4845c9eff
-  data.tar.gz: 47eca8ccd4000c0f22712818d8e72d7e7f4e37f5f523db0a59ff7441c119ff1ae5e29f4c5bef58c04831ee5b65e9bea7283c064bb4008a5732080cdb80f2ca9c
+  metadata.gz: 5d9fe69844ee374debb42557852bdcfd3d8cd3cadb30d15f01c2e2b932ad7412339107996bb2c88f04669951b88752856c56b812d2fd4ecbd3f993390b682efe
+  data.tar.gz: bfee82458261d1b20f78d7745da3cf620ce9beff2a993c01edcf6ff1d22f2538e8ddf7c45f21237e64f41a0218d0a25432dffcf0ea6cbcff3443cd416d4a677b

data/README.adoc

@@ -21,10 +21,9 @@ Key features:
    installed — Nokogiri otherwise and for HTML; both byte-compatible, engine
    parity is spec-gated
 ** JSON on https://github.com/leptris/yeptris[libyeptris]' strict JSON surface
-   whenever the native materializer is installed (`gem install yeptris` —
-   platform gems, zero compilation), the stdlib JSON extension otherwise
-** YAML on yeptris opt-in (`CANON_YAML_BACKEND=yeptris`, ~3x Psych loads);
-   Psych otherwise
+   (yeptris is a required gem — platform gems, zero compilation)
+** YAML on yeptris (default — byte-parity with Psych, gated by the dump
+   corpus in the suite); Psych via `CANON_YAML_BACKEND=psych`
 
 == When to use formatting vs comparison
 

data/docs/features/match-options/index.adoc

@@ -486,6 +486,33 @@ Canon::Comparison.equivalent?(html1, html2,
 
 `:strict`:: Namespace URIs must match (default and only supported behavior)
 
+=== namespace_prefix
+
+**Applies to**: XML only
+
+**Purpose**: Controls whether namespace *prefix spelling* is significant.
+Per XML Namespaces, the prefix is a binding convenience — `xmlns:ns="http://x.example"`
+and `xmlns:m="http://x.example"` bind to the same URI, so `<ns:e>` and `<m:e>` are the
+same `{uri}local` name. Documents that round-trip through XML tooling (Office,
+serializers) often churn prefixes; with `:ignore`, such documents compare
+equivalent as long as the *set of declared URIs* matches. Namespace
+declarations that resolve differently still report differences.
+
+**Behaviors**:
+
+`:significant`:: Prefix spelling matters — `xmlns:ns` and `xmlns:m` are
+different declarations (default; `strict` and `rendered` profiles)
+
+`:ignore`:: Only the set of declared namespace URIs matters
+(`spec_friendly` and `content_only` profiles)
+
+[source,ruby]
+----
+Canon::Comparison.equivalent?(xml1, xml2,
+  format: :xml,
+  match: { namespace_prefix: :ignore })
+----
+
 **Note**: This dimension is always `:strict` for XML. Namespace prefixes are not significant - only the namespace URI matters. Elements with different prefixes but the same namespace URI are considered equivalent.
 
 .Namespace URI comparison
@@ -601,6 +628,12 @@ Each format has sensible defaults based on typical usage:
 |—
 |`:strict`
 
+|`namespace_prefix`
+|`:significant`
+|`:significant`
+|—
+|—
+
 |`namespace_uri`
 |`:strict`
 |—

data/docs/guides/choosing-configuration.adoc

@@ -9,6 +9,29 @@ nav_order: 1
 
 Canon's 4-layer architecture provides powerful flexibility, but this can be overwhelming. This guide helps you choose the right configuration for your use case through decision trees, use case scenarios, and practical recommendations.
 
+== XML namespace prefixes
+
+If your documents round-trip through XML tooling (Office files, serializers,
+XSLT processors), namespace *prefixes* often churn while the resolved names
+stay identical (`xmlns:ns="http://x.example"` vs `xmlns:m="http://x.example"`). Canon's
+default treats prefix spelling as significant; choose `:ignore` when the
+binding, not the spelling, is what matters:
+
+[source,ruby]
+----
+# Per comparison
+Canon::Comparison.equivalent?(a, b,
+  format: :xml, match: { namespace_prefix: :ignore })
+
+# Or per suite via config
+Canon::Config.instance.xml.match.options[:namespace_prefix] = :ignore
+----
+
+The `spec_friendly` and `content_only` profiles already set
+`namespace_prefix: :ignore`. Canonicalization output (`Canon.format`,
+C14N) never rewrites prefixes regardless of this option — canonical bytes
+stay spec-conformant.
+
 == Quick Decision Tree
 
 [mermaid]

data/lib/canon/comparison/comparison_result.rb

@@ -56,6 +56,23 @@ parse_errors_expected: nil, parse_errors_received: nil)
         @original_strings || preprocessed_strings
       end
 
+      # The lazy display-string builder is a Proc, which Marshal (and
+      # every serializing test-distribution tool) cannot dump.
+      # Materialize first — the restored copy carries plain strings
+      # and round-trips exactly like the pre-lazy results.
+      def marshal_dump
+        preprocessed_strings
+        [@differences, @preprocessed_strings, @original_strings,
+         @format, @html_version, @match_options, @algorithm,
+         @parse_errors_expected, @parse_errors_received]
+      end
+
+      def marshal_load(data)
+        @differences, @preprocessed_strings, @original_strings,
+          @format, @html_version, @match_options, @algorithm,
+          @parse_errors_expected, @parse_errors_received = data
+      end
+
       # Whether either side reported parse errors.  Used by the diff
       # formatter to decide whether to render the parse-error banner.
       #

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

@@ -44,6 +44,10 @@ module Canon
                                     name: :comments,
                                     valid_behaviors: %i[strict ignore],
                                   ),
+                                  Dimension.new(
+                                    name: :namespace_prefix,
+                                    valid_behaviors: %i[significant ignore],
+                                  ),
                                 ]),
 
           json: DimensionSet.new(:json, [

data/lib/canon/comparison/match_options/xml_resolver.rb

@@ -23,6 +23,7 @@ module Canon
             element_position: :ignore,
             comments: :ignore,
             whitespace_type: :strict,
+            namespace_prefix: :significant,
           },
           xml: {
             preprocessing: :none,
@@ -34,6 +35,7 @@ module Canon
             element_position: :strict,
             comments: :strict,
             whitespace_type: :strict,
+            namespace_prefix: :significant,
           },
         }.freeze
 
@@ -49,6 +51,7 @@ module Canon
             element_position: :strict,
             comments: :strict,
             whitespace_type: :strict,
+            namespace_prefix: :significant,
           },
 
           rendered: {
@@ -56,11 +59,12 @@ module Canon
             text_content: :normalize,
             structural_whitespace: :normalize,
             attribute_presence: :strict,
-            attribute_order: :strict,
+            attribute_order: :ignore,
             attribute_values: :strict,
             element_position: :strict,
             comments: :ignore,
             whitespace_type: :strict,
+            namespace_prefix: :significant,
           },
 
           html4: {
@@ -97,6 +101,7 @@ module Canon
             element_position: :ignore,
             comments: :ignore,
             whitespace_type: :strict,
+            namespace_prefix: :ignore,
           },
 
           content_only: {
@@ -109,6 +114,7 @@ module Canon
             element_position: :ignore,
             comments: :ignore,
             whitespace_type: :strict,
+            namespace_prefix: :ignore,
           },
         }.freeze
 

data/lib/canon/comparison/xml_comparator/child_comparison.rb

@@ -122,6 +122,23 @@ module Canon
           end
 
           # Process ElementMatcher results
+          # Position differences carry element identity — a bare
+          # "position 0 vs position 1" next to identical-looking
+          # Expected/Actual payloads reads as a canon false positive
+          # when the real change is sibling order (e.g. id="1" and
+          # id="2" swapped).
+          def position_reason(elem, pos)
+            return "position #{pos}" if elem.nil?
+
+            label = elem.name.to_s
+            attrs = Canon::Diff::NodeSerializer.extract_attributes(elem)
+            return "position #{pos}" if attrs.nil? || attrs.empty?
+
+            id_like = %w[id href name].filter_map { |k| attrs[k] && "#{k}=#{attrs[k]}" }
+            id_like << attrs.first.then { |k, v| "#{k}=#{v}" } if id_like.empty?
+            "#{label}[#{id_like.first}] at position #{pos}"
+          end
+
           def process_matches(matches, _children1, _children2, _parent_node, comparator,
                              opts, child_opts, diff_children, differences)
             all_equivalent = true
@@ -137,7 +154,8 @@ module Canon
                   # Only create DiffNode if element_position is not :ignore
                   if position_behavior != :ignore
                     comparator.add_difference(match.elem1, match.elem2,
-                                              "position #{match.pos1}", "position #{match.pos2}",
+                                              position_reason(match.elem1, match.pos1),
+                                              position_reason(match.elem2, match.pos2),
                                               :element_position, opts, differences)
                     all_equivalent = false if position_behavior == :strict
                   end

data/lib/canon/comparison/xml_comparator/namespace_comparator.rb

@@ -20,6 +20,22 @@ module Canon
           # Most element pairs declare nothing — skip the set algebra.
           return Comparison::EQUIVALENT if ns_decls1.empty? && ns_decls2.empty?
 
+          # namespace_prefix: :ignore — prefix spelling is cosmetic;
+          # what resolves differently is the set of declared URIs
+          # (XML Namespaces: the prefix is a binding convenience, the
+          # {uri}local name is the name).
+          if opts[:match_opts][:namespace_prefix] == :ignore
+            uris1 = ns_decls1.values.uniq.sort
+            uris2 = ns_decls2.values.uniq.sort
+            return Comparison::EQUIVALENT if uris1 == uris2
+
+            missing = (ns_decls1.values.uniq - ns_decls2.values).sort
+            extra = (ns_decls2.values.uniq - ns_decls1.values).sort
+            add_namespace_uri_difference(node1, node2, missing, extra,
+                                         opts, differences)
+            return Comparison::UNEQUAL_ATTRIBUTES
+          end
+
           # Find missing, extra, and changed namespace declarations
           missing = ns_decls1.keys - ns_decls2.keys  # In node1 but not node2
           extra = ns_decls2.keys - ns_decls1.keys    # In node2 but not node1
@@ -125,6 +141,27 @@ module Canon
           Canon::Xml::NamespaceHelper.namespace_declaration?(attr_name)
         end
 
+        # URI-flavored difference for namespace_prefix: :ignore —
+        # reports the URIs that resolve differently, not the prefix
+        # spellings.
+        def self.add_namespace_uri_difference(node1, node2, missing, extra,
+                                              opts, differences)
+          reasons = []
+          reasons << "removed URIs: #{missing.join(', ')}" if missing.any?
+          reasons << "added URIs: #{extra.join(', ')}" if extra.any?
+
+          diff_node = Canon::Comparison::DiffNodeBuilder.build(
+            node1: node1,
+            node2: node2,
+            diff1: Comparison::UNEQUAL_ATTRIBUTES,
+            diff2: Comparison::UNEQUAL_ATTRIBUTES,
+            dimension: :namespace_declarations,
+            **opts,
+          )
+          diff_node.reason = reasons.join("; ") if diff_node && reasons.any?
+          differences << diff_node if diff_node
+        end
+
         # Add a namespace declaration difference
         #
         # @param node1 [Object] First node

data/lib/canon/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.66
+  version: 0.3.68
 platform: ruby
 authors:
 - Ribose Inc.