cov-loupe 3.0.0

data/lib/cov_loupe/coverage_reporter.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # 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
+  #
+  module CoverageReporter
+    module_function def report(threshold: 80, count: 5, model: nil)
+      model ||= CoverageModel.new
+      file_list = model.all_files(sort_order: :ascending)
+        .select { |f| 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|
+        lines << format('  %5.1f%%  %s', f['percentage'], f['file'])
+      end
+      lines.join("\n")
+    end
+  end
+end

data/lib/cov_loupe/error_handler.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'errors'
+require_relative 'util'
+
+module CovLoupe
+  # Handles error reporting and logging with configurable behavior
+  class ErrorHandler
+    attr_accessor :error_mode, :logger
+
+    VALID_ERROR_MODES = [:off, :log, :debug].freeze
+
+    def initialize(error_mode: :log, logger: nil)
+      unless VALID_ERROR_MODES.include?(error_mode)
+        raise ArgumentError, "Invalid error_mode: #{error_mode.inspect}. Valid modes: #{VALID_ERROR_MODES.inspect}"
+      end
+
+      @error_mode = error_mode
+      @logger = logger
+    end
+
+    def log_errors?
+      error_mode != :off
+    end
+
+    def show_stack_traces?
+      error_mode == :debug
+    end
+
+    # Handle an error with appropriate logging and re-raising behavior
+    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)
+      end
+    end
+
+    # Convert standard Ruby errors to user-friendly custom errors.
+    # @param error [Exception] the error to convert
+    # @param context [Symbol] :general (default) or :coverage_loading for context-specific messages
+    def convert_standard_error(error, context: :general)
+      case error
+      when Errno::ENOENT
+        convert_enoent(error, context)
+      when Errno::EACCES
+        convert_eacces(error, context)
+      when Errno::EISDIR
+        filename = extract_filename(error.message)
+        NotAFileError.new("Expected file but found directory: #{filename}", error)
+      when JSON::ParserError
+        CoverageDataError.new("Invalid coverage data format: #{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)
+      end
+    end
+
+    private def convert_enoent(error, context)
+      if context == :coverage_loading
+        ResultsetNotFoundError.new('Coverage data not found', error)
+      else
+        filename = extract_filename(error.message)
+        FileNotFoundError.new("File not found: #{filename}", error)
+      end
+    end
+
+    private def convert_eacces(error, context)
+      if context == :coverage_loading
+        FilePermissionError.new("Permission denied reading coverage data: #{error.message}", error)
+      else
+        filename = extract_filename(error.message)
+        FilePermissionError.new("Permission denied accessing file: #{filename}", error)
+      end
+    end
+
+    private def convert_argument_error(error, context)
+      if context == :coverage_loading
+        CoverageDataError.new("Invalid path in coverage data: #{error.message}", error)
+      elsif error.message.include?('wrong number of arguments')
+        UsageError.new("Invalid number of arguments: #{error.message}", error)
+      else
+        ConfigurationError.new("Invalid configuration: #{error.message}", error)
+      end
+    end
+
+    private def convert_no_method_error(error, context)
+      if context == :coverage_loading
+        CoverageDataError.new("Invalid coverage data structure: #{error.message}", error)
+      else
+        method_info = extract_method_info(error.message)
+        CoverageDataError.new("Invalid coverage data structure - #{method_info}", error)
+      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
+    end
+
+    private def build_log_message(error, context)
+      context_suffix = context ? " in #{context}" : ''
+      parts = ["Error#{context_suffix}: #{error.class}: #{error.message}"]
+
+      if show_stack_traces? && error.backtrace
+        parts << error.backtrace.join("\n")
+      end
+
+      parts.join("\n")
+    end
+
+    private def extract_filename(message)
+      # Extract filename from "No such file or directory @ rb_sysopen - filename"
+      match = message.match(/@ \w+ - (.+)$/)
+      match ? match[1] : 'unknown file'
+    end
+
+    private def extract_method_info(message)
+      match = message.match(/undefined method `(.+?)' for (.+)$/)
+      if match
+        method_name = match[1]
+        object_info = match[2].gsub(/#<.*?>/, 'object')
+        "missing method '#{method_name}' on #{object_info}"
+      else
+        message
+      end
+    end
+  end
+end

data/lib/cov_loupe/error_handler_factory.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'error_handler'
+
+module CovLoupe
+  module ErrorHandlerFactory
+    # Error handler for CLI usage
+    # - Logs errors for debugging
+    # - Shows stack traces only when explicitly requested
+    # - Suitable for user-facing command line interface
+    def self.for_cli(error_mode: :log)
+      ErrorHandler.new(error_mode: error_mode)
+    end
+
+    # Error handler for library usage
+    # - No logging by default (avoids side effects in consuming applications)
+    # - No stack traces (libraries should let consumers handle error display)
+    # - Suitable for embedding in other applications
+    def self.for_library(error_mode: :off)
+      ErrorHandler.new(error_mode: error_mode)
+    end
+
+    # Error handler for MCP server usage
+    # - Logs errors for server debugging
+    # - Shows stack traces only when explicitly requested
+    # - Suitable for long-running server processes
+    def self.for_mcp_server(error_mode: :log)
+      ErrorHandler.new(error_mode: error_mode)
+    end
+  end
+end

data/lib/cov_loupe/errors.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Base error class for all SimpleCov MCP errors
+  class Error < StandardError
+    attr_reader :original_error
+
+    def initialize(message = nil, original_error = nil)
+      @original_error = original_error
+      super(message)
+    end
+
+    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
+  class ConfigurationError < Error
+    def user_friendly_message
+      "Configuration error: #{message}"
+    end
+  end
+
+  # File or path related errors
+  class FileError < Error
+    def user_friendly_message
+      "File error: #{message}"
+    end
+  end
+
+  # More specific file errors
+  class FileNotFoundError < FileError; end
+  class FilePermissionError < FileError; end
+  class NotAFileError < FileError; end
+
+  class ResultsetNotFoundError < FileError
+    def user_friendly_message
+      base = "File error: #{message}"
+
+      # Only add helpful tips in CLI and library modes, not MCP mode
+      unless CovLoupe.context.mcp_mode?
+        base += <<~HELP
+
+
+          Try one of the following:
+            - cd to a directory containing coverage/.resultset.json
+            - Specify a resultset: cov-loupe -r PATH
+            - Use -h for help: cov-loupe -h
+        HELP
+      end
+
+      base
+    end
+  end
+
+  # Coverage data related errors
+  class CoverageDataError < Error
+    def user_friendly_message
+      "Coverage data error: #{message}"
+    end
+  end
+
+  # Coverage data is present but appears stale compared to source files
+  class CoverageDataStaleError < CoverageDataError
+    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,
+      cov_timestamp: nil, src_len: nil, cov_len: nil, resultset_path: nil)
+      @file_path = file_path
+      @file_mtime = file_mtime
+      @cov_timestamp = cov_timestamp
+      @src_len = src_len
+      @cov_len = cov_len
+      @resultset_path = resultset_path
+      super(message || default_message, original_error)
+    end
+
+    def user_friendly_message
+      "Coverage data stale: #{message}" + build_details
+    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
+
+    def initialize(message = nil, original_error = nil, cov_timestamp: nil, newer_files: [],
+      missing_files: [], deleted_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)
+      @resultset_path = resultset_path
+    end
+
+    def user_friendly_message
+      base = "Coverage data stale (project): #{message || default_message}"
+      base + build_details
+    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
+  class UsageError < Error
+    def self.for_subcommand(usage_fragment)
+      new("Usage: cov-loupe #{usage_fragment}")
+    end
+
+    def user_friendly_message
+      message
+    end
+  end
+end

data/lib/cov_loupe/formatters/source_formatter.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  module Formatters
+    class SourceFormatter
+      def initialize(color_enabled: true)
+        @color_enabled = color_enabled
+      end
+
+      def format_source_for(model, path, mode: nil, context: 2)
+        raw = fetch_raw(model, path)
+        return '[source not available]' unless raw
+
+        abs = raw['file']
+        lines_cov = raw['lines']
+        src = File.file?(abs) ? File.readlines(abs, chomp: true) : nil
+        return '[source not available]' unless src
+
+        begin
+          rows = build_source_rows(src, lines_cov, mode: mode, context: context)
+          format_source_rows(rows)
+        rescue ArgumentError
+          raise
+        rescue
+          # If any unexpected formatting/indexing error occurs, avoid crashing the CLI
+          '[source not available]'
+        end
+      end
+
+      def build_source_payload(model, path, mode: nil, context: 2)
+        raw = fetch_raw(model, path)
+        return nil unless raw
+
+        abs = raw['file']
+        lines_cov = raw['lines']
+        src = File.file?(abs) ? File.readlines(abs, chomp: true) : nil
+        return nil unless src
+
+        build_source_rows(src, lines_cov, mode: mode, context: context)
+      end
+
+      def build_source_rows(src_lines, cov_lines, mode:, context: 2)
+        # Normalize inputs defensively to avoid type errors in formatting
+        coverage_lines = cov_lines || []
+        context_line_count = begin
+          context.to_i
+        rescue
+          2
+        end
+        raise ArgumentError, 'Context lines cannot be negative' if context_line_count.negative?
+
+        n = src_lines.length
+        include_line = Array.new(n, mode == :full)
+        if mode == :uncovered
+          include_line = mark_uncovered_lines_with_context(coverage_lines, context_line_count, n)
+        end
+
+        build_row_data(src_lines, coverage_lines, include_line)
+      end
+
+      def format_source_rows(rows)
+        marker = ->(covered, _hits) do
+          case covered
+          when true then colorize('✓', :green)
+          when false then colorize('·', :red)
+          else colorize(' ', :dim)
+          end
+        end
+
+        lines = []
+        lines << format('%6s  %2s | %s', 'Line', ' ', 'Source')
+        lines << format('%6s  %2s-+-%s', '------', '--', '-' * 60)
+
+        rows.each do |r|
+          m = marker.call(r['covered'], r['hits'])
+          lines << format('%6d  %2s | %s', r['line'], m, r['code'])
+        end
+        lines.join("\n")
+      end
+
+      def format_detailed_rows(rows)
+        # Simple aligned columns: line, hits, covered
+        out = []
+        out << format('%6s  %6s  %7s', 'Line', 'Hits', 'Covered')
+        out << format('%6s  %6s  %7s', '-----', '----', '-------')
+        rows.each do |r|
+          out << format('%6d  %6d  %5s', r['line'], r['hits'], r['covered'] ? 'yes' : 'no')
+        end
+        out.join("\n")
+      end
+
+      attr_reader :color_enabled
+
+      private def fetch_raw(model, path)
+        @raw_cache ||= {}
+        return @raw_cache[path] if @raw_cache.key?(path)
+
+        raw = model.raw_for(path)
+        @raw_cache[path] = raw
+      rescue
+        nil
+      end
+
+      private def mark_uncovered_lines_with_context(coverage_lines, context_line_count, total_lines)
+        include_line = Array.new(total_lines, false)
+        misses = find_uncovered_lines(coverage_lines)
+
+        misses.each do |uncovered_line_index|
+          mark_context_lines(include_line, uncovered_line_index, context_line_count, total_lines)
+        end
+
+        include_line
+      end
+
+      private def find_uncovered_lines(coverage_lines)
+        misses = []
+        coverage_lines.each_with_index do |hits, i|
+          misses << i if !hits.nil? && hits.to_i == 0
+        end
+        misses
+      end
+
+      private def mark_context_lines(include_line, center_line, context_count, total_lines)
+        start_line = [0, center_line - context_count].max
+        end_line = [total_lines - 1, center_line + context_count].min
+
+        (start_line..end_line).each { |i| include_line[i] = true }
+      end
+
+      private def build_row_data(src_lines, coverage_lines, include_line)
+        out = []
+        src_lines.each_with_index do |code, i|
+          next unless include_line[i]
+
+          hits = coverage_lines[i]
+          covered = hits.nil? ? nil : hits.to_i > 0
+          # Use string keys consistently across CLI formatting and JSON payloads
+          out << { 'line' => i + 1, 'code' => code, 'hits' => hits, 'covered' => covered }
+        end
+        out
+      end
+
+      private def colorize(text, color)
+        return text unless color_enabled
+
+        codes = { green: 32, red: 31, dim: 2 }
+        code = codes[color] || 0
+        "\e[#{code}m#{text}\e[0m"
+      end
+    end
+  end
+end

data/lib/cov_loupe/formatters.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module CovLoupe
+  module Formatters
+    # Maps format symbols to their formatter lambdas
+    # Following the rexe pattern for simple, extensible formatting
+    FORMATTERS = {
+      table: ->(obj) { obj }, # Pass through - table formatting handled elsewhere
+      json: lambda(&:to_json),
+      pretty_json: ->(obj) { JSON.pretty_generate(obj) },
+      yaml: ->(obj) {
+        require 'yaml'
+        obj.to_yaml
+      },
+      awesome_print: ->(obj) {
+        require 'awesome_print'
+        obj.ai
+      }
+    }.freeze
+
+    # Maps format symbols to their required libraries
+    # Only loaded when the format is actually used
+    FORMAT_REQUIRES = {
+      yaml: 'yaml',
+      awesome_print: 'awesome_print'
+    }.freeze
+
+    # Returns the formatter lambda for the given format
+    def self.formatter_for(format)
+      FORMATTERS[format] or raise ArgumentError, "Unknown format: #{format}"
+    end
+
+    # 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
+    def self.format(obj, format)
+      ensure_requirements_for(format)
+      formatter_for(format).call(obj)
+    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
+  end
+end

data/lib/cov_loupe/mcp_server.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  class MCPServer
+    def initialize(context: CovLoupe.context)
+      @context = context
+    end
+
+    def run
+      CovLoupe.with_context(context) do
+        server = ::MCP::Server.new(
+          name: 'cov-loupe',
+          version: CovLoupe::VERSION,
+          tools: toolset
+        )
+        ::MCP::Server::Transports::StdioTransport.new(server).open
+      end
+    end
+
+    TOOLSET = [
+      Tools::AllFilesCoverageTool,
+      Tools::CoverageDetailedTool,
+      Tools::CoverageRawTool,
+      Tools::CoverageSummaryTool,
+      Tools::CoverageTotalsTool,
+      Tools::UncoveredLinesTool,
+      Tools::CoverageTableTool,
+      Tools::ValidateTool,
+      Tools::HelpTool,
+      Tools::VersionTool
+    ].freeze
+
+    # Expose the registered tools so embedders can introspect without booting the server.
+    def toolset
+      TOOLSET
+    end
+
+    private
+
+    attr_reader :context
+  end
+end