simplecov-mcp 1.0.1 → 2.0.0

data/lib/simplecov_mcp/tools/coverage_summary_tool.rb

@@ -10,18 +10,23 @@ module SimpleCovMcp
       description <<~DESC
         Use this when the user asks for the covered/total line counts and percentage for a specific file.
         Do not use this for multi-file reports; coverage.all_files or coverage.table handle those.
-        Inputs: file path (required) plus optional root/resultset/stale mode inherited from BaseTool.
-        Output: JSON object {"file": String, "summary": {"covered": Integer, "total": Integer, "pct": Float}, "stale": String|False}.
+        Inputs: file path (required) plus optional root/resultset/staleness mode inherited from BaseTool.
+        Output: JSON object {"file": String, "summary": {"covered": Integer, "total": Integer, "percentage": Float}, "stale": String|False}.
         Examples: "What is the coverage for lib/simple_cov_mcp/tools/all_files_coverage_tool.rb?".
       DESC
       input_schema(**input_schema_def)
       class << self
-        def call(path:, root: '.', resultset: nil, stale: 'off', error_mode: 'on', server_context:)
-          model = CoverageModel.new(root: root, resultset: resultset, staleness: stale)
-          presenter = Presenters::CoverageSummaryPresenter.new(model: model, path: path)
-          respond_json(presenter.relativized_payload, name: 'coverage_summary.json', pretty: true)
-        rescue => e
-          handle_mcp_error(e, 'CoverageSummaryTool', error_mode: error_mode)
+        def call(path:, root: '.', resultset: nil, staleness: :off, error_mode: 'log',
+          server_context:)
+          with_error_handling('CoverageSummaryTool', error_mode: error_mode) do
+            model = CoverageModel.new(
+              root: root,
+              resultset: resultset,
+              staleness: staleness.to_sym
+            )
+            presenter = Presenters::CoverageSummaryPresenter.new(model: model, path: path)
+            respond_json(presenter.relativized_payload, name: 'coverage_summary.json', pretty: true)
+          end
         end
       end
     end

data/lib/simplecov_mcp/tools/coverage_table_tool.rb

@@ -14,75 +14,35 @@ module SimpleCovMcp
         Output: text block containing the formatted coverage table with headers and percentages.
         Example: "Show me the CLI coverage table sorted descending".
       DESC
