cov-loupe 3.0.0 → 4.0.0.pre

data/lib/cov_loupe/scripts/pre_release_check.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'time'
+require_relative 'command_execution'
+
+module CovLoupe
+  module Scripts
+    class PreReleaseCheck
+      include CommandExecution
+
+      ROOT = Pathname.new(__dir__).join('../../..').expand_path
+
+      def call
+        Dir.chdir(ROOT) do
+          verify_git_clean!
+          puts '✓ Git working tree is clean'
+
+          verify_branch!
+          puts '✓ On main branch'
+
+          verify_sync!
+          puts '✓ Local branch is in sync with origin/main'
+
+          verify_ci_passed!
+          puts '✓ GitHub Actions CI passed'
+
+          @version = fetch_version
+          @tag_name = "v#{@version}"
+          puts "✓ Preparing release for version #{@version}"
+
+          verify_release_notes!
+          puts "✓ Release notes found for #{@tag_name}"
+
+          verify_tag_new!
+          puts "✓ Tag #{@tag_name} does not yet exist"
+
+          build_gem!
+          puts '✓ Gem built successfully'
+
+          puts "\nBuild complete! To finish the release, run:"
+          puts
+          puts "  git tag -a #{@tag_name} -m 'Version #{@version}'"
+          puts '  git push origin main --follow-tags'
+          puts "  gem push #{@gem_file.basename}"
+          puts
+          puts 'Then draft the GitHub release via the web UI.'
+        end
+      end
+
+      private def verify_git_clean!
+        status = run_command(%w[git status --porcelain], print_output: false)
+        unless status.strip.empty?
+          abort_with('Uncommitted changes present. Commit or stash before releasing.')
+        end
+      end
+
+      private def verify_branch!
+        current_branch = run_command(%w[git rev-parse --abbrev-ref HEAD], print_output: false).strip
+        abort_with('Releases must be cut from the main branch.') unless current_branch == 'main'
+      end
+
+      private def verify_sync!
+        run_command(%w[git fetch origin --tags], print_output: true)
+        local = run_command(%w[git rev-parse HEAD], print_output: false).strip
+        remote = run_command(%w[git rev-parse origin/main], print_output: false).strip
+        return if local == remote
+
+        base = run_command(%w[git merge-base HEAD origin/main], print_output: false).strip
+
+        if base == local
+          abort_with('Local main is behind origin. Pull before releasing.')
+        elsif base == remote
+          abort_with('Local main is ahead of origin. Push before releasing.')
+        else
+          abort_with('Local main has diverged from origin. Reconcile before releasing.')
+        end
+      end
+
+      private def verify_ci_passed!
+        # Capture current HEAD SHA and timestamp before triggering
+        head_sha = run_command(%w[git rev-parse HEAD], print_output: false).strip
+        trigger_time = Time.now
+
+        # Trigger the workflow
+        run_command(%w[gh workflow run test.yml --ref main], print_output: true)
+        puts 'Waiting for workflow to initialize...'
+
+        # Poll for the specific workflow run matching HEAD SHA and created after trigger time
+        run_id = find_triggered_run_id(head_sha, trigger_time)
+        abort_with('Failed to retrieve the CI run ID.') if run_id.empty?
+
+        puts "Monitoring CI build (Run ID: #{run_id})..."
+        run_command(['gh', 'run', 'watch', run_id, '--exit-status'], print_output: true)
+      end
+
+      private def find_triggered_run_id(head_sha, trigger_time)
+        max_attempts = 30
+        poll_interval = 2
+        attempts = 0
+
+        while attempts < max_attempts
+          sleep poll_interval
+          attempts += 1
+
+          # Get runs with databaseId, headSha, and createdAt fields
+          runs_json = run_command(
+            %w[gh run list --workflow test.yml --branch main --limit 10] \
+              + %w[--json databaseId,headSha,createdAt],
+            print_output: false
+          ).strip
+
+          next if runs_json.empty?
+
+          begin
+            runs = JSON.parse(runs_json)
+            # Find the newest run matching our HEAD SHA and created after trigger time
+            matching_run = runs.find do |run|
+              run['headSha'] == head_sha &&
+                Time.parse(run['createdAt']) >= trigger_time
+            end
+
+            return matching_run['databaseId'].to_s if matching_run
+          rescue JSON::ParserError => e
+            abort_with("Failed to parse GitHub API response: #{e.message}")
+          end
+        end
+
+        abort_with("Timed out waiting for workflow run to appear for HEAD SHA #{head_sha}")
+      end
+
+      private def fetch_version
+        version_file = ROOT.join('lib/cov_loupe/version.rb')
+        version_source = version_file.read
+        version = version_source[/VERSION\s*=\s*["'](.+?)["']/, 1]
+        abort_with("Could not find VERSION constant in #{version_file}") unless version
+        version
+      end
+
+      private def verify_release_notes!
+        release_notes = ROOT.join('RELEASE_NOTES.md').read
+        version_pattern = /^## .*\b#{Regexp.escape(@tag_name)}\b/
+        unless release_notes.match?(version_pattern)
+          abort_with("Add a '## #{@tag_name}' section to RELEASE_NOTES.md before releasing.")
+        end
+      end
+
+      private def verify_tag_new!
+        existing_tag = run_command(['git', 'tag', '-l', @tag_name], print_output: false)
+          .split("\n").include?(@tag_name)
+        abort_with("Tag #{@tag_name} already exists. Bump the version before releasing.") if existing_tag
+      end
+
+      private def build_gem!
+        @gem_file = ROOT.join("cov-loupe-#{@version}.gem")
+        FileUtils.rm_f(@gem_file)
+        run_command(%w[gem build cov-loupe.gemspec], print_output: true)
+        abort_with("Gem file #{@gem_file} not found after build.") unless @gem_file.exist?
+      end
+    end
+  end
+end

data/lib/cov_loupe/scripts/setup_doc_server.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'command_execution'
+
+module CovLoupe
+  module Scripts
+    class SetupDocServer
+      include CommandExecution
+
+      def call
+        puts 'Setting up Python virtual environment...'
+        run_command(%w[python3 -m venv .venv], print_output: true)
+
+        puts 'Installing dependencies...'
+        # Install using the venv's pip directly
+        pip_path = File.exist?('.venv/bin/pip') ? '.venv/bin/pip' : 'pip'
+        run_command([pip_path, 'install', '-q', '-r', 'requirements.txt'], print_output: true)
+
+        puts '✓ Documentation server setup complete.'
+      end
+    end
+  end
+end

data/lib/cov_loupe/scripts/start_doc_server.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'command_execution'
+
+module CovLoupe
+  module Scripts
+    class StartDocServer
+      include CommandExecution
+
+      def call
+        mkdocs_path = File.exist?('.venv/bin/mkdocs') ? '.venv/bin/mkdocs' : 'mkdocs'
+
+        unless command_exists?(mkdocs_path)
+          warn "Error: mkdocs not found. Please run 'bin/set-up-python-for-doc-server' or " \
+               "'rake docs:setup' first."
+          exit 1
+        end
+
+        puts 'Starting documentation server...'
+        exec(mkdocs_path, 'serve')
+      end
+    end
+  end
+end

data/lib/cov_loupe/staleness/stale_status.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CovLoupe
+  # Helpers for working with staleness status values.
+  module StaleStatus
+    VALID_STATUSES = %w[ok missing newer length_mismatch error].freeze
+
+    module_function def stale?(value)
+      normalize(value) != 'ok'
+    end
+
+    module_function def normalize(value)
+      raise ArgumentError, 'Stale status is missing' if value.nil?
+      unless value.is_a?(String)
+        raise ArgumentError, "Stale status must be a String, got #{value.class} (value: #{value.inspect})"
+      end
+      return value if VALID_STATUSES.include?(value)
+
+      raise ArgumentError, "Unknown stale status: #{value.inspect}. " \
+                           "Permitted values: #{VALID_STATUSES.join(', ')}"
+    end
+  end
+end

data/lib/cov_loupe/staleness/staleness_checker.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'pathname'
+require 'set' # rubocop:disable Lint/RedundantRequireStatement -- Ruby >= 3.4 requires explicit require for set; RuboCop targets 3.2
+require_relative '../errors/errors'
+require_relative '../resolvers/resolver_helpers'
+
+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.expand_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)
+
+      # Raise FileError if there was a read error
+      if d[:read_error]
+        raise FileError, "Error reading file: #{rel(file_abs)}"
+      end
+
+      # 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 the staleness status for a specific file relative to coverage.
+    # Ignores mode and never raises. Returns a String:
+    # - 'ok' - file is not stale (fresh)
+    # - 'missing' - the file is missing/deleted
+    # - 'newer' - the file mtime is newer than the coverage timestamp
+    # - 'length_mismatch' - the source line count differs from coverage lines array length
+    # - 'error' - the file cannot be read due to permission or I/O errors
+    def file_staleness_status(file_abs, coverage_lines)
+      d = compute_file_staleness_details(file_abs, coverage_lines)
+      return 'error' if d[:read_error]
+      return 'missing' unless d[:exists]
+      return 'newer' if d[:newer]
+      return 'length_mismatch' if d[:len_mismatch]
+
+      'ok'
+    end
+
+    # Compute and return project staleness details (newer, missing, deleted files).
+    # If in error mode, raises CoverageDataProjectStaleError when issues are found.
+    # Returns a hash { newer_files: [], missing_files: [], deleted_files: [], unreadable_files: [] }
+    def check_project!(coverage_map)
+      ts = coverage_timestamp
+      coverage_files = coverage_map.keys
+
+      newer, deleted, unreadable = compute_newer_and_deleted_files(coverage_files, ts)
+      missing = compute_missing_files(coverage_files)
+
+      staleness_details = {
+        newer_files: newer,
+        missing_files: missing,
+        deleted_files: deleted,
+        unreadable_files: unreadable,
+        timestamp_status: ts.to_i > 0 ? 'ok' : 'missing'
+      }
+
+      if @mode == :error && (newer.any? || missing.any? || deleted.any? || unreadable.any?)
+        raise CoverageDataProjectStaleError.new(
+          nil,
+          nil,
+          cov_timestamp: ts,
+          newer_files: newer,
+          missing_files: missing,
+          deleted_files: deleted,
+          unreadable_files: unreadable,
+          resultset_path: resultset_path
+        )
+      end
+
+      staleness_details
+    end
+
+    # Compute and return project staleness details including line-count mismatches.
+    # If in error mode, raises CoverageDataProjectStaleError when issues are found.
+    # Returns a hash with newer/missing/deleted/mismatched/unreadable files and per-file statuses.
+    def check_project_with_lines!(coverage_lines_by_path, coverage_files:)
+      coverage_lines_by_path ||= {}
+      ts = coverage_timestamp
+
+      newer, deleted, unreadable = compute_newer_and_deleted_files(coverage_files, ts)
+      missing = compute_missing_files(coverage_files)
+
+      file_statuses = {}
+      length_mismatch = []
+
+      coverage_lines_by_path.each do |abs_path, coverage_lines|
+        details = compute_file_staleness_details(abs_path, coverage_lines)
+        status = if details[:read_error]
+          'error'
+        elsif !details[:exists]
+          'missing'
+        elsif details[:newer]
+          'newer'
+        elsif details[:len_mismatch]
+          'length_mismatch'
+        else
+          'ok'
+        end
+        file_statuses[abs_path] = status
+        unreadable << rel(abs_path) if details[:read_error]
+        length_mismatch << rel(abs_path) if details[:len_mismatch] && details[:exists]
+      end
+
+      # Ensure files are not reported as both "newer" and "length mismatch" or "unreadable"
+      # Length mismatch and unreadable are the stronger signals for staleness
+      newer -= length_mismatch
+      newer -= unreadable
+
+      staleness_details = {
+        newer_files: newer,
+        missing_files: missing,
+        deleted_files: deleted,
+        length_mismatch_files: length_mismatch,
+        unreadable_files: unreadable,
+        file_statuses: file_statuses,
+        timestamp_status: ts.to_i > 0 ? 'ok' : 'missing'
+      }
+
+      if @mode == :error && [newer, missing, deleted, length_mismatch, unreadable].any?(&:any?)
+        raise CoverageDataProjectStaleError.new(
+          nil,
+          nil,
+          cov_timestamp: ts,
+          newer_files: newer,
+          missing_files: missing,
+          deleted_files: deleted,
+          length_mismatch_files: length_mismatch,
+          unreadable_files: unreadable,
+          resultset_path: resultset_path
+        )
+      end
+
+      staleness_details
+    end
+
+    private def compute_newer_and_deleted_files(coverage_files, timestamp)
+      existing = []
+      deleted_abs = []
+      unreadable_abs = []
+
+      coverage_files.each do |abs|
+        if File.file?(abs)
+          existing << abs
+        else
+          deleted_abs << abs
+        end
+      rescue SystemCallError, IOError
+        # Permission denied or other filesystem errors
+        unreadable_abs << abs
+      end
+
+      newer = []
+      # If timestamp is missing/0, skip newer checks
+      check_newer = timestamp.to_i > 0
+
+      existing.each do |abs|
+        newer << rel(abs) if check_newer && File.mtime(abs).to_i > timestamp.to_i
+      rescue SystemCallError, IOError
+        # Permission denied or other filesystem errors reading mtime
+        unreadable_abs << abs
+      end
+
+      deleted = deleted_abs.map { |abs| rel(abs) }
+      unreadable = unreadable_abs.map { |abs| rel(abs) }
+
+      [newer, deleted, unreadable]
+    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.expand_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 ||= Resolvers::ResolverHelpers.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 SystemCallError, IOError
+      :read_error
+    end
+
+    private def safe_file_state(path)
+      exists = false
+      file_mtime = nil
+      read_error = false
+
+      begin
+        exists = File.file?(path)
+      rescue SystemCallError, IOError
+        return [false, nil, true]
+      end
+
+      return [false, nil, false] unless exists
+
+      begin
+        file_mtime = File.mtime(path)
+      rescue SystemCallError, IOError
+        read_error = true
+      end
+
+      [exists, file_mtime, read_error]
+    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, :read_error
+    private def compute_file_staleness_details(file_abs, coverage_lines)
+      coverage_ts = coverage_timestamp
+
+      exists, file_mtime, read_error = safe_file_state(file_abs)
+
+      cov_len = coverage_lines.respond_to?(:length) ? coverage_lines.length : 0
+      src_len = (exists && !read_error) ? safe_count_lines(file_abs) : 0
+
+      # Check if safe_count_lines returned an error sentinel
+      read_error ||= src_len == :read_error
+      src_len = 0 if read_error
+
+      # Check if the source file has been modified since coverage was generated
+      # Don't check for mismatch if we couldn't read the file
+      len_mismatch = read_error ? false : length_mismatch?(cov_len, src_len)
+      newer = check_file_newer_than_coverage(file_mtime, coverage_ts, len_mismatch, read_error)
+
+      {
+        exists: exists,
+        file_mtime: file_mtime,
+        coverage_timestamp: coverage_ts,
+        cov_len: cov_len,
+        src_len: src_len,
+        newer: newer,
+        len_mismatch: len_mismatch,
+        read_error: read_error
+      }
+    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, src_len)
+      cov_len.positive? && 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 or read error, 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 && !read_error means:
+    # - If len_mismatch or read_error is true, set newer to false (those take precedence)
+    # - This way, staleness is categorized as either 'newer' (time-based), 'length_mismatch' (length-based),
+    #   or 'error' (read error), not multiple
+    private def check_file_newer_than_coverage(file_mtime, coverage_ts, len_mismatch, read_error)
+      return false if coverage_ts.to_i <= 0
+
+      newer = !!(file_mtime && file_mtime.to_i > coverage_ts.to_i)
+      # If there's a length mismatch or read error, don't also flag as "newer" - those are more specific
+      newer &&= !len_mismatch && !read_error
+      newer
+    end
+  end
+end

