RubyGems - canon - Versions diffs - 0.2.3 → 0.2.4 - Mend

canon 0.2.3 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (52) hide show

checksums.yaml +4 -4
data/.rubocop_todo.yml +31 -149
data/README.adoc +9 -0
data/docs/advanced/semantic-diff-report.adoc +31 -0
data/docs/features/configuration-profiles.adoc +4 -2
data/docs/features/match-options/html-policies.adoc +2 -0
data/docs/features/match-options/index.adoc +40 -0
data/docs/guides/choosing-configuration.adoc +12 -1
data/docs/reference/cli-options.adoc +3 -0
data/docs/reference/options-across-interfaces.adoc +7 -1
data/docs/understanding/formats/html.adoc +9 -2
data/lib/canon/cli.rb +4 -0
data/lib/canon/commands/diff_command.rb +1 -0
data/lib/canon/comparison/comparison_result.rb +79 -0
data/lib/canon/comparison/html_comparator.rb +92 -11
data/lib/canon/comparison/markup_comparator.rb +19 -0
data/lib/canon/comparison/match_options/base_resolver.rb +1 -0
data/lib/canon/comparison/match_options/xml_resolver.rb +8 -0
data/lib/canon/comparison/match_options.rb +23 -2
data/lib/canon/comparison/whitespace_sensitivity.rb +96 -0
data/lib/canon/comparison/xml_comparator/child_comparison.rb +6 -0
data/lib/canon/comparison/xml_comparator/node_parser.rb +45 -7
data/lib/canon/comparison/xml_comparator.rb +80 -4
data/lib/canon/comparison/xml_node_comparison.rb +29 -3
data/lib/canon/comparison.rb +84 -22
data/lib/canon/config/env_schema.rb +2 -1
data/lib/canon/config/profiles/metanorma.yml +3 -0
data/lib/canon/config.rb +51 -5
data/lib/canon/diff/diff_classifier.rb +18 -2
data/lib/canon/diff/diff_line_builder.rb +9 -8
data/lib/canon/diff_formatter/by_line/base_formatter.rb +39 -4
data/lib/canon/diff_formatter/by_line/html_formatter.rb +5 -2
data/lib/canon/diff_formatter/by_line_formatter.rb +84 -0
data/lib/canon/diff_formatter/by_object_formatter.rb +53 -0
data/lib/canon/diff_formatter/diff_detail_formatter/dimension_formatter.rb +65 -17
data/lib/canon/diff_formatter/diff_detail_formatter/node_utils.rb +17 -0
data/lib/canon/diff_formatter/diff_detail_formatter/text_utils.rb +29 -0
data/lib/canon/diff_formatter/pretty_diff_formatter.rb +109 -0
data/lib/canon/diff_formatter.rb +57 -173
data/lib/canon/html/data_model.rb +10 -4
data/lib/canon/tree_diff/adapters/html_adapter.rb +55 -2
data/lib/canon/tree_diff/tree_diff_integrator.rb +1 -1
data/lib/canon/version.rb +1 -1
data/lib/canon/xml/c14n.rb +59 -5
data/lib/canon/xml/element_matcher.rb +3 -0
data/lib/canon/xml/node.rb +8 -1
data/lib/canon/xml/nodes/comment_node.rb +4 -0
data/lib/canon/xml/nodes/element_node.rb +4 -0
data/lib/canon/xml/nodes/text_node.rb +4 -0
data/lib/canon/xml/sax_builder.rb +11 -2
data/lib/canon/xml/xpath_engine.rb +238 -0
metadata +6 -2

data/lib/canon/comparison/xml_node_comparison.rb CHANGED Viewed

@@ -232,6 +232,17 @@ diff_children, differences)
         return false unless text_node?(node) && node.parent
         return false unless MatchOptions.normalize_text(node_text(node)).empty?
