canon 0.2.6 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6437f1a8b556bb49bffbcecf47ec0eeecabdf6541bd5baa5954ac88f98f33a2c
-  data.tar.gz: 98eff2aa558165dc7e13c8d29da21d8d9c6589cae1d48a18d27f0420d6be7198
+  metadata.gz: 1800400419926b8607eb146490d0bc4a0ecf5e4bfaf2b3007a87e99d440661f3
+  data.tar.gz: 0fc8298171e94fec5e9c4b650001fcc31e79ca774e1d7ad0f19fe91308199b18
 SHA512:
-  metadata.gz: 055614c143bca292b575755f5b4a1554a002e0d6f264ddee3e29049f89d6f9795a61069c1bdf7ebfa459ed11ac2a21203a779e115f8aee143a2aa3c77951a086
-  data.tar.gz: ff64c25654c1eef41dcc80b471df2958c516e69fa625723bdecfd18c5a99716e7f347c313bf72c28f3b898547d5c97aac3ebb62bcf44e726bc49e668a73e0dd9
+  metadata.gz: 5c553b671df23a70814bedb7521836b01ce7d6e0ab1af99f00aa05ca6f4ef875d8e8af2e4e63c208443d8ddbab92ed7a05c3c8c6828da2608c42bf6a38f0b7c4
+  data.tar.gz: e183e77684bc3fe7c072caa904cf709a3c20e2f6c38099a42f099e3367d2b0c2336f5407a6def0147f7405056a26a639f4b9dd5075deb6b51a60bcb7921c7c44

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

@@ -98,6 +98,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.rb

@@ -873,12 +873,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 +908,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)

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

metadata

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