path_coverage 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7146cc322217826aadc2bd040b560b5e77d6fad7b6de4d2ae43e8bdfaa893940
-  data.tar.gz: 29135bab12a1cc92d1a15dd8d383d3e79d75b3b8716fff7efa95fbbb6f8c3b34
+  metadata.gz: c68ba875b18ba000eb6be70f5c7bcb294ab4d50915868b913825c3f53bc60a93
+  data.tar.gz: 2beaba1e32cd4110ff9d04d3ab06e8c689395748566502a092175d8a339c9a5d
 SHA512:
-  metadata.gz: 4ebf32a5b048eb5d3d1b1cbbca0e2ed9c217e429481d1bd77a242f0a3baff83ee7b83a2b4a4cd99f6a6611885d1c165a56b6bd6f814be28c4cb6a92cffbc8282
-  data.tar.gz: 9ee6e1f2aea70b34ffb38ec5fa16a52f92ae5daf0a680727903db858fcdb557c244d0ae61a048e1a7bc09d99128c0b7068dd408686b2aca683b9f037afe3f6f3
+  metadata.gz: 6539c5ce97bd892ee616d0b1f780c79f18624381a404d3e6d2c60f6245957243b5ac7c395e130496fbbb2ba0ac6d69b4e9daf8e4fd235cb124d184aa3f8e5ad2
+  data.tar.gz: f72f62b796ad07d0290f56a88bc920ef1088b81abc04c6667ae1ee612e97499cc2f40ca6689acb1e8df35ebff607b463e8ec5ef271de11227bcf01017e98bb42

data/README.md

@@ -7,58 +7,19 @@
 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 `?:`,
 `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.
+`partition` `count` `filter_map`, the writes `||=` and `&&=`, and `&.`
+safe-navigation chains. 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
 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
+## Getting started
 
 ```ruby
 # test coverage config, before any application code is required
@@ -70,14 +31,101 @@ 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
+  cover 'test/**/*.rb'         # more than one cover glob may be given
+  skip 'source/vendor/**/*.rb' # except these, though a cover glob matches them
   coverage_dir '/tmp/coverage' # where path_coverage.json is written
   measure :decisions, :methods # :decisions alone unless :methods is named
-  report :gaps, :html          # the reporters run at exit (default :gaps)
+  report :gaps, :html          # the reporters run at exit (default :gaps);
+                               # also :summary and :post
+  group 'code', 'source/**/*.rb' # each group a tab of its own on index.html
+  group 'test', 'test/**/*.rb'
+  ignore '&&='                 # operators whose sites are not measured
+  treat 'name', as: :present   # a call to name is never nil
+  treat 'any?', as: :nonempty  # any? is true when its receiver has items
 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.
