canon 0.2.3 → 0.2.5

data/lib/canon/config.rb

@@ -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

@@ -73,6 +73,16 @@ module Canon
           return diff_node
         end
 
+        # :whitespace_adjacency is a report-only re-label of an
+        # asymmetric whitespace mismatch emitted by ChildComparison's
+        # two-cursor walk.  Equivalence behaviour is unchanged — the
+        # underlying mismatch is normative regardless of match options.
+        if diff_node.dimension == :whitespace_adjacency
+          diff_node.formatting = false
+          diff_node.normative = true
+          return diff_node
+        end
+
         # THIRD: Determine if this dimension is normative based on CompareProfile
         # This respects the policy settings (strict/normalize/ignore)
         is_normative = profile.normative_dimension?(diff_node.dimension)
@@ -150,8 +160,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 +170,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
@@ -194,28 +220,21 @@ module Canon
       def extract_text_content(node)
         return nil if node.nil?
 
-        # For TextNode with value attribute (Canon::Xml::Nodes::TextNode)
-        return node.value if node.respond_to?(:value) && node.is_a?(Canon::Xml::Nodes::TextNode)
-
-        # For XML/HTML nodes with text_content method
-        return node.text_content if node.respond_to?(:text_content)
-
-        # For nodes with text method
-        return node.text if node.respond_to?(:text)
-
-        # For nodes with content method
-        return node.content if node.respond_to?(:content)
-
-        # For nodes with value method (other types)
-        return node.value if node.respond_to?(:value)
-
-        # For simple text nodes or strings
-        return node.to_s if node.is_a?(String)
-
-        # For other node types, try to_s
-        node.to_s
+        case node
+        when Canon::Xml::Nodes::TextNode
+          node.value
+        when Canon::Xml::Node
+          node.text_content
+        when Nokogiri::XML::Node
+          node.content.to_s
+        when Moxml::Node
+          node.content.to_s
+        when String
+          node
+        else
+          node.to_s
+        end
       rescue StandardError
-        # If extraction fails, return nil (not formatting-only)
         nil
       end
 
@@ -225,25 +244,20 @@ module Canon
       def text_node?(node)
         return false if node.nil?
 
-        # Canon::Xml::Nodes::TextNode
-        return true if node.is_a?(Canon::Xml::Nodes::TextNode)
-
-        # Nokogiri text nodes (node_type returns integer constant like 3)
-        return true if node.respond_to?(:node_type) &&
-          node.node_type.is_a?(Integer) &&
+        case node
+        when Canon::Xml::Nodes::TextNode
+          true
+        when Canon::Xml::Node
+          node.node_type == :text
+        when Nokogiri::XML::Node
           node.node_type == Nokogiri::XML::Node::TEXT_NODE
-
-        # Moxml text nodes (node_type returns symbol)
-        return true if node.respond_to?(:node_type) && node.node_type == :text
-
-        # String
-        return true if node.is_a?(String)
-
-        # Test doubles or objects with text node-like interface
-        # Check if it has a value method (contains text content)
-        return true if node.respond_to?(:value)
-
-        false
+        when Moxml::Node
+          node.text?
+        when String
+          true
+        else
+          false
+        end
       end
     end
   end

data/lib/canon/diff/diff_line_builder.rb

@@ -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/xml_serialization_formatter.rb

@@ -91,28 +91,20 @@ module Canon
       def self.text_node?(node)
         return false if node.nil?
 
-        # Canon::Xml::Nodes::TextNode
-        return true if node.is_a?(Canon::Xml::Nodes::TextNode)
-
-        # Moxml::Text (check before generic node_type check)
-        return true if node.is_a?(Moxml::Text)
-
-        # Nokogiri text nodes (node_type returns integer constant like 3)
-        return true if node.respond_to?(:node_type) &&
-          node.node_type.is_a?(Integer) &&
+        case node
+        when Canon::Xml::Nodes::TextNode
+          true
+        when Canon::Xml::Node
+          node.node_type == :text
+        when Nokogiri::XML::Node
           node.node_type == Nokogiri::XML::Node::TEXT_NODE
-
-        # Moxml text nodes (node_type returns symbol) - for when using Moxml adapters
-        return true if node.respond_to?(:node_type) && node.node_type == :text
-
-        # String
-        return true if node.is_a?(String)
-
-        # Test doubles or objects with text node-like interface
-        # Check if it has a value method (contains text content)
-        return true if node.respond_to?(:value)
-
-        false
+        when Moxml::Node
+          node.text?
+        when String
+          true
+        else
+          false
+        end
       end
 
       # Extract text content from a node
@@ -121,28 +113,21 @@ module Canon
       def self.extract_text_content(node)
         return nil if node.nil?
 
-        # For TextNode with value attribute (Canon::Xml::Nodes::TextNode)
-        return node.value if node.respond_to?(:value) && node.is_a?(Canon::Xml::Nodes::TextNode)
-
-        # For XML/HTML nodes with text_content method
-        return node.text_content if node.respond_to?(:text_content)
-
-        # For nodes with content method (try before text, as Moxml::Text.text returns "")
-        return node.content if node.respond_to?(:content)
-
-        # For nodes with text method
-        return node.text if node.respond_to?(:text)
-
-        # For nodes with value method (other types)
-        return node.value if node.respond_to?(:value)
-
-        # For simple text nodes or strings
-        return node.to_s if node.is_a?(String)
-
-        # For other node types, try to_s
-        node.to_s
+        case node
+        when Canon::Xml::Nodes::TextNode
+          node.value
+        when Canon::Xml::Node
+          node.text_content
+        when Nokogiri::XML::Node
+          node.content.to_s
+        when Moxml::Node
+          node.content.to_s
+        when String
+          node
+        else
+          node.to_s
+        end
       rescue StandardError
-        # If extraction fails, return nil (not a serialization difference)
         nil
       end
 

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

@@ -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

@@ -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

@@ -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

@@ -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