simplecov-mcp 1.0.1 → 2.0.0

data/lib/simplecov_mcp/{cli_config.rb → app_config.rb}

@@ -1,37 +1,37 @@
 # frozen_string_literal: true
 
 module SimpleCovMcp
-  # Configuration container for CLI options
+  # Configuration container for application options (used by both CLI and MCP modes)
   # Uses Struct for simplicity and built-in functionality
-  CLIConfig = Struct.new(
+  AppConfig = Struct.new(
     :root,
     :resultset,
-    :json,
+    :format,
     :sort_order,
     :source_mode,
     :source_context,
     :color,
     :error_mode,
-    :stale_mode,
+    :staleness,
     :tracked_globs,
     :log_file,
-    :success_predicate,
+    :show_version,
     keyword_init: true
   ) do
     # Set sensible defaults - ALL SYMBOLS FOR ENUMS
     def initialize(
       root: '.',
       resultset: nil,
-      json: false,
-      sort_order: :ascending,
+      format: :table,
+      sort_order: :descending,
       source_mode: nil,
       source_context: 2,
-      color: STDOUT.tty?,
-      error_mode: :on,
-      stale_mode: :off,
+      color: $stdout.tty?,
+      error_mode: :log,
+      staleness: :off,
       tracked_globs: nil,
       log_file: nil,
-      success_predicate: nil
+      show_version: false
     )
       super
     end
@@ -41,7 +41,7 @@ module SimpleCovMcp
       {
         root: root,
         resultset: resultset,
-        staleness: stale_mode,
+        staleness: staleness,
         tracked_globs: tracked_globs
       }
     end

data/lib/simplecov_mcp/app_context.rb

@@ -19,7 +19,7 @@ module SimpleCovMcp
       self.class.new(error_handler: error_handler, log_target: target, mode: mode)
     end
 
-    def mcp_mode? = mode == :mcp_server
+    def mcp_mode? = mode == :mcp
     def cli_mode? = mode == :cli
     def library_mode? = mode == :library
   end

data/lib/simplecov_mcp/base_tool.rb

@@ -7,46 +7,75 @@ 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'
-        }
+    COMMON_PROPERTIES = {
+      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).'
+      },
+      staleness: {
+        type: 'string',
+        description: 'How to handle missing/outdated coverage data. ' \
+                     "'off' skips checks; 'error' raises.",
+        enum: [:off, :error],
+        default: :off
+      },
+      error_mode: {
+        type: 'string',
+        description: "Error handling mode: 'off' (silent), 'log' (log errors), " \
+            "'debug' (verbose with backtraces).",
+        enum: %w[off log debug],
+        default: 'log'
+      }
+    }.freeze
+
+    ERROR_MODE_PROPERTY = COMMON_PROPERTIES[:error_mode].freeze
+
+    TRACKED_GLOBS_PROPERTY = {
+      type: 'array',
+      description: 'Glob patterns for files that should exist in the coverage report' \
+                   '(helps flag new files).',
+      items: { type: 'string' }
+    }.freeze
+
+    PATH_PROPERTY = {
+      type: 'string',
+      description: 'Repo-relative or absolute path to the file whose coverage data you need.',
+      examples: ['lib/simple_cov_mcp/model.rb']
+    }.freeze
+
+    def self.coverage_schema(additional_properties: {}, required: [])
+      {
+        type: 'object',
+        additionalProperties: false,
+        properties: COMMON_PROPERTIES.merge(additional_properties),
+        required: required
+      }.freeze
+    end
+
+    FILE_INPUT_SCHEMA = coverage_schema(
+      additional_properties: { path: PATH_PROPERTY },
       required: ['path']
-    }
-    def self.input_schema_def = INPUT_SCHEMA
+    )
+    def self.input_schema_def = FILE_INPUT_SCHEMA
+
+    # Wrap tool execution with consistent error handling.
+    # Yields to the block and rescues any error, delegating to handle_mcp_error.
+    # This eliminates duplicate rescue blocks across all tools.
+    def self.with_error_handling(tool_name, error_mode:)
+      yield
+    rescue => e
+      handle_mcp_error(e, tool_name, error_mode: error_mode)
+    end
 
     # 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)
+    def self.handle_mcp_error(error, tool_name, error_mode: :log)
       # Create error handler with the specified mode
       error_handler = ErrorHandlerFactory.for_mcp_server(error_mode: error_mode.to_sym)
 
@@ -54,7 +83,7 @@ module SimpleCovMcp
       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}" }])
+      ::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.
@@ -64,11 +93,10 @@ module SimpleCovMcp
       ::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
+    private_class_method :log_mcp_error
   end
 end

data/lib/simplecov_mcp/cli.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
-require_relative 'cli_config'
+require_relative 'app_config'
 require_relative 'option_parser_builder'
 require_relative 'commands/command_factory'
 require_relative 'option_parsers/error_helper'
@@ -11,7 +11,7 @@ require_relative 'presenters/project_coverage_presenter'
 
 module SimpleCovMcp
   class CoverageCLI
-    SUBCOMMANDS = %w[list summary raw uncovered detailed version].freeze
+    SUBCOMMANDS = %w[list summary raw uncovered detailed totals validate version].freeze
     HORIZONTAL_RULE = '-' * 79
 
     # Reference shared constant to avoid duplication with ModeDetector
@@ -22,7 +22,7 @@ module SimpleCovMcp
     # Initialize CLI for pure CLI usage only.
     # Always runs as CLI, no mode detection needed.
     def initialize(error_handler: nil)
-      @config = CLIConfig.new
+      @config = AppConfig.new
       @cmd = nil
       @cmd_args = []
       @custom_error_handler = error_handler # Store custom handler if provided
@@ -31,28 +31,19 @@ module SimpleCovMcp
 
     def run(argv)
       context = nil
-      # Prepend environment options to command line arguments
-      full_argv = parse_env_opts + argv
+      # argv should already include environment options (merged by caller)
       # 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
+      pre_scan_error_mode(argv)
+      parse_options!(argv)
+      enforce_version_subcommand_if_requested
 
       context = SimpleCovMcp.create_context(
-        error_handler: @error_handler,
+        error_handler: error_handler, # construct after options to respect --error-mode
         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
@@ -62,22 +53,23 @@ module SimpleCovMcp
     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) }
+      with_context_if_available(context) { handle_option_parser_error(e, argv: 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)
+    def show_default_report(sort_order: :descending, output: $stdout)
       model = CoverageModel.new(**config.model_options)
       presenter = Presenters::ProjectCoveragePresenter.new(
         model: model,
         sort_order: sort_order,
-        check_stale: (config.stale_mode == :error),
+        check_stale: (config.staleness == :error),
         tracked_globs: config.tracked_globs
       )
 
-      if config.json
-        output.puts JSON.pretty_generate(presenter.relativized_payload)
+      if config.format != :table
+        require_relative 'formatters'
+        output.puts Formatters.format(presenter.relativized_payload, config.format)
         return
       end
 
@@ -85,149 +77,101 @@ module SimpleCovMcp
       output.puts model.format_table(
         file_summaries,
         sort_order: sort_order,
-        check_stale: (config.stale_mode == :error),
+        check_stale: (config.staleness == :error),
         tracked_globs: nil
       )
     end
 
-    private
-
-    def parse_options!(argv)
+    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
+      # order! parses global options (updating config) and removes them from argv.
+      # It stops cleanly at the first subcommand (e.g., 'list', 'summary') or unknown option.
+      # If it stops at an unknown option, it raises OptionParser::InvalidOption.
+      parser.order!(argv)
 
-      argv.each_with_index do |token, index|
-        # skip the argument that belongs to the previous option
-        if pending_option
-          pending_option = nil
-          next
-        end
+      # The first remaining argument is the subcommand
+      @cmd = argv.shift
 
-        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
+      # Verify it's a valid subcommand if present
+      if @cmd && !SUBCOMMANDS.include?(@cmd)
+        raise UsageError, "Unknown subcommand: '#{@cmd}'. Valid subcommands: #{SUBCOMMANDS.join(', ')}"
       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)
+      # Any remaining arguments belong to the subcommand
+      @cmd_args = argv
     end
 
-    def parse_env_opts
-      @env_parser ||= OptionParsers::EnvOptionsParser.new
-      @env_parser.parse_env_opts
+    private def error_handler
+      @error_handler ||= @custom_error_handler ||
+                         ErrorHandlerFactory.for_cli(error_mode: config.error_mode)
     end
 
-    def pre_scan_error_mode(argv)
-      @env_parser ||= OptionParsers::EnvOptionsParser.new
-      config.error_mode = @env_parser.pre_scan_error_mode(argv) || :on
+    private def pre_scan_error_mode(argv)
+      env_parser = OptionParsers::EnvOptionsParser.new
+      config.error_mode = env_parser.pre_scan_error_mode(argv) || :log
     end
 
-    def build_option_parser
+    private def build_option_parser
       builder = OptionParserBuilder.new(config)
       builder.build_option_parser
     end
 
-    def with_context_if_available(ctx)
+    # Converts the -v/--version flags into the version subcommand.
+    # When the user passes -v or --version, config.show_version is set to true during option parsing.
+    # This method intercepts that flag and redirects execution to the 'version' subcommand,
+    # ensuring consistent version display regardless of whether the user runs
+    # `simplecov-mcp -v`, `simplecov-mcp --version`, or `simplecov-mcp version`.
+    private def enforce_version_subcommand_if_requested
+      @cmd = 'version' if config.show_version
+    end
+
+    private def with_context_if_available(ctx, &block)
       if ctx
-        SimpleCovMcp.with_context(ctx) { yield }
+        SimpleCovMcp.with_context(ctx, &block)
       else
-        yield
+        block.call
       end
     end
 
-    def run_subcommand(cmd, args)
+    private def run_subcommand(cmd, args)
+      # Check if user mistakenly placed global options after the subcommand
+      check_for_misplaced_global_options(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}'")
+      error_handler.handle_error(e, context: "subcommand '#{cmd}'")
     end
 
-    def handle_option_parser_error(error, argv: [])
+    private 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
+    private def check_for_misplaced_global_options(cmd, args)
+      # Global options that users commonly place after subcommands by mistake
+      global_options = %w[-r --resultset -R --root -f --format -o --sort-order -s --source
+                          -c --context-lines -S --staleness -g --tracked-globs
+                          -l --log-file --error-mode --color --no-color]
 
-      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
+      misplaced = args.select { |arg| global_options.include?(arg) }
+      return if misplaced.empty?
 
-      predicate
-    rescue SyntaxError => e
-      raise "Syntax error in success predicate file: #{e.message}"
+      option_list = misplaced.join(', ')
+      raise UsageError, "Global option(s) must come BEFORE the subcommand.\n" \
+        "You used: #{cmd} #{option_list}\n" \
+        "Correct: #{option_list} #{cmd}\n\n" \
+        "Example: simplecov-mcp --format json #{cmd}"
     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
+    private def handle_user_facing_error(error)
+      error_handler.handle_error(error, context: 'CLI', reraise: false)
       warn error.user_friendly_message
+      warn error.backtrace.first(5).join("\n") if config.error_mode == :debug && error.backtrace
       exit 1
     end
   end

data/lib/simplecov_mcp/commands/base_command.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require_relative '../formatters'
 require_relative '../formatters/source_formatter'
 require_relative '../model'
 require_relative '../errors'
@@ -16,59 +17,47 @@ module SimpleCovMcp
         )
       end
 
-      protected
-
       attr_reader :cli, :config, :source_formatter
 
-      def model
+      protected def model
         @model ||= CoverageModel.new(**config.model_options)
       end
 
-      def handle_with_path(args, name)
+      protected 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}")
+      rescue Errno::ENOENT
+        raise FileNotFoundError, "File not found: #{path}"
+      rescue Errno::EACCES
+        raise FilePermissionError, "Permission denied: #{path}"
       end
 
-      def maybe_output_json(obj, model)
-        return false unless config.json
+      protected def maybe_output_structured_format?(obj, model)
+        return false if config.format == :table
 
-        puts JSON.pretty_generate(model.relativize(obj))
+        puts SimpleCovMcp::Formatters.format(model.relativize(obj), config.format)
         true
       end
 
-      def emit_json_with_optional_source(data, model, path)
-        return false unless config.json
+      protected def emit_structured_format_with_optional_source?(data, model, path)
+        return false if config.format == :table
 
         relativized = model.relativize(data)
         if config.source_mode
           payload = relativized.merge('source' => build_source_payload(model, path))
-          puts JSON.pretty_generate(payload)
+          puts SimpleCovMcp::Formatters.format(payload, config.format)
         else
-          puts JSON.pretty_generate(relativized)
+          puts SimpleCovMcp::Formatters.format(relativized, config.format)
         end
         true
       end
 
-      def build_source_payload(model, path)
+      protected 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)
+      protected def print_source_for(model, path)
         formatted = source_formatter.format_source_for(model, path, mode: config.source_mode,
           context: config.source_context)
         puts formatted

data/lib/simplecov_mcp/commands/command_factory.rb

@@ -7,6 +7,8 @@ require_relative 'summary_command'
 require_relative 'raw_command'
 require_relative 'uncovered_command'
 require_relative 'detailed_command'
+require_relative 'totals_command'
+require_relative 'validate_command'
 
 module SimpleCovMcp
   module Commands
@@ -17,14 +19,18 @@ module SimpleCovMcp
         'summary' => SummaryCommand,
         'raw' => RawCommand,
         'uncovered' => UncoveredCommand,
-        'detailed' => DetailedCommand
+        'detailed' => DetailedCommand,
+        'totals' => TotalsCommand,
+        'total' => TotalsCommand, # Alias for backward compatibility
+        'validate' => ValidateCommand
       }.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'
+            'list | summary <path> | raw <path> | uncovered <path> | detailed <path> ' \
+              '| totals | validate <file> | validate -i <code> | version'
           )
         end
 

data/lib/simplecov_mcp/commands/detailed_command.rb

@@ -3,6 +3,7 @@
 require_relative 'base_command'
 require_relative '../formatters/source_formatter'
 require_relative '../presenters/coverage_detailed_presenter'
+require_relative '../table_formatter'
 
 module SimpleCovMcp
   module Commands
@@ -11,11 +12,24 @@ module SimpleCovMcp
         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)
+          break if emit_structured_format_with_optional_source?(data, model, path)
 
           relative_path = presenter.relative_path
           puts "File: #{relative_path}"
-          puts source_formatter.format_detailed_rows(data['lines'])
+          puts
+
+          # Table format with box-drawing
+          headers = ['Line', 'Hits', 'Covered']
+          rows = data['lines'].map do |r|
+            [r['line'].to_s, r['hits'].to_s, r['covered'] ? 'yes' : 'no']
+          end
+
+          puts TableFormatter.format(
+            headers: headers,
+            rows: rows,
+            alignments: [:right, :right, :center]
+          )
+
           print_source_for(model, path) if config.source_mode
         end
       end

data/lib/simplecov_mcp/commands/list_command.rb

@@ -5,7 +5,7 @@ require_relative 'base_command'
 module SimpleCovMcp
   module Commands
     class ListCommand < BaseCommand
-      def execute(args)
+      def execute(_args)
         cli.send(:show_default_report, sort_order: config.sort_order)
       end
     end