cov-loupe 3.0.0 → 4.0.0.pre

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../staleness/staleness_message_formatter'
+
 module CovLoupe
   # Base error class for all SimpleCov MCP errors
   class Error < StandardError
@@ -13,34 +15,6 @@ module CovLoupe
     def user_friendly_message
       message
     end
-
-    protected def format_epoch_both(epoch_seconds)
-      return [nil, nil] unless epoch_seconds
-
-      t = Time.at(epoch_seconds.to_i)
-      [t.utc.iso8601, t.getlocal.iso8601]
-    rescue
-      [epoch_seconds.to_s, epoch_seconds.to_s]
-    end
-
-    protected def format_time_both(time)
-      return [nil, nil] unless time
-
-      t = time.is_a?(Time) ? time : Time.parse(time.to_s)
-      [t.utc.iso8601, t.getlocal.iso8601]
-    rescue
-      [time.to_s, time.to_s]
-    end
-
-    protected def format_delta_seconds(file_mtime, cov_timestamp)
-      return nil unless file_mtime && cov_timestamp
-
-      seconds = file_mtime.to_i - cov_timestamp.to_i
-      sign = seconds >= 0 ? '+' : '-'
-      "#{sign}#{seconds.abs}s"
-    rescue
-      nil
-    end
   end
 
   # Configuration or setup related errors
@@ -50,6 +24,13 @@ module CovLoupe
     end
   end
 
+  # Error wrapper when the root cause is unknown or unclassified.
+  class UnknownError < Error
+    def user_friendly_message
+      "An unexpected error occurred: #{message}"
+    end
+  end
+
   # File or path related errors
   class FileError < Error
     def user_friendly_message
@@ -89,8 +70,26 @@ module CovLoupe
     end
   end
 
+  class CorruptCoverageDataError < CoverageDataError
+    def user_friendly_message
+      "Corrupt coverage data: #{message}"
+    end
+  end
+
+  # Shared module for stale error formatting
+  module StalenessFormatterMixin
+    private def formatter
+      @formatter ||= StalenessMessageFormatter.new(
+        cov_timestamp: @cov_timestamp,
+        resultset_path: @resultset_path
+      )
+    end
+  end
+
   # Coverage data is present but appears stale compared to source files
   class CoverageDataStaleError < CoverageDataError
+    include StalenessFormatterMixin
+
     attr_reader :file_path, :file_mtime, :cov_timestamp, :src_len, :cov_len, :resultset_path
 
     def initialize(message = nil, original_error = nil, file_path: nil, file_mtime: nil,
@@ -105,77 +104,55 @@ module CovLoupe
     end
 
     def user_friendly_message
-      "Coverage data stale: #{message}" + build_details
+      "Coverage data stale: #{message}" + formatter.format_single_file_details(
+        file_path: @file_path,
+        file_mtime: @file_mtime,
+        src_len: @src_len,
+        cov_len: @cov_len
+      )
     end
 
     private def default_message
       fp = file_path || 'file'
       "Coverage data appears stale for #{fp}"
     end
-
-    private def build_details
-      file_utc, file_local = format_time_both(@file_mtime)
-      cov_utc,  cov_local  = format_epoch_both(@cov_timestamp)
-      delta_str = format_delta_seconds(@file_mtime, @cov_timestamp)
-
-      details = <<~DETAILS
-
-        File     - time: #{file_utc || 'not found'} (local #{file_local || 'n/a'}), lines: #{@src_len}
-        Coverage - time: #{cov_utc  || 'not found'} (local #{cov_local  || 'n/a'}), lines: #{@cov_len}
-        DETAILS
-
-      details += "\nDelta    - file is #{delta_str} newer than coverage" if delta_str
-      details += "\nResultset - #{@resultset_path}" if @resultset_path
-      details.chomp
-    end
   end
 
   # Project-level stale coverage (global) — coverage timestamp older than
   # one or more source files, or new tracked files missing from coverage.
   class CoverageDataProjectStaleError < CoverageDataError
-    attr_reader :cov_timestamp, :newer_files, :missing_files, :deleted_files, :resultset_path
+    include StalenessFormatterMixin
+
+    attr_reader :cov_timestamp, :newer_files, :missing_files, :deleted_files,
+      :length_mismatch_files, :unreadable_files, :resultset_path
 
     def initialize(message = nil, original_error = nil, cov_timestamp: nil, newer_files: [],
-      missing_files: [], deleted_files: [], resultset_path: nil)
+      missing_files: [], deleted_files: [], length_mismatch_files: [], unreadable_files: [],
+      resultset_path: nil)
       super(message, original_error)
       @cov_timestamp = cov_timestamp
       @newer_files = Array(newer_files)
       @missing_files = Array(missing_files)
       @deleted_files = Array(deleted_files)
