path_coverage 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acac92dac750f3680a27856c6e410469f26c48c6ec23d6363d8b22caba5bc30c
-  data.tar.gz: c19de09501f409d8209ddb1071f37e44b926d9a4381ec302a6c460961ff162f8
+  metadata.gz: 7146cc322217826aadc2bd040b560b5e77d6fad7b6de4d2ae43e8bdfaa893940
+  data.tar.gz: 29135bab12a1cc92d1a15dd8d383d3e79d75b3b8716fff7efa95fbbb6f8c3b34
 SHA512:
-  metadata.gz: 2ec2945b4797a6b1f51f558c2cf2348307e1b6da68e5812c8ad4dfcab51f85926716f425c695cfd7456fec679d17fabf2e6b1400f7f6e131b0ccd9608aed5bce
-  data.tar.gz: 196816d6db1d908d2c578f7c547a9464025187d03c344537b741106faee39aa6c0c1127759456989442497fbc7a33f773a0ca096f92e5aaa599cbec9949f27f6
+  metadata.gz: 4ebf32a5b048eb5d3d1b1cbbca0e2ed9c217e429481d1bd77a242f0a3baff83ee7b83a2b4a4cd99f6a6611885d1c165a56b6bd6f814be28c4cb6a92cffbc8282
+  data.tar.gz: 9ee6e1f2aea70b34ffb38ec5fa16a52f92ae5daf0a680727903db858fcdb557c244d0ae61a048e1a7bc09d99128c0b7068dd408686b2aca683b9f037afe3f6f3

data/README.md

@@ -1,15 +1,21 @@
 # path_coverage
 
