simplecov 0.22.0 → 1.1.1

data/lib/simplecov/cli/merge.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "../atomic_file"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov merge <files...>` — wrap SimpleCov::ResultMerger so a
+    # CI matrix that produces one .resultset.json per worker can stitch
+    # them together from the shell instead of dropping a Rake task into
+    # every project. Requires the full simplecov library to be on the
+    # load path; lazy-required so the read-only subcommands above don't
+    # pay for ResultMerger (and its Coverage runtime guard).
+    module Merge
+      extend CommandHelpers
+
+    module_function
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args)
+        return error(stderr, "missing input files") if opts[:files].empty?
+        return 1 unless valid_inputs?(opts[:files], stderr)
+
+        require "simplecov"
+        result = SimpleCov::ResultMerger.merge_results(*opts[:files], ignore_timeout: !opts[:honor_timeout])
+        return error(stderr, "no mergeable results in input files") unless result
+
+        commit(opts, result, stdout)
+        0
+      end
+
+      def commit(opts, result, stdout)
+        verb = opts[:dry_run] ? "would write" : "wrote"
+        write(opts[:output], result) unless opts[:dry_run]
+        stdout.puts("simplecov merge: #{verb} #{opts[:output]}") unless opts[:quiet]
+      end
+
+      def valid_inputs?(files, stderr)
+        parsed = parse_inputs(files, stderr) or return false
+
+        warn_about_duplicate_command_names(parsed, stderr)
+        true
+      end
+
+      def parse(args)
+        opts = {output: SimpleCov::CLI.default_resultset, honor_timeout: false, dry_run: false, quiet: false}
+        files =
+          OptionParser.new do |o|
+            o.on("--output PATH") { |v| opts[:output] = v }
+            o.on("--honor-timeout") { opts[:honor_timeout] = true }
+            o.on("--dry-run") { opts[:dry_run] = true }
+            o.on("-q", "--quiet") { opts[:quiet] = true }
+          end.parse(args)
+        opts.merge(files: files)
+      end
+
+      # Validate every input file up-front and return a {path => parsed}
+      # hash. Surfacing per-file errors here turns ResultMerger's
+      # generic "no mergeable results" into a message that points at
+      # the specific input causing the failure.
+      def parse_inputs(files, stderr)
+        parsed = {} #: Hash[String, Hash[String, untyped]]
+        files.each_with_object(parsed) do |path, memo|
+          data = parse_input(path, stderr) or return nil
+
+          memo[path] = data
+        end
+      end
+
+      # Read first, classify by the exception: an exist?-then-read pair
+      # is racy, and rescuing only ENOENT crashed with a backtrace on a
+      # directory (EISDIR) or an unreadable file (EACCES).
+      def parse_input(path, stderr)
+        data = JSON.parse(File.read(path))
+        return data if data.is_a?(Hash) && !data.empty?
+
+        parse_input_error(stderr, path, "has no resultset entries")
+      rescue Errno::ENOENT
+        parse_input_error(stderr, path, "not found")
+      rescue JSON::ParserError => e
+        parse_input_error(stderr, path, "isn't valid JSON (#{e.message})")
+      rescue SystemCallError => e
+        parse_input_error(stderr, path, "cannot be read (#{e.message.lines.first.to_s.strip})")
+      end
+
+      def parse_input_error(stderr, path, reason)
+        stderr.puts("simplecov merge: input file #{path.inspect} #{reason}")
+        nil
+      end
+
+      # When two input files share a command_name, ResultMerger folds
+      # them together with last-write-wins on the timestamp — easy to
+      # mistake for "no merge happened." Surface the overlap so the
+      # operator can rename the workers or accept the merge knowingly.
+      def warn_about_duplicate_command_names(parsed, stderr)
+        files_per_command = {} #: Hash[String, Array[String]]
+        parsed.each do |path, data|
+          data.each_key { |command_name| (files_per_command[command_name] ||= []) << path }
+        end
+        files_per_command.each do |command_name, paths|
+          next if paths.size < 2
+
+          stderr.puts(duplicate_warning(command_name, paths))
+        end
+      end
+
+      def duplicate_warning(command_name, paths)
+        "simplecov merge: warning — command_name #{command_name.inspect} " \
+          "appears in #{paths.size} input files (#{paths.join(', ')}); " \
+          "entries will be merged"
+      end
+
+      def write(path, result)
+        AtomicFile.write(path, JSON.pretty_generate(result.to_hash))
+      end
+    end
+  end
+end

data/lib/simplecov/cli/open.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov open [--report PATH]` — open the HTML report in the
+    # platform's default browser. Tiny QoL wrapper around `xdg-open` /
+    # `open` / `start` so users don't have to type a file:// URL.
+    module Open
+      extend CommandHelpers
+
+    module_function
+
+      def run(args, stderr:, **)
+        path = parse(args)
+        return error(stderr, "#{path} not found") unless File.exist?(path)
+
+        opener = browser_opener
+        return error(stderr, "no known opener for #{RbConfig::CONFIG['host_os']}") unless opener
+
+        system(*opener, path) ? 0 : 1
+      end
+
+      def parse(args)
+        path = SimpleCov::CLI.default_report
+        OptionParser.new do |o|
+          o.on("--report PATH") { |v| path = v }
+        end.parse(args)
+        path
+      end
+
+      # Returns the argv for the platform's "open this file" command, or
+      # nil if the host OS isn't recognized. On Windows, `start` is a
+      # cmd.exe builtin (not an executable), so route through `cmd /c`;
+      # the empty string is the window-title positional `start` takes
+      # before the path so a quoted path isn't mis-parsed as the title.
+      def browser_opener
+        case RbConfig::CONFIG["host_os"]
+        when /darwin/             then ["open"]
+        when /mswin|mingw|cygwin/ then ["cmd", "/c", "start", ""]
+        when /linux|bsd|solaris/  then ["xdg-open"]
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/report.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov report [--input PATH]` — pretty-print the overall
+    # totals row plus per-group totals from a JSONFormatter
+    # coverage.json. Same numbers as the HTML report's totals row, for
+    # contexts where opening a browser isn't an option (CI logs, ssh
+    # sessions, terminal-only workflows).
+    module Report
+      extend CommandHelpers
+
+      TOTAL_LABEL = "All Files"
+      SECTIONS = [%w[Line lines], %w[Branch branches], %w[Method methods]].freeze
+
+    module_function
+
+      def run(args, stdout:, stderr:)
+        opts, = parse_common(args)
+        return 1 unless (data = load_data(opts[:input], stderr))
+
+        if opts[:json]
+          emit_json(stdout, data)
+        else
+          emit_text(stdout, data, SimpleCov::CLI.color_enabled?(opts, stdout))
+        end
+        0
+      end
+
+      # Valid JSON isn't enough: a wrong-typed "total" or "groups" (or a
+      # wrong-typed group entry) used to escape here and crash the
+      # emitters with a backtrace instead of the one-line error the
+      # sibling commands print.
+      def load_data(input, stderr)
+        data = CoverageFile.load_document(input, command: "report", stderr: stderr)
+        return unless data
+
+        none = {} #: Hash[String, untyped]
+        unless data.fetch("total", none).is_a?(Hash)
+          return CoverageFile.report_invalid(stderr, "report", input, '"total" must be an object')
+        end
+
+        groups = data.fetch("groups", none)
+        return data if groups.is_a?(Hash) && groups.each_value.all?(Hash)
+
+        CoverageFile.report_invalid(stderr, "report", input, '"groups" must be an object of objects')
+      end
+
+      def emit_text(stdout, data, color)
+        none = {} #: Hash[String, untyped]
+        emit_totals(stdout, TOTAL_LABEL, data.fetch("total", none), color)
+        data.fetch("groups", none).each do |name, group|
+          label = name == TOTAL_LABEL ? "#{name} (group)" : name
+          emit_totals(stdout, label, group, color)
+        end
+      end
+
+      def emit_totals(stdout, label, totals, color)
+        stdout.puts(label)
+        SECTIONS.each { |display, key| emit_section(stdout, display, totals[key], color) }
+        stdout.puts
+      end
+
+      def emit_section(stdout, display, section, color)
+        return unless section.is_a?(Hash) && section["total"].to_i.positive?
+
+        stdout.puts(stats_row(display,
+                              SimpleCov::Color.colorize_percent(section["percent"].to_f, enabled: color),
+                              section["covered"],
+                              section["total"]))
+      end
+
+      def emit_json(stdout, data)
+        none = {} #: Hash[String, untyped]
+        groups = data.fetch("groups", none).transform_values { |group| collect_section(group) }
+        payload = {"total" => collect_section(data.fetch("total", none)), "groups" => groups}
+        stdout.puts(JSON.pretty_generate(payload))
+      end
+
+      def collect_section(totals)
+        sections = {} #: Hash[String, untyped]
+        SECTIONS.each_with_object(sections) do |(_, key), out|
+          section = totals[key]
+          next unless section.is_a?(Hash) && section["total"].to_i.positive?
+
+          out[key.to_s] = {
+            "percent" => section["percent"], "covered" => section["covered"], "total" => section["total"]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/run.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    # `simplecov run <command...>` — exec the given command with
+    # simplecov auto-loaded so a coverage report drops into the
+    # project's coverage/ directory at the end. Useful for projects
+    # without a test_helper that already calls SimpleCov.start (e.g.
+    # plain `bundle exec rake test` on an unconfigured library).
+    module Run
+      AUTOSTART = File.expand_path("../autostart", __dir__.to_s)
+
+    module_function
+
+      def run(args, stderr:, **)
+        cmd = args.first == "--" ? args.drop(1) : args
+        if cmd.empty?
+          stderr.puts("simplecov run: missing command")
+          return 1
+        end
+
+        Kernel.exec(rubyopt_env, *cmd)
+      rescue Errno::ENOENT => e
+        stderr.puts("simplecov run: #{e.message}")
+        127
+      end
+
+      def rubyopt_env
+        existing = ENV["RUBYOPT"].to_s.strip
+        injection = "-r#{AUTOSTART}"
+        merged = existing.empty? ? injection : "#{existing} #{injection}"
+        ENV.to_hash.merge("RUBYOPT" => merged)
+      end
+    end
+  end
+end

data/lib/simplecov/cli/serve/report_preparer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../../coverage_json"
+
+module SimpleCov
+  module CLI
+    module Serve
+      # Ensures the coverage directory has a renderable entry point before
+      # the HTTP server binds. Existing self-contained reports take priority
+      # over their optional JSON sidecar.
+      module ReportPreparer
+        def self.call(dir)
+          index_path = File.join(dir, "index.html")
+          json_path = File.join(dir, "coverage.json")
+          return "#{dir} doesn't exist; run your test suite first" unless File.directory?(dir)
+          return if File.file?(index_path)
+
+          return "#{dir} has no index.html or coverage.json; run your test suite first" unless File.file?(json_path)
+
+          require_relative "../../formatter/html_formatter"
+          SimpleCov::Formatter::HTMLFormatter.new.format_from_json(json_path, dir)
+          nil
+        rescue SimpleCov::CoverageJSON::Error, SystemCallError => e
+          "cannot build index.html from #{json_path}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/serve/static_file_handler.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Serve
+      # The HTTP mechanics behind `simplecov serve`: reads one request
+      # per connection and answers it from the report directory, with
+      # traversal-safe path resolution. Kept apart from the CLI wiring
+      # (option parsing, binding, the accept loop) in serve.rb.
+      module StaticFileHandler
+        MIME = {
+          ".html" => "text/html; charset=utf-8", ".htm" => "text/html; charset=utf-8",
+          ".css" => "text/css",
+          ".js" => "application/javascript",
+          ".json" => "application/json",
+          ".svg" => "image/svg+xml",
+          ".png" => "image/png",
+          ".gif" => "image/gif",
+          ".jpg" => "image/jpeg",
+          ".jpeg" => "image/jpeg",
+          ".ico" => "image/x-icon",
+          ".txt" => "text/plain; charset=utf-8"
+        }.freeze
+        STATUS_TEXT = {200 => "OK", 400 => "Bad Request", 403 => "Forbidden",
+                       404 => "Not Found", 405 => "Method Not Allowed"}.freeze
+
+        # Seconds a connection may sit idle mid-request before its reads
+        # raise IO::TimeoutError and the connection is dropped.
+        READ_TIMEOUT = 5
+
+      module_function
+
+        # Reads one HTTP request line, drains headers, serves the file or
+        # writes a status response. Wide rescue so a misbehaving client
+        # can't crash the server. The read timeout keeps idle connections
+        # from pinning their threads forever.
+        def handle_connection(client, root)
+          # simplecov:disable branch — support for IO#timeout= is fixed by the engine
+          # JRuby and TruffleRuby don't implement IO#timeout=. Without
+          # the guard the NoMethodError lands in the wide rescue below
+          # and every connection closes with an empty response. On those
+          # engines an idle connection pins its thread instead of timing
+          # out, which only leaks a thread in an interactive dev server.
+          client.timeout = READ_TIMEOUT if client.respond_to?(:timeout=)
+          # simplecov:enable branch
+          method, path = client.readline.split
+          drain_headers(client)
+          # A request line without both tokens used to raise on
+          # `path.split` inside the wide rescue, closing the connection
+          # with an empty response instead of the 400 defined below.
+          return respond(client, 400) if path.nil?
+          return respond(client, 405) unless method == "GET"
+
+          serve_file(client, path, root)
+        rescue StandardError
+          # Misbehaving clients (truncated requests, connection resets,
+          # invalid encoding) shouldn't take the whole server down.
+          nil
+        ensure
+          # simplecov:disable — `client` is the parameter, never nil here;
+          # the `&.` is purely defensive in case of future refactors
+          client&.close
+          # simplecov:enable
+        end
+
+        def serve_file(client, path, root)
+          file = resolve(path, root)
+          return respond(client, file == :forbidden ? 403 : 404) unless file.is_a?(String)
+
+          respond(client, 200, File.binread(file), MIME[File.extname(file).downcase])
+        end
+
+        def drain_headers(client)
+          loop { break if client.readline.strip.empty? }
+        end
+
+        # Returns the absolute path of the file to serve, :forbidden for
+        # a traversal attempt (including symlinks that escape root), or
+        # nil for "not found".
+        #
+        # The request path is deliberately NOT percent-decoded: filenames
+        # needing escapes don't occur in generated reports, and keeping
+        # `%2e%2e%2f` as literal bytes is part of the traversal defense.
+        # If decoding is ever added, it must happen BEFORE the `inside?`
+        # check below.
+        def resolve(request_path, root)
+          path = request_path.split("?", 2).first.to_s.sub(%r{^/}, "")
+          absolute_root = File.realpath(root)
+          candidate = File.expand_path(path.empty? ? "index.html" : path, absolute_root)
+          # Reject `..` traversal and absolute-path attempts before
+          # touching disk so they're 403, not 404.
+          return :forbidden unless inside?(candidate, absolute_root)
+
+          candidate = File.join(candidate, "index.html") if File.directory?(candidate)
+          return nil unless File.file?(candidate)
+
+          # Resolve symlinks last and re-check: a file inside root could
+          # be a symlink pointing outside (e.g. /etc/passwd).
+          real = File.realpath(candidate)
+          inside?(real, absolute_root) ? real : :forbidden
+        rescue Errno::ENOENT
+          # simplecov:disable — TOCTOU: candidate vanished between
+          # File.file? and File.realpath. Treat as "not found".
+          nil
+          # simplecov:enable
+        end
+
+        def inside?(path, root)
+          path == root || path.start_with?(root + File::SEPARATOR)
+        end
+
+        def respond(client, status, body = "", content_type = "text/plain")
+          client.write("HTTP/1.1 #{status} #{STATUS_TEXT[status] || 'Error'}\r\n",
+                       "Content-Type: #{content_type || 'application/octet-stream'}\r\n",
+                       "Content-Length: #{body.bytesize}\r\n",
+                       "Connection: close\r\n\r\n")
+          client.write(body)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/serve.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "command_helpers"
+require_relative "serve/report_preparer"
+require_relative "serve/static_file_handler"
+
+module SimpleCov
+  module CLI
+    # `simplecov serve [--port N] [--host HOST]` — serve the coverage
+    # report over HTTP. A small static file server backed by stdlib
+    # `socket`, so there's no extra dependency just for "view a local
+    # report on a CI box where `file://` doesn't work." This module is
+    # the CLI wiring (options, binding, the accept loop); the HTTP
+    # mechanics live in StaticFileHandler.
+    module Serve
+      extend CommandHelpers
+
+    module_function
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args)
+        dir = SimpleCov::CLI.coverage_dir
+        message = ReportPreparer.call(dir)
+        return error(stderr, message) if message
+
+        require "socket"
+        with_server(opts, stderr) do |server|
+          announce(stdout, server, dir)
+          serve_loop(server, dir, stdout)
+          0
+        end
+      end
+
+      # Returns the block's exit status, or 1 when the socket can't be
+      # bound (port already taken, privileged port, unresolvable host).
+      def with_server(opts, stderr)
+        # The receiver cast works around an rbs stdlib gap: TCPSocket's
+        # explicit `self.new` shadows TCPServer#initialize's (host, port) form.
+        server = (_ = TCPServer).new(opts[:host], opts[:port]) #: TCPServer
+      rescue SystemCallError, SocketError => e
+        error(stderr, "cannot bind to #{opts[:host]}:#{opts[:port]} (#{e.message})")
+      else
+        begin
+          yield server
+        ensure
+          server.close
+        end
+      end
+
+      def parse(args)
+        opts = {port: 0, host: "127.0.0.1"} #: Hash[Symbol, untyped]
+        OptionParser.new do |o|
+          o.on("--port N", Integer) { |v| opts[:port] = v }
+          o.on("--host HOST")       { |v| opts[:host] = v }
+        end.parse(args)
+        opts
+      end
+
+      def announce(stdout, server, dir)
+        port = server.addr[1]
+        host = url_host(server.addr[3])
+        stdout.puts("simplecov serve: serving #{dir} at http://#{host}:#{port}/")
+        stdout.puts("Press Ctrl-C to stop.")
+      end
+
+      # IPv6 literals need brackets in a URL (--host ::1 must announce
+      # http://[::1]:PORT/, not the invalid http://::1:PORT/).
+      def url_host(host)
+        host.include?(":") ? "[#{host}]" : host
+      end
+
+      # One thread per connection: browsers open speculative sockets
+      # that send no bytes, and a serial loop would stall every real
+      # request (the report's assets included) behind them.
+      def serve_loop(server, dir, stdout)
+        loop do
+          Thread.new(server.accept) { |client| StaticFileHandler.handle_connection(client, dir) }
+        end
+      rescue Interrupt
+        stdout.puts("\nsimplecov serve: stopping")
+      end
+    end
+  end
+end

