path_coverage 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc1af74670e1171318d1d58fbd6a27f19b89c01ac95ee556f4e6bac3afa2bfbf
-  data.tar.gz: 2ecf0d75608a054914d31e426c77f75cc607ac578671a8e93fe4494efd040ea2
+  metadata.gz: acac92dac750f3680a27856c6e410469f26c48c6ec23d6363d8b22caba5bc30c
+  data.tar.gz: c19de09501f409d8209ddb1071f37e44b926d9a4381ec302a6c460961ff162f8
 SHA512:
-  metadata.gz: 41b26c437c12f9b6aa7ab78d3a4a50a2fd532d2a8db0923813a059943fc0289d3421a78e754c633db0ea20962e42564031b98453c2e2ad6cb6d61cef81557ac8
-  data.tar.gz: 52b79781e54c09a07d1b6733ef3356ba8aac5cc87881fdb0303aae99842d2ef48cf00e555e29f11215fc8c1516986bf2f8bff02fdb5d539da3f48c0e688d1c79
+  metadata.gz: 2ec2945b4797a6b1f51f558c2cf2348307e1b6da68e5812c8ad4dfcab51f85926716f425c695cfd7456fec679d17fabf2e6b1400f7f6e131b0ccd9608aed5bce
+  data.tar.gz: 196816d6db1d908d2c578f7c547a9464025187d03c344537b741106faee39aa6c0c1127759456989442497fbc7a33f773a0ca096f92e5aaa599cbec9949f27f6

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2026, [CyberDojo Foundation](http://blog.cyber-dojo.org/2015/08/cyber-dojo-foundation.html)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,316 @@
+# path_coverage
+
+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).
+
+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
+same report locally.
+
+Take this method:
+
+```ruby
+def fee(user, order)
+  total = 100
+  if user.member? && order.paid?
+    total -= 5
+  end
+  if order.big?
+    total -= 10
+  end
+  total
+end
+```
+
+Tests that run both `if`s both ways reach every line and every branch,
+so SimpleCov, which reads Ruby's built-in `Coverage`, reports 100%. Yet
+they can still miss paths, at two scopes, and path_coverage lists each
+path no test took.
+
+## Within each decision
+
+The first `if` can go three ways: member and paid, member and not
+paid, not a member. A member who has not paid may never have been
+tried.
+
+![The first if's grid: a column per way it can go, each headed by
+its count, the member who has not paid at 0](docs/decision.png)
+
+## Across a method's decisions
+
+The two `if`s can go four ways together. A paying member with a small
+order may never have been tried.
+
+![fee's grid: a column per way its two ifs can go together, each
+headed by its count, true then false at 0 and selected](docs/method.png)
+
+## Use
+
+```ruby
+# test coverage config, before any application code is required
+require 'simplecov'
+require 'path_coverage'
+SimpleCov.start do
+  # ...
+end
+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
+  report :gaps, :html          # the reporters run at exit (default :gaps)
+end
+```
+
+A misspelt setting or an unknown reporter is refused by name, with the list
+of the ones there are. Calling `start` again replaces the configuration.
+
+A run whose code cannot be changed, such as a script in a `docker build`
+step, can be covered from its environment alone:
+
+```sh
+RUBYOPT=-rpath_coverage/auto
+PATH_COVERAGE_ROOT=/app                   # root
+PATH_COVERAGE_COVER=src/**/*.rb,lib/*.rb  # cover, comma-separated
+PATH_COVERAGE_DIR=/tmp/paths              # coverage_dir
+PATH_COVERAGE_COLLECTOR=http://host.docker.internal:4570/runs
+```
+
+This starts with `report :post`. With no `PATH_COVERAGE_COLLECTOR` it
+starts nothing and prints nothing, so an image can set `RUBYOPT` for every
+run and measure only those given a collector.
+
+The gem's `path_coverage_collector` command is that collector. It saves
+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
+```
+
+```ruby
+runs = Dir['/tmp/paths/runs/*.json']
+PathCoverage::Render.from_json(config, runs)
+```
+
+## What a run reports
+
+As the process exits:
+
+- `path_coverage.json` is always written to `coverage_dir`: every site
+  of every covered file, with each operand's true and false counts under
+  `sites`, and each site's paths under `paths`. It is the base the other
+  reporters read, so they can also be run later, in another process, from
+  it alone: `PathCoverage::Render.from_json(config)`, where `config` is a
+  `PathCoverage::Configuration` built from the same settings block.
+  Given several runs' reports, `Render.from_json(config, paths)` adds
+  their counts together first, so the report shows only the gaps that
+  every run left.
+- `:gaps` prints one line per path never taken, in manifest order: a
+  site's naming the outcome of each leaf on it, a method's the outcome
+  of each decision on it, by line:
+
+```text
+source/kata.rb:3:23 path never taken: `ok?(id)` true, `new?(id)` false
+source/kata.rb:4:24 never reached
+source/fee.rb:2:2 fee path never taken: line 4 true, line 7 false
+```
+
+### Sites
+
+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
+still reported, as `never reached`.
+
+A path is the outcome of each leaf one evaluation of the site reached, in
+order; a leaf that short-circuiting skipped is not on it. Each leaf is
+quoted as a Markdown code span, on one line, its fence one backtick longer
+than any run of backticks inside it. The gap lines are for people; a tool
+should read the JSON, whose `paths` give each site's leaves as
+`line:column` spans, and each possible path with its count:
+
+```json
+"paths": {
+  "source/kata.rb:3:23": {
+    "leaves": [["3:23", "3:30"], ["3:34", "3:42"]],
+    "taken": [
+      { "path": [true, true], "count": 2 },
+      { "path": [true, false], "count": 0 },
+      { "path": [false, null], "count": 1 }
+    ]
+  }
+}
+```
+
+A site is an outermost condition. Its leaves are numbered left to right
+across the whole of it, nested conditions included:
+
+```ruby
+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
+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
+```
+
+A ternary is a site even when its predicate is a single leaf. An arm
+holding a condition of `&&`, `||`, `and`, `or` or `?:` is part of the
+ternary's site, its leaves numbered after the predicate's, so the site's
+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
+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.
+
+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
+nothing.
+
+A leaf whose form allows one outcome only needs only to be evaluated: a
+path needing its other outcome is impossible, not a gap. `Foo.new`,
+literals (`'s'`, `1`, `:k`, `[]`, `{}`, `true`) and lambdas can only be
+truthy, as can `$stdout` and `$stderr`, which Ruby refuses to set to nil
+or false. Other globals, `$stdin` among them, can be either, as can
+constants, since one can hold nil or false (`VERBOSE = false`). `nil` and
+`false` can only be falsy:
+
+```ruby
+@clock = options[:clock] || MonotonicClock.new  # leaf 1: never evaluated, or no gap
+```
+
+### Methods
+
+With `measure :conditions, :paths`, 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,
+however many leaves its predicate has; those are its site's to show. So a
+site's columns stay its own leaves' combinations, and a method's its own
+decisions', rather than multiplying together. A decision whose arm always
+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
+  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
+  are the site's tree: its operators, nested as Ruby groups them, a
+  ternary's arms marked `?` and `:`, an `if`'s named `then` and `else`,
+  and its leaves. Its columns are the site's paths, never taken first,
+  each headed by its count, orange when zero; a leaf shows its outcome on
+  each path, T or F, blank where the path never reached it, and a plain
+  arm a dot on each path that took it. A site written over several lines
+  has one button over all of its line numbers. Grids with gaps start
+  open. A header that stays at the top of the page lists every site as a
+  link to its line, covered sites first, then those with gaps, and arrows
+  beside each site with gaps jump to the previous and next one, wrapping
+  round at either end. Measuring paths, each method's grid of its
+  decisions' paths opens on the right.
+- `:post` sends the JSON report, as an HTTP POST, to the url set by
+  `collector 'http://...'`. It is for a run whose own files are thrown
+  away, such as a failing `docker build` step. It prints nothing, never
+  goes through an `http_proxy`, and gives up in silence on a collector
+  that cannot be reached or does not answer within a second, so the
+  run's output and exit status are unchanged.
+
+## How it works
+
+At load time each covered file is read and parsed once, with Prism. The
+parse gives the manifest: each site's condition tree and the byte range of
+each of its leaves. The rewriter then inserts a record call around each
+leaf, and a leave call around the whole site, whose first argument enters
+it, without parsing again, and the result is compiled in place of the
+file:
+
+```ruby
+ok?(id) && new?(id)
+# compiles as
+PathCoverage.leave(PathCoverage.enter("k.rb:2:2", 2), PathCoverage.record("k.rb:2:2", 0, ok?(id)) && PathCoverage.record("k.rb:2:2", 1, new?(id)))
+```
+
+An `if` site's leave call wraps its predicate alone, as its path is
+decided there, so an arm that returns or raises still counts it.
+Measuring paths, each method starts a path at its entry, and each
+decision's predicate is wrapped in a decide call too, outside its site's
+calls.
+
+A command call such as `ok? id` (after `and`) is not valid as a bare
+argument, so that leaf alone gets parentheses of its own, and so does a
+whole `and` or `or` inside its leave call. Nothing else does:
+parentheses make a statement, and a statement on a continuation line gives
+that line a line-coverage count of its own, which changes SimpleCov's line
+totals. So a command call, or an `and` or `or`, written over several lines
+can add to SimpleCov's relevant lines; nothing else does.
+
+`record` counts whether its value was truthy or falsy, and notes it on the
+site's current path; `enter` starts that path, and `leave` counts it.
+Each returns its value unchanged, so short-circuiting and the value of
+the expression are preserved. Paths are kept per fiber, so threads never
+mix their outcomes; an evaluation cut short by a raise counts no path,
+so no path is ever claimed that was not taken. Only text is inserted,
+never a newline, so backtrace line numbers still match the file. The
+rewrite happens in memory; no file on disk changes.
+
+At exit the manifests parsed during the run are reused; only covered files
+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
+  - `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
+  - regex matches: nil vs MatchData
+
+## Constraints
+
+- CRuby only: the hook is `RubyVM::InstructionSequence.load_iseq`.
+- Ruby 3.2 or later, for `String#bytesplice`.
+- That hook has a single slot, which Bootsnap also uses, so the two cannot
+  both be active in one process.
+
+## Development
+
+`make all` runs, in a Docker image built from the repo's `Dockerfile`:
+
+- `make lint`: rubocop over `lib/`, `test/` and `bin/` alike
+- `make test`: the tests, then a check that the coverage report has zero
+  missed lines and branches in both the code and the tests, within the
+  bounds in `test/coverage_metrics_params.json`
+  (`make test tids='6D1K'` runs only matching tests, and skips the check)
+- `make test_check`: shunit2 tests showing that a breached bound fails the
+  check with a non-zero exit
+
+`make demo` (not part of `make all`) runs `demo/run.rb` through
+`bin/build_demo.sh`, writing the report to `site/` and opening it. The
+Pages workflow (`.github/workflows/pages.yml`) runs the same script on
+each push to `main` and publishes `site/`.
+
+`bin/capture_readme_images.sh` rebuilds the demo and saves this README's
+two screenshots, `docs/decision.png` and `docs/method.png`, from it with
+headless Chrome. Run it again whenever the report's look changes.

