canon 0.2.3 → 0.2.5

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

@@ -13,8 +13,10 @@ module Canon
         # @param use_color [Boolean] Whether to use colors
         # @param compact [Boolean] Whether to serialize element nodes as compact XML
         # @return [String] Formatted dimension details
+        # rubocop:disable Lint/UnusedMethodArgument
         def self.format_dimension_details(diff, use_color, compact: false,
 expand_difference: false)
+          # rubocop:enable Lint/UnusedMethodArgument
           dimension = extract_dimension(diff)
 
           case dimension
@@ -23,8 +25,7 @@ expand_difference: false)
           when :namespace_declarations
             format_namespace_declarations_details(diff, use_color)
           when :element_structure
-            format_element_structure_details(diff, use_color,
-                                             expand_difference: expand_difference)
+            format_element_structure_details(diff, use_color)
           when :attribute_presence
             format_attribute_presence_details(diff, use_color)
           when :attribute_values
@@ -33,6 +34,8 @@ expand_difference: false)
             format_attribute_order_details(diff, use_color)
           when :text_content
             format_text_content_details(diff, use_color, compact: compact)
+          when :whitespace_adjacency
+            format_whitespace_adjacency_details(diff, use_color)
           when :structural_whitespace
             format_structural_whitespace_details(diff, use_color)
           when :comments
@@ -163,37 +166,70 @@ expand_difference: false)
 
         # Format element structure differences
         #
+        # Produces compact XML for both sides so the user can see attributes
+        # and text content, not just the tag name.  Handles nil nodes that
+        # arise from insertions/deletions.
+        #
         # @param diff [DiffNode, Hash] Difference node
         # @param use_color [Boolean] Whether to use colors
         # @return [Array] Tuple of [detail1, detail2, changes]
-        def self.format_element_structure_details(diff, use_color,
-expand_difference: false)
+        def self.format_element_structure_details(diff, use_color)
           require_relative "color_helper"
           require_relative "node_utils"
 
           node1 = extract_node1(diff)
           node2 = extract_node2(diff)
 
-          name1 = NodeUtils.get_element_name_for_display(node1)
-          name2 = NodeUtils.get_element_name_for_display(node2)
+          has1 = !node1.nil?
+          has2 = !node2.nil?
+
+          if has1 && has2
+            # Both elements present — show compact XML for both
+            compact1 = NodeUtils.serialize_node_compact(node1)
+            compact2 = NodeUtils.serialize_node_compact(node2)
+            detail1 = ColorHelper.colorize(compact1, :red, use_color)
+            detail2 = ColorHelper.colorize(compact2, :green, use_color)
+
+            name1 = NodeUtils.get_element_name_for_display(node1)
+            name2 = NodeUtils.get_element_name_for_display(node2)
 
-          if expand_difference
-            display1 = NodeUtils.serialize_node_compact(node1)
-            display2 = NodeUtils.serialize_node_compact(node2)
-            detail1 = ColorHelper.colorize(display1, :red, use_color)
-            detail2 = ColorHelper.colorize(display2, :green, use_color)
+            changes = if name1 == name2
+                        "Element <#{name1}> structure changed (children differ)"
+                      else
+                        build_structure_change_text(compact1, compact2,
+                                                    use_color)
+                      end
+          elsif has1
+            # Element removed
+            compact1 = NodeUtils.serialize_node_compact(node1)
+            detail1 = ColorHelper.colorize(compact1, :red, use_color)
+            detail2 = ColorHelper.colorize("(not present)", :green, use_color)
+            changes = "Element removed: #{ColorHelper.colorize(compact1, :red,
+                                                               use_color)}"
           else
-            detail1 = "<#{ColorHelper.colorize(name1, :red, use_color)}>"
-            detail2 = "<#{ColorHelper.colorize(name2, :green, use_color)}>"
+            # Element added
+            compact2 = NodeUtils.serialize_node_compact(node2)
+            detail1 = ColorHelper.colorize("(not present)", :red, use_color)
+            detail2 = ColorHelper.colorize(compact2, :green, use_color)
+            changes = "Element added: #{ColorHelper.colorize(compact2, :green,
+                                                             use_color)}"
           end
 
