cov-loupe 3.0.0 → 4.0.0.pre

data/lib/cov_loupe/commands/raw_command.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
 require_relative 'base_command'
-require_relative '../presenters/coverage_raw_presenter'
-require_relative '../table_formatter'
+require_relative '../presenters/coverage_payload_presenter'
+require_relative '../formatters/table_formatter'
 
 module CovLoupe
   module Commands
     class RawCommand < BaseCommand
       def execute(args)
         handle_with_path(args, 'raw') do |path|
-          presenter = Presenters::CoverageRawPresenter.new(model: model, path: path)
+          presenter = Presenters::CoveragePayloadPresenter.new(model: model, path: path,
+            payload_method: :raw_for)
           data = presenter.absolute_payload
           break if maybe_output_structured_format?(data, model)
 
-          relative_path = presenter.relative_path
+          relative_path = convert_text(presenter.relative_path)
           puts "File: #{relative_path}"
           puts
 
@@ -29,7 +30,8 @@ module CovLoupe
           puts TableFormatter.format(
             headers: headers,
             rows: rows,
-            alignments: [:right, :right]
+            alignments: [:right, :right],
+            output_chars: config.output_chars
           )
         end
       end

data/lib/cov_loupe/commands/summary_command.rb

@@ -1,27 +1,31 @@
 # frozen_string_literal: true
 
 require_relative 'base_command'
-require_relative '../presenters/coverage_summary_presenter'
-require_relative '../table_formatter'
+require_relative '../presenters/coverage_payload_presenter'
+require_relative '../formatters/table_formatter'
+require_relative '../staleness/stale_status'
 
 module CovLoupe
   module Commands
     class SummaryCommand < BaseCommand
       def execute(args)
         handle_with_path(args, 'summary') do |path|
-          presenter = Presenters::CoverageSummaryPresenter.new(model: model, path: path)
+          presenter = Presenters::CoveragePayloadPresenter.new(model: model, path: path,
+            payload_method: :summary_for)
           data = presenter.absolute_payload
           break if emit_structured_format_with_optional_source?(data, model, path)
 
-          relative_path = presenter.relative_path
+          relative_path = convert_text(presenter.relative_path)
           summary = data['summary']
 
           # Table format with box-drawing
           headers = ['File', '%', 'Covered', 'Total', 'Stale']
-          stale_marker = data['stale'] ? 'Yes' : ''
+          stale_marker = StaleStatus.stale?(data['stale']) ? 'Yes' : ''
+          percent_display = summary['percentage'] ? format('%.2f%%', summary['percentage']) : 'n/a'.rjust(6)
+
           rows = [[
             relative_path,
-            format('%.2f%%', summary['percentage']),
+            percent_display,
             summary['covered'].to_s,
             summary['total'].to_s,
             stale_marker
@@ -30,7 +34,8 @@ module CovLoupe
           puts TableFormatter.format(
             headers: headers,
             rows: rows,
-            alignments: [:left, :right, :right, :right, :center]
+            alignments: [:left, :right, :right, :right, :center],
+            output_chars: config.output_chars
           )
           puts
           print_source_for(model, path) if config.source_mode

data/lib/cov_loupe/commands/totals_command.rb

@@ -2,19 +2,17 @@
 
 require_relative 'base_command'
 require_relative '../presenters/project_totals_presenter'
-require_relative '../table_formatter'
+require_relative '../formatters/table_formatter'
 
 module CovLoupe
   module Commands
     class TotalsCommand < BaseCommand
       def execute(args)
-        unless args.empty?
-          raise UsageError.for_subcommand('totals')
-        end
+        reject_extra_args(args, 'totals')
 
         presenter = Presenters::ProjectTotalsPresenter.new(
           model: model,
-          check_stale: (config.staleness == :error),
+          raise_on_stale: config.raise_on_stale,
           tracked_globs: config.tracked_globs
         )
         payload = presenter.absolute_payload
@@ -22,22 +20,36 @@ module CovLoupe
 
         lines = payload['lines']
         files = payload['files']
+        tracking = payload['tracking']
+        with_coverage = files['with_coverage']
+        without_coverage = files['without_coverage']
+
+        if tracking && tracking['enabled']
+          puts 'Tracked globs:'
+          tracking['globs'].each { |glob| puts "  - #{convert_text(glob)}" }
+        else
+          puts 'Tracked globs: (tracking disabled)'
+        end
+        puts
 
-        # Table format
+        puts 'Totals'
         headers = ['Metric', 'Total', 'Covered', 'Uncovered', '%']
+        file_ok = with_coverage['ok']
+        file_uncovered = files['total'] - file_ok
+        percent_display = lines['percent_covered'].nil? ? 'n/a' : format('%.2f%%', lines['percent_covered'])
         rows = [
           [
             'Lines',
             lines['total'].to_s,
             lines['covered'].to_s,
             lines['uncovered'].to_s,
-            format('%.2f%%', payload['percentage'])
+            percent_display
           ],
           [
             'Files',
             files['total'].to_s,
-            files['ok'].to_s,
-            files['stale'].to_s,
+            file_ok.to_s,
+            file_uncovered.to_s,
             ''
           ]
         ]
@@ -45,8 +57,60 @@ module CovLoupe
         puts TableFormatter.format(
           headers: headers,
           rows: rows,
-          alignments: [:left, :right, :right, :right, :right]
+          alignments: [:left, :right, :right, :right, :right],
+          output_chars: config.output_chars
         )
+        with_coverage_line = format_with_coverage_line(with_coverage)
+        stale_line = format_stale_breakdown(with_coverage['stale']['by_type'])
+        without_coverage_line, without_breakdown_line =
+          format_without_coverage_lines(without_coverage)
+
+        puts <<~BREAKDOWN
+
+          File breakdown:
+          #{with_coverage_line}
+          #{stale_line}
+          #{without_coverage_line}
+          #{without_breakdown_line}
+        BREAKDOWN
+
+        warn_missing_timestamps(presenter)
+      end
+
+      private def format_with_coverage_line(with_coverage)
+        stale = with_coverage['stale']
+        "  With coverage: #{with_coverage['total']} total, #{with_coverage['ok']} ok, #{stale['total']} stale"
+      end
+
+      private def format_stale_breakdown(stale_by_type)
+        '    Stale: missing on disk = ' \
+          "#{stale_by_type['missing_from_disk']}, " \
+          "newer than coverage = #{stale_by_type['newer']}, " \
+          "line mismatch = #{stale_by_type['length_mismatch']}, " \
+          "unreadable = #{stale_by_type['unreadable']}"
+      end
+
+      private def format_without_coverage_lines(without_coverage)
+        return [nil, nil] unless without_coverage
+
+        without_by_type = without_coverage['by_type']
+        without_coverage_line = "  Without coverage: #{without_coverage['total']} total"
+        without_breakdown_line = '    Missing from coverage = ' \
+          "#{without_by_type['missing_from_coverage']}, " \
+          "unreadable = #{without_by_type['unreadable']}, " \
+          "skipped (errors) = #{without_by_type['skipped']}"
+        [without_coverage_line, without_breakdown_line]
+      end
+
+      private def warn_missing_timestamps(presenter)
+        return unless presenter.timestamp_status == 'missing'
+
+        warn <<~WARNING
+
+          WARNING: Coverage timestamps are missing. Time-based staleness checks were skipped.
+          Files may appear "ok" even if source code is newer than the coverage data.
+          Check your coverage tool configuration to ensure timestamps are recorded.
+        WARNING
       end
     end
   end

data/lib/cov_loupe/commands/uncovered_command.rb

@@ -1,19 +1,20 @@
 # frozen_string_literal: true
 
 require_relative 'base_command'
-require_relative '../presenters/coverage_uncovered_presenter'
-require_relative '../table_formatter'
+require_relative '../presenters/coverage_payload_presenter'
+require_relative '../formatters/table_formatter'
 
 module CovLoupe
   module Commands
     class UncoveredCommand < BaseCommand
       def execute(args)
         handle_with_path(args, 'uncovered') do |path|
-          presenter = Presenters::CoverageUncoveredPresenter.new(model: model, path: path)
+          presenter = Presenters::CoveragePayloadPresenter.new(model: model, path: path,
+            payload_method: :uncovered_for)
           data = presenter.absolute_payload
           break if emit_structured_format_with_optional_source?(data, model, path)
 
-          relative_path = presenter.relative_path
+          relative_path = convert_text(presenter.relative_path)
           summary = data['summary']
 
           puts "File: #{relative_path}"
@@ -32,7 +33,8 @@ module CovLoupe
             puts TableFormatter.format(
               headers: headers,
               rows: rows,
-              alignments: [:right]
+              alignments: [:right],
+              output_chars: config.output_chars
             )
           end
 

data/lib/cov_loupe/commands/validate_command.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'base_command'
-require_relative '../predicate_evaluator'
+require_relative '../config/predicate_evaluator'
 
 module CovLoupe
   module Commands
@@ -35,6 +35,9 @@ module CovLoupe
           code = file_path
         end
 
+        # Ensure no extra arguments remain
+        reject_extra_args(args, 'validate')
+
         # Evaluate the predicate
         result = if inline_mode
           PredicateEvaluator.evaluate_code(code, model)
@@ -51,8 +54,13 @@ module CovLoupe
       end
 
       private def handle_predicate_error(error)
-        warn "Predicate error: #{error.message}"
-        warn error.backtrace.first(5).join("\n") if config.error_mode == :debug
+        # Convert error message to ASCII if in ascii mode
+        message = convert_text(error.message)
+        warn "Predicate error: #{message}"
+        if config.error_mode == :debug
+          backtrace = error.backtrace.first(5).map { |line| convert_text(line) }
+          warn backtrace.join("\n")
+        end
         exit 2
       end
     end

data/lib/cov_loupe/commands/version_command.rb

@@ -2,12 +2,13 @@
 
 require 'json'
 require_relative 'base_command'
-require_relative '../table_formatter'
+require_relative '../formatters/table_formatter'
 
 module CovLoupe
   module Commands
     class VersionCommand < BaseCommand
-      def execute(_args)
+      def execute(args)
+        reject_extra_args(args, 'version')
         @gem_root = File.expand_path('../../..', __dir__)
 
         if config.format == :table
@@ -16,9 +17,10 @@ module CovLoupe
             'Gem Root' => @gem_root,
             'Documentation' => 'README.md and docs/user/**/*.md in gem root'
           }
-          puts TableFormatter.format_vertical(data)
+          puts TableFormatter.format_vertical(data, output_chars: config.output_chars)
         else
-          puts CovLoupe::Formatters.format(version_info, config.format)
+          puts CovLoupe::Formatters.format(version_info, config.format,
+            output_chars: config.output_chars)
         end
       end
 

data/lib/cov_loupe/{app_config.rb → config/app_config.rb}

@@ -12,10 +12,12 @@ module CovLoupe
     :source_context,
     :color,
     :error_mode,
-    :staleness,
+    :raise_on_stale,
     :tracked_globs,
     :log_file,
     :show_version,
+    :mode,
+    :output_chars,
     keyword_init: true
   ) do
     # Set sensible defaults - ALL SYMBOLS FOR ENUMS
@@ -28,11 +30,16 @@ module CovLoupe
       source_context: 2,
       color: $stdout.tty?,
       error_mode: :log,
-      staleness: :off,
+      raise_on_stale: false,
       tracked_globs: nil,
       log_file: nil,
-      show_version: false
+      show_version: false,
+      mode: :cli,
+      output_chars: :default
     )
+      # Default to empty array (show all files in resultset and don't look for files lacking coverage data)
+      # Users should set COV_LOUPE_OPTS to match SimpleCov track_files patterns
+      tracked_globs = [] if tracked_globs.nil?
       super
     end
 
@@ -41,7 +48,7 @@ module CovLoupe
       {
         root: root,
         resultset: resultset,
-        staleness: staleness,
+        raise_on_stale: raise_on_stale,
         tracked_globs: tracked_globs
       }
     end
@@ -49,7 +56,8 @@ module CovLoupe
     # Convenience method for SourceFormatter initialization
     def formatter_options
       {
-        color_enabled: color
+        color_enabled: color,
+        output_chars: output_chars
       }
     end
   end

data/lib/cov_loupe/config/app_context.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'logger'
+
+module CovLoupe
+  # Encapsulates per-request configuration such as error handling and logging.
+  AppContext = Data.define(:error_handler, :log_target, :mode, :app_config, :logger) do
+    def initialize(error_handler:, log_target: nil, mode: :library, app_config: nil, logger: nil)
+      logger ||= Logger.new(target: log_target, mode: mode)
+      super
+    end
+
+    # Overrides Data#with to handle derived state.
+    #
+    # Since the `logger` depends on `log_target` and `mode`, we must ensure
+    # it is regenerated if either of those fields are changed. Otherwise,
+    # the new instance would point to the old logger (e.g. logging to the
+    # wrong file).
+    def with(**kwargs)
+      target_changed = kwargs.key?(:log_target) && kwargs[:log_target] != log_target
+      mode_changed = kwargs.key?(:mode) && kwargs[:mode] != mode
+
+      if target_changed || mode_changed
+        target = kwargs.fetch(:log_target, log_target)
+        new_mode = kwargs.fetch(:mode, mode)
+        kwargs[:logger] = Logger.new(target: target, mode: new_mode)
+      end
+      super
+    end
+
+    def mcp_mode?
+      mode == :mcp
+    end
+
+    def cli_mode?
+      mode == :cli
+    end
+
+    def library_mode?
+      mode == :library
+    end
+  end
+end

