canon 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfa3648b7c5308716c22fbdc377d875dc60d479eb0e376cfe347eb02a279d3d7
-  data.tar.gz: 87024447cc6a13eaa8cb9d1edf91d360e35d2e6cb5a1f2b7035c067050fae24a
+  metadata.gz: f2d050730d102cb224140f806e5b56634cdb98a16206301b0773d310dec582b9
+  data.tar.gz: 0b3bbf793abcfc9c3dd96a8c935260f4cf3360c7ee326e65ef8f165c48421f77
 SHA512:
-  metadata.gz: 6299802984ef5bab4c658c534105491f853c9d6cd297a5df49e5f8c83e0b36d1b01d140c1ea510002cf2916f3902035e764dcd589e4e01c5eec10c4ba76fda28
-  data.tar.gz: 42e73a1c3f80942d7ad102187b8a19148eb8a4046539eabb45561a716711fa3a51ea228e7bc372b4f675f4777db9ad964ed6c4873c19a5be9dc375af8639d92d
+  metadata.gz: 69b187c69b2aee23b1c1763504a33b226347ccbaaaab92d228d2a70da7d1f94f7160fb84b67356001de7de4e51155cc856104344fa795da8573ccf5e27af0633
+  data.tar.gz: 687fb81fbf5cafd49e8b1818e3dc641c44f62cf0f5d387829916ab270bdd4b9fffa56278e61d09f6bdabec52da1640ad59baf3c8d472d6248d1e0fce38209227

data/docs/advanced/diff-classification.adoc

@@ -253,6 +253,19 @@ result = Canon::Comparison.equivalent?(xml1, xml2)
   - Comment differences tracked but don't affect equivalence
   - Default for HTML (comments are presentational)
 
+==== Element Structure
+
+`element_structure` is a derived dimension — produced by comparators when children
+differ structurally (insertions, deletions, name changes). It is not a user-configurable
+match dimension but follows the same normative rule as all general dimensions:
+
+* **Default (no explicit behavior)** → Normative
+  - Structural differences (added/removed/renamed elements) affect equivalence
+
+* **`:ignore` behavior** → Informative
+  - Structural differences tracked but don't affect equivalence
+  - Useful for content-only comparisons where wrapper elements don't matter
+
 .Example: Comment handling
 ====
 [source,ruby]
@@ -405,6 +418,8 @@ The classification system uses three main classes:
   - `normative_dimension?(dimension)` - Is this dimension normative?
   - `affects_equivalence?(dimension)` - Does this dimension affect equivalence?
   - `supports_formatting_detection?(dimension)` - Can this dimension have formatting-only diffs?
+  - Normative rules: `structural_whitespace` requires `:strict` for normative status;
+    all other dimensions are normative unless behavior is `:ignore`
 
 * **`DiffClassifier`** - Orchestrates classification using the above
   - First checks `XmlSerializationFormatter` for serialization formatting

data/lib/canon/comparison/compare_profile.rb

@@ -51,12 +51,13 @@ module Canon
       #
       # This is used by DiffClassifier to determine the normative flag.
       #
+      # Normative rules by dimension:
+      # - structural_whitespace: only :strict is normative (:normalize and :ignore are informative)
+      # - all other dimensions: normative unless behavior is :ignore
+      #
       # @param dimension [Symbol] The match dimension to check
       # @return [Boolean] true if normative, false if informative
       def normative_dimension?(dimension)
-        # Element structure changes are ALWAYS normative
-        return true if dimension == :element_structure
-
         # Structural whitespace with :normalize or :ignore behavior is INFORMATIVE
         # Only :strict mode makes whitespace normative
         if dimension == :structural_whitespace
@@ -64,7 +65,7 @@ module Canon
           return behavior == :strict
         end
 
-        # For other dimensions, if behavior affects equivalence, it's normative
+        # For all other dimensions, normative if behavior affects equivalence
         affects_equivalence?(dimension)
       end
 

data/lib/canon/comparison/markup_comparator.rb

@@ -306,7 +306,11 @@ module Canon
           end
 
           # Default reason - can be overridden in subclasses
-          "#{diff1} vs #{diff2}"
+          if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
+            "element structure mismatch (children differ)"
+          else
+            "#{diff1} vs #{diff2}"
+          end
         end
 
         # Build a clear reason message for attribute presence differences

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

@@ -85,7 +85,11 @@ module Canon
         end
 
         # Default reason
-        "#{diff1} vs #{diff2}"
+        if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
+          "element structure mismatch (children differ)"
+        else
+          "#{diff1} vs #{diff2}"
+        end
       end
 
       # Enrich DiffNode with canonical path, serialized content, and attributes

data/lib/canon/comparison/xml_comparator.rb

@@ -631,7 +631,11 @@ differences)
             return "Attribute order changed: [#{attrs1.join(', ')}] → [#{attrs2.join(', ')}]"
           end
 
-          "#{diff1} vs #{diff2}"
+          if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
+            "element structure mismatch (children differ)"
+          else
+            "#{diff1} vs #{diff2}"
+          end
         end
 
         # Build a clear reason message for attribute value differences

data/lib/canon/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-16 00:00:00.000000000 Z
+date: 2026-04-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs