canon 0.1.21 → 0.1.23

data/docs/internals/index.adoc

@@ -24,6 +24,9 @@ These documents are intended for:
 link:diffnode-enrichment[**DiffNode Enrichment**]::
 How DiffNode objects carry location, serialized content, and attribute metadata through the comparison pipeline. Covers PathBuilder (canonical paths with ordinal indices), NodeSerializer (library-agnostic serialization), and how Layer 2 algorithms populate metadata for Layer 4 rendering.
 
+link:diff-char-range-pipeline[**DiffCharRange Pipeline**]::
+How enriched DiffNodes are processed into character-level diff ranges for precise rendering. Covers DiffNodeEnricher (Phase 1: locating serialized content and decomposing changes), DiffLineBuilder (Phase 2: assembling DiffLines from enriched DiffNodes), DiffCharRange (character position value objects), TextDecomposer (prefix/suffix decomposition), and SourceLocator (finding content positions in source text).
+
 link:../advanced/dom-diff-internals[**DOM Diff Internals**]::
 Deep dive into Canon's default DOM diff algorithm: position-based matching, operation detection, and diff generation.
 
@@ -80,17 +83,23 @@ graph LR
     B -->|Enriches| D[DiffNode.path]
     C -->|Enriches| E[DiffNode.serialized_before/after]
     C -->|Enriches| F[DiffNode.attributes_before/after]
-    D --> G[Layer 4: Rendering]
+    D --> G[Phase 1: DiffNodeEnricher]
     E --> G
     F --> G
-    G --> H[Accurate diff output]
+    G -->|Enriches| H[DiffNode.char_ranges]
+    G -->|Enriches| I[DiffNode.line_range_before/after]
+    H --> J[Phase 2: DiffLineBuilder]
+    I --> J
+    J --> K[DiffLine with DiffCharRange[]]
+    K --> L[Layer 4: Rendering]
 
     style A fill:#fff4e1
     style D fill:#e1f5ff
-    style G fill:#e1ffe1
+    style G fill:#ffe1f5
+    style K fill:#e1ffe1
 ----
 
-Key insight: Metadata is captured at diff creation time (Layer 2) and carried through to rendering (Layer 4), ensuring accurate display even if nodes are modified during comparison.
+Key insight: Metadata is captured at diff creation time (Layer 2), enriched with character positions (Phase 1), assembled into display lines (Phase 2), and rendered without further computation (Layer 4).
 
 == Data Structures
 
@@ -112,11 +121,50 @@ class DiffNode
   attr_accessor :serialized_after      # Serialized "after" content
   attr_accessor :attributes_before     # Normalized "before" attributes
   attr_accessor :attributes_after      # Normalized "after" attributes
+
+  # Character-level enrichment (Phase 1 enrichment pipeline)
+  attr_accessor :char_ranges           # Array<DiffCharRange>
+  attr_accessor :line_range_before     # [start_line, end_line] in text1
+  attr_accessor :line_range_after      # [start_line, end_line] in text2
 end
 ----
 
 See link:diffnode-enrichment[DiffNode Enrichment] for details.
 
+=== DiffLine
+
+Represents a single line in the diff output, linked to semantic DiffNode and character-level DiffCharRanges:
+
+[source,ruby]
+----
+class DiffLine
+  attr_reader :line_number, :new_position, :content, :type, :diff_node,
+              :char_ranges, :new_char_ranges, :new_content
+  attr_accessor :old_content, :formatting
+
+  # type: :unchanged, :added, :removed, :changed
+  # char_ranges: text1 side DiffCharRange[]
+  # new_char_ranges: text2 side DiffCharRange[]
+  # new_content: text2 line text (for :changed lines)
+end
+----
+
+=== DiffCharRange
+
+Character-level position within a source line, linked to a DiffNode:
+
+[source,ruby]
+----
+class DiffCharRange
+  attr_reader :line_number, :start_col, :end_col, :side, :status, :role,
+              :diff_node
+
+  # side: :old (text1) or :new (text2)
+  # status: :unchanged, :removed, :added, :changed_old, :changed_new
+  # role: :before, :changed, :after
+end
+----
+
 === TreeNode (Semantic Diff)
 
 Canonical node representation from semantic diff:

data/docs/reference/environment-variables.adoc

@@ -142,6 +142,12 @@ export CANON_JSON_FORMAT_PREPROCESSING=normalize
 |`10000`
 |Maximum number of diff output lines
 |All formats
+
+|`CANON_DIFF_THEME`
+|symbol
+|`:dark`
+|Diff display theme: `light`, `dark`, `retro`, `claude`, `cyberpunk`
+|All formats
 |===
 
 === Match Configuration Variables

data/docs/understanding/architecture.adoc

@@ -889,6 +889,11 @@ class DiffNode
   attr_accessor :serialized_after      # Serialized "after" content
   attr_accessor :attributes_before     # Normalized "before" attributes
   attr_accessor :attributes_after      # Normalized "after" attributes
+
+  # Character-level enrichment (populated by DiffNodeEnricher)
+  attr_accessor :char_ranges           # Array<DiffCharRange> char positions
+  attr_accessor :line_range_before     # [start_line, end_line] in text1
+  attr_accessor :line_range_after      # [start_line, end_line] in text2
 end
 ----
 

data/examples/show_themes.rb

@@ -0,0 +1,217 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example script demonstrating all available diff display themes.
+# Run with: bundle exec ruby examples/show_themes.rb
+#
+# This script shows how the same XML diff renders under each theme:
+#   - :light     - Light terminal backgrounds
+#   - :dark      - Dark terminal backgrounds (default)
+#   - :retro     - Amber CRT phosphor look
+#   - :claude    - Claude Code diff style (red/green backgrounds)
+#   - :cyberpunk - Neon on black, high contrast, futuristic
+
+require "bundler/setup"
+require "canon"
+require "canon/diff_formatter"
+
+# Sample XML documents with meaningful differences
+# These documents have:
+# - A deleted element (the <old-item>)
+# - An added element (the <new-item>)
+# - A changed attribute (version="1.0" -> version="2.0")
+# - A changed text content ("Old Text" -> "New Text")
+# - Whitespace-only change (formatting)
+# - An informative comment difference
+
+XML1 = <<~XML
+  <?xml version="1.0" encoding="UTF-8"?>
+  <document version="1.0">
+    <header>
+      <!-- Original comment -->
+      <title>Document Title</title>
+    </header>
+    <content>
+      <old-item name="thing1">Old Text</old-item>
+      <common-item>Shared content</common-item>
+      <common-item>More shared content</common-item>
+    </content>
+    <footer>
+      <note>Footer note</note>
+    </footer>
+  </document>
+XML
+
+XML2 = <<~XML
+  <?xml version="1.0" encoding="UTF-8"?>
+  <document version="2.0">
+    <header>
+      <!-- Updated comment -->
+      <title>Document Title</title>
+    </header>
+    <content>
+      <new-item name="thing2">New Text</new-item>
+      <common-item>Shared content</common-item>
+      <common-item>More shared content</common-item>
+      <extra-item>Additional item</extra-item>
+    </content>
+    <footer>
+      <note>Footer note</note>
+    </footer>
+  </document>
+XML
+
+# Helper to run diff with a specific theme and display mode
+def run_diff_with_theme(theme_name, xml1, xml2, display_mode: :separate)
+  Canon::Config.reset!
+  Canon::Config.configure do |config|
+    config.xml.diff.theme = theme_name
+  end
+
+  # Use semantic diff to get all differences reported, even when documents
+  # are not equivalent. DOM diff stops at the first difference.
+  result = Canon::Comparison.equivalent?(xml1, xml2, diff_algorithm: :semantic,
+                                                     verbose: true)
+
+  formatter = Canon::DiffFormatter.new(
+    use_color: true,
+    mode: :by_line,
+    show_diffs: :all,
+    diff_mode: display_mode,
+  )
+
+  formatter.format(result, :xml, doc1: xml1, doc2: xml2)
+end
+
+# Helper to print section header
+def print_header(title)
+  puts
+  puts "=" * 70
+  puts title
+  puts "=" * 70
+end
+
+# Helper to strip ANSI codes for plain text display
+def strip_ansi(text)
+  text.gsub(/\e\[[0-9;]*m/, "")
+end
+
+# Main demonstration
+puts
+puts "DIFF DISPLAY THEME DEMONSTRATION"
+puts "=" * 70
+puts
+puts "This script demonstrates how the same XML diff renders under"
+puts "each of the 5 available themes. Each theme has different:"
+puts "  - Color schemes (light vs dark backgrounds)"
+puts "  - Marker styles ([, ], <, >, -, +)"
+puts "  - Visual emphasis (backgrounds vs foreground colors)"
+puts
+puts "Sample documents have these differences:"
+puts "  - Attribute change: version=\"1.0\" -> version=\"2.0\""
+puts "  - Text change: <old-item> -> <new-item>"
+puts "  - Content change: \"Old Text\" -> \"New Text\""
+puts "  - Addition: <extra-item> added"
+puts "  - Comment change: informative difference"
+puts
+
+# Demonstrate each theme in both display modes
+themes = {
+  light: "Light Theme (light backgrounds, red/green markers with light bg)",
+  dark: "Dark Theme (dark backgrounds, saturated red/green foregrounds)",
+  retro: "Retro Theme (amber CRT phosphor, monochrome amber with inverse video)",
+  claude: "Claude Theme (red/green backgrounds + white text, maximum visual pop)",
+  cyberpunk: "Cyberpunk Theme (neon magenta/cyan on black, electric, futuristic)",
+}
+
+display_modes = {
+  separate: "Separate lines (- / + on separate lines)",
+  inline: "Inline mode (* on same line, old→new)",
+}
+
+themes.each do |theme_name, description|
+  print_header("#{theme_name.upcase} THEME: #{description}")
+
+  puts
+  puts "Theme configuration:"
+  puts "  Canon::Config.xml.diff.theme = :#{theme_name}"
+
+  display_modes.each do |mode, mode_description|
+    puts
+    puts "-" * 70
+    puts "DISPLAY MODE: #{mode.upcase} - #{mode_description}"
+    puts "-" * 70
+    puts "COLOR OUTPUT (with ANSI escape sequences):"
+
+    output = run_diff_with_theme(theme_name, XML1, XML2, display_mode: mode)
+    puts output
+
+    puts
+    puts "-" * 70
+    puts "PLAIN TEXT OUTPUT (without ANSI codes):"
+    puts strip_ansi(output)
+  end
+end
+
+# Summary table
+print_header("THEME SUMMARY")
+puts
+puts "| Theme      | Best For                      | Key Characteristics            |"
+puts "|------------|-------------------------------|--------------------------------|"
+puts "| :light     | Light terminal backgrounds    | Light marker backgrounds       |"
+puts "| :dark      | Dark terminals (default)      | Saturated foreground colors    |"
+puts "| :retro     | Low blue light / accessibility| Amber monochrome + inverse     |"
+puts "| :claude    | Maximum visual pop            | Red/green backgrounds          |"
+puts "| :cyberpunk | Neon / futuristic terminals   | Magenta/cyan neon on black     |"
+puts
+
+# How to use programmatically
+print_header("HOW TO USE IN CODE")
+puts
+puts "# Set theme via configuration:"
+puts "Canon::Config.configure do |config|"
+puts "  config.xml.diff.theme = :claude"
+puts "end"
+puts
+puts "# Or via ENV variable:"
+puts "ENV['CANON_DIFF_THEME'] = 'claude'"
+puts
+puts "# Or for a single diff, pass theme to formatter:"
+puts "formatter = Canon::DiffFormatter.new("
+puts "  use_color: true,"
+puts "  mode: :by_line,"
+puts "  show_diffs: :all,"
+puts "  theme: :retro  # if supported by the formatter"
+puts ")"
+puts
+
+# Theme inheritance example
+print_header("THEME INHERITANCE (advanced)")
+puts
+puts "# Create custom theme inheriting from :dark with overrides:"
+puts "Canon::Config.configure do |config|"
+puts "  config.xml.diff.theme_inheritance = {"
+puts "    base: :dark,"
+puts "    overrides: {"
+puts "      diff: {"
+puts "        removed: { content: { bg: :light_red } }"
+puts "      }"
+puts "    }"
+puts "  }"
+puts "end"
+puts
+
+# Note about Rainbow gem limitations
+print_header("NOTE: RAINBOW GEM LIMITATIONS")
+puts
+puts "The Rainbow gem (used for terminal colors) doesn't support"
+puts ":bright_black or :bright_white in standard 16-color mode."
+puts "Themes substitute compatible colors:"
+puts "  - DARK theme uses :white instead of :bright_white"
+puts "  - LIGHT theme uses :black instead of :bright_black"
+puts "  - Comments use :cyan or :magenta instead of :bright_black"
+puts
+
+puts "=" * 70
+puts "END OF THEME DEMONSTRATION"
+puts "=" * 70

data/lib/canon/comparison/comparison_result.rb

@@ -90,9 +90,11 @@ html_version: nil, match_options: nil, algorithm: :dom, original_strings: nil)
       # @param context_lines [Integer] Number of context lines to show
       # @param diff_grouping_lines [Integer] Maximum gap for grouping diffs
       # @param show_diffs [Symbol] Which diffs to show (:all, :normative, :informative)