-      input_schema(
-        type: 'object',
-        additionalProperties: false,
-        properties: {
-          root: {
-            type: 'string',
-            description: 'Project root used to resolve relative inputs.',
-            default: '.'
-          },
-          resultset: {
-            type: 'string',
-            description: 'Path to the SimpleCov .resultset.json file.'
-          },
+      input_schema(**coverage_schema(
+        additional_properties: {
           sort_order: {
             type: 'string',
             description: 'Sort order for the printed coverage table (ascending or descending).',
             default: 'ascending',
             enum: ['ascending', 'descending']
           },
-          stale: {
-            type: 'string',
-            description: 'How to handle missing/outdated coverage data. ' \
-                         "'off' skips checks; 'error' raises.",
-            enum: ['off', 'error'],
-            default: 'off'
-          },
-          tracked_globs: {
-            type: 'array',
-            description: 'Glob patterns for files that should exist in the coverage report ' \
-                         '(helps flag new files).',
-            items: { type: 'string' }
-          },
-          error_mode: {
-            type: 'string',
-            description:
-              "Error handling mode: 'off' (silent), 'on' (log errors), 'trace' (verbose).",
-            enum: ['off', 'on', 'trace'],
-            default: 'on'
-          }
+          tracked_globs: TRACKED_GLOBS_PROPERTY
         }
-      )
-
+      ))
       class << self
-        def call(root: '.', resultset: nil, sort_order: 'ascending', stale: 'off',
-          tracked_globs: nil, error_mode: 'on', server_context:)
-          # Capture the output of the CLI's table report while honoring CLI options
-          # Convert string inputs from MCP to symbols for internal use
-          sort_order_sym = sort_order.to_sym
-          stale_sym = stale.to_sym
-          check_stale = (stale_sym == :error)
+        def call(root: '.', resultset: nil, sort_order: 'ascending', staleness: :off,
+          tracked_globs: nil, error_mode: 'log', server_context:)
+          with_error_handling('CoverageTableTool', error_mode: error_mode) do
+            # Convert string inputs from MCP to symbols for internal use
+            sort_order_sym = sort_order.to_sym
+            staleness_sym = staleness.to_sym
 
-          model = CoverageModel.new(root: root, resultset: resultset, staleness: stale_sym,
-            tracked_globs: tracked_globs)
-          presenter = Presenters::ProjectCoveragePresenter.new(
-            model: model,
-            sort_order: sort_order_sym,
-            check_stale: check_stale,
-            tracked_globs: tracked_globs
-          )
-          relativized = presenter.relative_files
-          table = model.format_table(
-            relativized,
-            sort_order: sort_order_sym,
-            check_stale: check_stale,
-            tracked_globs: nil # rows already filtered via all_files
-          )
-          ::MCP::Tool::Response.new([{ type: 'text', text: table }])
-        rescue => e
-          handle_mcp_error(e, 'CoverageTableTool', error_mode: error_mode)
+            model = CoverageModel.new(root: root, resultset: resultset, staleness: staleness_sym,
+              tracked_globs: tracked_globs)
+            table = model.format_table(
+              sort_order: sort_order_sym,
+              check_stale: (staleness_sym == :error),
+              tracked_globs: tracked_globs
+            )
+            # Return text response
+            ::MCP::Tool::Response.new([{ 'type' => 'text', 'text' => table }])
+          end
         end
       end
     end

data/lib/simplecov_mcp/tools/coverage_totals_tool.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative '../model'
+require_relative '../base_tool'
+require_relative '../presenters/project_totals_presenter'
+
+module SimpleCovMcp
+  module Tools
+    class CoverageTotalsTool < BaseTool
+      description <<~DESC
+        Use this when you want aggregated coverage counts for the entire project.
+        It reports covered/total lines, uncovered line counts, and the overall average percentage.
+        Inputs: optional project root, alternate .resultset path, staleness mode, tracked_globs, and error mode.
+        Output: JSON {"lines":{"total","covered","uncovered"},"percentage":Float,"files":{"total","ok","stale"}}.
+        Example: "Give me total/covered/uncovered line counts and the overall coverage percent."
+      DESC
+
+      input_schema(**coverage_schema(
+        additional_properties: {
+          tracked_globs: TRACKED_GLOBS_PROPERTY
+        }
+      ))
+
+      class << self
+        def call(root: '.', resultset: nil, staleness: :off, tracked_globs: nil,
+          error_mode: 'log', server_context:)
+          with_error_handling('CoverageTotalsTool', error_mode: error_mode) do
+            # Convert string inputs from MCP to symbols for internal use
+            staleness_sym = staleness.to_sym
+
+            model = CoverageModel.new(root: root, resultset: resultset, staleness: staleness_sym,
+              tracked_globs: tracked_globs)
+            presenter = Presenters::ProjectTotalsPresenter.new(
+              model: model,
+              check_stale: (staleness_sym == :error),
+              tracked_globs: tracked_globs
+            )
+            respond_json(presenter.relativized_payload, name: 'coverage_totals.json', pretty: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/tools/help_tool.rb

@@ -6,30 +6,14 @@ 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?".
+        Returns help containing descriptions of all tools, including: use_when, avoid_when, inputs.
       DESC
 
       input_schema(
         type: 'object',
         additionalProperties: false,
         properties: {
-          query: {
-            type: 'string',
-            description:
-              'Optional keywords to filter the help entries (e.g., "uncovered", "summary").'
-          },
-          error_mode: {
-            type: 'string',
-            description:
-              "Error handling mode: 'off' (silent), 'on' (log errors), 'trace' (verbose).",
-            enum: ['off', 'on', 'trace'],
-            default: 'on'
-          }
+          error_mode: ERROR_MODE_PROPERTY
         }
       )
 
@@ -39,104 +23,92 @@ module SimpleCovMcp
           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?'
+          inputs: ['path (required)', 'root/resultset/staleness (optional)']
         },
         {
           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.'
+          inputs: ['path (required)', 'root/resultset/staleness (optional)']
         },
         {
           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.'
+          inputs: ['path (required)', 'root/resultset/staleness (optional)']
         },
         {
           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.'
+          inputs: ['path (required)', 'root/resultset/staleness (optional)']
         },
         {
           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.'
+          inputs: ['root/resultset (optional)', 'sort_order', 'staleness', 'tracked_globs']
+        },
+        {
+          tool: CoverageTotalsTool,
+          label: 'Project coverage totals',
+          use_when: 'User wants total/covered/uncovered line counts or the average percent.',
+          avoid_when: 'User needs per-file breakdowns.',
+          inputs: ['root/resultset (optional)', 'staleness', 'tracked_globs']
         },
         {
           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.'
+          inputs: ['root/resultset (optional)', 'sort_order', 'staleness']
+        },
+        {
+          tool: ValidateTool,
+          label: 'Validate coverage policy',
+          use_when: 'User needs to enforce coverage rules (e.g., minimum percentage) in CI.',
+          avoid_when: 'User just wants to view coverage data.',
+          inputs: ['path (required)', 'root/resultset (optional)']
+        },
+        {
+          tool: ValidateTool,
+          label: 'Validate coverage policy',
+          use_when: 'User needs to enforce coverage rules (e.g., minimum percentage) in CI.',
+          avoid_when: 'User just wants to view coverage data.',
+          inputs: ['path (required)', 'root/resultset (optional)']
         },
         {
           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?'
+          inputs: ['(no arguments)']
         }
       ].freeze
 
       class << self
