simplecov 1.1.1 → 1.3.0

data/lib/simplecov/cli/dead_code.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "command_helpers"
+require_relative "coverage_file"
+require_relative "../production/file_sink"
+require_relative "dead_code/output"
+
+module SimpleCov
+  module CLI
+    # `simplecov dead-code --production PATH` — cross the coverage a
+    # `SimpleCov::Production` sink accumulated with the test report, and
+    # answer the question neither answers alone. Per line:
+    #
+    #   production | tests | meaning
+    #   yes        | yes   | normal
+    #   yes        | no    | untested code real users are running
+    #   no         | yes   | possibly dead, a deletion candidate
+    #   no         | no    | dead
+    #
+    # The default view prints the bottom two rows (the deletion candidates);
+    # `--untested-in-production` prints the second (the highest-value place to
+    # add a test). Coverage over a long enough window is far better evidence
+    # for deleting Ruby than any static analysis of it, which is why the header
+    # names the window the production data spans.
+    module DeadCode
+      extend CommandHelpers
+
+      extend self
+
+      # The module-name derivation would say "deadcode"; the command is
+      # hyphenated.
+      def command_name
+        "dead-code"
+      end
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args, stderr) or return 1
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: command_name, stderr: stderr) or return 1
+        production = load_production(opts.fetch(:production), stderr) or return 1
+
+        matrix = cross(coverage, production.fetch("coverage"))
+        Output.emit(stdout, opts, matrix, production)
+        0
+      end
+
+      def parse(args, stderr)
+        # `production` needs no default: it is filled in below from the project's
+        # configured store whenever the flag went unused.
+        opts, rest = parse_common(args, untested: false) do |parser, options|
+          parser.on("--production PATH") { |v| options[:production] = v }
+          parser.on("--untested-in-production") { options[:untested] = true }
+        end
+        return error_nil(stderr, "unexpected argument #{rest.first.inspect}") unless rest.empty?
+
+        # The project's configured store fills in for the flag, the way ratchet
+        # reads `baseline_file`, so the DSL stays the single source of truth for
+        # where production coverage lives.
+        opts[:production] ||= Dotfile.production_coverage
+        opts.fetch(:production) ? opts : missing_production(stderr)
+      end
+
+      def missing_production(stderr)
+        error_nil(stderr,
+          "missing --production PATH (the file a SimpleCov::Production sink wrote, " \
+          "or configure SimpleCov.production_coverage in .simplecov)")
+      end
+
+      def load_production(path, stderr)
+        Production::FileSink.read(path)
+      rescue Errno::ENOENT
+        error_nil(stderr, "#{path} not found")
+      rescue SystemCallError, Production::Error => e
+        # The exception stands for its own message in `error`'s interpolation.
+        error_nil(stderr, e)
+      end
+
+      # Classifies every relevant line of the report against the production set,
+      # and sweeps in production files the report never tracked (nothing tested
+      # them, so every recorded line is untested-in-production). Lines the
+      # report deems irrelevant or deliberately ignored stay out of every
+      # bucket.
+      def cross(coverage, production_coverage)
+        matrix = {dead: {}, possibly_dead: {}, untested_in_production: {}, entire: Set.new} #: Hash[Symbol, untyped]
+        coverage.each do |file, entry|
+          lines = entry["lines"]
+          classify_file(matrix, file, lines, production_coverage[file] || []) if lines.instance_of?(Array)
+        end
+        # Files go in unsorted: both the text sections and the JSON payload sort
+        # what they print.
+        (production_coverage.keys - coverage.keys).each do |file|
+          matrix.fetch(:untested_in_production)[file] = production_coverage.fetch(file).sort
+        end
+        matrix
+      end
+
+      # mutant:disable -- the production lines are held as a Set for the cost of
+      # asking, and a list answers `include?` the same way, so the conversion
+      # has no witness at any call site it could live at.
+      def classify_file(matrix, file, lines, production_lines)
+        production = production_lines.to_set
+        buckets = {dead: [], possibly_dead: [], untested_in_production: []} #: Hash[Symbol, Array[Integer]]
+        relevant = 0
+        lines.each_with_index do |value, index|
+          next unless value.is_a?(Numeric)
+
+          relevant += 1
+          bucket = classify_line(value.positive?, production.include?(index + 1))
+          buckets.fetch(bucket) << (index + 1) if bucket
+        end
+        record(matrix, file, buckets, relevant)
+      end
+
+      # The matrix's four cells; the yes/yes cell is the one nothing needs
+      # reporting about.
+      def classify_line(tested, in_production)
+        return :untested_in_production if in_production && !tested
+        return nil if in_production
+
+        tested ? :possibly_dead : :dead
+      end
+
+      # mutant:disable -- the count of relevant lines is checked before a file is
+      # called entirely dead, but a file with no relevant lines lands in no
+      # bucket, so the mark is never read back. The guard says what is meant
+      # rather than what can be seen.
+      def record(matrix, file, buckets, relevant)
+        buckets.each { |bucket, found| matrix.fetch(bucket)[file] = found unless found.empty? }
+        # Counted down to nothing rather than compared for equality: two counts
+        # that are equal are equal through every spelling of the comparison.
+        unhit = buckets.fetch(:dead).size + buckets.fetch(:possibly_dead).size
+        return unless relevant.positive? && (relevant - unhit).zero?
+
+        # Every relevant line unhit in production: the deletion candidate is the
+        # whole file.
+        matrix.fetch(:entire) << file
+      end
+    end
+  end
+end