+      # @param diff_mode [Symbol] Diff display mode (:separate, :inline)
+      # @param legacy_terminal [Boolean] Force legacy mode (no ANSI, separate-line only)
       # @return [String] Formatted diff output
       def diff(use_color: true, context_lines: 3, diff_grouping_lines: nil,
-show_diffs: :all)
+show_diffs: :all, diff_mode: :separate, legacy_terminal: false)
         require_relative "../diff_formatter"
 
         formatter = Canon::DiffFormatter.new(
@@ -101,13 +103,16 @@ show_diffs: :all)
           context_lines: context_lines,
           diff_grouping_lines: diff_grouping_lines,
           show_diffs: show_diffs,
+          diff_mode: diff_mode,
+          legacy_terminal: legacy_terminal,
         )
 
+        # Pass self (ComparisonResult) so formatter can check equivalent? status
         formatter.format(
-          @differences,
+          self,
           @format,
-          doc1: @original_strings[0],
-          doc2: @original_strings[1],
+          doc1: @preprocessed_strings[0],
+          doc2: @preprocessed_strings[1],
           html_version: @html_version,
         )
       end

data/lib/canon/config/env_schema.rb

@@ -18,6 +18,7 @@ module Canon
         show_preprocessed_inputs: :boolean,
         show_line_numbered_inputs: :boolean,
         display_format: :symbol,
