canon 0.3.67 → 0.3.68

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58c68ab8bd9ce6ae758ef8a9b2aeb69272dac07ef633e6d400dce01498e4a45a
-  data.tar.gz: d118362c2a39b59d6739c67623b31d8a957c093e8b280360be969643041b15f2
+  metadata.gz: 590320aa865898c6342d5c96566e6313e678a6d6f31a4d1e9463a50c9f434052
+  data.tar.gz: 6daacd998c4d52ae54096bc91329cd48686d33b7942970313891f8d69edf2141
 SHA512:
-  metadata.gz: dc4582dc42ff629f85115a37e5456f6339ec7fe27f6e9b568fa6af1096d42c362aa5eb6bd767ceb40fb8f2e0f781cf642cfecd454631e34e937961e5c5b3ca45
-  data.tar.gz: d7c4b776c8720cd9c04bbc0b002d9a355ce23ea57668bb42df2bb7c3224a2a654776ff67ed8c0ad6b0c74a6173557ef650bb7a5f3f1178e042d379c8f833b6a6
+  metadata.gz: 5d9fe69844ee374debb42557852bdcfd3d8cd3cadb30d15f01c2e2b932ad7412339107996bb2c88f04669951b88752856c56b812d2fd4ecbd3f993390b682efe
+  data.tar.gz: bfee82458261d1b20f78d7745da3cf620ce9beff2a993c01edcf6ff1d22f2538e8ddf7c45f21237e64f41a0218d0a25432dffcf0ea6cbcff3443cd416d4a677b

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/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/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.67"
+  VERSION = "0.3.68"
 end

metadata

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