canon 0.2.2 → 0.2.4

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
@@ -163,37 +164,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
@@ -351,6 +385,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

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

@@ -318,6 +318,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

data/lib/canon/diff_formatter.rb

@@ -7,6 +7,9 @@ require_relative "diff/diff_block"
 require_relative "diff/diff_context"
 require_relative "diff/diff_report"
 require_relative "diff_formatter/debug_output"
+require_relative "diff_formatter/by_line_formatter"
+require_relative "diff_formatter/by_object_formatter"
+require_relative "diff_formatter/pretty_diff_formatter"
 
 module Canon
   # Formatter for displaying semantic differences with color support
@@ -301,17 +304,26 @@ module Canon
     # @param html_version [Symbol, nil] HTML version (:html4 or :html5)
     # @return [String] Formatted output
     def format(differences, format, doc1: nil, doc2: nil, html_version: nil)
-      # In by-line mode, always use by-line diff
+      # In by-line mode with both docs present, always use by-line diff
       if @mode == :by_line && doc1 && doc2
-        return by_line_diff(doc1, doc2, format: format,
-                                        html_version: html_version,
-                                        differences: differences)
+        doc1, doc2 = apply_display_preprocessing(doc1, doc2, format)
+        # rubocop:disable Layout/HashAlignment
+        return by_line_formatter.format(doc1, doc2, format: format,
+                                                  html_version: html_version,
+                                                  differences: differences)
+        # rubocop:enable Layout/HashAlignment
       end
 
       # In pretty_diff mode, always use text-LCS diff (bypasses DiffNodeMapper).
-      # pretty_diff_format handles nil doc1/doc2 itself (emits header only).
       if @mode == :pretty_diff
-        return pretty_diff_format(doc1, doc2, format: format)
+        d1, d2 = if doc1 && doc2
+                   apply_display_preprocessing(doc1, doc2,
+                                               format)
+                 else
+                   [doc1,
+                    doc2]
+                 end
+        return pretty_diff_formatter.format(d1, d2, format: format)
       end
 
       no_diffs = if differences.respond_to?(:equivalent?)
@@ -323,12 +335,26 @@ module Canon
 
       case @mode
       when :by_line
-        by_line_diff(doc1, doc2, format: format, html_version: html_version,
-                                 differences: differences)
+        if doc1 && doc2
+          doc1, doc2 = apply_display_preprocessing(doc1, doc2,
+                                                   format)
+        end
+        # rubocop:disable Layout/HashAlignment
+        by_line_formatter.format(doc1, doc2, format: format,
+                                               html_version: html_version,
+                                               differences: differences)
+        # rubocop:enable Layout/HashAlignment
       when :pretty_diff
-        pretty_diff_format(doc1, doc2, format: format)
+        d1, d2 = if doc1 && doc2
+                   apply_display_preprocessing(doc1, doc2,
+                                               format)
+                 else
+                   [doc1,
+                    doc2]
+                 end
+        pretty_diff_formatter.format(d1, d2, format: format)
       else
-        by_object_diff(differences, format)
+        by_object_formatter.format(differences, format)
       end
     end
 
@@ -685,10 +711,8 @@ module Canon
       # false disables all visualization
       return {} if character_visualization == false
 
-      # :content_only currently behaves as true (full map)
-      # TODO: apply visualization at DOM text-node level pre-serialization,
-      # keeping structural indentation whitespace plain.
-      # See docs/features/diff-formatting/character-visualization.adoc
+      # :content_only builds the full map; the by_line formatter applies
+      # it only to content portions, leaving structural indentation plain.
 
       return visualization_map if visualization_map
 
@@ -723,177 +747,37 @@ module Canon
       colorize("#{emoji}#{message}\n", :green, :bold)
     end
 
