canon 0.1.10 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f9d0e9c0c1bc9f213d837f480d3d9a26ce11505691ff48b63907e7a4abd530e
-  data.tar.gz: aa591a7682cede5f23a8dcb8b8eb8f7616d849bc5f9cad1aa2038463ee9c52b0
+  metadata.gz: 0c7f014834dac890a353a1e85abe80dc834e81f20b853cfa00f51a06c423a699
+  data.tar.gz: 3b849925479fcec2777b22619bee9ab3d710fd33ce29b10bf2873c90d3095192
 SHA512:
-  metadata.gz: 6c0af5461fff1d1cd1347ba57681bc671cda71d55d62efd328ac9424ef10b8329ec877ccf43f9ff78e83a54ca03df1026e160b259396caac7bd2704227ef01b1
-  data.tar.gz: 8803713442225ae16c0c6c9c03c9cff55dd27dc6b96f5254ee5f814a29b7ad7b5ef6eafd0cd6a58d17f070a2609154476215147d595a01a69586ca7de8608a7f
+  metadata.gz: 7def7dca16c59b0e3f3952b12f814ad93b38cb108654903471320e0e3c7d55418af60068a114eb9d3fcd4e260bdc806c5cd65b9471b06a85b5c5a223f6373395
+  data.tar.gz: b36133cf1c3c0597e12b880057ebdc5af80689ab59bb8983ff631208d31db994151858521fb8897c88c00d1651e0ac25ad376584558a3b5b514cfd409c2f20be

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-21 01:26:28 UTC using RuboCop version 1.81.7.
+# on 2026-01-21 09:17:44 UTC using RuboCop version 1.81.7.
 # 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
@@ -12,52 +12,13 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 16
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'lib/canon/comparison/xml_comparator.rb'
-    - 'lib/canon/diff/xml_serialization_formatter.rb'
-    - 'spec/canon/diff/xml_serialization_formatter_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'test_verify_equivalent.rb'
-
-# Offense count: 709
+# Offense count: 700
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: aligned, indented
-Layout/MultilineOperationIndentation:
-  Exclude:
-    - 'lib/canon/diff/diff_classifier.rb'
-    - 'lib/canon/diff/xml_serialization_formatter.rb'
-
-# Offense count: 17
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/canon/comparison/xml_comparator.rb'
-    - 'lib/canon/diff/xml_serialization_formatter.rb'
-    - 'spec/canon/diff/xml_serialization_formatter_spec.rb'
-    - 'test_verify_equivalent.rb'
-
 # Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
@@ -98,7 +59,7 @@ Lint/UnusedMethodArgument:
     - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
 
-# Offense count: 207
+# Offense count: 209
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -109,22 +70,22 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 84
 
-# Offense count: 176
+# Offense count: 177
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 360
+# Offense count: 363
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
 
-# Offense count: 45
+# Offense count: 44
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 142
+# Offense count: 143
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -165,7 +126,7 @@ Performance/CollectionLiteralInLoop:
     - 'lib/canon/comparison/html_comparator.rb'
     - 'lib/canon/xml/xml_base_handler.rb'
 
-# Offense count: 64
+# Offense count: 68
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
@@ -182,7 +143,13 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 675
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+RSpec/EmptyHook:
+  Exclude:
+    - 'spec/canon/color_detector_spec.rb'
+
+# Offense count: 679
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 67
@@ -213,10 +180,11 @@ RSpec/IndexedLet:
     - 'spec/canon/tree_diff/matchers/universal_matcher_spec.rb'
     - 'spec/canon/tree_diff/operations/operation_detector_spec.rb'
 
-# Offense count: 4
+# Offense count: 5
 # Configuration parameters: AssignmentOnly.
 RSpec/InstanceVariable:
   Exclude:
+    - 'spec/canon/color_detector_spec.rb'
     - 'spec/canon/rspec_matchers_spec.rb'
 
 # Offense count: 15
@@ -233,7 +201,7 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 518
+# Offense count: 522
 RSpec/MultipleExpectations:
   Max: 15
 
@@ -251,7 +219,7 @@ RSpec/NamedSubject:
     - 'spec/canon/pretty_printer/json_spec.rb'
     - 'spec/canon/pretty_printer/xml_spec.rb'
 
-# Offense count: 37
+# Offense count: 40
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
@@ -311,35 +279,9 @@ Style/IdenticalConditionalBranches:
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
     - 'lib/canon/diff_formatter/legend.rb'
 
