simplecov 1.1.1 → 1.2.0

data/lib/simplecov/cli/affected/selection.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Affected
+      module Selection
+        TEST_FILE_NAME = /\A(?:test_.*|.*_(?:test|spec))\.rb\z/
+
+        extend self
+
+        def build(changed, document, contexts, opts, stderr, root:)
+          none = {} #: Hash[String, untyped]
+          coverage = document.fetch("coverage", none)
+          unless coverage.instance_of?(Hash)
+            return CoverageFile.report_invalid(stderr, "affected", opts.fetch(:input), '"coverage" must be an object')
+          end
+
+          state = initial_state(changed, contexts, coverage, opts, stderr, root: root)
+          return nil unless changed.all? { |path| classify(path, state) }
+
+          {tests: state.fetch(:tests).uniq.sort, triggers: state.fetch(:triggers)}
+        end
+
+        def initial_state(changed, contexts, coverage, opts, stderr, root:)
+          {
+            tests: [], triggers: [], changed: changed, contexts: contexts,
+            known: contexts.each_with_object(Set.new) { |id, set| set << test_file_of(id) },
+            index: CoverageFile.exact_index(coverage), root: root, opts: opts, stderr: stderr
+          } #: Hash[Symbol, untyped]
+        end
+
+        # A recorded test file selects itself, a file the report covers selects the
+        # files of the tests touching it, a test-looking file the map has never seen
+        # always runs, and anything else is a trigger. Changed paths are exact
+        # root-relative names, so they resolve against the report exactly: a
+        # lookalike entry elsewhere must not stand in for a file it doesn't carry.
+        def classify(path, state)
+          entry = entry_for(path, state)
+          if state.fetch(:known).include?(path)
+            select_test_file(path, state)
+          elsif entry
+            select_covering(path, entry, state)
+          elsif TEST_FILE_NAME.match?(File.basename(path))
+            select_test_file(path, state, note_deleted: false)
+          else
+            note_untracked(path, state)
+          end
+        end
+
+        def note_untracked(path, state)
+          state.fetch(:triggers) << "#{path} changed but #{state.fetch(:opts).fetch(:input)} has no data for it"
+        end
+
+        # A changed test file runs, unless the change is its deletion: its tests are
+        # gone, which removes them from the answer without distrusting the map.
+        def select_test_file(path, state, note_deleted: true)
+          if on_disk?(path, state)
+            state.fetch(:tests) << path
+          elsif note_deleted
+            state.fetch(:stderr).puts("simplecov affected: skipping deleted test file #{path}")
+          end
+          path
+        end
+
+        # Existence judged at the repository root the paths are relative to, not the
+        # cwd, so a subdirectory run answers the same.
+        def on_disk?(path, state)
+          File.exist?(File.expand_path(path, state.fetch(:root)))
+        end
+
+        def entry_for(path, state)
+          state.fetch(:index)[File.expand_path(path, state.fetch(:root))] || state.fetch(:index)[path]
+        end
+
+        def select_covering(path, entry, state)
+          table = covering_table(path, entry, state)
+          table&.each_key { |index| select_context(state.fetch(:contexts).fetch(index), path, state) }
+        end
+
+        def covering_table(path, entry, state)
+          unless entry.instance_of?(Hash)
+            return CoverageFile.report_invalid(state.fetch(:stderr), "affected", state.fetch(:opts).fetch(:input),
+              "entry for #{path} must be an object")
+          end
+
+          raw = entry["contexts"] || {}
+          table = raw.instance_of?(Hash) && Tests.decode_table(raw, state.fetch(:contexts).size)
+          return table if table
+
+          CoverageFile.report_invalid(state.fetch(:stderr), "affected", state.fetch(:opts).fetch(:input),
+            "entry for #{path} carries a malformed \"contexts\" table")
+        end
+
+        # Selected via its file, or a staleness trigger when it has no file to
+        # select: a locationless id, or a file that exists neither on disk nor in
+        # the change.
+        def select_context(id, path, state)
+          file = test_file_of(id)
+          if file.nil?
+            state.fetch(:triggers) << "recorded test #{id} touches #{path} but has no file location"
+          elsif on_disk?(file, state)
+            state.fetch(:tests) << file
+          elsif !state.fetch(:changed).include?(file)
+            state.fetch(:triggers) << "recorded test file #{file} no longer exists"
+          end
+        end
+
+        # "spec/a_spec.rb:12" and the :file granularity's bare "spec/a_spec.rb" both
+        # name a file, while a locationless fallback id names none.
+        def test_file_of(id)
+          base = id.sub(/:\d+\z/, "")
+          base if base.include?("/") || base.end_with?(".rb")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/affected.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+require_relative "tests"
+require_relative "affected/changed_files"
+require_relative "affected/selection"
+
+module SimpleCov
+  module CLI
+    # `simplecov affected`: select the test files whose recorded tests touch the
+    # code changed since a git base ref, from a coverage.json written under
+    # `track_tests`. The change is everything between the merge base of `--base`
+    # and the working tree, plus untracked files.
+    #
+    # The set intersection is the easy half; the hard half is knowing when to
+    # distrust the map, because a test map is stale the moment something changes
+    # that no test mentions by name. Any changed file outside the tracked set
+    # fails open to the full suite, out loud: each trigger is named on stderr and
+    # stdout stays empty, which a bare runner reads as "run everything". Test
+    # files always select themselves, recorded or not.
+    module Affected
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        issue = precheck(opts)
+        return error(stderr, issue) if issue
+
+        document = CoverageFile.load_document(opts.fetch(:input), command: "affected", stderr: stderr)
+        return 1 unless document
+
+        contexts = recorded_contexts(document, opts, stderr)
+        return 1 unless contexts
+
+        diffed = ChangedFiles.call(opts[:base] ||= Git.default_base, stderr)
+        return 1 unless diffed
+
+        respond(diffed, document, contexts, opts, stdout: stdout, stderr: stderr)
+      end
+
+      def parse(args)
+        head, runner = split_runner(args)
+        opts, rest = parse_common(head, base: nil, run: runner) do |parser, into|
+          parser.on("--base REF") { |v| into[:base] = v }
+        end
+        opts[:rest] = rest
+        opts
+      end
+
+      # Everything after `--run` is the runner command, verbatim, so the command's
+      # own flags never collide with ours.
+      def split_runner(args)
+        index = args.index("--run")
+        return [args, nil] unless index
+
+        [args.take(index), args.drop(index + 1)]
+      end
+
+      # A stray positional looks exactly like a forgotten `--base` ref, and
+      # silently dropping it would select tests for the wrong change.
+      def precheck(opts)
+        stray = opts.fetch(:rest).first
+        return "unexpected argument #{stray.inspect} (did you mean `--base #{stray}`?)" if stray
+        return "missing command after --run" if opts.fetch(:run) && opts.fetch(:run).empty?
+
+        "--run and --json cannot be combined" if opts.fetch(:run) && opts.fetch(:json)
+      end
+
+      def respond(diffed, document, contexts, opts, stdout:, stderr:)
+        opts[:root] = diffed.fetch(:root)
+        return no_changes(opts, stdout, stderr) if diffed.fetch(:changed).empty?
+
+        selection = Selection.build(diffed.fetch(:changed), document, contexts, opts, stderr, root: diffed.fetch(:root))
+        return 1 unless selection
+
+        deliver(selection, opts, stdout, stderr)
+      end
+
+      def no_changes(opts, stdout, stderr)
+        stderr.puts("simplecov affected: no changes against #{opts.fetch(:base)}")
+        empty = {tests: [], triggers: []} #: Hash[Symbol, Array[String]]
+        emit_json(empty, false, stdout) if opts.fetch(:json)
+        0
+      end
+
+      def deliver(selection, opts, stdout, stderr)
+        full = !selection.fetch(:triggers).empty?
+        selection.fetch(:triggers).each { |trigger| stderr.puts("simplecov affected: #{trigger}") }
+        stderr.puts("simplecov affected: falling back to the full suite") if full
+        return emit_json(selection, full, stdout) if opts.fetch(:json)
+        return execute(selection, full, opts, stderr) if opts.fetch(:run)
+
+        emit_text(selection, full, stdout, stderr)
+      end
+
+      def emit_json(selection, full, stdout)
+        none = [] #: Array[String]
+        stdout.puts(JSON.pretty_generate("full_suite" => full, "triggers" => selection.fetch(:triggers),
+          "tests" => full ? none : selection.fetch(:tests)))
+        0
+      end
+
+      # Stdout carries the selected files and nothing else, so the list can feed a
+      # runner directly, and a full-suite fallback prints nothing, which
+      # `rspec $(simplecov affected)` reads as "run everything".
+      def emit_text(selection, full, stdout, stderr)
+        return 0 if full
+
+        tests = selection.fetch(:tests)
+        if tests.empty?
+          note_untouched(stderr)
+        else
+          tests.each { |file| stdout.puts(file) }
+          0
+        end
+      end
+
+      def note_untouched(stderr)
+        stderr.puts("simplecov affected: no recorded test touches the changed code")
+        0
+      end
+
+      def execute(selection, full, opts, stderr)
+        return run_command(opts.fetch(:run), opts.fetch(:root), stderr) if full
+        return note_untouched(stderr) if selection.fetch(:tests).empty?
+
+        count = selection.fetch(:tests).size
+        stderr.puts("simplecov affected: running #{count} test file#{"s" unless count.eql?(1)}")
+        run_command(opts.fetch(:run) + selection.fetch(:tests), opts.fetch(:root), stderr)
+      end
+
+      # The selection's paths are relative to the repository root, so the runner
+      # starts there. The command is named explicitly in the failure because not
+      # every engine's exception message carries it.
+      def run_command(command, root, stderr)
+        _, status = Process.wait2(spawn(*command, chdir: root))
+        status.exitstatus || 1
+      rescue SystemCallError => e
+        stderr.puts("simplecov affected: cannot run #{command.first.inspect} (#{e})")
+        127
+      end
+    end
+  end
+end

