canon 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6437f1a8b556bb49bffbcecf47ec0eeecabdf6541bd5baa5954ac88f98f33a2c
-  data.tar.gz: 98eff2aa558165dc7e13c8d29da21d8d9c6589cae1d48a18d27f0420d6be7198
+  metadata.gz: b5218e18de7c596c5875ee1cf906331269cd58475a1f00de5c20af398bb07f08
+  data.tar.gz: 0dedd6f9e8ca265d37c610a183ed0e695ba68a9d8c9f0766b890f3d8db7d1f66
 SHA512:
-  metadata.gz: 055614c143bca292b575755f5b4a1554a002e0d6f264ddee3e29049f89d6f9795a61069c1bdf7ebfa459ed11ac2a21203a779e115f8aee143a2aa3c77951a086
-  data.tar.gz: ff64c25654c1eef41dcc80b471df2958c516e69fa625723bdecfd18c5a99716e7f347c313bf72c28f3b898547d5c97aac3ebb62bcf44e726bc49e668a73e0dd9
+  metadata.gz: c24944e5600684e24f4b32cd16d90d68f64ca07671da7cd30a4cc7e13e818e98f86ab849ee28f7780f40ae3514df1ba3087cb32f55c7923d5303c65819aa8d59
+  data.tar.gz: 13a3c944492c29a916569b86829cefd8bf7baaf247eea105ee3f608d25789ef7c79ab0b0a95a3806e66b85348dd629169f8e19bef127e3ca79685a0e13d1bca9

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-27 09:48:55 UTC using RuboCop version 1.86.0.
+# on 2026-05-05 13:09:45 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,52 +11,58 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 30
+# Offense count: 5
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'lib/canon/comparison/xml_comparator.rb'
-    - 'spec/canon/comparison/html4_html5_whitespace_parity_spec.rb'
+    - 'lib/canon/comparison/child_realignment.rb'
+    - 'lib/canon/comparison/xml_comparator/child_comparison.rb'
+    - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
 
-# Offense count: 1
+# Offense count: 5
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/text_utils.rb'
+    - 'spec/canon/comparison/comments_asymmetry_spec.rb'
+    - 'spec/canon/comparison/whitespace_adjacency_spec.rb'
 
-# Offense count: 1
+# Offense count: 5
 # This cop supports safe autocorrection (--autocorrect).
 Layout/BlockEndNewline:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/text_utils.rb'
+    - 'spec/canon/comparison/comments_asymmetry_spec.rb'
+    - 'spec/canon/comparison/whitespace_adjacency_spec.rb'
 
-# Offense count: 2
+# Offense count: 10
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
 # SupportedStylesAlignWith: start_of_line, relative_to_receiver
 Layout/IndentationWidth:
   Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter/text_utils.rb'
+    - 'spec/canon/comparison/comments_asymmetry_spec.rb'
+    - 'spec/canon/comparison/whitespace_adjacency_spec.rb'
 
-# Offense count: 1347
+# Offense count: 1386
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 2
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'lib/canon/comparison/xml_comparator.rb'
+    - 'lib/canon/comparison/child_realignment.rb'
+    - 'lib/canon/comparison/xml_comparator/child_comparison.rb'
+    - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
 
-# Offense count: 58
+# Offense count: 63
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
@@ -101,7 +107,7 @@ Lint/UselessConstantScoping:
   Exclude:
     - 'lib/canon/diff_formatter/theme.rb'
 
-# Offense count: 322
+# Offense count: 321
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -117,12 +123,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 281
+# Offense count: 285
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 517
+# Offense count: 529
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 146
@@ -132,7 +138,7 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 10
 
-# Offense count: 225
+# Offense count: 221
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -165,13 +171,13 @@ Performance/CollectionLiteralInLoop:
     - 'lib/canon/xml/xml_base_handler.rb'
     - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
 
-# Offense count: 85
+# Offense count: 107
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 43
+# Offense count: 46
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -182,7 +188,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 847
+# Offense count: 876
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 44
@@ -196,12 +202,6 @@ RSpec/ExpectActual:
     - 'spec/canon/rspec_matchers_spec.rb'
     - 'spec/canon/string_matcher_spec.rb'
 
-# Offense count: 7
-# This cop supports unsafe autocorrection (--autocorrect-all).
-RSpec/IncludeExamples:
-  Exclude:
-    - 'spec/canon/comparison/html4_html5_whitespace_parity_spec.rb'
-
 # Offense count: 177
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
@@ -240,7 +240,7 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 694
+# Offense count: 735
 RSpec/MultipleExpectations:
   Max: 15
 
@@ -249,7 +249,7 @@ RSpec/MultipleExpectations:
 RSpec/MultipleMemoizedHelpers:
   Max: 16
 
-# Offense count: 17
+# Offense count: 29
 # Configuration parameters: EnforcedStyle, IgnoreSharedExamples.
 # SupportedStyles: always, named_only
 RSpec/NamedSubject:
@@ -258,7 +258,7 @@ RSpec/NamedSubject:
     - 'spec/canon/pretty_printer/json_spec.rb'
     - 'spec/canon/pretty_printer/xml_spec.rb'
 
-# Offense count: 53
+# Offense count: 54
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
@@ -292,7 +292,7 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 134
+# Offense count: 100
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:
@@ -304,6 +304,18 @@ RSpec/VerifiedDoubles:
     - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
+# Offense count: 8
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/canon/comparison/comments_asymmetry_spec.rb'
+    - 'spec/canon/comparison/whitespace_adjacency_spec.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, AllowComments.

data/README.adoc

@@ -618,6 +618,11 @@ See link:docs/MODES[Diff modes] for details.
   reported as a dedicated `:whitespace_adjacency` dimension with direction
   wording (`before`/`after`/`adjacent to`) instead of cascading into
   misleading `:text_content` mismatches