+      @length_mismatch_files = Array(length_mismatch_files)
+      @unreadable_files = Array(unreadable_files)
       @resultset_path = resultset_path
     end
 
     def user_friendly_message
       base = "Coverage data stale (project): #{message || default_message}"
-      base + build_details
+      base + formatter.format_project_details(
+        newer_files: @newer_files,
+        missing_files: @missing_files,
+        deleted_files: @deleted_files,
+        length_mismatch_files: @length_mismatch_files,
+        unreadable_files: @unreadable_files
+      )
     end
 
     private def default_message
       'Coverage data appears stale for project'
     end
-
-    private def build_details
-      cov_utc, cov_local = format_epoch_both(@cov_timestamp)
-      parts = []
-      parts << "\nCoverage  - time: #{cov_utc || 'not found'} (local #{cov_local || 'n/a'})"
-      unless @newer_files.empty?
-        parts << "\nNewer files (#{@newer_files.size}):"
-        parts.concat(@newer_files.first(10).map { |f| "  - #{f}" })
-        parts << '  ...' if @newer_files.size > 10
-      end
-      unless @missing_files.empty?
-        parts << "\nMissing files (new in project, not in coverage, #{@missing_files.size}):"
-        parts.concat(@missing_files.first(10).map { |f| "  - #{f}" })
-        parts << '  ...' if @missing_files.size > 10
-      end
-      unless @deleted_files.empty?
-        parts << "\nCoverage-only files (deleted or moved in project, #{@deleted_files.size}):"
-        parts.concat(@deleted_files.first(10).map { |f| "  - #{f}" })
-        parts << '  ...' if @deleted_files.size > 10
-      end
-      parts << "\nResultset - #{@resultset_path}" if @resultset_path
-      parts.join
-    end
   end
 
   # Command line usage errors

data/lib/cov_loupe/formatters/formatters.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../output_chars'
+
+module CovLoupe
+  module Formatters
+    # Maps format symbols to their required libraries
+    # Only loaded when the format is actually used
+    FORMAT_REQUIRES = {
+      yaml: 'yaml',
+      amazing_print: 'amazing_print'
+    }.freeze
+
+    # Ensures required libraries are loaded for the given format
+    def self.ensure_requirements_for(format)
+      requirement = FORMAT_REQUIRES[format]
+      require requirement if requirement
+    end
+
+    # Formats an object using the specified format.
+    #
+    # @param obj [Object] The object to format
+    # @param format [Symbol] Format type (:table, :json, :pretty_json, :yaml, :amazing_print)
+    # @param output_chars [Symbol] Output character mode (:default, :fancy, :ascii)
+    # @return [String] Formatted output
+    def self.format(obj, format, output_chars: :default)
+      ensure_requirements_for(format)
+      ascii_mode = OutputChars.ascii_mode?(output_chars)
+
+      case format
+      when :table
+        # Pass through - table formatting handled elsewhere with its own output_chars
+        obj
+      when :json
+        ascii_mode ? JSON.generate(obj, ascii_only: true) : obj.to_json
+      when :pretty_json
+        ascii_mode ? JSON.pretty_generate(obj, ascii_only: true) : JSON.pretty_generate(obj)
+      when :yaml
+        format_yaml(obj, ascii_mode: ascii_mode)
+      when :amazing_print
+        require 'amazing_print'
+        result = obj.ai
+        # AmazingPrint doesn't have native ASCII mode; convert if needed
+        ascii_mode ? OutputChars.convert(result, :ascii) : result
+      else
+        raise ArgumentError, "Unknown format: #{format}"
+      end
+    rescue LoadError => e
+      gem_name = e.message[/-- (\S+)/, 1] || 'required gem'
+      raise LoadError, "The #{format} format requires the '#{gem_name}' gem. " \
+                       "Install it with: gem install #{gem_name}"
+    end
+
+    # Formats an object as YAML, with optional ASCII-only output.
+    #
+    # YAML doesn't have a native ASCII-only mode, so for ASCII mode we:
+    # 1. Generate standard YAML
+    # 2. Convert any non-ASCII characters using OutputChars.convert
+    #
+    # This approach preserves YAML structure while ensuring ASCII-only output.
+    # Note: This may affect string values containing Unicode, but YAML structure
+    # (which is ASCII) remains valid.
+    #
+    # @param obj [Object] The object to format
+    # @param ascii_mode [Boolean] If true, ensure ASCII-only output
+    # @return [String] YAML-formatted output
+    def self.format_yaml(obj, ascii_mode: false)
+      require 'yaml'
+      yaml = obj.to_yaml
+      ascii_mode ? OutputChars.convert(yaml, :ascii) : yaml
+    end
+    private_class_method :format_yaml
+  end
+end