data/lib/simplecov/cli/diff/output.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Diff
+      module Output
+        STATUS_SUFFIX = {"added" => "(new file)", "removed" => "(removed)"}.freeze
+
+        extend self
+
+        def emit_text(stdout, rows, color)
+          if rows.empty?
+            stdout.puts("simplecov diff: no per-file coverage changes")
+          else
+            rows.each { |row| stdout.puts(format_row(row, color)) }
+          end
+        end
+
+        def format_row(row, color)
+          line = "  #{delta_parts(row, color).join("  ")}  #{row.fetch(:file)}"
+          suffix = STATUS_SUFFIX[row.fetch(:status)]
+          suffix ? "#{line}  #{suffix}" : line
+        end
+
+        def delta_parts(row, color)
+          [
+            format_delta(row.fetch(:line_delta), "lines", color),
+            (format_delta(row.fetch(:branch_delta), "branches", color) if row.fetch(:branch_delta).abs > EPSILON),
+            (format_delta(row.fetch(:method_delta), "methods", color) if row.fetch(:method_delta).abs > EPSILON)
+          ].compact
+        end
+
+        # Deltas are sign-based, not threshold-based: a +5% bump is green and a -5%
+        # drop is red, regardless of where the absolute coverage level lands. A drop
+        # carries its own minus, so the sign is a prefix a rise has and a drop has
+        # not.
+        def format_delta(delta, label, color)
+          sign = "+" if delta.positive?
+          text = format("%<sign>s%<delta>6.2f%% %<label>s", sign: sign, delta: delta, label: label)
+          Color.colorize(text, delta.negative? ? :red : :green, enabled: color)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/diff.rb

@@ -3,50 +3,52 @@
 require "json"
 require "optparse"
 require_relative "command_helpers"
+require_relative "diff/output"
 
 module SimpleCov
   module CLI
-    # `simplecov diff <baseline>` — print per-file coverage deltas between
-    # coverage.json (--input) and a baseline coverage.json
-    # checked in alongside the suite. Only files whose coverage moved
-    # are listed; --fail-on-drop exits non-zero when any file regressed,
-    # so this composes with CI as a "coverage of this PR didn't drop"
-    # gate. Resolves the long-standing "diff coverage" feature request.
+    # `simplecov diff <baseline>`: per-file coverage deltas between coverage.json
+    # and a baseline coverage.json checked in alongside the suite. Only files
+    # whose coverage moved are listed, and `--fail-on-drop` exits non-zero when
+    # any file regressed, so this composes as a "coverage of this PR didn't drop"
+    # gate.
     module Diff
       extend CommandHelpers
 
-      EPSILON = 0.005 # tolerance below which a delta is considered noise
+      # Tolerance below which a delta is considered noise.
+      EPSILON = 0.005
 
