simplecov 1.1.1 → 1.2.0

data/lib/simplecov/cli/completions/scripts.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Completions
+      # The per-shell renderers. Each receives the same parsed usage data and
+      # returns the complete script text. The completions command's own shell-name
+      # argument is the one thing the usage tables don't carry, so each renderer
+      # wires it in by hand.
+      module Scripts
+        extend self
+
+        def fish(commands, options)
+          lines = ["# Completions for simplecov. Generated by `simplecov completions fish`."] #: Array[String]
+          commands.each do |name, desc|
+            lines << "complete -c simplecov -f -n __fish_use_subcommand -a #{name} -d #{fish_quote(desc)}"
+          end
+          options.each { |name, list| list.each { |option| lines << fish_option(name, option) } }
+          lines << "complete -c simplecov -f -n '__fish_seen_subcommand_from completions' -a 'fish bash zsh'"
+          lines.join("\n")
+        end
+
+        def fish_option(name, option)
+          parts = ["complete -c simplecov -n '__fish_seen_subcommand_from #{name}'"] #: Array[String]
+          parts << "-s #{(_ = option.fetch(:short)).delete_prefix("-")}" if option.fetch(:short)
+          parts << "-l #{option.fetch(:long).delete_prefix("--")}"
+          parts << "-r" if option.fetch(:arg)
+          parts << "-d #{fish_quote(option.fetch(:desc))}"
+          parts.join(" ")
+        end
+
+        def fish_quote(text)
+          "'#{text.gsub("\\") { "\\\\" }.gsub("'") { "\\'" }}'"
+        end
+
+        BASH_TAIL = [
+          "  esac",
+          '  [[ "$cur" == -* ]] && COMPREPLY=( $(compgen -W "$opts" -- "$cur") )',
+          "}",
+          "complete -o default -F _simplecov simplecov"
+        ].freeze
+
+        def bash(commands, options)
+          (bash_head(commands) + bash_cases(options) + BASH_TAIL).join("\n")
+        end
+
+        def bash_head(commands)
+          [
+            "# Completions for simplecov. Generated by `simplecov completions bash`.",
+            "_simplecov() {",
+            '  local cur="${COMP_WORDS[COMP_CWORD]}" opts=""',
+            '  if [ "$COMP_CWORD" -eq 1 ]; then',
+            "    COMPREPLY=( $(compgen -W \"#{commands.collect(&:first).join(" ")}\" -- \"$cur\") ); return",
+            "  fi",
+            '  case "${COMP_WORDS[1]}" in'
+          ]
+        end
+
+        def bash_cases(options)
+          shells = '    completions) COMPREPLY=( $(compgen -W "fish bash zsh -h --help" -- "$cur") ); return;;'
+          cases = [shells] #: Array[String]
+          options.each do |name, list|
+            next if name.eql?("completions")
+
+            words = list.flat_map { |option| [option.fetch(:short), option.fetch(:long)] }.compact.join(" ")
+            cases << "    #{name}) opts=\"#{words}\";;"
+          end
+          cases
+        end
+
+        ZSH_MIDDLE = [
+          "  )",
+          "  if (( CURRENT == 2 )); then",
+          "    _describe -t commands 'simplecov command' commands",
+          "    return",
+          "  fi",
+          '  case "$words[2]" in'
+        ].freeze
+
+        ZSH_TAIL = ["  esac", "}", '_simplecov "$@"'].freeze
+
+        def zsh(commands, options)
+          head = ["#compdef simplecov", "# Completions for simplecov. Generated by `simplecov completions zsh`.",
+            "_simplecov() {", "  local -a commands", "  commands=("]
+          rows = commands.collect { |name, desc| "    '#{name}:#{zsh_quote(desc)}'" }
+          (head + rows + ZSH_MIDDLE + zsh_cases(options) + ZSH_TAIL).join("\n")
+        end
+
+        def zsh_cases(options)
+          options.collect do |name, list|
+            specs = +""
+            specs << "'1:shell:(fish bash zsh)' " if name.eql?("completions")
+            list.each { |option| zsh_specs(option).each { |spec| specs << spec << " " } }
+            "    #{name}) _arguments #{specs.chop};;"
+          end
+        end
+
+        # `'--input=[desc]'`: the `=` marks an argument-taking switch, which optparse
+        # accepts in that spelling too. Brackets would end the description early, so
+        # they are dropped from it.
+        def zsh_specs(option)
+          desc = "[#{zsh_quote(option.fetch(:desc).delete("[]"))}]"
+          specs = [] #: Array[String]
+          specs << "'#{option.fetch(:short)}#{desc}'" if option.fetch(:short)
+          specs << "'#{option.fetch(:long)}#{"=" if option.fetch(:arg)}#{desc}'"
+        end
+
+        def zsh_quote(text)
+          text.gsub("'") { "'\\''" }
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/completions.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+require_relative "usage"
+require_relative "completions/scripts"
+
+module SimpleCov
+  module CLI
+    # `simplecov completions <shell>`: completion scripts for fish, bash, and
+    # zsh, generated from the usage document rather than a hand-kept table, so a
+    # new command or switch shows up in completions the moment it is documented.
+    module Completions
+      extend CommandHelpers
+
+      extend self
+
+      SHELLS = %w[fish bash zsh].freeze
+
+      # "  -q, --quiet               Suppress...": optional short, long, optional
+      # argument placeholder, then the description after the column gap. A single
+      # space never separates the switch from its description, so one non-space
+      # token before a two-space run can only be an argument.
+      OPTION_ROW = /\A\s*(?:(-\w), )?(--[\w-]+)(?: (\S+))?\s{2,}(\S.*)\z/
+      COMMAND_ROW = /\A(\S+)(?: \S+)*?\s{2,}(\S.*)\z/
+
+      def run(args, stdout:, stderr:)
+        shell, = build_parser.parse(args)
+        return error(stderr, "missing shell (expected fish, bash, or zsh)") unless shell
+        unless SHELLS.include?(shell)
+          return error(stderr, "unknown shell #{shell.inspect} (expected fish, bash, or zsh)")
+        end
+
+        stdout.puts(script_for(shell))
+        0
+      end
+
+      def script_for(shell)
+        case shell
+        when "fish" then Scripts.fish(commands, options_by_command)
+        when "bash" then Scripts.bash(commands, options_by_command)
+        else Scripts.zsh(commands, options_by_command)
+        end
+      end
+
+      def commands
+        Usage.text(CLI).split("\n\n").fetch(1).lines.filter_map do |row|
+          match = row.strip.match(COMMAND_ROW)
+          match && [(_ = match[1]), (_ = match[2])]
+        end
+      end
+
+      def options_by_command
+        commands.filter_map do |name, _desc|
+          list = options_for(name)
+          [name, list] unless list.empty?
+        end.to_h
+      end
+
+      # `run` takes no options of its own, since everything after it belongs to the
+      # command being run, so it must not even offer --help.
+      def options_for(command)
+        return [] if command.eql?("run")
+
+        sections = Usage.text(CLI).split("\n\n").select { |section| Usage.section_for?(section, command) }
+        options = sections.flat_map { |section| section_options(section) }
+        options << {short: "-h", long: "--help", arg: nil, desc: "Show this command's usage"}
+      end
+
+      # Rows that don't parse as options are continuations of the previous row's
+      # description, wrapped for the terminal.
+      def section_options(section)
+        section.lines.each_with_object([]) do |line, options|
+          if (match = line.chomp.match(OPTION_ROW))
+            options << {short: match[1], long: match[2], arg: match[3], desc: (_ = match[4])}
+          elsif (previous = options.last)
+            previous[:desc] = "#{previous.fetch(:desc)} #{line.strip}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/coverage.rb

