simplecov 1.1.1 → 1.2.0

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

data/lib/simplecov/color.rb

@@ -1,22 +1,11 @@
 # frozen_string_literal: true
 
 module SimpleCov
-  # ANSI colorization for stderr diagnostics. Thresholds mirror the
-  # HTML formatter (>= 90 green, >= 75 yellow, otherwise red) so a
-  # team's mental model of "what's the cutoff" is the same whether
-  # they're reading the terminal output or the HTML report.
-  #
-  # Color precedence, highest first:
-  #
-  # - `SimpleCov.color = true` / `false` (programmatic override, wins
-  #   over everything; default is `:auto` which falls through)
-  # - `NO_COLOR` env var (any non-empty value) → off (see no-color.org)
-  # - `FORCE_COLOR` env var (any non-empty value) → on
-  # - `stream.tty?` fallback
-  #
-  # `NO_COLOR` wins over `FORCE_COLOR` if both env vars are set.
+  # ANSI colorization for stderr diagnostics. Thresholds mirror the HTML
+  # formatter so a team's mental model of "what's the cutoff" is the same in
+  # the terminal and in the report.
   module Color
-    GREEN_THRESHOLD  = 90
+    GREEN_THRESHOLD = 90
     YELLOW_THRESHOLD = 75
 
     ANSI = {
@@ -26,51 +15,44 @@ module SimpleCov
       reset: "\e[0m"
     }.freeze
 
-  module_function
+    extend self
 
-    # `stream` is the IO that the colorized text is destined for. The
-    # formatter writes to stderr, so that's the default. CLI subcommands
-    # that print to stdout should pass `$stdout` so a redirected pipe
-    # doesn't get ANSI sequences. See the module-level comment for
-    # precedence.
+    # Precedence, highest first: an explicit `SimpleCov.color` true/false (the
+    # default `:auto` falls through), then `NO_COLOR`, then `FORCE_COLOR`, then
+    # `stream.tty?`. `NO_COLOR` wins over `FORCE_COLOR` when both are set.
+    #
+    # `stream` is the IO the colorized text is destined for. CLI subcommands
+    # that print to stdout should pass `$stdout` so a redirected pipe doesn't
+    # get ANSI sequences.
+    #
+    # `SimpleCov.color` only exists once the full library is loaded, and the
+    # standalone CLI loads this file without it, so a missing config reads as
+    # its `:auto` default. A parallel runner can also close a worker's stdio
+    # before its at_exit hooks run, and a closed stream is not a tty.
     def enabled?(stream = $stderr)
-      # `SimpleCov.color` only exists once the full library is loaded.
-      # The standalone CLI (`exe/simplecov`) loads `simplecov/color`
-      # without `simplecov` itself to stay lightweight, so treat a
-      # missing config the same as its `:auto` default: fall through to
-      # the env vars and tty check below.
       config = SimpleCov.color if SimpleCov.respond_to?(:color)
       return config if [true, false].include?(config)
       return false if env_set?("NO_COLOR")
-      return true  if env_set?("FORCE_COLOR")
+      return true if env_set?("FORCE_COLOR")
 
       stream.tty?
     rescue IOError
-      # A parallel runner can close a worker's stdio before its at_exit
-      # hooks run (rspec-conductor does). A closed stream is not a tty.
       false
     end
 
     def for_percent(percent)
-      return :green  if percent >= GREEN_THRESHOLD
+      return :green if percent >= GREEN_THRESHOLD
       return :yellow if percent >= YELLOW_THRESHOLD
 
       :red
     end
 
-    # Wrap `text` in the ANSI sequence for `color` (a key of ANSI).
-    # Returns the bare text if color is disabled. The `enabled:`
-    # keyword lets callers (e.g., CLI subcommands honoring `--no-color`)
-    # override the auto-detection without touching env vars.
     def colorize(text, color, enabled: enabled?)
       return text unless enabled
 
       "#{ANSI.fetch(color)}#{text}#{ANSI.fetch(:reset)}"
     end
 
-    # Render `percent` as a fixed "NN.NN%" string colored by which
-    # threshold band it falls into. Callers that want a different
-    # rendering of the number can pass the pre-rendered `text`.
     def colorize_percent(percent, text = nil, enabled: enabled?)
       colorize(text || format("%.2f%%", percent), for_percent(percent), enabled: enabled)
     end

data/lib/simplecov/combine/branches_combiner.rb

@@ -6,49 +6,29 @@ require_relative "interned_counts"
 
 module SimpleCov
   module Combine
-    #
-    # Combine different branch coverage results on single file.
-    #
-    # Should be called through `CoverageAccumulator`.
     module BranchesCombiner
-    module_function
+      extend self
 
-      #
-      # Return merged branches or the existed branch if other is missing.
-      #
-      # Branches inside files are always same if they exist, the difference only in coverage count.
-      # Branch coverage report for any conditional case is built from hash, it's key is a condition and
-      # it's body is a hash << keys from condition and value is coverage rate >>.
-      # ex: branches => { [:if, 3, 8, 6, 8, 36] =>
-      #                     {[:then, 4, 8, 6, 8, 12] => 1, [:else, 5, 8, 6, 8, 36] => 2}, ... }
-      # We create copy of result and update it values depending on the combined branches coverage values.
-      #
-      # @return [Hash]
-      #
       def combine(coverage_a, coverage_b)
         merged = absorb({}, coverage_a) #: Hash[untyped, [untyped, Hash[untyped, untyped]]]
         materialize(absorb(merged, coverage_b))
       end
 
       # Folds `coverage` into `target`, an interned table keyed by condition
-      # identity. Kept interned (rather than turned back into tuple keys per
-      # merge) so a fold over N resultsets interns each condition once
-      # instead of re-interning the whole accumulated table N times.
-      #
-      # @return [Hash] `target`
+      # identity. Kept interned rather than turned back into tuple keys per merge,
+      # so a fold over N resultsets interns each condition once instead of
+      # re-interning the whole accumulated table N times.
       def absorb(target, coverage)
         return target unless coverage
 
         coverage.each do |condition, branches_inside|
           entry = target[identities[condition]] ||= new_condition(condition)
-          InternedCounts.absorb_counts(entry[1], branches_inside, identities)
+          InternedCounts.absorb_counts(entry.fetch(1), branches_inside, identities)
         end
 
         target
       end
 
-      # Split out so the empty arm table has somewhere to carry its type
-      # annotation. Only allocated the first time a condition is seen.
       def new_condition(condition)
         arms = {} #: Hash[untyped, untyped]
         [condition, arms]
@@ -56,20 +36,16 @@ module SimpleCov
 
       # Turns an interned table back into the tuple-keyed hash the rest of
       # SimpleCov reads. Done once, at the end of a fold.
-      #
-      # @return [Hash]
       def materialize(target)
         target.values.to_h { |condition, branches| [condition, branches.values.to_h] }
       end
 
-      # Bounded by the project's branch count, like `RubyDataParser`'s parse
-      # cache.
       def identities
         @identities ||= IdentityInterner.build { |tuple| tuple_identity(tuple) }
       end
 
-      # Branches match on source span, whatever ids the recording processes
-      # handed them (issue #1233).
+      # Branches match on source span, whatever ids the recording processes handed
+      # them (#1233).
       def tuple_identity(tuple)
         type, _id, start_line, start_column, end_line, end_column = SourceFile::RubyDataParser.call(tuple)
         [type, start_line, start_column, end_line, end_column].freeze