canon 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10234a14be49f993f58acac6d82bb6e8ca409d309bcd8446296f32f60ad6380f
-  data.tar.gz: 80e29ddf981d17f0fcd5812921f6ec1fbdf056b3ae673dc4d3d94c9979cddc21
+  metadata.gz: f2d050730d102cb224140f806e5b56634cdb98a16206301b0773d310dec582b9
+  data.tar.gz: 0b3bbf793abcfc9c3dd96a8c935260f4cf3360c7ee326e65ef8f165c48421f77
 SHA512:
-  metadata.gz: bc63b5a8dae56a06781d8588809e8356eea618fdcdb13b933ea4c8a3c4f221201c05070a3ce100945c9f81ef6f122b73ff6ac723441aa2b3cbcc5fd31e8fee63
-  data.tar.gz: fbcb9ceb782f7847e6f2c6afba275f7d68da410d253b6f34f263b5c91803a3fbaff031de9b2dda5b8787fc37d0c82e1cea97d3ae1489d507eaad969168a107a1
+  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/docs/advanced/verbose-mode-architecture.adoc

@@ -130,10 +130,33 @@ Each difference displays:
 * **Status indicator**: `[NORMATIVE]` (green) or `[INFORMATIVE]` (yellow)
 * **Dimension**: Which aspect differs (colorized in magenta)
 * **Location**: XPath for XML/HTML, path for JSON/YAML (colorized in blue)
+* **Reason**: When the reason contains visualized whitespace characters (░),
+  it is split across two lines with the before and after text vertically
+  aligned for easier visual comparison:
++
+[source]
+----
+Reason:  Text: "░░term2░definition░░"
+          vs.: "░term2░definition░"
+----
++
+When no visualized whitespace is present, the reason remains a single line.
 * **Expected section**: What was in File 1 (red heading, bold)
 * **Actual section**: What was in File 2 (green heading, bold)
 * **Changes summary**: Actionable description of the difference (yellow, bold)
 
+When both the Expected and Actual values are short (under 30 characters), they
+are rendered as compact single lines with aligned colons for succinctness:
+
+[source]
+----
+⊖ Expected (File 1): "term2 definition"
+⊕ Actual (File 2)  : "term2 definition"
+----
+
+For longer values, they appear on separate lines with no blank line between
+them.
+
 === Dimension-specific formats
 
 ==== Attribute presence differences

data/docs/features/match-options/html-policies.adoc

@@ -226,6 +226,9 @@ Canon::Comparison.equivalent?(html1, html2, preprocessing: :rendered)
 Pretty-prints before comparison:
 - Consistent indentation
 - One element per line
+- Whitespace-only text nodes in strip-context elements (e.g. `<div>`) are
+  removed after formatting, so differences in structural whitespace between
+  elements do not produce false normative differences
 - Good for visual diffs
 
 [source,ruby]

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

@@ -393,12 +393,17 @@ module Canon
               end
             end
 
-            # For :rendered preprocessing with Nokogiri nodes
-            if preprocessing == :rendered
-              # Normalize and return
+            # For preprocessing modes that require whitespace filtering,
+            # apply the same post-parsing normalization used for string inputs.
+            # This is needed because dom_diff() pre-parses HTML5 strings into
+            # Nokogiri fragments before calling HtmlComparator, bypassing the
+            # string-input path where these filters are normally applied.
+            if %i[normalize format rendered].include?(preprocessing)
               frag = node.is_a?(Nokogiri::XML::DocumentFragment) ? node : Nokogiri::XML.fragment(node.to_html)
               normalize_html_style_script_comments(frag)
-              normalize_rendered_whitespace(frag, match_opts)
+              if preprocessing == :rendered
+                normalize_rendered_whitespace(frag, match_opts)
+              end
               remove_whitespace_only_text_nodes(frag)
               return frag
             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/diff_formatter/diff_detail_formatter.rb

@@ -14,6 +14,9 @@ module Canon
     # Formats dimension-specific detail for individual differences
     # Provides actionable, colorized output showing exactly what changed
     module DiffDetailFormatter
+      ANSI_ESCAPE = /\e\[[0-9;]*m/
+      COMPACT_DETAIL_MAX = 30
+
       class << self
         # Format all differences as a semantic diff report
         #
@@ -127,9 +130,7 @@ compact: false, expand_difference: false)
 
           # show reason if available
           if diff.respond_to?(:reason) && diff.reason
-            output << "#{colorize('Reason:', :cyan, use_color,
-                                  bold: true)}  #{colorize(diff.reason,
-                                                           :yellow, use_color)}"
+            format_reason_line(output, diff.reason, use_color)
           end
           output << ""
 
@@ -138,13 +139,7 @@ compact: false, expand_difference: false)
             diff, use_color, compact: compact, expand_difference: expand_difference
           )
 
-          output << colorize("⊖ Expected (File 1):", :red, use_color,
-                             bold: true)
-          output << "   #{detail1}"
-          output << ""
-          output << colorize("⊕ Actual (File 2):", :green, use_color,
-                             bold: true)
-          output << "   #{detail2}"
+          format_expected_actual(output, detail1, detail2, use_color)
 
           if changes && !changes.empty?
             output << ""
@@ -182,6 +177,52 @@ compact: false, expand_difference: false)
           colorize(error_msg, :red, use_color, bold: true)
         end
 
+        # Format the Reason line. When the reason contains visualized
+        # spaces (░), split into two vertically-aligned lines so the
+        # before/after text can be compared visually.
+        def format_reason_line(output, reason_text, use_color)
+          if reason_text.include?("\u2591") &&
+              reason_text.match?(/\A(Text|whitespace): .*\bvs\b/)
+            parts = reason_text.split(" vs ", 2)
+            if parts.length == 2
+              output << "#{colorize('Reason:', :cyan, use_color,
+                                    bold: true)}  #{colorize(parts[0],
+                                                             :yellow, use_color)}"
+              output << "#{' ' * 10}#{colorize("vs.: #{parts[1]}",
+                                               :yellow, use_color)}"
+              return
+            end
+          end
+          output << "#{colorize('Reason:', :cyan, use_color,
+                                bold: true)}  #{colorize(reason_text,
+                                                         :yellow, use_color)}"
+        end
+
+        # Format the Expected/Actual block. Short values (both under 30
+        # chars) are rendered as compact single lines with aligned colons;
+        # longer values use the multi-line layout without a blank line gap.
+        def format_expected_actual(output, detail1, detail2, use_color)
+          plain1 = detail1.gsub(ANSI_ESCAPE, "")
+          plain2 = detail2.gsub(ANSI_ESCAPE, "")
+
+          if plain1.length < COMPACT_DETAIL_MAX &&
+              plain2.length < COMPACT_DETAIL_MAX
+            lbl1 = colorize("\u2296 Expected (File 1)", :red, use_color,
+                            bold: true)
+            lbl2 = colorize("\u2295 Actual (File 2)  ", :green, use_color,
+                            bold: true)
+            output << "#{lbl1}: #{detail1}"
+            output << "#{lbl2}: #{detail2}"
+          else
+            output << colorize("\u2296 Expected (File 1):", :red, use_color,
+                               bold: true)
+            output << "   #{detail1}"
+            output << colorize("\u2295 Actual (File 2):", :green, use_color,
+                               bold: true)
+            output << "   #{detail2}"
+          end
+        end
+
         # Helper: Colorize text
         def colorize(text, color, use_color, bold: false)
           DiffDetailFormatterHelpers::ColorHelper.colorize(text, color,

data/lib/canon/version.rb

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

metadata

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