simplecov-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2a8ecf4bfeeedc4b7377baaa3fcabf0b196ad9c17f2ccd29e5532b7a6104751
+  data.tar.gz: 8b52e3920dd3734add19862838f03b967bb73d17dd769539a66160ef9950e38f
+SHA512:
+  metadata.gz: bbcec76c297750544657a18cec0366148f1cff30ebff2c9b5bbc593f2d9492fe32554d2b4859f1e89f7efd19f35d35e7345f8ecdfa05d1c32ffea86f42c68ed6
+  data.tar.gz: 2266b137c11b92fcaedc7337010c7a5b8c6814d09b4a652bc642abad2082e3f8cd20e8d33930808257176e020602249408be71c206d518adba3cc577dab7aa41

data/README.md

@@ -0,0 +1,97 @@
+# simplecov-mcp
+
+MCP server + CLI for inspecting SimpleCov coverage data.
+
+This gem provides:
+
+- An MCP (Model Context Protocol) server exposing tools to query coverage for files.
+- A human-friendly CLI that prints a sorted table of file coverage.
+
+## Installation
+
+Add to your Gemfile or install directly:
+
+```
+gem install simplecov-mcp
+```
+
+Require path is `simplecov/mcp` (also `simplecov_mcp`). Executable is `simplecov-mcp`.
+
+## Usage
+
+Environment variable:
+
+- `SIMPLECOV_RESULTSET` — optional explicit path to `.resultset.json`.
+
+Search order for resultset:
+
+1. `.resultset.json`
+2. `coverage/.resultset.json`
+3. `tmp/.resultset.json`
+
+### CLI Mode
+
+Run in a project directory with a SimpleCov resultset:
+
+```
+simplecov-mcp
+```
+
+Forces CLI mode:
+
+```
+simplecov-mcp --cli
+# or
+COVERAGE_MCP_CLI=1 simplecov-mcp
+``;
+
+Example output:
+
+```
+┌───────────────────────────┬──────────┬──────────┬────────┐
+│ File                      │        % │  Covered │  Total │
+├───────────────────────────┼──────────┼──────────┼────────┤
+│ lib/models/user.rb        │    92.31 │       12 │     13 │
+│ lib/services/auth.rb      │   100.00 │        8 │      8 │
+│ spec/user_spec.rb         │    85.71 │       12 │     14 │
+└───────────────────────────┴──────────┴──────────┴────────┘
+```
+
+Files are sorted by percentage (ascending), then by path.
+
+### MCP Server Mode
+
+When stdin has data (e.g., from an MCP client), the program runs as an MCP server over stdio.
+
+Available tools:
+
+- `coverage_raw(path, root=".")`
+- `coverage_summary(path, root=".")`
+- `uncovered_lines(path, root=".")`
+- `coverage_detailed(path, root=".")`
+- `all_files_coverage(root=".")`
+
+Example (manual):
+
+```
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_summary","arguments":{"path":"lib/foo.rb"}}}' | simplecov-mcp
+```
+
+### Notes
+
+- Library entrypoint: `require "simplecov/mcp"` or `require "simplecov_mcp"`
+- Programmatic run: `Simplecov::Mcp.run(ARGV)`
+- Logs basic diagnostics to `~/coverage_mcp.log`.
+
+## Development
+
+Standard Ruby gem structure. After cloning:
+
+```
+bundle install
+ruby -Ilib exe/simplecov-mcp --cli
+```
+
+## License
+
+MIT

data/exe/simplecov-mcp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "simplecov_mcp"
+
+Simplecov::Mcp.run(ARGV)

data/lib/simplecov/mcp/base_tool.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class BaseTool < ::MCP::Tool
+      INPUT_SCHEMA = {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Absolute or project-relative file path" },
+          root: { type: "string", description: "Project root for resolution", default: "." }
+        },
+        required: ["path"]
+      }
+      def self.input_schema_def = INPUT_SCHEMA
+    end
+  end
+end
+

data/lib/simplecov/mcp/cli.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class CoverageCLI
+      def initialize
+        @root = "."
+      end
+
+      def run(argv)
+        if force_cli?(argv)
+          show_default_report
+        else
+          run_mcp_server
+        end
+      rescue => e
+        CovUtil.log("CLI fatal error: #{e.class}: #{e.message}\n#{e.backtrace&.join("\n")}")
+        raise
+      end
+
+      private
+
+      def force_cli?(argv)
+        return true  if ENV["COVERAGE_MCP_CLI"] == "1"
+        return true  if argv.include?("--cli") || argv.include?("--report")
+        # If interactive TTY, prefer CLI; else (e.g., pipes), run MCP.
+        return STDIN.tty?
+      end
+
+      def show_default_report
+        model = CoverageModel.new(root: @root)
+        file_summaries = model.all_files(sort_order: :ascending).map do |row|
+          row.dup.tap do |h|
+            h[:file] = Pathname.new(h[:file]).relative_path_from(Pathname.new(Dir.pwd)).to_s
+          end
+        end
+
+        # Format as table with box-style borders
+        max_file_length = file_summaries.map { |f| f[:file].length }.max.to_i
+        max_file_length = [max_file_length, "File".length].max
+
+        # Calculate maximum numeric values for proper column widths
+        max_covered = file_summaries.map { |f| f[:covered].to_s.length }.max
+        max_total = file_summaries.map { |f| f[:total].to_s.length }.max
+
+        # Define column widths
+        file_width = max_file_length + 2  # Extra padding
+        pct_width = 8
+        covered_width = [max_covered, "Covered".length].max + 2
+        total_width = [max_total, "Total".length].max + 2
+
+        # Horizontal line for each column span
+        h_line = ->(col_width) { '─' * (col_width + 2) }
+
+        # Border line lambda
+        border_line = ->(left, middle, right) {
+          left   + h_line.(file_width) +
+          middle + h_line.(pct_width) +
+          middle + h_line.(covered_width) +
+          middle + h_line.(total_width) +
+          right
+        }
+
+        # Top border
+        puts border_line.call("┌", "┬", "┐")
+
+        # Header row
+        printf "│ %-#{file_width}s │ %#{pct_width}s │ %#{covered_width}s │ %#{total_width}s │\n",
+               "File", " %", "Covered", "Total"
+
+        # Header separator
+        puts border_line.call("├", "┼", "┤")
+
+        # Data rows
+        file_summaries.each do |file_data|
+          printf "│ %-#{file_width}s │ %#{pct_width - 1}.2f%% │ %#{covered_width}d │ %#{total_width}d │\n",
+                 file_data[:file],
+                 file_data[:percentage],
+                 file_data[:covered],
+                 file_data[:total]
+        end
+
+        # Bottom border
+        puts border_line.call("└", "┴", "┘")
+      end
+
+      def run_mcp_server
+        server = ::MCP::Server.new(
+          name:    "ruby_coverage_server",
+          version: Simplecov::Mcp::VERSION,
+          tools:   [CoverageRaw, CoverageSummary, UncoveredLines, CoverageDetailed, AllFilesCoverage]
+        )
+        ::MCP::Server::Transports::StdioTransport.new(server).open
+      end
+    end
+  end
+end
+

data/lib/simplecov/mcp/model.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class CoverageModel
+      def initialize(root: ".")
+        @root = File.absolute_path(root || ".")
+        @cov  = CovUtil.load_latest_coverage(@root)
+      end
+
+      # Returns { file: <abs>, lines: [hits|nil,...] }
+      def raw_for(path)
+        abs, arr = resolve(path)
+        { file: abs, lines: arr }
+      end
+
+      # Returns { file: <abs>, summary: {"covered"=>, "total"=>, "pct"=>} }
+      def summary_for(path)
+        abs, arr = resolve(path)
+        { file: abs, summary: CovUtil.summary(arr) }
+      end
+
+      # Returns { file: <abs>, uncovered: [line,...], summary: {...} }
+      def uncovered_for(path)
+        abs, arr = resolve(path)
+        { file: abs, uncovered: CovUtil.uncovered(arr), summary: CovUtil.summary(arr) }
+      end
+
+      # Returns { file: <abs>, lines: [{line:,hits:,covered:},...], summary: {...} }
+      def detailed_for(path)
+        abs, arr = resolve(path)
+        { file: abs, lines: CovUtil.detailed(arr), summary: CovUtil.summary(arr) }
+      end
+
+      # Returns [ { file:, covered:, total:, percentage: }, ... ]
+      def all_files(sort_order: :ascending)
+        rows = @cov.map do |abs_path, data|
+          next unless data["lines"].is_a?(Array)
+          s = CovUtil.summary(data["lines"])
+          { file: abs_path, covered: s["covered"], total: s["total"], percentage: s["pct"] }
+        end.compact
+
+        rows.sort! do |a, b|
+          pct_cmp = (sort_order.to_s == "descending") ? (b[:percentage] <=> a[:percentage]) : (a[:percentage] <=> b[:percentage])
+          pct_cmp == 0 ? (a[:file] <=> b[:file]) : pct_cmp
+        end
+        rows
+      end
+
+      private
+
+      def resolve(path)
+        abs = File.absolute_path(path, @root)
+        [abs, CovUtil.lookup_lines(@cov, abs)]
+      end
+    end
+  end
+end
+

data/lib/simplecov/mcp/tools/all_files_coverage.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class AllFilesCoverage < ::MCP::Tool
+      description "Return coverage percentage for all files in the project"
+      input_schema(
+        type: "object",
+        properties: {
+          root: { type: "string", description: "Project root for resolution", default: "." },
+          sort_order: { type: "string", description: "Sort order for coverage percentage: ascending or descending", default: "ascending", enum: ["ascending", "descending"] }
+        }
+      )
+      class << self
+        def call(root: ".", sort_order: "ascending", server_context:)
+          model = CoverageModel.new(root: root)
+          files = model.all_files(sort_order: sort_order)
+          ::MCP::Tool::Response.new([{ type: "json", json: { files: files } }],
+                              meta: { mimeType: "application/json" })
+        rescue => e
+          CovUtil.log("AllFilesCoverage error: #{e.class}: #{e.message}")
+          ::MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.class}: #{e.message}" }])
+        end
+      end
+    end
+  end
+end
+

data/lib/simplecov/mcp/tools/coverage_detailed.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class CoverageDetailed < BaseTool
+      description "Verbose per-line objects [{line,hits,covered}] (token-heavy)"
+      input_schema(**input_schema_def)
+      class << self
+        def call(path:, root: ".", server_context:)
+          model = CoverageModel.new(root: root)
+          data = model.detailed_for(path)
+          ::MCP::Tool::Response.new([{ type: "json", json: data }],
+                              meta: { mimeType: "application/json" })
+        rescue => e
+          CovUtil.log("CoverageDetailed error: #{e.class}: #{e.message}")
+          ::MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.class}: #{e.message}" }])
+        end
+      end
+    end
+  end
+end
+

data/lib/simplecov/mcp/tools/coverage_raw.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class CoverageRaw < BaseTool
+      description "Return the original SimpleCov 'lines' array for a file"
+      input_schema(**input_schema_def)
+      class << self
+        def call(path:, root: ".", server_context:)
+          model = CoverageModel.new(root: root)
+          data = model.raw_for(path)
+          ::MCP::Tool::Response.new([{ type: "json", json: data }],
+                              meta: { mimeType: "application/json" })
+        rescue => e
+          CovUtil.log("CoverageRaw error: #{e.class}: #{e.message}")
+          ::MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.class}: #{e.message}" }])
+        end
+      end
+    end
+  end
+end
+

data/lib/simplecov/mcp/tools/coverage_summary.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class CoverageSummary < BaseTool
+      description "Return {covered,total,pct} for a file"
+      input_schema(**input_schema_def)
+      class << self
+        def call(path:, root: ".", server_context:)
+          model = CoverageModel.new(root: root)
+          data = model.summary_for(path)
+          ::MCP::Tool::Response.new([{ type: "json", json: data }],
+                              meta: { mimeType: "application/json" })
+        rescue => e
+          CovUtil.log("CoverageSummary error: #{e.class}: #{e.message}")
+          ::MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.class}: #{e.message}" }])
+        end
+      end
+    end
+  end
+end
+

data/lib/simplecov/mcp/tools/uncovered_lines.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    class UncoveredLines < BaseTool
+      description "Return only uncovered executable line numbers plus a summary"
+      input_schema(**input_schema_def)
+      class << self
+        def call(path:, root: ".", server_context:)
+          model = CoverageModel.new(root: root)
+          data = model.uncovered_for(path)
+          ::MCP::Tool::Response.new([{ type: "json", json: data }],
+                              meta: { mimeType: "application/json" })
+        rescue => e
+          CovUtil.log("UncoveredLines error: #{e.class}: #{e.message}")
+          ::MCP::Tool::Response.new([{ type: "text", text: "Error: #{e.class}: #{e.message}" }])
+        end
+      end
+    end
+  end
+end
+

data/lib/simplecov/mcp/util.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    RESULTSET_CANDIDATES = [
+      ".resultset.json",
+      "coverage/.resultset.json",
+      "tmp/.resultset.json"
+    ].freeze
+
+    module CovUtil
+      module_function
+
+      def log(msg)
+        path = File.expand_path("~/coverage_mcp.log")
+        File.open(path, "a") { |f| f.puts "[#{Time.now.iso8601}] #{msg}" }
+      rescue StandardError
+        # ignore logging failures
+      end
+
+      def find_resultset(root)
+        if (env = ENV["SIMPLECOV_RESULTSET"]) && !env.empty?
+          path = File.absolute_path(env, root)
+          return path if File.file?(path)
+        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)
+        rs = find_resultset(root)
+        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 in .resultset.json"
+        cov.transform_keys { |k| File.absolute_path(k, root) }
+      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
+end
+

data/lib/simplecov/mcp/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Simplecov
+  module Mcp
+    VERSION = "0.1.0"
+  end
+end
+

data/lib/simplecov/mcp.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "pathname"
+require "mcp"
+require "mcp/server/transports/stdio_transport"
+require "awesome_print"
+
+require_relative "mcp/version"
+require_relative "mcp/util"
+require_relative "mcp/model"
+require_relative "mcp/base_tool"
+require_relative "mcp/tools/coverage_raw"
+require_relative "mcp/tools/coverage_summary"
+require_relative "mcp/tools/uncovered_lines"
+require_relative "mcp/tools/coverage_detailed"
+require_relative "mcp/tools/all_files_coverage"
+require_relative "mcp/cli"
+
+module Simplecov
+  module Mcp
+    def self.run(argv)
+      CoverageCLI.new.run(argv)
+    end
+  end
+end
+

data/lib/simplecov_mcp.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience single-level require path
+require "simplecov/mcp"
+

data/spec/simplecov_mcp_model_spec.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe Simplecov::Mcp::CoverageModel do
+  let(:root)  { (FIXTURES / "project1").to_s }
+  subject(:model) { described_class.new(root: root) }
+
+  describe "raw_for" do
+    it "returns absolute file and lines array" do
+      data = model.raw_for("lib/foo.rb")
+      expect(data[:file]).to eq(File.expand_path("lib/foo.rb", root))
+      expect(data[:lines]).to eq([1, 0, nil, 2])
+    end
+  end
+
+  describe "summary_for" do
+    it "computes covered/total/pct" do
+      data = model.summary_for("lib/foo.rb")
+      expect(data[:summary]["total"]).to eq(3)
+      expect(data[:summary]["covered"]).to eq(2)
+      expect(data[:summary]["pct"]).to be_within(0.01).of(66.67)
+    end
+  end
+
+  describe "uncovered_for" do
+    it "lists uncovered executable line numbers" do
+      data = model.uncovered_for("lib/foo.rb")
+      expect(data[:uncovered]).to eq([2])
+      expect(data[:summary]["total"]).to eq(3)
+    end
+  end
+
+  describe "detailed_for" do
+    it "returns per-line details for non-nil lines" do
+      data = model.detailed_for("lib/foo.rb")
+      expect(data[:lines]).to eq([
+        { line: 1, hits: 1, covered: true },
+        { line: 2, hits: 0, covered: false },
+        { line: 4, hits: 2, covered: true }
+      ])
+    end
+  end
+
+  describe "all_files" do
+    it "sorts ascending by percentage then by file path" do
+      files = model.all_files(sort_order: :ascending)
+      expect(files.first[:file]).to eq(File.expand_path("lib/bar.rb", root))
+      expect(files.first[:percentage]).to be_within(0.01).of(33.33)
+      expect(files.last[:file]).to eq(File.expand_path("lib/foo.rb", root))
+    end
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+ENV.delete("SIMPLECOV_RESULTSET")
+
+require "rspec"
+require "pathname"
+require "json"
+
+require "simplecov/mcp"
+
+FIXTURES = Pathname.new(File.expand_path("fixtures", __dir__))
+
+RSpec.configure do |config|
+  config.example_status_persistence_file_path = ".rspec_status"
+  config.disable_monkey_patching!
+  config.order = :random
+  Kernel.srand config.seed
+end
+

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: simplecov-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Keith R. Bennett
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.9.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.9.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Provides an MCP (Model Context Protocol) server and a CLI to inspect
+  SimpleCov coverage, including per-file summaries and uncovered lines.
+email:
+- keithrbennett@gmail.com
+executables:
+- simplecov-mcp
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/simplecov-mcp
+- lib/simplecov/mcp.rb
+- lib/simplecov/mcp/base_tool.rb
+- lib/simplecov/mcp/cli.rb
+- lib/simplecov/mcp/model.rb
+- lib/simplecov/mcp/tools/all_files_coverage.rb
+- lib/simplecov/mcp/tools/coverage_detailed.rb
+- lib/simplecov/mcp/tools/coverage_raw.rb
+- lib/simplecov/mcp/tools/coverage_summary.rb
+- lib/simplecov/mcp/tools/uncovered_lines.rb
+- lib/simplecov/mcp/util.rb
+- lib/simplecov/mcp/version.rb
+- lib/simplecov_mcp.rb
+- spec/simplecov_mcp_model_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/keithrbennett/simplecov-mcp
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: MCP server + CLI for SimpleCov coverage data
+test_files: []