-      STATUS_SUFFIX = {"added" => "(new file)", "removed" => "(removed)"}.freeze
-
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:, **)
         opts = parse(args, stderr)
         return 1 unless opts
 
-        rows = compute_rows(opts[:current], opts[:baseline], opts[:threshold])
-        rows.sort_by! { |row| row[:line_delta] }
-        if opts[:json]
+        rows = compute_rows(opts.fetch(:current), opts.fetch(:baseline), opts.fetch(:threshold))
+        rows.sort_by! { |row| row.fetch(:line_delta) }
+        if opts.fetch(:json)
           stdout.puts(JSON.pretty_generate(rows))
         else
-          emit_text(stdout, rows, SimpleCov::CLI.color_enabled?(opts, stdout))
+          Output.emit_text(stdout, rows, CLI.color_enabled?(opts, stdout))
         end
-        opts[:fail_on_drop] && coverage_drop?(rows) ? 1 : 0
+        (opts.fetch(:fail_on_drop) && coverage_drop?(rows)) ? 1 : 0
       end
 
       def parse(args, stderr)
         opts = parse_flags(args)
-        return stderr.puts("simplecov diff: missing baseline argument") && nil if opts[:rest].empty?
+        if opts.fetch(:rest).empty?
+          stderr.puts("simplecov diff: missing baseline argument")
+          return nil
+        end
 
-        opts[:baseline] = load_coverage(opts[:rest].first, stderr) or return nil
-        opts[:current]  = load_coverage(opts[:input], stderr) or return nil
+        opts[:baseline] = load_coverage(opts.fetch(:rest).first, stderr) or return nil
+        opts[:current] = load_coverage(opts.fetch(:input), stderr) or return nil
         opts
       end
 
       def parse_flags(args)
         opts, rest = parse_common(args, fail_on_drop: false, threshold: 0.0) do |o, options|
-          o.on("--fail-on-drop")       { options[:fail_on_drop] = true }
+          o.on("--fail-on-drop") { options[:fail_on_drop] = true }
           o.on("--threshold N", Float) { |v| options[:threshold] = v }
         end
         opts.merge(rest: rest)
@@ -59,9 +61,8 @@ module SimpleCov
         normalize_keys(coverage)
       end
 
-      # Strip a leading slash so coverage.json files written before the
-      # `project_filename` change (keys like "/lib/foo.rb") still diff
-      # cleanly against newer reports (keys like "lib/foo.rb").
+      # Strips a leading slash so coverage.json files written before the
+      # `project_filename` change still diff cleanly against newer reports.
       def normalize_keys(coverage)
         coverage.transform_keys { |key| key.delete_prefix("/") }
       end
@@ -71,17 +72,15 @@ module SimpleCov
         files.filter_map { |fname| compute_row(fname, current[fname], baseline[fname], threshold) }
       end
 
-      # EPSILON keeps float noise out regardless of threshold; the
-      # threshold itself is inclusive, so a file that moved exactly N%
-      # is listed under `--threshold N`, matching the "at least N%" the
-      # usage text promises.
+      # The threshold is inclusive, so a file that moved exactly N% is listed under
+      # `--threshold N`, matching the "at least N%" the usage text promises.
       def compute_row(fname, current_payload, baseline_payload, threshold)
         deltas = compute_deltas(current_payload, baseline_payload)
         floor = threshold.abs
         return nil unless deltas.values.any? { |delta| delta.abs > EPSILON && delta.abs >= floor }
 
         {file: fname, status: status_for(current_payload, baseline_payload),
-         line_delta: deltas[:line], branch_delta: deltas[:branch], method_delta: deltas[:method]}
+         line_delta: deltas.fetch(:line), branch_delta: deltas.fetch(:branch), method_delta: deltas.fetch(:method)}
       end
 
       def compute_deltas(current_payload, baseline_payload)
@@ -91,56 +90,25 @@ module SimpleCov
       end
 
       def status_for(current_payload, baseline_payload)
-        return "added"   if baseline_payload.nil?
+        return "added" if baseline_payload.nil?
         return "removed" if current_payload.nil?
 
         "changed"
       end
 
       def pct_for(fields, payload)