data/exe/path_coverage_collector

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+require 'socket'
+require 'path_coverage/collector'
+
+if ARGV.first == '-h'
+  puts <<~HELP
+    Usage: path_coverage_collector PORT DIR
+
+    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.
+
+    Options:
+      -h    Show this help
+
+    Example:
+      path_coverage_collector 4570 /tmp/condition/runs
+  HELP
+  exit 0
+end
+
+port, dir = ARGV
+FileUtils.mkdir_p(dir)
+server = TCPServer.new('0.0.0.0', Integer(port))
+PathCoverage::Collector.serve(server, dir)

data/lib/path_coverage/auto.rb

@@ -0,0 +1,5 @@
+require_relative 'kernel'
+
+# Required by RUBYOPT=-rpath_coverage/auto, to cover a run
+# with no change to its code, its settings all in ENV.
+PathCoverage.start_from_env(ENV)

data/lib/path_coverage/collector.rb

@@ -0,0 +1,46 @@
+module PathCoverage
+  # Receives the JSON reports the :post reporter sends, so the
+  # 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.
+    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)
+      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)
+      headers = []
+      while (line = client.gets) && line != "\r\n"
+        headers << line
+      end
+      body = headers.empty? ? nil : answer(client, headers)
+      client.close
+      body
+    end
+
+    # The body of a request with headers, read from client,
+    # which is then answered 200.
+    def self.answer(client, headers)
+      length = 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
+  end
+end

