cov-loupe 3.0.0

data/lib/cov_loupe/resolvers/resultset_path_resolver.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module CovLoupe
+  module Resolvers
+    class ResultsetPathResolver
+      DEFAULT_CANDIDATES = [
+        '.resultset.json',
+        'coverage/.resultset.json',
+        'tmp/.resultset.json'
+      ].freeze
+
+      def initialize(root: Dir.pwd, candidates: DEFAULT_CANDIDATES)
+        @root = root
+        @candidates = candidates
+      end
+
+      def find_resultset(resultset: nil)
+        if resultset && !resultset.empty?
+          path = normalize_resultset_path(resultset)
+          if (resolved = resolve_candidate(path, strict: true))
+            return resolved
+          end
+        end
+
+        resolve_fallback or raise_not_found_error
+      end
+
+      private def resolve_candidate(path, strict:)
+        return path if File.file?(path)
+        return resolve_directory(path) if File.directory?(path)
+
+        raise_not_found_error_for_file(path) if strict
+        nil
+      end
+
+      private def resolve_directory(path)
+        candidate = File.join(path, '.resultset.json')
+        return candidate if File.file?(candidate)
+
+        raise "No .resultset.json found in directory: #{path}"
+      end
+
+      private def raise_not_found_error_for_file(path)
+        raise "Specified resultset not found: #{path}"
+      end
+
+      private def resolve_fallback
+        @candidates
+          .map { |p| File.absolute_path(p, @root) }
+          .find { |p| File.file?(p) }
+      end
+
+      private def normalize_resultset_path(resultset)
+        candidate = Pathname.new(resultset)
+        return candidate.cleanpath.to_s if candidate.absolute?
+
+        expanded = File.expand_path(resultset, Dir.pwd)
+        return expanded if within_root?(expanded)
+
+        File.absolute_path(resultset, @root)
+      end
+
+      private def within_root?(path)
+        normalized_root = Pathname.new(@root).cleanpath.to_s
+        root_with_sep = normalized_root.end_with?(File::SEPARATOR) ? normalized_root : "#{normalized_root}#{File::SEPARATOR}"
+        path == normalized_root || path.start_with?(root_with_sep)
+      end
+
+      private def raise_not_found_error
+        raise "Could not find .resultset.json under #{@root.inspect}; run tests or set --resultset option"
+      end
+    end
+  end
+end