+        theme: :symbol,
 
         # MatchConfig attributes
         profile: :symbol,
@@ -47,7 +48,8 @@ module Canon
         def all_diff_attributes
           %i[mode use_color context_lines grouping_lines show_diffs
              verbose_diff algorithm show_raw_inputs show_preprocessed_inputs
-             show_line_numbered_inputs display_format max_file_size max_node_count max_diff_lines]
+             show_line_numbered_inputs display_format max_file_size max_node_count max_diff_lines
+             theme]
         end
 
         def all_match_attributes

data/lib/canon/config.rb

@@ -262,6 +262,15 @@ module Canon
         @resolver.set_programmatic(:algorithm, value)
       end
 
+      # Theme name (:light, :dark, :retro, :claude)
+      def theme
+        @resolver.resolve(:theme)
+      end
+
+      def theme=(value)
+        @resolver.set_programmatic(:theme, value)
+      end
+
       # File size limit in bytes (default 5MB)
       def max_file_size
         @resolver.resolve(:max_file_size)
@@ -306,6 +315,7 @@ module Canon
           max_file_size: max_file_size,
           max_node_count: max_node_count,
           max_diff_lines: max_diff_lines,
+          theme: theme,
         }
       end
 
@@ -327,6 +337,7 @@ module Canon
           max_file_size: 5_242_880, # 5MB in bytes
           max_node_count: 10_000,   # Maximum nodes in tree
           max_diff_lines: 10_000,   # Maximum diff output lines
+          theme: :dark, # Default theme
         }
 
         env = format ? EnvProvider.load_diff_for_format(format) : {}

data/lib/canon/diff/diff_block.rb

@@ -42,6 +42,13 @@ diff_node: nil)
         !normative?
       end
 
