canon 0.1.11 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e123b3a909e4ca7309ed6815282fd03c86e4514fa325d82f1e8973f1428ce83a
-  data.tar.gz: '09e45b9a9f5e8721f4df5b41465b199d0a34824640745321f35cd7edd6d65a91'
+  metadata.gz: 0c7f014834dac890a353a1e85abe80dc834e81f20b853cfa00f51a06c423a699
+  data.tar.gz: 3b849925479fcec2777b22619bee9ab3d710fd33ce29b10bf2873c90d3095192
 SHA512:
-  metadata.gz: c027b7abd237f7b0f3dc679c3b919c11dea6d02f8636aaca9ac95ba56c2d9e321ed3dc23691c33274fa1403f7147b0547011adebb4cb70f1073875cac557a394
-  data.tar.gz: 75aea03c181390b0f927c5d7ba979a8ed6a5ab807e9ab40fa281257e3d165fa001e62fa7ad9bfff3c1d007e1d8157aa49c7218cb2a99bb07919efb1b7da6b120
+  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 06:10:55 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,30 +12,13 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'lib/canon/diff_formatter.rb'
-    - 'spec/canon/diff_formatter_spec.rb'
-
-# Offense count: 705
+# 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: 5
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/canon/diff_formatter.rb'
-    - 'spec/canon/diff_formatter_spec.rb'
-
 # Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
@@ -87,12 +70,12 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 84
 
-# Offense count: 176
+# Offense count: 177
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 362
+# Offense count: 363
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
@@ -102,7 +85,7 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 142
+# Offense count: 143
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -143,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:
@@ -160,6 +143,12 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
+# 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:
@@ -191,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
@@ -229,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

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

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

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,7 +49,7 @@ 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],
@@ -64,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],
@@ -278,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.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
@@ -304,7 +305,7 @@ 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,

data/lib/canon/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  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