data/lib/cov_loupe/formatters/source_formatter.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
+require_relative '../output_chars'
+
 module CovLoupe
   module Formatters
     class SourceFormatter
-      def initialize(color_enabled: true)
+      def initialize(color_enabled: true, output_chars: :default)
         @color_enabled = color_enabled
+        @output_chars = output_chars
       end
 
       def format_source_for(model, path, mode: nil, context: 2)
@@ -21,8 +24,9 @@ module CovLoupe
           format_source_rows(rows)
         rescue ArgumentError
           raise
-        rescue
+        rescue => e
           # If any unexpected formatting/indexing error occurs, avoid crashing the CLI
+          CovLoupe.logger.safe_log("SourceFormatter#format_source_for error for path '#{abs}': #{e.class} - #{e.message}")
           '[source not available]'
         end
       end
@@ -59,10 +63,14 @@ module CovLoupe
       end
 
       def format_source_rows(rows)
+        # Use ASCII-safe markers when output_chars is :ascii
+        check_mark = OutputChars.ascii_mode?(@output_chars) ? '+' : "\u2713" # ✓
+        miss_mark = OutputChars.ascii_mode?(@output_chars) ? '-' : "\u00B7"  # ·
+
         marker = ->(covered, _hits) do
           case covered
-          when true then colorize('✓', :green)
-          when false then colorize('·', :red)
+          when true then colorize(check_mark, :green)
+          when false then colorize(miss_mark, :red)
           else colorize(' ', :dim)
           end
         end
@@ -73,7 +81,9 @@ module CovLoupe
 
         rows.each do |r|
           m = marker.call(r['covered'], r['hits'])
-          lines << format('%6d  %2s | %s', r['line'], m, r['code'])
+          # Convert source code to ASCII when in ASCII mode
+          code = OutputChars.convert(r['code'], @output_chars)
+          lines << format('%6d  %2s | %s', r['line'], m, code)
         end
         lines.join("\n")
       end
@@ -89,7 +99,7 @@ module CovLoupe
         out.join("\n")
       end
 
-      attr_reader :color_enabled
+      attr_reader :color_enabled, :output_chars
 
       private def fetch_raw(model, path)
         @raw_cache ||= {}
@@ -97,7 +107,8 @@ module CovLoupe
 
         raw = model.raw_for(path)
         @raw_cache[path] = raw
-      rescue
+      rescue => e
+        CovLoupe.logger.safe_log("SourceFormatter#fetch_raw error for path '#{path}': #{e.class} - #{e.message}")
         nil
       end
 

data/lib/cov_loupe/formatters/table_formatter.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative '../output_chars'
+
+module CovLoupe
+  # General-purpose table formatter with box-drawing or ASCII characters
+  # Used by commands to create consistent formatted output
+  class TableFormatter
+    # Format data as a table with box-drawing or ASCII characters.
+    # @param headers [Array<String>] Column headers
+    # @param rows [Array<Array>] Data rows (each row is an array of cell values)
+    # @param alignments [Array<Symbol>] Column alignments (:left, :right, :center)
+    # @param output_chars [Symbol] Output character mode (:default, :fancy, or :ascii)
+    # @return [String] Formatted table
+    def self.format(headers:, rows:, alignments: nil, output_chars: :default)
+      return 'No data to display' if rows.empty?
+
+      # Resolve mode and get appropriate charset
+      resolved_mode = OutputChars.resolve_mode(output_chars)
+      charset = OutputChars.charset_for(resolved_mode)
+
+      # Convert cell contents to ASCII if needed
+      convert = ->(text) { OutputChars.convert(text.to_s, resolved_mode) }
+
+      alignments ||= [:left] * headers.size
+      converted_headers = headers.map(&convert)
+      converted_rows = rows.map { |row| row.map(&convert) }
+      all_rows = [converted_headers] + converted_rows
+
+      # Calculate column widths
+      widths = headers.size.times.map do |col|
+        all_rows.map { |row| row[col].to_s.length }.max
+      end
+
+      lines = []
+      lines << border_line(widths, charset[:top_left], charset[:top_tee], charset[:top_right], charset)
+      lines << data_row(converted_headers, widths, alignments, charset)
+      lines << border_line(widths, charset[:left_tee], charset[:cross], charset[:right_tee], charset)
+      converted_rows.each { |row| lines << data_row(row, widths, alignments, charset) }
+      lines << border_line(widths, charset[:bottom_left], charset[:bottom_tee], charset[:bottom_right],
+        charset)
+
+      lines.join("\n")
+    end
+
+    # Format a single key-value table (vertical layout)
+    # @param data [Hash] Key-value pairs
+    # @param output_chars [Symbol] Output character mode (:default, :fancy, or :ascii)
+    # @return [String] Formatted table
+    def self.format_vertical(data, output_chars: :default)
+      rows = data.map { |k, v| [k.to_s, v.to_s] }
+      format(headers: ['Key', 'Value'], rows: rows, alignments: [:left, :left], output_chars: output_chars)
+    end
+
+    private_class_method def self.border_line(widths, left, mid, right, charset)
+      h = charset[:horizontal]
+      segments = widths.map { |w| h * (w + 2) }
+      left + segments.join(mid) + right
+    end
+
+    private_class_method def self.data_row(cells, widths, alignments, charset)
+      v = charset[:vertical]
+      formatted = cells.each_with_index.map do |cell, i|
+        align_cell(cell.to_s, widths[i], alignments[i])
+      end
+      "#{v} #{formatted.join(" #{v} ")} #{v}"
+    end
+
+    private_class_method def self.align_cell(content, width, alignment)
+      case alignment
+      when :right
+        content.rjust(width)
+      when :center
+        content.center(width)
+      else # :left
+        content.ljust(width)
+      end
+    end
+  end
+end

data/lib/cov_loupe/loaders/all.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Load all CovLoupe components including CLI, MCP server, and all tools.
+# This file is used by the test suite (spec/spec_helper.rb) to ensure all
+# components are loaded for testing.
+#
+# For selective loading at runtime:
+# - Use all_cli.rb for CLI mode (loads optparse + CLI)
+# - Use all_mcp.rb for MCP mode (loads MCP gem + tools)
+#
+# Library users should use `require 'cov_loupe'` instead, which loads only the core
+# components (CoverageModel, errors, utilities) without the CLI/MCP overhead.
+
+require_relative 'all_cli'
+require_relative 'all_mcp'

data/lib/cov_loupe/loaders/all_cli.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Load CLI-specific components.
+# Used when CovLoupe.run detects CLI mode.
+
+require_relative '../../cov_loupe' # Core library components (lib/cov_loupe.rb)
+
+# CLI dependencies
+require 'optparse'
+require_relative '../cli'

data/lib/cov_loupe/loaders/all_mcp.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Load MCP server-specific components including all tools.
+# Used when CovLoupe.run detects MCP mode.
+
+require_relative '../../cov_loupe' # Core library components (lib/cov_loupe.rb)
+
+# MCP server dependencies
+require 'mcp'
+require 'mcp/server/transports/stdio_transport'
+require_relative '../config/config_parser'
+require_relative '../base_tool'
+require_relative '../tools/coverage_raw_tool'
+require_relative '../tools/coverage_summary_tool'
+require_relative '../tools/uncovered_lines_tool'
+require_relative '../tools/coverage_detailed_tool'
+require_relative '../tools/list_tool'
+require_relative '../tools/coverage_totals_tool'
+require_relative '../tools/coverage_table_tool'
+require_relative '../tools/validate_tool'
+require_relative '../tools/version_tool'
+require_relative '../tools/help_tool'
+require_relative '../mcp_server'

