cov-loupe 3.0.0

data/lib/cov_loupe/option_parsers/env_options_parser.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+require_relative '../option_normalizers'
+
+module CovLoupe
+  module OptionParsers
+    class EnvOptionsParser
+      ENV_VAR = 'COV_LOUPE_OPTS'
+
+      def initialize(env_var: ENV_VAR)
+        @env_var = env_var
+      end
+
+      def parse_env_opts
+        opts_string = ENV[@env_var]
+        return [] unless opts_string && !opts_string.empty?
+
+        begin
+          Shellwords.split(opts_string)
+        rescue ArgumentError => e
+          raise CovLoupe::ConfigurationError, "Invalid #{@env_var} format: #{e.message}"
+        end
+      end
+
+      def pre_scan_error_mode(argv, error_mode_normalizer: method(:normalize_error_mode))
+        # Quick scan for --error-mode to ensure early errors are logged correctly
+        argv.each_with_index do |arg, i|
+          if arg == '--error-mode' && argv[i + 1]
+            return error_mode_normalizer.call(argv[i + 1])
+          elsif arg.start_with?('--error-mode=')
+            value = arg.split('=', 2)[1]
+            return nil if value.to_s.empty?
+            return error_mode_normalizer.call(value) if value
+          end
+        end
+        nil
+      rescue
+        # Ignore errors during pre-scan; they'll be caught during actual parsing
+        nil
+      end
+
+      private def normalize_error_mode(value)
+        OptionNormalizers.normalize_error_mode(value, strict: false, default: :log)
+      end
+    end
+  end
+end

data/lib/cov_loupe/option_parsers/error_helper.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  module OptionParsers
+    class ErrorHelper
+      SUBCOMMANDS = %w[list summary raw uncovered detailed totals version].freeze
+
+      def initialize(subcommands = SUBCOMMANDS)
+        @subcommands = subcommands
+      end
+
+      def handle_option_parser_error(error, argv: [], usage_hint: "Run '#{program_name} --help' for usage information.")
+        message = error.message.to_s
+        # Suggest a subcommand when an invalid option matches a known subcommand
+        option = extract_invalid_option(message)
+
+        if option&.start_with?('--') && @subcommands.include?(option[2..])
+          suggest_subcommand(option)
+        else
+          # Generic message from OptionParser
+          warn "Error: #{message}"
+          # Attempt to derive a helpful hint for enumerated options
+          if (hint = build_enum_value_hint(argv))
+            warn hint
+          end
+        end
+        warn usage_hint
+        exit 1
+      end
+
+      private def extract_invalid_option(message)
+        message.match(/invalid option: (.+)/)[1]
+      rescue
+        nil
+      end
+
+      private def suggest_subcommand(option)
+        subcommand = option[2..]
+        warn "Error: '#{option}' is not a valid option. Did you mean the '#{subcommand}' subcommand?"
+        warn "Try: #{program_name} #{subcommand} [args]"
+      end
+
+      private def build_enum_value_hint(argv)
+        rules = enumerated_option_rules
+        tokens = Array(argv)
+        rules.each do |rule|
+          hint = build_hint_for_rule(rule, tokens)
+          return hint if hint
+        end
+        nil
+      end
+
+      private def build_hint_for_rule(rule, tokens)
+        switches = rule[:switches]
+        allowed = rule[:values]
+        display = rule[:display] || allowed.join(', ')
+        preferred = switches.find { |s| s.start_with?('--') } || switches.first
+
+        tokens.each_with_index do |tok, i|
+          # --opt=value form
+          if equal_form_match?(tok, switches, preferred)
+            hint = handle_equal_form(tok, switches, preferred, display, allowed)
+            return hint if hint
+          end
+
+          # --opt value or -o value form
+          if switches.include?(tok)
+            hint = handle_space_form(tokens, i, preferred, display, allowed)
+            return hint if hint
+          end
+        end
+        nil
+      end
+
+      private def equal_form_match?(token, switches, preferred)
+        token.start_with?(preferred + '=') || switches.any? { |s| token.start_with?(s + '=') }
+      end
+
+      private def handle_equal_form(token, switches, preferred, display, allowed)
+        sw = switches.find { |s| token.start_with?(s + '=') } || preferred
+        val = token.split('=', 2)[1]
+        "Valid values for #{sw}: #{display}" if val && !allowed.include?(val)
+      end
+
+      private def handle_space_form(tokens, index, preferred, display, allowed)
+        val = tokens[index + 1]
+        # If missing value, provide hint; if present and invalid, also hint
+        if val.nil? || val.start_with?('-') || !allowed.include?(val)
+          "Valid values for #{preferred}: #{display}"
+        end
+      end
+
+      private def enumerated_option_rules
+        [
+          { switches: ['-S', '--staleness'], values: %w[off o error e], display: 'o[ff]|e[rror]' },
+          { switches: ['-s', '--source'], values: %w[full f uncovered u],
+            display: 'f[ull]|u[ncovered]' },
+          { switches: ['--error-mode'], values: %w[off o log l debug d],
+            display: 'o[ff]|l[og]|d[ebug]' },
+          { switches: ['-o', '--sort-order'], values: %w[a d ascending descending],
+            display: 'a[scending]|d[escending]' }
+        ]
+      end
+
+      private def program_name
+        'cov-loupe'
+      end
+    end
+  end
+end