-        def call(query: nil, error_mode: 'on', server_context:, **_unused)
-          entries = TOOL_GUIDE.map { |guide| format_entry(guide) }
-          entries = filter_entries(entries, query) if query && !query.strip.empty?
+        def call(error_mode: 'log', server_context:, **_unused)
+          with_error_handling('HelpTool', error_mode: error_mode) do
+            entries = TOOL_GUIDE.map { |guide| format_entry(guide) }
 
-          data = { query: query, tools: entries }
-          respond_json(data, name: 'tools_help.json')
-        rescue => e
-          handle_mcp_error(e, 'HelpTool', error_mode: error_mode)
+            data = { tools: entries }
+            respond_json(data, name: 'tools_help.json')
+          end
         end
 
-        private
-
-        def format_entry(guide)
+        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]
+            'inputs' => guide[:inputs]
           }
         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

data/lib/simplecov_mcp/tools/uncovered_lines_tool.rb

@@ -10,18 +10,23 @@ module SimpleCovMcp
       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), "summary" {"covered","total","pct"}, and "stale" status.
+        Inputs: file path (required) plus optional root/resultset/staleness mode inherited from BaseTool.
+        Output: JSON object with keys "file", "uncovered" (array of integers), "summary" {"covered","total","percentage"}, and "stale" status.
         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', error_mode: 'on', server_context:)
-          model = CoverageModel.new(root: root, resultset: resultset, staleness: stale)
-          presenter = Presenters::CoverageUncoveredPresenter.new(model: model, path: path)
-          respond_json(presenter.relativized_payload, name: 'uncovered_lines.json', pretty: true)
-        rescue => e
-          handle_mcp_error(e, 'UncoveredLinesTool', error_mode: error_mode)
+        def call(path:, root: '.', resultset: nil, staleness: :off, error_mode: 'log',
+          server_context:)
+          with_error_handling('UncoveredLinesTool', error_mode: error_mode) do
+            model = CoverageModel.new(
+              root: root,
+              resultset: resultset,
+              staleness: staleness.to_sym
+            )
+            presenter = Presenters::CoverageUncoveredPresenter.new(model: model, path: path)
+            respond_json(presenter.relativized_payload, name: 'uncovered_lines.json', pretty: true)
+          end
         end
       end
     end

data/lib/simplecov_mcp/tools/validate_tool.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+require_relative '../model'
+require_relative '../predicate_evaluator'
+
+module SimpleCovMcp
+  module Tools
+    class ValidateTool < BaseTool
+      description <<~DESC
+        Validates coverage data against a predicate (Ruby code that evaluates to true/false).
+        Use this to enforce coverage policies programmatically.
+        Inputs: Either 'code' (Ruby string) OR 'file' (path to Ruby file), plus optional root/resultset/staleness/error_mode.
+        Output: JSON object {"result": Boolean} where true means policy passed, false means failed.
+        On error (syntax error, file not found, etc.), returns an MCP error response.
+        Security Warning: Predicates execute as arbitrary Ruby code with full system privileges.
+        Examples:
+        - "Check if all files have at least 80% coverage" → {"code": "->(m) { m.all_files.all? { |f| f['percentage'] >= 80 } }"}
+        - "Run coverage policy from file" → {"file": "coverage_policy.rb"}
+      DESC
+
+      input_schema(**coverage_schema(
+        additional_properties: {
+          code: {
+            type: 'string',
+            description: 'Ruby code string that returns a callable predicate. ' \
+                         'Must evaluate to a lambda, proc, or object with #call method.'
+          },
+          file: {
+            type: 'string',
+            description:
+              'Path to Ruby file containing predicate code (absolute or relative to root).'
+          }
+        }
+      ))
+      class << self
+        def call(code: nil, file: nil, root: '.', resultset: nil, staleness: :off,
+          error_mode: 'log', server_context:)
+          with_error_handling('ValidateTool', error_mode: error_mode) do
+            # Re-use logic from ValidateCommand, but adapt for MCP return format
+            require_relative '../cli'
+
+            # Create a minimal CLI shim to reuse command logic
+            cli = CoverageCLI.new
+            cli.config.root = root
+            cli.config.resultset = resultset
+            cli.config.staleness = staleness.to_sym
+            cli.config.error_mode = error_mode.to_sym
+
+            # We need to capture the boolean result instead of letting it exit
+            # Commands::ValidateCommand is designed to exit, so we'll use the model and evaluator directly
+            # This duplicates some logic from ValidateCommand#execute but avoids the exit(status) call
+
+            model = CoverageModel.new(**cli.config.model_options)
+
+            result = if code
+              PredicateEvaluator.evaluate_code(code, model)
+            elsif file
+              # Resolve file path relative to root if needed
+              predicate_path = File.expand_path(file, root)
+              PredicateEvaluator.evaluate_file(predicate_path, model)
+            else
+              raise UsageError, "Either 'code' or 'file' must be provided"
+            end
+
+            respond_json({ result: result }, name: 'validate_result.json', pretty: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov_mcp/tools/version_tool.rb

@@ -15,23 +15,16 @@ module SimpleCovMcp
         type: 'object',
         additionalProperties: false,
         properties: {
-          error_mode: {
-            type: 'string',
-            description:
-              "Error handling mode: 'off' (silent), 'on' (log errors), 'trace' (verbose).",
-            enum: ['off', 'on', 'trace'],
-            default: 'on'
-          }
+          error_mode: ERROR_MODE_PROPERTY
         }
       )