data/lib/path_coverage/condition.rb

@@ -0,0 +1,45 @@
+module PathCoverage
+  # The operators whose predicate picks an arm.
+  CHOICES = %w[?: if].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
+  # statements, and body the Condition it is, when it is one,
+  # else nil for a plain value or statements, which decide
+  # nothing.
+  Arm = Data.define(:kind, :extent, :body)
+
+  # One site's condition as the manifest found it: its operator
+  # and its operands, each the byte range of a leaf or a nested
+  # Condition. A site's commands are the byte ranges of its
+  # leaves that are command calls, eg `ok? id`; its fixed are
+  # { byte range => :truthy } for leaves that can have that one
+  # outcome only, eg `Clock.new`. Its extent is the byte range
+  # of the whole condition as written, eg a ternary's from its
+  # predicate to its else arm, which its leaves alone cannot
+  # give.
+  Condition = Data.define(
+    :operator, :operands, :commands, :fixed, :extent
+  ) do
+    # A condition with no command-call or fixed leaves, and no
+    # extent, by default.
+    def initialize(
+      operator:, operands:, commands: [], fixed: {}, extent: nil
+    )
+      super
+    end
+
+    # The byte range of every leaf operand, left to right, a
+    # ternary's arms' after its predicate's; a leaf's index here
+    # is the index it is recorded under.
+    def leaves
+      operands.flat_map do |operand|
+        case operand
+        when Condition then operand.leaves
+        when Arm then operand.body&.leaves || []
+        else [operand]
+        end
+      end
+    end
+  end
+end