+        # HTML-specific: NBSP (U+00A0) is never insignificant whitespace —
+        # it always renders as a visible non-breaking space.
+        format = opts[:format] || match_opts[:format]
+        if %i[html html4 html5].include?(format)
+          return false if WhitespaceSensitivity.contains_nbsp?(node_text(node))
+          # Whitespace between inline element siblings is semantically
+          # significant (renders as a visible gap) and must not be stripped.
+          return false if WhitespaceSensitivity.inline_whitespace_significant?(node)
+        end
         return true unless WhitespaceSensitivity.whitespace_preserved?(
           node.parent, match_opts
         )
@@ -329,9 +340,24 @@ diff_children, differences)
       # @param node [Object] Node to check
       # @return [Boolean] true if node is a text node
       def self.text_node?(node)
-        (node.respond_to?(:text?) && node.text? &&
-          !node.respond_to?(:element?)) ||
-          (node.respond_to?(:node_type) && node.node_type == :text)
+        return false unless node
+        # Nokogiri text nodes (XML, HTML4, HTML5) — call element? rather
+        # than respond_to?(:element?), which always returns true for
+        # Nokogiri::XML::Node and made this predicate vacuously false
+        # for every Nokogiri text node. See issue #118.
+        if node.is_a?(Nokogiri::XML::Node)
+          return node.text? && !node.element?
+        end
+        # Canon::Xml::Nodes types and other ducktyped nodes.
+        if node.respond_to?(:text?) && node.text? &&
+            !node.respond_to?(:element?)
+          return true
+        end
+        # Symbol-style node_type (Canon's own node objects).
+        node.respond_to?(:node_type) && node.node_type == :text
       end
       # Extract text content from a node

data/lib/canon/comparison.rb CHANGED Viewed

@@ -144,6 +144,35 @@ module Canon
         dom_diff(obj1, obj2, opts)
       end
+      # Summarize the first difference between two documents.
+      #
+      # Returns a human-readable string describing the first difference
+      # when documents differ, or "Equivalent" when they match.
+      # This is a lightweight alternative to +equivalent?+ with +verbose: true+.
+      #
+      # @param obj1 [Object] First object to compare
+      # @param obj2 [Object] Second object to compare
+      # @param opts [Hash] Comparison options (same as +equivalent?+)
+      # @return [String] Summary string
+      #
+      # @example
+      #   Canon::Comparison.summarize("<p>Hello</p>", "<p>World</p>")
+      #   # => "Not equivalent: text content differs at /p[1] (Hello vs World)"
+      #
+      #   Canon::Comparison.summarize("<p>Hello</p>", "<p>Hello</p>")
+      #   # => "Equivalent"
+      def summarize(obj1, obj2, opts = {})
+        result = equivalent?(obj1, obj2, opts.merge(verbose: true))
+        if result.is_a?(ComparisonResult)
+          result.summary
+        elsif result == true
+          "Equivalent"
+        else
+          "Not equivalent"
+        end
+      end
       # Define a custom comparison profile with DSL syntax
       #
       # @param name [Symbol] Profile name
@@ -602,26 +631,26 @@ module Canon
             # parsers can mutate the DOM).
             opts[:_original_str1] = obj1.dup if obj1.is_a?(String)
             opts[:_original_str2] = obj2.dup if obj2.is_a?(String)
