simplecov 0.22.0 → 1.3.0

data/lib/simplecov/cli/coverage.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    module Coverage
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args, stderr: stderr)
+        return 1 unless opts
+
+        match = locate_match(opts, stderr)
+        return 1 unless match
+
+        emit(match, opts, stdout)
+        0
+      end
+
+      def parse(args, stderr:)
+        opts, rest = parse_common(args)
+        if rest.empty?
+          stderr.puts("simplecov coverage: missing file argument")
+          return nil
+        end
+
+        opts[:path] = rest.first
+        opts
+      end
+
+      def locate_match(opts, stderr)
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "coverage", stderr: stderr)
+        return unless coverage
+
+        match = lookup(coverage, opts.fetch(:path))
+        return report_not_found(stderr, coverage, opts) if match.nil?
+        return match if match.last.instance_of?(Hash)
+
+        CoverageFile.report_invalid(stderr, "coverage", opts.fetch(:input),
+          "entry for #{opts.fetch(:path)} must be an object")
+      end
+
+      def report_not_found(stderr, coverage, opts)
+        message = CoverageFile.not_found_message(coverage, opts.fetch(:path), opts.fetch(:input))
+        stderr.puts("simplecov coverage: #{message}")
+      end
+
+      def lookup(coverage_hash, path)
+        CoverageFile.lookup(coverage_hash, path)
+      end
+
+      def emit(match, opts, stdout)
+        filename, payload = match
+        if opts.fetch(:json)
+          entry = {filename => payload} #: Hash[untyped, untyped]
+          stdout.puts(JSON.pretty_generate(entry))
+        else
+          print_human(filename, payload, stdout, CLI.color_enabled?(opts, stdout))
+        end
+      end
+
+      def print_human(filename, payload, stdout, color)
+        stdout.puts(filename)
+        CoverageFile::CRITERIA.each_value { |c| emit_criterion(stdout, payload, c, color) }
+      end
+
+      def emit_criterion(stdout, payload, criterion, color)
+        return unless payload.key?(criterion.fetch(:percent))
+
+        pct = payload.fetch(criterion.fetch(:percent)).to_f
+        stdout.puts(stats_row(criterion.fetch(:label),
+          Color.colorize_percent(pct, enabled: color),
+          payload[criterion.fetch(:covered)],
+          payload[criterion.fetch(:total)]))
+      end
+    end
+  end
+end