-          changes = "Element differs: #{ColorHelper.colorize(name1, :red,
-                                                             use_color)} → " \
-                    "#{ColorHelper.colorize(name2, :green, use_color)}"
-
           [detail1, detail2, changes]
         end
 
+        # Build human-readable change text for element structure diffs
+        #
+        # @param display1 [String] Serialized expected element
+        # @param display2 [String] Serialized actual element
+        # @param use_color [Boolean] Whether to use colors
+        # @return [String] Change description
+        def self.build_structure_change_text(display1, display2, use_color)
+          "Element structure changed: " \
+            "#{ColorHelper.colorize(display1, :red, use_color)} → " \
+            "#{ColorHelper.colorize(display2, :green, use_color)}"
+        end
+
         # Format attribute presence differences
         #
         # @param diff [DiffNode, Hash] Difference node
@@ -332,18 +368,21 @@ expand_difference: false)
           node1 = extract_node1(diff)
           node2 = extract_node2(diff)
 
+          # Symmetric one-sided rendering for missing/extra text nodes.
+          # When exactly one side is nil, render "(not present)" on that
+          # side and the present side's raw text content (whitespace-
+          # visualised, with a brief parent open-tag hint for context).
+          # Mirrors format_element_structure_details above.  Without this
+          # short-circuit, the ambiguous-pair fallback further down would
+          # serialize the present side's *parent subtree* in full,
+          # producing a misleading diff payload.  See lutaml/canon#125.
+          if node1.nil? ^ node2.nil?
+            return format_text_content_one_sided(node1, node2, use_color)
+          end
+
           text1 = NodeUtils.node_to_display(node1, compact: compact)
           text2 = NodeUtils.node_to_display(node2, compact: compact)
 
-          # Handle cases where one node is missing (e.g. text added or removed)
-          if node1.nil? || node2.nil?
-            if node1.nil?
-              text2 = NodeUtils.node_to_display(node2, compact: compact)
-            else
-              text1 = NodeUtils.node_to_display(node1, compact: compact)
-            end
-          end
-
           if NodeUtils.inside_preserve_element?(node1) || NodeUtils.inside_preserve_element?(node2)
             detail1 = ColorHelper.colorize(
               TextUtils.visualize_whitespace(text1), :red, use_color
@@ -351,6 +390,20 @@ expand_difference: false)
             detail2 = ColorHelper.colorize(
               TextUtils.visualize_whitespace(text2), :green, use_color
             )
+          elsif TextUtils.ambiguous_text_pair?(text1, text2) &&
+              (NodeUtils.parent_of(node1) || NodeUtils.parent_of(node2))
+            # Both sides render to empty/whitespace-only strings, which are
+            # indistinguishable after JSON quoting.  Fall back to each side's
+            # parent element serialized compactly, with whitespace visualized
+            # so the reader can see the structural contrast.
+            ctx1 = NodeUtils.serialize_node_compact(NodeUtils.parent_of(node1))
+            ctx2 = NodeUtils.serialize_node_compact(NodeUtils.parent_of(node2))
+            detail1 = ColorHelper.colorize(
+              TextUtils.visualize_whitespace(ctx1), :red, use_color
+            )
+            detail2 = ColorHelper.colorize(
+              TextUtils.visualize_whitespace(ctx2), :green, use_color
+            )
           elsif compact && (node1.is_a?(Canon::Xml::Nodes::ElementNode) ||
                            node2.is_a?(Canon::Xml::Nodes::ElementNode))
             # In compact mode with element nodes, display as raw XML without
@@ -384,8 +437,113 @@ expand_difference: false)
           [detail1, detail2, changes]
         end
 