-            if opts[:format] == :html5
-              # HTML5 fragment parsing is safe — it normalizes without
-              # destructive content-model mutations.
-              obj1 = HtmlParser.parse(obj1, :html5) if obj1.is_a?(String)
-              obj2 = HtmlParser.parse(obj2, :html5) if obj2.is_a?(String)
-            else
-              # HTML4 fragment parsing mutates the DOM (strips <body>
-              # attributes, re-parents <h1> content, etc.).  Use XML
-              # fragment parsing which preserves structure faithfully.
-              if obj1.is_a?(String)
-                obj1 = Nokogiri::XML.fragment(
-                  strip_xml_preamble(obj1),
-                )
-              end
-              if obj2.is_a?(String)
-                obj2 = Nokogiri::XML.fragment(
-                  strip_xml_preamble(obj2),
-                )
-              end
-            end
+            # Parse all HTML formats (:html, :html4, :html5) with
+            # Nokogiri::HTML5 so that html4 and html5 share HTML's
+            # whitespace-sensitivity semantics (issue #118).
+            #
+            # The previous html/html4 branch used Nokogiri::XML.fragment
+            # to dodge Nokogiri::HTML4.fragment's destructive DOM
+            # mutations. That avoided one problem but introduced a
+            # bigger one: XML whitespace rules were being applied to
+            # HTML content. HTML's content model — identical between
+            # HTML4 and HTML5 — treats whitespace-only text between
+            # block-level children as insignificant; XML treats every
+            # whitespace text node as significant. Routing html4 input
+            # through an XML parser therefore made
+            # be_html4_equivalent_to reject inputs that
+            # be_html5_equivalent_to (correctly) accepts.
+            # Nokogiri::HTML5.fragment is non-destructive (the original
+            # HTML4.fragment concern does not apply to it) and applies
+            # HTML's content model uniformly.
+            obj1 = HtmlParser.parse(obj1, :html5) if obj1.is_a?(String)
+            obj2 = HtmlParser.parse(obj2, :html5) if obj2.is_a?(String)
           end
         else
           format1 = FormatDetector.detect(obj1)
@@ -662,8 +691,14 @@ module Canon
         # but defined in config
         if Canon::Config.instance.respond_to?(comparison_format)
           format_config = Canon::Config.instance.public_send(comparison_format)
-          if opts[:match_profile].nil? && format_config.match.profile
-            opts[:match_profile] = format_config.match.profile
+          if opts[:global_profile].nil? && format_config.match.profile
+            # Config-sourced profile has *global* priority (applied before
+            # global_options), so that YAML profile_options like
+            # whitespace_type: :normalize can override the built-in profile
+            # (e.g. :spec_friendly)'s whitespace_type: :strict.  Writing to
+            # :match_profile here gave the config profile per-call priority,
+            # which incorrectly overrode the YAML's own overrides.
+            opts[:global_profile] = format_config.match.profile
           end
           # Pass YAML profile's extra match options (e.g., preserve_whitespace_elements)
           # that are stored in MatchConfig's resolver but not exposed via the
@@ -701,6 +736,33 @@ module Canon
         str
       end
+      # Decode HTML named entities (&nbsp; etc.) to their numeric
+      # character reference equivalents so that Nokogiri::XML.fragment
+      # (which only understands the five XML entities) preserves them
+      # as text nodes instead of silently dropping them.
+      #
+      # Uses Nokogiri's HTML4 parser to resolve the entities — the
+      # text is extracted from a fragment so no structural tags are added.
+      #
+      # @param str [String] HTML string potentially containing named entities
+      # @return [String] String with named entities replaced by characters
+      def decode_html_entities(str)
+        # Fast path: skip if no ampersands present
+        return str unless str.include?("&")
+        # Parse as HTML fragment to resolve named entities, then
+        # re-serialize as text.  This converts &nbsp; → U+00A0, etc.
+        doc = Nokogiri::HTML4.fragment(str)
+        # Serialize back, preserving the resolved characters.
+        # to_html re-encodes characters, so use inner_html which
+        # keeps the character form.
+        doc.inner_html
+        # If the serialization re-encoded characters as entities,
+        # that's fine — the XML parser understands numeric refs like &#160;
+      end
       # Detect the format of an object (delegates to FormatDetector)
       #
       # @param obj [Object] Object to detect format of

data/lib/canon/config/env_schema.rb CHANGED Viewed

@@ -14,6 +14,7 @@ module Canon
         show_diffs: :symbol,
         verbose_diff: :boolean,
         algorithm: :symbol,
+        parser: :symbol,
         show_raw_inputs: :boolean,
         show_raw_expected: :boolean,
         show_raw_received: :boolean,