+      # @return [Boolean] true if all lines in this block are formatting-only
+      def formatting?
+        return false if diff_lines.empty?
+
+        diff_lines.all?(&:formatting?)
+      end
+
       # Check if this block contains a specific type of change
       def includes_type?(type)
         types.include?(type)

data/lib/canon/diff/diff_block_builder.rb

@@ -95,9 +95,9 @@ module Canon
         when :normative
           blocks.select(&:normative?)
         when :informative
-          blocks.select(&:informative?)
+          blocks.select { |b| b.informative? && !b.formatting? }
         else # :all
-          blocks
+          blocks.reject(&:formatting?)
         end
       end
     end

data/lib/canon/diff/diff_char_range.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Represents a character range within a source line, linked to a DiffNode.
+    #
+    # DiffCharRange is the core abstraction for character-level diff rendering.
+    # Each DiffNode produces one or more DiffCharRanges (before-text, changed-text,
+    # after-text) that tell the formatter exactly which characters to highlight.
+    #
+    # The formatter reads DiffCharRanges and applies colors — no computation needed.
+    #
+    # @example Text change "Hello World" → "Hello Universe"
+    #   # Before-text (unchanged):
+    #   DiffCharRange.new(line_number: 0, start_col: 9, end_col: 15,
+    #                     side: :old, status: :unchanged, role: :before, diff_node: dn)
+    #   # Changed-text (old side):
+    #   DiffCharRange.new(line_number: 0, start_col: 15, end_col: 20,
+    #                     side: :old, status: :changed_old, role: :changed, diff_node: dn)
+    #   # Changed-text (new side):
+    #   DiffCharRange.new(line_number: 0, start_col: 15, end_col: 23,
+    #                     side: :new, status: :changed_new, role: :changed, diff_node: dn)
+    class DiffCharRange
+      # @return [Integer] 0-based line index in text1 or text2
+      attr_reader :line_number
+
+      # @return [Integer] 0-based column offset (inclusive start)
+      attr_reader :start_col
+
+      # @return [Integer] exclusive end (half-open [start_col, end_col))
+      attr_reader :end_col
+
+      # @return [Symbol] :old (text1) or :new (text2)
+      attr_reader :side
+
+      # @return [Symbol] :unchanged, :removed, :added, :changed_old, :changed_new
+      attr_reader :status
+
+      # @return [Symbol] :before, :changed, :after
+      attr_reader :role
+
+      # @return [DiffNode, nil] the originating DiffNode
+      attr_reader :diff_node
+
+      # @param line_number [Integer] 0-based line index
+      # @param start_col [Integer] 0-based column (inclusive)
+      # @param end_col [Integer] exclusive end
+      # @param side [Symbol] :old or :new
+      # @param status [Symbol] :unchanged, :removed, :added, :changed_old, :changed_new
+      # @param role [Symbol] :before, :changed, :after
+      # @param diff_node [DiffNode, nil] originating DiffNode
+      def initialize(line_number:, start_col:, end_col:, side:, status:,
+                     role: nil, diff_node: nil)
+        @line_number = line_number
+        @start_col = start_col
+        @end_col = end_col
+        @side = side
+        @status = status
+        @role = role
+        @diff_node = diff_node
+      end
+
+      # @return [Boolean] true if this range has zero length
+      def empty?
+        start_col >= end_col
+      end
+
+      # @return [Integer] number of characters in this range
+      def length
+        end_col - start_col
+      end
+
+      # @param line_length [Integer] total length of the line
+      # @return [Boolean] true if this range covers the entire line
+      def covers_entire_line?(line_length)
+        start_col.zero? && end_col >= line_length
+      end
+
+      # Extract the substring this range covers from a line
+      # @param line_text [String] the full line text
+      # @return [String] the substring, or "" if out of bounds
+      def extract_from(line_text)
+        return "" if line_text.nil? || empty?
+
+        line_text[start_col...end_col] || ""
+      end
+
+      # @return [Boolean] true if this is an old-side (text1) range
+      def old_side?
+        side == :old
+      end
+
+      # @return [Boolean] true if this is a new-side (text2) range
+      def new_side?
+        side == :new
+      end
+
+      # @return [Boolean] true if this range represents unchanged content
+      def unchanged?
+        status == :unchanged
+      end
+
+      # @return [Boolean] true if this range represents a change on the old side
+      def changed_old?
+        status == :changed_old
+      end
+
+      # @return [Boolean] true if this range represents a change on the new side
+      def changed_new?
+        status == :changed_new
+      end
+
+      # @return [Boolean] true if this range should be highlighted
+      def highlighted?
+        %i[changed_old changed_new removed added].include?(status)
+      end
+
+      def to_h
+        {
+          line_number: line_number,
+          start_col: start_col,
+          end_col: end_col,
+          side: side,
+          status: status,
+          role: role,
+        }
+      end
+
+      def ==(other)
+        other.is_a?(DiffCharRange) &&
+          line_number == other.line_number &&
+          start_col == other.start_col &&
+          end_col == other.end_col &&
+          side == other.side &&
+          status == other.status &&
+          role == other.role
+      end
+    end
+  end
+end

