canon 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 615e3154c89a9850e86c39852201e5573b461ac62d52cc423523e444ace301f7
-  data.tar.gz: 37ee00969f0682dde670168fbd7888294edda612220bfbebb7c950efbcb76aa2
+  metadata.gz: 6437f1a8b556bb49bffbcecf47ec0eeecabdf6541bd5baa5954ac88f98f33a2c
+  data.tar.gz: 98eff2aa558165dc7e13c8d29da21d8d9c6589cae1d48a18d27f0420d6be7198
 SHA512:
-  metadata.gz: bce4239ab6a471edd896fd3b54def4e57e21714078cb3631b55363b50646349a6923eed1e208e5706c3319d3e7a2ae75f2db698ffe853c0e03a754d76c856679
-  data.tar.gz: 1441bd5412658d9d2b975e3889fc95bfd080dec2b89b731f71e191f5ca7bbc7e0a8aa63e787916781bd5e653732c16d5c03b0d3fc3b967a3b653a2a735e62636
+  metadata.gz: 055614c143bca292b575755f5b4a1554a002e0d6f264ddee3e29049f89d6f9795a61069c1bdf7ebfa459ed11ac2a21203a779e115f8aee143a2aa3c77951a086
+  data.tar.gz: ff64c25654c1eef41dcc80b471df2958c516e69fa625723bdecfd18c5a99716e7f347c313bf72c28f3b898547d5c97aac3ebb62bcf44e726bc49e668a73e0dd9

data/README.adoc

@@ -614,6 +614,10 @@ See link:docs/MODES[Diff modes] for details.
 * **Formatting diff detection**: Automatically detects and highlights purely cosmetic whitespace/line break differences
 * **Whitespace visualization**: Make invisible characters visible with CJK-safe
   Unicode symbols
+* **Whitespace adjacency reporting**: Stray whitespace-only text nodes are
+  reported as a dedicated `:whitespace_adjacency` dimension with direction
+  wording (`before`/`after`/`adjacent to`) instead of cascading into
+  misleading `:text_content` mismatches
 * **Non-ASCII detection**: Warnings for unexpected Unicode characters
 * **Customizable**: Character maps, context lines, grouping options
 

data/docs/advanced/diff-classification.adoc

@@ -266,6 +266,22 @@ match dimension but follows the same normative rule as all general dimensions:
   - Structural differences tracked but don't affect equivalence
   - Useful for content-only comparisons where wrapper elements don't matter
 
+==== Whitespace Adjacency
+
+`:whitespace_adjacency` is a derived dimension — emitted when the
+alignment walk pairs a whitespace-only text node on one side against a
+content node on the other. The Reason line describes the whitespace's
+direction relative to the partner content: `before`, `after`, or
+`adjacent to`.
+
+* **Always normative** — differences always affect equivalence
+* **Not user-configurable** — dimension is always tracked when the
+  re-alignment walk encounters an asymmetric whitespace node
+* **Report-only** — does not change equivalence outcomes compared to
+  pre-#137 behaviour; only changes the diff-report shape (see
+  link:../features/diff-formatting/whitespace-adjacency.adoc[Whitespace
+  adjacency] for details)
+
 .Example: Comment handling
 ====
 [source,ruby]

data/docs/features/diff-formatting/index.adoc

@@ -30,7 +30,9 @@ Canon's diff formatting includes:
   algorithms
 * **Whitespace adjacency**: Stray whitespace-only text nodes are anchored at
   themselves instead of cascading into mismatches against neighbouring
-  content (link:./whitespace-adjacency.adoc[details])
+  content. The Reason line names the direction relative to the partner
+  (`before`/`after`/`adjacent to`)
+  (link:./whitespace-adjacency.adoc[details])
 
 == Available formatting options
 

data/docs/features/diff-formatting/whitespace-adjacency.adoc

@@ -75,28 +75,104 @@ After the new contract, the cascade above collapses to:
 
 [source]
 ----
-DIFFERENCE #1 — whitespace_adjacency: Whitespace surrounding "20483":
+DIFFERENCE #1 — whitespace_adjacency: Whitespace before "20483":
                   present on EXPECTED ("↵░░"), absent on ACTUAL
-DIFFERENCE #2 — whitespace_adjacency: Whitespace surrounding ",":
+DIFFERENCE #2 — whitespace_adjacency: Whitespace before ",":
                   present on EXPECTED ("↵░░"), absent on ACTUAL
 DIFFERENCE #3 — text_content: "↵░░,↵░░"  vs  ", "
 ----
 
-== Adjacency positions
+== Direction relative to the partner
 
-The Reason line names the adjacency position of the whitespace node
-relative to its non-whitespace siblings:
+The Reason line names the document-order position of the whitespace
+node relative to the *partner content node* it was zipped against by
+the alignment walk. The partner is the next (or, at parent edge,
+previous) non-whitespace sibling on the whitespace-bearing side, which
+is what aligns against the corresponding content node on the other
+side.
 
-`:preceding`::  Whitespace at the start of its parent (no non-whitespace
-sibling before it, has one after it).
+`before`::  The whitespace immediately precedes its next non-whitespace
+sibling. This is the common case (e.g. indentation between two inline
+spans where the asymmetric whitespace sits on the leading edge of the
+partner).
 
-`:following`::  Whitespace at the end of its parent (has a non-whitespace
-sibling before it, none after).
+`after`::  The whitespace trails the previous non-whitespace sibling
+and has no non-whitespace sibling after it. Emitted at the trailing
+edge of a parent.
 