data/lib/cov_loupe/resultset_loader.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+require_relative 'errors'
+require_relative 'util'
+
+module CovLoupe
+  class ResultsetLoader
+    Result = Struct.new(:coverage_map, :timestamp, :suite_names, keyword_init: true)
+    SuiteEntry = Struct.new(:name, :coverage, :timestamp, keyword_init: true)
+
+    class << self
+      def load(resultset_path:)
+        raw = JSON.load_file(resultset_path)
+
+
+        suites = extract_suite_entries(raw, resultset_path)
+        raise CoverageDataError, "No test suite with coverage data found in resultset file: #{resultset_path}" if suites.empty?
+
+        coverage_map = build_coverage_map(suites, resultset_path)
+        Result.new(
+          coverage_map: coverage_map,
+          timestamp: compute_combined_timestamp(suites),
+          suite_names: suites.map(&:name)
+        )
+      end
+
+      private def extract_suite_entries(raw, resultset_path)
+        raw
+          .select { |_, data| data.is_a?(Hash) && data.key?('coverage') && !data['coverage'].nil? }
+          .map do |name, data|
+            SuiteEntry.new(
+              name: name.to_s,
+              coverage: normalize_suite_coverage(data['coverage'], suite_name: name,
+                resultset_path: resultset_path),
+              timestamp: normalize_coverage_timestamp(data['timestamp'], data['created_at'])
+            )
+          end
+      end
+
+      private def build_coverage_map(suites, resultset_path)
+        return suites.first&.coverage if suites.length == 1
+
+        merge_suite_coverages(suites, resultset_path)
+      end
+
+      private def normalize_suite_coverage(coverage, suite_name:, resultset_path:)
+        unless coverage.is_a?(Hash)
+          raise CoverageDataError, "Invalid coverage data structure for suite #{suite_name.inspect} in resultset file: #{resultset_path}"
+        end
+
+        needs_adaptation = coverage.values.any? { |value| value.is_a?(Array) }
+        return coverage unless needs_adaptation
+
+        coverage.transform_values do |value|
+          value.is_a?(Array) ? { 'lines' => value } : value
+        end
+      end
+
+      private def merge_suite_coverages(suites, resultset_path)
+        require_simplecov_for_merge!(resultset_path)
+        log_duplicate_suite_names(suites)
+
+        suites.reduce(nil) do |memo, suite|
+          coverage = suite.coverage
+          memo ?
+            SimpleCov::Combine.combine(SimpleCov::Combine::ResultsCombiner, memo, coverage) :
+            coverage
+        end
+      end
+
+      private def require_simplecov_for_merge!(resultset_path)
+        require 'simplecov'
+      rescue LoadError
+        raise CoverageDataError, "Multiple coverage suites detected in #{resultset_path}, but the simplecov gem could not be loaded. Install simplecov to enable suite merging."
+      end
+
+      private def log_duplicate_suite_names(suites)
+        grouped = suites.group_by(&:name)
+        duplicates = grouped.select { |_, entries| entries.length > 1 }.keys
+        return if duplicates.empty?
+
+        message = "Merging duplicate coverage suites for #{duplicates.join(', ')}"
+        CovUtil.safe_log(message)
+      end
+
+      private def compute_combined_timestamp(suites)
+        suites.map(&:timestamp).compact.max.to_i
+      end
+
+      private def normalize_coverage_timestamp(timestamp_value, created_at_value)
+        raw = timestamp_value.nil? ? created_at_value : timestamp_value
+        return 0 if raw.nil?
+
+        case raw
+        when Integer
+          raw
+        when Float, Time
+          raw.to_i
+        when String
+          normalize_string_timestamp(raw)
+        else
+          log_timestamp_warning(raw)
+          0
+        end
+      rescue => e
+        log_timestamp_warning(raw, e)
+        0
+      end
+
+      private def normalize_string_timestamp(value)
+        str = value.strip
+        return 0 if str.empty?
+
+        if str.match?(/\A-?\d+(\.\d+)?\z/)
+          str.to_f.to_i
+        else
+          Time.parse(str).to_i
+        end
+      end
+
+      private def log_timestamp_warning(raw_value, error = nil)
+        message = "Coverage resultset timestamp could not be parsed: #{raw_value.inspect}"
+        message = "#{message} (#{error.message})" if error
+        CovUtil.safe_log(message)
+      end
+    end
+  end
+end