data/lib/simplecov/cli/badge/svg.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Badge
+      # Renders the badge SVG in shields.io's flat style: 20px tall with 3px
+      # rounded corners, the label on #555 and the value on its ladder color, each
+      # text drawn twice for the drop shadow at 10x scale. `textLength` pins the
+      # layout, so the estimated segment widths never let glyphs spill.
+      module Svg
+        extend self
+
+        COLORS = [[90, "#4c1"], [80, "#97ca00"], [70, "#a4a61d"], [60, "#dfb317"], [50, "#fe7d37"]].freeze
+
+        def color(percent)
+          rung = COLORS.detect { |floor, _color| percent >= floor }
+          rung ? rung.fetch(1) : "#e05d44"
+        end
+
+        def render(label:, percent:)
+          value = format("%.2f%%", percent)
+          document(label: escape(label), value: value, fill: color(percent),
+            geo: geometry(width(label), width(value)))
+        end
+
+        # Estimates 11px Verdana; `textLength` absorbs the error.
+        def width(text)
+          (7 * text.length) + 10
+        end
+
+        # The scale(.1) trick draws text at 10x and shrinks it, so the text
+        # coordinates live in a 10x space: centers at 10 * (offset + width / 2) and
+        # textLength spanning the width less padding.
+        def geometry(label_width, value_width)
+          {label_width: label_width, value_width: value_width, total: label_width + value_width,
+           label_x: 5 * label_width, value_x: (10 * label_width) + (5 * value_width),
+           label_span: 10 * (label_width - 10), value_span: 10 * (value_width - 10)}
+        end
+
+        def escape(text)
+          text.gsub(/[&<>"]/, "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;")
+        end
+
+        def document(label:, value:, fill:, geo:)
+          <<~SVG
+            <svg xmlns="http://www.w3.org/2000/svg" width="#{geo.fetch(:total)}" height="20" role="img" aria-label="#{label}: #{value}">
+              <title>#{label}: #{value}</title>
+              <linearGradient id="s" x2="0" y2="100%">
+                <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+                <stop offset="1" stop-opacity=".1"/>
+              </linearGradient>
+              <clipPath id="r"><rect width="#{geo.fetch(:total)}" height="20" rx="3" fill="#fff"/></clipPath>
+              <g clip-path="url(#r)">
+                <rect width="#{geo.fetch(:label_width)}" height="20" fill="#555"/>
+                <rect x="#{geo.fetch(:label_width)}" width="#{geo.fetch(:value_width)}" height="20" fill="#{fill}"/>
+                <rect width="#{geo.fetch(:total)}" height="20" fill="url(#s)"/>
+              </g>
+              <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+                <text aria-hidden="true" x="#{geo.fetch(:label_x)}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="#{geo.fetch(:label_span)}">#{label}</text>
+                <text x="#{geo.fetch(:label_x)}" y="140" transform="scale(.1)" fill="#fff" textLength="#{geo.fetch(:label_span)}">#{label}</text>
+                <text aria-hidden="true" x="#{geo.fetch(:value_x)}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="#{geo.fetch(:value_span)}">#{value}</text>
+                <text x="#{geo.fetch(:value_x)}" y="140" transform="scale(.1)" fill="#fff" textLength="#{geo.fetch(:value_span)}">#{value}</text>
+              </g>
+            </svg>
+          SVG
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/badge.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+require_relative "coverage_file"
+require_relative "badge/svg"
+
+module SimpleCov
+  module CLI
+    module Badge
+      extend CommandHelpers
+
+      extend self
+
+      TOTAL_KEYS = {line: "lines", branch: "branches", method: "methods"}.freeze
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        key = TOTAL_KEYS[opts.fetch(:criterion)]
+        unless key
+          return error(stderr,
+            "unknown --criterion #{opts.fetch(:criterion).inspect} (expected line, branch, or method)")
+        end
+
+        percent = percent_for(opts, key, stderr)
+        return 1 unless percent
+
+        label = opts.fetch(:label) || "#{opts.fetch(:criterion)} coverage"
+        emit(Svg.render(label: label, percent: percent), opts, stdout)
+      end
+
+      def parse(args)
+        opts = {input: CLI.default_input, criterion: :line,
+                label: nil, output: nil} #: Hash[Symbol, untyped]
+        build_parser do |parser|
+          parser.on("--input PATH") { |v| opts[:input] = v }
+          parser.on("--output PATH") { |v| opts[:output] = v }
+          parser.on("--criterion C") { |v| opts[:criterion] = v.to_sym }
+          parser.on("--label TEXT") { |v| opts[:label] = v }
+        end.parse(args)
+        opts
+      end
+
+      def percent_for(opts, key, stderr)
+        document = CoverageFile.load_document(opts.fetch(:input), command: "badge", stderr: stderr)
+        return nil unless document
+
+        totals = document["total"]
+        percent = totals.dig(key, "percent") if totals.is_a?(Hash)
+        return percent if percent.is_a?(Numeric)
+
+        error_nil(stderr, "no #{opts.fetch(:criterion)} totals in #{opts.fetch(:input)} " \
+                          "(was the run measuring #{opts.fetch(:criterion)} coverage?)")
+      end
+
+      def emit(svg, opts, stdout)
+        opts.fetch(:output) ? File.write(opts.fetch(:output), svg) : stdout.puts(svg)
+        0
+      end
+    end
+  end
+end

data/lib/simplecov/cli/clean.rb

@@ -1,22 +1,21 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "optparse"
 require_relative "command_helpers"
 
 module SimpleCov
   module CLI
-    # `simplecov clean [--dry-run]` — remove the coverage report
-    # directory (or whatever `SimpleCov.coverage_dir` resolves to). The
-    # `--dry-run` flag prints what would be deleted without touching
-    # disk, for when you're not sure what's in there.
+    # `simplecov clean [--dry-run]`: remove the coverage report directory.
+    # `--dry-run` prints what would be deleted without touching disk.
     module Clean
       extend CommandHelpers
 
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:, **)
         opts = parse(args)
-        dir = SimpleCov::CLI.coverage_dir
+        dir = CLI.coverage_dir
         return error(stderr, "refusing to remove unsafe coverage directory #{dir.inspect}") unless safe_to_remove?(dir)
         return announce(stdout, opts, "#{dir} doesn't exist; nothing to do") || 0 unless File.directory?(dir)
 
@@ -25,45 +24,45 @@ module SimpleCov
       end
 
       def sweep(dir, opts, stdout)
-        if opts[:dry_run]
+        if opts.fetch(:dry_run)
           announce(stdout, opts, "would remove #{dir} (#{entry_count(dir)} entries)")
         else
-          require "fileutils"
           FileUtils.rm_rf(dir)
           announce(stdout, opts, "removed #{dir}")
         end
       end
 
-      # FNM_DOTMATCH so the dotfiles rm_rf will actually delete
-      # (.resultset.json, .last_run.json) count too; the glob still
-      # yields the directory's own "." entry, which rm_rf does not
+      # FNM_DOTMATCH so the dotfiles rm_rf will actually delete count too. The
+      # glob still yields the directory's own "." entry, which rm_rf does not
       # remove separately.
       def entry_count(dir)
         Dir.glob("#{dir}/**/*", File::FNM_DOTMATCH).count { |path| !path.end_with?("/.") }
       end
 
       def announce(stdout, opts, message)
-        stdout.puts("simplecov #{command_name}: #{message}") unless opts[:quiet]
+        stdout.puts("simplecov #{command_name}: #{message}") unless opts.fetch(:quiet)
       end
 
+      # A filesystem root is its own dirname, on every platform and every Windows
+      # drive. The descendant check only protects roots that happen to contain the
+      # cwd, which misses other drives, so roots are refused outright.
       def safe_to_remove?(dir)
         target = canonical_path(dir)
-        # A filesystem root is its own dirname ("/" everywhere, drive
-        # roots like "D:/" on Windows). The descendant check below only
-        # protects roots that happen to contain the cwd or project root,
-        # which misses other drives, so refuse roots outright.
-        return false if File.dirname(target) == target
+        return false if File.dirname(target).eql?(target)
 
-        protected_paths.none? { |path| path == target || descendant_of?(path, target) }
+        protected_paths.none? { |path| path.eql?(target) || descendant_of?(path, target) }
       end
 
+      # The working directory, which a coverage directory must not be or contain.
+      # The `.simplecov` project root needs no entry of its own: `Dotfile.find`
+      # walks up from the working directory, so any target containing that root
+      # contains the working directory too.
       def protected_paths
-        project_root = SimpleCov::CLI::Dotfile.find
-        [Dir.pwd, (File.dirname(project_root) if project_root)].compact.map { |path| canonical_path(path) }.uniq
+        [canonical_path(Dir.pwd)]
       end
 
-      # Canonical paths only carry a trailing separator on a filesystem
-      # root, and roots are refused before this check runs.
+      # Canonical paths only carry a trailing separator on a filesystem root, and
+      # roots are refused before this check runs.
       def descendant_of?(path, possible_ancestor)
         path.start_with?("#{possible_ancestor}#{File::SEPARATOR}")
       end
@@ -76,9 +75,9 @@ module SimpleCov
 
       def parse(args)
         opts = {dry_run: false, quiet: false}
-        OptionParser.new do |o|
+        build_parser do |o|
           o.on("--dry-run") { opts[:dry_run] = true }
-          o.on("-q", "--quiet") { opts[:quiet] = true }
+          quiet_option(o, opts)
         end.parse(args)
         opts
       end

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)