-    # Generate by-object diff with tree visualization
-    # Delegates to format-specific by-object formatters
-    def by_object_diff(differences, format)
-      output = []
-      output << colorize("Visual Diff:", :cyan, :bold)
-
-      # Extract differences array from ComparisonResult if needed
-      diffs_array = if differences.is_a?(Canon::Comparison::ComparisonResult)
-                      differences.differences
-                    else
-                      differences
-                    end
-
-      # Delegate to format-specific formatter
-      formatter = ByObject::BaseFormatter.for_format(
-        format,
+    # Factory methods for mode-specific formatters
+
+    # @return [ByLineFormatter]
+    def by_line_formatter
+      @by_line_formatter ||= ByLineFormatter.new(
         use_color: @use_color,
         visualization_map: @visualization_map,
+        context_lines: @context_lines,
+        diff_grouping_lines: @diff_grouping_lines,
         show_diffs: @show_diffs,
+        character_visualization: @character_visualization,
+        legacy_terminal: @legacy_terminal,
+        diff_mode: @diff_mode,
       )
-
-      output << formatter.format(diffs_array, format)
-
-      output.join("\n")
     end
 
-    # Generate by-line diff
-    # Delegates to format-specific by-line formatters
-    def by_line_diff(doc1, doc2, format: :xml, html_version: nil,
-differences: [])
-      # For HTML format, use html_version if provided, otherwise default to :html4
-      if format == :html && html_version
-        format = html_version # Use :html4 or :html5
-      end
-
-      # Format display name for header
-      format_name = format.to_s.upcase
-
-      output = []
-      output << colorize("Line-by-line diff (#{format_name} mode):", :cyan,
-                         :bold)
-
-      return output.join("\n") if doc1.nil? || doc2.nil?
-
-      # Apply display preprocessing (format both sides identically before diff)
-      doc1, doc2 = apply_display_preprocessing(doc1, doc2, format)
-      # Extract differences array and equivalent status from ComparisonResult if needed
-      diffs_array = if differences.is_a?(Canon::Comparison::ComparisonResult)
-                      @comparison_equivalent = differences.equivalent?
-                      differences.differences
-                    else
-                      @comparison_equivalent = nil
-                      differences
-                    end
-
-      # Delegate to format-specific formatter
-      formatter = ByLine::BaseFormatter.for_format(
-        format,
+    # @return [ByObjectFormatter]
+    def by_object_formatter
+      @by_object_formatter ||= ByObjectFormatter.new(
         use_color: @use_color,
-        context_lines: @context_lines,
-        diff_grouping_lines: @diff_grouping_lines,
         visualization_map: @visualization_map,
         show_diffs: @show_diffs,
-        differences: diffs_array,
-        diff_mode: @legacy_terminal ? :separate : @diff_mode,
-        legacy_terminal: @legacy_terminal,
-        equivalent: @comparison_equivalent,
       )
-
-      output << formatter.format(doc1, doc2)
-
-      output.join("\n")
-    end
-
-    # Generate a text-LCS diff against preprocessed lines (pretty_diff mode).
-    #
-    # This mode bypasses DiffNodeMapper entirely: it applies display_preprocessing
-    # to both sides, then runs Diff::LCS.sdiff on the resulting plain-text lines.
-    # It is a reliable short-term workaround for #85 (normative changes invisible
-    # in :by_line mode when DiffNodeMapper's DOM-address correlation is off).
-    #
-    # Limitations:
-    # - show_diffs :normative / :informative filter is ignored (no DiffNodes)
-    # - No inline character highlighting (whole-line granularity only)
-    #
-    # @param doc1 [String] First document
-    # @param doc2 [String] Second document
-    # @param format [Symbol] Document format
-    # @return [String] Formatted diff output
-    def pretty_diff_format(doc1, doc2, format:)
-      require "diff/lcs"
-
-      resolved_format = format
-
-      format_name = resolved_format.to_s.upcase
-      output = []
-      output << colorize("Pretty diff (#{format_name} mode):", :cyan, :bold)
-
-      return output.join("\n") if doc1.nil? || doc2.nil?
-
-      # Apply display preprocessing — same transforms as by_line_diff
-      d1, d2 = apply_display_preprocessing(doc1, doc2, resolved_format)
-
-      lines1 = d1.lines.map(&:chomp)
-      lines2 = d2.lines.map(&:chomp)
-
-      hunks = ::Diff::LCS.sdiff(lines1, lines2)
-
-      output << render_pretty_diff(hunks)
-      output.join("\n")
     end
 
-    # Render sdiff hunks with context windowing and colorization.
-    #
-    # Uses the same context_lines setting as by_line_diff. 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)
-      # Identify positions of changed hunks
-      changed = hunks.each_index.reject { |i| hunks[i].action == "=" }
-
-      return colorize("  (no differences)", :green) if changed.empty?
-
-      ctx = [@context_lines || 3, 0].max
-
-      # Build expanded windows, then merge overlapping/adjacent ones
-      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|
-        # Separator between non-adjacent blocks
-        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")
+    # @return [PrettyDiffFormatter]
+    def pretty_diff_formatter
+      @pretty_diff_formatter ||= PrettyDiffFormatter.new(
+        use_color: @use_color,
+        context_lines: @context_lines,
+      )
     end
 
     # Apply display preprocessing to both documents before the line diff.

data/lib/canon/html/data_model.rb

@@ -208,19 +208,25 @@ module Canon
 
       # Build text node from Nokogiri text node
       # HTML-specific: handles whitespace-sensitive elements (pre, code, textarea, script, style)
+      # and preserves whitespace between inline element siblings.
       def self.build_text_node(nokogiri_text)
         # Skip text nodes that are only whitespace between elements
         # EXCEPT in whitespace-sensitive elements (pre, code, textarea, script, style)
-        # where whitespace is semantically significant
+        # and when whitespace is between inline element siblings (semantically significant)
         content = nokogiri_text.content
 
-        if content.strip.empty? && nokogiri_text.parent.is_a?(Nokogiri::XML::Element)
+        # NBSP (U+00A0) is never insignificant whitespace
+        if content.strip.empty? && nokogiri_text.parent.is_a?(Nokogiri::XML::Element) && !content.include?("\u00A0")
           # Check if parent is whitespace-sensitive
           parent_name = nokogiri_text.parent.name.downcase
           whitespace_sensitive_tags = %w[pre code textarea script style]
 
-          # Skip whitespace-only text UNLESS in whitespace-sensitive element
-          return nil unless whitespace_sensitive_tags.include?(parent_name)
+          # Check if whitespace is between inline siblings
+          require_relative "../comparison/whitespace_sensitivity"
+          unless whitespace_sensitive_tags.include?(parent_name) ||
+              Canon::Comparison::WhitespaceSensitivity.inline_whitespace_significant?(nokogiri_text)
+            return nil
+          end
         end
 
         # Nokogiri already handles CDATA conversion and entity resolution