data/lib/cov_loupe/path_relativizer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module CovLoupe
+  # Utility object that converts configured path-bearing keys to forms
+  # relative to the project root while leaving the original payload untouched.
+  class PathRelativizer
+    def initialize(root:, scalar_keys:, array_keys: [])
+      @root = Pathname.new(File.absolute_path(root || '.'))
+      @scalar_keys = Array(scalar_keys).map(&:to_s).freeze
+      @array_keys = Array(array_keys).map(&:to_s).freeze
+    end
+
+    def relativize(obj)
+      deep_copy_and_relativize(obj)
+    end
+
+    # Converts an absolute path to a path relative to the root.
+    # Falls back to the original path if conversion fails (e.g., different drive on Windows).
+    #
+    # @param path [String] file path (absolute or relative)
+    # @return [String] relative path or original path on failure
+    def relativize_path(path)
+      root_str = @root.to_s
+      abs = File.absolute_path(path, root_str)
+      return path unless abs.start_with?(root_prefix(root_str)) || abs == root_str
+
+      Pathname.new(abs).relative_path_from(@root).to_s
+    rescue ArgumentError
+      path
+    end
+
+    private def deep_copy_and_relativize(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), acc|
+          acc[k] = relativize_value(k, v)
+        end
+      when Array
+        obj.map { |item| deep_copy_and_relativize(item) }
+      else
+        obj
+      end
+    end
+
+    private def relativize_value(key, value)
+      key_str = key.to_s
+      if @scalar_keys.include?(key_str) && value.is_a?(String)
+        relativize_path(value)
+      elsif @array_keys.include?(key_str) && value.is_a?(Array)
+        value.map do |item|
+          item.is_a?(String) ? relativize_path(item) : deep_copy_and_relativize(item)
+        end
+      else
+        deep_copy_and_relativize(value)
+      end
+    end
+
+    private def root_prefix(root_str)
+      root_str.end_with?(File::SEPARATOR) ? root_str : root_str + File::SEPARATOR
+    end
+  end
+end