-
       class << self
-        def call(error_mode: 'on', server_context: nil, **_args)
-          ::MCP::Tool::Response.new([
-            { type: 'text', text: "SimpleCovMcp version: #{SimpleCovMcp::VERSION}" }
-          ])
-        rescue => error
-          handle_mcp_error(error, 'version_tool', error_mode: error_mode)
+        def call(error_mode: 'log', server_context: nil, **_args)
+          with_error_handling('VersionTool', error_mode: error_mode) do
+            ::MCP::Tool::Response.new([
+              { 'type' => 'text', 'text' => "SimpleCovMcp version: #{SimpleCovMcp::VERSION}" }
+            ])
+          end
         end
       end
     end

data/lib/simplecov_mcp/util.rb

@@ -12,9 +12,7 @@ module SimpleCovMcp
   DEFAULT_LOG_FILESPEC = './simplecov_mcp.log'
 
   module CovUtil
-    module_function
-
-    def log(msg)
+    module_function def log(msg)
       log_file = SimpleCovMcp.active_log_file
 
       case log_file
@@ -27,39 +25,47 @@ module SimpleCovMcp
         path_to_log = log_file || DEFAULT_LOG_FILESPEC
         File.open(File.expand_path(path_to_log), 'a') { |f| f.puts "[#{Time.now.iso8601}] #{msg}" }
       end
-    rescue StandardError => e
+    rescue => e
       # Fallback to stderr if file logging fails, but suppress in MCP mode
       # to avoid interfering with JSON-RPC protocol
       unless SimpleCovMcp.context.mcp_mode?
         begin
           $stderr.puts "[#{Time.now.iso8601}] LOGGING ERROR: #{e.message}"
           $stderr.puts "[#{Time.now.iso8601}] #{msg}"
-        rescue StandardError
+        rescue
           # Silently ignore only stderr fallback failures
         end
       end
     end
 
-    def find_resultset(root, resultset: nil)
+    # Safe logging that never raises - use when logging should not interrupt execution.
+    # Unlike `log`, this method guarantees it will never propagate exceptions.
+    module_function def safe_log(msg)
+      log(msg)
+    rescue
+      # Silently ignore all logging failures
+    end
+
+    module_function def find_resultset(root, resultset: nil)
       Resolvers::ResolverFactory.find_resultset(root, resultset: resultset)
     end
 
-    def lookup_lines(cov, file_abs)
+    module_function def lookup_lines(cov, file_abs)
       Resolvers::ResolverFactory.lookup_lines(cov, file_abs)
     end
 
-    def summary(arr)
+    module_function def summary(arr)
       total = 0
       covered = 0
       arr.compact.each do |hits|
         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 }
+      percentage = total.zero? ? 100.0 : ((covered.to_f * 100.0 / total) * 100).round / 100.0
+      { 'covered' => covered, 'total' => total, 'percentage' => percentage }
     end
 
-    def uncovered(arr)
+    module_function def uncovered(arr)
       out = []
 
       arr.each_with_index do |hits, i|
@@ -70,7 +76,7 @@ module SimpleCovMcp
       out
     end
 
-    def detailed(arr)
+    module_function def detailed(arr)
       rows = []
       arr.each_with_index do |hits, i|
         h = hits&.to_i

data/lib/simplecov_mcp/version.rb

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