canon 0.1.21 → 0.1.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c93345884c8bf0f6d5c4507415bb04fa991b8361eb9e38f10fddcbebb92b2370
-  data.tar.gz: d48eb18c21f562d7e0ff533507c56c6d264600a775f04b2adf2b267b9ce4de2a
+  metadata.gz: ba5fabd7a7d0057f365952f8aecc01381ef88f2f1dd28679e9e8947945b54104
+  data.tar.gz: 3e4119f7fc69a7c2534957c7654b6a567a868208179262fc921ea1266b5a1a6c
 SHA512:
-  metadata.gz: 0cd5ed6a025b439ef76e347a8e223abcdf70c7524bc3e4e883297bfff35c68a30b0ca543c00a657c05714da9273e740c89e7cb34b3d4d0f5b9a3ea496f237530
-  data.tar.gz: a80515c239c74a58835ad6486e2fc02379166831e5555d4426607bf9b7e612e4047b50135e59caea25ed9d4c6809624a2f2a3b305f54c9c70899280f85d317dd
+  metadata.gz: 44a74c7bb2010a2aa22855258affa6889003585edba717538bb579c63f6694757b21b74bc929b07bd0f87660f0bb3bd02f158b0a91be18017e938100f1fee491
+  data.tar.gz: be61d26774ae22a5547b2ba0ec1d578b11d37be0899add26d7f14ac63c197637568b74a9d0cad76535e5ab6a82d297af7b917f225f972361f09549964917576b

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-25 12:14:38 UTC using RuboCop version 1.86.0.
+# on 2026-03-31 12:44:31 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -13,34 +13,25 @@ Gemspec/RequiredRubyVersion:
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
+# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
+Layout/EmptyLineBetweenDefs:
   Exclude:
-    - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
+    - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
-  Exclude:
-    - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
-# SupportedStylesAlignWith: start_of_line, relative_to_receiver
-Layout/IndentationWidth:
+Layout/EmptyLines:
   Exclude:
-    - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
+    - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
 
-# Offense count: 858
+# Offense count: 1094
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 48
+# Offense count: 55
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
@@ -80,33 +71,43 @@ Lint/UnusedMethodArgument:
     - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
 
-# Offense count: 238
+# Offense count: 1
+Lint/UselessConstantScoping:
+  Exclude:
+    - 'lib/canon/diff_formatter/theme.rb'
+
+# Offense count: 297
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 22
+# Offense count: 29
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Max: 85
+  Max: 92
+
+# Offense count: 1
+# Configuration parameters: CountBlocks, CountModifierForms.
+Metrics/BlockNesting:
+  Max: 4
 
-# Offense count: 198
+# Offense count: 261
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 413
+# Offense count: 485
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 104
+  Max: 146
 
-# Offense count: 46
+# Offense count: 56
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
-  Max: 9
+  Max: 10
 
-# Offense count: 162
+# Offense count: 212
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -130,11 +131,12 @@ Naming/VariableNumber:
     - 'lib/canon/comparison/markup_comparator.rb'
     - 'lib/canon/comparison/xml_comparator/diff_node_builder.rb'
 
-# Offense count: 3
+# Offense count: 4
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
     - 'lib/canon/comparison/html_comparator.rb'
+    - 'lib/canon/diff_formatter/theme.rb'
     - 'lib/canon/xml/xml_base_handler.rb'
     - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
 
@@ -144,7 +146,7 @@ Performance/CollectionLiteralInLoop:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 30
+# Offense count: 33
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -155,10 +157,10 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 707
+# Offense count: 736
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
-  Max: 43
+  Max: 44
 
 # Offense count: 8
 # This cop supports safe autocorrection (--autocorrect).
@@ -207,7 +209,7 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 546
+# Offense count: 590
 RSpec/MultipleExpectations:
   Max: 15
 
@@ -240,10 +242,11 @@ RSpec/NoExpectationExample:
     - 'spec/canon/isodoc_blockquotes_spec.rb'
     - 'spec/canon/match_scenarios_spec.rb'
 
-# Offense count: 2
+# Offense count: 4
 RSpec/RepeatedExample:
   Exclude:
     - 'spec/canon/comparison/encoding_normalization_spec.rb'
+    - 'spec/canon/diff_display_spec.rb'
 
 # Offense count: 7
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
@@ -270,17 +273,6 @@ RSpec/VerifiedDoubles:
     - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
-# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
-# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
-# FunctionalMethods: let, let!, subject, watch
-# AllowedMethods: lambda, proc, it
-Style/BlockDelimiters:
-  Exclude:
-    - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
-
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, AllowComments.
@@ -309,3 +301,11 @@ Style/IdenticalConditionalBranches:
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowedMethods.
+# AllowedMethods: infinite?, nonzero?
+Style/RedundantCondition:
+  Exclude:
+    - 'lib/canon/diff/diff_node_enricher.rb'

data/README.adoc