+        # Whether a node is an element (Canon or Nokogiri), used to
+        # detect element-shaped diffs that have been misclassified as
+        # :text_content and route them to element-structure rendering.
+        # See lutaml/canon#125 follow-up.
+        def self.present_is_element?(node)
+          return false unless node
+
+          case node
+          when Canon::Xml::Node
+            node.node_type == :element
+          when Nokogiri::XML::Node
+            node.element?
+          else
+            false
+          end
+        end
+
+        # Render a one-sided text-content diff (one node nil, the other a
+        # text node).  Mirrors the +has1+/+has2+ branches of
+        # +format_element_structure_details+: "(not present)" on the nil
+        # side, the present side's raw text content (whitespace-visualised
+        # and quoted) plus a brief parent open-tag hint for context.
+        #
+        # @param node1 [Object, nil] First node (nil if removed)
+        # @param node2 [Object, nil] Second node (nil if added)
+        # @param use_color [Boolean] Whether to apply ANSI colours
+        # @return [Array<String>] Tuple of [detail1, detail2, changes]
+        def self.format_text_content_one_sided(node1, node2, use_color)
+          require_relative "color_helper"
+          require_relative "node_utils"
+          require_relative "text_utils"
+
+          present = node1 || node2
+
+          # Defensive: if a one-sided text-content diff carries an
+          # *element* on the present side (e.g. because an upstream
+          # comparator misclassified an element orphan as
+          # :text_content), delegate to the element-structure
+          # formatter rather than rendering the element as +text ""+.
+          # The construction-side fix in lutaml/canon#125 follow-up
+          # removes the immediate failure mode, but other paths could
+          # still misclassify and the formatter must produce a
+          # best-effort element representation, never +text ""+.
+          if present_is_element?(present)
+            return format_element_structure_details(
+              { node1: node1, node2: node2 }, use_color
+            )
+          end
+
+          removed = node2.nil?
+
+          raw     = NodeUtils.raw_text_value(present)
+          visible = TextUtils.visualize_whitespace(raw)
+          parent  = NodeUtils.parent_of(present)
+          context = parent ? " in #{NodeUtils.serialize_open_tag(parent)}" : ""
+          present_str = "text \"#{visible}\"#{context}"
+
+          if removed
+            detail1 = ColorHelper.colorize(present_str, :red, use_color)
+            detail2 = ColorHelper.colorize("(not present)", :green, use_color)
+            changes = "Text removed: #{detail1}"
+          else
+            detail1 = ColorHelper.colorize("(not present)", :red, use_color)
+            detail2 = ColorHelper.colorize(present_str, :green, use_color)
+            changes = "Text added: #{detail2}"
+          end
+
+          [detail1, detail2, changes]
+        end
+
         # Format structural whitespace differences
         #
+        # Format a :whitespace_adjacency diff (#137).
+        #
+        # @param diff [DiffNode, Hash] Difference node
+        # @param use_color [Boolean] Whether to use colors
+        # @return [Array] Tuple of [detail1, detail2, changes]
+        def self.format_whitespace_adjacency_details(diff, use_color)
+          require_relative "color_helper"
+          require_relative "node_utils"
+          require_relative "text_utils"
+
+          node1 = extract_node1(diff)
+          node2 = extract_node2(diff)
+
+          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
+          )
+
+          reason = if diff.is_a?(Canon::Diff::DiffNode)
+                     diff.reason
+                   else
+                     diff.is_a?(Hash) ? diff[:reason] : nil
+                   end
+          changes = reason.to_s
+
+          [detail1, detail2, changes]
+        end
+
         # @param diff [DiffNode, Hash] Difference node
         # @param use_color [Boolean] Whether to use colors
         # @return [Array] Tuple of [detail1, detail2, changes]

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "nokogiri"
 require_relative "../../xml/namespace_helper"
 
 module Canon
@@ -260,12 +261,15 @@ module Canon
           end
         end
 
-        # Serialize a Canon Xml node tree as compact XML for display.
+        # Serialize a node tree as compact XML for display.
         #
         # Produces a human-readable inline XML string without namespace
         # declarations and without indentation — suitable for use in Semantic
-        # Diff Report entries.  Only handles Canon::Xml::Nodes types; for any
-        # other node (Nokogiri, etc.) falls back to +get_node_text+.
+        # Diff Report entries.  Handles both +Canon::Xml::Nodes+ types and
+        # Nokogiri XML/HTML nodes (the html DOM comparison path uses
+        # Nokogiri nodes, so element-structure diffs originating there must
+        # be rendered structurally too — see issue #120).  For any other
+        # node type, falls back to +get_node_text+.
         #
         # @param node [Object] Node to serialize
         # @return [String] Compact XML string
@@ -294,12 +298,79 @@ module Canon
           when Canon::Xml::Nodes::CommentNode
             text = node.respond_to?(:value) ? node.value.to_s : ""
             "<!--#{CGI.escapeHTML(text)}-->"