data/lib/canon/diff/diff_line.rb

@@ -3,26 +3,61 @@
 module Canon
   module Diff
     # Represents a single line in the diff output
-    # Links textual representation to semantic DiffNode
+    # Links textual representation to semantic DiffNode and DiffCharRanges
     class DiffLine
-      attr_reader :line_number, :new_position, :content, :type, :diff_node
+      attr_reader :line_number, :new_position, :content, :type, :diff_node,
+                  :char_ranges, :new_char_ranges, :new_content
+      attr_accessor :old_content
       attr_writer :formatting
 
       # @param line_number [Integer] The 0-based line number in text1 (old text)
       # @param new_position [Integer, nil] The 0-based line number in text2 (new text),
       #   used for :changed lines where old and new positions differ
-      # @param content [String] The text content of the line
+      # @param content [String] The text content of the line (from text1)
       # @param type [Symbol] The type of line (:unchanged, :added, :removed, :changed)
       # @param diff_node [DiffNode, nil] The semantic diff node this line belongs to
       # @param formatting [Boolean] Whether this is a formatting-only difference
+      # @param char_ranges [Array<DiffCharRange>] Character ranges for text1 side
+      # @param new_char_ranges [Array<DiffCharRange>] Character ranges for text2 side
+      # @param new_content [String, nil] The text2 line content (for :changed lines)
+      # @param old_content [String, nil] Deprecated: multi-line old content
       def initialize(line_number:, content:, type:, diff_node: nil,
-                     formatting: false, new_position: nil)
+                     formatting: false, new_position: nil, old_content: nil,
+                     char_ranges: nil, new_char_ranges: nil, new_content: nil)
         @line_number = line_number
         @new_position = new_position
         @content = content
         @type = type
         @diff_node = diff_node
         @formatting = formatting
+        @old_content = old_content
+        @char_ranges = char_ranges || []
+        @new_char_ranges = new_char_ranges || []
+        @new_content = new_content
+      end
+
+      # Add a character range for the text1 (old) side
+      # @param char_range [DiffCharRange]
+      def add_char_range(char_range)
+        @char_ranges << char_range
+      end
+
+      # Add a character range for the text2 (new) side
+      # @param char_range [DiffCharRange]
+      def add_new_char_range(char_range)
+        @new_char_ranges << char_range
+      end
+
+      # @return [Boolean] true if this line has any character ranges
+      def has_char_ranges?
+        !@char_ranges.empty? || !@new_char_ranges.empty?
+      end
+
+      # Get character ranges for a specific side
+      # @param side [Symbol] :old or :new
+      # @return [Array<DiffCharRange>]
+      def char_ranges_for_side(side)
+        side == :old ? @char_ranges : @new_char_ranges
       end
 
       # @return [Boolean] true if this line represents a normative difference
@@ -77,11 +112,14 @@ module Canon
           line_number: line_number,
           new_position: new_position,
           content: content,
+          new_content: new_content,
           type: type,
           diff_node: diff_node&.to_h,
           normative: normative?,
           informative: informative?,
           formatting: formatting?,
+          char_ranges: @char_ranges.map(&:to_h),
+          new_char_ranges: @new_char_ranges.map(&:to_h),
         }
       end