data/lib/cov_loupe/predicate_evaluator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Evaluates coverage predicates from either Ruby code strings or files.
+  # Used by the validate subcommand, validate MCP tool, and library API.
+  #
+  # Security Warning:
+  # Predicates execute as arbitrary Ruby code with full system privileges.
+  # Only use predicates from trusted sources.
+  class PredicateEvaluator
+    # Evaluate a predicate from a code string
+    #
+    # @param code [String] Ruby code that returns a callable (lambda, proc, or object with #call)
+    # @param model [CoverageModel] The coverage model to pass to the predicate
+    # @return [Boolean] The result of calling the predicate with the model
+    # @raise [RuntimeError] If the code doesn't return a callable or has syntax errors
+    def self.evaluate_code(code, model)
+      # WARNING: The predicate code executes with full Ruby privileges.
+      # It has unrestricted access to the file system, network, and system commands.
+      # Only use predicate code from trusted sources.
+      #
+      # We evaluate in a fresh Object context to prevent accidental access to
+      # internals, but this provides NO security isolation.
+      evaluation_context = Object.new
+      predicate = evaluation_context.instance_eval(code, '<predicate>', 1)
+
+      validate_callable(predicate)
+      predicate.call(model)
+    rescue SyntaxError => e
+      raise "Syntax error in predicate code: #{e.message}"
+    end
+
+    # Evaluate a predicate from a file
+    #
+    # @param path [String] Path to Ruby file containing predicate code
+    # @param model [CoverageModel] The coverage model to pass to the predicate
+    # @return [Boolean] The result of calling the predicate with the model
+    # @raise [RuntimeError] If the file doesn't exist, doesn't return a callable, or has syntax errors
+    def self.evaluate_file(path, model)
+      unless File.exist?(path)
+        raise "Predicate file not found: #{path}"
+      end
+
+      content = File.read(path)
+
+      # WARNING: The predicate code executes with full Ruby privileges.
+      # It has unrestricted access to the file system, network, and system commands.
+      # Only use predicate files from trusted sources.
+      #
+      # We evaluate in a fresh Object context to prevent accidental access to
+      # internals, but this provides NO security isolation.
+      evaluation_context = Object.new
+      predicate = evaluation_context.instance_eval(content, path, 1)
+
+      validate_callable(predicate)
+      predicate.call(model)
+    rescue SyntaxError => e
+      raise "Syntax error in predicate file: #{e.message}"
+    end
+
+    # Validate that an object is callable
+    #
+    # @param predicate [Object] The object to check
+    # @raise [RuntimeError] If the object doesn't respond to #call
+    def self.validate_callable(predicate)
+      unless predicate.respond_to?(:call)
+        raise 'Predicate must be callable (lambda, proc, or object with #call method)'
+      end
+    end
+    private_class_method :validate_callable
+  end
+end

data/lib/cov_loupe/presenters/base_coverage_presenter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  module Presenters
+    # Shared presenter behavior for single-file coverage payloads.
+    class BaseCoveragePresenter
+      attr_reader :model, :path
+
+      def initialize(model:, path:)
+        @model = model
+        @path = path
+      end
+
+      # Returns the absolute-path payload augmented with stale metadata.
+      def absolute_payload
+        @absolute_payload ||= begin
+          payload = build_payload
+          payload.merge('stale' => model.staleness_for(path))
+        end
+      end
+
+      # Returns the payload with file paths relativized for presentation.
+      def relativized_payload
+        @relativized_payload ||= model.relativize(absolute_payload)
+      end
+
+      # Returns the cached stale status for the file.
+      def stale
+        absolute_payload['stale']
+      end
+
+      # Returns the relativized file path used in CLI output.
+      def relative_path
+        relativized_payload['file']
+      end
+
+      private def build_payload
+        raise NotImplementedError, "#{self.class} must implement #build_payload"
+      end
+    end
+  end
+end

data/lib/cov_loupe/presenters/coverage_detailed_presenter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'base_coverage_presenter'
+
+module CovLoupe
+  module Presenters
+    # Provides shared detailed coverage payloads for CLI and MCP callers.
+    class CoverageDetailedPresenter < BaseCoveragePresenter
+      private def build_payload
+        model.detailed_for(path)
+      end
+    end
+  end
+end

data/lib/cov_loupe/presenters/coverage_raw_presenter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'base_coverage_presenter'
+
+module CovLoupe
+  module Presenters
+    # Provides shared raw coverage payloads for CLI and MCP callers.
+    class CoverageRawPresenter < BaseCoveragePresenter
+      private def build_payload
+        model.raw_for(path)
+      end
+    end
+  end
+end

