cov-loupe 3.0.0

data/lib/cov_loupe/tools/coverage_table_tool.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+
+require_relative '../base_tool'
+require_relative '../presenters/project_coverage_presenter'
+
+module CovLoupe
+  module Tools
+    class CoverageTableTool < BaseTool
+      description <<~DESC
+        Use this when a user wants the plain text coverage table exactly like `cov-loupe --table` would print (no ANSI colors).
+        Do not use this for machine-readable data; coverage.all_files returns structured JSON.
+        Inputs: optional project root/resultset path/sort order/staleness mode matching the CLI flags.
+        Output: text block containing the formatted coverage table with headers and percentages.
+        Example: "Show me the CLI coverage table sorted descending".
+      DESC
+      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']
+          },
+          tracked_globs: TRACKED_GLOBS_PROPERTY
+        }
+      ))
+      class << self
+        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: 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
+  end
+end

data/lib/cov_loupe/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 CovLoupe
+  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/cov_loupe/tools/help_tool.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module CovLoupe
+  module Tools
+    class HelpTool < BaseTool
+      description <<~DESC
+        Returns help containing descriptions of all tools, including: use_when, avoid_when, inputs.
+      DESC
+
+      input_schema(
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          error_mode: ERROR_MODE_PROPERTY
+        }
+      )
+
+      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/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/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/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/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', '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', '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: 'cov-loupe version',
+          use_when: 'User needs to confirm the running gem version.',
+          avoid_when: 'User is asking for coverage information.',
+          inputs: ['(no arguments)']
+        }
+      ].freeze
+
+      class << self
+        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 = { tools: entries }
+            respond_json(data, name: 'tools_help.json')
+          end
+        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]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/tools/uncovered_lines_tool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+require_relative '../model'
+require_relative '../presenters/coverage_uncovered_presenter'
+
+module CovLoupe
+  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/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/cov_loupe/tools/coverage_summary_tool.rb".
+      DESC
+      input_schema(**input_schema_def)
+      class << self
+        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
+  end
+end

data/lib/cov_loupe/tools/validate_tool.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+require_relative '../model'
+require_relative '../predicate_evaluator'
+
+module CovLoupe
+  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/cov_loupe/tools/version_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+
+module CovLoupe
+  module Tools
+    class VersionTool < BaseTool
+      description <<~DESC
+        Use this when the user or client needs to confirm which version of cov-loupe is running.
+        This tool takes no arguments and only returns the version string; avoid it for coverage data.
+        Output: plain text line "CovLoupe version: x.y.z".
+        Example: "What version of cov-loupe is installed?".
+      DESC
+      input_schema(
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          error_mode: ERROR_MODE_PROPERTY
+        }
+      )
+      class << self
+        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' => "CovLoupe version: #{CovLoupe::VERSION}" }
+            ])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/util.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative 'resolvers/resolver_factory'
+
+module CovLoupe
+  RESULTSET_CANDIDATES = [
+    '.resultset.json',
+    'coverage/.resultset.json',
+    'tmp/.resultset.json'
+  ].freeze
+
+  DEFAULT_LOG_FILESPEC = './cov_loupe.log'
+
+  module CovUtil
+    module_function def log(msg)
+      log_file = CovLoupe.active_log_file
+
+      case log_file
+      when 'stdout'
+        $stdout.puts "[#{Time.now.iso8601}] #{msg}"
+      when 'stderr'
+        $stderr.puts "[#{Time.now.iso8601}] #{msg}"
+      else
+        # Handles both nil (default) and custom file paths
+        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 => e
+      # Fallback to stderr if file logging fails, but suppress in MCP mode
+      # to avoid interfering with JSON-RPC protocol
+      unless CovLoupe.context.mcp_mode?
+        begin
+          $stderr.puts "[#{Time.now.iso8601}] LOGGING ERROR: #{e.message}"
+          $stderr.puts "[#{Time.now.iso8601}] #{msg}"
+        rescue
+          # Silently ignore only stderr fallback failures
+        end
+      end
+    end
+
+    # 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
+
+    module_function def lookup_lines(cov, file_abs)
+      Resolvers::ResolverFactory.lookup_lines(cov, file_abs)
+    end
+
+    module_function def summary(arr)
+      total = 0
+      covered = 0
+      arr.compact.each do |hits|
+        total += 1
+        covered += 1 if hits.to_i > 0
+      end
+      percentage = total.zero? ? 100.0 : ((covered.to_f * 100.0 / total) * 100).round / 100.0
+      { 'covered' => covered, 'total' => total, 'percentage' => percentage }
+    end
+
+    module_function 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
+
+    module_function def detailed(arr)
+      rows = []
+      arr.each_with_index do |hits, i|
+        h = hits&.to_i
+        rows << { 'line' => i + 1, 'hits' => h, 'covered' => h.positive? } if h
+      end
+      rows
+    end
+  end
+end

data/lib/cov_loupe/version.rb

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

