cov-loupe 3.0.0

data/lib/cov_loupe/mode_detector.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative 'constants'
+
+module CovLoupe
+  # Centralizes the logic for detecting whether to run in CLI or MCP server mode.
+  # This makes the mode detection strategy explicit and testable.
+  class ModeDetector
+    SUBCOMMANDS = %w[list summary raw uncovered detailed totals validate version].freeze
+
+    # Reference shared constant to avoid duplication with CoverageCLI
+    OPTIONS_EXPECTING_ARGUMENT = Constants::OPTIONS_EXPECTING_ARGUMENT
+
+    def self.cli_mode?(argv, stdin: $stdin)
+      # 1. Explicit flags that force CLI mode always win
+      cli_options = %w[--force-cli -h --help --version -v]
+      return true if argv.intersect?(cli_options)
+
+
+      # 2. Find the first non-option argument
+      first_non_option = find_first_non_option(argv)
+
+      # 3. If a non-option argument exists, it must be a CLI command (or an error)
+      return true if first_non_option
+
+      # 4. Fallback: If no non-option args, use TTY status to decide
+      stdin.tty?
+    end
+
+    def self.mcp_server_mode?(argv, stdin: $stdin)
+      !cli_mode?(argv, stdin: stdin)
+    end
+
+    # Scans argv and returns the first token that is not an option or a value for an option.
+    def self.find_first_non_option(argv)
+      pending_option = false
+      argv.each do |token|
+        if pending_option
+          pending_option = false
+          next
+        end
+
+        if token.start_with?('-')
+          # Check if the option is one that takes a value and isn't using '=' syntax.
+          pending_option = OPTIONS_EXPECTING_ARGUMENT.include?(token) && !token.include?('=')
+          next
+        end
+
+        # Found the first token that is not an option
+        return token
+      end
+      nil
+    end
+    private_class_method :find_first_non_option
+  end
+end

