simplecov 1.1.1 → 1.3.0

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

@@ -3,10 +3,10 @@
 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.
+      # 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",
@@ -24,96 +24,102 @@ module SimpleCov
         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.
+        # 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.
+        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=)
-          # 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.
+          # 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?
-          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.
+          dispatch(client, method, path, root, routes)
+        rescue
+          # 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
+          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)
-          return respond(client, file == :forbidden ? 403 : 404) unless file.is_a?(String)
+          # `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.strip.empty? }
+          loop { break if client.readline.rstrip.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".
+        # 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 below.
+        # 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("?", 2).first.to_s.sub(%r{^/}, "")
+          path = request_path.split("?").first.to_s.delete_prefix("/")
           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.
+          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)
 
-          # Resolve symlinks last and re-check: a file inside root could
-          # be a symlink pointing outside (e.g. /etc/passwd).
+          # 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
-          # simplecov:disable — TOCTOU: candidate vanished between
-          # File.file? and File.realpath. Treat as "not found".
+          # TOCTOU: candidate vanished between File.file? and File.realpath.
           nil
-          # simplecov:enable
         end
 
         def inside?(path, root)
-          path == root || path.start_with?(root + File::SEPARATOR)
+          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("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

data/lib/simplecov/cli/serve.rb

@@ -7,24 +7,22 @@ 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.
+    # `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
 
-    module_function
+      extend self
 
       def run(args, stdout:, stderr:, **)
         opts = parse(args)
-        dir = SimpleCov::CLI.coverage_dir
+        dir = CLI.coverage_dir
         message = ReportPreparer.call(dir)
         return error(stderr, message) if message
 
-        require "socket"
+        require_socket
         with_server(opts, stderr) do |server|
           announce(stdout, server, dir)
           serve_loop(server, dir, stdout)
@@ -32,14 +30,20 @@ module SimpleCov
         end
       end
 
-      # Returns the block's exit status, or 1 when the socket can't be
-      # bound (port already taken, privileged port, unresolvable host).
+      # 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)
-        # 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
+        server = (_ = TCPServer).new(opts.fetch(:host), opts.fetch(:port)) #: TCPServer
       rescue SystemCallError, SocketError => e
-        error(stderr, "cannot bind to #{opts[:host]}:#{opts[:port]} (#{e.message})")
+        error(stderr, "cannot bind to #{opts.fetch(:host)}:#{opts.fetch(:port)} (#{e})")
       else
         begin
           yield server
@@ -50,29 +54,28 @@ module SimpleCov
 
       def parse(args)
         opts = {port: 0, host: "127.0.0.1"} #: Hash[Symbol, untyped]
-        OptionParser.new do |o|
+        build_parser do |o|
           o.on("--port N", Integer) { |v| opts[:port] = v }
-          o.on("--host HOST")       { |v| opts[:host] = 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])
+        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/).
+      # 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.
+      # 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) }

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

data/lib/simplecov/cli/status/facts.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SimpleCov
+  module CLI
+    module Status
+      module Facts
+        extend self
+
+        def gather(document, resultset_path)
+          contexts = document["contexts"]
+          meta_facts(document).merge(
+            totals: totals(document["total"]),
+            contexts: (contexts.size if contexts.instance_of?(Array)),
+            resultset_path: resultset_path, resultset: readable_resultset(resultset_path)
+          )
+        end
+
+        def meta_facts(document)
+          none = {} #: Hash[String, untyped]
+          recorded = document["meta"]
+          meta = recorded.instance_of?(Hash) ? recorded : none
+          generated = parse_time(meta["timestamp"])
+          {
+            generated_at: meta["timestamp"], age: generated && whole_seconds(Time.now - generated),
+            version: meta["simplecov_version"], command_name: meta["command_name"],
+            commit: meta["commit"], behind: behind(meta["commit"])
+          }
+        end
+
+        def age_of(timestamp)
+          whole_seconds(Process.clock_gettime(Process::CLOCK_REALTIME) - timestamp)
+        end
+
+        def whole_seconds(elapsed)
+          elapsed.truncate
+        end
+
+        def parse_time(value)
+          Time.iso8601(value) if value.instance_of?(String)
+        rescue ArgumentError
+          nil
+        end
+
+        # Commits between the report's commit and HEAD: 0 at HEAD, nil when
+        # unanswerable, meaning no commit recorded, no git, or a commit this
+        # repository has never seen.
+        def behind(commit)
+          return nil unless commit.instance_of?(String)
+
+          stdout, _detail, success = Git.capture("rev-list", "--count", "#{commit}..HEAD")
+          commit_count(_ = stdout) if success
+        end
+
+        # `Integer` ignores surrounding whitespace on its own, so git's trailing
+        # newline needs no trimming. The base is spelled out because bare `Integer`
+        # reads a leading zero as octal.
+        def commit_count(output)
+          Integer(output, 10)
+        end
+
+        def totals(total)
+          return {} unless total.instance_of?(Hash)
+
+          rows = {"line" => "lines", "branch" => "branches", "method" => "methods"}.filter_map do |name, key|
+            percent = total.dig(key, "percent")
+            [name, percent] if percent.is_a?(Numeric)
+          end
+          rows.to_h
+        end
+
+        # An unreadable resultset answers nothing rather than raising: its
+        # absence is a fact, not an error.
+        def readable_resultset(path)
+          parsed = JSON.parse(File.read(path))
+          return nil unless parsed.instance_of?(Hash)
+
+          parsed.map do |command, data|
+            timestamp = data["timestamp"] if data.instance_of?(Hash)
+            {command: command, age: (age_of(timestamp) if timestamp.is_a?(Numeric))}
+          end
+        rescue SystemCallError, JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end