simplecov 0.22.0 → 1.3.0

data/lib/simplecov/cli/usage.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Usage
+      extend self
+
+      def for(cli, command)
+        sections = text(cli).split("\n\n")
+        row = sections.fetch(1).lines.find { |line| line.match?(/\A  #{Regexp.escape(command)}[ \[]/) }
+        options = sections.select { |section| section_for?(section, command) }
+        ["Usage: simplecov #{command} [options]", row&.strip, *options].compact.join("\n\n")
+      end
+
+      def section_for?(section, command)
+        header = heading_of(section)
+        header.end_with?("options:") && header.delete_suffix("options:").split(%r{[\s/]+}).include?(command)
+      end
+
+      def heading_of(section)
+        section.lines.first.to_s.strip
+      end
+
+      # A method rather than a constant so its default paths resolve at call time
+      # against the active `.simplecov`.
+      def text(cli)
+        <<~USAGE
+          Usage: simplecov <command> [options]
+
+          Commands:
+            run <command...>          Execute <command> with SimpleCov pre-loaded
+                                      (works without a test_helper hook)
+            coverage <path>           Print coverage stats for the given file
+            show <path>               Print the file's source annotated with hit counts and misses
+            report                    Print the overall summary and group totals
+            status                    Report freshness: age, commit distance, recorded tests
+            history                   Print the recorded coverage trend, a sparkline per criterion
+            badge                     Render the coverage percent as an SVG badge
+            uncovered                 List the lowest-coverage files
+            tests [<path>[:<line>]]   List recorded tests for a file or line (needs track_tests)
+            affected                  List test files touching code changed since a git ref (needs track_tests)
+            merge <files...>          Merge multiple .resultset.json files
+            diff <baseline>           Show per-file coverage delta vs baseline
+            patch                     Show coverage of the lines a change touched
+            ratchet                   Rewrite the per-file coverage baseline, only ever tightening
+            dead-code                 Cross production coverage with the report to find dead code
+            open                      Open the HTML report in the default browser
+            serve                     Serve the coverage report over HTTP
+            watch <command...>        Re-run <command> on save and live-reload the served report
+            clean                     Remove the coverage report directory
+            completions <shell>       Emit the completion script for fish, bash, or zsh
+            help                      Show this message
+            version                   Print the version (also --version / -v)
+
+          Every command answers `--help` / `-h`. Default paths follow a project's
+          `.simplecov` SimpleCov.coverage_dir (#{cli.coverage_dir} for this run).
+
+          coverage / show / report / status / uncovered / tests / affected / diff / patch / ratchet / dead-code options:
+            --input PATH              Read from PATH instead of #{cli.default_input}
+            --no-color                Disable colorized percentages (also honors NO_COLOR / FORCE_COLOR env)
+
+          coverage options:
+            --json                    Print the file's JSON entry verbatim
+
+          show options:
+            --uncovered-only          Print only <path>:<ranges> of the missed lines
+            --json                    Emit path, missed lines, per-line hits, and markers as JSON
+
+          report options:
+            --json                    Emit totals and group sections as JSON
+
+          status options:
+            --json                    Emit the freshness facts as a JSON object
+
+          history options:
+            --input PATH              Read from PATH instead of the coverage directory's .history.json
+            --file PATH               Follow one file's trajectory instead of the totals
+            --json                    Emit the entries (or the file's trajectory) as JSON
+            --no-color                Disable colorized deltas (also honors NO_COLOR / FORCE_COLOR env)
+
+          badge options:
+            --input PATH              Read from PATH instead of #{cli.default_input}
+            --output PATH             Write the badge to PATH instead of stdout
+            --criterion C             line, branch, or method (default: line)
+            --label TEXT              The badge's left-side text (default: the criterion's, like "line coverage")
+
+          uncovered options:
+            --threshold N             Only show files below N% coverage
+            --top N                   Show at most N files (default: 10)
+            --criterion C             line, branch, or method (default: line)
+            --missing                 Append the missed line ranges to each row
+            --annotate KIND           Emit CI annotations instead of rows: github, gitlab, rdjson, azure, teamcity, or buildkite
+            --json                    Emit results as a JSON array (for CI)
+
+          tests options:
+            --redundant               List only tests whose covered lines other tests also cover
+            --json                    Emit the test ids as a JSON array
+
+          affected options:
+            --base REF                Diff against the merge base of REF and HEAD (default: origin's HEAD, else main)
+            --run <command...>        Run <command> (all args after --run) with the selection appended, or bare on a full-suite fallback, exiting with the command's status
+            --json                    Emit {full_suite, triggers, tests} as a JSON object
+
+          merge options:
+            --output PATH             Write merged resultset to PATH (default: #{cli.default_resultset})
+            --honor-timeout           Drop entries older than merge_timeout
+            --dry-run                 Print what would be written without writing
+            -q, --quiet               Suppress the success status line
+
+          diff options:
+            --fail-on-drop            Exit non-zero when any file's coverage dropped vs baseline (deletions don't count)
+            --json                    Emit results as a JSON array (for CI)
+            --threshold N             Only show files whose absolute delta in any criterion is at least N%
+
+          patch options:
+            --base REF                Diff against the merge-base of REF for the touched lines (default: origin's HEAD, else main, or in CI the PR's target branch)
+            --minimum N               Exit non-zero when patch coverage on any measured criterion is below N%
+            --find-renames            Follow a renamed file instead of counting the moved file as all-new
+            --annotate KIND           Emit CI annotations instead of rows: github, gitlab, rdjson, azure, teamcity, or buildkite
+            --json                    Emit results as a JSON array (for CI)
+
+          dead-code options:
+            --production PATH         The production coverage file a SimpleCov::Production sink wrote (default: the project's `production_coverage`, required when none is configured)
+            --untested-in-production  Print code production runs that no test covers, instead of the dead rows
+            --json                    Emit every category (dead, possibly dead, untested in production) as JSON
+
+          ratchet options:
+            --baseline PATH           The baseline file to rewrite (default: the project's `baseline_file`, .simplecov_baseline.yml)
+            --init                    Regenerate from scratch: add entries for new files and reset every floor to the current state
+            --dry-run                 Print what would change without writing
+            --json                    Emit the summary (tightened / pruned / regressed entries) as JSON
+
+          open options:
+            --report PATH             Open PATH instead of #{cli.default_report}
+
+          serve options:
+            --port N                  Bind to port N (default: random open port)
+            --host HOST               Bind to HOST (default: 127.0.0.1)
+
+          watch options:
+            --port N                  Bind to port N (default: random open port)
+            --host HOST               Bind to HOST (default: 127.0.0.1)
+            --interval SECONDS        Poll the tracked files this often (default: 0.5)
+            --open                    Open the served report in the default browser
+
+          clean options:
+            --dry-run                 Print what would be removed without deleting
+            -q, --quiet               Suppress status lines
+        USAGE
+      end
+    end
+  end
+end

data/lib/simplecov/cli/watch/live_report.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Watch
+      # The live half of the watch server: an /events endpoint streaming
+      # server-sent events to every open report tab, and an index route that
+      # appends the reload listener to the artifact on the way out, so the report
+      # on disk stays byte-identical to a plain run's.
+      class LiveReport
+        RELOAD_SCRIPT = "\n<script>new EventSource('/events').onmessage = () => location.reload();</script>\n"
+
+        def initialize(dir)
+          @dir = dir
+          @queues = [] #: Array[Thread::Queue]
+          @lock = Mutex.new
+        end
+
+        def routes
+          page = method(:page)
+          {"/events" => method(:stream), "/" => page, "/index.html" => page}
+        end
+
+        def broadcast(event = "reload")
+          with_queues { |queues| queues.each { |queue| queue << event } }
+        end
+
+        private
+
+        # Holds the connection open, forwarding each broadcast as one SSE message,
+        # until the tab goes away and the write fails. A closed tab that never sees
+        # another broadcast parks its thread on the queue, a leak the dev-server
+        # trade accepts.
+        def stream(client)
+          queue = Queue.new #: Thread::Queue
+          begin
+            with_queues { |queues| queues << queue }
+            forward(client, queue)
+          ensure
+            with_queues { |queues| queues.delete(queue) }
+          end
+        end
+
+        def forward(client, queue)
+          client.write("HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\n" \
+                       "Cache-Control: no-cache\r\n\r\n")
+          loop { client.write("data: #{next_event(queue)}\n\n") }
+        rescue IOError, SystemCallError
+          nil
+        end
+
+        # mutant:disable
+        def next_event(queue)
+          queue.pop
+        end
+
+        def page(client)
+          body = File.binread(File.join(@dir, "index.html")) + RELOAD_SCRIPT
+          Serve::StaticFileHandler.respond(client, 200, body, "text/html; charset=utf-8")
+        rescue SystemCallError
+          Serve::StaticFileHandler.respond(client, 404)
+        end
+
+        # mutant:disable
+        # Every touch of the queue registry goes through the lock: an accept thread
+        # adds and drops its own queue while the session thread walks them all.
+        def with_queues
+          @lock.synchronize { yield @queues }
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/watch/narrator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Watch
+      class Narrator
+        def initialize(stdout, root)
+          @stdout = stdout
+          @root = root
+        end
+
+        def banner(server, count)
+          host = Serve.url_host(server.addr.fetch(3))
+          @stdout.puts("watching #{count} file#{"s" unless count.eql?(1)}, " \
+                       "serving http://#{host}:#{server.addr.fetch(1)}/")
+          @stdout.puts("Press Ctrl-C to stop.")
+        end
+
+        def change(changed, plan)
+          named = name(changed)
+          return @stdout.puts("#{named} changed, no recorded test touches it") unless plan.fetch(:run)
+
+          @stdout.print("#{named} changed, #{action(plan.fetch(:tests))}...")
+        end
+
+        def result(before, after)
+          return @stdout.puts unless after
+
+          delta = before ? format(" (%+.2f%%)", after - before) : ""
+          @stdout.puts(format(" %.2f%%", after) + delta)
+        end
+
+        def failed_refresh
+          @stdout.puts(" the report did not regenerate")
+        end
+
+        def stopping
+          @stdout.puts("\nsimplecov watch: stopping")
+        end
+
+        private
+
+        def name(changed)
+          relative = changed.map { |path| path.delete_prefix("#{@root}/") }
+          named = relative.first
+          relative.size.eql?(1) ? named : "#{named} and #{relative.size - 1} more"
+        end
+
+        def action(tests)
+          tests ? "running #{tests.size} file#{"s" unless tests.one?}" : "running the full suite"
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/watch/poller.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Watch
+      # Watches a fixed set of paths by polling mtimes, the trade chosen over a
+      # filesystem-event dependency for a command that is optional to begin with.
+      # Editors that save through a temporary file plus rename still move the final
+      # path's mtime, which is all this looks at.
+      class Poller
+        def initialize
+          @snapshot = {} #: Hash[String, untyped]
+        end
+
+        # Replaces the watched set, snapshotting current mtimes. A path with no file
+        # snapshots as nil, so appearing counts as a change.
+        def watch(paths)
+          @snapshot = paths.to_h { |path| [path, stamp(path)] }
+        end
+
+        def size
+          @snapshot.size
+        end
+
+        def changes
+          changed = [] #: Array[String]
+          @snapshot.each_key do |path|
+            now = stamp(path)
+            next if now.eql?(@snapshot.fetch(path))
+
+            @snapshot[path] = now
+            changed << path
+          end
+          changed
+        end
+
+        def stamp(path)
+          File.mtime(path)
+        rescue SystemCallError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/watch/session.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Watch
+      # One watch session: accept report connections in the background, poll the
+      # tracked set for changes, re-run tests on save (selecting over the recorded
+      # test map when the report carries one), and push a reload to every open tab
+      # when the report regenerates.
+      class Session
+        # The merge window the child runs get through SIMPLECOV_MERGE_TIMEOUT: a
+        # day, so subset re-runs keep merging into a whole report across a long
+        # session instead of eroding it after the default ten minutes.
+        MERGE_WINDOW = "86400"
+
+        TOTALS_KEYS = {"line" => "lines", "branch" => "branches", "method" => "methods"}.freeze
+
+        def initialize(command:, dir:, interval:, stdout:, stderr:)
+          @command = command
+          @dir = dir
+          @interval = interval
+          @stderr = stderr
+          @root = Dir.pwd
+          @narrator = Narrator.new(stdout, @root)
+          @live = LiveReport.new(dir)
+          @poller = Poller.new
+          @document = {} #: Hash[String, untyped]
+        end
+
+        def run(server)
+          accept_loop(server)
+          run_tests(nil) unless File.exist?(json_path)
+          return 1 unless refresh
+
+          @narrator.banner(server, @poller.size)
+          poll_forever
+        rescue Interrupt
+          @narrator.stopping
+          0
+        end
+
+        def poll_forever
+          loop do
+            sleep(@interval)
+            step
+          end
+        end
+
+        def step
+          changed = settled_changes
+          return if changed.empty?
+
+          plan = plan_for(changed)
+          @narrator.change(changed, plan)
+          return unless plan.fetch(:run)
+
+          before = total_percent
+          run_tests(plan.fetch(:tests))
+          return @narrator.failed_refresh unless refresh
+
+          @live.broadcast
+          @narrator.result(before, total_percent)
+        end
+
+        private
+
+        def accept_loop(server)
+          Thread.new do
+            loop do
+              Thread.new(server.accept) do |client|
+                Serve::StaticFileHandler.handle_connection(client, @dir, @live.routes)
+              end
+            end
+          rescue IOError, SystemCallError
+            nil
+          end
+        end
+
+        def plan_for(changed)
+          relative = changed.map { |path| path.delete_prefix("#{@root}/") }
+          TestPlan.build(relative, @document, root: @root, input: json_path, stderr: @stderr)
+        end
+
+        # The command is the project's own test invocation and must produce the
+        # report itself. A selection is appended to it; no selection means the whole
+        # suite, which is the command on its own.
+        def run_tests(tests)
+          env = {"SIMPLECOV_MERGE_TIMEOUT" => MERGE_WINDOW}
+          Kernel.system(env, *(tests ? @command + tests : @command))
+        end
+
+        # The regenerated report is both the watch set and the totals the result line
+        # diffs against. The previous document is kept when the read fails, so one
+        # bad write doesn't blind the session.
+        def refresh
+          document = CoverageFile.load_document(json_path, command: "watch", stderr: @stderr)
+          return false unless document
+
+          @document = document
+          @poller.watch(TestPlan.watched_paths(document, @root))
+          document
+        end
+
+        # Editors save in bursts, so after the first detection keep polling until a
+        # full interval passes with nothing new.
+        def settled_changes
+          changed = @poller.changes
+          return changed if changed.empty?
+
+          loop do
+            sleep(@interval)
+            more = @poller.changes
+            break if more.empty?
+
+            changed |= more
+          end
+          changed
+        end
+
+        # Follows the report's own primary criterion, falling back to line coverage
+        # for documents from before meta carried one.
+        def total_percent
+          key = TOTALS_KEYS[@document.dig("meta", "primary_coverage")] || "lines"
+          value = @document.dig("total", key, "percent")
+          (_ = value).to_f if value.is_a?(Numeric)
+        end
+
+        def json_path
+          File.join(@dir, "coverage.json")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/watch/test_plan.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Watch
+      module TestPlan
+        extend self
+
+        # {run:, tests:} where nil tests mean the full command. A report with no map,
+        # a malformed one, or any fail-open trigger runs everything; an empty
+        # selection runs nothing.
+        def build(changed, document, root:, input:, stderr:)
+          contexts = document["contexts"]
+          return {run: true, tests: nil} unless contexts.instance_of?(Array) && contexts.all?(String)
+
+          selection = Affected::Selection.build(changed, document, contexts, {input: input}, stderr, root: root)
+          return {run: true, tests: nil} if selection.nil? || !selection.fetch(:triggers).empty?
+          return {run: false, tests: []} if selection.fetch(:tests).empty?
+
+          {run: true, tests: selection.fetch(:tests)}
+        end
+
+        # The watch set a report defines: its tracked files plus the files of its
+        # recorded tests.
+        def watched_paths(document, root)
+          none = [] #: Array[String]
+          coverage = document["coverage"]
+          sources = coverage.instance_of?(Hash) ? coverage.keys : none
+          tests = recorded_test_files(document).map { |path| File.expand_path(path, root) }
+          (sources + tests).uniq
+        end
+
+        def recorded_test_files(document)
+          none = [] #: Array[String]
+          contexts = document["contexts"]
+          return none unless contexts.instance_of?(Array)
+
+          contexts.filter_map { |id| Affected::Selection.test_file_of(id.to_s) }
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/watch.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+require_relative "open"
+require_relative "serve"
+require_relative "affected"
+require_relative "watch/poller"
+require_relative "watch/live_report"
+require_relative "watch/narrator"
+require_relative "watch/test_plan"
+require_relative "watch/session"
+
+module SimpleCov
+  module CLI
+    # `simplecov watch <command...>`: the coverage inner loop. Serves the report
+    # the way `serve` does, polls the tracked files for saves, re-runs the given
+    # command on change, and pushes a reload to the open tab over server-sent
+    # events when the report regenerates. With a `track_tests` recording in the
+    # report, a save re-runs only the tests that touch the changed files, by the
+    # same selection walk `simplecov affected` uses.
+    module Watch
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        opts, command = parse(args)
+        return error(stderr, "missing command to run (e.g. `simplecov watch bundle exec rspec`)") if command.empty?
+
+        Serve.require_socket
+        server = bind(opts, stderr)
+        return 1 unless server
+
+        serve_session(server, command, opts, stdout, stderr)
+      end
+
+      def serve_session(server, command, opts, stdout, stderr)
+        launch_browser(server, stderr) if opts.fetch(:open)
+        session_for(command, opts, stdout, stderr).run(server)
+      ensure
+        server.close
+      end
+
+      # Fire-and-forget through the same platform opener `simplecov open` uses,
+      # detached so the session never waits on a browser. A platform with no known
+      # opener notes the URL instead of failing the watch.
+      def launch_browser(server, stderr)
+        url = "http://#{Serve.url_host(server.addr.fetch(3))}:#{server.addr.fetch(1)}/"
+        opener = Open.browser_opener
+        unless opener
+          return stderr.puts("simplecov watch: no known browser opener for this platform, open it yourself: #{url}")
+        end
+
+        Process.detach(spawn(*opener, url, out: File::NULL, err: File::NULL))
+      end
+
+      # `order` rather than `parse` stops at the first positional, so the runner
+      # command keeps its own flags: `simplecov watch bundle exec rspec --seed 1`
+      # passes --seed through untouched.
+      def parse(args)
+        opts = {port: 0, host: "127.0.0.1", interval: 0.5, open: false} #: Hash[Symbol, untyped]
+        rest =
+          build_parser do |parser|
+            parser.on("--port N", Integer) { |v| opts[:port] = v }
+            parser.on("--host HOST") { |v| opts[:host] = v }
+            parser.on("--interval SECONDS", Float) { |v| opts[:interval] = v }
+            parser.on("--open") { opts[:open] = true }
+          end.order(args)
+        [opts, rest]
+      end
+
+      def bind(opts, stderr)
+        (_ = TCPServer).new(opts.fetch(:host), opts.fetch(:port)) #: TCPServer
+      rescue SystemCallError, SocketError => e
+        error_nil(stderr, "cannot bind to #{opts.fetch(:host)}:#{opts.fetch(:port)} (#{e})")
+      end
+
+      def session_for(command, opts, stdout, stderr)
+        Session.new(command: command, dir: CLI.coverage_dir,
+          interval: opts.fetch(:interval), stdout: stdout, stderr: stderr)
+      end
+    end
+  end
+end