data/lib/cov_loupe.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'pathname'
+require 'set' # rubocop:disable Lint/RedundantRequireStatement -- Ruby >= 3.4 requires explicit require for set; RuboCop targets 3.2
+require 'optparse'
+require 'mcp'
+require 'mcp/server/transports/stdio_transport'
+
+require_relative 'cov_loupe/version'
+require_relative 'cov_loupe/app_context'
+require_relative 'cov_loupe/util'
+require_relative 'cov_loupe/errors'
+require_relative 'cov_loupe/error_handler'
+require_relative 'cov_loupe/error_handler_factory'
+require_relative 'cov_loupe/path_relativizer'
+require_relative 'cov_loupe/resultset_loader'
+require_relative 'cov_loupe/mode_detector'
+require_relative 'cov_loupe/model'
+require_relative 'cov_loupe/coverage_reporter'
+require_relative 'cov_loupe/base_tool'
+require_relative 'cov_loupe/tools/coverage_raw_tool'
+require_relative 'cov_loupe/tools/coverage_summary_tool'
+require_relative 'cov_loupe/tools/uncovered_lines_tool'
+require_relative 'cov_loupe/tools/coverage_detailed_tool'
+require_relative 'cov_loupe/tools/all_files_coverage_tool'
+require_relative 'cov_loupe/tools/coverage_totals_tool'
+require_relative 'cov_loupe/tools/coverage_table_tool'
+require_relative 'cov_loupe/tools/validate_tool'
+require_relative 'cov_loupe/tools/version_tool'
+require_relative 'cov_loupe/tools/help_tool'
+require_relative 'cov_loupe/mcp_server'
+require_relative 'cov_loupe/cli'
+
+module CovLoupe
+  class << self
+    THREAD_CONTEXT_KEY = :cov_loupe_context
+
+    def run(argv)
+      # Prepend environment options once at entry point
+      full_argv = extract_env_opts + argv
+
+      if ModeDetector.cli_mode?(full_argv)
+        # CLI mode: pass merged argv to CoverageCLI
+        CoverageCLI.new.run(full_argv)
+      else
+        # MCP server mode: parse config once from full_argv
+        require_relative 'cov_loupe/config_parser'
+        config = ConfigParser.parse(full_argv)
+
+        if config.log_file == 'stdout'
+          raise ConfigurationError,
+            'Logging to stdout is not permitted in MCP server mode as it interferes with ' \
+            "the JSON-RPC protocol. Please use 'stderr' or a file path."
+        end
+
+        handler = ErrorHandlerFactory.for_mcp_server(error_mode: config.error_mode)
+        context = create_context(error_handler: handler, log_target: config.log_file,
+          mode: :mcp)
+        with_context(context) { MCPServer.new(context: context).run }
+      end
+    end
+
+    def with_context(context)
+      previous = Thread.current[THREAD_CONTEXT_KEY]
+      Thread.current[THREAD_CONTEXT_KEY] = context
+      yield
+    ensure
+      Thread.current[THREAD_CONTEXT_KEY] = previous
+    end
+
+    def context
+      Thread.current[THREAD_CONTEXT_KEY] || default_context
+    end
+
+    def create_context(error_handler:, log_target: nil, mode: :library)
+      AppContext.new(
+        error_handler: error_handler,
+        log_target: log_target.nil? ? default_context.log_target : log_target,
+        mode: mode
+      )
+    end
+
+    def default_log_file
+      default_context.log_target
+    end
+
+    def default_log_file=(value)
+      previous_default = default_context
+      @default_context = previous_default.with_log_target(value)
+      active = Thread.current[THREAD_CONTEXT_KEY]
+      if active.nil? || active.log_target == previous_default.log_target
+        Thread.current[THREAD_CONTEXT_KEY] = @default_context
+      end
+      value # rubocop:disable Lint/Void -- return assigned log target for symmetry
+    end
+
+    def active_log_file
+      context.log_target
+    end
+
+    def active_log_file=(value)
+      current = Thread.current[THREAD_CONTEXT_KEY]
+      Thread.current[THREAD_CONTEXT_KEY] = if current
+        current.with_log_target(value)
+      else
+        default_context.with_log_target(value)
+      end
+      value # rubocop:disable Lint/Void -- return assigned log target for symmetry
+    end
+
+    def error_handler
+      context.error_handler
+    end
+
+    def error_handler=(handler)
+      @default_context = default_context.with_error_handler(handler)
+    end
+
+    private def default_context
+      @default_context ||= AppContext.new(
+        error_handler: ErrorHandlerFactory.for_cli,
+        log_target: nil
+      )
+    end
+
+    private def extract_env_opts
+      require 'shellwords'
+      opts_string = ENV['COV_LOUPE_OPTS']
+      return [] unless opts_string && !opts_string.empty?
+
+      begin
+        Shellwords.split(opts_string)
+      rescue ArgumentError
+        [] # Ignore parsing errors
+      end
+    end
+  end
+end