+          when Nokogiri::XML::Text, Nokogiri::XML::CDATA
+            CGI.escapeHTML(node.content.to_s)
+          when Nokogiri::XML::Comment
+            "<!--#{CGI.escapeHTML(node.content.to_s)}-->"
+          when Nokogiri::XML::Element
+            tag = node.name.to_s
+            attrs = node.attribute_nodes.map do |a|
+              " #{a.name}=\"#{CGI.escapeHTML(a.value.to_s)}\""
+            end.join
+            children_xml = node.children.map do |c|
+              serialize_node_compact(c)
+            end.join
+            if children_xml.empty?
+              "<#{tag}#{attrs}/>"
+            else
+              "<#{tag}#{attrs}>#{children_xml}</#{tag}>"
+            end
           else
-            # Nokogiri nodes or other unknown types — fall back to text extraction
+            # Unknown node types — fall back to text extraction
             get_node_text(node)
           end
         end
 
+        # Serialize a node's open tag only — name + attributes, no children,
+        # no closing tag.  Used by +format_text_content_one_sided+ to render
+        # a brief parent-element context hint (e.g. +<div id="A">+) for a
+        # one-sided text diff, instead of the full ancestor subtree that
+        # +serialize_node_compact+ would produce.  See lutaml/canon#125.
+        #
+        # @param node [Object] Element node to serialize
+        # @return [String] Open-tag string, or "" for non-elements / nil
+        def self.serialize_open_tag(node)
+          require "cgi"
+          return "" unless node
+
+          case node
+          when Canon::Xml::Nodes::ElementNode
+            tag = node.name.to_s
+            attrs = node.attribute_nodes.map do |attr|
+              " #{attr.name}=\"#{CGI.escapeHTML(attr.value.to_s)}\""
+            end.join
+            "<#{tag}#{attrs}>"
+          when Nokogiri::XML::Element
+            tag = node.name.to_s
+            attrs = node.attribute_nodes.map do |a|
+              " #{a.name}=\"#{CGI.escapeHTML(a.value.to_s)}\""
+            end.join
+            "<#{tag}#{attrs}>"
+          else
+            ""
+          end
+        end
+
+        # Return the raw text content of a text node without stripping
+        # whitespace.  +get_node_text+ strips ASCII whitespace, which
+        # destroys whitespace-only payloads that callers (e.g. one-sided
+        # text-content diff rendering) need to display verbatim.
+        #
+        # @param node [Object] Text node
+        # @return [String] Raw text content, or "" if not a text-bearing node
+        def self.raw_text_value(node)
+          return "" unless node
+
+          case node
+          when Canon::Xml::Node
+            node.value.to_s
+          when Nokogiri::XML::Node
+            node.content.to_s
+          else
+            ""
+          end
+        end
+
         # Return the best display string for a node.
         #
         # When +compact: true+ and the node is a Canon ElementNode, returns a
@@ -318,6 +389,23 @@ module Canon
           end
         end
 
+        # Return the parent of a node, or nil, regardless of the node API.
+        #
+        # Canon::Xml nodes expose +parent+; some Nokogiri-shaped nodes expose
+        # +parent_node+.  This helper abstracts over both.
+        #
+        # @param node [Object] Node to query
+        # @return [Object, nil] Parent node or nil
+        def self.parent_of(node)
+          return nil unless node
+
+          if node.respond_to?(:parent)
+            node.parent
+          elsif node.respond_to?(:parent_node)
+            node.parent_node
+          end
+        end
+
         # Check if node is inside a preserve-whitespace element
         #
         # @param node [Object] Node to check

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

@@ -83,6 +83,35 @@ module Canon
           end.join
         end
 