@@ -6,12 +6,10 @@ require_relative "command_helpers"
 
 module SimpleCov
   module CLI
-    # `simplecov coverage <path>` — print per-criterion stats for one
-    # file from a JSONFormatter coverage.json.
     module Coverage
       extend CommandHelpers
 
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:)
         opts = parse(args, stderr: stderr)
@@ -26,44 +24,43 @@ module SimpleCov
 
       def parse(args, stderr:)
         opts, rest = parse_common(args)
-        return stderr.puts("simplecov coverage: missing file argument") && nil if rest.empty?
+        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[:input], command: "coverage", stderr: stderr)
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "coverage", stderr: stderr)
         return unless coverage
 
-        match = lookup(coverage, opts[:path])
-        if match.nil?
-          stderr.puts("simplecov coverage: no entry for #{opts[:path]} in #{opts[:input]}")
-          return nil
-        end
-        # A wrong-typed entry used to escape here and crash print_human.
-        return match if match.last.is_a?(Hash)
+        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
 
-        CoverageFile.report_invalid(stderr, "coverage", opts[:input], "entry for #{opts[:path]} must be an object")
+      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
 
-      # Match either the absolute path, the literal string passed, or
-      # any coverage entry whose absolute filename ends with "/<path>".
-      # That covers the three natural ways a user types a path: relative
-      # to project root ("app/foo.rb"), absolute, or basename-only.
       def lookup(coverage_hash, path)