@@ -586,10 +586,15 @@ See link:docs/ENV_CONFIG#size-limits[ENV_CONFIG] for details on size limit confi
 
 **By-line mode**: Traditional line-by-line diff with:
 
+* **DiffCharRange pipeline**: DiffNodes are enriched with character-level positions (Phase 1: DiffNodeEnricher using SourceLocator + TextDecomposer), then assembled into display lines (Phase 2: DiffLineBuilder). The formatter only reads pre-computed positions — no tokenization or LCS during rendering.
+* **Character-level highlighting**: Within changed lines, only the specific changed characters are highlighted, not entire lines. A text change like "Hello World" → "Hello Universe" shows "World" in red and "Universe" in green, with "Hello " in default color.
+* **Inline and separate-line display modes**: Changed lines can be displayed inline (old→new on same line with effects) or as separate lines (traditional `-`/`+` format).
+* **Mixed change detection**: The `*` marker identifies lines with multiple separate changed regions, distinguishing them from simple word replacements.
+* **Legacy terminal support**: For terminals without ANSI support, forces separate-line mode with no color codes.
 * DOM-guided semantic matching for XML
-* Syntax-aware token highlighting
-* Context lines around changes
-* Whitespace visualization
+* Context lines around changes with configurable grouping
+* Whitespace visualization (`░` for spaces, `⇥` for tabs)
+* Three-tier classification with directional colors
 
 **By-object mode**: Tree-based semantic diff with:
 

data/docs/advanced/diff-pipeline.adoc

@@ -84,17 +84,21 @@ end
 
 == Layer 3: Mapping
 
-**Responsibility**: Map semantic diffs to text line positions
+**Responsibility**: Enrich semantic diffs with character-level positions and map to text lines
 
 **Input**: DiffNode array + original text documents
 
 **Process**:
-1. Run text diff (Diff::LCS) on original strings
-2. For each changed line, find corresponding DiffNode
-3. Create DiffLine linking line ↔ DiffNode
-4. Inherit normative/informative from DiffNode
+1. **Enrichment** (DiffNodeEnricher): For each DiffNode, locate serialized content in source text and decompose into character ranges
+   - SourceLocator: Find serialized content position (char offset, line, column)
+   - TextDecomposer: Split into common prefix / changed / common suffix
+   - Create DiffCharRange objects with exact character positions
+2. **Assembly** (DiffLineBuilder): Build DiffLine sequence from enriched DiffNodes
+   - Map DiffCharRanges to source lines
+   - Fill in unchanged lines between changes
+   - Detect reflow (lines that moved but content unchanged)
 
-**Output**: Array of DiffLine objects
+**Output**: Array of DiffLine objects, each carrying DiffCharRange arrays
 
 [source,ruby]
 ----
@@ -102,13 +106,27 @@ end
 {
   line_number: 5,
   content: "<p>Changed text</p>",
+  new_content: "<p>New text</p>",
   type: :changed,  # :added, :removed, :unchanged
   diff_node: DiffNode reference,
+  char_ranges: [DiffCharRange, ...],       # text1 side
+  new_char_ranges: [DiffCharRange, ...],   # text2 side
   normative: true  # from diff_node
 }
+
+# DiffCharRange structure
+{
+  line_number: 5,
+  start_col: 3,
+  end_col: 14,
+  side: :old,
+  status: :changed_old,  # :unchanged, :changed_new, :removed, :added
+  role: :changed,        # :before, :changed, :after
+  diff_node: DiffNode reference
+}
 ----
 
-**Key Point**: This layer bridges semantic differences to their textual representation.
+**Key Point**: This layer bridges semantic differences to their textual representation with precise character-level positions. The two-phase approach (enrich then assemble) ensures the formatter receives pre-computed data requiring no further computation.
 
 == Layer 4: Blocking
 
@@ -272,7 +290,15 @@ Result: Files differ, diff shown in red/green
 
 === Processing Layers
 
-[`DiffNodeMapper`](../../lib/canon/diff/diff_node_mapper.rb):: Maps semantic diffs to text line positions
+[`DiffNodeEnricher`](../../lib/canon/diff/diff_node_enricher.rb):: Phase 1: Enriches DiffNodes with character-level positions (SourceLocator + TextDecomposer)
+
+[`DiffLineBuilder`](../../lib/canon/diff/diff_line_builder.rb):: Phase 2: Assembles DiffLines from enriched DiffNodes (replaces DiffNodeMapper)
+
+[`DiffCharRange`](../../lib/canon/diff/diff_char_range.rb):: Value object: a character range within a source line linked to a DiffNode
+
+[`TextDecomposer`](../../lib/canon/diff/text_decomposer.rb):: Decomposes two strings into common prefix / changed / common suffix
+
+[`SourceLocator`](../../lib/canon/diff/source_locator.rb):: Locates serialized content within source text, returns char offset + line/col
 
 [`DiffBlockBuilder`](../../lib/canon/diff/diff_block_builder.rb):: Groups contiguous lines into blocks, filters by show_diffs
 