data/lib/cov_loupe/model.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'json'
+
+require_relative 'util'
+require_relative 'errors'
+require_relative 'error_handler'
+require_relative 'staleness_checker'
+require_relative 'path_relativizer'
+require_relative 'resultset_loader'
+
+module CovLoupe
+  class CoverageModel
+    RELATIVIZER_SCALAR_KEYS = %w[file file_path].freeze
+    RELATIVIZER_ARRAY_KEYS = %w[newer_files missing_files deleted_files].freeze
+
+    attr_reader :relativizer
+
+    # Create a CoverageModel
+    #
+    # Params:
+    # - root: project root directory (default '.')
+    # - resultset: path or directory to .resultset.json
+    # - staleness: :off or :error (default :off). When :error, raises
+    #   stale errors if sources are newer than coverage or line counts mismatch.
+    # - tracked_globs: only used for all_files project-level staleness.
+    def initialize(root: '.', resultset: nil, staleness: :off, tracked_globs: nil)
+      @root = File.absolute_path(root || '.')
+      @resultset = resultset
+      @relativizer = PathRelativizer.new(
+        root: @root,
+        scalar_keys: RELATIVIZER_SCALAR_KEYS,
+        array_keys: RELATIVIZER_ARRAY_KEYS
+      )
+
+      load_coverage_data(resultset, staleness, tracked_globs)
+    end
+
+    # Returns { 'file' => <absolute_path>, 'lines' => [hits|nil,...] }
+    def raw_for(path)
+      file_abs, coverage_lines = coverage_data_for(path)
+      { 'file' => file_abs, 'lines' => coverage_lines }
+    end
+
+    def relativize(payload)
+      relativizer.relativize(payload)
+    end
+
+    # Returns { 'file' => <absolute_path>, 'summary' => {'covered'=>, 'total'=>, 'percentage'=>} }
+    def summary_for(path)
+      file_abs, coverage_lines = coverage_data_for(path)
+      { 'file' => file_abs, 'summary' => CovUtil.summary(coverage_lines) }
+    end
+
+    # Returns { 'file' => <absolute_path>, 'uncovered' => [line,...], 'summary' => {...} }
+    def uncovered_for(path)
+      file_abs, coverage_lines = coverage_data_for(path)
+      {
+        'file' => file_abs,
+        'uncovered' => CovUtil.uncovered(coverage_lines),
+        'summary' => CovUtil.summary(coverage_lines)
+      }
+    end
+
+    # Returns { 'file' => <absolute_path>, 'lines' => [{'line'=>,'hits'=>,'covered'=>},...], 'summary' => {...} }
+    def detailed_for(path)
+      file_abs, coverage_lines = coverage_data_for(path)
+      {
+        'file' => file_abs,
+        'lines' => CovUtil.detailed(coverage_lines),
+        'summary' => CovUtil.summary(coverage_lines)
+      }
+    end
+
+    # Returns [ { 'file' =>, 'covered' =>, 'total' =>, 'percentage' =>, 'stale' => }, ... ]
+    def all_files(sort_order: :descending, check_stale: !@checker.off?, tracked_globs: nil)
+      stale_checker = build_staleness_checker(mode: :off, tracked_globs: tracked_globs)
+
+      rows = @cov.map do |abs_path, _data|
+        begin
+          coverage_lines = CovUtil.lookup_lines(@cov, abs_path)
+        rescue FileError
+          next
+        end
+
+        s = CovUtil.summary(coverage_lines)
+        stale = stale_checker.stale_for_file?(abs_path, coverage_lines)
+        {
+          'file' => abs_path,
+          'covered' => s['covered'],
+          'total' => s['total'],
+          'percentage' => s['percentage'],
+          'stale' => stale
+        }
+      end.compact
+
+      rows = filter_rows_by_globs(rows, tracked_globs)
+
+      if check_stale
+        build_staleness_checker(mode: :error, tracked_globs: tracked_globs).check_project!(@cov)
+      end
+
+      sort_rows(rows, sort_order: sort_order)
+    end
+
+    def project_totals(tracked_globs: nil, check_stale: !@checker.off?)
+      rows = all_files(sort_order: :ascending, check_stale: check_stale,
+        tracked_globs: tracked_globs)
+      totals_from_rows(rows)
+    end
+
+    def staleness_for(path)
+      file_abs = File.absolute_path(path, @root)
+      coverage_lines = CovUtil.lookup_lines(@cov, file_abs)
+      @checker.stale_for_file?(file_abs, coverage_lines)
+    rescue => e
+      CovUtil.safe_log("Failed to check staleness for #{path}: #{e.message}")
+      false
+    end
+
+    # Returns formatted table string for all files coverage data
+    def format_table(rows = nil, sort_order: :descending, check_stale: !@checker.off?,
+      tracked_globs: nil)
+      rows = prepare_rows(rows, sort_order: sort_order, check_stale: check_stale,
+        tracked_globs: tracked_globs)
+      return 'No coverage data found' if rows.empty?
+
+      widths = compute_table_widths(rows)
+      lines = []
+      lines << border_line(widths, '┌', '┬', '┐')
+      lines << header_row(widths)
+      lines << border_line(widths, '├', '┼', '┤')
+      rows.each { |file_data| lines << data_row(file_data, widths) }
+      lines << border_line(widths, '└', '┴', '┘')
+      lines << summary_counts(rows)
+      if rows.any? { |f| f['stale'] }
+        lines <<
+          'Staleness: M = Missing file, T = Timestamp (source newer), L = Line count mismatch'
+      end
+      lines.join("\n")
+    end
+
+    private def load_coverage_data(resultset, staleness, tracked_globs)
+      rs = CovUtil.find_resultset(@root, resultset: resultset)
+      loaded = ResultsetLoader.load(resultset_path: rs)
+      coverage_map = loaded.coverage_map or raise(CoverageDataError, "No 'coverage' key found in resultset file: #{rs}")
+
+      @cov = coverage_map.transform_keys { |k| File.absolute_path(k, @root) }
+      @cov_timestamp = loaded.timestamp
+
+      @checker = StalenessChecker.new(
+        root: @root,
+        resultset: @resultset,
+        mode: staleness,
+        tracked_globs: tracked_globs,
+        timestamp: @cov_timestamp
+      )
+    rescue CovLoupe::Error
+      raise # Re-raise our own errors as-is
+    rescue => e
+      raise ErrorHandler.new.convert_standard_error(e, context: :coverage_loading)
+    end
+
+    private def build_staleness_checker(mode:, tracked_globs:)
+      StalenessChecker.new(
+        root: @root,
+        resultset: @resultset,
+        mode: mode,
+        tracked_globs: tracked_globs,
+        timestamp: @cov_timestamp
+      )
+    end
+
+    private def prepare_rows(rows, sort_order:, check_stale:, tracked_globs:)
+      if rows.nil?
+        all_files(sort_order: sort_order, check_stale: check_stale, tracked_globs: tracked_globs)
+      else
+        rows = sort_rows(rows.dup, sort_order: sort_order)
+        filter_rows_by_globs(rows, tracked_globs)
+      end
+    end
+
+    private def sort_rows(rows, sort_order: :descending)
+      rows.sort do |a, b|
+        pct_cmp = (sort_order == :descending) \
+                    ? (b['percentage'] <=> a['percentage'])
+                    : (a['percentage'] <=> b['percentage'])
+        pct_cmp == 0 ? (a['file'] <=> b['file']) : pct_cmp
+      end
+    end
+
+    private def compute_table_widths(rows)
+      max_file_length = rows.map { |f| f['file'].length }.max.to_i
+      file_width = [max_file_length, 'File'.length].max + 2
+      pct_width = 8
+      max_covered = rows.map { |f| f['covered'].to_s.length }.max
+      max_total = rows.map { |f| f['total'].to_s.length }.max
+      covered_width = [max_covered, 'Covered'.length].max + 2
+      total_width = [max_total, 'Total'.length].max + 2
+      stale_width = 'Stale'.length
+      {
+        file: file_width,
+        pct: pct_width,
+        covered: covered_width,
+        total: total_width,
+        stale: stale_width
+      }
+    end
+
+    private def border_line(widths, left, middle, right)
+      h_line = ->(col_width) { '─' * (col_width + 2) }
+      left +
+        h_line.call(widths[:file]) +
+        middle + h_line.call(widths[:pct]) +
+        middle + h_line.call(widths[:covered]) +
+        middle + h_line.call(widths[:total]) +
+        middle + h_line.call(widths[:stale]) +
+        right
+    end
+
+    private def header_row(widths)
+      format(
+        "│ %-#{widths[:file]}s │ %#{widths[:pct]}s │ %#{widths[:covered]}s │ %#{widths[:total]}s │ %#{widths[:stale]}s │",
+        'File', ' %', 'Covered', 'Total', 'Stale'.center(widths[:stale])
+      )
+    end
+
+    private def data_row(file_data, widths)
+      stale_text_str = file_data['stale'] ? file_data['stale'].to_s : ''
+      format(
+        "│ %-#{widths[:file]}s │ %#{widths[:pct] - 1}.2f%% │ %#{widths[:covered]}d │ %#{widths[:total]}d │ %#{widths[:stale]}s │",
+        file_data['file'],
+        file_data['percentage'],
+        file_data['covered'],
+        file_data['total'],
+        stale_text_str.center(widths[:stale])
+      )
+    end
+
+    private def summary_counts(rows)
+      total = rows.length
+      stale_count = rows.count { |f| f['stale'] }
+      ok_count = total - stale_count
+      "Files: total #{total}, ok #{ok_count}, stale #{stale_count}"
+    end
+
+    # Filters coverage rows to only include files matching the given glob patterns.
+    #
+    # @param rows [Array<Hash>] coverage rows with 'file' keys containing absolute paths
+    # @param tracked_globs [Array<String>, String, nil] glob patterns to match against
+    # @return [Array<Hash>] rows whose files match at least one pattern (or all rows if no patterns)
+    private def filter_rows_by_globs(rows, tracked_globs)
+      patterns = Array(tracked_globs).compact.map(&:to_s).reject(&:empty?)
+      return rows if patterns.empty?
+
+      absolute_patterns = patterns.map { |p| absolutize_pattern(p) }
+      rows.select { |row| matches_any_pattern?(row['file'], absolute_patterns) }
+    end
+
+    # Converts a relative pattern to absolute by joining with root.
+    # Absolute patterns are returned unchanged.
+    #
+    # @param pattern [String] glob pattern (e.g., "lib/**/*.rb")
+    # @return [String] absolute pattern
+    private def absolutize_pattern(pattern)
+      absolute_pattern?(pattern) ? pattern : File.join(@root, pattern)
+    end
+
+    # Checks if a pattern is absolute, handling both Unix and Windows-style paths.
+    # On Unix, Pathname won't recognize "C:/" as absolute, so we check explicitly.
+    #
+    # @param pattern [String] glob pattern
+    # @return [Boolean] true if pattern is absolute
+    private def absolute_pattern?(pattern)
+      Pathname.new(pattern).absolute? || pattern.match?(/\A[A-Za-z]:/)
+    end
+
+    # Tests if a file path matches any of the given absolute glob patterns.
+    # Uses File.fnmatch? for pure string matching without filesystem access,
+    # which is faster and works for paths that may no longer exist on disk.
+    #
+    # @param abs_path [String] absolute file path to test
+    # @param patterns [Array<String>] absolute glob patterns
+    # @return [Boolean] true if the path matches at least one pattern
+    private def matches_any_pattern?(abs_path, patterns)
+      flags = File::FNM_PATHNAME | File::FNM_EXTGLOB
+      patterns.any? { |pattern| File.fnmatch?(pattern, abs_path, flags) }
+    end
+
+    # Retrieves coverage data for a file path.
+    # Converts the path to absolute form and performs staleness checking if enabled.
+    #
+    # @param path [String] relative or absolute file path
+    # @return [Array(String, Array)] tuple of [absolute_path, coverage_lines]
+    # @raise [FileError] if no coverage data exists for the file
+    # @raise [FileNotFoundError] if the file does not exist
+    # @raise [CoverageDataStaleError] if staleness checking is enabled and data is stale
+    private def coverage_data_for(path)
+      file_abs = File.absolute_path(path, @root)
+      begin
+        coverage_lines = CovUtil.lookup_lines(@cov, file_abs)
+      rescue RuntimeError
+        raise FileError, "No coverage data found for file: #{path}"
+      end
+      @checker.check_file!(file_abs, coverage_lines) unless @checker.off?
+      if coverage_lines.nil?
+        raise FileError, "No coverage data found for file: #{path}"
+      end
+
+      [file_abs, coverage_lines]
+    rescue Errno::ENOENT
+      raise FileNotFoundError, "File not found: #{path}"
+    end
+
+    private def totals_from_rows(rows)
+      covered = rows.sum { |row| row['covered'].to_i }
+      total = rows.sum { |row| row['total'].to_i }
+      uncovered = total - covered
+      percentage = total.zero? ? 100.0 : ((covered.to_f * 100.0 / total) * 100).round / 100.0
+      stale_count = rows.count { |row| row['stale'] }
+      files_total = rows.length
+
+      {
+        'lines' => {
+          'covered' => covered,
+          'uncovered' => uncovered,
+          'total' => total
+        },
+        'percentage' => percentage,
+        'files' => {
+          'total' => files_total,
+          'ok' => files_total - stale_count,
+          'stale' => stale_count
+        }
+      }
+    end
+  end
+end