data/lib/cov_loupe/presenters/coverage_summary_presenter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'base_coverage_presenter'
+
+module CovLoupe
+  module Presenters
+    # Builds a consistent summary payload that both the CLI and MCP surfaces can use.
+    class CoverageSummaryPresenter < BaseCoveragePresenter
+      private def build_payload
+        model.summary_for(path)
+      end
+    end
+  end
+end

data/lib/cov_loupe/presenters/coverage_uncovered_presenter.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'base_coverage_presenter'
+
+module CovLoupe
+  module Presenters
+    # Provides shared uncovered coverage payloads for CLI and MCP callers.
+    class CoverageUncoveredPresenter < BaseCoveragePresenter
+      private def build_payload
+        model.uncovered_for(path)
+      end
+    end
+  end
+end

data/lib/cov_loupe/presenters/project_coverage_presenter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  module Presenters
+    # Provides repository-wide coverage summaries shared by CLI and MCP surfaces.
+    class ProjectCoveragePresenter
+      attr_reader :model, :sort_order, :check_stale, :tracked_globs
+
+      def initialize(model:, sort_order:, check_stale:, tracked_globs:)
+        @model = model
+        @sort_order = sort_order
+        @check_stale = check_stale
+        @tracked_globs = tracked_globs
+      end
+
+      # Returns the absolute-path payload including counts.
+      def absolute_payload
+        @absolute_payload ||= begin
+          files = model.all_files(
+            sort_order: sort_order,
+            check_stale: check_stale,
+            tracked_globs: tracked_globs
+          )
+          { 'files' => files, 'counts' => build_counts(files) }
+        end
+      end
+
+      # Returns the payload with file paths relativized for presentation.
+      def relativized_payload
+        @relativized_payload ||= model.relativize(absolute_payload)
+      end
+
+      # Returns the relativized file rows.
+      def relative_files
+        relativized_payload['files']
+      end
+
+      # Returns the coverage counts with relative file paths.
+      def relative_counts
+        relativized_payload['counts']
+      end
+
+      private def build_counts(files)
+        total = files.length
+        stale = files.count { |f| f['stale'] }
+        { 'total' => total, 'ok' => total - stale, 'stale' => stale }
+      end
+    end
+  end
+end

data/lib/cov_loupe/presenters/project_totals_presenter.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  module Presenters
+    # Provides aggregated line totals and average coverage across the project.
+    class ProjectTotalsPresenter
+      attr_reader :model, :check_stale, :tracked_globs
+
+      def initialize(model:, check_stale:, tracked_globs:)
+        @model = model
+        @check_stale = check_stale
+        @tracked_globs = tracked_globs
+      end
+
+      def absolute_payload
+        @absolute_payload ||= model.project_totals(
+          tracked_globs: tracked_globs,
+          check_stale: check_stale
+        )
+      end
+
+      def relativized_payload
+        @relativized_payload ||= model.relativize(absolute_payload)
+      end
+    end
+  end
+end

