simplecov 0.22.0 → 1.3.0

data/lib/simplecov/cli/report.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+
+module SimpleCov
+  module CLI
+    module Report
+      extend CommandHelpers
+
+      TOTAL_LABEL = "All Files"
+      SECTIONS = [%w[Line lines], %w[Branch branches], %w[Method methods]].freeze #: Array[[String, String]]
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts, = parse_common(args)
+        return 1 unless (data = load_data(opts.fetch(:input), stderr))
+
+        if opts.fetch(:json)
+          emit_json(stdout, data)
+        else
+          emit_text(stdout, data, CLI.color_enabled?(opts, stdout))
+        end
+        0
+      end
+
+      # Valid JSON isn't enough: a wrong-typed "total" or "groups" 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).instance_of?(Hash)
+          return CoverageFile.report_invalid(stderr, "report", input, '"total" must be an object')
+        end
+
+        groups = data.fetch("groups", none)
+        return data if groups.instance_of?(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.eql?(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.instance_of?(Hash) && section["total"].to_i.positive?
+
+        stdout.puts(stats_row(display,
+          Color.colorize_percent(section["percent"].to_f, enabled: color),
+          section["covered"],
+          section.fetch("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.instance_of?(Hash) && section["total"].to_i.positive?
+
+          out[key] = {
+            "percent" => section["percent"], "covered" => section["covered"], "total" => section.fetch("total")
+          }
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/run.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Run
+      AUTOSTART = File.expand_path("../autostart", __dir__.to_s)
+
+      extend self
+
+      def run(args, stderr:, **)
+        cmd = args.first.eql?("--") ? args.drop(1) : args
+        if cmd.empty?
+          stderr.puts("simplecov run: missing command")
+          return 1
+        end
+
+        exec_command(rubyopt_env, cmd)
+      rescue Errno::ENOENT => e
+        stderr.puts("simplecov run: #{e}")
+        127
+      end
+
+      def exec_command(env, cmd)
+        Kernel.exec(env, *cmd)
+      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,30 @@
+# frozen_string_literal: true
+
+require_relative "../../coverage_json"
+
+module SimpleCov
+  module CLI
+    module Serve
+      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)
+
+          build_index(json_path, dir)
+        rescue CoverageJSON::Error, SystemCallError => e
+          "cannot build index.html from #{json_path}: #{e}"
+        end
+
+        def self.build_index(json_path, dir)
+          require_relative "../../formatter/html_formatter"
+          Formatter::HTMLFormatter.new.format_from_json(json_path, dir)
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# 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 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
+
+        extend self
+
+        # 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.
+        #
+        # `routes` maps exact request paths (query string excluded) to callables
+        # that take over the connection, the seam `simplecov watch` mounts its
+        # /events stream on. A route may hold the socket for as long as it
+        # likes; the ensure below closes it when the route returns.
+        def handle_connection(client, root, routes = {})
+          # JRuby doesn't implement IO#timeout=. Without the guard the
+          # NoMethodError lands in the wide rescue below and every connection
+          # closes with an empty response. An idle connection then 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=)
+          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 below.
+          return respond(client, 400) if path.nil?
+
+          dispatch(client, method, path, root, routes)
+        rescue
+          # Misbehaving clients (truncated requests, connection resets, invalid
+          # encoding) shouldn't take the whole server down.
+          nil
+        ensure
+          client.close
+        end
+
+        def dispatch(client, method, path, root, routes)
+          return respond(client, 405) unless method.eql?("GET")
+
+          route = routes[path.split("?").first]
+          return route.call(client) if route
+
+          serve_file(client, path, root)
+        end
+
+        def serve_file(client, path, root)
+          file = resolve(path, root)
+          # `resolve` answers a path, nothing for a file that is not there, or the
+          # refusal itself.
+          return respond(client, file ? 403 : 404) unless file.instance_of?(String)
+
+          respond(client, 200, File.binread(file), MIME[File.extname(file).downcase])
+        end
+
+        def drain_headers(client)
+          loop { break if client.readline.rstrip.empty? }
+        end
+
+        # Answers the absolute path of the file to serve, :forbidden for a
+        # traversal attempt (symlinks that escape root included), 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.
+        def resolve(request_path, root)
+          path = request_path.split("?").first.to_s.delete_prefix("/")
+          absolute_root = File.realpath(root)
+          candidate = File.expand_path(path, absolute_root)
+          # Rejected before touching disk, so traversal and absolute-path attempts
+          # are 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)
+
+          # Symlinks are resolved last and re-checked: a file inside root could be
+          # a symlink pointing outside.
+          real = File.realpath(candidate)
+          inside?(real, absolute_root) ? real : :forbidden
+        rescue Errno::ENOENT
+          # TOCTOU: candidate vanished between File.file? and File.realpath.
+          nil
+        end
+
+        def inside?(path, root)
+          path.eql?(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,88 @@
+# 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`: a small static file server backed by stdlib `socket`, so
+    # there is no extra dependency just for viewing a local report on a box where
+    # `file://` doesn't work. This module is the CLI wiring; the HTTP mechanics
+    # live in StaticFileHandler.
+    module Serve
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:, **)
+        opts = parse(args)
+        dir = 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
+
+      # Required here rather than at load time so the other subcommands do not pay
+      # for sockets.
+      def require_socket
+        require "socket"
+      end
+
+      # Answers 1 when the socket can't be bound: port already taken, privileged
+      # port, unresolvable host. The receiver cast works around an rbs stdlib gap,
+      # where TCPSocket's explicit `self.new` shadows TCPServer#initialize's
+      # (host, port) form.
+      def with_server(opts, stderr)
+        server = (_ = TCPServer).new(opts.fetch(:host), opts.fetch(:port)) #: TCPServer
+      rescue SystemCallError, SocketError => e
+        error(stderr, "cannot bind to #{opts.fetch(:host)}:#{opts.fetch(:port)} (#{e})")
+      else
+        begin
+          yield server
+        ensure
+          server.close
+        end
+      end
+
+      def parse(args)
+        opts = {port: 0, host: "127.0.0.1"} #: Hash[Symbol, untyped]
+        build_parser 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.fetch(1)
+        host = url_host(server.addr.fetch(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 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/show/annotator.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Show
+      # Renders one file's annotated source: a right-aligned line-number gutter,
+      # the hit count beside it, and a caret line naming each miss under the line
+      # it happened on.
+      module Annotator
+        extend self
+
+        def call(source, entry, stdout, color:)
+          markers = markers_for(entry)
+          widths = {number: source.size.to_s.length, count: count_width(entry)}
+          source.each_with_index do |line, index|
+            rendered = row(index + 1, entry.fetch("lines").at(index), line, widths, color)
+            emit(stdout, rendered, markers[index + 1], widths, color)
+          end
+        end
+
+        def emit(stdout, rendered, labels, widths, color)
+          stdout.puts(rendered)
+          return if labels.empty?
+
+          gutter = " " * (widths.fetch(:number) + widths.fetch(:count) + 4)
+          stdout.puts(gutter + paint("^ #{labels.join(", ")}", :red, color))
+        end
+
+        def missed_lines(entry)
+          entry.fetch("lines").each_with_index.filter_map do |hit, index|
+            index + 1 if hit.instance_of?(Integer) && hit.zero?
+          end
+        end
+
+        def markers_for(entry)
+          markers = Hash.new { |hash, line| hash[line] = [] } #: Hash[Integer, Array[String]]
+          missed_lines(entry).each { |line| markers[line] << "missed" }
+          each_missed(entry["branches"]) { |line| markers[line] << "branch missed" }
+          each_missed(entry["methods"]) { |line| markers[line] << "method missed" }
+          markers
+        end
+
+        def each_missed(items)
+          return unless items.instance_of?(Array)
+
+          items.each do |item|
+            line = missed_line_of(item)
+            yield line if line
+          end
+        end
+
+        # The reported line of a zero-hit item, nil for a covered or malformed one,
+        # the same tolerance the patch subcommand applies to branch entries.
+        def missed_line_of(item)
+          return nil unless item.instance_of?(Hash)
+
+          hits = item["coverage"]
+          return nil unless hits.instance_of?(Integer) && hits.zero?
+
+          line = item["report_line"] || item["start_line"]
+          line if line.instance_of?(Integer)
+        end
+
+        def count_width(entry)
+          entry.fetch("lines").grep(Integer) { |hit| hit.to_s.length }.max || 1
+        end
+
+        def row(number, hit, line, widths, color)
+          format("%#{widths.fetch(:number)}d  %s  %s", number, count(hit, widths, color), line).rstrip
+        end
+
+        # Padded to width before it is painted, so escape codes can't skew the
+        # column, and blank for a line carrying no count.
+        def count(hit, widths, color)
+          padded = (hit.instance_of?(Integer) ? hit.to_s : "").rjust(widths.fetch(:count))
+          return padded unless hit.instance_of?(Integer)
+
+          paint(padded, hit.zero? ? :red : :green, color)
+        end
+
+        def paint(text, tint, color)
+          Color.colorize(text, tint, enabled: color)
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/show/sweep.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Show
+      module Sweep
+        extend self
+
+        def misses(coverage)
+          rows = coverage.filter_map do |filename, entry|
+            next unless entry.instance_of?(Hash) && entry["lines"].instance_of?(Array)
+
+            missed = Annotator.missed_lines(entry)
+            [display_path(filename), missed] unless missed.empty?
+          end
+          rows.sort_by(&:first)
+        end
+
+        def emit(rows, opts, stdout, stderr)
+          if opts.fetch(:json)
+            stdout.puts(JSON.pretty_generate(rows.map { |path, missed| {path: path, missed: missed} }))
+          elsif rows.empty?
+            stderr.puts("simplecov show: nothing uncovered")
+          else
+            rows.each { |path, missed| stdout.puts("#{path}:#{Patch::Output.ranges(missed, ",")}") }
+          end
+          0
+        end
+
+        def display_path(filename)
+          filename.delete_prefix("#{File.expand_path(SimpleCov.root)}/")
+        end
+      end
+    end
+  end
+end

data/lib/simplecov/cli/show.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require_relative "command_helpers"
+require_relative "patch/output"
+require_relative "show/annotator"
+require_relative "show/sweep"
+
+module SimpleCov
+  module CLI
+    # `simplecov show <path>`: annotated source in the terminal, the way
+    # `go tool cover` and `llvm-cov show` print it. `--uncovered-only` collapses
+    # the answer to `path:ranges`, a form that greps, fits in a commit message,
+    # and hands a coding agent exactly the lines whose tests are missing.
+    module Show
+      extend CommandHelpers
+
+      extend self
+
+      def run(args, stdout:, stderr:)
+        opts = parse(args)
+        return run_project(opts, stdout, stderr) unless opts.fetch(:path)
+
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "show", stderr: stderr)
+        return 1 unless coverage
+
+        located = locate_or_report(coverage, opts, stderr)
+        return 1 unless located
+
+        render(located, opts, stdout, stderr)
+      end
+
+      # No path sweeps the whole project, in the compact forms only. The annotated
+      # text form still wants one file.
+      def run_project(opts, stdout, stderr)
+        unless opts.fetch(:uncovered_only) || opts.fetch(:json)
+          return error(stderr, "missing path (annotating needs one file; --uncovered-only sweeps the whole project)")
+        end
+
+        coverage = CoverageFile.load_coverage(opts.fetch(:input), command: "show", stderr: stderr)
+        return 1 unless coverage
+
+        Sweep.emit(Sweep.misses(coverage), opts, stdout, stderr)
+      end
+
+      def parse(args)
+        opts = {input: CLI.default_input, no_color: false,
+                uncovered_only: false, json: false} #: Hash[Symbol, untyped]
+        rest = build_parser { |parser| options(parser, opts) }.parse(args)
+        opts[:path] = rest.first
+        opts
+      end
+
+      def options(parser, opts)
+        parser.on("--input PATH") { |v| opts[:input] = v }
+        parser.on("--no-color") { opts[:no_color] = true }
+        parser.on("--uncovered-only") { opts[:uncovered_only] = true }
+        parser.on("--json") { opts[:json] = true }
+      end
+
+      # A line-less report has no per-line hits to put in a gutter, so it is
+      # reported like an unresolvable path is.
+      def locate_or_report(coverage, opts, stderr)
+        path, input = opts.fetch_values(:path, :input)
+        match = CoverageFile.lookup(coverage, path)
+        return error_nil(stderr, CoverageFile.not_found_message(coverage, path, input)) unless match
+
+        entry = match.last
+        unless entry.instance_of?(Hash)
+          return CoverageFile.report_invalid(stderr, "show", input, "entry for #{path} must be an object")
+        end
+        return match if entry["lines"].instance_of?(Array)
+
+        error_nil(stderr, "no line coverage for #{path} in #{input}")
+      end
+
+      def render(located, opts, stdout, stderr)
+        filename, entry = located
+        return emit_json(entry, opts, stdout) if opts.fetch(:json)
+        return show_uncovered(entry, opts, stdout, stderr) if opts.fetch(:uncovered_only)
+
+        source = source_for(filename, entry, opts, stderr)
+        return 1 unless source
+
+        Annotator.call(source, entry, stdout, color: CLI.color_enabled?(opts, stdout))
+        0
+      end
+
+      def emit_json(entry, opts, stdout)
+        stdout.puts(JSON.pretty_generate(
+          path: opts.fetch(:path), missed: Annotator.missed_lines(entry),
+          lines: relevant_lines(entry), markers: Annotator.markers_for(entry)
+        ))
+        0
+      end
+
+      def relevant_lines(entry)
+        entry.fetch("lines").each_with_index.filter_map do |hit, index|
+          {number: index + 1, hits: hit} if hit.instance_of?(Integer)
+        end
+      end
+
+      def show_uncovered(entry, opts, stdout, stderr)
+        missed = Annotator.missed_lines(entry)
+        if missed.empty?
+          stderr.puts("simplecov show: nothing uncovered in #{opts.fetch(:path)}")
+        else
+          stdout.puts("#{opts.fetch(:path)}:#{Patch::Output.ranges(missed, ",")}")
+        end
+        0
+      end
+
+      # The report's own source when it carries one; otherwise the file on disk,
+      # accepted only while its line count still matches the report's, since
+      # annotating drifted source would put hit counts on the wrong lines.
+      def source_for(filename, entry, opts, stderr)
+        embedded = entry["source"]
+        return embedded if embedded.instance_of?(Array) && embedded.all?(String)
+        unless File.file?(filename)
+          return error_nil(stderr, "no source for #{opts.fetch(:path)} in #{opts.fetch(:input)} and no file " \
+                                   "at #{filename}, regenerate the report with `source_in_json true`")
+        end
+
+        lines = File.readlines(filename, chomp: true)
+        return lines if lines.size.eql?(entry.fetch("lines").size)
+
+        error_nil(stderr, "#{filename} has changed since the report (#{lines.size} lines now, " \
+                          "#{entry.fetch("lines").size} recorded), regenerate the report")
+      end
+    end
+  end
+end