data/lib/cov_loupe/option_normalizers.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Shared normalization logic for CLI options.
+  # Provides both strict (raise on invalid) and lenient (default on invalid) modes.
+  module OptionNormalizers
+    SORT_ORDER_MAP = {
+      'a' => :ascending,
+      'ascending' => :ascending,
+      'd' => :descending,
+      'descending' => :descending
+    }.freeze
+
+    SOURCE_MODE_MAP = {
+      'f' => :full,
+      'full' => :full,
+      'u' => :uncovered,
+      'uncovered' => :uncovered
+    }.freeze
+
+    STALENESS_MAP = {
+      'o' => :off,
+      'off' => :off,
+      'e' => :error,
+      'error' => :error
+    }.freeze
+
+    ERROR_MODE_MAP = {
+      'off' => :off,
+      'o' => :off,
+      'log' => :log,
+      'l' => :log,
+      'debug' => :debug,
+      'd' => :debug
+    }.freeze
+
+    FORMAT_MAP = {
+      't' => :table,
+      'table' => :table,
+      'j' => :json,
+      'json' => :json,
+      'J' => :pretty_json,
+      'pretty_json' => :pretty_json,
+      'pretty-json' => :pretty_json,
+      'y' => :yaml,
+      'yaml' => :yaml,
+      'a' => :awesome_print,
+      'awesome_print' => :awesome_print,
+      'ap' => :awesome_print
+    }.freeze
+
+    module_function def normalize_sort_order(value, strict: true)
+      normalized = SORT_ORDER_MAP[value.to_s.downcase]
+      return normalized if normalized
+      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
+
+      nil
+    end
+
+    # Normalize source mode value.
+    # @param value [String, Symbol, nil] The value to normalize
+    # @param strict [Boolean] If true, raises on invalid value; if false, returns nil
+    # @return [Symbol, nil] The normalized symbol or nil if invalid and not strict
+    # @raise [OptionParser::InvalidArgument] If strict and value is invalid
+    module_function def normalize_source_mode(value, strict: true)
+      normalized = SOURCE_MODE_MAP[value.to_s.downcase]
+      return normalized if normalized
+      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
+
+      nil
+    end
+
+    # Normalize stale mode value.
+    # @param value [String, Symbol] The value to normalize
+    # @param strict [Boolean] If true, raises on invalid value; if false, returns nil
+    # @return [Symbol, nil] The normalized symbol or nil if invalid and not strict
+    # @raise [OptionParser::InvalidArgument] If strict and value is invalid
+    module_function def normalize_staleness(value, strict: true)
+      normalized = STALENESS_MAP[value.to_s.downcase]
+      return normalized if normalized
+      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
+
+      nil
+    end
+
+    # Normalize error mode value.
+    # @param value [String, Symbol, nil] The value to normalize
+    # @param strict [Boolean] If true, raises on invalid value; if false, returns default
+    # @param default [Symbol] The default value to return if invalid and not strict
+    # @return [Symbol] The normalized symbol or default if invalid and not strict
+    # @raise [OptionParser::InvalidArgument] If strict and value is invalid
+    module_function def normalize_error_mode(value, strict: true, default: :log)
+      normalized = ERROR_MODE_MAP[value.to_s.downcase]
+      return normalized if normalized
+      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
+
+      default
+    end
+
+    # Normalize format value.
+    # @param value [String, Symbol] The value to normalize
+    # @param strict [Boolean] If true, raises on invalid value; if false, returns nil
+    # @return [Symbol, nil] The normalized symbol or nil if invalid and not strict
+    # @raise [OptionParser::InvalidArgument] If strict and value is invalid
+    module_function def normalize_format(value, strict: true)
+      normalized = FORMAT_MAP[value.to_s.downcase]
+      return normalized if normalized
+      raise OptionParser::InvalidArgument, "invalid argument: #{value}" if strict
+
+      nil
+    end
+  end
+end

