simplecov-mcp 0.3.0 → 1.0.0

data/exe/simplecov-mcp

@@ -2,8 +2,8 @@
 # frozen_string_literal: true
 
 # Make it safe to run via symlink by resolving the real path
-root = File.expand_path("..", File.realpath(__FILE__))
-lib  = File.join(root, "lib")
+root = File.expand_path('..', File.realpath(__FILE__))
+lib  = File.join(root, 'lib')
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 # Fail fast with a helpful message if Ruby is too old for this gem
@@ -11,13 +11,13 @@ begin
   require 'rubygems'
   if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.2')
     $stderr.puts "simplecov-mcp requires Ruby >= 3.2 (current: #{RUBY_VERSION})."
-    $stderr.puts "Please run with a supported Ruby version (e.g., via rbenv, rvm, asdf)."
+    $stderr.puts 'Please run with a supported Ruby version (e.g., via rbenv, rvm, asdf).'
     exit 1
   end
 rescue StandardError
   # If anything goes wrong, let the app load and potentially fail with a more specific error.
 end
 
-require 'simple_cov_mcp'
+require 'simplecov_mcp'
 
 SimpleCovMcp.run(ARGV)

data/lib/simplecov_mcp/app_context.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module SimpleCovMcp
+  # Encapsulates per-request configuration such as error handling and logging.
+  class AppContext
+    attr_reader :error_handler, :log_target, :mode
+
+    def initialize(error_handler:, log_target: nil, mode: :library)
+      @error_handler = error_handler
+      @log_target = log_target
+      @mode = mode
+    end
+
+    def with_error_handler(handler)
+      self.class.new(error_handler: handler, log_target: log_target, mode: mode)
+    end
+
+    def with_log_target(target)
+      self.class.new(error_handler: error_handler, log_target: target, mode: mode)
+    end
+
+    def mcp_mode? = mode == :mcp_server
+    def cli_mode? = mode == :cli
+    def library_mode? = mode == :library
+  end
+end

data/lib/simplecov_mcp/base_tool.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'json'
+require_relative 'errors'
+require_relative 'error_handler'
+
+module SimpleCovMcp
+  class BaseTool < ::MCP::Tool
+    INPUT_SCHEMA = {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Repo-relative or absolute path to the file whose coverage data you need.',
+          examples: ['lib/simple_cov_mcp/model.rb']
+        },
+        root: {
+          type: 'string',
+          description: 'Project root used to resolve relative paths ' \
+                       '(defaults to current workspace).',
+          default: '.'
+        },
+        resultset: {
+          type: 'string',
+          description: 'Path to the SimpleCov .resultset.json file (absolute or relative to root).'
+        },
+        stale: {
+          type: 'string',
+          description: 'How to handle missing/outdated coverage data.' \
+                       "'off' skips checks; 'error' raises.",
+          enum: %w[off error],
+          default: 'off'
+        },
+        error_mode: {
+          type: 'string',
+          description: "Error handling mode: 'off' (silent), 'on' (log errors), 'trace' (verbose).",
+          enum: %w[off on trace],
+          default: 'on'
+        }
+      },
+      required: ['path']
+    }
+    def self.input_schema_def = INPUT_SCHEMA
+
+    # Handle errors consistently across all MCP tools
+    # Returns an MCP::Tool::Response with appropriate error message
+    def self.handle_mcp_error(error, tool_name, error_mode: :on)
+      # Create error handler with the specified mode
+      error_handler = ErrorHandlerFactory.for_mcp_server(error_mode: error_mode.to_sym)
+
+      # Normalize to a SimpleCovMcp::Error so we can handle/log uniformly
+      normalized = error.is_a?(SimpleCovMcp::Error) \
+        ? error : error_handler.convert_standard_error(error)
+      log_mcp_error(normalized, tool_name, error_handler)
+      ::MCP::Tool::Response.new([{ type: 'text', text: "Error: #{normalized.user_friendly_message}" }])
+    end
+
+    # Respond with JSON as a resource to avoid clients mutating content types.
+    # The resource embeds the JSON string with a clear MIME type.
+    def self.respond_json(payload, name: 'data.json', pretty: false)
+      json = pretty ? JSON.pretty_generate(payload) : JSON.generate(payload)
+      ::MCP::Tool::Response.new([{ 'type' => 'text', 'text' => json }])
+    end
+
+    private
+
+    def self.log_mcp_error(error, tool_name, error_handler)
+      # Use the provided error handler for logging
+      error_handler.send(:log_error, error, tool_name)
+    end
+  end
+end

data/lib/simplecov_mcp/cli.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'cli_config'
+require_relative 'option_parser_builder'
+require_relative 'commands/command_factory'
+require_relative 'option_parsers/error_helper'
+require_relative 'option_parsers/env_options_parser'
+require_relative 'constants'
+require_relative 'presenters/project_coverage_presenter'
+
+module SimpleCovMcp
+  class CoverageCLI
+    SUBCOMMANDS = %w[list summary raw uncovered detailed version].freeze
+    HORIZONTAL_RULE = '-' * 79
+
+    # Reference shared constant to avoid duplication with ModeDetector
+    OPTIONS_EXPECTING_ARGUMENT = Constants::OPTIONS_EXPECTING_ARGUMENT
+
+    attr_reader :config
+
+    # Initialize CLI for pure CLI usage only.
+    # Always runs as CLI, no mode detection needed.
+    def initialize(error_handler: nil)
+      @config = CLIConfig.new
+      @cmd = nil
+      @cmd_args = []
+      @custom_error_handler = error_handler # Store custom handler if provided
+      @error_handler = nil # Will be created after parsing options
+    end
+
+    def run(argv)
+      context = nil
+      # Prepend environment options to command line arguments
+      full_argv = parse_env_opts + argv
+      # Pre-scan for error-mode to ensure early errors are logged with correct verbosity
+      pre_scan_error_mode(full_argv)
+      parse_options!(full_argv)
+
+      # Create error handler AFTER parsing options to respect user's --error-mode choice
+      ensure_error_handler
+
+      context = SimpleCovMcp.create_context(
+        error_handler: @error_handler,
+        log_target: config.log_file.nil? ? SimpleCovMcp.context.log_target : config.log_file,
+        mode: :cli
+      )
+
+      SimpleCovMcp.with_context(context) do
+        # If success predicate specified, run it and exit
+        if config.success_predicate
+          run_success_predicate
+          next
+        end
+
+        if @cmd
+          run_subcommand(@cmd, @cmd_args)
+        else
+          show_default_report(sort_order: config.sort_order)
+        end
+      end
+    rescue OptionParser::ParseError => e
+      # Handle any option parsing errors (invalid option/argument) without relying on
+      # @error_handler, which is not guaranteed to be initialized yet.
+      with_context_if_available(context) { handle_option_parser_error(e, argv: full_argv) }
+    rescue SimpleCovMcp::Error => e
+      with_context_if_available(context) { handle_user_facing_error(e) }
+    end
+
+    def show_default_report(sort_order: :ascending, output: $stdout)
+      model = CoverageModel.new(**config.model_options)
+      presenter = Presenters::ProjectCoveragePresenter.new(
+        model: model,
+        sort_order: sort_order,
+        check_stale: (config.stale_mode == :error),
+        tracked_globs: config.tracked_globs
+      )
+
+      if config.json
+        output.puts JSON.pretty_generate(presenter.relativized_payload)
+        return
+      end
+
+      file_summaries = presenter.relative_files
+      output.puts model.format_table(
+        file_summaries,
+        sort_order: sort_order,
+        check_stale: (config.stale_mode == :error),
+        tracked_globs: nil
+      )
+    end
+
+    private
+
+    def parse_options!(argv)
+      require 'optparse'
+      extract_subcommand!(argv)
+      parser = build_option_parser
+      parser.parse!(argv)
+      @cmd_args = argv
+    end
+
+    def extract_subcommand!(argv)
+      # Environment options (e.g., from SIMPLECOV_MCP_OPTS) may precede the subcommand.
+      # Walk the array so we can skip over any option/argument pairs before
+      # we decide what the first meaningful token is.
+      return if argv.empty?
+
+      first_unknown = nil
+      pending_option = nil
+
+      argv.each_with_index do |token, index|
+        # skip the argument that belongs to the previous option
+        if pending_option
+          pending_option = nil
+          next
+        end
+
+        if token.start_with?('-')
+          # CLI options (and --foo=value forms) start with '-'; values beginning with '-' are skipped via pending_option
+          # Remember options that expect a following argument so we can skip
+          # that value on the next iteration.
+          pending_option = expects_argument?(token) && !token.include?('=') ? token : nil
+          next
+        elsif SUBCOMMANDS.include?(token)
+          # Found the real subcommand; pluck it out so option parsing sees the
+          # remaining args in their original order.
+          @cmd = token
+          argv.delete_at(index)
+          return
+        else
+          first_unknown ||= token
+        end
+      end
+
+      if first_unknown
+        raise UsageError.new("Unknown subcommand: '#{first_unknown}'. Valid subcommands: #{SUBCOMMANDS.join(', ')}")
+      end
+    end
+
+    def expects_argument?(option)
+      OPTIONS_EXPECTING_ARGUMENT.include?(option)
+    end
+
+    def ensure_error_handler
+      @error_handler ||=
+        @custom_error_handler || ErrorHandlerFactory.for_cli(error_mode: config.error_mode)
+    end
+
+    def parse_env_opts
+      @env_parser ||= OptionParsers::EnvOptionsParser.new
+      @env_parser.parse_env_opts
+    end
+
+    def pre_scan_error_mode(argv)
+      @env_parser ||= OptionParsers::EnvOptionsParser.new
+      config.error_mode = @env_parser.pre_scan_error_mode(argv) || :on
+    end
+
+    def build_option_parser
+      builder = OptionParserBuilder.new(config)
+      builder.build_option_parser
+    end
+
+    def with_context_if_available(ctx)
+      if ctx
+        SimpleCovMcp.with_context(ctx) { yield }
+      else
+        yield
+      end
+    end
+
+    def run_subcommand(cmd, args)
+      command = Commands::CommandFactory.create(cmd, self)
+      command.execute(args)
+    rescue SimpleCovMcp::Error => e
+      handle_user_facing_error(e)
+    rescue => e
+      @error_handler.handle_error(e, context: "subcommand '#{cmd}'")
+    end
+
+    def handle_option_parser_error(error, argv: [])
+      @error_helper ||= OptionParsers::ErrorHelper.new(SUBCOMMANDS)
+      @error_helper.handle_option_parser_error(error, argv: argv)
+    end
+
+    def run_success_predicate
+      predicate = load_success_predicate(config.success_predicate)
+      model = CoverageModel.new(**config.model_options)
+
+      result = predicate.call(model)
+      exit(result ? 0 : 1)
+    rescue => e
+      warn "Success predicate error: #{e.message}"
+      warn e.backtrace.first(5).join("\n") if config.error_mode == :trace
+      exit 2 # Exit code 2 for predicate errors
+    end
+
+    def load_success_predicate(path)
+      unless File.exist?(path)
+        raise "Success predicate file not found: #{path}"
+      end
+
+      content = File.read(path)
+
+      # WARNING: The predicate code executes with full Ruby privileges.
+      # It has unrestricted access to the file system, network, and system commands.
+      # Only use predicate files from trusted sources.
+      #
+      # We evaluate in a fresh Object context to prevent accidental access to
+      # CLI internals, but this provides NO security isolation.
+      evaluation_context = Object.new
+      predicate = evaluation_context.instance_eval(content, path, 1)
+
+      unless predicate.respond_to?(:call)
+        raise 'Success predicate must be callable (lambda, proc, or object with #call method)'
+      end
+
+      predicate
+    rescue SyntaxError => e
+      raise "Syntax error in success predicate file: #{e.message}"
+    end
+
+    def handle_user_facing_error(error)
+      # Ensure error handler exists (may not be initialized if error occurs during option parsing)
+      ensure_error_handler
+      # Log the error if error_mode allows it
+      @error_handler.handle_error(error, context: 'CLI', reraise: false)
+      # Show user-friendly message
+      warn error.user_friendly_message
+      exit 1
+    end
+  end
+end

data/lib/simplecov_mcp/cli_config.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module SimpleCovMcp
+  # Configuration container for CLI options
+  # Uses Struct for simplicity and built-in functionality
+  CLIConfig = Struct.new(
+    :root,
+    :resultset,
+    :json,
+    :sort_order,
+    :source_mode,
+    :source_context,
+    :color,
+    :error_mode,
+    :stale_mode,
+    :tracked_globs,
+    :log_file,
+    :success_predicate,
+    keyword_init: true
+  ) do
+    # Set sensible defaults - ALL SYMBOLS FOR ENUMS
+    def initialize(
+      root: '.',
+      resultset: nil,
+      json: false,
+      sort_order: :ascending,
+      source_mode: nil,
+      source_context: 2,
+      color: STDOUT.tty?,
+      error_mode: :on,
+      stale_mode: :off,
+      tracked_globs: nil,
+      log_file: nil,
+      success_predicate: nil
+    )
+      super
+    end
+
+    # Convenience method for CoverageModel initialization
+    def model_options
+      {
+        root: root,
+        resultset: resultset,
+        staleness: stale_mode,
+        tracked_globs: tracked_globs
+      }
+    end
+
+    # Convenience method for SourceFormatter initialization
+    def formatter_options
+      {
+        color_enabled: color
+      }
+    end
+  end
+end

data/lib/simplecov_mcp/commands/base_command.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../formatters/source_formatter'
+require_relative '../model'
+require_relative '../errors'
+
+module SimpleCovMcp
+  module Commands
+    class BaseCommand
+      def initialize(cli_context)
+        @cli = cli_context
+        @config = cli_context.config
+        @source_formatter = Formatters::SourceFormatter.new(
+          **config.formatter_options
+        )
+      end
+
+      protected
+
+      attr_reader :cli, :config, :source_formatter
+
+      def model
+        @model ||= CoverageModel.new(**config.model_options)
+      end
+
+      def handle_with_path(args, name)
+        path = args.shift or raise UsageError.for_subcommand("#{name} <path>")
+        yield(path)
+      rescue Errno::ENOENT => e
+        raise FileNotFoundError.new("File not found: #{path}")
+      rescue Errno::EACCES => e
+        raise FilePermissionError.new("Permission denied: #{path}")
+      end
+
+      def maybe_output_json(obj, model)
+        return false unless config.json
+
+        puts JSON.pretty_generate(model.relativize(obj))
+        true
+      end
+
+      def emit_json_with_optional_source(data, model, path)
+        return false unless config.json
+
+        relativized = model.relativize(data)
+        if config.source_mode
+          payload = relativized.merge('source' => build_source_payload(model, path))
+          puts JSON.pretty_generate(payload)
+        else
+          puts JSON.pretty_generate(relativized)
+        end
+        true
+      end
+
+      def build_source_payload(model, path)
+        source_formatter.build_source_payload(model, path, mode: config.source_mode,
+          context: config.source_context)
+      end
+
+      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 print_source_for(model, path)
+        formatted = source_formatter.format_source_for(model, path, mode: config.source_mode,
+          context: config.source_context)
+        puts formatted
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/commands/command_factory.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative 'list_command'
+require_relative 'version_command'
+require_relative 'summary_command'
+require_relative 'raw_command'
+require_relative 'uncovered_command'
+require_relative 'detailed_command'
+
+module SimpleCovMcp
+  module Commands
+    class CommandFactory
+      COMMAND_MAP = {
+        'list' => ListCommand,
+        'version' => VersionCommand,
+        'summary' => SummaryCommand,
+        'raw' => RawCommand,
+        'uncovered' => UncoveredCommand,
+        'detailed' => DetailedCommand
+      }.freeze
+
+      def self.create(command_name, cli_context)
+        command_class = COMMAND_MAP[command_name]
+        unless command_class
+          raise UsageError.for_subcommand(
+            'list | summary <path> | raw <path> | uncovered <path> | detailed <path> | version'
+          )
+        end
+
+        command_class.new(cli_context)
+      end
+
+      def self.available_commands
+        COMMAND_MAP.keys
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/commands/detailed_command.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../formatters/source_formatter'
+require_relative '../presenters/coverage_detailed_presenter'
+
+module SimpleCovMcp
+  module Commands
+    class DetailedCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'detailed') do |path|
+          presenter = Presenters::CoverageDetailedPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if emit_json_with_optional_source(data, model, path)
+
+          relative_path = presenter.relative_path
+          puts "File: #{relative_path}"
+          puts source_formatter.format_detailed_rows(data['lines'])
+          print_source_for(model, path) if config.source_mode
+        end
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/commands/list_command.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+
+module SimpleCovMcp
+  module Commands
+    class ListCommand < BaseCommand
+      def execute(args)
+        cli.send(:show_default_report, sort_order: config.sort_order)
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/commands/raw_command.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../presenters/coverage_raw_presenter'
+
+module SimpleCovMcp
+  module Commands
+    class RawCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'raw') do |path|
+          presenter = Presenters::CoverageRawPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if maybe_output_json(data, model)
+
+          relative_path = presenter.relative_path
+          puts "File: #{relative_path}"
+          puts data['lines'].inspect
+        end
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/commands/summary_command.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../presenters/coverage_summary_presenter'
+
+module SimpleCovMcp
+  module Commands
+    class SummaryCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'summary') do |path|
+          presenter = Presenters::CoverageSummaryPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if emit_json_with_optional_source(data, model, path)
+
+          relative_path = presenter.relative_path
+          summary = data['summary']
+          printf "%8.2f%%  %6d/%-6d  %s\n\n", summary['pct'], summary['covered'], summary['total'],
+            relative_path
+          print_source_for(model, path) if config.source_mode
+        end
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/commands/uncovered_command.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'base_command'
+require_relative '../presenters/coverage_uncovered_presenter'
+
+module SimpleCovMcp
+  module Commands
+    class UncoveredCommand < BaseCommand
+      def execute(args)
+        handle_with_path(args, 'uncovered') do |path|
+          presenter = Presenters::CoverageUncoveredPresenter.new(model: model, path: path)
+          data = presenter.absolute_payload
+          break if emit_json_with_optional_source(data, model, path)
+
+          relative_path = presenter.relative_path
+          puts "File:            #{relative_path}"
+          puts "Uncovered lines: #{data['uncovered'].join(', ')}"
+          summary = data['summary']
+          printf "Summary:      %8.2f%%  %6d/%-6d\n\n", summary['pct'], summary['covered'],
+            summary['total']
+          print_source_for(model, path) if config.source_mode
+        end
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/commands/version_command.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'base_command'
+
+module SimpleCovMcp
+  module Commands
+    class VersionCommand < BaseCommand
+      def execute(args)
+        if config.json
+          puts JSON.pretty_generate({ version: SimpleCovMcp::VERSION })
+        else
+          puts "SimpleCovMcp version #{SimpleCovMcp::VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/constants.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SimpleCovMcp
+  # Shared constants used across multiple components to avoid duplication.
+  # This ensures consistency between CLI option parsing and mode detection.
+  module Constants
+    # CLI options that expect an argument value following them.
+    # Used by both CoverageCLI and ModeDetector to correctly parse command-line arguments.
+    OPTIONS_EXPECTING_ARGUMENT = %w[
+      -r --resultset
+      -R --root
+      -o --sort-order
+      -s --source
+      -c --source-context
+      -S --stale
+      -g --tracked-globs
+      -l --log-file
+      --error-mode
+      --success-predicate
+    ].freeze
+  end
+end