+
+## Reading the HTML
+
+Clicking a line number on a file's HTML page opens that line's popout.
+
+Each popout has two sections:
+- on the left is a hierarchical representation of the code fragment.
+- on the right is one column for each possible path through that fragment.
+  - at the top of the column is the count of that path. Look for zeros!
+  - the symbols in the column align with their fragment and are explained below.
+
+### Boolean: `T` `F` 
+
+![A file's page: line 2, name.size > 2 && name.ascii_only?, its button pressed, its popout open beside it](docs/example-outcome.png)
+
+- `T` the expression was true.
+- `F` the expression was false.
+
+In this example, there was no test which exercised the path where `name.size > 2` was `true`, and 
+`name.ascii_only?` was `false`.
+
+### Unreachable: blank 
+
+![A file's page: line 2, @x = dee || dum, its button pressed, its popout open beside it](docs/example-unreachable.png)
+
+- "blank" the expression is never evaluated. 
+
+In the second column `dee` was `T`, so because of `||`'s short-circuiting, `dum` is never evaluated.
+
+### Taken: `✓`
+
+![A file's page: line 2, if paid, its button pressed, its popout open beside it](docs/example-taken.png)
+
+- `✓` marks the column whose path took that "arm"
+
+The `paid` row is the `if`'s predicate, `T` or `F`. Below it is one row
+per arm, named `then` and `else`.  The first column, `paid` false, took `else`; the
+second, `paid` true, took `then`.
+
+### Navigation: `∅` `●`
+
+![A file's page: line 2, user&.account&.owner, its button pressed, its popout open beside it](docs/example-nil.png)
+
+- `∅` the receiver was nil, so `&.` skipped the rest of the chain.
+- `●` the receiver was not nil, so `&.` made the call.
+
+In this example, there was no test which exercised the path where
+`user` was nil.
+
+### Count: `0` `1` `*`
+
+![A file's page: line 2, ids.any? { |id| id.odd? }, its button pressed, its popout open beside it](docs/example-count.png)
+
+- `0` the block was called with no items.
+- `1` the block was called with one item.
+- `*` the block was called with two or more items.
+
+In this example, there was no test which exercised the path where
+the block was called with two or more items and every answer was
+`false`.
+
+### Both: `TF`
+
+![A file's page: line 2, ids.select { |id| id.odd? }, its button pressed, its popout open beside it](docs/example-both.png)
+
+- `T` every answer of the block was true.
+- `F` every answer of the block was false.
+- `TF` the block's answers were both true and false.
+
+In this example, there was no test which exercised the path where
+the block was called with two or more items and every answer was
+`false`.
+
+### Lots of paths!
+
+Ruby code can be very compact so short expressions can generate lots of paths!
+
+![A file's page: line 2, if user&.admin? && ids.select { |id| id.odd? }.any?, its button pressed, its popout open beside it](docs/example-overview.png)
+
+
+## Use when you cannot edit the code!
 
 A run whose code cannot be changed, such as a script in a `docker build`
 step, can be covered from its environment alone:
@@ -86,6 +134,7 @@ step, can be covered from its environment alone:
 RUBYOPT=-rpath_coverage/auto
 PATH_COVERAGE_ROOT=/app                   # root
 PATH_COVERAGE_COVER=src/**/*.rb,lib/*.rb  # cover, comma-separated
+PATH_COVERAGE_SKIP=src/vendor/**/*.rb     # skip, comma-separated, optional
 PATH_COVERAGE_DIR=/tmp/paths              # coverage_dir
 PATH_COVERAGE_COLLECTOR=http://host.docker.internal:4570/runs
 ```
@@ -122,13 +171,23 @@ 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
+  `sites`, each site's paths under `paths`, each method's paths taken
+  under `method_paths` when `:methods` is measured, and the paths taken
+  of all possible under `totals`, as [taken, possible]: `decisions`,
+  `methods` when `:methods` is measured, and, with groups, each group's
+  own under `groups`, eg `"groups": {"code": {"decisions": [481, 567]}}`.
+  It also names the kinds of site measured under `kinds`, any `ignored`
+  operators and `treats`, and any paths taken that a treatment rules
+  out under `outside`.
+  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.
+  every run left. A report whose kinds, `ignored` or `treats` differ
+  from `config`'s is refused, as its sites list their paths
+  differently.
 - `: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:
@@ -141,7 +200,8 @@ source/fee.rb:2:2 fee path never taken: line 4 true, line 7 false
 
 ### Decisions
 
-Measured always, as `:decisions`: the paths within each decision.
+The paths within each decision are always measured, whatever `measure`
+names.
 
 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
@@ -168,17 +228,8 @@ should read the JSON, whose `paths` give each site's leaves as
 ```
 
 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.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
-```
+across the whole of it, nested conditions included. A condition inside a
+block is a site of its own.
 
 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
@@ -201,16 +252,31 @@ 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 call to `any?` `all?` `none?` `find` `detect` `find_index`
+`take_while` `select` `filter` `reject` `partition` `count` or
+`filter_map`, with no arguments and a block of one expression, is a site
+named at its method. Its item count is noted from the block's own calls,
+so the receiver is never asked its size, which could consume a sequence
+that can be read only once.
+
+A `||=` or `&&=` write is a site, whatever its target: a variable of any
+kind, a constant, an attribute (`self.size ||= n`) or an index
+(`store[key] ||= key.upcase`). Its one leaf is its target, and its right
+side is an arm, run when the target is false for `||=`, true for `&&=`,
+as an `unless` or an `if` runs its arm. The target is never read again,
+since reading `store[key]` could call a method twice: its outcome follows
+from whether the right side ran. So `@clock ||= Clock.now` called only
+once, as a fresh object, leaves the path with `@clock` true a gap.
+
+A `&.` chain is a site, named where it starts. Its leaves are the
+receivers of its `&.` calls. `false` counts as not nil, as `&.` calls on
+it.
+
+A chain inside a condition, eg `ok?(id) && user&.admin?` or
+`if user&.admin?`, folds into its site, as one expression: its value is
+one more leaf, true or false, reached when every receiver is not nil. A
+write through `&.`, eg `box&.size ||= 3`, is no site, as a nil `box`
+skips it whole and its target is never looked at.
 
 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
@@ -228,6 +294,18 @@ constants, since one can hold nil or false (`VERBOSE = false`). `nil` and
 @clock = options[:clock] || MonotonicClock.new  # leaf 1: never evaluated, or no gap
 ```
 
+Any other leaf, a call among them, is taken to have either outcome, as its
+form alone cannot say which it returns. So a call that never returns nil
+or false still leaves a path needing it falsy, which no test can take:
+
+```ruby
+methods: paths && methods_of(path, methods, paths)  # [true, false] impossible
+methods: paths ? methods_of(path, methods, paths) : nil  # the same, no such path
+```
+
+Written as a choice, the same code has no such path. Reporting a gap that
+cannot be closed is the lesser error than hiding one that can.
+
 ### Methods
 
 With `measure :decisions, :methods`, each method with two or more
@@ -239,11 +317,24 @@ 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.
 
+The JSON report's `method_paths` lists each method's paths taken, with
+their counts, so a later render, or several runs' reports merged, still
+shows them. A report with none, eg from a run that did not measure
+`:methods`, renders as no method path taken:
+
+```json
+"method_paths": {
+  "source/fee.rb:2:2": [
+    { "path": [true, false], "count": 1 }
+  ]
+}
+```
+
 ### Reporters
 
 - `:html` writes `index.html` to `coverage_dir`: the covered files with
   their sites and their paths taken of all possible, within each decision
-  and, when `:methods` is measured, across a method's decisions (eg
+  and, when `:methods` is measured, within each method (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
@@ -268,6 +359,25 @@ leaves the method ends the path there.
   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.
+- `:summary` prints each total as SimpleCov prints its line and branch
+  coverage, the methods line only when `:methods` is measured:
+
+```text
+Path coverage within decisions: 527 / 631 (83.52%)
+Path coverage within methods: 44 / 52 (84.62%)
+```
+
+  With groups, each group is a heading, its own totals indented under it,
+  and there is no total over every group.
+
+```text
+code:
+  Path coverage within decisions: 481 / 567 (84.83%)
+  Path coverage within methods: 41 / 49 (83.67%)
+test:
+  Path coverage within decisions: 65 / 84 (77.38%)
+  Path coverage within methods: 3 / 3 (100.00%)
+```
 
 ## How it works
 
@@ -310,19 +420,65 @@ 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.
 
+## Ignoring and treating
+
+`ignore '&&=', '||='` stops `&&=` and `||=` writes being measured.
+A site inside such a write is still measured, eg the `a && b` in
+`@m ||= a && b`. Ignoring `&&` does not ignore `and`, nor does ignoring
+`||` ignore `or`. The summary and `index.html` list what is ignored.
+
+`treat` tells path_coverage what you know about a method, so paths that
+cannot happen are not listed as gaps. Add `in: 'source/models/**'` to
+limit a treatment to the files that glob matches.
+
+- `treat 'name', as: :present`: a call to `name` is never nil, so
+  `user.name&.size` has no path with `user.name` nil.
+- `treat 'any?', as: :nonempty`: `x.any?` is true exactly when `x` has
+  items. When `x` is a call to `select`, `reject`, `filter`,
+  `filter_map`, `partition` or `take_while`, the path that call took
+  often decides whether it kept any items. Paths where `any?` disagrees
+  with that are not listed, eg `ids.select { |i| i.odd? }.any?` true
+  with `ids` empty.
+
+A run where a treatment turns out to be wrong is reported:
+
+```text
+source/user.rb:4:9 path taken that a treatment rules out: `user.name` nil
+```
+
 ## Roadmap
 
 - decisions hidden inside calls, each with its own outcome classes:
   - `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 || default` in value context: nil vs not nil
   - `x rescue y` modifier: raised vs not raised
   - `case` with no subject, and `case`/`in` patterns
   - regex matches: nil vs MatchData
+- `treat 'methods_of', as: :truthy`, so each call to it counts as a
+  leaf that is only truthy, as `Foo.new` is, and a run where it returns
+  nil or false is reported. Later, treatments could come from the
+  project's RBS signatures (`sig/*.rbs`) too.
+- exceptions the code itself names: a `begin` or `def` with `rescue`
+  clauses as a site, like a `case`, whose paths are no raise and each
+  clause that rescued, eg `rescue IOError` never taken. Branch coverage
+  ignores `rescue`, and tests reach these paths with real input. A raise
+  that nothing names, from any call, stays out, as every leaf would gain
+  a third outcome that only fault injection could take.
+- an evaluation that raised part way through a site, eg
+  `ok?(id) && fetch(id)` where `fetch` raises, reported as a path that
+  raised rather than dropped as unfinished.
+- complexity maximums, reported and gated, since the possible paths
+  count how much there is to test, not only how much was tested. A
+  file's total measures its size, so each is a maximum over smaller
+  parts:
+  - paths in one decision, eg 6 for a `select` block
+  - paths through one method's decisions, eg 2 top-level ifs give 4
+  - paths within each decision, summed over every decision in one
+    method, nested ones included, eg decisions of 2, 3 and 15 paths
+    sum to 20. Every method has one, and it grows as the method gains
+    conditions, where the paths through a method multiply.
 
 ## Constraints
 
@@ -336,13 +492,48 @@ the run never loaded are read and parsed then.
 `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`: the tests, with path_coverage measuring its own `lib/` and
+  `test/`, then a check that SimpleCov's report has zero missed lines and
+  branches in both the code and the tests, and that every path within the
+  tests' methods was taken, within the bounds in
+  `test/coverage_metrics_params.json` (a path bound is eg
+  `test.paths.methods.missed`, and a missing path report denies it)
   (`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
 
+Each run prints its seed; `SEED=n make test` replays that run's order of
+files and tests. When the coverage check fails, it names each line and
+branch missed.
+
+A run ends with each group, code and test, as a heading over its four
+figures, SimpleCov's and path_coverage's together, then where each report
+is, each with a code and a test tab, then the check's verdict:
+
+```text
+code:
+  Line coverage: 1270 / 1270 (100.00%)
+  Branch coverage: 321 / 321 (100.00%)
+  Path coverage within decisions: 481 / 567 (84.83%)
+  Path coverage within methods: 41 / 49 (83.67%)
+test:
+  Line coverage: 2250 / 2250 (100.00%)
+  Branch coverage: 43 / 43 (100.00%)
+  Path coverage within decisions: 65 / 84 (77.38%)
+  Path coverage within methods: 3 / 3 (100.00%)
+Coverage report: .../reports/index.html
+Path coverage report: .../reports/paths/index.html
+coverage: ALLOWED
+```
+
+`bin/check_coverage_metrics.rb` prints the groups, reading SimpleCov's
+figures from `reports/coverage_metrics.json` and path_coverage's from the
+`totals` in `reports/paths/path_coverage.json`; SimpleCov's own console
+lines, totals over every group, are silenced. The tool measuring paths is
+a copy of `lib/` renamed `PathCoverageSelf` (`test/self_coverage.rb`), so
+the tests start and restart `PathCoverage` as always. SimpleCov's figures
+for `lib/` are the same with it as without.
+
 `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
@@ -351,3 +542,21 @@ 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.
+
+
+## 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)
+
+## Within each method
+
+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)

data/lib/path_coverage/calls.rb

@@ -26,30 +26,69 @@ module PathCoverage
     @recorder.when_match(site, index, size, pattern)
   end
 
+  # The call rewritten code makes around the pattern of a case
+  # nested in site, the site's index-th leaf; returns the
+  # pattern's stand-in.
+  def self.pattern(site, index, pattern)
+    @recorder.pattern(site, index, pattern)
+  end
+
+  # The call rewritten code makes around the right side of a
+  # write nested in site, its target the site's at-th leaf,
+  # outcome being the target's when it runs; returns value
+  # unchanged.
+  def self.written_at(site, at, outcome, value)
+    @recorder.written_at(site, at, outcome, value)
+  end
+
+  # The call rewritten code makes around a write nested in site,
+  # its target the site's at-th leaf, skipped being the target's
+  # outcome when its right side never ran; returns value
+  # unchanged.
+  def self.settle(site, at, skipped, value)
+    @recorder.settle(site, at, skipped, value)
+  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)
+  # nested in site runs, its receiver the site's at-th leaf;
+  # returns the site's trail.
+  def self.begin_items(site, at)
+    @recorder.begin_items(site, at)
   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)
+  # The call rewritten code makes around the block's expression
+  # of a stop-early block method nested in site, its receiver the
+  # site's at-th leaf; returns value unchanged.
+  def self.item_at(site, at, value)
+    @recorder.item_at(site, at, 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)
+  # of an every-item block method nested in site, its receiver
+  # the site's at-th leaf; returns value unchanged.
+  def self.answer_at(site, at, value)
+    @recorder.answer_at(site, at, 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)
+  # nested in site, its receiver the site's at-th leaf, with the
+  # trail begin_items gave it; returns value unchanged.
+  def self.end_items(site, at, trail, value)
+    @recorder.end_items(site, at, trail, value)
+  end
+
+  # The call rewritten code makes around a &. receiver, the
+  # index-th leaf of site, its chain's leaves starting at first;
+  # returns value unchanged.
+  def self.present(site, index, first, value)
+    @recorder.present(site, index, first, value)
+  end
+
+  # The call rewritten code makes around a &. chain's value, the
+  # index-th leaf of site, its chain's leaves starting at first;
+  # returns value unchanged.
+  def self.chained(site, index, first, value)
+    @recorder.chained(site, index, first, value)
   end
 
   # The call rewritten code makes as a call reaches its

data/lib/path_coverage/condition.rb

@@ -6,9 +6,28 @@ module PathCoverage
   # decided by their predicate alone.
   STATEMENT_CHOICES = %w[if unless].freeze
 
+  # The operator of a safe-navigation chain, eg user&.account.
+  SAFE = '&.'.freeze
+
+  # The operator of a leaf with sites inside it, eg
+  # ids.select { |i| i.odd? }.any? as an operand of an &&: its
+  # operands are those sites' Conditions, then the leaf's own byte
+  # range, whose outcome is the leaf's value.
+  CONTAINS = 'contains'.freeze
+
+  # A &. receiver's outcome: not nil, so the call is made, false
+  # included, or nil, so the rest of the chain is skipped.
+  PRESENCE = ['not nil', 'nil'].freeze
+
+  # The writes whose target decides whether their right side
+  # runs, as an unless or an if decides its arm: x ||= v runs v
+  # when x is false, x &&= v when x is true.
+  WRITES = %w[||= &&=].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
+  # arm: an unless's is false, as is a ||= write's.
+  THEN_ON = Hash.new(true).merge('unless' => false, '||=' => false)
+                .freeze
 
   # The methods that call their block an item at a time until
   # it decides, its last answer deciding the result.
@@ -47,6 +66,10 @@ module PathCoverage
     [ITEMS[2], ANSWERS[2]]
   ].freeze
 
+  # The block methods whose value follows from their path alone:
+  # all but find and detect, whose found item may itself be nil.
+  VALUED = [*STOP_EARLY - %w[find detect], *EVERY_ITEM].freeze
+
   # Every block method whose call is a site, by its paths.
   BLOCK_PATHS = [
     *STOP_EARLY.map { |name| [name, STOP_EARLY_PATHS] },