@@ -66,7 +67,7 @@ module Canon
         def all_diff_attributes
           %i[mode use_color context_lines grouping_lines show_diffs
-             verbose_diff algorithm show_raw_inputs show_raw_expected show_raw_received
+             verbose_diff algorithm parser show_raw_inputs show_raw_expected show_raw_received
              show_preprocessed_inputs show_preprocessed_expected show_preprocessed_received
              show_prettyprint_inputs show_prettyprint_expected show_prettyprint_received
              show_line_numbered_inputs character_visualization

data/lib/canon/config/profiles/metanorma.yml CHANGED Viewed

@@ -28,6 +28,9 @@ formats:
   xml:
     match:
       profile: spec_friendly
+      # Treat different Unicode whitespace types (space, NBSP, ideographic space, etc.)
+      # as equivalent — useful for spec comparisons where whitespace type doesn't matter
+      whitespace_type: :normalize
       # Elements where whitespace is PRESERVED exactly (no manipulation)
       # All whitespace characters are significant in these elements
       preserve_whitespace_elements:

data/lib/canon/config.rb CHANGED Viewed

@@ -285,6 +285,7 @@ module Canon
       end
       def indent_type=(value)
+        DiffConfig.validate_config_value!(:pretty_printer_indent_type, value)
         @resolver.set_programmatic(:pretty_printer_indent_type, value)
       end
     end
@@ -293,6 +294,20 @@ module Canon
     class DiffConfig
       attr_reader :pretty_printer
+      # Valid values for enum-like configuration options
+      VALID_ENUM_VALUES = {
+        mode: %i[by_line by_object pretty_diff],
+        show_diffs: %i[all normative informative],
+        algorithm: %i[dom semantic],
+        parser: %i[sax dom],
+        display_preprocessing: %i[none pretty_print normalize_pretty_print
+                                  c14n],
+        display_format: %i[raw canonical],
+        pretty_printer_indent_type: %i[space tab],
+        character_visualization: [true, false, :content_only],
+        theme: %i[light dark retro claude cyberpunk],
+      }.freeze
       def initialize(format = nil)
         @format = format
         @resolver = build_resolver(format)
@@ -309,7 +324,9 @@ module Canon
         data.each do |key, value|
           sym_key = key.to_sym
-          @resolver.set_profile(sym_key, coerce_profile_value(sym_key, value))
+          coerced = coerce_profile_value(sym_key, value)
+          self.class.validate_config_value!(sym_key, coerced)
+          @resolver.set_profile(sym_key, coerced)
         end
       end
@@ -317,12 +334,25 @@ module Canon
         @resolver.clear_profile!
       end
+      # Validate a config value against its allowed enum values
+      def self.validate_config_value!(key, value)
+        valid = VALID_ENUM_VALUES[key]
+        return unless valid
+        return if valid.include?(value)
+        raise ArgumentError,
+              "Invalid value #{value.inspect} for #{key}. " \
+              "Valid values: #{valid.map(&:inspect).join(', ')}"
+      end
       # Accessors with ENV override support
       def mode
         @resolver.resolve(:mode)
       end
       def mode=(value)
+        self.class.validate_config_value!(:mode, value)
         @resolver.set_programmatic(:mode, value)
       end
@@ -355,6 +385,7 @@ module Canon
       end
       def show_diffs=(value)
+        self.class.validate_config_value!(:show_diffs, value)
         @resolver.set_programmatic(:show_diffs, value)
       end
@@ -495,6 +526,7 @@ module Canon
       end
       def display_format=(value)
+        self.class.validate_config_value!(:display_format, value)
         @resolver.set_programmatic(:display_format, value)
       end
@@ -511,6 +543,7 @@ module Canon
       end
       def display_preprocessing=(value)
+        self.class.validate_config_value!(:display_preprocessing, value)
         @resolver.set_programmatic(:display_preprocessing, value)
       end
@@ -620,10 +653,8 @@ module Canon
       # Values:
       #   true          - apply the full default visualization map (default)
       #   false         - disable visualization; output plain text
-      #   :content_only - reserved for future use; currently behaves as +true+.
-      #                   Future intent: apply visualization only to DOM text
-      #                   node content, not to structural indentation whitespace.
-      #                   (TODO: implement DOM-level pre-serialization pass)
+      #   :content_only - apply visualization only to text content, not
+      #                   to structural indentation whitespace.
       def character_visualization
         val = @resolver.resolve(:character_visualization)
         # Coerce symbol booleans that may arrive via ENV (env_schema uses :symbol type
@@ -636,6 +667,7 @@ module Canon
       end
       def character_visualization=(value)
+        self.class.validate_config_value!(:character_visualization, value)
         @resolver.set_programmatic(:character_visualization, value)
       end
@@ -644,15 +676,27 @@ module Canon
       end
       def algorithm=(value)
+        self.class.validate_config_value!(:algorithm, value)
         @resolver.set_programmatic(:algorithm, value)
       end
+      # XML parser backend (:sax or :dom, default :sax)
+      def parser
+        @resolver.resolve(:parser)
+      end
+      def parser=(value)
+        self.class.validate_config_value!(:parser, value)
+        @resolver.set_programmatic(:parser, value)
+      end
       # Theme name (:light, :dark, :retro, :claude)
       def theme
         @resolver.resolve(:theme)
       end
       def theme=(value)
+        self.class.validate_config_value!(:theme, value)
         @resolver.set_programmatic(:theme, value)
       end
@@ -693,6 +737,7 @@ module Canon
           show_diffs: show_diffs,
           verbose_diff: verbose_diff,
           diff_algorithm: algorithm,
+          parser: parser,
           show_raw_inputs: show_raw_inputs,
           show_raw_expected: show_raw_expected,
           show_raw_received: show_raw_received,
@@ -733,6 +778,7 @@ module Canon
           show_diffs: :all,
           verbose_diff: false,
           algorithm: :dom,
+          parser: :sax,
           show_raw_inputs: false,
           show_raw_expected: false,
           show_raw_received: false,

data/lib/canon/diff/diff_classifier.rb CHANGED Viewed

@@ -150,8 +150,9 @@ module Canon
       end
       # Check if the text node is inside a whitespace-sensitive element
-      # (preserve/collapse classification or xml:space='preserve').
-      # In these elements, whitespace presence is meaningful and should
+      # (preserve/collapse classification, xml:space='preserve', or
+      # between inline element siblings in HTML).
+      # In these contexts, whitespace presence is meaningful and should
       # not be dismissed as serialization formatting.
       # @param diff_node [DiffNode] The diff node to check
       # @return [Boolean] true if whitespace is preserved for this element
@@ -159,6 +160,21 @@ module Canon
         node = diff_node.node1 || diff_node.node2
         return false unless node
+        # HTML: whitespace between inline element siblings is significant
+        if Canon::Comparison::WhitespaceSensitivity.inline_whitespace_significant?(node)
+          return true
+        end
+        # HTML: non-breaking space (U+00A0) is never insignificant
+        text = if node.respond_to?(:content)
+                 node.content
+               elsif node.respond_to?(:value)
+                 node.value
+               end
+        if text && Canon::Comparison::WhitespaceSensitivity.contains_nbsp?(text)
+          return true
+        end
         return false unless node.respond_to?(:parent)
         parent = node.parent

data/lib/canon/diff/diff_line_builder.rb CHANGED Viewed

@@ -858,12 +858,14 @@ new_line_ranges)
       # The DiffNode's explicit formatting? flag takes precedence:
       # - If formatting? == true: return true (explicitly formatting-only)
       #