@@ -296,7 +322,8 @@ Each class does ONE thing:
 
 * **Comparator**: Compares → DiffNodes
 * **Classifier**: Classifies → normative flags
-* **Mapper**: Maps nodes → lines
+* **Enricher**: Enriches → char positions on DiffNodes
+* **LineBuilder**: Assembles → DiffLines with char ranges
 * **BlockBuilder**: Groups lines → blocks
 * **ContextBuilder**: Adds context → contexts
 * **Formatter**: Renders → string

data/docs/features/diff-formatting/colors-and-symbols.adoc

@@ -49,6 +49,13 @@ Green (added)
 | Semantic differences that affect match results. +
 Requires developer attention. +
 Represents actual content changes.
+
+h| Mixed
+| `*`
+| Yellow
+| Line contains multiple separate changed regions. +
+Both old and new lines are modified. +
+Appears on both OLD and NEW lines.
 |===
 
 === Classification hierarchy
@@ -141,6 +148,13 @@ Normative changes use red/green for high visual priority:
 * `-` - Line removed (normative difference, red)
 * `+` - Line added (normative difference, green)
 
+==== Mixed Marker (Yellow)
+
+* `*` - Line with multiple separate changed regions (yellow)
+** Appears on BOTH old and new lines when changes are interleaved.
+** A simple word replacement (e.g., "John" → "Jane") uses `-`/`+`, not `*`.
+** Only used when there are 2+ separate changed regions in the same line.
+
 ==== Context Marker
 
 * ` ` (space) - Unchanged line (context)
@@ -457,6 +471,17 @@ The whitespace difference is informative because `structural_whitespace: :ignore
 
 == Color Control
 
+=== Theme System
+
+Canon supports multiple color themes that adapt the diff display to your terminal background and personal preference. Four built-in themes are available:
+
+* `:light` -- Light terminal backgrounds
+* `:dark` -- Dark terminals (default)
+* `:retro` -- Amber CRT, low blue light, accessibility
+* `:claude` -- Claude Code diff style with red/green backgrounds
+
+See link:themes.adoc[Diff display themes] for full theme documentation.
+
 === Automatic Color Detection
 
 Canon automatically detects whether the terminal supports color output:
@@ -522,6 +547,63 @@ canon diff file1.xml file2.xml
 
 The `NO_COLOR` variable always takes precedence over other color settings.
 
+== Diff Display Modes
+
+Canon supports two display modes for changed lines, controlled by the `diff_mode` option:
+
+=== Separate-Line Mode (default)
+
+Each changed line is shown as two lines — old on top, new on bottom:
+
+[source]
+----
+   2|    - | <p>John░Doe</p>
+    |   2+ | <p>Jane░Doe</p>
+----
+
+* Old line: line number on left, `-` marker, full content
+* New line: line number on right, `+` marker, full content
+* Changes are highlighted with colors (red for old, green for new)
+
+=== Inline Mode
+
+Old and new content shown on the same line, with inline highlighting:
+
+* When color is ON: removed text appears in red, added text in green
+* When color is OFF: removed text has strikethrough (`\e[9m`), added text has underline (`\e[4m`)
+* Both sides of the change are visible simultaneously
+
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  diff_mode: :inline
+)
+----
+
+=== Legacy Terminal Mode
+
+For terminals without ANSI support, Canon forces separate-line mode with no color codes:
+
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  legacy_terminal: true
+)
+----
+
+Legacy terminal mode automatically sets `diff_mode: :separate` and disables all color output.
+
+=== Color-Off Effects (Separate-Line Mode)
+
+When colors are disabled but ANSI is supported, Canon uses text effects to distinguish changes:
+
+* **Strikethrough** (`\e[9m`): Removed text
+* **Underline** (`\e[4m`): Added text
+
+These provide visual distinction even without color support.
+
 === Environment Variables
 
 In addition to `NO_COLOR`, Canon supports these environment variables:

data/docs/features/diff-formatting/index.adoc

@@ -23,6 +23,7 @@ Canon's diff formatting includes:
 * **Display filtering**: Control which differences appear in output based on
   whether they affect equivalence
 * **Colors and symbols**: Visual indicators for different types of changes
+* **Diff display themes**: Choose from light, dark, retro, or claude color schemes
 * **Character visualization**: Make invisible characters visible
 * **Context and grouping**: Control how much surrounding context to show
 * **Algorithm-specific output**: Different output styles for different diff
@@ -52,6 +53,17 @@ Canon uses color-coded output to distinguish different types of changes:
 
 See link:colors-and-symbols.adoc[Colors and symbols] for details.
 
+=== Diff display themes
+
+Choose from 4 predefined color themes (light, dark, retro, claude) or create custom themes:
+
+* Light theme: Light terminal backgrounds
+* Dark theme: Dark terminals (default)
+* Retro theme: Amber CRT, low blue light
+* Claude theme: Maximum contrast with colored backgrounds
+
+See link:themes.adoc[Themes] for complete theme documentation.
+
 === Character visualization
 
 Make invisible characters visible in diff output: