simplecov-mcp 0.1.0 → 0.2.0

data/lib/simple_cov_mcp/tools/help_tool.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module SimpleCovMcp
+  module Tools
+    class HelpTool < BaseTool
+      description <<~DESC
+        Use this when you are unsure which simplecov-mcp tool fits the user’s coverage request.
+        Do not use this once you know the correct tool; call that tool directly.
+        Inputs: optional query string to filter the list of tools.
+        Output: JSON {"tools": [...]} with per-tool "use_when", "avoid_when", "inputs", and "example" guidance.
+        Example: "Which tool shows uncovered lines?".
+      DESC
+
+      input_schema(
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Optional keywords to filter the help entries (e.g., "uncovered", "summary").'
+          }
+        }
+      )
+
+      TOOL_GUIDE = [
+        {
+          tool: CoverageSummaryTool,
+          label: 'Single-file coverage summary',
+          use_when: 'User wants covered/total line counts or percentage for one file.',
+          avoid_when: 'User needs repo-wide stats or specific uncovered lines.',
+          inputs: ['path (required)', 'root/resultset/stale (optional)'],
+          example: 'What is the coverage for lib/simple_cov_mcp/model.rb?'
+        },
+        {
+          tool: UncoveredLinesTool,
+          label: 'Uncovered line numbers',
+          use_when: 'User asks which lines in a file still lack tests.',
+          avoid_when: 'User only wants overall percentages or detailed per-line hit data.',
+          inputs: ['path (required)', 'root/resultset/stale (optional)'],
+          example: 'List uncovered lines for lib/simple_cov_mcp/tools/coverage_summary_tool.rb.'
+        },
+        {
+          tool: CoverageDetailedTool,
+          label: 'Per-line coverage details',
+          use_when: 'User needs per-line hit counts for a file.',
+          avoid_when: 'User only wants totals or uncovered line numbers.',
+          inputs: ['path (required)', 'root/resultset/stale (optional)'],
+          example: 'Show detailed coverage for lib/simple_cov_mcp/util.rb.'
+        },
+        {
+          tool: CoverageRawTool,
+          label: 'Raw SimpleCov lines array',
+          use_when: 'User needs the raw SimpleCov `lines` array for a file.',
+          avoid_when: 'User expects human-friendly summaries or explanations.',
+          inputs: ['path (required)', 'root/resultset/stale (optional)'],
+          example: 'Fetch the raw coverage array for spec/support/helpers.rb.'
+        },
+        {
+          tool: AllFilesCoverageTool,
+          label: 'Repo-wide file coverage',
+          use_when: 'User wants coverage percentages for every tracked file.',
+          avoid_when: 'User asks about a single file.',
+          inputs: ['root/resultset (optional)', 'sort_order', 'stale', 'tracked_globs'],
+          example: 'List files with the lowest coverage.'
+        },
+        {
+          tool: CoverageTableTool,
+          label: 'Formatted coverage table',
+          use_when: 'User wants the plain-text table produced by the CLI.',
+          avoid_when: 'User needs JSON data for automation.',
+          inputs: ['root/resultset (optional)', 'sort_order', 'stale'],
+          example: 'Show me the coverage table sorted descending.'
+        },
+        {
+          tool: VersionTool,
+          label: 'simplecov-mcp version',
+          use_when: 'User needs to confirm the running gem version.',
+          avoid_when: 'User is asking for coverage information.',
+          inputs: ['(no arguments)'],
+          example: 'What version of simplecov-mcp is installed?'
+        }
+      ].freeze
+
+      class << self
+        def call(query: nil, server_context:, **_unused)
+          entries = TOOL_GUIDE.map { |guide| format_entry(guide) }
+          entries = filter_entries(entries, query) if query && !query.strip.empty?
+
+          ::MCP::Tool::Response.new([{ type: 'text', text: JSON.pretty_generate({ query: query, tools: entries }) }])
+        rescue => e
+          handle_mcp_error(e, 'HelpTool')
+        end
+
+        private
+
+        def format_entry(guide)
+          {
+            'tool' => guide[:tool].tool_name,
+            'label' => guide[:label],
+            'use_when' => guide[:use_when],
+            'avoid_when' => guide[:avoid_when],
+            'inputs' => guide[:inputs],
+            'example' => guide[:example]
+          }
+        end
+
+        def filter_entries(entries, query)
+          tokens = query.downcase.scan(/\w+/)
+          return entries if tokens.empty?
+
+          entries.select do |entry|
+            tokens.all? do |token|
+              entry.any? { |_, value| value_matches?(value, token) }
+            end
+          end
+        end
+
+        def value_matches?(value, token)
+          case value
+          when String
+            value.downcase.include?(token)
+          when Array
+            value.any? { |element| element.downcase.include?(token) }
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simple_cov_mcp/tools/uncovered_lines_tool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+require_relative '../model'
+
+module SimpleCovMcp
+  module Tools
+    class UncoveredLinesTool < BaseTool
+      description <<~DESC
+        Use this when the user wants to know which lines in a file still lack coverage.
+        Do not use this for overall percentages; coverage.summary is faster when counts are enough.
+        Inputs: file path (required) plus optional root/resultset/stale mode inherited from BaseTool.
+        Output: JSON object with keys "file", "uncovered" (array of integers), and "summary" {"covered","total","pct"}.
+        Example: "List uncovered lines for lib/simple_cov_mcp/tools/coverage_summary_tool.rb".
+      DESC
+      input_schema(**input_schema_def)
+      class << self
+        def call(path:, root: '.', resultset: nil, stale: 'off', server_context:)
+          mode = stale
+          model = CoverageModel.new(root: root, resultset: resultset, staleness: mode)
+          data = model.uncovered_for(path)
+          ::MCP::Tool::Response.new([{ type: 'text', text: JSON.pretty_generate(data) }])
+        rescue => e
+          handle_mcp_error(e, 'UncoveredLinesTool')
+        end
+      end
+    end
+  end
+end

data/lib/simple_cov_mcp/tools/version_tool.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module SimpleCovMcp
+  module Tools
+    class VersionTool < BaseTool
+      description <<~DESC
+        Use this when the user or client needs to confirm which version of simplecov-mcp is running.
+        This tool takes no arguments and only returns the version string; avoid it for coverage data.
+        Output: plain text line "SimpleCovMcp version: x.y.z".
+        Example: "What version of simplecov-mcp is installed?".
+      DESC
+      input_schema(
+        type: 'object',
+        additionalProperties: false,
+        properties: {}
+      )
+
+      class << self
+        def call(server_context: nil, **_args)
+          ::MCP::Tool::Response.new([
+            { type: 'text', text: "SimpleCovMcp version: #{SimpleCovMcp::VERSION}" }
+          ])
+        rescue => error
+          handle_mcp_error(error, 'version_tool')
+        end
+      end
+    end
+  end
+end

data/lib/simple_cov_mcp/util.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module SimpleCovMcp
+    RESULTSET_CANDIDATES = [
+      '.resultset.json',
+      'coverage/.resultset.json',
+      'tmp/.resultset.json'
+    ].freeze
+
+    module CovUtil
+      module_function
+
+      
+      def log(msg)
+        path = File.expand_path('~/simplecov_mcp.log')
+        File.open(path, 'a') { |f| f.puts "[#{Time.now.iso8601}] #{msg}" }
+      rescue StandardError
+        # ignore logging failures
+      end
+
+      def find_resultset(root, resultset: nil)
+        if resultset && !resultset.to_s.empty?
+          path = File.absolute_path(resultset, root)
+          if (resolved = resolve_resultset_candidate(path, strict: true))
+            return resolved
+          end
+        end
+
+        if (env = ENV['SIMPLECOV_RESULTSET']) && !env.empty?
+          path = File.absolute_path(env, root)
+          if (resolved = resolve_resultset_candidate(path, strict: false))
+            return resolved
+          end
+        end
+        RESULTSET_CANDIDATES
+          .map { |p| File.absolute_path(p, root) }
+          .find { |p| File.file?(p) } or
+          raise "Could not find .resultset.json under #{root.inspect}; run tests or set SIMPLECOV_RESULTSET"
+      end
+
+      # returns { abs_path => {'lines' => [hits|nil,...]} }
+      def load_latest_coverage(root, resultset: nil)
+        rs = find_resultset(root, resultset: resultset)
+        raw = JSON.parse(File.read(rs))
+        _suite, data = raw.max_by { |_k, v| (v['timestamp'] || v['created_at'] || 0).to_i }
+        cov = data['coverage'] or raise "No 'coverage' key found in resultset file: #{rs}"
+        cov.transform_keys { |k| File.absolute_path(k, root) }
+      end
+
+      # Returns the timestamp (Integer seconds) for the latest coverage entry
+      # in the resultset. Used for staleness checks against source mtimes.
+      def latest_timestamp(root, resultset: nil)
+        rs = find_resultset(root, resultset: resultset)
+        raw = JSON.parse(File.read(rs))
+        _suite, data = raw.max_by { |_k, v| (v['timestamp'] || v['created_at'] || 0).to_i }
+        (data['timestamp'] || data['created_at'] || 0).to_i
+      end
+
+      def resolve_resultset_candidate(path, strict:)
+        return path if File.file?(path)
+        if File.directory?(path)
+          candidate = File.join(path, '.resultset.json')
+          return candidate if File.file?(candidate)
+          raise "No .resultset.json found in directory: #{path}" if strict
+          return nil
+        end
+        raise "Specified resultset not found: #{path}" if strict
+        nil
+      end
+
+      def lookup_lines(cov, file_abs)
+        if (h = cov[file_abs]) && h['lines'].is_a?(Array)
+          return h['lines']
+        end
+
+        # try without current working directory prefix
+        cwd = Dir.pwd
+        without = file_abs.sub(/\A#{Regexp.escape(cwd)}\//, '')
+        if (h = cov[without]) && h['lines'].is_a?(Array)
+          return h['lines']
+        end
+
+        # fallback: basename match
+        base = File.basename(file_abs)
+        kv = cov.find { |k, v| File.basename(k) == base && v['lines'].is_a?(Array) }
+        kv and return kv[1]['lines']
+
+        raise "No coverage entry found for #{file_abs}"
+      end
+
+      def summary(arr)
+        total = 0
+        covered = 0
+        arr.each do |hits|
+          next if hits.nil?
+          total += 1
+          covered += 1 if hits.to_i > 0
+        end
+        pct = total.zero? ? 100.0 : ((covered.to_f * 100.0 / total) * 100).round / 100.0
+        { 'covered' => covered, 'total' => total, 'pct' => pct }
+      end
+
+      def uncovered(arr)
+        out = []
+        arr.each_with_index do |hits, i|
+          next if hits.nil?
+          out << (i + 1) if hits.to_i.zero?
+        end
+        out
+      end
+
+      def detailed(arr)
+        rows = []
+        arr.each_with_index do |hits, i|
+          next if hits.nil?
+          h = hits.to_i
+          rows << { 'line' => i + 1, 'hits' => h, 'covered' => h.positive? }
+        end
+        rows
+      end
+    end
+end

data/lib/simple_cov_mcp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SimpleCovMcp
+  VERSION = '0.2.0'
+end

data/lib/simple_cov_mcp.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'pathname'
+require 'mcp'
+require 'mcp/server/transports/stdio_transport'
+require 'awesome_print'
+
+require_relative 'simple_cov_mcp/version'
+require_relative 'simple_cov_mcp/util'
+require_relative 'simple_cov_mcp/errors'
+require_relative 'simple_cov_mcp/error_handler'
+require_relative 'simple_cov_mcp/error_handler_factory'
+require_relative 'simple_cov_mcp/model'
+require_relative 'simple_cov_mcp/base_tool'
+require_relative 'simple_cov_mcp/tools/coverage_raw_tool'
+require_relative 'simple_cov_mcp/tools/coverage_summary_tool'
+require_relative 'simple_cov_mcp/tools/uncovered_lines_tool'
+require_relative 'simple_cov_mcp/tools/coverage_detailed_tool'
+require_relative 'simple_cov_mcp/tools/all_files_coverage_tool'
+require_relative 'simple_cov_mcp/tools/coverage_table_tool'
+require_relative 'simple_cov_mcp/tools/version_tool'
+require_relative 'simple_cov_mcp/tools/help_tool'
+require_relative 'simple_cov_mcp/mcp_server'
+require_relative 'simple_cov_mcp/cli'
+
+module SimpleCovMcp
+    def self.run(argv)
+      # Determine whether to run CLI or MCP server based on arguments and environment
+      if should_run_cli?(argv)
+        CoverageCLI.new(error_handler: ErrorHandlerFactory.for_cli).run(argv)
+      else
+        MCPServer.new.run
+      end
+    end
+
+    # For library usage, allow configuration of error handling.
+    # This method is intended for applications that want to embed simplecov-mcp
+    # functionality without the CLI behavior of showing friendly error messages
+    # and exiting. Instead, it raises custom exceptions that can be caught.
+    #
+    # Usage:
+    #   # Basic usage - raises custom exceptions on errors
+    #   SimpleCov::Mcp.run_as_library(['summary', 'lib/foo.rb'])
+    #
+    #   # With custom error handler (e.g., disable logging)
+    #   handler = SimpleCov::Mcp::ErrorHandler.new(log_errors: false)
+    #   SimpleCov::Mcp.run_as_library(['summary', 'lib/foo.rb'], error_handler: handler)
+    #
+    #   # Exception handling
+    #   begin
+    #     SimpleCov::Mcp.run_as_library(['summary', 'missing.rb'])
+    #   rescue SimpleCov::Mcp::FileError => e
+    #     puts "File not found: #{e.user_friendly_message}"
+    #   rescue SimpleCov::Mcp::CoverageDataError => e
+    #     puts "Coverage issue: #{e.user_friendly_message}"
+    #   end
+    def self.run_as_library(argv, error_handler: nil)
+      # Set global error handler for library usage (affects shared components like MCP tools)
+      SimpleCovMcp.error_handler = error_handler || ErrorHandlerFactory.for_library
+
+      model = CoverageModel.new
+      execute_library_command(model, argv)
+    rescue SimpleCovMcp::Error => e
+      raise e  # Re-raise custom errors for library users to catch
+    rescue => e
+      SimpleCovMcp.error_handler.handle_error(e, context: 'library execution')
+      raise e  # Re-raise for library users to handle
+    end
+
+    private
+
+    def self.execute_library_command(model, argv)
+      return model.all_files if argv.empty?
+
+      unless argv.length >= 2
+        raise UsageError.new("Invalid arguments. Use: [] for all files, or [command, path] for specific file")
+      end
+
+      command, path = argv[0], argv[1]
+      case command
+      when 'summary'   then model.summary_for(path)
+      when 'raw'       then model.raw_for(path)
+      when 'uncovered' then model.uncovered_for(path)
+      when 'detailed'  then model.detailed_for(path)
+      else
+        raise UsageError.new("Unknown command: #{command}. Use: summary, raw, uncovered, or detailed")
+      end
+    end
+
+    def self.should_run_cli?(argv)
+      # Force CLI mode if environment variable is set
+      return true if ENV['SIMPLECOV_MCP_CLI'] == '1'
+
+      # If a subcommand is provided, run CLI
+      return true if CoverageCLI::SUBCOMMANDS.include?(argv[0])
+
+      # If interactive TTY, prefer CLI; else (e.g., pipes), run MCP server
+      STDIN.tty?
+    end
+end

data/lib/simplecov_mcp.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
 
-# Convenience single-level require path
-require "simplecov/mcp"
-
+# Convenience single-level require path (backcompat)
+require 'simple_cov_mcp'

data/spec/all_files_coverage_tool_spec.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'simple_cov_mcp/tools/all_files_coverage_tool'
+
+RSpec.describe SimpleCovMcp::Tools::AllFilesCoverageTool do
+  let(:root) { (FIXTURES / 'project1').to_s }
+  let(:server_context) { instance_double('ServerContext').as_null_object }
+
+  before do
+    # Stub a response object that accepts a meta keyword, like the real one
+    stub_const('MCP::Tool::Response', Class.new do
+      attr_reader :payload, :meta
+      def initialize(payload, meta: nil)
+        @payload = payload
+        @meta = meta
+      end
+    end)
+  end
+
+  it 'returns files with counts (total/ok/stale) as JSON' do
+    model = instance_double(SimpleCovMcp::CoverageModel)
+    allow(SimpleCovMcp::CoverageModel).to receive(:new).and_return(model)
+    allow(model).to receive(:all_files).and_return([
+      { 'file' => "#{root}/lib/foo.rb", 'percentage' => 100.0, 'covered' => 10, 'total' => 10, 'stale' => false },
+      { 'file' => "#{root}/lib/bar.rb", 'percentage' => 50.0,  'covered' => 5,  'total' => 10, 'stale' => true }
+    ])
+
+    response = described_class.call(root: root, server_context: server_context)
+    entry = response.payload.first
+    json = entry[:json] || entry['json']
+
+    expect(json).to have_key(:files).or have_key('files')
+    files = json[:files] || json['files']
+    counts = json[:counts] || json['counts']
+
+    expect(files.length).to eq(2)
+    expect(counts).to include('total' => 2).or include(total: 2)
+    # ok + stale equals total
+    ok = counts[:ok] || counts['ok']
+    stale = counts[:stale] || counts['stale']
+    total = counts[:total] || counts['total']
+    expect(ok + stale).to eq(total)
+    expect(stale).to eq(1)
+  end
+end

data/spec/base_tool_spec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe SimpleCovMcp::BaseTool do
+  let(:handler) { SimpleCovMcp::ErrorHandler.new(log_errors: true, show_stack_traces: false, logger: test_logger) }
+  let(:test_logger) do
+    Class.new do
+      attr_reader :messages
+      def initialize; @messages = []; end
+      def error(msg); @messages << msg; end
+    end.new
+  end
+
+  before do
+    @orig_handler = begin
+      SimpleCovMcp.error_handler
+    rescue StandardError
+      nil
+    end
+    SimpleCovMcp.error_handler = handler
+    # Stub MCP::Tool::Response once for all examples; capture the payload
+    fake_resp = Class.new do
+      attr_reader :payload
+      def initialize(payload) = @payload = payload
+    end
+    stub_const('MCP::Tool::Response', fake_resp)
+  end
+
+  after do
+    SimpleCovMcp.error_handler = @orig_handler if @orig_handler
+  end
+
+  shared_examples 'friendly response and logged' do
+    it 'returns friendly text and logs' do
+      resp = described_class.handle_mcp_error(error, tool)
+      expect(resp).to be_a(MCP::Tool::Response)
+      expect(resp.payload.first[:text]).to match(expected_pattern)
+      expect(test_logger.messages.join).to include(log_fragment)
+    end
+  end
+
+  context 'with SimpleCovMcp::Error' do
+    let(:error) { SimpleCovMcp::UsageError.new('invalid args') }
+    let(:tool) { 'coverage_summary' }
+    let(:expected_pattern) { /Error: invalid args/ }
+    let(:log_fragment) { 'invalid args' }
+    include_examples 'friendly response and logged'
+  end
+
+  context 'with standard error' do
+    let(:error) { Errno::ENOENT.new('No such file or directory @ rb_sysopen - missing.rb') }
+    let(:tool) { 'coverage_raw' }
+    let(:expected_pattern) { /Error: .*File not found: missing.rb/ }
+    let(:log_fragment) { 'File not found' }
+    include_examples 'friendly response and logged'
+  end
+end

data/spec/cli_error_spec.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe SimpleCovMcp::CoverageCLI do
+  let(:root) { (FIXTURES / 'project1').to_s }
+
+  def run_cli_with_status(*argv)
+    cli = described_class.new
+    status = nil
+    out_str = err_str = nil
+    silence_output do |out, err|
+      begin
+        cli.run(argv.flatten)
+        status = 0
+      rescue SystemExit => e
+        status = e.status
+      end
+      out_str = out.string
+      err_str = err.string
+    end
+    [out_str, err_str, status]
+  end
+
+  it 'shows help and exits 0' do
+    out, err, status = run_cli_with_status('--help')
+    expect(status).to eq(0)
+    expect(out).to include('Usage: simplecov-mcp')
+    expect(err).to eq("")
+  end
+
+  shared_examples 'maps error to exit 1 with message' do
+    before do
+      # Build a fake model that raises the specified error from the specified method
+      fake_model = Class.new do
+        def initialize(*) end
+      end
+      error_to_raise = raised_error
+      fake_model.define_method(model_method) { |*| raise error_to_raise }
+      stub_const('SimpleCovMcp::CoverageModel', fake_model)
+    end
+
+    it 'exits with status 1 and friendly message' do
+      _out, err, status = run_cli_with_status(*invoke_args)
+      expect(status).to eq(1)
+      expect(err).to include(expected_message)
+    end
+  end
+
+  context 'ENOENT mapping' do
+    let(:model_method) { :summary_for }
+    let(:raised_error) { Errno::ENOENT.new('No such file or directory @ rb_sysopen - missing.rb') }
+    let(:invoke_args) { ['summary', 'lib/missing.rb', '--root', root, '--resultset', 'coverage'] }
+    let(:expected_message) { 'File error: File not found: lib/missing.rb' }
+    include_examples 'maps error to exit 1 with message'
+  end
+
+  context 'EACCES mapping' do
+    let(:model_method) { :raw_for }
+    let(:raised_error) { Errno::EACCES.new('Permission denied @ rb_sysopen - secret.rb') }
+    let(:invoke_args) { ['raw', 'lib/secret.rb', '--root', root, '--resultset', 'coverage'] }
+    let(:expected_message) { 'Permission denied: lib/secret.rb' }
+    include_examples 'maps error to exit 1 with message'
+  end
+
+  it 'emits detailed stale coverage info and exits 1' do
+    begin
+      allow(SimpleCovMcp::CovUtil).to receive(:latest_timestamp).and_return(0)
+      _out, err, status = run_cli_with_status('summary', 'lib/foo.rb', '--root', root, '--resultset', 'coverage', '--stale', 'error')
+      expect(status).to eq(1)
+      expect(err).to include('Coverage data stale:')
+      expect(err).to match(/File\s+- time:/)
+      expect(err).to match('Coverage\s+- time:')
+      expect(err).to match(/Delta\s+- file is [+-]?\d+s newer than coverage/)
+      expect(err).to match('Resultset\s+-')
+    ensure
+    end
+  end
+
+  it 'honors --no-strict-staleness to disable checks' do
+    begin
+      allow(SimpleCovMcp::CovUtil).to receive(:latest_timestamp).and_return(0)
+      _out, err, status = run_cli_with_status('summary', 'lib/foo.rb', '--root', root, '--resultset', 'coverage', '--stale', 'off')
+      expect(status).to eq(0)
+      expect(err).to eq("")
+    ensure
+    end
+  end
+
+  # Note on text-mode source rendering tests:
+  # - "Text-mode source" refers to the plain-text source view (no ANSI colors)
+  #   when passing --source or --source=uncovered (checkmarks/dots, line nums).
+  # - Direct tests are omitted here because behavior depends on how paths are
+  #   resolved (relative vs absolute) in combination with --root/--resultset
+  #   and whether the source file is readable. In uncovered mode, we observed
+  #   a crash ("can't convert nil into Integer") when coverage arrays include
+  #   nils or don’t line up with file lines. JSON paths avoid this formatting
+  #   nuance and are already covered elsewhere.
+  # - Once the uncovered+source crash is guarded (treat out-of-range/nil hits
+  #   defensively and only format integers where expected), we can add a
+  #   regression: run `uncovered` with --source=uncovered against the fixtures
+  #   and assert exit status 0 and rendered source.
+end