-      # If node exists and is normative (formatting? is nil but norm is true):
-      # - Check line-level formatting via FormattingDetector for whitespace-only changes
-      # - But NOT via comment_only_line? heuristic because comment content is different
+      # If node exists and is normative:
+      # - Return false — normative DiffNodes are NEVER formatting-only.
+      #   Even if the serialized content looks whitespace-equivalent,
+      #   the comparison classified it as a normative change and it MUST
+      #   be visible in by_line output (especially with show_diffs: :normative).
       #
       # If node exists and is informative (norm=false):
-      # - Return false (informative diffs are always shown as informative)
+      # - Return false (informative diffs are shown as informative)
       #
       # If NO node exists (diff_node is nil):
       # - Use heuristics: comment-only lines and FormattingDetector
@@ -877,11 +879,10 @@ new_line_ranges)
         return true if diff_node&.formatting?
         if diff_node
-          # Node exists - use node classification
-          return false unless diff_node.normative?
+          # Normative nodes are never formatting-only
+          return false if diff_node.normative?
-          # For normative nodes, check line-level formatting
-          # (but NOT comment_only_line? which would misclassify comment content changes)
+          # Informative nodes: check line-level formatting
         elsif comment_only_line?(line1) || comment_only_line?(line2)
           # No DiffNode: use heuristics
           return true