data/lib/cov_loupe/staleness_checker.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'pathname'
+require_relative 'errors'
+require_relative 'util'
+
+module CovLoupe
+  # Lightweight service object to check staleness of coverage vs. sources
+  class StalenessChecker
+    MODES = [:off, :error].freeze
+
+    def initialize(root:, resultset:, mode: :off, tracked_globs: nil, timestamp: nil)
+      @root = File.absolute_path(root || '.')
+      @resultset = resultset
+      @mode = (mode || :off).to_sym
+      @tracked_globs = tracked_globs
+      @cov_timestamp = timestamp
+      @resultset_path = nil
+    end
+
+    def off?
+      @mode == :off
+    end
+
+    # Raise CoverageDataStaleError if stale (only in error mode)
+    def check_file!(file_abs, coverage_lines)
+      return if off?
+
+      d = compute_file_staleness_details(file_abs, coverage_lines)
+      # For single-file checks, missing files with recorded coverage count as stale
+      # via length mismatch; project-level checks also handle deleted files explicitly.
+      if d[:newer] || d[:len_mismatch]
+        raise CoverageDataStaleError.new(
+          nil,
+          nil,
+          file_path: rel(file_abs),
+          file_mtime: d[:file_mtime],
+          cov_timestamp: d[:coverage_timestamp],
+          src_len: d[:src_len],
+          cov_len: d[:cov_len],
+          resultset_path: resultset_path
+        )
+      end
+    end
+
+    # Compute whether a specific file appears stale relative to coverage.
+    # Ignores mode and never raises; returns true when:
+    # - the file is missing/deleted, or
+    # - the file mtime is newer than the coverage timestamp, or
+    # - the source line count differs from the coverage lines array length (when present).
+    def stale_for_file?(file_abs, coverage_lines)
+      d = compute_file_staleness_details(file_abs, coverage_lines)
+      return 'M' unless d[:exists]
+      return 'T' if d[:newer]
+      return 'L' if d[:len_mismatch]
+
+      false
+    end
+
+    # Raise CoverageDataProjectStaleError if any covered file is newer or if
+    # tracked files are missing from coverage, or coverage includes deleted files.
+    def check_project!(coverage_map)
+      return if off?
+
+      ts = coverage_timestamp
+      coverage_files = coverage_map.keys
+
+      newer, deleted = compute_newer_and_deleted_files(coverage_files, ts)
+      missing = compute_missing_files(coverage_files)
+
+      return if newer.empty? && missing.empty? && deleted.empty?
+
+      raise CoverageDataProjectStaleError.new(
+        nil,
+        nil,
+        cov_timestamp: ts,
+        newer_files: newer,
+        missing_files: missing,
+        deleted_files: deleted,
+        resultset_path: resultset_path
+      )
+    end
+
+    private def compute_newer_and_deleted_files(coverage_files, timestamp)
+      existing, deleted_abs = coverage_files.partition { |abs| File.file?(abs) }
+
+      newer = existing
+        .select { |abs| File.mtime(abs).to_i > timestamp.to_i }
+        .map { |abs| rel(abs) }
+      deleted = deleted_abs.map { |abs| rel(abs) }
+
+      [newer, deleted]
+    end
+
+    # Identifies tracked files that are missing from coverage.
+    # Returns array of relative paths for files matched by tracked_globs but not in coverage.
+    private def compute_missing_files(coverage_files)
+      return [] unless @tracked_globs && Array(@tracked_globs).any?
+
+      patterns = Array(@tracked_globs).map { |g| File.absolute_path(g, @root) }
+      tracked = patterns
+        .flat_map { |p| Dir.glob(p, File::FNM_EXTGLOB | File::FNM_PATHNAME) }
+        .select { |p| File.file?(p) }
+
+      covered_set = coverage_files.to_set
+      tracked.reject { |abs| covered_set.include?(abs) }.map { |abs| rel(abs) }
+    end
+
+    private def coverage_timestamp
+      @cov_timestamp || 0
+    end
+
+    private def resultset_path
+      @resultset_path ||= CovUtil.find_resultset(@root, resultset: @resultset)
+    rescue
+      nil
+    end
+
+    private def safe_count_lines(path)
+      return 0 unless File.file?(path)
+
+      File.foreach(path).count
+    rescue
+      0
+    end
+
+    private def missing_trailing_newline?(path)
+      return false unless File.file?(path)
+
+      File.open(path, 'rb') do |f|
+        size = f.size
+        return false if size.zero?
+
+        f.seek(-1, IO::SEEK_END)
+        f.getbyte != 0x0A
+      end
+    rescue
+      false
+    end
+
+    private def rel(path)
+      # Handle relative vs absolute path mismatches that cause ArgumentError
+      Pathname.new(path).relative_path_from(Pathname.new(@root)).to_s
+    rescue ArgumentError
+      # Path is outside the project root or has a different prefix type, fall back to absolute path
+      path.to_s
+    end
+
+    # Centralized computation of staleness-related details for a single file.
+    # Returns a Hash with keys:
+    #  :exists, :file_mtime, :coverage_timestamp, :cov_len, :src_len, :newer, :len_mismatch
+    private def compute_file_staleness_details(file_abs, coverage_lines)
+      coverage_ts = coverage_timestamp
+
+      exists = File.file?(file_abs)
+      file_mtime = exists ? File.mtime(file_abs) : nil
+
+      cov_len = coverage_lines.respond_to?(:length) ? coverage_lines.length : 0
+      src_len = exists ? safe_count_lines(file_abs) : 0
+
+      # Adjust source line count to handle edge cases with missing trailing newlines
+      adjusted_src_len = adjust_line_count_for_missing_newline(
+        file_abs: file_abs,
+        exists: exists,
+        cov_len: cov_len,
+        src_len: src_len
+      )
+
+      # Check if the source file has been modified since coverage was generated
+      len_mismatch = length_mismatch?(cov_len, adjusted_src_len)
+      newer = check_file_newer_than_coverage(file_mtime, coverage_ts, len_mismatch)
+
+      {
+        exists: exists,
+        file_mtime: file_mtime,
+        coverage_timestamp: coverage_ts,
+        cov_len: cov_len,
+        src_len: src_len,
+        newer: newer,
+        len_mismatch: len_mismatch
+      }
+    end
+
+    # Adjusts the source line count to account for files missing trailing newlines.
+    #
+    # Why this edge case exists:
+    # - File.foreach counts lines by separator (typically \n)
+    # - For a file with no trailing newline, File.foreach still counts all lines correctly
+    # - However, some editors or file operations may report one extra line when checking
+    #   if the file doesn't end with a newline
+    # - SimpleCov's coverage array length matches the logical line count (excluding trailing newline)
+    # - If src_len is exactly one more than cov_len AND the file is missing a trailing newline,
+    #   we adjust src_len down by 1 to match SimpleCov's convention
+    #
+    # Example: A file with "line1\nline2\nline3" (no final \n)
+    # - File.foreach counts: 3 lines
+    # - SimpleCov coverage array length: 3
+    # - No adjustment needed
+    #
+    # However, in certain edge cases where the file system or parsing reports an extra line:
+    # - Reported line count: 4
+    # - SimpleCov coverage array length: 3
+    # - Missing trailing newline: true
+    # - Adjustment: 4 - 1 = 3 (now matches)
+    private def adjust_line_count_for_missing_newline(file_abs:, exists:, cov_len:, src_len:)
+      # Only adjust if:
+      # 1. File exists (can't check newlines for missing files)
+      # 2. Coverage data is present (cov_len > 0)
+      # 3. Source has exactly one more line than coverage
+      # 4. File is missing a trailing newline
+      needs_adjusting =
+        exists && cov_len.positive? && src_len == cov_len + 1 && missing_trailing_newline?(file_abs)
+      needs_adjusting ? src_len - 1 : src_len
+    end
+
+    # Checks if the source line count differs from the coverage line count.
+    #
+    # Why this check exists:
+    # - When a file is modified after coverage is generated, the line count often changes
+    # - A mismatch indicates the coverage data is stale and no longer represents the current file
+    # - We only flag as mismatch when coverage data exists (cov_len > 0)
+    #
+    # Note: Empty coverage (cov_len == 0) is not considered a mismatch, as it may represent
+    # files that were never executed or files that are legitimately empty.
+    private def length_mismatch?(cov_len, adjusted_src_len)
+      cov_len.positive? && adjusted_src_len != cov_len
+    end
+
+    # Determines if a file has been modified more recently than the coverage timestamp.
+    #
+    # Why this check exists:
+    # - Files modified after coverage generation may have behavioral changes not captured
+    # - However, if there's already a length mismatch, we prioritize that as the staleness indicator
+    # - This prevents double-flagging: if lines changed, the file is already stale (length mismatch)
+    #
+    # The logic: newer &&= !len_mismatch means:
+    # - If len_mismatch is true, set newer to false (length mismatch takes precedence)
+    # - This way, staleness is categorized as either 'T' (time-based) OR 'L' (length-based), not both
+    private def check_file_newer_than_coverage(file_mtime, coverage_ts, len_mismatch)
+      newer = !!(file_mtime && file_mtime.to_i > coverage_ts.to_i)
+      # If there's a length mismatch, don't also flag as "newer" - the mismatch is more specific
+      newer &&= !len_mismatch
+      newer
+    end
+  end
+end

data/lib/cov_loupe/table_formatter.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # General-purpose table formatter with box-drawing characters
+  # Used by commands to create consistent formatted output
+  class TableFormatter
+    # Format data as a table with box-drawing characters
+    # @param headers [Array<String>] Column headers
+    # @param rows [Array<Array>] Data rows (each row is an array of cell values)
+    # @param alignments [Array<Symbol>] Column alignments (:left, :right, :center)
+    # @return [String] Formatted table
+    def self.format(headers:, rows:, alignments: nil)
+      return 'No data to display' if rows.empty?
+
+      alignments ||= [:left] * headers.size
+      all_rows = [headers] + rows.map { |row| row.map(&:to_s) }
+
+      # Calculate column widths
+      widths = headers.size.times.map do |col|
+        all_rows.map { |row| row[col].to_s.length }.max
+      end
+
+      lines = []
+      lines << border_line(widths, '┌', '┬', '┐')
+      lines << data_row(headers, widths, alignments)
+      lines << border_line(widths, '├', '┼', '┤')
+      rows.each { |row| lines << data_row(row, widths, alignments) }
+      lines << border_line(widths, '└', '┴', '┘')
+
+      lines.join("\n")
+    end
+
+    # Format a single key-value table (vertical layout)
+    # @param data [Hash] Key-value pairs
+    # @return [String] Formatted table
+    def self.format_vertical(data)
+      rows = data.map { |k, v| [k.to_s, v.to_s] }
+      format(headers: ['Key', 'Value'], rows: rows, alignments: [:left, :left])
+    end
+
+    private_class_method def self.border_line(widths, left, mid, right)
+      segments = widths.map { |w| '─' * (w + 2) }
+      left + segments.join(mid) + right
+    end
+
+    private_class_method def self.data_row(cells, widths, alignments)
+      formatted = cells.each_with_index.map do |cell, i|
+        align_cell(cell.to_s, widths[i], alignments[i])
+      end
+      "│ #{formatted.join(' │ ')} │"
+    end
+
+    private_class_method def self.align_cell(content, width, alignment)
+      case alignment
+      when :right
+        content.rjust(width)
+      when :center
+        content.center(width)
+      else # :left
+        content.ljust(width)
+      end
+    end
+  end
+end

data/lib/cov_loupe/tools/all_files_coverage_tool.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative '../model'
+require_relative '../base_tool'
+require_relative '../presenters/project_coverage_presenter'
+
+module CovLoupe
+  module Tools
+    class AllFilesCoverageTool < BaseTool
+      description <<~DESC
+        Use this when the user wants coverage percentages for every tracked file in the project.
+        Do not use this for single-file stats; prefer coverage.summary or coverage.uncovered_lines for that.
+        Inputs: optional project root, alternate .resultset path, sort order, staleness mode, and tracked_globs to alert on new files.
+        Output: JSON {"files": [{"file","covered","total","percentage","stale"}, ...], "counts": {"total", "ok", "stale"}} sorted as requested. "stale" is a string ('M', 'T', 'L') or false.
+        Examples: "List files with the lowest coverage"; "Show repo coverage sorted descending".
+      DESC
+      input_schema(**coverage_schema(
+        additional_properties: {
+          sort_order: {
+            type: 'string',
+            description: 'Sort order for coverage percentages.' \
+                         "'ascending' highlights the riskiest files first.",
+            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('AllFilesCoverageTool', 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)
+            presenter = Presenters::ProjectCoveragePresenter.new(
+              model: model,
+              sort_order: sort_order_sym,
+              check_stale: (staleness_sym == :error),
+              tracked_globs: tracked_globs
+            )
+            respond_json(presenter.relativized_payload, name: 'all_files_coverage.json')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/tools/coverage_detailed_tool.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+require_relative '../model'
+require_relative '../presenters/coverage_detailed_presenter'
+
+module CovLoupe
+  module Tools
+    class CoverageDetailedTool < BaseTool
+      description <<~DESC
+        Use this when the user needs per-line coverage data for a single file.
+        Do not use this for high-level counts; coverage.summary is cheaper for aggregate numbers.
+        Inputs: file path (required) plus optional root/resultset/staleness mode inherited from BaseTool.
+        Output: JSON object with "file", "lines" => [{"line": 12, "hits": 0, "covered": false}], plus "summary" with totals and "stale" status.
+        Example: "Show detailed coverage for lib/cov_loupe/model.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('CoverageDetailedTool', error_mode: error_mode) do
+            model = CoverageModel.new(
+              root: root,
+              resultset: resultset,
+              staleness: staleness.to_sym
+            )
+            presenter = Presenters::CoverageDetailedPresenter.new(model: model, path: path)
+            respond_json(presenter.relativized_payload, name: 'coverage_detailed.json',
+              pretty: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/tools/coverage_raw_tool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+require_relative '../model'
+require_relative '../presenters/coverage_raw_presenter'
+
+module CovLoupe
+  module Tools
+    class CoverageRawTool < BaseTool
+      description <<~DESC
+        Use this when you need the raw SimpleCov `lines` array for a file exactly as stored on disk.
+        Do not use this for human-friendly explanations; choose coverage.detailed or coverage.summary instead.
+        Inputs: file path (required) plus optional root/resultset/staleness mode inherited from BaseTool.
+        Output: JSON object with "file" and "lines" (array of integers/nulls) mirroring SimpleCov's native structure, plus "stale" status.
+        Example: "Fetch the raw coverage array for spec/support/foo_helper.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('CoverageRawTool', error_mode: error_mode) do
+            model = CoverageModel.new(
+              root: root,
+              resultset: resultset,
+              staleness: staleness.to_sym
+            )
+            presenter = Presenters::CoverageRawPresenter.new(model: model, path: path)
+            respond_json(presenter.relativized_payload, name: 'coverage_raw.json', pretty: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cov_loupe/tools/coverage_summary_tool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative '../base_tool'
+require_relative '../model'
+require_relative '../presenters/coverage_summary_presenter'
+
+module CovLoupe
+  module Tools
+    class CoverageSummaryTool < BaseTool
+      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/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/cov_loupe/tools/all_files_coverage_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('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
+  end
+end