+[![Gem Version](https://img.shields.io/gem/v/path_coverage)](https://rubygems.org/gems/path_coverage)
+[![Downloads](https://img.shields.io/gem/dt/path_coverage)](https://rubygems.org/gems/path_coverage)
+[![License](https://img.shields.io/github/license/cyber-dojo/path_coverage)](LICENSE.md)
+
 Path coverage for Ruby, to run alongside SimpleCov's line and branch
 coverage.
 
 Gem: https://rubygems.org/gems/path_coverage (which shows the latest
 version).
 
-Status: sites cover `&&`, `||`, `and`, `or`, the ternary `?:`, and
-`if`/`elsif`/`else`: each leaf operand of a condition, however its
-operators are chained, nested or grouped. Method paths cover `if`
-decisions. Decisions hidden inside calls come next (see Roadmap).
+Status: sites cover `&&`, `||`, `and`, `or`, the ternary `?:`,
+`if`/`elsif`/`else` and `unless` (modifiers included), `case`/`when`
+with a subject, and the block methods `any?` `all?` `none?` `find`
+`detect` `find_index` `take_while` `select` `filter` `reject`
+`partition` `count` `filter_map`. Method paths cover `if` decisions.
+More decisions hidden inside calls come next (see Roadmap).
 
 Demo: https://cyber-dojo.github.io/path_coverage/ shows the HTML report
 for the mock source tree in `demo/`. `make demo` builds and opens the
@@ -65,7 +71,7 @@ PathCoverage.start do
   root APP_DIR                 # cover globs and site names are relative to it
   cover 'source/**/*.rb'       # each matching file is instrumented as it loads
   coverage_dir '/tmp/coverage' # where path_coverage.json is written
-  measure :conditions, :paths  # sites alone unless :paths is named too
+  measure :decisions, :methods # :decisions alone unless :methods is named
   report :gaps, :html          # the reporters run at exit (default :gaps)
 end
 ```
@@ -93,9 +99,18 @@ each report POSTed to it as a numbered file, and once every run is done
 they render as one report:
 
 ```sh
-path_coverage_collector 4570 /tmp/paths/runs   # until stopped
+path_coverage_collector 4570 /tmp/paths/runs   # until sent TERM
 ```
 
+- A report is saved before it is answered 200, so a 200 means it is on
+  disk. A report cut short, eg by a sender dying mid-send, is answered
+  400 and not saved. One that cannot be saved is answered 500.
+- `GET /alive` answers 200 while the collector runs.
+- `GET /ready` answers 200 when its dir is writable, 503 when not. Wait
+  for it before starting the runs.
+- On TERM it stops accepting connections, finishes the report in hand,
+  and exits 0.
+
 ```ruby
 runs = Dir['/tmp/paths/runs/*.json']
 PathCoverage::Render.from_json(config, runs)
@@ -124,7 +139,9 @@ source/kata.rb:4:24 never reached
 source/fee.rb:2:2 fee path never taken: line 4 true, line 7 false
 ```
 
-### Sites
+### Decisions
+
+Measured always, as `:decisions`: the paths within each decision.
 
 A site is named by the `path:line:column` where it starts, the path
 relative to `root`. A site in a covered file the run never loaded is
@@ -157,7 +174,7 @@ across the whole of it, nested conditions included:
 ok?(id) && new?(id) && id.size == 6       # one && site, leaves 0 1 2
 ok?(id) && (new?(id) || id.size == 6)     # an || nested in an && site, 0 1 2
 ok?(id) && new?(id) || id.size == 6       # an && nested in an || site, 0 1 2
-ids.any? { |k| k && k.ok? } && ok?(id)    # two sites: the block's is its own
+ids.map { |k| k && k.ok? } && ok?(id)     # two sites: the block's is its own
 ok?(id) ? :ok : :no                       # a ?: site, its predicate leaf 0
 ok?(id) && new?(id) ? :ok : :no           # an && nested in a ?: site, 0 1
 ok?(id) ? new?(id) && id.size == 6 : :no  # one ?: site, its then arm 1 2
@@ -170,12 +187,30 @@ paths run through whichever arm the predicate picks. Any other arm, like a
 block, is not part of it, though a condition inside it is a site of its
 own.
 
-An `if` (with its `end`, not a modifier) is a site too, even when its
-predicate is a single leaf: its predicate nests in it, an `&&` there
+An `if` or an `unless`, a modifier included, is a site too, even when
+its predicate is a single leaf: its predicate nests in it, an `&&` there
 being no site of its own, and its `then` and `else` arms are plain, as
-they are statements. Its extent is the `if` keyword to the end of its
-predicate, so a site inside an arm keeps its own button. An `elsif` is a
-site of its own.
+they are statements; an `unless` takes its `then` arm when its predicate
+is false. It is named at its keyword, and its extent is its keyword to
+the end of its predicate, so a site inside an arm keeps its own button.
+An `elsif` is a site of its own.
+
+A `case` with a subject is a site whose leaves are its `when` patterns,
+tried in order until one matches. Each pattern is wrapped in a stand-in
+whose `===` calls the pattern's `===` once, exactly as the `case` would,
+and notes whether it matched. A `case` with no subject, or with a splat
+among its patterns, is no site.
+
+A call to a block method, with no arguments and a block of one
+expression, is a site named at its method. Its two leaves are its
+receiver, showing how many items its block was called with (`0 items`,
+`1 item` or `2+ items`), and its block's expression: for `any?` `all?`
+`none?` `find` `detect` `find_index` and `take_while`, which stop once
+their block decides, its last answer; for `select` `filter` `reject`
+`partition` `count` and `filter_map`, which call it with every item,
+whether its answers were `all true`, `all false` or `both`. Both are
+noted from the block's own calls, so the receiver is never asked for its
+size, which could consume a sequence that can be read only once.
 
 A chain of one operator is flat; a change of operator, by precedence or by
 parentheses, nests. Parentheses are not part of the tree, since they decide
@@ -195,7 +230,7 @@ constants, since one can hold nil or false (`VERBOSE = false`). `nil` and
 
 ### Methods
 
-With `measure :conditions, :paths`, each method with two or more
+With `measure :decisions, :methods`, each method with two or more
 decisions also counts each call's path through them: the outcome of each
 decision it reached, in order. A method is named by the `path:line:column`
 of its `def`, then its name. Each decision is one outcome on the path,
@@ -207,8 +242,11 @@ leaves the method ends the path there.
 ### Reporters
 
 - `:html` writes `index.html` to `coverage_dir`: the covered files with
-  their sites, outcomes seen (with a percent) and outcomes missing, each
-  column sortable. Each file name opens `files/<path>.html`, the file's
+  their sites and their paths taken of all possible, within each decision
+  and, when `:methods` is measured, across a method's decisions (eg
+  `9 / 28 (32%)`, or `-` for a file with no method of two or more
+  decisions), each column sortable, and a Total row for every file
+  together. Each file name opens `files/<path>.html`, the file's
   source. On a line holding a site the line number is a button (blue
   and outlined when every outcome was seen, solid orange when any is
   missing) that opens a grid of the site's paths, on the left. Its rows
@@ -275,16 +313,15 @@ the run never loaded are read and parsed then.
 ## Roadmap
 
 - decisions hidden inside calls, each with its own outcome classes:
-  - `any?` / `all?` / `none?`: empty, decided by the first item, decided
-    later, never decided
-  - `find` / `detect`: found vs nil
+  - `one?`, whose last answer does not decide it, and block methods
+    with blocks of more than one expression
   - `fetch(k, default)`, `dig`, `Hash#[]` with a default: present vs default
   - `x || default` in value context, `&.` safe navigation: nil vs not nil
   - `||=` and `&&=`, on variables, attributes and index targets: the
     right side evaluated vs skipped, counted without evaluating the
     target twice
   - `x rescue y` modifier: raised vs not raised
-  - `unless`, modifier `if`, `case`/`when` and `in` patterns
+  - `case` with no subject, and `case`/`in` patterns
   - regex matches: nil vs MatchData
 
 ## Constraints

data/exe/path_coverage_collector

@@ -9,7 +9,13 @@ if ARGV.first == '-h'
 
     Listens on PORT and saves each JSON report the :post reporter
     sends as DIR/run-0001.json, DIR/run-0002.json, and so on,
-    creating DIR if need be. Runs until stopped.
+    creating DIR if need be. A 200 means the report is saved.
+
+    GET /alive answers 200 while it runs.
+    GET /ready answers 200 when DIR is writable, 503 when not.
+
+    Runs until sent TERM. It then stops accepting connections,
+    finishes the report in hand, and exits 0.
 
     Options:
       -h    Show this help
@@ -23,4 +29,9 @@ end
 port, dir = ARGV
 FileUtils.mkdir_p(dir)
 server = TCPServer.new('0.0.0.0', Integer(port))
+# Closing the server on TERM makes serve return once the
+# report in hand, if any, is saved and answered. The close
+# runs in a thread of its own, as the trap runs on the thread
+# that may be waiting in accept, where a close deadlocks.
+Signal.trap('TERM') { Thread.new { server.close } }
 PathCoverage::Collector.serve(server, dir)

data/lib/path_coverage/calls.rb

@@ -0,0 +1,67 @@
+# The calls rewritten code makes, each handed to the kernel's
+# one recorder. Like the kernel, this file loads before any
+# covered file and is never itself instrumented.
+module PathCoverage
+  # The call rewritten code makes around each operand; returns
+  # value unchanged.
+  def self.record(site, index, value)
+    @recorder.record(site, index, value)
+  end
+
+  # The call rewritten code makes before a site's first leaf,
+  # site having size leaves; returns the evaluation's trail.
+  def self.enter(site, size)
+    @recorder.enter(site, size)
+  end
+
+  # The call rewritten code makes around a site as a whole,
+  # with the trail enter gave it; returns value unchanged.
+  def self.leave(trail, value)
+    @recorder.leave(trail, value)
+  end
+
+  # The call rewritten code makes around a case's pattern, the
+  # index-th of size at site; returns the pattern's stand-in.
+  def self.when_match(site, index, size, pattern)
+    @recorder.when_match(site, index, size, pattern)
+  end
+
+  # The call rewritten code makes before a block method's call
+  # at site runs; returns the evaluation's trail.
+  def self.enter_items(site)
+    @recorder.enter_items(site)
+  end
+
+  # The call rewritten code makes around a block method's
+  # block's expression at site; returns value unchanged.
+  def self.item(site, value)
+    @recorder.item(site, value)
+  end
+
+  # The call rewritten code makes around the block's expression
+  # of a block method that calls it with every item; returns
+  # value unchanged.
+  def self.answer(site, value)
+    @recorder.answer(site, value)
+  end
+
+  # The call rewritten code makes around a block method's call
+  # as a whole, with the trail enter_items gave it; returns
+  # value unchanged.
+  def self.leave_items(trail, value)
+    @recorder.leave_items(trail, value)
+  end
+
+  # The call rewritten code makes as a call reaches its
+  # method's first decision; returns the call's new path.
+  def self.path(site, size)
+    @recorder.path(site, size)
+  end
+
+  # The call rewritten code makes around each decision's
+  # predicate, with exits for one whose arm leaves the method;
+  # returns value unchanged.
+  def self.decide(path, index, value, exits = nil)
+    @recorder.decide(path, index, value, exits)
+  end
+end

data/lib/path_coverage/collector.rb

@@ -3,44 +3,110 @@ module PathCoverage
   # runs that sent them, eg failing docker build steps, can
   # be merged and rendered once they are all done.
   module Collector
-    # Answers every request on server, forever, saving each
-    # body in dir as run-0001.json, run-0002.json, and so on,
-    # in the order they arrive. A connection sending no
-    # request, eg a check that the collector is up, is skipped.
+    # Answers every request on server until server is closed,
+    # then returns.
+    # Each report is saved in dir as run-0001.json,
+    # run-0002.json, and so on, in the order they arrive.
+    # A connection sending no request is skipped.
     def self.serve(server, dir)
       n = 0
-      loop do
-        body = request_body(server.accept)
-        next if body.nil?
-
-        n += 1
-        File.write(format('%<dir>s/run-%<n>04d.json', dir:, n:), body)
+      while (client = accept(server))
+        saved = receive(client, dir) do |body|
+          save(dir, format('run-%<n>04d.json', n: n + 1), body)
+        end
+        n += 1 if saved
       end
     end
 
-    # The body of the one HTTP request on client, after
-    # answering it 200; nil, unanswered, when client closes
-    # without sending a request.
-    def self.request_body(client)
+    # The next connection to server; nil once server is closed,
+    # which is how serve is told to return.
+    def self.accept(server)
+      server.accept
+    rescue IOError
+      nil
+    end
+
+    # Saves body as dir/name whole or not at all: it is written
+    # to name.tmp and renamed, so a collector stopped mid-write
+    # leaves no partial report under a run's name.
+    def self.save(dir, name, body)
+      path = "#{dir}/#{name}"
+      File.write("#{path}.tmp", body)
+      File.rename("#{path}.tmp", path)
+    end
+
+    # Hands the body of the one HTTP request on client to the
+    # block, which saves it, and returns whether it was saved.
+    # dir is where reports are saved, which GET /ready checks.
+    # A client that closes without sending a request, eg a
+    # check that the collector is up, is closed unanswered and
+    # nothing is saved.
+    def self.receive(client, dir, &)
       headers = []
       while (line = client.gets) && line != "\r\n"
         headers << line
       end
-      body = headers.empty? ? nil : answer(client, headers)
+      saved = !headers.empty? && respond(client, headers, dir, &)
       client.close
-      body
+      saved
+    end
+
+    # The check each GET path makes of the collector's dir.
+    # GET /alive passes whenever the collector answers.
+    # GET /ready passes only when dir is a writable directory,
+    # so a report sent now could be saved.
+    PROBES = {
+      '/alive' => ->(_dir) { true },
+      '/ready' => lambda do |dir|
+        File.directory?(dir) && File.writable?(dir)
+      end
+    }.freeze
+
+    # Answers the request with headers on client, and returns
+    # whether a report was saved in dir.
+    # A GET of a path in PROBES is answered 200 when its check
+    # passes, 503 when not. Nothing is saved for it.
+    # Any other request is a report, handed to answer.
+    def self.respond(client, headers, dir, &)
+      probe = PROBES[headers.first[/\AGET (\S+) /, 1]]
+      return answer(client, headers, &) if probe.nil?
+
+      up = probe.call(dir)
+      reply(client, up ? '200 OK' : '503 Service Unavailable')
+      false
     end
 
-    # The body of a request with headers, read from client,
-    # which is then answered 200.
+    # Reads the body of a request with headers from client and
+    # yields it to be saved. Returns whether it was saved.
+    # The 200 is sent only once it is saved.
+    # So a 200 always means the report is on disk.
+    # A body shorter than its Content-Length is answered 400.
+    # Eg its sender died mid-send. It is not saved.
+    # A save that fails is answered 500.
     def self.answer(client, headers)
-      length = headers.sum do |line|
+      length = content_length(headers)
+      body = client.read(length).to_s
+      whole = body.bytesize == length
+      yield body if whole
+      reply(client, whole ? '200 OK' : '400 Bad Request')
+      whole
+    rescue SystemCallError
+      reply(client, '500 Internal Server Error')
+      false
+    end
+
+    # The byte length headers give the request's body; 0 when
+    # they give none.
+    def self.content_length(headers)
+      headers.sum do |line|
         name, value = line.split(':', 2)
         name.casecmp?('content-length') ? value.to_i : 0
       end
-      body = client.read(length)
-      client.write("HTTP/1.1 200 OK\r\nContent-Length: 0\r\n\r\n")
-      body
+    end
+
+    # Writes an HTTP response of status, with no body, to client.
+    def self.reply(client, status)
+      client.write("HTTP/1.1 #{status}\r\nContent-Length: 0\r\n\r\n")
     end
   end
 end

data/lib/path_coverage/condition.rb

@@ -1,9 +1,60 @@
 module PathCoverage
   # The operators whose predicate picks an arm.
-  CHOICES = %w[?: if].freeze
+  CHOICES = %w[?: if unless].freeze
 
-  # One arm of a ternary or an if: kind is :then or :else,
-  # extent its byte range, nil for an if's arm with no
+  # The choices whose arms are statements, so whose path is
+  # decided by their predicate alone.
+  STATEMENT_CHOICES = %w[if unless].freeze
+
+  # The predicate outcome on which each choice takes its then
+  # arm: an unless's is false.
+  THEN_ON = Hash.new(true).merge('unless' => false).freeze
+
+  # The methods that call their block an item at a time until
+  # it decides, its last answer deciding the result.
+  STOP_EARLY = %w[
+    any? all? none? find detect find_index take_while
+  ].freeze
+
+  # How many items a block method's block was called with, as
+  # its receiver's leaf outcome: none, one, or two or more.
+  ITEMS = ['0 items', '1 item', '2+ items'].freeze
+
+  # Every path a stop-early block method's call can take: how
+  # many items its block was called with, and its last answer,
+  # nil when it was never called.
+  STOP_EARLY_PATHS = [
+    [ITEMS[0], nil],
+    [ITEMS[1], true], [ITEMS[1], false],
+    [ITEMS[2], true], [ITEMS[2], false]
+  ].freeze
+
+  # The methods that call their block with every item.
+  EVERY_ITEM = %w[
+    select filter reject partition count filter_map
+  ].freeze
+
+  # A block's answers over every item it was called with.
+  ANSWERS = ['all true', 'all false', 'both'].freeze
+
+  # Every path an every-item block method's call can take: how
+  # many items its block was called with, and its answers,
+  # which can be both only with two or more items.
+  EVERY_ITEM_PATHS = [
+    [ITEMS[0], nil],
+    [ITEMS[1], ANSWERS[0]], [ITEMS[1], ANSWERS[1]],
+    [ITEMS[2], ANSWERS[0]], [ITEMS[2], ANSWERS[1]],
+    [ITEMS[2], ANSWERS[2]]
+  ].freeze
+
+  # Every block method whose call is a site, by its paths.
+  BLOCK_PATHS = [
+    *STOP_EARLY.map { |name| [name, STOP_EARLY_PATHS] },
+    *EVERY_ITEM.map { |name| [name, EVERY_ITEM_PATHS] }
+  ].to_h.freeze
+
+  # One arm of a ternary, an if or an unless: kind is :then or
+  # :else, extent its byte range, nil for an arm with no
   # statements, and body the Condition it is, when it is one,
   # else nil for a plain value or statements, which decide
   # nothing.

data/lib/path_coverage/configuration.rb

@@ -9,25 +9,28 @@ module PathCoverage
       collector cover coverage_dir measure report root
     ].freeze
     REPORTERS = %w[gaps html post].freeze
-    MEASURES = %w[conditions paths].freeze
+    MEASURES = %w[decisions methods].freeze
 
     # Evaluates the settings block against a new configuration.
     def initialize(&)
       @globs = []
       @reporters = [:gaps]
-      @measures = [:conditions]
+      @measures = [:decisions]
       instance_eval(&)
     end
 
     # The reporters chosen with report, :gaps when none were.
     attr_reader :reporters
 
-    # What is measured, chosen with measure, :conditions when
-    # nothing was.
+    # What is measured, chosen with measure.
+    # :decisions, the paths within each decision, when nothing
+    # was chosen.
     attr_reader :measures
 
-    # Chooses what is measured, eg measure :conditions, :paths;
-    # refuses a name there is no measure for.
+    # Chooses what is measured.
+    # Eg measure :decisions, :methods also measures the paths
+    # across each method's decisions.
+    # Refuses a name there is no measure for.
     def measure(*names)
       check('measure', names, MEASURES)
       @measures = names.map(&:to_sym)

data/lib/path_coverage/html/index.html

@@ -19,13 +19,16 @@
 <tr>
 <th aria-sort="none"><button type="button" data-column="0" data-type="text">File</button></th>
 <th class="num" aria-sort="none"><button type="button" data-column="1" data-type="number">Sites</button></th>
-<th class="num" aria-sort="none"><button type="button" data-column="2" data-type="number">Outcomes seen</button></th>
-<th class="num" aria-sort="none"><button type="button" data-column="3" data-type="number">Missing</button></th>
+<th class="num" aria-sort="none"><button type="button" data-column="2" data-type="number">Within each decision</button></th>
+{{across}}
 </tr>
 </thead>
 <tbody>
 {{rows}}
 </tbody>
+<tfoot>
+{{total}}
+</tfoot>
 </table>
 </div>
 </main>

data/lib/path_coverage/html/side.js

@@ -71,19 +71,30 @@
     });
     var side = !panel ? '' : panel.classList.contains('tree') ? 'cc' : 'pc';
     document.body.setAttribute('data-open', side);
-    slide();
+    slide(panel);
+  }
+
+  // Scrolls the page just enough to show all of panel when it
+  // is a tree, eg one opened from a line near the bottom of the
+  // window, so its last rows are not below the fold. Its first
+  // row stays level with its site's line.
+  function showWhole(panel) {
+    if (panel && panel.classList.contains('tree')) {
+      panel.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+    }
   }
 
   // How long a rail takes to open or close, as style.css has it.
   var SLIDE_MS = 250;
 
   // Places everything on every frame while the rails slide, as
-  // the bars and bands follow the code across.
-  function slide() {
+  // the bars and bands follow the code across, then shows all
+  // of panel, the one just opened, once it is in its place.
+  function slide(panel) {
     var end = performance.now() + SLIDE_MS + 50;
     function frame(now) {
       place();
-      if (now < end) { requestAnimationFrame(frame); }
+      if (now < end) { requestAnimationFrame(frame); } else { showWhole(panel); }
     }
     requestAnimationFrame(frame);
   }

data/lib/path_coverage/html/sort.js

@@ -1,5 +1,7 @@
 // Sorts the files table by the clicked column's data-sort values;
-// a second click on the same column reverses the order.
+// a second click on the same column reverses the order. A cell
+// with an empty data-sort, one with no value such as a -, stays
+// last in both orders, so either end of the values can be first.
 (function () {
   var table = document.getElementById('files');
   var body = table.tBodies[0];
@@ -15,6 +17,7 @@
       rows.sort(function (a, b) {
         var x = a.cells[column].dataset.sort;
         var y = b.cells[column].dataset.sort;
+        if (x === '' || y === '') { return (x === '') - (y === ''); }
         var order = numeric ? Number(x) - Number(y) : x.localeCompare(y);
         return state.ascending ? order : -order;
       });

data/lib/path_coverage/html/style.css

@@ -46,6 +46,10 @@ th, td { padding: 10px 16px; text-align: left; }
 th { background: var(--panel); }
 td { border-top: 1px solid var(--rule); }
 td:first-child { font-family: var(--font-code); }
+/* The Total row frames the table's foot as the headings do its
+   head, so it reads as a sum, not as one more file. */
+tfoot td { background: var(--panel); font-weight: 600; border-top: 1px solid var(--fg); }
+tfoot td:first-child { font-family: inherit; }
 .num, td:not(:first-child) { text-align: right; }
 th button {
   font: 600 13px var(--font-body); color: var(--fg); background: none; border: 0;