data/lib/cov_loupe/loaders/resultset_loader.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+require_relative '../errors/errors'
+
+module CovLoupe
+  class ResultsetLoader
+    Result = Struct.new(:coverage_map, :timestamp, :suite_names, keyword_init: true)
+    SuiteEntry = Struct.new(:name, :coverage, :timestamp, keyword_init: true)
+
+    def self.load(resultset_path:, logger: nil)
+      logger ||= CovLoupe.logger
+      new(resultset_path: resultset_path, logger: logger).load
+    end
+
+    def initialize(resultset_path:, logger:)
+      @resultset_path = resultset_path
+      @logger = logger
+    end
+
+    def load
+      raw = JSON.parse(File.read(@resultset_path))
+
+      suites = extract_suite_entries(raw)
+      if suites.empty?
+        raise CoverageDataError, "No test suite with coverage data found in resultset file: #{@resultset_path}"
+      end
+
+      coverage_map = build_coverage_map(suites)
+      Result.new(
+        coverage_map: coverage_map,
+        timestamp: compute_combined_timestamp(suites),
+        suite_names: suites.map(&:name)
+      )
+    end
+
+    private def extract_suite_entries(raw)
+      raw
+        .select { |_, data| data.is_a?(Hash) && data.key?('coverage') && !data['coverage'].nil? }
+        .map do |name, data|
+          SuiteEntry.new(
+            name: name.to_s,
+            coverage: normalize_suite_coverage(data['coverage'], suite_name: name),
+            timestamp: normalize_coverage_timestamp(data['timestamp'], data['created_at'])
+          )
+        end
+    end
+
+    private def build_coverage_map(suites)
+      return suites.first&.coverage if suites.length == 1
+
+      merge_suite_coverages(suites)
+    end
+
+    private def normalize_suite_coverage(coverage, suite_name:)
+      unless coverage.is_a?(Hash)
+        raise CoverageDataError, "Invalid coverage data structure for suite #{suite_name.inspect} in resultset file: #{@resultset_path}"
+      end
+
+      needs_adaptation = coverage.values.any? { |value| value.is_a?(Array) }
+      return coverage unless needs_adaptation
+
+      coverage.transform_values do |value|
+        value.is_a?(Array) ? { 'lines' => value } : value
+      end
+    end
+
+    private def merge_suite_coverages(suites)
+      require_simplecov_for_merge!
+      log_duplicate_suite_names(suites)
+
+      suites.reduce(nil) do |memo, suite|
+        coverage = suite.coverage
+        memo ?
+          SimpleCov::Combine.combine(SimpleCov::Combine::ResultsCombiner, memo, coverage) :
+          coverage
+      end
+    end
+
+    private def require_simplecov_for_merge!
+      require 'simplecov'
+    rescue LoadError
+      raise CoverageDataError, "Multiple coverage suites detected in #{@resultset_path}, but the simplecov gem could not be loaded. Install simplecov to enable suite merging."
+    end
+
+    private def log_duplicate_suite_names(suites)
+      grouped = suites.group_by(&:name)
+      duplicates = grouped.select { |_, entries| entries.length > 1 }.keys
+      return if duplicates.empty?
+
+      message = "Merging duplicate coverage suites for #{duplicates.join(', ')}"
+      @logger.safe_log(message)
+    end
+
+    private def compute_combined_timestamp(suites)
+      suites.map(&:timestamp).compact.max.to_i
+    end
+
+    private def normalize_coverage_timestamp(timestamp_value, created_at_value)
+      raw = timestamp_value.nil? ? created_at_value : timestamp_value
+      return log_missing_timestamp if raw.nil?
+
+      timestamp = case raw
+                  when Integer
+                    raw
+                  when Float, Time
+                    raw.to_i
+                  when String
+                    str = raw.strip
+                    if str.match?(/\A-?\d+(\.\d+)?\z/)
+                      # Matches optional leading "-", digits, and an optional fractional part.
+                      str.to_f.to_i
+                    elsif str.empty?
+                      0
+                    else
+                      Time.parse(str).to_i
+                    end
+                  else
+                    log_timestamp_warning(raw)
+                    return 0
+      end
+
+      timestamp = [timestamp.to_i, 0].max # change negative numbers to zero
+      log_missing_timestamp(raw) if timestamp.zero? # but log the original value
+      timestamp
+    rescue => e
+      log_timestamp_warning(raw, e)
+      0
+    end
+
+    private def log_missing_timestamp(raw_value = nil)
+      message = 'Coverage timestamp missing, defaulting to 0. ' \
+                'Time-based staleness checks will be disabled.'
+      message = "#{message} (value: #{raw_value.inspect})" if raw_value
+      @logger.safe_log(message)
+      0
+    end
+
+    private def log_timestamp_warning(raw_value, error = nil)
+      message = "Coverage resultset timestamp could not be parsed: #{raw_value.inspect}"
+      message = "#{message} (#{error.message})" if error
+      @logger.safe_log(message)
+    end
+  end
+end

data/lib/cov_loupe/mcp_server.rb

@@ -11,14 +11,15 @@ module CovLoupe
         server = ::MCP::Server.new(
           name: 'cov-loupe',
           version: CovLoupe::VERSION,
-          tools: toolset
+          tools: toolset,
+          server_context: context
         )
         ::MCP::Server::Transports::StdioTransport.new(server).open
       end
     end
 
     TOOLSET = [
-      Tools::AllFilesCoverageTool,
+      Tools::ListTool,
       Tools::CoverageDetailedTool,
       Tools::CoverageRawTool,
       Tools::CoverageSummaryTool,