+* **Asymmetric comment reporting**: A `<!-- ... -->` node present on only
+  one side is reported as a dedicated `:comments` dimension diff anchored
+  at the comment node, instead of shifting children alignment and
+  surfacing a misleading `:element_structure` "Element removed" diff
+  against an unrelated trailing sibling
 * **Non-ASCII detection**: Warnings for unexpected Unicode characters
 * **Customizable**: Character maps, context lines, grouping options
 

data/docs/advanced/semantic-diff-report.adoc

@@ -212,6 +212,8 @@ Reason:  Text: "¬······:¬······"
 
 This fallback is implemented in `Canon::DiffFormatter::DiffDetailFormatterHelpers::DimensionFormatter.format_text_content_details` and only triggers when `TextUtils.ambiguous_text_pair?` returns `true` _and_ at least one side has a parent element to render.
 
+The same fallback also applies to the `whitespace_adjacency` dimension (see <<whitespace-adjacency,Whitespace adjacency>>): when the alignment partner of a stray whitespace node extracts to an empty / whitespace-only string, the Reason line reads `Whitespace inside <PARENT>` (rather than `Whitespace before ""`), and the Expected/Actual block surfaces each side's parent element compactly. See `format_whitespace_adjacency_details` and `Canon::Comparison::XmlComparator#build_whitespace_adjacency_reason`.
+
 ==== One-sided text diffs (added or removed text nodes)
 
 When a `text_content` difference carries a text node on one side and `nil` on the other (issue #125) -- the shape that fragment-length mismatches and child-comparison emit when a text-node child is missing -- the renderer mirrors `element_structure`: the missing side reads `(not present)`, and the present side reads the text-node content (whitespace-visualised) plus a brief parent open-tag hint for context. The full ancestor subtree is *not* dumped; only the immediate parent's opening tag is shown, so a missing whitespace text node cannot make the diff look like the entire ancestor differs.

data/docs/features/diff-formatting/comment-asymmetry.adoc

@@ -0,0 +1,160 @@
+---
+title: Comment asymmetry in diff reports
+parent: Diff Formatting
+nav_order: 9
+---
+= Comment asymmetry in diff reports
+:toc:
+:toclevels: 2
+
+== Purpose
+
+Canon's diff reports anchor `<!-- ... -->` comment nodes that have no
+counterpart on the other side to a dedicated `:comments` dimension
+instead of letting the resulting children-array length mismatch cascade
+into a misleading `:element_structure` "Element removed" diff against
+the trailing named sibling.
+
+This is a *report-only* shape change — equivalence verdicts are
+unchanged. Whether asymmetric comments cause a non-equivalent verdict
+or not depends on the `comments` match option (`:strict` /
+`:ignore` / `:exact`), as before.
+
+== The problem
+
+Consider an HTML fragment compared with `verbose: true`:
+
+[source,html]
+----
+<!-- expected -->
+<body>
+  <div>first</div>
+  <div>second</div>
+  <!-- a comment that exists only on side A -->
+  <div style="mso-element:footnote-list"></div>
+</body>
+
+<!-- actual -->
+<body>
+  <div>first</div>
+  <div>second</div>
+  <div style="mso-element:footnote-list"></div>
+</body>
+----
+
+The `<div style="mso-element:footnote-list">` is byte-identical between
+the two sides; the only real difference is the comment on the expected
+side. Pre-#144, the diff report contained:
+
+[source]
+----
+DIFFERENCE #1 — element_structure: Element removed:
+                  <div style="mso-element:footnote-list"/>
+----
+
+That is the wrong dimension, anchored at the wrong node. The element is
+present on both sides — what is missing is the comment.
+
+The cascade comes from positional alignment in
+`Canon::Comparison::HtmlComparator#compare_fragment_children` (and the
+analogous walker in `XmlComparatorHelpers::ChildComparison`): in
+verbose mode, comments are intentionally kept by `filter_children` so
+informative differences can be recorded, but the resulting unequal
+children-array lengths fell through to a name-based mismatch heuristic
+that filtered out generic `#`-prefixed names (`#text`, `#comment`),
+leaving the trailing named element to take the blame.
+
+== The contract
+
+When the children alignment encounters a comment node on one side
+paired against a non-comment node on the other (or sitting past the
+trailing edge of the shorter side), Canon:
+
+1. Treats the comment as a *single-side gap* in the alignment.
+2. Emits one `:comments` diff entry anchored at the comment node
+   itself (not at a mis-paired neighbouring element).
+3. Advances only the cursor that carries the comment, so the next
+   iteration aligns content against content.
+
+The Reason line names the side that carries the comment and surfaces
+its text:
+
+[source]
+----
+DIFFERENCE #1 — comments: Comment present on EXPECTED only:
+                  <!-- a comment that exists only on side A -->
+----
+
+== Combined with whitespace asymmetry
+
+The same realignment walk handles asymmetric whitespace-only text
+nodes (link:whitespace-adjacency.adoc[issue #137]) and asymmetric
+comment nodes together. When a children mismatch is fully explained by
+a combination of asymmetric whitespace and asymmetric comments, the
+walker emits one diff per asymmetric node with the appropriate
+dimension (`:whitespace_adjacency` for whitespace, `:comments` for
+comments) — no `:element_structure` diff is produced.
+
+When a real structural mismatch coexists with an asymmetric comment,
+both kinds of diff are emitted — the structural one under
+`:element_structure`, the comment one under `:comments`.
+
+== Working with :comments diffs programmatically
+
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(html1, html2,
+  format: :html5, verbose: true)
+
+comment_diffs = result.differences.select { |d| d.dimension == :comments }
+
+# Whether these affect equivalence depends on the comments match option.
+# Under the default :ignore profile they are informative; under :strict
+# they are normative.
+----
+
+== What this contract does NOT do
+
+* **Does not silence asymmetric comments.** They are always reported
+  in verbose output; the change is the dimension label and the anchor
+  node.
+* **Does not affect symmetric comments.** When both sides carry
+  parallel comment nodes, those compare normally — content-vs-content
+  comparison applies.
+* **Does not change equivalence outcomes.** A comparison whose
+  equivalence verdict was driven by asymmetric comments retains the
+  same verdict; only the report shape changes.
+
+== Where it runs
+
+The noise-aware realignment is a single shared implementation:
+
+* `Canon::Comparison::ChildRealignment` — the two-cursor walk that
+  detects noise nodes via `NodeInspector.noise_dimension_for`,
+  emits per-orphan diffs with the appropriate dimension
+  (`:whitespace_adjacency`, `:comments`), and advances only the
+  noise-side cursor so content nodes stay aligned.
+
+Both comparison paths delegate to `ChildRealignment.walk`:
+
+* `Canon::Comparison::HtmlComparator#compare_fragment_children` — the
+  HTML fragment path (passes `emit_structural_orphans: true` because it
+  has no separate length-mismatch step).
+* `Canon::Comparison::XmlComparatorHelpers::ChildComparison` — the XML
+  comparator path (passes `emit_structural_orphans: false`; structural
+  orphans are handled by the pre-walk length-mismatch step via
+  `asymmetric_noise_explains_length_diff?`).
+
+== Related
+
+* link:whitespace-adjacency.adoc[Whitespace adjacency] — sibling
+  contract for asymmetric whitespace-only text nodes.
+* link:../../advanced/diff-classification.adoc[Diff classification] —
+  Normative vs informative differences.
+
+== History
+
+The false-positive cascade was reported in
+https://github.com/lutaml/canon/issues/144[issue #144]. The fix
+mirrors the structure of the `:whitespace_adjacency` work in
+https://github.com/lutaml/canon/issues/137[issue #137].

data/docs/features/diff-formatting/display-preprocessing.adoc

@@ -430,7 +430,7 @@ pretty-printer. This is a known future work item.
 |✓ Full
 |✓ (via XML serializer)
 |✓ Full
-|`:pretty_print` uses `Canon::PrettyPrinter::Html`; `:normalize_pretty_print` falls back to `XmlNormalized` pending a dedicated `HtmlNormalized`; `:c14n` uses Nokogiri HTML5 serialization
+|`:pretty_print` uses `Canon::PrettyPrinter::Html` in fixture-ready mode (`FORMAT|AS_XHTML|NO_DECLARATION`); `:normalize_pretty_print` falls back to `XmlNormalized` pending a dedicated `HtmlNormalized`; `:c14n` uses Nokogiri HTML5 serialization. In fixture-ready mode, stray structural whitespace (whitespace-only text nodes between block-level siblings) is stripped before formatting so that libxml's `FORMAT` flag produces correct indentation. Whitespace inside `<pre>`, `<script>`, `<style>`, and `<textarea>` is preserved.
 
 |JSON
 |Planned

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

@@ -103,6 +103,15 @@ edge of a parent.
 `adjacent to`::  Degenerate fallback for a whitespace node with no
 non-whitespace siblings at all. Rarely emitted.
 
+When the alignment partner extracts to an empty / whitespace-only
+string (e.g. an element with no text descendants), the direction
+phrasing degenerates to `Whitespace before ""` which carries no
+information. In that case Canon falls back to naming the parent
+element instead — `Whitespace inside <PARENT>` — and the
+Expected/Actual detail block renders each side's parent element
+compactly per the contract from
+link:../../advanced/semantic-diff-report.adoc#parent-context-fallback-for-ambiguous-text-diffs[issue #112].
+
 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

data/docs/interfaces/ruby-api/index.adoc

@@ -116,6 +116,9 @@ Where:
 `{Format}`:: The format module (`Xml`, `Html`, `Json`)
 `n`:: Number of spaces (default: 2) or tabs (use 1 for tabs)
 `type`:: Indentation type: `'space'` (default) or `'tab'`
+`fixture_ready`:: (HTML only) When `true`, emit indented XHTML-shaped
+output that strips structural whitespace before formatting. Designed for
+copy-paste into RSpec heredoc fixtures. Default: `false`.
 `content`:: The input string
 
 .Pretty-print examples
@@ -151,6 +154,23 @@ Canon::Xml::PrettyPrinter.new(
 html_input = '<div><p>Hello</p></div>'
 Canon::Html::PrettyPrinter.new(indent: 2).format(html_input)
 
+# HTML fixture-ready mode: produces indented XHTML-shaped output
+# suitable for pasting into RSpec heredoc fixtures.  Strips stray
+# structural whitespace (inter-element text nodes) so libxml's FORMAT
+# flag can indent block-level siblings that would otherwise be treated
+# as mixed content.  Whitespace inside <pre>, <script>, <style>, and
+# <textarea> is preserved.
+Canon::Html::PrettyPrinter.new(indent: 2, fixture_ready: true)
+  .format('<html><body><div>a</div> <div>b</div></body></html>')
+# =>
+# <html xmlns="http://www.w3.org/1999/xhtml">
+#   <head>...</head>
+#   <body>
+#     <div>a</div>
+#     <div>b</div>
+#   </body>
+# </html>
+
 # JSON with 2-space indentation
 json_input = '{"z":3,"a":{"b":1}}'
 Canon::Json::PrettyPrinter.new(indent: 2).format(json_input)

data/docs/understanding/formats/html.adoc

@@ -235,6 +235,23 @@ HTML whitespace is collapsed per CSS rendering rules. Empty text nodes between e
 Multiple spaces within text content are collapsed to single spaces when `text_content: :normalize` is used.
 ====
 
+==== Fixture-ready pretty-print and structural whitespace
+
+When using `Canon::PrettyPrinter::Html` with `fixture_ready: true` (the mode
+used by the diff pipeline's *PRETTY-PRINTED INPUTS* section), Canon strips
+stray structural whitespace before formatting.  Real-world HTML5 input from
+upstream pipelines often carries whitespace-only text nodes between block-level
+siblings (`<body>` → `<div>`, `<br>`, `<div>`, ...).  libxml's `FORMAT` flag
+treats any element with a non-whitespace-only text child as mixed content and
+refuses to indent its children — producing a single-line blob instead of a
+readable tree.
+
+The fixture-ready mode removes whitespace-only text nodes from parents that
+are purely structural (no real text content) and are not whitespace-preserving
+elements (`<pre>`, `<script>`, `<style>`, `<textarea>`).  Mixed-content runs
+like `<p>foo <em>bar</em> baz</p>` are left untouched so that significant
+inline whitespace is preserved.
+
 === Attribute order
 
 HTML attributes are inherently unordered per the HTML specification, so default is `:ignore`.

data/lib/canon/comparison/child_realignment.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "node_inspector"
+
+module Canon
+  module Comparison
+    # Shared two-cursor walk over child arrays with noise-aware realignment.
+    #
+    # When positional pairing would match a noise node (whitespace-only
+    # text or comment) against a content node, the walker treats the
+    # noise node as a single-side gap: emits a diff for it and advances
+    # only that cursor, so the next iteration aligns content against
+    # content.
+    #
+    # Noise classification is delegated to +NodeInspector.noise_dimension_for+,
+    # making the walk open for extension — new noise types only require
+    # adding a branch there.
+    #
+    # The walk is parameterised by a diff emitter (a callable that
+    # receives node1, node2, diff1, diff2, dimension) so both the HTML
+    # comparator (DiffNodeBuilder.build) and the XML comparator
+    # (comparator.add_difference) reuse the same cursor logic.
+    module ChildRealignment
+      class << self
+        # Walk two child arrays, emitting diffs for noise nodes and
+        # yielding matched content pairs.
+        #
+        # @param children1 [Array] Left-side children
+        # @param children2 [Array] Right-side children
+        # @param emitter [#call] Callable receiving
+        #   (node1, node2, diff1, diff2, dimension)
+        # @param emit_structural_orphans [Boolean] When true, trailing-edge
+        #   non-noise orphans are emitted as +:element_structure+ diffs.
+        #   HTML fragment path sets this to true (it has no separate
+        #   length-mismatch step); XML path sets it to false (structural
+        #   orphans are already recorded by +use_positional_comparison+).
+        # @yield [child1, child2] Compare two matched content nodes.
+        #   Must return a Comparison result constant.
+        # @return [Symbol] Worst comparison result encountered
+        def walk(children1, children2, emitter,
+                 emit_structural_orphans: false)
+          worst = Comparison::EQUIVALENT
+          i = 0
+          j = 0
+
+          while i < children1.length || j < children2.length
+            child1 = children1[i]
+            child2 = children2[j]
+
+            if child1.nil?
+              result = emit_orphan(child2, :right, emitter,
+                                   emit_structural_orphans)
+              worst = result if result && result != Comparison::EQUIVALENT
+              j += 1
+              next
+            elsif child2.nil?
+              result = emit_orphan(child1, :left, emitter,
+                                   emit_structural_orphans)
+              worst = result if result && result != Comparison::EQUIVALENT
+              i += 1
+              next
+            end
+
+            dim1 = NodeInspector.noise_dimension_for(child1)
+            dim2 = NodeInspector.noise_dimension_for(child2)
+
+            if dim1 && !dim2
+              result = emit_inline_noise(child1, child2, dim1, :left, emitter)
+              worst = result unless result == Comparison::EQUIVALENT
+              i += 1
+              next
+            elsif dim2 && !dim1
+              result = emit_inline_noise(child1, child2, dim2, :right, emitter)
+              worst = result unless result == Comparison::EQUIVALENT
+              j += 1
+              next
+            end
+
+            if block_given?
+              child_result = yield(child1, child2)
+              worst = child_result unless child_result == Comparison::EQUIVALENT
+            end
+            i += 1
+            j += 1
+          end
+
+          worst
+        end
+
+        private
+
+        # Emit a diff for an inline noise node that sits opposite a
+        # content node.  Whitespace passes both nodes for context;
+        # comments pass only the comment node.
+        def emit_inline_noise(node_left, node_right, dimension, noise_side,
+emitter)
+          if dimension == :whitespace_adjacency
+            emitter.call(node_left, node_right,
+                         Comparison::UNEQUAL_TEXT_CONTENTS,
+                         Comparison::UNEQUAL_TEXT_CONTENTS,
+                         dimension)
+            Comparison::UNEQUAL_TEXT_CONTENTS
+          else
+            n1 = noise_side == :left ? node_left : nil
+            n2 = noise_side == :right ? node_right : nil
+            emitter.call(n1, n2,
+                         Comparison::MISSING_NODE,
+                         Comparison::MISSING_NODE,
+                         dimension)
+            Comparison::UNEQUAL_ELEMENTS
+          end
+        end
+
+        # Emit a diff for a trailing-edge orphan (one side exhausted).
+        # Noise orphans are always emitted; structural orphans only when
+        # +emit_structural+ is true.
+        def emit_orphan(orphan, side, emitter, emit_structural)
+          dim = NodeInspector.noise_dimension_for(orphan)
+          if dim
+            n1 = side == :left ? orphan : nil
+            n2 = side == :right ? orphan : nil
+            emitter.call(n1, n2,
+                         Comparison::MISSING_NODE,
+                         Comparison::MISSING_NODE,
+                         dim)
+            Comparison::UNEQUAL_ELEMENTS
+          elsif emit_structural
+            n1 = side == :left ? orphan : nil
+            n2 = side == :right ? orphan : nil
+            emitter.call(n1, n2,
+                         Comparison::MISSING_NODE,
+                         Comparison::MISSING_NODE,
+                         :element_structure)
+            Comparison::UNEQUAL_ELEMENTS
+          end
+        end
+      end
+    end
+  end
+end

data/lib/canon/comparison/html_comparator.rb

@@ -188,32 +188,9 @@ module Canon
             node.is_a?(Nokogiri::HTML5::DocumentFragment)
         end
 
-        # Record a DiffNode for a fragment-level child-count mismatch.
-        # Each surplus child becomes its own MISSING_NODE diff so the
-        # downstream report shows what was added or removed.
-        def record_fragment_length_mismatch(_node1, _node2, children1,
-                                            children2, differences)
-          longer, shorter, side = if children1.length > children2.length
-                                    [children1, children2, :removed]
-                                  else
-                                    [children2, children1, :added]
-                                  end
-
-          longer[shorter.length...].each do |orphan|
-            n1 = side == :removed ? orphan : nil
-            n2 = side == :removed ? nil    : orphan
-            differences <<
-              Canon::Comparison::DiffNodeBuilder.build(
-                node1: n1,
-                node2: n2,
-                diff1: Comparison::MISSING_NODE,
-                diff2: Comparison::MISSING_NODE,
-                dimension: :element_structure,
-              )
-          end
-        end
-
-        # Compare children of document fragments
+        # Compare children of document fragments using the shared
+        # +ChildRealignment+ walk.  Structural orphans are emitted here
+        # (the HTML fragment path has no separate length-mismatch step).
         #
         # @param node1 [Nokogiri::DocumentFragment] First fragment
         # @param node2 [Nokogiri::DocumentFragment] Second fragment
@@ -230,29 +207,24 @@ module Canon
           children1 = XmlNodeComparison.filter_children(all_children1, opts)
           children2 = XmlNodeComparison.filter_children(all_children2, opts)
 
-          if children1.length != children2.length
-            # Record the length mismatch as a DiffNode so verbose mode
-            # surfaces it. Without this, equivalent? wraps an empty
-            # differences array and incorrectly reports the inputs as
-            # equivalent.
-            record_fragment_length_mismatch(node1, node2,
-                                            children1, children2,
-                                            differences)
-            return Comparison::UNEQUAL_ELEMENTS
-          elsif children1.empty?
-            return Comparison::EQUIVALENT
-          end
+          return Comparison::EQUIVALENT if children1.empty? && children2.empty?
 
-          # Compare each pair of children
-          children1.zip(children2).each do |child1, child2|
-            child_result = XmlNodeComparison.compare_nodes(child1, child2,
-                                                           opts, child_opts,
-                                                           diff_children,
-                                                           differences)
-            return child_result if child_result != Comparison::EQUIVALENT
+          emitter = html_diff_emitter(differences)
+          ChildRealignment.walk(children1, children2, emitter,
+                                emit_structural_orphans: true) do |c1, c2|
+            XmlNodeComparison.compare_nodes(c1, c2, opts, child_opts,
+                                            diff_children, differences)
           end
+        end
 
-          Comparison::EQUIVALENT
+        # Build a diff emitter for the HTML comparator path that
+        # creates DiffNode objects via DiffNodeBuilder.
+        def html_diff_emitter(differences)
+          proc do |n1, n2, d1, d2, dim|
+            differences << Canon::Comparison::DiffNodeBuilder.build(
+              node1: n1, node2: n2, diff1: d1, diff2: d2, dimension: dim,
+            )
+          end
         end
 
         # Perform semantic tree diff using SemanticTreeMatchStrategy

data/lib/canon/comparison/node_inspector.rb

@@ -83,6 +83,32 @@ module Canon
         end
       end
 
+      # Classify +node+ as a noise node and return the diff dimension
+      # it should be reported under, or +nil+ if it is structural content.
+      #
+      # Noise nodes (whitespace-only text, comments) are realigned past
+      # during child comparison so that content nodes line up correctly
+      # across sides.
+      #
+      # @param node [Object] DOM node to classify
+      # @return [Symbol, nil] +:whitespace_adjacency+, +:comments+, or +nil+
+      def self.noise_dimension_for(node)
+        if whitespace_only_text?(node)
+          :whitespace_adjacency
+        elsif comment_node?(node)
+          :comments
+        end
+      end
+
+      # True when +node+ is a noise node (whitespace-only text or comment).
+      # Convenience wrapper around +noise_dimension_for+.
+      #
+      # @param node [Object] DOM node to check
+      # @return [Boolean]
+      def self.noise_node?(node)
+        !noise_dimension_for(node).nil?
+      end
+
       # Extract parse-time errors carried on a node or its owning document.
       # Returns an Array of Strings.
       def self.parse_errors(node)
@@ -98,6 +124,15 @@ module Canon
           []
         end
       end
+
+      # Return the parent node of +node+, or nil when +node+ is not a
+      # recognised DOM backend type or has no parent.
+      def self.parent_of(node)
+        case node
+        when Canon::Xml::Node, Nokogiri::XML::Node
+          node.parent
+        end
+      end
     end
   end
 end

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

@@ -98,7 +98,7 @@ module Canon
             end
 
             # If no matches and children exist, they're all different
-            if matches.empty? && (!children1.empty? || !children2.empty?)
+            if matches.empty? && (!children1.empty? || children2.empty?)
               comparator.add_difference(parent_node, parent_node,
                                         Comparison::MISSING_NODE, Comparison::MISSING_NODE,
                                         :text_content, opts, differences)
@@ -156,13 +156,12 @@ module Canon
           end
 
           # Use simple positional comparison for children, with
-          # whitespace-asymmetry-aware re-alignment.  When positional
-          # +zip()+ would pair a whitespace-only text node on one side
-          # against a content node on the other, treat the whitespace
-          # node as a single-side gap: emit one +:whitespace_adjacency+
-          # diff anchored at the whitespace node and advance only the
-          # cursor carrying the whitespace, so the next iteration aligns
-          # content against content.  See lutaml/canon#137.
+          # noise-aware re-alignment via ChildRealignment. When the
+          # children arrays differ in length, a pre-walk step records
+          # structural orphans (or suppresses them when the length
+          # difference is fully explained by noise nodes). The shared
+          # walk then handles noise realignment and content comparison.
+          # See lutaml/canon#137 (whitespace) and #144 (comments).
           def use_positional_comparison(
             children1, children2, parent_node, comparator,
             opts, child_opts, diff_children, differences
@@ -173,11 +172,11 @@ module Canon
             unless children1.length == children2.length
               has_mismatch = true
 
-              ws_asymmetric = asymmetric_whitespace_explains_length_diff?(
+              noise_asymmetric = asymmetric_noise_explains_length_diff?(
                 children1, children2
               )
 
-              if ws_asymmetric
+              if noise_asymmetric
                 dimension = nil
                 mismatched_children = []
               else
@@ -191,7 +190,7 @@ module Canon
               end
 
               if mismatched_children.empty?
-                unless ws_asymmetric
+                unless noise_asymmetric
                   comparator.add_difference(parent_node, parent_node,
                                             Comparison::MISSING_NODE, Comparison::MISSING_NODE,
                                             dimension, opts, differences)
@@ -215,75 +214,31 @@ module Canon
             end
 
             result = has_mismatch ? Comparison::UNEQUAL_ELEMENTS : Comparison::EQUIVALENT
-            walk_result = walk_children_with_realignment(
-              children1, children2, comparator,
-              child_opts, diff_children, opts, differences
-            )
+
+            emitter = xml_diff_emitter(comparator, opts, differences)
+            walk_result = ChildRealignment.walk(children1, children2,
+                                                emitter) do |c1, c2|
+              comparator.compare_nodes(c1, c2, child_opts, child_opts,
+                                       diff_children, differences)
+            end
             result = walk_result unless walk_result == Comparison::EQUIVALENT
             result
           end
 
-          # Two-cursor walk over paired children that re-aligns past
-          # asymmetric whitespace-only text nodes.  Returns the worst
-          # child result encountered.
-          def walk_children_with_realignment(
-            children1, children2, comparator,
-            child_opts, diff_children, opts, differences
-          )
-            result = Comparison::EQUIVALENT
-            i = 0
-            j = 0
-
-            while i < children1.length || j < children2.length
-              c1 = children1[i]
-              c2 = children2[j]
-
-              if c1.nil?
-                j += 1
-                next
-              elsif c2.nil?
-                i += 1
-                next
-              end
-
-              ws1 = NodeInspector.whitespace_only_text?(c1)
-              ws2 = NodeInspector.whitespace_only_text?(c2)
-
-              if ws1 && !ws2
-                comparator.add_difference(c1, c2,
-                                          Comparison::UNEQUAL_TEXT_CONTENTS,
-                                          Comparison::UNEQUAL_TEXT_CONTENTS,
-                                          :whitespace_adjacency, opts, differences)
-                result = Comparison::UNEQUAL_TEXT_CONTENTS
-                i += 1
-                next
-              elsif ws2 && !ws1
-                comparator.add_difference(c1, c2,
-                                          Comparison::UNEQUAL_TEXT_CONTENTS,
-                                          Comparison::UNEQUAL_TEXT_CONTENTS,
-                                          :whitespace_adjacency, opts, differences)
-                result = Comparison::UNEQUAL_TEXT_CONTENTS
-                j += 1
-                next
-              end
-
-              child_result = comparator.compare_nodes(c1, c2,
-                                                      child_opts, child_opts,
-                                                      diff_children, differences)
-              result = child_result unless child_result == Comparison::EQUIVALENT
-              i += 1
-              j += 1
+          # Build a diff emitter for the XML comparator path that
+          # delegates to comparator.add_difference.
+          def xml_diff_emitter(comparator, opts, differences)
+            proc do |n1, n2, d1, d2, dim|
+              comparator.add_difference(n1, n2, d1, d2, dim, opts, differences)
             end
-
-            result
           end
 
-          # True when the length difference between the two child arrays
-          # is fully explained by asymmetric whitespace-only text nodes.
-          def asymmetric_whitespace_explains_length_diff?(children1, children2)
-            non_ws1 = children1.reject { |c| NodeInspector.whitespace_only_text?(c) }
-            non_ws2 = children2.reject { |c| NodeInspector.whitespace_only_text?(c) }
-            non_ws1.length == non_ws2.length
+          # True when the length difference is fully explained by
+          # asymmetric noise nodes (whitespace-only text and/or comments).
+          def asymmetric_noise_explains_length_diff?(children1, children2)
+            signal1 = children1.reject { |c| NodeInspector.noise_node?(c) }
+            signal2 = children2.reject { |c| NodeInspector.noise_node?(c) }
+            signal1.length == signal2.length
           end
 
           # Determine dimension for length mismatch

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

@@ -86,6 +86,14 @@ module Canon
           return "Attribute order changed: [#{attrs1.join(', ')}] → [#{attrs2.join(', ')}]"
         end
 
+        # For asymmetric comment nodes (#144), name the side that carries
+        # the comment and surface the comment text rather than reusing
+        # the generic "element structure mismatch" wording.
+        if dimension == :comments
+          comment_reason = build_comment_difference_reason(node1, node2)
+          return comment_reason if comment_reason
+        end
+
         # Default reason
         if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
           "element structure mismatch (children differ)"
@@ -217,6 +225,31 @@ module Canon
         "'#{truncate(text1)}' vs '#{truncate(text2)}'"
       end
 
+      # Build a Reason line for a +:comments+ diff. Returns +nil+ when
+      # neither side carries a comment (caller falls back to default).
+      def self.build_comment_difference_reason(node1, node2)
+        cm1 = node1 && Canon::Comparison::NodeInspector.comment_node?(node1)
+        cm2 = node2 && Canon::Comparison::NodeInspector.comment_node?(node2)
+
+        return nil unless cm1 || cm2
+
+        if cm1 && !cm2
+          "Comment present on EXPECTED only: " \
+            "<!--#{truncate(comment_text(node1))}-->"
+        elsif cm2 && !cm1
+          "Comment present on ACTUAL only: " \
+            "<!--#{truncate(comment_text(node2))}-->"
+        else
+          t1 = truncate(comment_text(node1))
+          t2 = truncate(comment_text(node2))
+          "Comment text differs: <!--#{t1}--> vs <!--#{t2}-->"
+        end
+      end
+
+      def self.comment_text(node)
+        Canon::Comparison::NodeInspector.text_content(node).to_s
+      end
+
       # Truncate text for display in reason messages
       #
       # @param text [String] Text to truncate

data/lib/canon/comparison/xml_comparator.rb

@@ -703,6 +703,10 @@ differences)
             return build_whitespace_adjacency_reason(node1, node2)
           end
 
+          if dimension == :comments
+            return build_comments_reason(node1, node2)
+          end
+
           # For attribute values differences, show the actual values
           if dimension == :attribute_values
             attrs1 = extract_attributes(node1)
@@ -873,12 +877,31 @@ differences)
             return build_text_diff_reason(text1, text2)
           end
 
-          direction = whitespace_partner_direction(ws_node)
           ws_vis = visualize_whitespace(ws_text)
-          content_vis = content_text ? visualize_whitespace(truncate_text(content_text)) : "(none)"
 
-          "Whitespace #{direction} \"#{content_vis}\": " \
-            "present on #{present_side} (\"#{ws_vis}\"), absent on #{absent_side}"
+          if content_text.nil? || content_text.strip.empty?
+            # Partner content extracts to "" / whitespace-only — naming it
+            # in the Reason ("Whitespace before \"\"") gives the reader
+            # nothing.  Fall back to the parent element name so the
+            # diff carries structural context (issue #112's contract,
+            # extended from :text_content to :whitespace_adjacency).
+            parent_label = whitespace_adjacency_parent_label(ws_node)
+            "Whitespace inside #{parent_label}: " \
+              "present on #{present_side} (\"#{ws_vis}\"), absent on #{absent_side}"
+          else
+            direction = whitespace_partner_direction(ws_node)
+            content_vis = visualize_whitespace(truncate_text(content_text))
+            "Whitespace #{direction} \"#{content_vis}\": " \
+              "present on #{present_side} (\"#{ws_vis}\"), absent on #{absent_side}"
+          end
+        end
+
+        def whitespace_adjacency_parent_label(ws_node)
+          parent = NodeInspector.parent_of(ws_node)
+          return "(unknown parent)" unless parent
+
+          name = parent.name
+          name && !name.empty? ? "<#{name}>" : "(unknown parent)"
         end
 
         # Direction of the partner content relative to the whitespace node,
@@ -889,11 +912,8 @@ differences)
         # "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 "adjacent to" if parent.nil?
+          parent = NodeInspector.parent_of(ws_node)
+          return "adjacent to" unless parent
 
           siblings = parent.children
           idx = siblings.index(ws_node)
@@ -918,6 +938,30 @@ differences)
           false
         end
 
+        # Build a Reason line for a +:comments+ diff (#144).
+        # Names the side that carries the comment and surfaces the
+        # comment text.
+        def build_comments_reason(node1, node2)
+          cm1 = node1 && NodeInspector.comment_node?(node1)
+          cm2 = node2 && NodeInspector.comment_node?(node2)
+
+          if cm1 && !cm2
+            "Comment present on EXPECTED only: <!--#{truncate_text(comment_text(node1))}-->"
+          elsif cm2 && !cm1
+            "Comment present on ACTUAL only: <!--#{truncate_text(comment_text(node2))}-->"
+          elsif cm1 && cm2
+            t1 = truncate_text(comment_text(node1))
+            t2 = truncate_text(comment_text(node2))
+            "Comment text differs: <!--#{t1}--> vs <!--#{t2}-->"
+          else
+            "element structure mismatch (children differ)"
+          end
+        end
+
+        def comment_text(node)
+          NodeInspector.text_content(node).to_s
+        end
+
         # Check if text is only whitespace
         #
         # @param text [String] Text to check

data/lib/canon/comparison.rb

@@ -104,6 +104,8 @@ module Canon
   # - diff_code: Type of difference
   #
   module Comparison
+    autoload :ChildRealignment, "canon/comparison/child_realignment"
+
     # Comparison result constants
     EQUIVALENT = 1
     MISSING_ATTRIBUTE = 2

data/lib/canon/diff/diff_classifier.rb

@@ -74,7 +74,7 @@ module Canon
         end
 
         # :whitespace_adjacency is a report-only re-label of an
-        # asymmetric whitespace mismatch emitted by ChildComparison's
+        # asymmetric whitespace mismatch emitted by ChildRealignment's
         # two-cursor walk.  Equivalence behaviour is unchanged — the
         # underlying mismatch is normative regardless of match options.
         if diff_node.dimension == :whitespace_adjacency
@@ -83,6 +83,14 @@ module Canon
           return diff_node
         end
 
+        # :comments diffs from asymmetric comment nodes intentionally
+        # fall through to profile.normative_dimension? below.  Unlike
+        # :whitespace_adjacency (always normative), the classification
+        # of comment diffs respects the :comments match option:
+        # :strict → normative, :ignore → informative.  This is by
+        # design — callers can control whether asymmetric comments
+        # affect equivalence via the match profile.
+
         # THIRD: Determine if this dimension is normative based on CompareProfile
         # This respects the policy settings (strict/normalize/ignore)
         is_normative = profile.normative_dimension?(diff_node.dimension)

data/lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb

@@ -525,14 +525,34 @@ expand_difference: false)
           text1 = NodeUtils.get_node_text(node1).to_s
           text2 = NodeUtils.get_node_text(node2).to_s
 
-          detail1 = ColorHelper.colorize(
-            "\"#{TextUtils.visualize_whitespace(text1)}\"",
-            :red, use_color
-          )
-          detail2 = ColorHelper.colorize(
-            "\"#{TextUtils.visualize_whitespace(text2)}\"",
-            :green, use_color
-          )
+          if TextUtils.ambiguous_text_pair?(text1, text2) &&
+              (NodeUtils.parent_of(node1) || NodeUtils.parent_of(node2))
+            # Both sides extract to empty / whitespace-only strings —
+            # `""` / `""` tells the reader nothing.  Fall back to a
+            # brief parent open-tag hint per #112's contract, but
+            # without dumping the full ancestor subtree (#125).
+            hint1 = NodeUtils.serialize_open_tag(NodeUtils.parent_of(node1))
+            hint2 = NodeUtils.serialize_open_tag(NodeUtils.parent_of(node2))
+            ws1 = TextUtils.visualize_whitespace(text1)
+            ws2 = TextUtils.visualize_whitespace(text2)
+            detail1 = ColorHelper.colorize(
+              "\"#{ws1}\" in #{hint1}",
+              :red, use_color
+            )
+            detail2 = ColorHelper.colorize(
+              "\"#{ws2}\" in #{hint2}",
+              :green, use_color
+            )
+          else
+            detail1 = ColorHelper.colorize(
+              "\"#{TextUtils.visualize_whitespace(text1)}\"",
+              :red, use_color
+            )
+            detail2 = ColorHelper.colorize(
+              "\"#{TextUtils.visualize_whitespace(text2)}\"",
+              :green, use_color
+            )
+          end
 
           reason = if diff.is_a?(Canon::Diff::DiffNode)
                      diff.reason

data/lib/canon/pretty_printer/html.rb

@@ -29,6 +29,8 @@ module Canon
     #
     # See lutaml/canon#133, lutaml/canon#135.
     class Html
+      WHITESPACE_PRESERVING_ELEMENTS = %w[pre textarea script style].freeze
+
       def initialize(indent: 2, indent_type: "space", fixture_ready: false)
         @indent = indent.to_i
         @indent_type = indent_type
@@ -83,6 +85,7 @@ module Canon
       # suppresses the +<?xml ...?>+ prefix.
       def format_fixture_ready(html_string)
         doc = Nokogiri::HTML5(html_string)
+        strip_structural_whitespace!(doc)
         io = StringIO.new
         if @indent_type == "tab"
           doc.write_to(io, save_with: fixture_ready_save_options,
@@ -94,6 +97,37 @@ module Canon
         io.string
       end
 
+      # libxml's +FORMAT+ save flag does not insert indentation around
+      # the children of any element it sees as mixed content (any
+      # non-whitespace-only text node child).  +Nokogiri::HTML5+ does
+      # not accept the +noblanks+ option that the XML parser uses to
+      # strip these inter-sibling text nodes pre-serialisation, so we
+      # do it manually here: drop whitespace-only text nodes whose
+      # parent is structural (no real text content) and not a
+      # whitespace-preserving element.  Mixed-content runs like
+      # +<p>foo <em>bar</em> baz</p>+ are left alone.
+      def strip_structural_whitespace!(doc)
+        to_remove = []
+        doc.traverse do |node|
+          next unless node.text?
+          next unless node.content.strip.empty?
+
+          parent = node.parent
+          next if parent.nil?
+          next if WHITESPACE_PRESERVING_ELEMENTS.include?(parent.name)
+          next if parent_has_real_text?(parent)
+
+          to_remove << node
+        end
+        to_remove.each(&:remove)
+      end
+
+      def parent_has_real_text?(parent)
+        parent.children.any? do |c|
+          c.text? && !c.content.strip.empty?
+        end
+      end
+
       def fixture_ready_save_options
         Nokogiri::XML::Node::SaveOptions::FORMAT |
           Nokogiri::XML::Node::SaveOptions::AS_XHTML |

data/lib/canon/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-03 00:00:00.000000000 Z
+date: 2026-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -167,6 +167,7 @@ files:
 - docs/features/diff-formatting/algorithm-specific-output.adoc
 - docs/features/diff-formatting/character-visualization.adoc
 - docs/features/diff-formatting/colors-and-symbols.adoc
+- docs/features/diff-formatting/comment-asymmetry.adoc
 - docs/features/diff-formatting/context-and-grouping.adoc
 - docs/features/diff-formatting/display-filtering.adoc
 - docs/features/diff-formatting/display-preprocessing.adoc
@@ -221,6 +222,7 @@ files:
 - lib/canon/commands/format_command.rb
 - lib/canon/comparison.rb
 - lib/canon/comparison/base_comparator.rb
+- lib/canon/comparison/child_realignment.rb
 - lib/canon/comparison/compare_profile.rb
 - lib/canon/comparison/comparison_result.rb
 - lib/canon/comparison/dimensions.rb