+        # Whether two text values would be visually indistinguishable when
+        # rendered through the standard JSON-quoting path.
+        #
+        # Covers three cases that collapse to near-identical short strings
+        # like +""+ / +" "+ / +":"+ / +":"+:
+        #   * both sides empty
+        #   * both sides whitespace-only (possibly with different whitespace
+        #     that JSON.generate preserves verbatim but a reader cannot tell
+        #     apart from plain spaces)
+        #   * both sides equal (the comparator reported a diff based on
+        #     something the text-only extraction does not surface — e.g. a
+        #     sibling text node that exists on one side and not the other)
+        #
+        # Callers should fall back to rendering parent-element context
+        # instead.
+        #
+        # @param text1 [String, nil]
+        # @param text2 [String, nil]
+        # @return [Boolean]
+        def self.ambiguous_text_pair?(text1, text2)
+          blank_or_whitespace = ->(t) {
+            t.nil? || t.empty? || t.match?(/\A\s+\z/)
+          }
+          return true if blank_or_whitespace.call(text1) &&
+            blank_or_whitespace.call(text2)
+
+          text1 == text2
+        end
+
         # Check if text contains non-ASCII or non-printable characters
         #
         # @param text [String] Text to check

data/lib/canon/diff_formatter/pretty_diff_formatter.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "paint"
+require "diff/lcs"
+
+module Canon
+  class DiffFormatter
+    # Handles the pretty_diff rendering pipeline for text-LCS diffs.
+    #
+    # Bypasses DiffNodeMapper entirely — runs Diff::LCS.sdiff on plain-text
+    # lines and renders with context windowing and colorization.
+    class PrettyDiffFormatter
+      def initialize(use_color:, context_lines:)
+        @use_color = use_color
+        @context_lines = context_lines
+      end
+
+      # Format a text-LCS diff between two documents.
+      #
+      # @param doc1 [String, nil] First document (already preprocessed)
+      # @param doc2 [String, nil] Second document (already preprocessed)
+      # @param format [Symbol] Document format for display name
+      # @return [String] Formatted diff output
+      def format(doc1, doc2, format:)
+        format_name = format.to_s.upcase
+
+        output = []
+        output << colorize("Pretty diff (#{format_name} mode):", :cyan, :bold)
+
+        return output.join("\n") if doc1.nil? || doc2.nil?
+
+        lines1 = doc1.lines.map(&:chomp)
+        lines2 = doc2.lines.map(&:chomp)
+
+        hunks = ::Diff::LCS.sdiff(lines1, lines2)
+
+        output << render_pretty_diff(hunks)
+        output.join("\n")
+      end
+
+      private
+
+      # Render sdiff hunks with context windowing and colorization.
+      #
+      # Uses context_lines setting for expansion. Changed hunks
+      # (action != "=") are expanded by context_lines in each direction;
+      # nearby windows are merged; a separator is emitted between
+      # non-adjacent blocks.
+      #
+      # @param hunks [Array<Diff::LCS::ContextChange>] Output of Diff::LCS.sdiff
+      # @return [String] Rendered diff lines joined with "\n"
+      def render_pretty_diff(hunks)
+        changed = hunks.each_index.reject { |i| hunks[i].action == "=" }
+
+        return colorize("  (no differences)", :green) if changed.empty?
+
+        ctx = [@context_lines || 3, 0].max
+
+        windows = changed.map do |pos|
+          [
+            [pos - ctx, 0].max,
+            [pos + ctx, hunks.length - 1].min,
+          ]
+        end
+
+        merged = []
+        windows.each do |lo, hi|
+          if merged.empty? || lo > merged.last[1] + 1
+            merged << [lo, hi]
+          else
+            merged.last[1] = [merged.last[1], hi].max
+          end
+        end
+
+        lines = []
+        merged.each_with_index do |(lo, hi), block_idx|
+          if block_idx.positive?
+            lines << colorize("--- ---", :cyan)
+          elsif lo.positive?
+            lines << colorize("--- ---", :cyan)
+          end
+
+          (lo..hi).each do |i|
+            hunk = hunks[i]
+            case hunk.action
+            when "="
+              lines << (@use_color ? "\e[0m  #{hunk.old_element}" : "  #{hunk.old_element}")
+            when "-"
+              lines << colorize("- #{hunk.old_element}", :red)
+            when "+"
+              lines << colorize("+ #{hunk.new_element}", :green)
+            when "!"
+              lines << colorize("- #{hunk.old_element}", :red)
+              lines << colorize("+ #{hunk.new_element}", :green)
+            end
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      def colorize(text, *colors)
+        return text unless @use_color
+
+        "\e[0m#{Paint[text, *colors]}"
+      end
+    end
+  end
+end