data/lib/cov_loupe/resolvers/coverage_line_resolver.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  module Resolvers
+    class CoverageLineResolver
+      def initialize(cov_data)
+        @cov_data = cov_data
+      end
+
+      def lookup_lines(file_abs)
+        # First try exact match
+        direct_match = find_direct_match(file_abs)
+        return direct_match if direct_match
+
+        # Then try without current working directory prefix
+        stripped_match = find_stripped_match(file_abs)
+        return stripped_match if stripped_match
+
+        raise_not_found_error(file_abs)
+      end
+
+      attr_reader :cov_data
+
+      private def find_direct_match(file_abs)
+        entry = cov_data[file_abs]
+        lines_from_entry(entry)
+      end
+
+      private def find_stripped_match(file_abs)
+        return unless file_abs.start_with?(cwd_with_slash)
+
+        relative_path = file_abs[(cwd.length + 1)..]
+        entry = cov_data[relative_path]
+        lines_from_entry(entry)
+      end
+
+      private def cwd
+        @cwd ||= Dir.pwd
+      end
+
+      private def cwd_with_slash
+        @cwd_with_slash ||= "#{cwd}/"
+      end
+
+      private def raise_not_found_error(file_abs)
+        raise FileError, "No coverage entry found for #{file_abs}"
+      end
+
+      # Entry may store exact line coverage, branch-only coverage, or neither.
+      # Prefer the provided `lines` array but fall back to synthesizing one so
+      # callers always receive something enumerable.
+      #
+      # Returning nil tells callers to keep searching; the resolver will raise
+      # a FileError if no variant yields coverage data.
+      private def lines_from_entry(entry)
+        return unless entry.is_a?(Hash)
+
+        lines = entry['lines']
+        return lines if lines.is_a?(Array)
+
+        synthesize_lines_from_branches(entry['branches'])
+      end
+
+      # Some SimpleCov configurations track only branch coverage. When the
+      # resultset omits the legacy `lines` array we rebuild a minimal substitute
+      # so the rest of the pipeline (summaries, uncovered lines, staleness) can
+      # continue to operate.
+      #
+      # Branch data looks like:
+      #   "[:if, 0, 12, 4, 20, 29]" => { "[:then, ...]" => hits, ... }
+      # We care about the third tuple element (line number). We sum branch-leg
+      # hits per line so the synthetic array still behaves like legacy line
+      # coverage (any positive value counts as executed).
+      private def synthesize_lines_from_branches(branch_data)
+        # Detailed shape and rationale documented in docs/BRANCH_ONLY_COVERAGE.md
+        return unless branch_data.is_a?(Hash) && branch_data.any?
+
+        line_hits = {}
+
+        branch_data
+          .values
+          .select { |targets| targets.is_a?(Hash) } # ignore malformed branch entries
+          .flat_map(&:to_a) # flatten each branch target into [meta, hits]
+          .filter_map do |meta, hits|
+            # Extract the covered line; filter_map discards nil results.
+            line_number = extract_line_number(meta)
+            line_number && [line_number, hits.to_i]
+          end
+          .each do |line_number, hits|
+            line_hits[line_number] = line_hits.fetch(line_number, 0) + hits
+          end
+
+        return if line_hits.empty?
+
+        max_line = line_hits.keys.max
+        # Build a dense array up to the highest line recorded so downstream
+        # consumers see the familiar SimpleCov shape (nil for untouched lines).
+        Array.new(max_line) { |idx| line_hits[idx + 1] }
+      end
+
+      # Branch metadata arrives as either the raw SimpleCov array
+      # (e.g. [:if, 0, 12, 4, 20, 29]) or the stringified JSON version
+      # ("[:if, 0, 12, 4, 20, 29]"). We normalize both forms and pull the line.
+      private def extract_line_number(meta)
+        if meta.is_a?(Array)
+          line_token = meta[2]
+          # Integer(..., exception: false) returns nil on failure, so malformed
+          # tuples quietly drop out of the synthesized array.
+          return Integer(line_token, exception: false)
+        end
+
+        tokens = meta.to_s.tr('[]', '').split(',').map(&:strip)
+        return if tokens.length < 3
+
+        Integer(tokens[2], exception: false)
+        # Any parsing errors result in nil; callers treat that as "no line".
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/cov_loupe/resolvers/resolver_factory.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'resultset_path_resolver'
+require_relative 'coverage_line_resolver'
+
+module CovLoupe
+  module Resolvers
+    class ResolverFactory
+      def self.create_resultset_resolver(root: Dir.pwd, resultset: nil, candidates: nil)
+        candidates ?
+          ResultsetPathResolver.new(root: root, candidates: candidates) :
+          ResultsetPathResolver.new(root: root)
+      end
+
+      def self.create_coverage_resolver(cov_data)
+        CoverageLineResolver.new(cov_data)
+      end
+
+      def self.find_resultset(root, resultset: nil)
+        ResultsetPathResolver.new(root: root).find_resultset(resultset: resultset)
+      end
+
+      def self.lookup_lines(cov, file_abs)
+        CoverageLineResolver.new(cov).lookup_lines(file_abs)
+      end
+    end
+  end
+end