data/lib/canon/diff_formatter/by_line/base_formatter.rb CHANGED Viewed

@@ -45,11 +45,13 @@ module Canon
           end
         end
+        # rubocop:disable Metrics/ParameterLists
         def initialize(use_color: true, context_lines: 3,
                        diff_grouping_lines: nil, visualization_map: nil,
                        show_diffs: :all, differences: [],
                        diff_mode: :separate, legacy_terminal: false,
-                       equivalent: nil, theme: nil)
+                       equivalent: nil, theme: nil,
+                       character_visualization: true)
           @use_color = use_color
           @context_lines = context_lines
           @diff_grouping_lines = diff_grouping_lines
@@ -61,7 +63,9 @@ module Canon
           @legacy_terminal = legacy_terminal
           @equivalent = equivalent
           @theme = theme
+          @character_visualization = character_visualization
         end
+        # rubocop:enable Metrics/ParameterLists
         # Get the resolved theme hash
         # @return [Hash] Theme hash
@@ -644,15 +648,23 @@ module Canon
         # Apply character visualization
         #
+        # When +character_visualization+ is +:content_only+, leading
+        # structural whitespace (indentation) is left plain while content
+        # whitespace is visualized.
+        #
         # @param token [String] The token to apply visualization to
         # @param color [Symbol, nil] Optional color to apply
         # @return [String] Visualized and optionally colored token
         def apply_visualization(token, color = nil)
           return "" if token.nil?
-          visual = token.to_s.chars.map do |char|
-            @visualization_map.fetch(char, char)
-          end.join
+          visual = if @character_visualization == :content_only
+                     visualize_content_only(token.to_s)
+                   else
+                     token.to_s.chars.map do |char|
+                       @visualization_map.fetch(char, char)
+                     end.join
+                   end
           if color && @use_color
             require "rainbow"
@@ -678,6 +690,29 @@ module Canon
           end
         end
+        # Visualize only content portion, leaving structural indentation plain.
+        #
+        # Splits the token into leading whitespace (structural indentation)
+        # and the rest (content). Only the content portion gets character
+        # visualization.
+        #
+        # @param token [String] The full line token
+        # @return [String] Token with content-only visualization
+        def visualize_content_only(token)
+          # Leading whitespace is structural indentation — keep it plain
+          indent_end = token.index(/[^\s]/) || token.length
+          indent = token[0...indent_end]
+          content = token[indent_end..]
+          if content.nil? || content.empty?
+            indent
+          else
+            indent + content.chars.map { |char|
+              @visualization_map.fetch(char, char)
+            }.join
+          end
+        end
         # Get max diff lines limit
         #
         # @return [Integer, nil] Max diff output lines

data/lib/canon/diff_formatter/by_line/html_formatter.rb CHANGED Viewed

@@ -12,19 +12,22 @@ module Canon
       class HtmlFormatter < BaseFormatter
         attr_reader :html_version