-        absolute = File.expand_path(path)
-        suffix   = "/#{path}"
-        coverage_hash.find { |fname, _| fname == absolute || fname == path || fname.end_with?(suffix) }
+        CoverageFile.lookup(coverage_hash, path)
       end
 
       def emit(match, opts, stdout)
         filename, payload = match
-        if opts[:json]
+        if opts.fetch(:json)
           entry = {filename => payload} #: Hash[untyped, untyped]
           stdout.puts(JSON.pretty_generate(entry))
         else
-          print_human(filename, payload, stdout, SimpleCov::CLI.color_enabled?(opts, stdout))
+          print_human(filename, payload, stdout, CLI.color_enabled?(opts, stdout))
         end
       end
 
@@ -73,13 +70,13 @@ module SimpleCov
       end
 
       def emit_criterion(stdout, payload, criterion, color)
-        return unless payload.key?(criterion[:percent])
+        return unless payload.key?(criterion.fetch(:percent))
 
-        pct = payload[criterion[:percent]].to_f
-        stdout.puts(stats_row(criterion[:label],
-                              SimpleCov::Color.colorize_percent(pct, enabled: color),
-                              payload[criterion[:covered]],
-                              payload[criterion[:total]]))
+        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

data/lib/simplecov/cli/coverage_file.rb

@@ -5,29 +5,76 @@ 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
+    # coverage.json. It validates only the stable outer shape, so older schema
     # versions remain readable.
     module CoverageFile
-      # The coverage.json fields backing each criterion, keyed by the
-      # criterion's singular name. The one table the coverage, uncovered,
-      # and diff subcommands all read from, so a schema change lands in
-      # exactly one place.
       CRITERIA = {
         line: {label: "Line", percent: "lines_covered_percent",
-               covered: "covered_lines", total: "total_lines"},
+               covered: "covered_lines", missed: "missed_lines", total: "total_lines"},
         branch: {label: "Branch", percent: "branches_covered_percent",
-                 covered: "covered_branches", total: "total_branches"},
+                 covered: "covered_branches", missed: "missed_branches", total: "total_branches"},
         method: {label: "Method", percent: "methods_covered_percent",
-                 covered: "covered_methods", total: "total_methods"}
+                 covered: "covered_methods", missed: "missed_methods", total: "total_methods"}
       }.freeze
 
-    module_function
+      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:)
-        SimpleCov::CoverageJSON.load(path)
+        CoverageJSON.load(path)
       rescue Errno::ENOENT
         report_missing(stderr, command, path)
-      rescue SimpleCov::CoverageJSON::Error => e
+      rescue CoverageJSON::Error => e
         report_invalid(stderr, command, path, e.message)
       rescue SystemCallError => e
         report_unreadable(stderr, command, path, e.message)
@@ -47,18 +94,15 @@ module SimpleCov
       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})")
-        nil
       end
 
       def report_missing(stderr, command, path)
         stderr.puts("simplecov #{command}: #{path} not found")
-        nil
       end
 
       def report_unreadable(stderr, command, path, reason)
         detail = reason.lines.first.to_s.strip
         stderr.puts("simplecov #{command}: cannot read #{path.inspect} (#{detail})")
-        nil
       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