data/lib/cov_loupe/option_parser_builder.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative 'option_normalizers'
+require_relative 'version'
+
+module CovLoupe
+  class OptionParserBuilder
+    HORIZONTAL_RULE = '-' * 79
+    SUBCOMMANDS = %w[list summary raw uncovered detailed totals validate version].freeze
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def build_option_parser
+      require 'optparse'
+      OptionParser.new do |parser|
+        configure_banner(parser)
+        define_subcommands_help(parser)
+        define_options(parser)
+        define_examples(parser)
+      end
+    end
+
+    private def configure_banner(parser)
+      parser.banner = <<~BANNER
+        #{HORIZONTAL_RULE}
+        Usage:      cov-loupe [options] [subcommand] [args]  (default subcommand: list)
+        Repository: https://github.com/keithrbennett/cov-loupe
+        Version:    #{CovLoupe::VERSION}
+        #{HORIZONTAL_RULE}
+
+        BANNER
+    end
+
+    private def define_subcommands_help(parser)
+      parser.separator <<~SUBCOMMANDS
+        Subcommands:
+          detailed <path>          Show per-line rows with hits/covered
+          list                     Show files coverage (default: table, or use --format)
+          raw <path>               Show the SimpleCov 'lines' array
+          summary <path>           Show covered/total/% for a file
+          totals                   Show aggregated line totals and average %
+          uncovered <path>         Show uncovered lines and a summary
+          validate <file>          Evaluate coverage policy from file (exit 0=pass, 1=fail, 2=error)
+          validate -e <code>       Evaluate coverage policy from code string
+          version                  Show version information
+
+        SUBCOMMANDS
+    end
+
+    private def define_options(parser)
+      parser.separator 'Options:'
+      parser.on('-r', '--resultset PATH', String,
+        'Path or directory that contains .resultset.json (default: coverage/.resultset.json)') \
+      do |value|
+        config.resultset = value
+      end
+      parser.on('-R', '--root PATH', String, 'Project root (default: .)') do |value|
+        config.root = value
+      end
+      parser.on(
+        '-f', '--format FORMAT', String,
+        'Output format: t[able]|j[son]|pretty-json|y[aml]|a[wesome-print] (default: table)'
+      ) do |value|
+        config.format = normalize_format(value)
+      end
+      parser.on('-o', '--sort-order ORDER', String,
+        'Sort order for list: a[scending]|d[escending] (default descending)') do |value|
+        config.sort_order = normalize_sort_order(value)
+      end
+      parser.on('-s', '--source MODE', String,
+        'Source display: f[ull]|u[ncovered]') do |value|
+        config.source_mode = normalize_source_mode(value)
+      end
+      parser.on('-c', '--context-lines N', Integer,
+        'Context lines around uncovered lines (non-negative, default: 2)') do |value|
+        config.source_context = value
+      end
+      parser.on('--color', 'Enable ANSI colors for source output') { config.color = true }
+      parser.on('--no-color', 'Disable ANSI colors') { config.color = false }
+      parser.on('-S', '--staleness MODE', String,
+        'Staleness detection: o[ff]|e[rror] (default off)') do |value|
+        config.staleness = normalize_staleness(value)
+      end
+      parser.on('-g', '--tracked-globs x,y,z', Array,
+        'Globs for filtering files (list/totals subcommands)') do |value|
+        config.tracked_globs = value
+      end
+      parser.on('-h', '--help', 'Show help') do
+        puts parser
+        gem_root = File.expand_path('../..', __dir__)
+        puts "\nFor more detailed help, consult README.md and docs/user/**/*.md"
+        puts "in the installed gem at: #{gem_root}"
+        exit 0
+      end
+      parser.on('-l', '--log-file PATH', String,
+        'Log file path (default ./cov_loupe.log, use stdout/stderr for streams)') do |value|
+        config.log_file = value
+      end
+      parser.on('--error-mode MODE', String,
+        'Error handling mode: o[ff]|l[og]|d[ebug] (default log). ' \
+        'off (silent), log (log errors to file), debug (verbose with backtraces)') do |value|
+        config.error_mode = normalize_error_mode(value)
+      end
+      parser.on('--force-cli', 'Force CLI mode (useful in scripts where auto-detection fails)') do
+        # This flag is mainly for mode detection - no action needed here
+      end
+      parser.on('-v', '--version', 'Show version information and exit') do
+        config.show_version = true
+      end
+    end
+
+    private def define_examples(parser)
+      parser.separator <<~EXAMPLES
+
+        Examples:
+          cov-loupe --resultset coverage list
+          cov-loupe --format json --resultset coverage summary lib/foo.rb
+          cov-loupe --source uncovered --context-lines 2 uncovered lib/foo.rb
+          cov-loupe totals --format json
+        EXAMPLES
+    end
+
+    private def normalize_sort_order(value)
+      OptionNormalizers.normalize_sort_order(value, strict: true)
+    end
+
+    private def normalize_source_mode(value)
+      OptionNormalizers.normalize_source_mode(value, strict: true)
+    end
+
+    private def normalize_staleness(value)
+      OptionNormalizers.normalize_staleness(value, strict: true)
+    end
+
+    private def normalize_error_mode(value)
+      OptionNormalizers.normalize_error_mode(value, strict: true)
+    end
+
+    private def normalize_format(value)
+      OptionNormalizers.normalize_format(value, strict: true)
+    end
+  end
+end