simplecov 1.1.1 → 1.3.0

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

data/lib/simplecov/cli.rb

@@ -1,50 +1,67 @@
 # frozen_string_literal: true
 
 require "optparse"
+require_relative "version"
 require_relative "color"
 require_relative "cli/dotfile"
+require_relative "cli/badge"
 require_relative "cli/clean"
+require_relative "cli/completions"
 require_relative "cli/coverage_file"
 require_relative "cli/coverage"
+require_relative "cli/dead_code"
 require_relative "cli/diff"
+require_relative "cli/history"
 require_relative "cli/merge"
 require_relative "cli/open"
+require_relative "cli/patch"
+require_relative "cli/ratchet"
 require_relative "cli/report"
 require_relative "cli/run"
 require_relative "cli/serve"
+require_relative "cli/show"
+require_relative "cli/status"
+require_relative "cli/tests"
+require_relative "cli/affected"
 require_relative "cli/uncovered"
+require_relative "cli/usage"
+require_relative "cli/watch"
 
 module SimpleCov
-  # Lightweight command-line front-end. `run` dispatches a subcommand
-  # (`coverage`, `report`, `uncovered`, `merge`, `diff`, `open`, etc.) —
-  # see the `usage` text below for the full list, or run `simplecov help`.
-  #
-  # Read-only subcommands consume JSONFormatter output (`coverage.json`),
-  # which the bundled HTMLFormatter already drops alongside the HTML, so
-  # no runtime hooking is needed for those. Default paths follow the
-  # project's `.simplecov` `SimpleCov.coverage_dir` setting when one is
-  # present, so a project that writes its report somewhere other than
-  # `coverage/` doesn't have to pass `--input` / `--report` every
-  # invocation.
+  # Lightweight command-line front-end. Read-only subcommands consume
+  # JSONFormatter output, which the bundled HTMLFormatter already drops
+  # alongside the HTML, so no runtime hooking is needed for those. Default
+  # paths follow the project's `.simplecov` `coverage_dir` setting when one is
+  # present.
   module CLI
     COMMANDS = {
       "coverage" => Coverage,
+      "show" => Show,
       "run" => Run,
       "open" => Open,
       "report" => Report,
+      "status" => Status,
+      "history" => History,
       "uncovered" => Uncovered,
+      "tests" => Tests,
+      "affected" => Affected,
       "merge" => Merge,
       "diff" => Diff,
+      "patch" => Patch,
+      "ratchet" => Ratchet,
+      "dead-code" => DeadCode,
       "serve" => Serve,
-      "clean" => Clean
+      "watch" => Watch,
+      "badge" => Badge,
+      "clean" => Clean,
+      "completions" => Completions
     }.freeze
 
-  module_function
+    extend self
 
-    # Resolved once per process. Walks up from cwd looking for a
-    # `.simplecov`; if present, the file is loaded with
-    # `SimpleCov.start` neutered so it can't trigger coverage tracking
-    # or an at_exit hook just because we asked it for a config value.
+    # Resolved once per process, by walking up from cwd for a `.simplecov` and
+    # loading it with `SimpleCov.start` neutered so it can't trigger tracking
+    # just because we asked it for a config value.
     def coverage_dir
       @coverage_dir ||= Dotfile.coverage_dir
     end
@@ -53,14 +70,10 @@ module SimpleCov
       File.join(coverage_dir, "coverage.json")
     end
 
-    # Resolve "should this subcommand colorize?" once per invocation.
-    # `--no-color` (opts[:no_color]) is the per-invocation kill-switch;
-    # otherwise we defer to `SimpleCov::Color.enabled?`, which honors
-    # `NO_COLOR` / `FORCE_COLOR` and falls back to `stream.tty?`.
     def color_enabled?(opts, stream)
       return false if opts[:no_color]
 
-      SimpleCov::Color.enabled?(stream)
+      Color.enabled?(stream)
     end
 
     def default_report
@@ -71,93 +84,31 @@ module SimpleCov
       File.join(coverage_dir, ".resultset.json")
     end
 
-    # Returns a process exit status (0 on success, non-zero on error).
     def run(argv, stdout: $stdout, stderr: $stderr)
       command, *rest = argv
       handler = COMMANDS[command]
       return dispatch(handler, command, rest, stdout: stdout, stderr: stderr) if handler
       return stdout.puts(usage) || 0 if [nil, "help", "--help", "-h"].include?(command)
+      return stdout.puts("simplecov #{VERSION}") || 0 if %w[version --version -v].include?(command)
 
       stderr.puts("simplecov: unknown command #{command.inspect}", usage)
       1
     end
 
-    # One rescue covers every subcommand's OptionParser, so a typo'd
-    # flag or a malformed typed argument becomes a one-line error and
-    # exit status 1 instead of an unhandled-exception backtrace.
+    # One rescue covers every subcommand's OptionParser, so a typo'd flag becomes
+    # a one-line error and exit status 1 instead of a backtrace.
     def dispatch(handler, command, rest, stdout:, stderr:)
       handler.run(rest, stdout: stdout, stderr: stderr)
+    rescue CommandHelpers::HelpRequested
+      stdout.puts(Usage.for(self, command))
+      0
     rescue OptionParser::ParseError => e
-      stderr.puts("simplecov #{command}: #{e.message} (run `simplecov help` for usage)")
+      stderr.puts("simplecov #{command}: #{e} (run `simplecov help` for usage)")
       1
     end
 
     def usage
-      <<~USAGE
-        Usage: simplecov <command> [options]
-
-        Commands:
-          run <command...>          Execute <command> with simplecov pre-loaded
-                                    (so a coverage report is generated even
-                                    when the project has no test_helper hook)
-          coverage <path>           Print coverage stats for the given file
-          report                    Print the overall summary and group totals
-          uncovered                 List the lowest-coverage files
-          merge <files...>          Merge multiple .resultset.json files
-          diff <baseline>           Show per-file coverage delta vs baseline
-          open                      Open the HTML report in the default browser
-          serve                     Serve the coverage report over HTTP
-          clean                     Remove the coverage report directory
-          help                      Show this message
-
-        Default paths follow SimpleCov.coverage_dir from a project's
-        `.simplecov` when one is present (#{coverage_dir} for this run).
-
-        coverage / report / uncovered / diff options:
-          --input PATH              Read from PATH instead of #{default_input}
-          --no-color                Disable colorized percentages
-                                    (also honors NO_COLOR / FORCE_COLOR env)
-
-        coverage options:
-          --json                    Print the file's JSON entry verbatim
-
-        report options:
-          --json                    Emit totals and group sections as JSON
-
-        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)
-          --json                    Emit results as a JSON array (for CI)
-
-        merge options:
-          --output PATH             Write merged resultset to PATH
-                                    (default: #{default_resultset})
-          --honor-timeout           Drop entries older than merge_timeout
-          --dry-run                 Print what would be written without
-                                    actually writing
-          -q, --quiet               Suppress the success status line
-
-        diff options:
-          --fail-on-drop            Exit non-zero when any file's coverage
-                                    dropped vs the baseline (deleted
-                                    files don't count as drops)
-          --json                    Emit results as a JSON array (for CI)
-          --threshold N             Only show files whose absolute delta
-                                    in any criterion is at least N%
-
-        open options:
-          --report PATH             Open PATH instead of #{default_report}
-
-        serve options:
-          --port N                  Bind to port N (default: random open port)
-          --host HOST               Bind to HOST (default: 127.0.0.1)
-
-        clean options:
-          --dry-run                 Print what would be removed without
-                                    deleting anything
-          -q, --quiet               Suppress status lines
-      USAGE
+      Usage.text(self)
     end
   end
 end