simplecov 1.1.1 → 1.3.0

data/lib/simplecov/cli/command_helpers.rb

@@ -4,19 +4,21 @@ require "optparse"
 
 module SimpleCov
   module CLI
-    # Plumbing the subcommands repeat, which their modules `extend`: the
-    # standard option trio the read-only commands share, the parse
-    # scaffold around it, the one-line error helper (prefixed with the
-    # command's own name), and the human-readable stats row `coverage`
-    # and `report` both print.
     module CommandHelpers
       STATS_ROW_FORMAT = "  %<label>-7s %<pct>s (%<covered>d / %<total>d)"
 
-      # "simplecov merge: ..." — derived from the extending module's
-      # name. The self cast collapses the mixin's view of `self` to the
-      # Module that extends it, which is what carries `name`.
+      # Raised by the shared --help switch; `CLI.dispatch` turns it into the
+      # command's own slice of the usage text. The explicit handler also overrides
+      # optparse's built-in --help, which would print a bare option summary and
+      # exit the process outright from inside the parser.
+      class HelpRequested < StandardError; end
+
       def command_name
-        (_ = self).name.split("::").last.downcase
+        name.split("::").last.downcase
+      end
+
+      def one?(count)
+        (count - 1).zero?
       end
 
       def error(stderr, message)
@@ -24,23 +26,57 @@ module SimpleCov
         1
       end
 
-      # The --input / --json / --no-color trio every read-only
-      # subcommand accepts.
+      # `error` returns 1 for an exit status; query helpers need nil so their
+      # callers can tell "reported" from a real answer.
+      def error_nil(stderr, message)
+        error(stderr, message)
+        nil
+      end
+
+      def recorded_contexts(document, opts, stderr)
+        contexts = document["contexts"]
+        if contexts.nil?
+          return error_nil(stderr, "no test contexts recorded in #{opts.fetch(:input)}. Enable `track_tests` in " \
+                                   "your `SimpleCov.start` block and rerun the suite to record them")
+        end
+        return contexts if contexts.instance_of?(Array) && contexts.all?(String)
+
+        CoverageFile.report_invalid(stderr, command_name, opts.fetch(:input), '"contexts" must be an array of strings')
+      end
+
       def common_options(parser, opts)
         parser.on("--input PATH") { |v| opts[:input] = v }
-        parser.on("--json")       { opts[:json] = true }
-        parser.on("--no-color")   { opts[:no_color] = true }
+        parser.on("--json") { opts[:json] = true }
+        parser.on("--no-color") { opts[:no_color] = true }
+      end
+
+      def build_parser
+        OptionParser.new do |parser|
+          yield parser if block_given?
+          on_help(parser)
+        end
+      end
+
+      # mutant:disable
+      # OptionParser answers `-q` as an unambiguous abbreviation of `--quiet`
+      # whether or not the short form is declared.
+      def quiet_option(parser, opts)
+        parser.on("-q", "--quiet") { opts[:quiet] = true }
+      end
+
+      # mutant:disable — optparse matches an abbreviated `-h` against
+      # `--help` whether or not the short form is declared, so dropping
+      # it changes nothing an example could see. Declared anyway, so the
+      # flag appears in the usage text.
+      def on_help(parser)
+        parser.on("--help", "-h") { raise HelpRequested }
       end
 
-      # The parse scaffold every read-only subcommand repeats: seed the
-      # shared defaults (plus the command's own), wire up the common
-      # option trio, yield the parser for command-specific flags, and
-      # return the parsed opts alongside the positional arguments.
       def parse_common(args, defaults = {})
-        opts = {input: SimpleCov::CLI.default_input, json: false, no_color: false} #: Hash[Symbol, untyped]
+        opts = {input: CLI.default_input, json: false, no_color: false} #: Hash[Symbol, untyped]
         opts.merge!(defaults)
         rest =
-          OptionParser.new do |parser|
+          build_parser do |parser|
             common_options(parser, opts)
             yield parser, opts if block_given?
           end.parse(args)

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