-        return 0.0 unless payload.is_a?(Hash) && payload[fields[:total]].to_i.positive?
-
-        payload[fields[:percent]].to_f
-      end
-
-      def emit_text(stdout, rows, color)
-        return stdout.puts("simplecov diff: no per-file coverage changes") if rows.empty?
+        return 0.0 unless payload.instance_of?(Hash) && payload[fields.fetch(:total)].to_i.positive?
 
-        rows.each { |row| stdout.puts(format_row(row, color)) }
+        payload[fields.fetch(:percent)].to_f
       end
 
-      def format_row(row, color)
-        line = "  #{delta_parts(row, color).join('  ')}  #{row[:file]}"
-        suffix = STATUS_SUFFIX[row[:status]]
-        suffix ? "#{line}  #{suffix}" : line
-      end
-
-      def delta_parts(row, color)
-        [
-          format_delta(row[:line_delta], "lines", color),
-          (format_delta(row[:branch_delta], "branches", color) if row[:branch_delta].abs > EPSILON),
-          (format_delta(row[:method_delta], "methods", color)  if row[:method_delta].abs > EPSILON)
-        ].compact
-      end
-
-      # A removed file's deltas are all -baseline%, but deleting a
-      # covered file (dead code cleanup) is not a coverage regression,
-      # so removed rows never trip the --fail-on-drop gate. Drops are
-      # gated on EPSILON like row inclusion and display: a row listed
-      # for a gain in one criterion must not fail the run over float
-      # noise in another, invisible in the printed output.
+      # A removed file's deltas are all -baseline%, but deleting a covered file is
+      # not a coverage regression, so removed rows never trip the gate. Drops are
+      # gated on EPSILON like row inclusion and display, so a row listed for a gain
+      # in one criterion cannot fail the run over float noise in another.
       def coverage_drop?(rows)
-        rows.reject { |row| row[:status] == "removed" }
-            .any? { |row| row.values_at(:line_delta, :branch_delta, :method_delta).min < -EPSILON }
-      end
-
-      # Deltas are sign-based, not threshold-based: a +5% bump is good
-      # (green) and a -5% drop is bad (red), regardless of where the
-      # absolute coverage level lands.
-      def format_delta(delta, label, color)
-        sign = delta.positive? ? "+" : ""
-        text = format("%<sign>s%<delta>6.2f%% %<label>s", sign: sign, delta: delta, label: label)
-        SimpleCov::Color.colorize(text, delta.negative? ? :red : :green, enabled: color)
+        rows.reject { |row| row.fetch(:status).eql?("removed") }
+          .any? { |row| row.fetch_values(:line_delta, :branch_delta, :method_delta).min < -EPSILON }
       end
     end
   end

data/lib/simplecov/cli/dotfile.rb

@@ -4,14 +4,13 @@ require "pathname"
 
 module SimpleCov
   module CLI
-    # Loads a project's `.simplecov` config file purely to read
-    # `coverage_dir` from it, with `SimpleCov.start` and the at_exit
-    # hook installer neutered so the load doesn't trigger coverage
-    # tracking. Used by the CLI to default `--input` / `--report`
-    # paths to whatever the project's dotfile declares, without making
-    # every read-only subcommand pay for actually starting Coverage.
+    # Loads a project's `.simplecov` config file purely to read configuration
+    # from it, with `SimpleCov.start` and the at_exit hook installer neutered so
+    # the load doesn't trigger coverage tracking. Used by the CLI to default
+    # paths to whatever the project's dotfile declares, without making every
+    # read-only subcommand pay for actually starting Coverage.
     module Dotfile
-    module_function
+      extend self
 
       def coverage_dir
         dotfile = find
@@ -19,37 +18,73 @@ module SimpleCov
 
         with_simplecov_loaded { read_from(dotfile) }
       rescue ScriptError, StandardError => e
-        # simplecov:disable — defensive fallback for a bad dotfile; never
-        # fires in the project's own dogfood run. ScriptError covers the
-        # SyntaxError a malformed dotfile raises from `load` (it is not a
-        # StandardError) along with LoadError; StandardError covers the
-        # rest (EACCES, errors raised by the dotfile's own code, etc.).
-        warn "simplecov: failed to read coverage_dir from #{dotfile}: #{e.class}: #{e.message}"
+        # ScriptError covers the SyntaxError a malformed dotfile raises from
+        # `load` (it is not a StandardError) along with LoadError; StandardError
+        # covers the rest.
+        warn "simplecov: failed to read coverage_dir from #{dotfile}: #{e.class}: #{e}"
         "coverage"
-        # simplecov:enable
       end
 
-      # Load the dotfile, snapshot+restore `SimpleCov.coverage_dir` so we
-      # don't quietly clobber it in a host process that's already
-      # configured (e.g. when the CLI is exercised inline by simplecov's
-      # own spec suite). The snapshot is intentionally narrow: a dotfile
-      # can still mutate other SimpleCov configuration (filters, groups,
-      # formatters, command_name, ...) via `SimpleCov.configure` or
-      # `SimpleCov.start { ... }` blocks. The CLI normally runs as a
-      # top-level process where that's harmless; callers driving it from
-      # inside a Ruby host that cares about isolation should arrange that
-      # themselves.
+      # Read from `.simplecov` the way `coverage_dir` is, so a project that moved
+      # its baseline doesn't need `--baseline` on every ratchet.
+      def baseline_file
+        dotfile = find
+        return Baseline::DEFAULT_FILENAME unless dotfile
+
+        with_simplecov_loaded { read_baseline_file_from(dotfile) }
+      rescue ScriptError, StandardError => e
+        warn "simplecov: failed to read baseline_file from #{dotfile}: #{e.class}: #{e}"
+        Baseline::DEFAULT_FILENAME
+      end
+
+      # Nil when there is no dotfile, the dotfile names no store, or it cannot be
+      # read: unlike the other reads there is no sensible fallback path, and the
+      # command's own missing-store error is the right answer.
+      def production_coverage
+        dotfile = find
+        return nil unless dotfile
+
+        with_simplecov_loaded { read_production_coverage_from(dotfile) }
+      rescue ScriptError, StandardError => e
+        # `warn` answers nil, which is this reader's whole fallback.
+        warn "simplecov: failed to read production_coverage from #{dotfile}: #{e.class}: #{e}"
+      end
+
+      def read_production_coverage_from(dotfile)
+        snapshot = SimpleCov.instance_variable_get(:@production_coverage) #: String?
+        load_with_start_neutered(dotfile)
+        SimpleCov.production_coverage
+      ensure
+        # @type var snapshot: String?
+        SimpleCov.instance_variable_set(:@production_coverage, snapshot)
+      end
+
+      def read_baseline_file_from(dotfile)
+        snapshot = SimpleCov.instance_variable_get(:@baseline_file) #: String?
+        load_with_start_neutered(dotfile)
+        SimpleCov.baseline_file
+      ensure
+        # @type var snapshot: String?
+        SimpleCov.instance_variable_set(:@baseline_file, snapshot)
+      end
+
+      # Snapshot and restore `SimpleCov.coverage_dir` so we don't quietly clobber
+      # it in a host process that's already configured. The snapshot is
+      # intentionally narrow: a dotfile can still mutate other configuration
+      # via `SimpleCov.configure` or `SimpleCov.start { ... }` blocks.
       def read_from(dotfile)
         snapshot = SimpleCov.instance_variable_get(:@coverage_dir) #: String?
         load_with_start_neutered(dotfile)
         SimpleCov.coverage_dir
       ensure
-        # Restore even when the load raises, so a bad dotfile doesn't
-        # leave a host process's configured dir clobbered.
+        # Restored even when the load raises, so a bad dotfile doesn't leave a
+        # host process's configured dir clobbered.
         # @type var snapshot: String?
         SimpleCov.instance_variable_set(:@coverage_dir, snapshot)
       end
 
+      # The nearest `.simplecov` at or above the working directory, or nil, which
+      # is what the walk itself answers once it breaks at the filesystem root.
       def find
         dir = Pathname.new(Dir.pwd)
         loop do
@@ -59,38 +94,48 @@ module SimpleCov
 
           dir = dir.parent
         end
-        nil
       end
 
       def with_simplecov_loaded
         previous_no_defaults = ENV.fetch("SIMPLECOV_NO_DEFAULTS", nil) #: String?
-        previous_cli         = ENV.fetch("SIMPLECOV_CLI", nil) #: String?
+        previous_cli = ENV.fetch("SIMPLECOV_CLI", nil) #: String?
         ENV["SIMPLECOV_NO_DEFAULTS"] = "1"
         # SIMPLECOV_CLI lets a project's `.simplecov` opt some config into
-        # CLI-only behavior — e.g. simplecov itself sets `coverage_dir`
-        # to the dogfood path here but skips that for descendants.
+        # CLI-only behavior: simplecov itself sets `coverage_dir` to the dogfood
+        # path here but skips that for descendants.
         ENV["SIMPLECOV_CLI"] = "1"
-        require "simplecov"
+        load_simplecov
         yield
       ensure
         # @type var previous_no_defaults: String?
         # @type var previous_cli: String?
         ENV["SIMPLECOV_NO_DEFAULTS"] = previous_no_defaults
-        ENV["SIMPLECOV_CLI"]         = previous_cli
+        ENV["SIMPLECOV_CLI"] = previous_cli
+      end
+
+      # The deferred require exists for a standalone CLI process that has not
+      # loaded simplecov yet. It must happen inside the env guard above, so a
+      # first load here skips the default profile chain.
+      def load_simplecov
+        require "simplecov"
       end
 
-      # Load `path` with `SimpleCov.start` and the at_exit installer
-      # turned into no-ops, so a project whose dotfile calls
-      # `SimpleCov.start` doesn't trigger Coverage just because we asked
-      # for `coverage_dir`. Config inside any `SimpleCov.start { ... }`
-      # block still runs.
+      # A constant rather than a block written at the call site, where an empty
+      # block and one answering nil are the same thing to every caller and so
+      # to every test.
+      NEUTERED = proc {}
+
+      # Load `path` with `SimpleCov.start` and the at_exit installer turned into
+      # no-ops, so a project whose dotfile calls `SimpleCov.start` doesn't
+      # trigger Coverage just because we asked for `coverage_dir`. Config
+      # inside any `SimpleCov.start { ... }` block still runs.
       def load_with_start_neutered(path)
         klass = SimpleCov.singleton_class
         names = %i[start_tracking install_at_exit_hook]
         stash = names.to_h { |name| [name, klass.instance_method(name)] } #: Hash[Symbol, UnboundMethod]
         # define_method over an existing method emits a "method redefined"
         # warning under $VERBOSE; the override and restore are intentional.
-        silence_verbose { names.each { |name| klass.define_method(name) { nil } } }
+        silence_verbose { names.each { |name| klass.define_method(name, &(_ = NEUTERED)) } }
         load path
       ensure
         # @type var stash: Hash[Symbol, UnboundMethod]

data/lib/simplecov/cli/git.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module SimpleCov
+  module CLI
+    # The git plumbing the change-aware subcommands share: safe capture, the
+    # repository toplevel, ref hygiene, and the default base ref.
+    module Git
+      extend self
+
+      # [stdout, first stderr line, success]. A spawn failure reads as an
+      # unsuccessful run whose stdout is nil, so callers can tell "git ran and
+      # refused" from "git never ran".
+      def capture(*argv)
+        stdout, stderr, status = Open3.capture3("git", *argv)
+        [stdout, stderr.lines.first.to_s.strip, status.success?]
+      rescue => e
+        [nil, e.message, false]
+      end
+
+      def toplevel
+        stdout, _detail, success = capture("rev-parse", "--show-toplevel")
+        (_ = stdout).chomp if success
+      end
+
+      # A git ref can never begin with "-", so one that does would be read by git
+      # as an option instead of a revision.
+      def option_like_ref?(ref)
+        ref.start_with?("-")
+      end
+
+      # The branch origin's HEAD points at, so master and trunk repositories work
+      # bare, falling back to main where no origin HEAD is recorded.
+      def default_base
+        stdout, _detail, success = capture("symbolic-ref", "--short", "refs/remotes/origin/HEAD")
+        success ? (_ = stdout).chomp.delete_prefix("origin/") : "main"
+      end
+    end
+  end
+end