canon 0.3.67 → 0.3.69

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58c68ab8bd9ce6ae758ef8a9b2aeb69272dac07ef633e6d400dce01498e4a45a
-  data.tar.gz: d118362c2a39b59d6739c67623b31d8a957c093e8b280360be969643041b15f2
+  metadata.gz: 4f23fa758538acdbe352d58250d880b04e905191ce3c44b30528580cee06f224
+  data.tar.gz: c33b27f2839764f6d91fded3b3d7cb2042dc7e91d1d7a630037bcda0ce645c37
 SHA512:
-  metadata.gz: dc4582dc42ff629f85115a37e5456f6339ec7fe27f6e9b568fa6af1096d42c362aa5eb6bd767ceb40fb8f2e0f781cf642cfecd454631e34e937961e5c5b3ca45
-  data.tar.gz: d7c4b776c8720cd9c04bbc0b002d9a355ce23ea57668bb42df2bb7c3224a2a654776ff67ed8c0ad6b0c74a6173557ef650bb7a5f3f1178e042d379c8f833b6a6
+  metadata.gz: 6137233af91995ea5956d35fa154d2c206557e30c7fd9d1ced455667560f05810a034c4a1c407e4635fdbaefe8ad9929ad5b28cdf4cf5118990d83865611c4a3
+  data.tar.gz: 16a631574442c56fc87e5a48851643630ba9342d7e06f4b0b938f28a24792d5b414884099ec7c767fedb067971cc6ab82cf48871d55a1d1551f9cc5d7886e868

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/cache.rb

@@ -24,7 +24,14 @@ module Canon
       # Maximum number of entries per cache category
       MAX_CACHE_SIZE = 100
 
-      # Fetch a value from cache, or compute and cache it
+      LOCK = Mutex.new
+
+      # Fetch a value from cache, or compute and cache it.
+      #
+      # The lock covers the cache operations only — never the compute
+      # block — so concurrent parses stay parallel; duplicate computes
+      # for the same key may race (last write wins), which any
+      # check-then-compute cache accepts.
       #
       # @param category [Symbol] Cache category (:document_parse, :format_detect, etc.)
       # @param key [String] Cache key
@@ -33,24 +40,24 @@ module Canon
       def fetch(category, key)
         cache = cache_for(category)
 
-        # Check if key exists
-        if cache.key?(key)
-          # Update access time for LRU
-          cache[key][:accessed] = Time.now
-          return cache[key][:value]
+        LOCK.synchronize do
+          if cache.key?(key)
+            @clock = (@clock || 0) + 1
+            cache[key][:accessed] = @clock
+            return cache[key][:value]
+          end
         end
 
-        # Compute and cache the value
         value = yield
 
-        # Evict oldest entry if cache is full
-        if cache.size >= MAX_CACHE_SIZE
-          oldest_key = cache.min_by { |_, v| v[:accessed] }&.first
-          cache.delete(oldest_key) if oldest_key
+        LOCK.synchronize do
+          if cache.size >= MAX_CACHE_SIZE
+            oldest_key = cache.min_by { |_, v| v[:accessed] }&.first
+            cache.delete(oldest_key) if oldest_key
+          end
+          @clock = (@clock || 0) + 1
+          cache[key] = { value: value, accessed: @clock }
         end
-
-        @clock = (@clock || 0) + 1
-        cache[key] = { value: value, accessed: @clock }
         value
       end
 
@@ -58,8 +65,10 @@ module Canon
       #
       # Useful for tests or when memory needs to be freed
       def clear_all
-        @caches&.each_value(&:clear)
-        @caches = nil
+        LOCK.synchronize do
+          @caches&.each_value(&:clear)
+          @caches = nil
+        end
       end
 
       # Clear a specific cache category

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.69"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.67
+  version: 0.3.69
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-22 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs