cov-loupe 3.0.0 → 4.0.0.pre

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

@@ -18,13 +18,6 @@ module CovLoupe
       'uncovered' => :uncovered
     }.freeze
 
-    STALENESS_MAP = {
-      'o' => :off,
-      'off' => :off,
-      'e' => :error,
-      'error' => :error
-    }.freeze
-
     ERROR_MODE_MAP = {
       'off' => :off,
       'o' => :off,
@@ -44,9 +37,26 @@ module CovLoupe
       'pretty-json' => :pretty_json,
       'y' => :yaml,
       'yaml' => :yaml,
-      'a' => :awesome_print,
-      'awesome_print' => :awesome_print,
-      'ap' => :awesome_print
+      'a' => :amazing_print,
+      'awesome_print' => :amazing_print,
+      'ap' => :amazing_print,
+      'amazing_print' => :amazing_print
+    }.freeze
+
+    MODE_MAP = {
+      'cli' => :cli,
+      'c' => :cli,
+      'mcp' => :mcp,
+      'm' => :mcp
+    }.freeze
+
+    OUTPUT_CHARS_MAP = {
+      'd' => :default,
+      'default' => :default,
+      'f' => :fancy,
+      'fancy' => :fancy,
+      'a' => :ascii,
+      'ascii' => :ascii
     }.freeze
 
     module_function def normalize_sort_order(value, strict: true)
@@ -70,19 +80,6 @@ module CovLoupe
       nil
     end
 
-    # Normalize stale mode value.
-    # @param value [String, Symbol] The value to normalize
-    # @param strict [Boolean] If true, raises on invalid value; if false, returns nil
-    # @return [Symbol, nil] The normalized symbol or nil if invalid and not strict
-    # @raise [OptionParser::InvalidArgument] If strict and value is invalid
-    module_function def normalize_staleness(value, strict: true)
-      normalized = STALENESS_MAP[value.to_s.downcase]
-      return normalized if normalized
-      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
-
-      nil
-    end
-
     # Normalize error mode value.
     # @param value [String, Symbol, nil] The value to normalize
     # @param strict [Boolean] If true, raises on invalid value; if false, returns default
@@ -92,6 +89,7 @@ module CovLoupe
     module_function def normalize_error_mode(value, strict: true, default: :log)
       normalized = ERROR_MODE_MAP[value.to_s.downcase]
       return normalized if normalized
+
       raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
 
       default
@@ -103,11 +101,44 @@ module CovLoupe
     # @return [Symbol, nil] The normalized symbol or nil if invalid and not strict
     # @raise [OptionParser::InvalidArgument] If strict and value is invalid
     module_function def normalize_format(value, strict: true)
-      normalized = FORMAT_MAP[value.to_s.downcase]
+      # Try exact match first (preserves case-sensitive 'J' for pretty_json)
+      normalized = FORMAT_MAP[value.to_s] || FORMAT_MAP[value.to_s.downcase]
       return normalized if normalized
+
       raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
 
       nil
     end
+
+    # Normalize mode value (cli or mcp).
+    # @param value [String, Symbol] The value to normalize
+    # @param strict [Boolean] If true, raises on invalid value; if false, returns default
+    # @param default [Symbol] The default value to return if invalid and not strict
+    # @return [Symbol] The normalized symbol (:cli or :mcp)
+    # @raise [OptionParser::InvalidArgument] If strict and value is invalid
+    module_function def normalize_mode(value, strict: true, default: :cli)
+      normalized = MODE_MAP[value.to_s.downcase]
+      return normalized if normalized
+
+      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
+
+      default
+    end
+
+    # Normalize output_chars value.
+    # Controls ASCII vs Unicode (fancy) output for tables and text.
+    # @param value [String, Symbol] The value to normalize
+    # @param strict [Boolean] If true, raises on invalid value; if false, returns default
+    # @param default [Symbol] The default value to return if invalid and not strict
+    # @return [Symbol] The normalized symbol (:default, :fancy, or :ascii)
+    # @raise [OptionParser::InvalidArgument] If strict and value is invalid
+    module_function def normalize_output_chars(value, strict: true, default: :default)
+      normalized = OUTPUT_CHARS_MAP[value.to_s.downcase]
+      return normalized if normalized
+
+      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
+
+      default
+    end
   end
 end

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

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 require_relative 'option_normalizers'
-require_relative 'version'
+require_relative '../version'
+require_relative 'boolean_type'
+require_relative '../errors/errors'
 
 module CovLoupe
   class OptionParserBuilder
     HORIZONTAL_RULE = '-' * 79
-    SUBCOMMANDS = %w[list summary raw uncovered detailed totals validate version].freeze
 
     attr_reader :config
 
@@ -25,11 +26,14 @@ module CovLoupe
     end
 
     private def configure_banner(parser)
+      gem_root = File.expand_path('../..', __dir__)
       parser.banner = <<~BANNER
         #{HORIZONTAL_RULE}
-        Usage:      cov-loupe [options] [subcommand] [args]  (default subcommand: list)
-        Repository: https://github.com/keithrbennett/cov-loupe
-        Version:    #{CovLoupe::VERSION}
+        Usage:                 cov-loupe [options] [subcommand] [args]  (default subcommand: list)
+        Repository:            https://github.com/keithrbennett/cov-loupe
+        Documentation (Web):   https://keithrbennett.github.io/cov-loupe/
+        Documentation (Local): #{gem_root}/**/*.md
+        Version:               #{CovLoupe::VERSION}
         #{HORIZONTAL_RULE}
 
         BANNER
@@ -45,7 +49,7 @@ module CovLoupe
           totals                   Show aggregated line totals and average %
           uncovered <path>         Show uncovered lines and a summary
           validate <file>          Evaluate coverage policy from file (exit 0=pass, 1=fail, 2=error)
-          validate -e <code>       Evaluate coverage policy from code string
+          validate -i <code>       Evaluate coverage policy from code string
           version                  Show version information
 
         SUBCOMMANDS
@@ -63,7 +67,7 @@ module CovLoupe
       end
       parser.on(
         '-f', '--format FORMAT', String,
-        'Output format: t[able]|j[son]|pretty-json|y[aml]|a[wesome-print] (default: table)'
+        'Output format: t[able]|j[son]|pretty-json|y[aml]|a[mazing_print] (default: table)'
       ) do |value|
         config.format = normalize_format(value)
       end
@@ -77,38 +81,52 @@ module CovLoupe
       end
       parser.on('-c', '--context-lines N', Integer,
         'Context lines around uncovered lines (non-negative, default: 2)') do |value|
+        raise UsageError, 'Context lines cannot be negative' if value.negative?
+
         config.source_context = value
       end
-      parser.on('--color', 'Enable ANSI colors for source output') { config.color = true }
-      parser.on('--no-color', 'Disable ANSI colors') { config.color = false }
-      parser.on('-S', '--staleness MODE', String,
-        'Staleness detection: o[ff]|e[rror] (default off)') do |value|
-        config.staleness = normalize_staleness(value)
+      parser.on('-C', '--color BOOLEAN', BooleanType::IS_BOOLEAN_STRING_VALUE,
+        'Enable/disable ANSI colors for source output (default: true). ' \
+          "Accepts: #{BooleanType::BOOLEAN_VALUES_DISPLAY_STRING}") do |value|
+        config.color = BooleanType.parse(value)
+      end
+      parser.on('-S', '--raise-on-stale BOOLEAN', BooleanType::IS_BOOLEAN_STRING_VALUE,
+        'Raise error if coverage is stale (default: false). ' \
+          "Accepts: #{BooleanType::BOOLEAN_VALUES_DISPLAY_STRING}") do |value|
+        config.raise_on_stale = BooleanType.parse(value)
       end
       parser.on('-g', '--tracked-globs x,y,z', Array,
-        'Globs for filtering files (list/totals subcommands)') do |value|
+        'Used to exclude unwanted results and/or include files with or without coverage data',
+        'Default: [] (shows all files in resultset)',
+        'Best practice: match your SimpleCov track_files patterns',
+        'Example: --tracked-globs lib/**/*.rb,app/**/*.rb') do |value|
         config.tracked_globs = value
       end
       parser.on('-h', '--help', 'Show help') do
         puts parser
-        gem_root = File.expand_path('../..', __dir__)
-        puts "\nFor more detailed help, consult README.md and docs/user/**/*.md"
-        puts "in the installed gem at: #{gem_root}"
         exit 0
       end
       parser.on('-l', '--log-file PATH', String,
         'Log file path (default ./cov_loupe.log, use stdout/stderr for streams)') do |value|
         config.log_file = value
       end
-      parser.on('--error-mode MODE', String,
+      parser.on('-m', '--mode MODE', String,
+        'Execution mode: cli|mcp (default: cli)') do |value|
+        config.mode = normalize_mode(value)
+      end
+      parser.on('-e', '--error-mode MODE', String,
         'Error handling mode: o[ff]|l[og]|d[ebug] (default log). ' \
         'off (silent), log (log errors to file), debug (verbose with backtraces)') do |value|
         config.error_mode = normalize_error_mode(value)
       end
-      parser.on('--force-cli', 'Force CLI mode (useful in scripts where auto-detection fails)') do
-        # This flag is mainly for mode detection - no action needed here
+      parser.on('-O', '--output-chars MODE', String,
+        'Output character mode: d[efault]|f[ancy]|a[scii] (default: default). ' \
+        'default: UTF-8 encoding uses fancy (Unicode), else ascii. ' \
+        'fancy: use Unicode box-drawing and symbols. ' \
+        'ascii: use ASCII-only characters (0x00-0x7F).') do |value|
+        config.output_chars = normalize_output_chars(value)
       end
-      parser.on('-v', '--version', 'Show version information and exit') do
+      parser.on('-v', '--version', 'Show version information and exit.') do
         config.show_version = true
       end
     end
@@ -132,10 +150,6 @@ module CovLoupe
       OptionNormalizers.normalize_source_mode(value, strict: true)
     end
 
-    private def normalize_staleness(value)
-      OptionNormalizers.normalize_staleness(value, strict: true)
-    end
-
     private def normalize_error_mode(value)
       OptionNormalizers.normalize_error_mode(value, strict: true)
     end
@@ -143,5 +157,13 @@ module CovLoupe
     private def normalize_format(value)
       OptionNormalizers.normalize_format(value, strict: true)
     end
+
+    private def normalize_mode(value)
+      OptionNormalizers.normalize_mode(value, strict: true)
+    end
+
+    private def normalize_output_chars(value)
+      OptionNormalizers.normalize_output_chars(value, strict: true)
+    end
   end
 end

data/lib/cov_loupe/coverage/coverage_calculator.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Provides coverage data transformations and calculations.
+  # Handles summary statistics, uncovered line identification, and detailed line-by-line analysis.
+  class CoverageCalculator
+    # Calculates coverage summary statistics from a coverage array.
+    #
+    # @param coverage_lines [Array<Integer, nil>] SimpleCov coverage array where each element
+    #   represents a line: Integer for hit count, nil for non-code lines
+    # @return [Hash] summary with 'covered', 'total', and 'percentage' keys
+    def self.summary(coverage_lines)
+      total = 0
+      covered = 0
+      coverage_lines.compact.each do |hits|
+        total += 1
+        covered += 1 if hits.to_i > 0
+      end
+      percentage = total <= 0 ? nil : (covered.to_f / total * 100.0).round(2)
+      { 'covered' => covered, 'total' => total, 'percentage' => percentage }
+    end
+
+    # Identifies uncovered line numbers from a coverage array.
+    #
+    # @param coverage_lines [Array<Integer, nil>] SimpleCov coverage array
+    # @return [Array<Integer>] array of uncovered line numbers (1-indexed)
+    def self.uncovered(coverage_lines)
+      out = []
+
+      coverage_lines.each_with_index do |hits, i|
+        next if hits.nil?
+
+        out << (i + 1) if hits.to_i.zero?
+      end
+      out
+    end
+
+    # Generates detailed line-by-line coverage information.
+    #
+    # @param coverage_lines [Array<Integer, nil>] SimpleCov coverage array
+    # @return [Array<Hash>] array of hashes with 'line', 'hits', and 'covered' keys
+    def self.detailed(coverage_lines)
+      rows = []
+      coverage_lines.each_with_index do |hits, i|
+        next if hits.nil?
+
+        h = hits.to_i
+        rows << { 'line' => i + 1, 'hits' => h, 'covered' => h.positive? }
+      end
+      rows
+    end
+  end
+end

data/lib/cov_loupe/coverage/coverage_reporter.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  require_relative '../staleness/stale_status'
+
+  # Reports files with coverage below a specified threshold.
+  # Useful for displaying low coverage files after test runs.
+  #
+  # @example Basic usage in spec_helper.rb
+  #   SimpleCov.at_exit do
+  #     SimpleCov.result.format!
+  #     report = CovLoupe::CoverageReporter.report(threshold: 80, count: 5)
+  #     puts report if report
+  #   end
+  #
+  # @example With custom resultset path
+  #   CovLoupe::CoverageReporter.report(
+  #     threshold: 80,
+  #     count: 5,
+  #     resultset: 'custom/coverage/.resultset.json'
+  #   )
+  #
+  # @example With custom project root
+  #   CovLoupe::CoverageReporter.report(
+  #     threshold: 80,
+  #     count: 5,
+  #     root: '/path/to/project'
+  #   )
+  #
+  module CoverageReporter
+    module_function def report(threshold: 80, count: 5, model: nil, root: nil, resultset: nil)
+      # Determine default root from SimpleCov if available
+      default_root = defined?(SimpleCov) ? SimpleCov.root : '.'
+
+      # Determine default resultset from SimpleCov if available
+      default_resultset = if defined?(SimpleCov)
+        File.join(SimpleCov.root, SimpleCov.coverage_dir, '.resultset.json')
+      end
+
+      model ||= CoverageModel.new(
+        root: root || default_root,
+        resultset: resultset || default_resultset
+      )
+      list_result = model.list(sort_order: :ascending)
+      file_list = list_result['files']
+        .select { |f| f['percentage'] && f['percentage'] < threshold }
+        .first(count)
+      file_list = model.relativize(file_list)
+
+      return nil if file_list.empty?
+
+      lines = ["\nLowest coverage files (< #{threshold}%):"]
+      file_list.each do |f|
+        label = f['file']
+        if StaleStatus.stale?(f['stale'])
+          label = "#{label} (stale: #{f['stale']})"
+        end
+        lines << format('  %5.1f%%  %s', f['percentage'], label)
+      end
+      lines.join("\n")
+    end
+  end
+end

data/lib/cov_loupe/coverage/coverage_table_formatter.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative '../staleness/stale_status'
+require_relative '../output_chars'
+
+module CovLoupe
+  # Formats coverage data as a table with box-drawing characters
+  # Extracted from CoverageModel to separate presentation from domain logic
+  class CoverageTableFormatter
+    # Format coverage rows as a table with box-drawing or ASCII characters.
+    #
+    # @param rows [Array<Hash>] Coverage rows with keys: 'file', 'percentage', 'covered', 'total', 'stale'
+    # @param output_chars [Symbol] Output character mode (:default, :fancy, or :ascii)
+    # @return [String] Formatted table with borders and summary
+    def self.format(rows, output_chars: :default)
+      return 'No coverage data found' if rows.empty?
+
+      # Resolve mode and get appropriate charset
+      resolved_mode = OutputChars.resolve_mode(output_chars)
+      charset = OutputChars.charset_for(resolved_mode)
+
+      # Convert file paths and other string content to ASCII if needed
+      converted_rows = rows.map do |row|
+        row.merge('file' => OutputChars.convert(row['file'], resolved_mode))
+      end
+
+      widths = compute_table_widths(converted_rows)
+      lines = []
+      lines << border_line(widths, charset[:top_left], charset[:top_tee], charset[:top_right], charset)
+      lines << header_row(widths, charset)
+      lines << border_line(widths, charset[:left_tee], charset[:cross], charset[:right_tee], charset)
+      converted_rows.each { |file_data| lines << data_row(file_data, widths, charset) }
+      lines << border_line(widths, charset[:bottom_left], charset[:bottom_tee], charset[:bottom_right],
+        charset)
+      lines << summary_counts(converted_rows)
+      if converted_rows.any? { |f| StaleStatus.stale?(f['stale']) }
+        lines <<
+          'Staleness: error, missing, newer, length_mismatch'
+      end
+      lines.join("\n")
+    end
+
+    # Calculate column widths based on data
+    #
+    # @param rows [Array<Hash>] Coverage rows
+    # @return [Hash] Width for each column (:file, :pct, :covered, :total, :stale)
+    private_class_method def self.compute_table_widths(rows)
+      max_file_length = rows.map { |f| f['file'].length }.max.to_i
+      file_width = [max_file_length, 'File'.length].max + 2
+      pct_width = 8
+      max_covered = rows.map { |f| f['covered'].to_s.length }.max
+      max_total = rows.map { |f| f['total'].to_s.length }.max
+      covered_width = [max_covered, 'Covered'.length].max + 2
+      total_width = [max_total, 'Total'.length].max + 2
+      max_stale_label = rows.map { |f| StaleStatus.stale?(f['stale']) ? f['stale'].to_s.length : 0 }.max.to_i
+      stale_width = [max_stale_label, 'Stale'.length].max
+      {
+        file: file_width,
+        pct: pct_width,
+        covered: covered_width,
+        total: total_width,
+        stale: stale_width
+      }
+    end
+
+    # Generate a border line for the table
+    #
+    # @param widths [Hash] Column widths
+    # @param left [String] Left edge character
+    # @param middle [String] Column separator character
+    # @param right [String] Right edge character
+    # @param charset [Hash] Character set for borders
+    # @return [String] Border line
+    private_class_method def self.border_line(widths, left, middle, right, charset)
+      h = charset[:horizontal]
+      h_line = ->(col_width) { h * (col_width + 2) }
+      left +
+        h_line.call(widths[:file]) +
+        middle + h_line.call(widths[:pct]) +
+        middle + h_line.call(widths[:covered]) +
+        middle + h_line.call(widths[:total]) +
+        middle + h_line.call(widths[:stale]) +
+        right
+    end
+
+    # Generate the header row
+    #
+    # @param widths [Hash] Column widths
+    # @param charset [Hash] Character set for borders
+    # @return [String] Header row
+    private_class_method def self.header_row(widths, charset)
+      v = charset[:vertical]
+      Kernel.format(
+        "#{v} %-#{widths[:file]}s #{v} %#{widths[:pct]}s #{v} %#{widths[:covered]}s " \
+        "#{v} %#{widths[:total]}s #{v} %#{widths[:stale]}s #{v}",
+        'File', ' %', 'Covered', 'Total', 'Stale'.center(widths[:stale])
+      )
+    end
+
+    # Generate a data row for a single file
+    #
+    # @param file_data [Hash] Coverage data for one file
+    # @param widths [Hash] Column widths
+    # @param charset [Hash] Character set for borders
+    # @return [String] Data row
+    private_class_method def self.data_row(file_data, widths, charset)
+      fd = file_data
+      ws = widths
+      v = charset[:vertical]
+      is_stale = StaleStatus.stale?(fd['stale'])
+      stale_str = is_stale ? fd['stale'].to_s.center(ws[:stale]) : ''
+      pct_str = if fd['percentage']
+        Kernel.format("%#{ws[:pct] - 1}.2f%%", fd['percentage'])
+      else
+        'n/a'.rjust(ws[:pct])
+      end
+
+      format_str = "#{v} %-#{ws[:file]}s #{v} %s #{v} %#{ws[:covered]}d #{v} %#{ws[:total]}d #{v} %#{ws[:stale]}s #{v}"
+      Kernel.format(format_str, fd['file'], pct_str, fd['covered'], fd['total'], stale_str)
+    end
+
+    # Generate summary counts footer
+    #
+    # @param rows [Array<Hash>] Coverage rows
+    # @return [String] Summary line
+    private_class_method def self.summary_counts(rows)
+      total = rows.length
+      stale_count = rows.count { |f| StaleStatus.stale?(f['stale']) }
+      ok_count = total - stale_count
+      "Files: total #{total}, ok #{ok_count}, stale #{stale_count}"
+    end
+  end
+end

data/lib/cov_loupe/{error_handler.rb → errors/error_handler.rb}

@@ -2,7 +2,6 @@
 
 require 'json'
 require_relative 'errors'
-require_relative 'util'
 
 module CovLoupe
   # Handles error reporting and logging with configurable behavior
@@ -32,7 +31,7 @@ module CovLoupe
     def handle_error(error, context: nil, reraise: true)
       log_error(error, context)
       if reraise
-        raise error.is_a?(CovLoupe::Error) ? error : convert_standard_error(error)
+        raise error.is_a?(CovLoupe::Error) ? error : convert_standard_error(error, context: context)
       end
     end
 
@@ -48,18 +47,24 @@ module CovLoupe
       when Errno::EISDIR
         filename = extract_filename(error.message)
         NotAFileError.new("Expected file but found directory: #{filename}", error)
+      when Errno::EMFILE, Errno::ENOSPC, IOError
+        FileError.new(error.message, error)
+      when Errno::EROFS
+        FilePermissionError.new(error.message, error)
       when JSON::ParserError
         CoverageDataError.new("Invalid coverage data format: #{error.message}", error)
+      when EncodingError
+        CoverageDataError.new("Invalid encoding in coverage data: #{error.message}", error)
+      when RangeError
+        CoverageDataError.new("Numeric overflow or range error: #{error.message}", error)
       when TypeError
         CoverageDataError.new("Invalid coverage data structure: #{error.message}", error)
       when ArgumentError
         convert_argument_error(error, context)
       when NoMethodError
         convert_no_method_error(error, context)
-      when RuntimeError
-        convert_runtime_error(error, context)
-      else
-        Error.new("An unexpected error occurred: #{error.message}", error)
+      else # including RuntimeError
+        UnknownError.new(error.message, error)
       end
     end
 
@@ -100,40 +105,23 @@ module CovLoupe
       end
     end
 
-    private def convert_runtime_error(error, context)
-      message = error.message
-      if message.include?('Could not find .resultset.json')
-        dir_info = message.match(/under (.+?)(?:;|$)/)&.[](1) || 'project directory'
-        CoverageDataError.new(
-          "Coverage data not found in #{dir_info} - please run your tests first", error)
-      elsif message.include?('No .resultset.json found in directory')
-        dir_info = message.match(/directory: (.+)$/)&.[](1) || 'specified directory'
-        CoverageDataError.new("Coverage data not found in directory: #{dir_info}", error)
-      elsif message.include?('Specified resultset not found')
-        # Preserve the original message format for consistency with existing tests
-        ResultsetNotFoundError.new(message, error)
-      elsif context == :coverage_loading
-        if message.downcase.include?('resultset')
-          ResultsetNotFoundError.new(message, error)
-        else
-          CoverageDataError.new("Failed to load coverage data: #{message}", error)
-        end
-      else
-        Error.new("An unexpected error occurred: #{message}", error)
-      end
-    end
 
     private def log_error(error, context)
       return unless log_errors?
 
       message = build_log_message(error, context)
-      if logger
-        logger.error(message)
-      else
-        CovUtil.log(message)
-      end
+      active_logger = @logger || CovLoupe.logger
+      active_logger.error(message)
     end
 
+    # Build log message for error logging.
+    # NOTE: Log messages are NOT converted to ASCII in ASCII output mode.
+    # This is intentional because:
+    # - Log files are system/debugging artifacts, not user-facing output
+    # - The output_chars feature targets terminal errors/warnings, not log files
+    # - Converting would lose debugging information (exact file paths, error details)
+    # - Creates inconsistency between logged paths and actual filesystem paths
+    # - No user value since logs are developer artifacts
     private def build_log_message(error, context)
       context_suffix = context ? " in #{context}" : ''
       parts = ["Error#{context_suffix}: #{error.class}: #{error.message}"]