data/lib/path_coverage/configuration.rb

@@ -0,0 +1,127 @@
+module PathCoverage
+  # Raised for a start block that cannot be applied.
+  class ConfigurationError < StandardError; end
+
+  # The settings given in a PathCoverage.start block.
+  class Configuration
+    GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+    SETTINGS = %w[
+      collector cover coverage_dir measure report root
+    ].freeze
+    REPORTERS = %w[gaps html post].freeze
+    MEASURES = %w[conditions paths].freeze
+
+    # Evaluates the settings block against a new configuration.
+    def initialize(&)
+      @globs = []
+      @reporters = [:gaps]
+      @measures = [:conditions]
+      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.
+    attr_reader :measures
+
+    # Chooses what is measured, eg measure :conditions, :paths;
+    # refuses a name there is no measure for.
+    def measure(*names)
+      check('measure', names, MEASURES)
+      @measures = names.map(&:to_sym)
+    end
+
+    # The dir the reports are written to.
+    def output_dir
+      @coverage_dir
+    end
+
+    # The url the :post reporter sends the JSON report to.
+    attr_reader :collector_url
+
+    # Sets the url the :post reporter sends the JSON report to.
+    def collector(url)
+      @collector_url = url
+    end
+
+    # Sets the dir that cover globs and site names are
+    # relative to.
+    def root(dir)
+      @root = dir
+    end
+
+    # Adds a glob, relative to root, of files to instrument.
+    def cover(glob)
+      @globs << glob
+    end
+
+    # Chooses the reporters run at exit, eg report :gaps;
+    # refuses a name there is no reporter for.
+    def report(*names)
+      check('reporter', names, REPORTERS)
+      @reporters = names.map(&:to_sym)
+    end
+
+    # Refuses the first of names that is not in known, naming
+    # it as a kind and listing the known ones.
+    def check(kind, names, known)
+      names.each do |name|
+        next if known.include?(name.to_s)
+
+        raise ConfigurationError, [
+          "unknown #{kind} #{name} in PathCoverage.start",
+          "the #{kind}s are: #{known.join(', ')}"
+        ].join("\n")
+      end
+    end
+
+    # Sets the dir the path_coverage.json report is
+    # written to.
+    def coverage_dir(dir)
+      @coverage_dir = dir
+    end
+
+    # Every file the cover globs match under root, as full
+    # paths, whether or not the run loads it.
+    def files
+      Dir.glob(@globs, base: @root).sort.map { |f| "#{@root}/#{f}" }
+    end
+
+    # Where the JSON report goes.
+    def json_path
+      "#{output_dir}/path_coverage.json"
+    end
+
+    # True when path is under root and matches a cover glob.
+    def covers?(path)
+      path.start_with?("#{@root}/") && matches?(relative(path))
+    end
+
+    # True when the root-relative path matches a cover glob.
+    def matches?(relative_path)
+      @globs.any? do |glob|
+        File.fnmatch?(glob, relative_path, GLOB_FLAGS)
+      end
+    end
+
+    # path relative to root, eg "source/kata.rb".
+    def relative(path)
+      path.delete_prefix("#{@root}/")
+    end
+
+    # Refuses a setting that does not exist, naming it.
+    def method_missing(name, *)
+      raise ConfigurationError, [
+        "unknown setting #{name} in PathCoverage.start",
+        "the settings are: #{SETTINGS.join(', ')}"
+      ].join("\n")
+    end
+
+    # Answers only for the settings there are.
+    def respond_to_missing?(_name, _include_private = false)
+      false
+    end
+  end
+end