-`:surrounding`::  Sandwiched between two non-whitespace siblings.
+`adjacent to`::  Degenerate fallback for a whitespace node with no
+non-whitespace siblings at all. Rarely emitted.
 
-`:isolated`::  No non-whitespace siblings at all (degenerate; rarely
-emitted).
+NOTE: An earlier wording (`Whitespace surrounding "X"`) classified the
+*whitespace node's position among its own siblings* rather than its
+direction relative to the partner. That label was misleading when the
+whitespace sat between two element siblings but the asymmetry was
+one-sided — see issue #137 follow-up.
+
+=== Examples
+
+==== "before" — whitespace between inline element siblings
+
+[source,ruby]
+----
+html1 = "<a><span>ISO </span>\n   <span>712</span></a>"
+html2 = "<a><span>ISO </span><span>712</span></a>"
+
+result = Canon::Comparison.equivalent?(html1, html2,
+  format: :html5, verbose: true)
+# => #<ComparisonResult equivalent=false>
+
+# The stray "\n   " between two spans is the only asymmetric node.
+# It sits immediately before <span>712</span>, its next non-ws sibling.
+result.differences.first.reason
+# => "Whitespace before \"712\": present on EXPECTED (\"░\"), absent on ACTUAL"
+----
+
+==== "after" — trailing whitespace in a whitespace-preserving element
+
+[source,ruby]
+----
+# <code> preserves whitespace, so the trailing newline survives the
+# upstream filter and pairs against the extra <b>B</b> on the other side.
+html1 = "<code><b>A</b>\n</code>"
+html2 = "<code><b>A</b><b>B</b></code>"
+
+result = Canon::Comparison.equivalent?(html1, html2,
+  format: :html5, verbose: true)
+result.differences.first.reason
+# => "Whitespace after \"B\": present on EXPECTED (\"↵\"), absent on ACTUAL"
+----
+
+==== "adjacent to" — sole-child whitespace node
+
+[source,ruby]
+----
+# A whitespace-only text node as the only child of <code>, paired
+# against an element on the other side.  No non-ws siblings exist.
+html1 = "<code>\n</code>"
+html2 = "<code><b>A</b></code>"
+
+result = Canon::Comparison.equivalent?(html1, html2,
+  format: :html5, verbose: true)
+result.differences.first.reason
+# => "Whitespace adjacent to \"A\": present on EXPECTED (\"↵\"), absent on ACTUAL"
+----
+
+== Working with :whitespace_adjacency diffs programmatically
+
+Use the `dimension` field on `DiffNode` to filter:
+
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(html1, html2,
+  format: :html5, verbose: true)
+
+# Find all whitespace-adjacency diffs
+ws_diffs = result.differences.select { |d| d.dimension == :whitespace_adjacency }
+
+# These are always normative — they affect the equivalence verdict
+ws_diffs.all?(&:normative?)  # => true
+----
 
 == What this contract does NOT do
 
@@ -137,4 +213,6 @@ whitespace node as a single normative `:whitespace_adjacency` diff.
 
 The cascade behaviour was reported in
 https://github.com/lutaml/canon/issues/137[issue #137]. The fix landed
-as a report-only re-alignment in PR #138.
+as a report-only re-alignment in PR #138. PR #141 replaced the
+misleading `:surrounding`/`:preceding`/`:following` position labels
+with direction-faithful wording (`before`/`after`/`adjacent to`).

data/lib/canon/comparison/xml_comparator.rb

@@ -873,36 +873,39 @@ differences)
             return build_text_diff_reason(text1, text2)
           end
 
-          position = whitespace_adjacency_position(ws_node)
+          direction = whitespace_partner_direction(ws_node)
           ws_vis = visualize_whitespace(ws_text)
           content_vis = content_text ? visualize_whitespace(truncate_text(content_text)) : "(none)"
 
-          "Whitespace #{position} \"#{content_vis}\": " \
+          "Whitespace #{direction} \"#{content_vis}\": " \
             "present on #{present_side} (\"#{ws_vis}\"), absent on #{absent_side}"
         end
 
-        def whitespace_adjacency_position(ws_node)
-          return :isolated unless ws_node.is_a?(Canon::Xml::Node) ||
+        # Direction of the partner content relative to the whitespace node,
+        # phrased from the partner's point of view: "before" when the
+        # whitespace immediately precedes its next non-whitespace sibling
+        # (the alignment partner on the other side), "after" when the
+        # whitespace trails the previous non-whitespace sibling, or
+        # "adjacent to" as a degenerate fallback when neither neighbour
+        # exists.
+        def whitespace_partner_direction(ws_node)
+          return "adjacent to" unless ws_node.is_a?(Canon::Xml::Node) ||
             ws_node.is_a?(Nokogiri::XML::Node)
 
           parent = ws_node.parent
-          return :isolated if parent.nil?
+          return "adjacent to" if parent.nil?
 
           siblings = parent.children
           idx = siblings.index(ws_node)
-          return :isolated unless idx
+          return "adjacent to" unless idx
 
-          before = sibling_with_content?(siblings, idx, -1)
-          after = sibling_with_content?(siblings, idx, 1)
-
-          if before && after then :surrounding
-          elsif before then :following
-          elsif after then :preceding
-          else :isolated
+          if non_ws_sibling_exists?(siblings, idx, 1) then "before"
+          elsif non_ws_sibling_exists?(siblings, idx, -1) then "after"
+          else "adjacent to"
           end
         end
 
-        def sibling_with_content?(siblings, idx, direction)
+        def non_ws_sibling_exists?(siblings, idx, direction)
           i = idx + direction
           while i >= 0 && i < siblings.length
             s = siblings[i]

data/lib/canon/version.rb

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

metadata

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