data/lib/simplecov/cli/uncovered.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    # `simplecov uncovered [--threshold N] [--top N] [--criterion C]` — list
+    # the lowest-coverage files (by the chosen criterion, ascending), so a
+    # developer can answer "where should I add tests next?" without
+    # opening a browser. Reads coverage.json directly.
+    module Uncovered
+      extend CommandHelpers
+
+      DEFAULT_TOP = 10
+
+    module_function
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args)
+        keys = CoverageFile::CRITERIA[opts[:criterion]]
+        return unknown_criterion(opts[:criterion], stderr) unless keys
+
+        report(opts, keys, stdout, stderr)
+      end
+
+      def report(opts, keys, stdout, stderr)
+        coverage = CoverageFile.load_coverage(opts[:input], command: "uncovered", stderr: stderr)
+        return 1 unless coverage
+
+        files = rank(coverage, opts[:threshold], keys).first(opts[:top])
+        return stdout.puts(empty_message(opts[:json])) || 0 if files.empty?
+
+        emit(stdout, files, opts)
+        0
+      end
+
+      def unknown_criterion(criterion, stderr)
+        stderr.puts("simplecov uncovered: unknown --criterion #{criterion.inspect} (expected line, branch, or method)")
+        1
+      end
+
+      def emit(stdout, files, opts)
+        opts[:json] ? emit_json(stdout, files) : emit_text(stdout, files, SimpleCov::CLI.color_enabled?(opts, stdout))
+      end
+
+      def parse(args)
+        opts, = parse_common(args, threshold: 100.0, top: DEFAULT_TOP, criterion: :line) do |o, options|
+          o.on("--threshold N", Float) { |v| options[:threshold] = v }
+          o.on("--top N", Integer)     { |v| options[:top] = validate_top(v) }
+          o.on("--criterion C")        { |v| options[:criterion] = v.to_sym }
+        end
+        opts
+      end
+
+      # A negative count would raise from `Array#first`; report it as
+      # the parse error it is (`--top 0` is allowed and shows nothing).
+      # OptionParser prepends the offending option's name, so the raise
+      # carries only the reason.
+      def validate_top(value)
+        raise OptionParser::InvalidArgument, "must not be negative" if value.negative?
+
+        value
+      end
+
+      def emit_text(stdout, files, color)
+        files.each { |fname, pct, covered, total| stdout.puts(format_row(fname, pct, covered, total, color)) }
+      end
+
+      def emit_json(stdout, files)
+        rows = files.map do |fname, pct, covered, total|
+          {"file" => fname, "percent" => pct, "covered" => covered, "total" => total}
+        end
+        stdout.puts(JSON.pretty_generate(rows))
+      end
+
+      def empty_message(json)
+        json ? "[]" : "simplecov uncovered: nothing to report"
+      end
+
+      def rank(coverage_hash, threshold, keys)
+        rows = coverage_hash.filter_map { |fname, payload| row_for(fname, payload, threshold, keys) }
+        rows.sort_by { |_fname, pct, _c, _t| pct }
+      end
+
+      def row_for(fname, payload, threshold, keys)
+        return unless payload.is_a?(Hash) && payload[keys[:total]].to_i.positive?
+
+        pct = payload[keys[:percent]].to_f
+        return if pct >= threshold
+
+        [fname, pct, payload[keys[:covered]].to_i, payload[keys[:total]].to_i]
+      end
+
+      def format_row(fname, pct, covered, total, color)
+        format("%<pct>s  %<covered>d/%<total>d  %<fname>s",
+               pct: SimpleCov::Color.colorize_percent(pct, format("%6.2f%%", pct), enabled: color),
+               covered: covered, total: total, fname: fname)
+      end
+    end
+  end
+end