data/lib/path_coverage/gaps.rb

@@ -0,0 +1,60 @@
+module PathCoverage
+  # The terminal worklist: one line per path a site never
+  # took, and nothing for a site that took them all. Every
+  # count stays in the operands and paths for reporters that
+  # show them all.
+  module Gaps
+    # The gap lines of operands and paths, as Result gives
+    # them, in manifest order; texts is { site => each leaf's
+    # source text }.
+    def self.lines(operands, paths: {}, texts: {})
+      operands.flat_map do |site, counts|
+        if counts.all? { |each| never_ran?(each) }
+          next ["#{site} never reached"]
+        end
+
+        path_gaps(site, paths.fetch(site, []), texts[site])
+      end
+    end
+
+    # One line per path site never took, as Result#paths gives
+    # them, naming the outcome of each leaf the path reaches,
+    # texts being each leaf's source text.
+    def self.path_gaps(site, paths, texts)
+      paths.select { |each| each[:count].zero? }.map do |each|
+        steps = each[:path].zip(texts).filter_map do |outcome, text|
+          "#{code(text)} #{outcome}" unless outcome.nil?
+        end
+        "#{site} path never taken: #{steps.join(', ')}"
+      end
+    end
+
+    # text as a markdown code span on one line: each run of
+    # whitespace one space, fenced by a run of backticks one
+    # longer than any inside it, with a space inside the fence
+    # when text starts or ends with one.
+    def self.code(text)
+      text = text.gsub(/\s+/, ' ')
+      longest = text.scan(/`+/).map(&:size).max || 0
+      fence = '`' * (longest + 1)
+      pad = text.start_with?('`') || text.end_with?('`') ? ' ' : ''
+      "#{fence}#{pad}#{text}#{pad}#{fence}"
+    end
+
+    # The one outcome this operand is missing, if any; a fixed
+    # leaf, which can have one outcome only, needs only to run.
+    def self.operand_gap(counts)
+      return ['never evaluated'] if never_ran?(counts)
+      return [] if counts[:only]
+      return ['never true'] if counts[:truthy].zero?
+      return ['never false'] if counts[:falsy].zero?
+
+      []
+    end
+
+    # True when the operand was never recorded either way.
+    def self.never_ran?(counts)
+      counts[:truthy].zero? && counts[:falsy].zero?
+    end
+  end
+end