+        # rubocop:disable Metrics/ParameterLists
         def initialize(use_color: true, context_lines: 3,
                        diff_grouping_lines: nil, visualization_map: nil,
                        html_version: :html4, show_diffs: :all, differences: [],
                        diff_mode: :separate, legacy_terminal: false,
-                       equivalent: nil)
+                       equivalent: nil, character_visualization: true)
           super(use_color: use_color, context_lines: context_lines,
                 diff_grouping_lines: diff_grouping_lines,
                 visualization_map: visualization_map,
                 show_diffs: show_diffs, differences: differences,
                 diff_mode: diff_mode, legacy_terminal: legacy_terminal,
-                equivalent: equivalent)
+                equivalent: equivalent,
+                character_visualization: character_visualization)
           @html_version = html_version
         end
+        # rubocop:enable Metrics/ParameterLists
         # Format DOM-guided HTML diff
         #

data/lib/canon/diff_formatter/by_line_formatter.rb ADDED Viewed

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+require "paint"
+module Canon
+  class DiffFormatter
+    # Handles the by_line rendering pipeline for line-by-line diffs.
+    #
+    # Receives preprocessed document strings from the DiffFormatter facade
+    # and delegates to format-specific ByLine formatters (XML, HTML, JSON, YAML).
+    class ByLineFormatter
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(use_color:, visualization_map:, context_lines:,
+                     diff_grouping_lines:, show_diffs:, character_visualization:,
+                     legacy_terminal:, diff_mode:)
+        @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
+      end
+      # rubocop:enable Metrics/ParameterLists
+      # Format a line-by-line diff between two documents.
+      #
+      # @param doc1 [String] First document (already preprocessed)
+      # @param doc2 [String] Second document (already preprocessed)
+      # @param format [Symbol] Document format (:xml, :html, :json, :yaml, etc.)
+      # @param html_version [Symbol, nil] HTML version override (:html4, :html5)
+      # @param differences [Array, ComparisonResult] Differences from comparison
+      # @return [String] Formatted diff output
+      def format(doc1, doc2, format:, html_version: nil, differences: [])
+        resolved_format = format == :html && html_version ? html_version : format
+        format_name = resolved_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?
+        diffs_array = extract_differences(differences)
+        formatter = ByLine::BaseFormatter.for_format(
+          resolved_format,
+          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,
+          character_visualization: @character_visualization,
+        )
+        output << formatter.format(doc1, doc2)
+        output.join("\n")
+      end
+      private
+      def extract_differences(differences)
+        if differences.is_a?(Canon::Comparison::ComparisonResult)
+          @comparison_equivalent = differences.equivalent?
+          differences.differences
+        else
+          @comparison_equivalent = nil
+          differences
+        end
+      end
+      def colorize(text, *colors)
+        return text unless @use_color
+        "\e[0m#{Paint[text, *colors]}"
+      end
+    end
+  end
+end

data/lib/canon/diff_formatter/by_object_formatter.rb ADDED Viewed

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+require "paint"
+module Canon
+  class DiffFormatter
+    # Handles the by_object rendering pipeline for tree-based semantic diffs.
+    #
+    # Delegates to format-specific ByObject formatters (XML, JSON, YAML)
+    # which produce visual tree output with box-drawing characters.
+    class ByObjectFormatter
+      def initialize(use_color:, visualization_map:, show_diffs:)
+        @use_color = use_color
+        @visualization_map = visualization_map
+        @show_diffs = show_diffs
+      end
+      # Format a tree-based object diff.
+      #
+      # @param differences [Array, ComparisonResult] Differences from comparison
+      # @param format [Symbol] Document format (:xml, :json, :yaml)
+      # @return [String] Formatted diff output
+      def format(differences, format)
+        output = []
+        output << colorize("Visual Diff:", :cyan, :bold)
+        diffs_array = if differences.is_a?(Canon::Comparison::ComparisonResult)
+                        differences.differences
+                      else
+                        differences
+                      end
+        formatter = ByObject::BaseFormatter.for_format(
+          format,
+          use_color: @use_color,
+          visualization_map: @visualization_map,
+          show_diffs: @show_diffs,
+        )
+        output << formatter.format(diffs_array, format)
+        output.join("\n")
+      end
+      private
+      def colorize(text, *colors)
+        return text unless @use_color
+        "\e[0m#{Paint[text, *colors]}"
+      end
+    end
+  end
+end