data/lib/cov_loupe/staleness/staleness_message_formatter.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../output_chars'
+
+module CovLoupe
+  # Formatter for stale coverage error messages
+  class StalenessMessageFormatter
+    def initialize(cov_timestamp:, resultset_path: nil, output_chars: :default)
+      @cov_timestamp = cov_timestamp
+      @resultset_path = resultset_path
+      @output_chars = output_chars
+    end
+
+    def format_project_details(newer_files:, missing_files:, deleted_files:,
+      length_mismatch_files:, unreadable_files: [])
+      [
+        format_coverage_time,
+        *format_file_list(newer_files, 'Newer files'),
+        *format_file_list(missing_files, 'Missing files', 'new in project, not in coverage'),
+        *format_file_list(deleted_files, 'Coverage-only files', 'deleted or moved in project'),
+        *format_file_list(length_mismatch_files, 'Line count mismatches'),
+        *format_file_list(unreadable_files, 'Unreadable files', 'permission denied or read errors'),
+        (@resultset_path ? "\nResultset - #{convert_path(@resultset_path)}" : nil)
+      ].compact.join
+    end
+
+    def format_single_file_details(file_path:, file_mtime:, src_len:, cov_len:)
+      file_utc, file_local = format_time_both(file_mtime)
+      cov_utc, cov_local = format_epoch_both(@cov_timestamp)
+      delta_str = format_delta_seconds(file_mtime, @cov_timestamp)
+
+      details = <<~DETAILS
+
+        File     - time: #{file_utc || 'not found'} (local #{file_local || 'n/a'}), lines: #{src_len}
+        Coverage - time: #{cov_utc  || 'not found'} (local #{cov_local  || 'n/a'}), lines: #{cov_len}
+        DETAILS
+
+      details += "\nDelta    - file is #{delta_str} newer than coverage" if delta_str
+      details += "\nResultset - #{convert_path(@resultset_path)}" if @resultset_path
+      details.chomp
+    end
+
+    private def convert_path(path)
+      OutputChars.convert(path, @output_chars)
+    end
+
+    private def format_coverage_time
+      cov_utc, cov_local = format_epoch_both(@cov_timestamp)
+      "\nCoverage  - time: #{cov_utc || 'not found'} (local #{cov_local || 'n/a'})"
+    end
+
+    private def format_file_list(files, label, description = nil)
+      return [] if files.empty?
+
+      desc = description ? " (#{description}, #{files.size}):" : " (#{files.size}):"
+      [
+        "\n#{label}#{desc}",
+        *files.first(10).map { |f| "  - #{convert_path(f)}" },
+        *(files.size > 10 ? ['  ...'] : [])
+      ]
+    end
+
+    private def format_epoch_both(epoch_seconds)
+      return [nil, nil] unless epoch_seconds
+
+      t = Time.at(epoch_seconds.to_i)
+      [t.utc.iso8601, t.getlocal.iso8601]
+    rescue
+      [epoch_seconds.to_s, epoch_seconds.to_s]
+    end
+
+    private def format_time_both(time)
+      return [nil, nil] unless time
+
+      t = time.is_a?(Time) ? time : Time.parse(time.to_s)
+      [t.utc.iso8601, t.getlocal.iso8601]
+    rescue
+      [time.to_s, time.to_s]
+    end
+
+    private def format_delta_seconds(file_mtime, cov_timestamp)
+      return nil unless file_mtime && cov_timestamp
+
+      seconds = file_mtime.to_i - cov_timestamp.to_i
+      sign = seconds >= 0 ? '+' : '-'
+      "#{sign}#{seconds.abs}s"
+    rescue
+      nil
+    end
+  end
+end