data/lib/simplecov/cli/coverage_file.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../coverage_json"
+
+module SimpleCov
+  module CLI
+    # Shared input boundary for commands that consume JSONFormatter's
+    # coverage.json. It validates only the stable outer shape, so older schema
+    # versions remain readable.
+    module CoverageFile
+      CRITERIA = {
+        line: {label: "Line", percent: "lines_covered_percent",
+               covered: "covered_lines", missed: "missed_lines", total: "total_lines"},
+        branch: {label: "Branch", percent: "branches_covered_percent",
+                 covered: "covered_branches", missed: "missed_branches", total: "total_branches"},
+        method: {label: "Method", percent: "methods_covered_percent",
+                 covered: "covered_methods", missed: "missed_methods", total: "total_methods"}
+      }.freeze
+
+      extend self
+
+      # An exact match, the absolute path or the literal string passed, wins over
+      # a suffix match, so a nested "vendor/lib/foo.rb" can't shadow the real
+      # "lib/foo.rb" just by sitting earlier in the report. A subpath can end more
+      # than one key, and a collision is left as "not found" for the caller rather
+      # than scoring whichever key happens to sit first.
+      def lookup(coverage_hash, path)
+        absolute = File.expand_path(path)
+        return [absolute, coverage_hash.fetch(absolute)] if coverage_hash.key?(absolute)
+        return [path, coverage_hash.fetch(path)] if coverage_hash.key?(path)
+
+        matches = suffix_matches(coverage_hash, path)
+        matches.first if matches.one?
+      end
+
+      # The suffix's leading slash keeps "foo.rb" from matching "barfoo.rb", and
+      # hoisting it keeps the scan from allocating a string per entry.
+      def suffix_matches(coverage_hash, path)
+        suffix = "/#{path}"
+        coverage_hash.select { |fname, _| fname.end_with?(suffix) }
+      end
+
+      # The report's entries under exact, realpath-normalized keys, for
+      # programmatic resolution where a suffix fallback could bind a path to the
+      # wrong entry. The realpath step keeps a symlinked project root from
+      # splitting a resolved path apart from the report's keys.
+      def exact_index(coverage_hash)
+        index = {} #: Hash[String, untyped]
+        coverage_hash.each do |key, payload|
+          index[key] ||= payload
+          index[normalize(key)] ||= payload
+        end
+        index
+      end
+
+      # A key whose file no longer exists keeps its literal spelling.
+      def normalize(key)
+        File.realdirpath(key)
+      rescue SystemCallError
+        key
+      end
+
+      # An ambiguous subpath names its candidates: "no entry" would send the user
+      # hunting for a typo in a path that exists twice.
+      def not_found_message(coverage_hash, path, input)
+        matches = suffix_matches(coverage_hash, path).keys
+        return "no entry for #{path} in #{input}" if matches.size < 2
+
+        "#{path} matches #{matches.size} files in #{input}: #{matches.sort.join(", ")} " \
+          "(use a longer path to pick one)"
+      end
+
+      def load_document(path, command:, stderr:)
+        CoverageJSON.load(path)
+      rescue Errno::ENOENT
+        report_missing(stderr, command, path)
+      rescue CoverageJSON::Error => e
+        report_invalid(stderr, command, path, e.message)
+      rescue SystemCallError => e
+        report_unreadable(stderr, command, path, e.message)
+      end
+
+      def load_coverage(path, command:, stderr:)
+        document = load_document(path, command: command, stderr: stderr)
+        return unless document
+
+        none = {} #: Hash[String, untyped]
+        coverage = document.fetch("coverage", none)
+        return coverage if coverage.is_a?(Hash)
+
+        report_invalid(stderr, command, path, '"coverage" must be an object')
+      end
+
+      def report_invalid(stderr, command, path, reason)
+        detail = reason.lines.first.to_s.strip
+        stderr.puts("simplecov #{command}: input file #{path.inspect} isn't valid JSON (#{detail})")
+      end
+
+      def report_missing(stderr, command, path)
+        stderr.puts("simplecov #{command}: #{path} not found")
+      end
+
+      def report_unreadable(stderr, command, path, reason)
+        detail = reason.lines.first.to_s.strip
+        stderr.puts("simplecov #{command}: cannot read #{path.inspect} (#{detail})")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require_relative "../patch/output"
+
+module SimpleCov
+  module CLI
+    module DeadCode
+      module Output
+        extend CommandHelpers
+
+        extend self
+
+        def emit(stdout, opts, matrix, production)
+          return stdout.puts(JSON.generate(json_payload(matrix, production))) if opts.fetch(:json)
+
+          stdout.puts("Production coverage: #{opts.fetch(:production)}#{window_suffix(production)}")
+          stdout.puts
+          last_seen = production.fetch("last_seen")
+          opts.fetch(:untested) ? emit_untested(stdout, matrix, last_seen) : emit_dead(stdout, matrix, last_seen)
+        end
+
+        def emit_dead(stdout, matrix, last_seen)
+          rows = section(stdout, "Dead code (not run in production, not covered by tests):", matrix, :dead,
+            last_seen)
+          rows += section(stdout, "Possibly dead (not run in production, covered only by tests):", matrix,
+            :possibly_dead, last_seen)
+          return stdout.puts("No dead code found.") if rows.zero?
+
+          dead = count(matrix, :dead)
+          possibly = count(matrix, :possibly_dead)
+          stdout.puts("#{pluralize(dead, "dead line")}, #{pluralize(possibly, "possibly dead line")}")
+        end
+
+        def emit_untested(stdout, matrix, last_seen)
+          rows = section(stdout, "Untested code running in production:", matrix, :untested_in_production, last_seen)
+          return stdout.puts("No untested production code found.") if rows.zero?
+
+          stdout.puts("#{pluralize(count(matrix, :untested_in_production), "untested line")} running in production")
+        end
+
+        def section(stdout, heading, matrix, bucket, last_seen)
+          rows = matrix.fetch(bucket).sort
+          return 0 if rows.empty?
+
+          stdout.puts(heading)
+          rows.each do |file, lines|
+            stdout.puts("  #{file}:#{Patch::Output.ranges(lines, ",")}#{markers(matrix, file, last_seen)}")
+          end
+          stdout.puts
+          rows.size
+        end
+
+        # The row's parenthesized evidence. "entire file" says every relevant line
+        # skipped production; "last run" dates the store's last sighting of the file,
+        # which for a dead or possibly dead row means other lines of the file ran
+        # then, and its absence means the window never saw the file at all. Both can
+        # hold at once.
+        def markers(matrix, file, last_seen)
+          markers = [] #: Array[String]
+          markers << "entire file" if matrix.fetch(:entire).include?(file)
+          stamp = last_seen[file]
+          markers << "last run #{stamp[0, 10]}" if stamp.instance_of?(String)
+          " (#{markers.join(", ")})" unless markers.empty?
+        end
+
+        def count(matrix, bucket)
+          matrix.fetch(bucket).sum { |_file, lines| lines.size }
+        end
+
+        def pluralize(number, noun)
+          "#{number} #{noun}#{"s" unless one?(number)}"
+        end
+
+        def window_suffix(production)
+          started = production["started_at"]
+          updated = production["updated_at"]
+          " (window #{started} to #{updated})" if started && updated
+        end
+
+        def json_payload(matrix, production)
+          last_seen = production.fetch("last_seen")
+          payload = {window: {started_at: production["started_at"], updated_at: production["updated_at"]}}
+          %i[dead possibly_dead untested_in_production].each do |bucket|
+            payload[bucket] = matrix.fetch(bucket).sort.map { |file, lines| json_entry(file, lines, last_seen) }
+          end
+          payload
+        end
+
+        # JSON carries the full stamp where the text views print its date, and omits
+        # the key for a file the window never saw.
+        def json_entry(file, lines, last_seen)
+          entry = {file: file, lines: lines} #: Hash[Symbol, untyped]
+          stamp = last_seen[file]
+          entry[:last_seen] = stamp if stamp.instance_of?(String)
+          entry
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+require_relative "diff/output"
+
+module SimpleCov
+  module CLI
+    # `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
+
+      # Tolerance below which a delta is considered noise.
+      EPSILON = 0.005
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args, stderr)
+        return 1 unless opts
+
+        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
+          Output.emit_text(stdout, rows, CLI.color_enabled?(opts, stdout))
+        end
+        (opts.fetch(:fail_on_drop) && coverage_drop?(rows)) ? 1 : 0
+      end
+
+      def parse(args, stderr)
+        opts = parse_flags(args)
+        if opts.fetch(:rest).empty?
+          stderr.puts("simplecov diff: missing baseline argument")
+          return nil
+        end
+
+        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("--threshold N", Float) { |v| options[:threshold] = v }
+        end
+        opts.merge(rest: rest)
+      end
+
+      def load_coverage(path, stderr)
+        coverage = CoverageFile.load_coverage(path, command: "diff", stderr: stderr)
+        return unless coverage
+
+        normalize_keys(coverage)
+      end
+
+      # 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
+
+      def compute_rows(current, baseline, threshold)
+        files = current.keys | baseline.keys
+        files.filter_map { |fname| compute_row(fname, current[fname], baseline[fname], threshold) }
+      end
+
+      # 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.fetch(:line), branch_delta: deltas.fetch(:branch), method_delta: deltas.fetch(:method)}
+      end
+
+      def compute_deltas(current_payload, baseline_payload)
+        CoverageFile::CRITERIA.transform_values do |fields|
+          pct_for(fields, current_payload) - pct_for(fields, baseline_payload)
+        end
+      end
+
+      def status_for(current_payload, baseline_payload)
+        return "added" if baseline_payload.nil?
+        return "removed" if current_payload.nil?
+
+        "changed"
+      end
+
+      def pct_for(fields, payload)
+        return 0.0 unless payload.instance_of?(Hash) && payload[fields.fetch(:total)].to_i.positive?
+
+        payload[fields.fetch(:percent)].to_f
+      end
+
+      # 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.fetch(:status).eql?("removed") }
+          .any? { |row| row.fetch_values(:line_delta, :branch_delta, :method_delta).min < -EPSILON }
+      end
+    end
+  end
+end