simplecov-mcp 0.3.0 → 1.0.0

data/lib/simplecov_mcp/error_handler.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'errors'
+require_relative 'util'
+
+module SimpleCovMcp
+  # Handles error reporting and logging with configurable behavior
+  class ErrorHandler
+    attr_accessor :error_mode, :logger
+
+    VALID_ERROR_MODES = [:off, :on, :trace].freeze
+
+    def initialize(error_mode: :on, 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 == :trace
+    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?(SimpleCovMcp::Error) ? error : convert_standard_error(error)
+      end
+    end
+
+    # Convert standard Ruby errors to user-friendly custom errors
+    def convert_standard_error(error)
+      case error
+      when Errno::ENOENT
+        filename = extract_filename(error.message)
+        FileNotFoundError.new("File not found: #{filename}", error)
+      when Errno::EACCES
+        filename = extract_filename(error.message)
+        FilePermissionError.new("Permission denied accessing file: #{filename}", error)
+      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 - JSON parsing failed: #{error.message}", error)
+      when ArgumentError
+        if 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
+      when NoMethodError
+        method_info = extract_method_info(error.message)
+        CoverageDataError.new("Invalid coverage data structure - #{method_info}", error)
+      when RuntimeError, StandardError
+        # Handle string errors from CovUtil and other runtime errors
+        if error.message.include?('Could not find .resultset.json')
+          # Extract directory info if available
+          dir_info = error.message.match(/under (.+?)(?:;|$)/)&.[](1) || 'project directory'
+          CoverageDataError.new("Coverage data not found in #{dir_info} - please run your tests first", error)
+        elsif error.message.include?('No .resultset.json found in directory')
+          # Extract directory from error message
+          dir_info = error.message.match(/directory: (.+)$/)&.[](1) || 'specified directory'
+          CoverageDataError.new("Coverage data not found in directory: #{dir_info}", error)
+        elsif error.message.include?('Specified resultset not found')
+          # Extract path from error message
+          path_info = error.message.match(/not found: (.+)$/)&.[](1) || 'specified path'
+          ResultsetNotFoundError.new("Resultset file not found: #{path_info}", error)
+        else
+          Error.new("An unexpected error occurred: #{error.message}", error)
+        end
+      else
+        Error.new("An unexpected error occurred: #{error.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
+
+    def build_log_message(error, context)
+      parts = ["Error#{context ? " in #{context}" : ''}: #{error.class}: #{error.message}"]
+
+      if show_stack_traces? && error.backtrace
+        parts << error.backtrace.join("\n")
+      end
+
+      parts.join("\n")
+    end
+
+    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
+
+    def extract_method_info(message)
+      # Extract method info from "undefined method `foo' for #<Object:0x...>"
+      if match = message.match(/undefined method `(.+?)' for (.+)$/)
+        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/simplecov_mcp/error_handler_factory.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'error_handler'
+
+module SimpleCovMcp
+  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: :on)
+      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: :on)
+      ErrorHandler.new(error_mode: error_mode)
+    end
+  end
+end

data/lib/simplecov_mcp/errors.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module SimpleCovMcp
+  # 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 StandardError
+      [epoch_seconds.to_s, epoch_seconds.to_s]
+    end
+
+    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 StandardError
+      [time.to_s, time.to_s]
+    end
+
+    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 StandardError
+      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; 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)
+      super(message, original_error)
+      @file_path = file_path
+      @file_mtime = file_mtime
+      @cov_timestamp = cov_timestamp
+      @src_len = src_len
+      @cov_len = cov_len
+      @resultset_path = resultset_path
+    end
+
+    def user_friendly_message
+      base = "Coverage data stale: #{message || default_message}"
+      base + build_details
+    end
+
+    private
+
+    def default_message
+      fp = file_path || 'file'
+      "Coverage data appears stale for #{fp}"
+    end
+
+    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
+
+    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: simplecov-mcp #{usage_fragment}")
+    end
+
+    def user_friendly_message
+      message
+    end
+  end
+end

data/lib/simplecov_mcp/formatters/source_formatter.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module SimpleCovMcp
+  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 StandardError
+          # 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 = context.to_i rescue 2
+        context_line_count = 0 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 << sprintf('%6s  %2s | %s', 'Line', ' ', 'Source')
+        lines << sprintf('%6s  %2s-+-%s', '------', '--', '-' * 60)
+
+        rows.each do |r|
+          m = marker.call(r['covered'], r['hits'])
+          lines << sprintf('%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 << sprintf('%6s  %6s  %7s', 'Line', 'Hits', 'Covered')
+        out << sprintf('%6s  %6s  %7s', '-----', '----', '-------')
+        rows.each do |r|
+          out << sprintf('%6d  %6d  %7s', r['line'], r['hits'], r['covered'] ? 'yes' : 'no')
+        end
+        out.join("\n")
+      end
+
+      private
+
+      attr_reader :color_enabled
+
+      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 StandardError
+        nil
+      end
+
+      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
+
+      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
+
+      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
+
+      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
+
+      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/simplecov_mcp/mcp_server.rb

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

data/lib/simplecov_mcp/mode_detector.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+
+module SimpleCovMcp
+  # Centralizes the logic for detecting whether to run in CLI or MCP server mode.
+  # This makes the mode detection strategy explicit and testable.
+  class ModeDetector
+    SUBCOMMANDS = %w[list summary raw uncovered detailed version].freeze
+
+    # Reference shared constant to avoid duplication with CoverageCLI
+    OPTIONS_EXPECTING_ARGUMENT = Constants::OPTIONS_EXPECTING_ARGUMENT
+
+    def self.cli_mode?(argv, stdin: STDIN)
+      # 1. Explicit flags that force CLI mode always win
+      cli_options = %w[--force-cli -h --help --version]
+      return true if (argv & cli_options).any?
+
+      # 2. Find the first non-option argument
+      first_non_option = find_first_non_option(argv)
+
+      # 3. If a non-option argument exists, it must be a CLI command (or an error)
+      return true if first_non_option
+
+      # 4. Fallback: If no non-option args, use TTY status to decide
+      stdin.tty?
+    end
+
+    def self.mcp_server_mode?(argv, stdin: STDIN)
+      !cli_mode?(argv, stdin: stdin)
+    end
+
+    # Scans argv and returns the first token that is not an option or a value for an option.
+    def self.find_first_non_option(argv)
+      pending_option = false
+      argv.each do |token|
+        if pending_option
+          pending_option = false
+          next
+        end
+
+        if token.start_with?('-')
+          # Check if the option is one that takes a value and isn't using '=' syntax.
+          pending_option = OPTIONS_EXPECTING_ARGUMENT.include?(token) && !token.include?('=')
+          next
+        end
+
+        # Found the first token that is not an option
+        return token
+      end
+      nil
+    end
+    private_class_method :find_first_non_option
+  end
+end