-# Offense count: 2
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: InverseMethods, InverseBlocks.
-Style/InverseMethods:
-  Exclude:
-    - 'lib/canon/comparison/markup_comparator.rb'
-    - 'lib/canon/comparison/xml_comparator/diff_node_builder.rb'
-
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
-
-# Offense count: 3
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
-  Exclude:
-    - 'lib/canon/comparison/markup_comparator.rb'
-    - 'lib/canon/comparison/xml_comparator/diff_node_builder.rb'
-    - 'test_verify_equivalent.rb'
-
-# Offense count: 12
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleForMultiline.
-# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
-Style/TrailingCommaInArguments:
-  Exclude:
-    - 'spec/canon/diff/xml_serialization_formatter_spec.rb'

data/README.adoc

@@ -224,68 +224,262 @@ expect(actual).to be_xml_equivalent_to(expected)
   .show_diffs(:normative)
 ----
 
-=== Original input string display
+=== Input display options
 
-When debugging test failures, it's often helpful to see the exact strings that
-were passed to the comparison before any preprocessing or normalization. The
-`verbose_diff` option displays the original input strings in an RSpec-style
-format with line numbers.
+When debugging test failures, it's often helpful to see the exact inputs that were
+passed to the comparison. Canon provides four input display options:
 
+`show_raw_inputs`:: Show raw/original file contents (before preprocessing)
+
+`show_preprocessed_inputs`:: Show what was actually compared (after preprocessing)
+
+`show_line_numbered_inputs`:: Show raw inputs with line numbers (for reference)
+
+`verbose_diff`:: Convenience flag that enables all three options above
+
+You can enable any combination of them independently.
+
+==== Show raw inputs
+
+Display the raw file contents before any preprocessing. This shows exactly what's
+in your files, useful for copying to specs.
+
+**Ruby API:**
 [source,ruby]
 ----
-# Enable original string display in configuration
+# Enable raw input display in configuration
 Canon::Config.configure do |config|
-  config.xml.diff.verbose_diff = true
+  config.xml.diff.show_raw_inputs = true
 end
 
 # Or programmatically for a specific comparison
 result = Canon::Comparison.equivalent?(xml1, xml2,
   verbose: true,
-  verbose_diff: true
+  show_raw_inputs: true
 )
 ----
 
+**CLI usage:**
+[source,bash]
+----
+# Show raw file contents (for copying to specs)
+$ canon diff file1.xml file2.xml --show-raw-inputs
+
+# Show both raw and preprocessed (full trace)
+$ canon diff file1.xml file2.xml --show-raw-inputs --show-preprocessed-inputs
+----
+
+**Environment variables:**
+[source,bash]
+----
+# Global (all formats)
+export CANON_SHOW_RAW_INPUTS=true
+
+# Format-specific
+export CANON_XML_SHOW_RAW_INPUTS=true
+export CANON_HTML_SHOW_RAW_INPUTS=true
+export CANON_JSON_SHOW_RAW_INPUTS=true
+export CANON_YAML_SHOW_RAW_INPUTS=true
+----
+
 **Output format:**
 ----
-==================================================================
-  ORIGINAL INPUT STRINGS
-==================================================================
+=== ORIGINAL INPUTS (Raw) ===
 
-Expected (as string):
-     1 | <root>
-     2 |   <element>value1</element>
-     3 | </root>
+EXPECTED:
+----------------------------------------------------------------------
+<root>  hello
+  world</root>
+
+RECEIVED:
+----------------------------------------------------------------------
+<root>hello world</root>
+
+----
+
+==== Show preprocessed inputs
+
+Display the content after preprocessing (c14n, normalize, format, etc.).
+This shows what the comparison actually compared, useful for understanding
+how preprocessing affects your content.
+
+**Ruby API:**
+[source,ruby]
+----
+# Enable preprocessed input display in configuration
+Canon::Config.configure do |config|
+  config.xml.diff.show_preprocessed_inputs = true
+end
+
+# Or programmatically for a specific comparison
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  show_preprocessed_inputs: true
+)
+----
+
+**CLI usage:**
+[source,bash]
+----
+# Show what was actually compared
+$ canon diff file1.xml file2.xml --show-preprocessed-inputs
+
+# Preprocess with normalization and show what was compared
+$ canon diff file1.xml file2.xml --preprocessing normalize --show-preprocessed-inputs
+----
+
+**Environment variables:**
+[source,bash]
+----
+# Global (all formats)
+export CANON_SHOW_PROCESSED_INPUTS=true
+
+# Format-specific
+export CANON_XML_SHOW_PROCESSED_INPUTS=true
+export CANON_HTML_SHOW_PROCESSED_INPUTS=true
+export CANON_JSON_SHOW_PROCESSED_INPUTS=true
+export CANON_YAML_SHOW_PROCESSED_INPUTS=true
+----
+
+**Output format:**
+----
+=== PREPROCESSED INPUTS (Compared) ===
+Preprocessing: normalize
+
+EXPECTED:
+----------------------------------------------------------------------
+<root> hello world </root>
+
+RECEIVED:
+----------------------------------------------------------------------
+<root>hello world</root>
 
-Actual (as string):
+----
+
+==== Show line-numbered inputs
+
+Display raw inputs with line numbers (RSpec-style format). Useful for
+pinpointing specific lines when debugging.
+
+**Ruby API:**
+[source,ruby]
+----
+# Enable line-numbered input display in configuration
+Canon::Config.configure do |config|
+  config.xml.diff.show_line_numbered_inputs = true
+end
+
+# Or programmatically for a specific comparison
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  show_line_numbered_inputs: true
+)
+----
+
+**CLI usage:**
+[source,bash]
+----
+# Show raw inputs with line numbers (RSpec-style)
+$ canon diff file1.xml file2.xml --show-line-numbered-inputs
+----
+
+**Environment variables:**
+[source,bash]
+----
+# Global (all formats)
+export CANON_SHOW_LINE_NUMBERED_INPUTS=true
+
+# Format-specific
+export CANON_XML_SHOW_LINE_NUMBERED_INPUTS=true
+export CANON_HTML_SHOW_LINE_NUMBERED_INPUTS=true
+export CANON_JSON_SHOW_LINE_NUMBERED_INPUTS=true
+export CANON_YAML_SHOW_LINE_NUMBERED_INPUTS=true
+----
+
+**Output format:**
+----
+======================================================================
+  ORIGINAL INPUTS (with line numbers)
+======================================================================
+
+Expected:
      1 | <root>
-     2 |   <element>value2</element>
+     2 |   hello
      3 | </root>
 
-==================================================================
+Received:
+     1 | <root>hello world</root>
+
+======================================================================
 ----
 
-**When to use this feature:**
+==== Verbose diff (all input displays)
 
-* Debugging why two documents are considered different
-* Understanding preprocessing effects (c14n, normalization, etc.)
-* Verifying the exact input received by the comparison
-* Comparing raw vs processed content
+The `verbose_diff` option is a convenience flag that enables all three input
+display options at once. This is useful for maximum debugging output.
+
+**Ruby API:**
+[source,ruby]
+----
+# Enable all input displays in configuration
+Canon::Config.configure do |config|
+  config.xml.diff.verbose_diff = true
+end
 
-**Environment variable:**
+# Or programmatically for a specific comparison
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  verbose_diff: true
+)
+----
+
+**CLI usage:**
+[source,bash]
+----
+# Show all three input displays
+$ canon diff file1.xml file2.xml --verbose
+----
+
+**Environment variables:**
 [source,bash]
 ----
+# Format-specific
 export CANON_XML_DIFF_VERBOSE_DIFF=true
 export CANON_HTML_DIFF_VERBOSE_DIFF=true
 export CANON_JSON_DIFF_VERBOSE_DIFF=true
 export CANON_YAML_DIFF_VERBOSE_DIFF=true
 ----
 
+==== When to use each option
+
+`show_raw_inputs`::
+** You want to copy the expected output to paste into your test specs
+** You need to see the exact formatting/structure of your input files
+** You're debugging file reading/parsing issues
+
+`show_preprocessed_inputs`::
+** You want to understand what the comparison actually compared
+** You're debugging why two documents are considered equivalent (or not)
+** You need to trace the effect of preprocessing (c14n, normalize, format)
+
+`show_line_numbered_inputs`::
+** You need line numbers for pinpointing specific lines
+** You prefer the RSpec-style format
+** You're collaborating on debugging with others
+
+`verbose_diff`::
+** You want maximum debugging output (all three displays at once)
+** You're doing initial investigation of a complex comparison issue
+
 === Algorithm choice
 
 Canon provides two diff algorithms:
 
-* **DOM diff** (default): Stable, position-based comparison for traditional line-by-line output
-* **Semantic tree diff** (experimental): Advanced operation detection (INSERT, DELETE, UPDATE, MOVE, MERGE, SPLIT, UPGRADE, DOWNGRADE)
+DOM diff (default):: Stable, position-based comparison for traditional
+line-by-line output
+
+Semantic tree diff (experimental):: Advanced operation detection (INSERT,
+DELETE, UPDATE, MOVE, MERGE, SPLIT, UPGRADE, DOWNGRADE)
 
 [source,ruby]
 ----

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

@@ -457,59 +457,110 @@ The whitespace difference is informative because `structural_whitespace: :ignore
 
 == Color Control
 
+=== Automatic Color Detection
+
+Canon automatically detects whether the terminal supports color output:
+
+* **TTY detection**: Colors are only enabled when output is to a terminal (not when piped to a file)
+* **NO_COLOR support**: If the `NO_COLOR` environment variable is set (per https://no-color.org/), colors are disabled
+* **Terminal capability detection**: Checks environment variables like `TERM` and `COLORTERM`
+* **CI environment awareness**: Detects and adapts to CI systems (GitHub Actions, Travis CI, etc.)
+
+This means colors work automatically in most scenarios without manual configuration.
+
 === Enabling/Disabling Colors
 
-Colors are controlled by the `use_color` option:
+Colors can be explicitly controlled using the `use_color` option:
+
+.Using automatic detection (default)
+[example]
+====
+[source,bash]
+----
+# Auto-detects color support (default)
+canon diff file1.xml file2.xml
+----
+====
 
-.CLI
+.Explicit control
 [example]
 ====
 [source,bash]
 ----
-# Enable colors (default)
+# Force enable colors
 canon diff file1.xml file2.xml --color
 
-# Disable colors
+# Force disable colors
 canon diff file1.xml file2.xml --no-color
 ----
 ====
 
 .Ruby API
-[example]
-====
 [source,ruby]
 ----
-# Enable colors
-Canon.compare(file1, file2, format: :xml, color: true)
+# Auto-detect (default)
+Canon.compare(file1, file2, format: :xml)
 
-# Disable colors
-Canon.compare(file1, file2, format: :xml, color: false)
+# Explicit control
+Canon.compare(file1, file2, format: :xml, use_color: false)
 ----
 ====
 
-.RSpec
-[example]
-====
-[source,ruby]
+=== NO_COLOR Environment Variable
+
+Per the https://no-color.org/[NO_COLOR standard], setting the `NO_COLOR`
+environment variable will disable colors:
+
+[source,bash]
 ----
-RSpec.configure do |config|
-  # Enable for local, disable for CI
-  config.canon.xml.diff.use_color = !ENV['CI']
-end
+# Disable colors (respected by Canon and other NO_COLOR-aware tools)
+export NO_COLOR=1
+
+# Run canon - colors will be disabled
+canon diff file1.xml file2.xml
 ----
-====
 
-=== Environment Variable
+The `NO_COLOR` variable always takes precedence over other color settings.
+
+=== Environment Variables
+
+In addition to `NO_COLOR`, Canon supports these environment variables:
 
 [source,bash]
 ----
-# Disable colors globally
+# Disable colors globally (CANON_USE_COLOR)
 export CANON_USE_COLOR=false
 
-# Enable colors globally
+# Enable colors globally (CANON_USE_COLOR)
 export CANON_USE_COLOR=true
+
+# Format-specific color control
+export CANON_XML_DIFF_USE_COLOR=false
+export CANON_HTML_DIFF_USE_COLOR=false
+export CANON_JSON_DIFF_USE_COLOR=false
+export CANON_YAML_DIFF_USE_COLOR=false
 ----
 
+=== Terminal Detection
+
+Canon detects terminal capabilities through these environment variables:
+
+`COLORTERM`::
+Set to `24bit`, `truecolor`, or `true` indicates True Color support
+
+`TERM`:: Terminal type:
+
+256-color support::: `xterm-256color`, `screen-256color`
+Direct color support::: `xterm-direct`
+No color support::: `dumb`, `emacs`
+Assume basic ANSI color support::: Most other values
+
+`CI`:: CI environment detection
+(plus CI-specific variables)
+
+If no terminal information is available, Canon assumes color support for modern
+terminals.
+
 
 == Diff Type Display Options
 

data/lib/canon/cli.rb

@@ -126,6 +126,24 @@ module Canon
 
         # Disable color output
         $ canon diff file1.xml file2.xml --no-color
+
+        # Show raw file contents (for copying to specs)
+        $ canon diff file1.xml file2.xml --show-raw-inputs
+
+        # Show preprocessed contents (what was actually compared)
+        $ canon diff file1.xml file2.xml --show-preprocessed-inputs
+
+        # Show both raw and preprocessed (full trace)
+        $ canon diff file1.xml file2.xml --show-raw-inputs --show-preprocessed-inputs
+
+        # Preprocess with normalization and show what was compared
+        $ canon diff file1.xml file2.xml --preprocessing normalize --show-preprocessed-inputs
+
+        # Show raw inputs with line numbers (RSpec-style)
+        $ canon diff file1.xml file2.xml --show-line-numbered-inputs
+
+        # Verbose mode (shows all three input displays)
+        $ canon diff file1.xml file2.xml --verbose
     DESC
     method_option :format,
                   aliases: "-f",
@@ -142,8 +160,7 @@ module Canon
                   desc: "Format type for second file"
     method_option :color,
                   type: :boolean,
-                  default: true,
-                  desc: "Colorize diff output"
+                  desc: "Colorize diff output (auto-detected by default)"
     method_option :verbose,
                   aliases: "-v",
                   type: :boolean,
@@ -213,6 +230,18 @@ module Canon
     method_option :diff_grouping_lines,
                   type: :numeric,
                   desc: "Group diffs within N lines into context blocks (default: no grouping)"
+    method_option :show_raw_inputs,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show raw/original file contents before diff"
+    method_option :show_preprocessed_inputs,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show preprocessed contents (what was actually compared)"
+    method_option :show_line_numbered_inputs,
+                  type: :boolean,
+                  default: false,
+                  desc: "Show raw inputs with line numbers (RSpec-style)"
     def diff(file1, file2)
       Commands::DiffCommand.new(options).run(file1, file2)
     end

data/lib/canon/color_detector.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Canon
+  # Detects whether the current terminal supports color output.
+  #
+  # This class provides cross-platform detection of terminal color capabilities
+  # by checking environment variables and, on Unix-like systems, optionally
+  # querying the terminfo database.
+  #
+  # == Detection Logic
+  #
+  # The detection follows this priority order:
+  #
+  # 1. **NO_COLOR**: If set (regardless of value), colors are disabled
+  #    (per https://no-color.org/)
+  # 2. **Explicit user choice**: If explicitly set, honor that choice
+  # 3. **Terminal capability detection**:
+  #    - COLORTERM=24bit or truecolor → True color support
+  #    - TERM ending with 256 or 256color → 256-color support
+  #    - TERM=dumb, TERM containing "emacs" → No color support
+  #    - CI environment → Check specific CI variables
+  #    - TTY detection → Only enable colors if output is to a TTY
+  #
+  # == Usage
+  #
+  #   # Auto-detect
+  #   ColorDetector.supports_color?  # => true or false
+  #
+  #   # Explicit choice (bypass detection)
+  #   ColorDetector.supports_color?(explicit: true)   # => true
+  #   ColorDetector.supports_color?(explicit: false)  # => false
+  #
+  #   # With output stream check
+  #   ColorDetector.supports_color?(output: $stdout)
+  #
+  class ColorDetector
+    # Environment variables that indicate color support
+    COLOR_TERM_VALUES = %w[24bit truecolor true].freeze
+    COLOR_TERM_SUFFIXES = %w[256 256color direct].freeze
+    NO_COLOR_TERMS = %w[dumb emacs].freeze
+    CI_ENV_VARS = %w[CI GITHUB_ACTIONS TRAVIS GITLAB_CI JENKINS_HOME].freeze
+
+    class << self
+      # Detect whether the current environment supports color output.
+      #
+      # @param explicit [Boolean, nil] Explicit user choice to bypass detection
+      # @param output [IO, nil] Output stream to check (default: $stdout)
+      # @return [Boolean] true if colors are supported, false otherwise
+      def supports_color?(explicit: nil, output: $stdout)
+        # 1. NO_COLOR always wins (per https://no-color.org/)
+        return false if ENV.key?("NO_COLOR")
+
+        # 2. Explicit user choice bypasses detection
+        return explicit unless explicit.nil?
+
+        # 3. Check if output is a TTY (don't use colors for piped/file output)
+        return false unless tty?(output)
+
+        # 4. Check terminal capability indicators
+        detect_from_env
+      end
+
+      private
+
+      # Check if output stream is a TTY
+      #
+      # @param io [IO] Output stream
+      # @return [Boolean] true if the stream is a TTY
+      def tty?(io)
+        return false unless io.respond_to?(:tty?)
+        return false unless io.respond_to?(:isatty)
+
+        # Ruby 2.5+ uses tty?, older uses isatty
+        io.tty? || io.isatty
+      rescue ArgumentError, IOError
+        # Stream might be closed or invalid
+        false
+      end
+
+      # Detect color support from environment variables
+      #
+      # @return [Boolean] true if colors appear to be supported
+      def detect_from_env
+        # Check for known color-capable terminals
+        colorterm = ENV["COLORTERM"]
+        return true if COLOR_TERM_VALUES.include?(colorterm)
+
+        # Check TERM variable
+        term = ENV["TERM"]
+        if term
+          # Known no-color terminals
+          return false if NO_COLOR_TERMS.any? { |t| term.include?(t) }
+          # Known color-capable terminals
+          return true if COLOR_TERM_SUFFIXES.any? { |s| term.end_with?(s) }
+          # Most modern terminals support basic ANSI colors
+          return true unless term.empty? || term == "unknown"
+        end
+
+        # Check CI environments
+        # Some CI systems support colors, others don't
+        return detect_ci_colors if ci_environment?
+
+        # Default: assume colors are supported on modern terminals
+        # This is a safe default for most use cases
+        true
+      end
+
+      # Detect if we're in a CI environment
+      #
+      # @return [Boolean] true if in a CI environment
+      def ci_environment?
+        CI_ENV_VARS.any? { |var| ENV.key?(var) }
+      end
+
+      # Detect color support in CI environments
+      #
+      # Different CI systems have different color support:
+      # - GitHub Actions: supports colors (explicit CI env vars)
+      # - Travis CI: supports colors
+      # - GitLab CI: supports colors
+      # - Jenkins: supports colors
+      # - Generic CI: check for specific TeamCity/Terminal variables
+      #
+      # @return [Boolean] true if CI environment likely supports colors
+      def detect_ci_colors
+        # GitHub Actions explicitly supports colors
+        return true if ENV["GITHUB_ACTIONS"]
+
+        # TeamCity supports colors with specific env var
+        return true if ENV["TEAMCITY_VERSION"]
+
+        # Most modern CI systems support ANSI colors
+        # Only disable for explicitly known non-color CI
+        return false if ENV["TERM"] == "dumb"
+
+        # Default to supporting colors in CI
+        true
+      end
+    end
+  end
+end

data/lib/canon/commands/diff_command.rb

@@ -2,6 +2,7 @@
 
 require_relative "../comparison"
 require_relative "../diff_formatter"
+require_relative "../color_detector"
 require "json"
 require "yaml"
 
@@ -48,11 +49,14 @@ module Canon
 
         # Format and output results
         formatter = Canon::DiffFormatter.new(
-          use_color: @options[:color],
+          use_color: resolve_color_option,
           mode: mode,
           context_lines: @options.fetch(:context_lines, 3),
           diff_grouping_lines: @options[:diff_grouping_lines],
           show_diffs: @options[:show_diffs]&.to_sym || :all,
+          show_raw_inputs: @options[:show_raw_inputs] || false,
+          show_preprocessed_inputs: @options[:show_preprocessed_inputs] || false,
+          show_line_numbered_inputs: @options[:show_line_numbered_inputs] || false,
         )
 
         # Show configuration in verbose mode using shared DebugOutput
@@ -61,7 +65,7 @@ module Canon
           config_output = Canon::DiffFormatter::DebugOutput.verbose_tables_only(
             result,
             {
-              use_color: @options[:color],
+              use_color: resolve_color_option,
               mode: mode,
               context_lines: @options.fetch(:context_lines, 3),
               diff_grouping_lines: @options[:diff_grouping_lines],
@@ -275,6 +279,19 @@ module Canon
           5_242_880 # Default 5MB
         end
       end
+
+      # Resolve color option with auto-detection
+      #
+      # Returns the user's explicit choice if provided, otherwise
+      # auto-detects terminal color support.
+      #
+      # @return [Boolean] true if colors should be used
+      def resolve_color_option
+        return @options[:color] unless @options[:color].nil?
+
+        # Auto-detect when no explicit choice was made
+        ColorDetector.supports_color?
+      end
     end
   end
 end

data/lib/canon/config/env_schema.rb

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

data/lib/canon/config.rb

@@ -2,6 +2,7 @@
 
 require_relative "config/env_provider"
 require_relative "config/override_resolver"
+require_relative "color_detector"
 
 module Canon
   # Global configuration for Canon
@@ -221,6 +222,30 @@ module Canon
         @resolver.set_programmatic(:verbose_diff, value)
       end
 
+      def show_raw_inputs
+        @resolver.resolve(:show_raw_inputs)
+      end
+
+      def show_raw_inputs=(value)
+        @resolver.set_programmatic(:show_raw_inputs, value)
+      end
+
+      def show_preprocessed_inputs
+        @resolver.resolve(:show_preprocessed_inputs)
+      end
+
+      def show_preprocessed_inputs=(value)
+        @resolver.set_programmatic(:show_preprocessed_inputs, value)
+      end
+
+      def show_line_numbered_inputs
+        @resolver.resolve(:show_line_numbered_inputs)
+      end
+
+      def show_line_numbered_inputs=(value)
+        @resolver.set_programmatic(:show_line_numbered_inputs, value)
+      end
+
       def algorithm
         @resolver.resolve(:algorithm)
       end
@@ -266,6 +291,9 @@ module Canon
           show_diffs: show_diffs,
           verbose_diff: verbose_diff,
           diff_algorithm: algorithm,
+          show_raw_inputs: show_raw_inputs,
+          show_preprocessed_inputs: show_preprocessed_inputs,
+          show_line_numbered_inputs: show_line_numbered_inputs,
           max_file_size: max_file_size,
           max_node_count: max_node_count,
           max_diff_lines: max_diff_lines,
@@ -277,12 +305,15 @@ module Canon
       def build_resolver(format)
         defaults = {
           mode: :by_line,
-          use_color: true,
+          use_color: ColorDetector.supports_color?,
           context_lines: 3,
           grouping_lines: 10,
           show_diffs: :all,
           verbose_diff: false,
           algorithm: :dom,
+          show_raw_inputs: false,
+          show_preprocessed_inputs: false,
+          show_line_numbered_inputs: false,
           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

data/lib/canon/diff_formatter.rb

@@ -162,16 +162,23 @@ module Canon
       Comparison::UNEQUAL_PRIMITIVES => "Unequal primitive values",
     }.freeze
 
+    # rubocop:disable Metrics/ParameterLists
     def initialize(use_color: true, mode: :by_object, context_lines: 3,
                    diff_grouping_lines: nil, visualization_map: nil,
                    character_map_file: nil, character_definitions: nil,
-                   show_diffs: :all, verbose_diff: false)
+                   show_diffs: :all, verbose_diff: false,
+                   show_raw_inputs: false, show_preprocessed_inputs: false,
+                   show_line_numbered_inputs: false)
+      # rubocop:enable Metrics/ParameterLists
       @use_color = use_color
       @mode = mode
       @context_lines = context_lines
       @diff_grouping_lines = diff_grouping_lines
       @show_diffs = show_diffs
       @verbose_diff = verbose_diff
+      @show_raw_inputs = show_raw_inputs
+      @show_preprocessed_inputs = show_preprocessed_inputs
+      @show_line_numbered_inputs = show_line_numbered_inputs
       @visualization_map = build_visualization_map(
         visualization_map: visualization_map,
         character_map_file: character_map_file,
@@ -329,15 +336,39 @@ module Canon
         )
       end
 
-      # 2.5. Original Input Strings (ONLY if verbose_diff is enabled)
-      if @verbose_diff && comparison_result.is_a?(Canon::Comparison::ComparisonResult)
+      # verbose_diff enables all three input displays as a convenience
+      verbose = @verbose_diff || @show_raw_inputs
+      show_prep = @verbose_diff || @show_preprocessed_inputs
+      show_line = @verbose_diff || @show_line_numbered_inputs
+
+      # 3. Raw/Original Input Display (when show_raw_inputs is enabled)
+      if verbose && comparison_result.is_a?(Canon::Comparison::ComparisonResult)
+        original1, original2 = comparison_result.original_strings
+        if original1 && original2
+          output << format_raw_inputs(original1, original2)
+        end
+      end
+
+      # 4. Preprocessed Input Display (when show_preprocessed_inputs is enabled)
+      if show_prep && comparison_result.is_a?(Canon::Comparison::ComparisonResult)
+        preprocessed1, preprocessed2 = comparison_result.preprocessed_strings
+        if preprocessed1 && preprocessed2
+          preprocessing_info = comparison_result.match_options&.dig(:match,
+                                                                    :preprocessing)
+          output << format_preprocessed_inputs(preprocessed1, preprocessed2,
+                                               preprocessing_info)
+        end
+      end
+
+      # 5. Line-Numbered Input Display (when show_line_numbered_inputs is enabled)
+      if show_line && comparison_result.is_a?(Canon::Comparison::ComparisonResult)
         original1, original2 = comparison_result.original_strings
         if original1 && original2
-          output << format_original_strings(original1, original2)
+          output << format_line_numbered_inputs(original1, original2)
         end
       end
 
-      # 3. Main diff output (by-line or by-object) - ALWAYS
+      # 6. Main diff output (by-line or by-object) - ALWAYS
 
       # Check if comparison result is a ComparisonResult object
       if comparison_result.is_a?(Canon::Comparison::ComparisonResult)
@@ -428,24 +459,24 @@ module Canon
       html.to_s
     end
 
-    # Format original input strings for display (RSpec-style)
-    # Shows the actual strings that were passed in before any preprocessing
+    # Format original input strings with line numbers (RSpec-style)
+    # Shows the actual strings that were passed in with line numbers for reference
     #
     # @param original1 [String] First original input string
     # @param original2 [String] Second original input string
-    # @return [String] Formatted display of original strings
-    def format_original_strings(original1, original2)
+    # @return [String] Formatted display with line numbers
+    def format_line_numbered_inputs(original1, original2)
       return "" if original1.nil? || original2.nil?
 
       output = []
       output << ""
       output << colorize("=" * 70, :cyan, :bold)
-      output << colorize("  ORIGINAL INPUT STRINGS", :cyan, :bold)
+      output << colorize("  ORIGINAL INPUTS (with line numbers)", :cyan, :bold)
       output << colorize("=" * 70, :cyan, :bold)
       output << ""
 
       # Format expected
-      output << colorize("Expected (as string):", :yellow, :bold)
+      output << colorize("Expected:", :yellow, :bold)
       original1.each_line.with_index do |line, idx|
         output << "  #{colorize(sprintf('%4d', idx + 1),
                                 :blue)} | #{line.chomp}"
@@ -453,7 +484,7 @@ module Canon
       output << ""
 
       # Format actual
-      output << colorize("Actual (as string):", :yellow, :bold)
+      output << colorize("Received:", :yellow, :bold)
       original2.each_line.with_index do |line, idx|
         output << "  #{colorize(sprintf('%4d', idx + 1),
                                 :blue)} | #{line.chomp}"
@@ -465,6 +496,65 @@ module Canon
       output.join("\n")
     end
 
+    # Format raw/original inputs for display (user-friendly copyable format)
+    # Shows the raw file contents before any preprocessing
+    #
+    # @param raw1 [String] First raw input string
+    # @param raw2 [String] Second raw input string
+    # @return [String] Formatted display of raw inputs
+    def format_raw_inputs(raw1, raw2)
+      return "" if raw1.nil? || raw2.nil?
+
+      output = []
+      output << ""
+      output << colorize("=== ORIGINAL INPUTS (Raw) ===", :cyan, :bold)
+      output << ""
+      output << colorize("EXPECTED:", :yellow, :bold)
+      output << "-" * 70
+      output << raw1
+      output << ""
+      output << colorize("RECEIVED:", :yellow, :bold)
+      output << "-" * 70
+      output << raw2
+      output << ""
+      output << ""
+
+      output.join("\n")
+    end
+
+    # Format preprocessed inputs for display (what was actually compared)
+    # Shows the content after preprocessing (c14n, normalize, format, etc.)
+    #
+    # @param preprocessed1 [String] First preprocessed string
+    # @param preprocessed2 [String] Second preprocessed string
+    # @param preprocessing_info [Symbol, nil] Preprocessing mode (:c14n, :normalize, :format, etc.)
+    # @return [String] Formatted display of preprocessed inputs
+    def format_preprocessed_inputs(preprocessed1, preprocessed2,
+preprocessing_info = nil)
+      return "" if preprocessed1.nil? || preprocessed2.nil?
+
+      output = []
+      output << ""
+      output << colorize("=== PREPROCESSED INPUTS (Compared) ===", :cyan, :bold)
+
+      # Show preprocessing mode if available
+      if preprocessing_info
+        output << "Preprocessing: #{preprocessing_info}"
+      end
+      output << ""
+      output << colorize("EXPECTED:", :yellow, :bold)
+      output << "-" * 70
+      output << preprocessed1
+      output << ""
+      output << colorize("RECEIVED:", :yellow, :bold)
+      output << "-" * 70
+      output << preprocessed2
+      output << ""
+      output << ""
+
+      output.join("\n")
+    end
+
     # Build the final visualization map from various customization options
     #
     # @param visualization_map [Hash, nil] Complete custom visualization map

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.1.10"
+  VERSION = "0.1.12"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.1.10
+  version: 0.1.12
 platform: ruby
 authors:
 - Ribose Inc.
@@ -193,6 +193,7 @@ files:
 - lib/canon.rb
 - lib/canon/cache.rb
 - lib/canon/cli.rb
+- lib/canon/color_detector.rb
 - lib/canon/commands/diff_command.rb
 - lib/canon/commands/format_command.rb
 - lib/canon/comparison.rb