data/lib/cov_loupe/config/boolean_type.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # A pluggable boolean type converter for OptionParser.
+  # Accepts various string representations of true/false and converts them to boolean values.
+  #
+  # Usage with OptionParser:
+  #   parser.accept(BooleanType) { |v| BooleanType.parse(v) }
+  #   parser.on('--flag [BOOLEAN]', BooleanType) { |v| config.flag = v }
+  #
+  # Supported values (case-insensitive):
+  #   true:  yes, y, true, t, on, +, 1
+  #   false: no, n, false, f, off, -, 0
+  #   nil:   treated as true (for bare flags like --flag)
+  #
+  # Examples:
+  #   --flag         → true
+  #   --flag=yes     → true
+  #   --flag=no      → false
+  #   --flag yes     → true
+  #   --flag false   → false
+  class BooleanType
+    # Values that map to true
+    TRUE_VALUES = %w[yes y true t on + 1].freeze
+
+    # Values that map to false
+    FALSE_VALUES = %w[no n false f off - 0].freeze
+
+    # All valid boolean string values
+    VALID_VALUES = TRUE_VALUES.zip(FALSE_VALUES).flatten.freeze # %w{yes no y n true false t f on off + - 1 0 }
+
+    # String representation for help messages ('yes/no/true/false/t/f/on/off/y/n/+/-/1/0')
+    BOOLEAN_VALUES_DISPLAY_STRING = VALID_VALUES.join('/').freeze
+
+    # Pattern object for OptionParser.
+    # Proc objects get treated as blocks, and Module instances are rejected outright,
+    # so we expose a singleton that only responds to #match like a regex.
+    IS_BOOLEAN_STRING_VALUE = Object.new
+    IS_BOOLEAN_STRING_VALUE.define_singleton_method(:match) do |value|
+      BooleanType.valid?(value) ? value : nil
+    end
+
+    class << self
+      # Parse a string value into a boolean.
+      #
+      # @param value [String, nil] The value to parse
+      # @return [Boolean] true or false
+      # @raise [ArgumentError] if the value is not a valid boolean string
+      def parse(value)
+        # nil means bare flag (e.g., --flag without a value) → true
+        return true if value.nil?
+
+        normalized = value.to_s.strip.downcase
+
+        return true if TRUE_VALUES.include?(normalized)
+        return false if FALSE_VALUES.include?(normalized)
+
+        raise ArgumentError, "invalid boolean value: #{value.inspect}. " \
+                            "Valid values: #{VALID_VALUES.join(', ')}"
+      end
+
+      # Check if a value is a valid boolean string.
+      #
+      # @param value [String, nil] The value to check
+      # @return [Boolean] true if valid, false otherwise
+      def valid?(value)
+        return true if value.nil?
+
+        VALID_VALUES.include?(value.to_s.strip.downcase)
+      end
+
+      # Pattern matching for OptionParser (called via ===)
+      # This is called to determine if a token should be consumed as the option's argument.
+      # Returning nil signals OptionParser to NOT consume the token.
+      #
+      # @param value [String, nil] The value to match
+      # @return [Boolean, nil] The parsed boolean if valid, or nil to reject the token
+      def ===(value)
+        # nil means optional argument not provided - accept as match
+        return true if value.nil?
+
+        # Only consume the token if it's a valid boolean value
+        # This prevents consuming subcommand names or other arguments
+        return true if valid?(value)
+
+        # Invalid value - don't consume it, let OptionParser treat it as the next argument
+        nil
+      end
+    end
+  end
+end

data/lib/cov_loupe/config/logger.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'time'
+
+module CovLoupe
+  class Logger
+    DEFAULT_LOG_FILESPEC = './cov_loupe.log'
+    FALLBACK_LOG_FILE = 'COV-LOUPE-LOG-ERROR.log'
+
+    attr_reader :target
+
+    def initialize(target:, mode: :library)
+      @mode = mode
+      @target = target
+      @init_error = nil
+      @stderr_warning_emitted = false
+
+      begin
+        @logger = build_logger(target)
+      rescue => e
+        @init_error = e
+      end
+    end
+
+    def info(msg)
+      log_with_level(:info, msg)
+    end
+
+    def warn(msg)
+      log_with_level(:warn, msg)
+    end
+
+    def error(msg)
+      log_with_level(:error, msg)
+    end
+
+    # Safe logging that never raises - use when logging should not interrupt execution.
+    def safe_log(msg)
+      info(msg)
+    rescue
+      # Silently ignore all logging failures
+    end
+
+    private def log_with_level(level, msg)
+      if @init_error
+        handle_logging_error(@init_error, msg)
+      else
+        @logger.send(level, msg)
+      end
+    rescue => e
+      handle_logging_error(e, msg)
+    end
+
+    private def build_logger(target)
+      io_or_path = case target
+                   when 'stdout' then $stdout
+                   when 'stderr' then $stderr
+                   else
+                     path = target || DEFAULT_LOG_FILESPEC
+                     File.expand_path(path)
+      end
+
+      ::Logger.new(io_or_path).tap do |l|
+        l.formatter = ->(severity, datetime, _progname, msg) { "[#{datetime.iso8601}] #{severity}: #{msg}\n" }
+      end
+    end
+
+    private def handle_logging_error(error, original_msg)
+      write_fallback_file(error, original_msg)
+      warn_stderr_once if @mode == :cli
+    rescue
+      # Silently ignore all fallback failures
+    end
+
+    private def write_fallback_file(error, original_msg)
+      File.open(FALLBACK_LOG_FILE, 'a') do |f|
+        timestamp = Time.now.iso8601
+        f.puts "[#{timestamp}] MODE:#{@mode} ERROR:#{error.message} MSG:#{original_msg}"
+      end
+    rescue
+      # Best effort - ignore write failures
+    end
+
+    private def warn_stderr_once
+      return if @stderr_warning_emitted
+
+      @stderr_warning_emitted = true
+      $stderr.puts "Warning: Logging failed. See #{FALLBACK_LOG_FILE} for details."
+    end
+  end
+end