supercov 4.19.0 → 4.20.1

package/docs/assertions.md

@@ -199,12 +199,12 @@ Measured on four JavaScript and TypeScript projects (7,393 executed statements):
 
   | Project | Checked | Right | Flagged (truly not asserted) | Share reported / true |
   | --- | --- | --- | --- | --- |
-  | google/uuid (Go) | 339 | 298 | 34 (28) | 90.0% / 81.4% |
-  | hashicorp/go-version (Go) | 257 | 253 | 21 (19) | 91.8% / 91.8% |
+  | google/uuid (Go) | 291 of 326 | 254 | 16 (12) | 94.5% / 84.5% |
+  | hashicorp/go-version (Go) | 232 of 237 | 230 | 0 (0) | 100.0% / 99.1% |
   | dtolnay/semver (Rust) | 200 of a sample of 200 | 190 | 7 (2) | 96.5% / 96.5% |
   | apache/commons-cli (Java) | 196 of a sample of 200 | 167 | 49 (33) | 75.0% / 76.5% |
-  | dry-rb/dry-inflector (Ruby 3.4) | 157 | 148 | 13 (8) | 91.7% / 92.4% |
-  | sporkmonger/addressable (Ruby) | 198 of a sample of 200 | 182 | 25 (14) | 87.4% / 90.4% |
+  | dry-rb/dry-inflector (Ruby 3.3) | 157 of 157 | 151 | 12 (9) | 92.4% / 92.4% |
+  | sporkmonger/addressable (Ruby 3.3) | 199 of a sample of 200 | 183 | 17 (11) | 91.5% / 89.4% |
   | square/moshi (Kotlin) | 60 of a sample of 60 | 52 | 9 (6) | 85.0% / 81.7% |
 
 - **Held out:** five projects nothing was tuned on, each assessed once by the
@@ -217,14 +217,23 @@ Measured on four JavaScript and TypeScript projects (7,393 executed statements):
   | pallets/itsdangerous (Python) | 60 of 60 | 56 | 3 (2) | 95.0% / 91.7% |
   | — every statement | 238 of 238 | 224 | 13 (9) | 94.5% / 92.0% |
   | Masterminds/semver (Go) | 60 of 60 | 55 | 7 (7) | 88.3% / 80.0% |
-  | — every statement | 497 of 498 | 472 | 46 (44) | 90.7% / 86.5% |
+  | — every statement | 443 of 461 | 422 | 9 (9) | 98.0% / 93.2% |
   | hashie/hashie (Ruby 3.4) | 60 of 60 | 57 | 3 (1) | 95.0% / 96.7% |
-  | — every statement | 700 of 701 | 655 | 26 (10) | 96.3% / 94.4% |
+  | — every statement | 771 of 772 | 720 | 22 (7) | 97.1% / 94.4% |
   | FasterXML/java-classmate (Java) | 60 of 60 | 58 | 9 (7) | 85.0% / 88.3% |
   | bluss/arrayvec (Rust) | 54 of 60 | 48 | 1 (1) | 98.1% / 87.0% |
 
   Assessing all five (2,582 statements) cost $0.15, about 0.006 cents per
-  statement. Go reads high: Jev takes a dropped error (`return false,
+  statement.
+
+  The Go and Ruby rows of both tables, the held-out ones' every-statement rows
+  among them, were measured again on 19 October 2026 by the current release,
+  at each project's latest commit and on Ruby 3.3; the projects have changed
+  since, so the counts differ from the first study's. The 60-statement samples
+  and the Rust, Java, Kotlin and Python rows are from that first study.
+  `node scripts/assertions-truth.mjs <project> -- <test command>` makes each
+  change, runs the tests and prints a row (Go and Ruby; a statement no
+  version of which builds is left out, so not every statement is checked). Go reads high: Jev takes a dropped error (`return false,
   fmt.Errorf(..)` becoming `return false, nil`) as caught where the tests check
   only the boolean. Rust reads high too on arrayvec, whose code is generic over
   its element type; six of its sampled changes cannot be made, because no value

package/docs/cli.md

@@ -541,8 +541,8 @@ Neither input run is changed. Under the totals it lists what was lost, marked
 `-`, and then what was gained, marked `+`:
 
 ```
-gained: 1 lines, 1 branches, 0 MC/DC conditions
-lost: 1 lines, 1 branches, 0 MC/DC conditions
+gained: 1 line, 1 branch, 0 MC/DC conditions
+lost: 1 line, 1 branch, 0 MC/DC conditions
 - line src/fee.js:5
 - branch src/fee.js:2 false
 + line src/fee.js:3
@@ -555,8 +555,8 @@ as one row and not as forty:
 
 ```
 in 2 files, most lost first:
-  src/panel.js: lost 6 lines, 1 branches
-  src/fee.js: lost 1 lines, 1 branches; gained 1 lines, 1 branches
+  src/panel.js: lost 6 lines, 1 branch
+  src/fee.js: lost 1 line, 1 branch; gained 1 line, 1 branch
 ```
 
 The counts are of the whole difference, whatever page of it is shown. In
@@ -625,7 +625,9 @@ npx supercov runs latest minimize --metric branches --target 90
 ```
 
 `minimize` finds a small set of tests that preserves the selected coverage
-target. It does not edit, delete, or skip tests for you. Treat the result as an
+target. Without `--target` it keeps everything the tests together cover, so
+it works on a run that is not fully covered; `--target 90` asks for 90% of
+each selected metric instead. It does not edit, delete, or skip tests for you. Treat the result as an
 analysis aid, not permission to remove tests that protect behavior outside the
 selected metric.
 
@@ -921,6 +923,7 @@ terminal or offline environment after the package has been downloaded.
 | `SUPERCOV_SOURCE_ROOTS` | Comma-separated directories or files that hold your own code, in any language; everything else is left out |
 | `SUPERCOV_TEST_KIND` | Label the wrapped command as a test level such as `unit` or `e2e` |
 | `SUPERCOV_SOURCE_TOOLS` | Comma-separated names of tools the test command runs that read source as text, such as a linter or a spell checker, besides Biome, oxlint, dprint, cspell and knip. Each is run on your source as you wrote it instead of on the instrumented copy |
+| `SUPERCOV_RUN_ID` | Set by Supercov, not by you: in every process a measured command starts, the run's id, so a test or harness can tell it is measured |
 | `SUPERCOV_RUN_ID_FILE` | A file to write the recorded run's id to, for a script to query that run rather than `latest` |
 | `SUPERCOV_KEEP_WORKSPACE` | Set to `1` to leave the instrumented copy of the project in `.supercov/workspaces/` after the run, to inspect what the command ran |
 
@@ -937,6 +940,7 @@ SUPERCOV_TEST_KIND=e2e npx supercov -- npx playwright test
 | --- | --- |
 | `0` | The command or query succeeded |
 | Wrapped command's code | The test command failed and Supercov preserved its status |
+| `127`, `126` | The test command could not start: no such program, or one that may not be run, as a shell reports it |
 | `1` | A valid measurement failed a policy you set, such as a coverage floor |
 | `2` | Supercov could not complete the request, or the evidence cannot answer it |
 

package/docs/coverage-model.md

@@ -189,6 +189,14 @@ Files  Status     Directory   Reason
   311  EXCLUDED   tests       test or fixture source
 ```
 
+A file under no source root that first-party source imports is source:
+Supercov follows the imports of the source it found, through what those load
+in turn, before anything runs, and counts what they reach with the reason
+`loaded by first-party source`. A file only tests import stays ambiguous,
+since tests load their own helpers, mocks and simulators. What stays
+ambiguous counts in no percentage, and `runs check` names it under its result
+without failing, since the suite passes without Supercov.
+
 When first-party source lives in unusual directories, declare it explicitly:
 
 ```sh supercov

package/docs/supported-suites.md

@@ -234,7 +234,11 @@ is your entry, and gives `[dev]` an inspector port unless you set one; your
 own configuration and command are not changed. While the suite runs,
 Supercov reads what the Worker ran through that inspector every 5 ms, and
 each read is credited to the browser test that was running then, if only one
-was, as for a [Go server](#a-go-server-under-browser-tests). The Worker's
+was, as for a [Go server](#a-go-server-under-browser-tests). Several Workers
+in one `wrangler dev` (`-c a/wrangler.toml -c b/wrangler.toml`) are each
+measured: wrangler's inspector shows one of them, so Supercov reads each
+through workerd's own inspector, whose address a small preload in wrangler's
+Node process reports. The Worker's
 coverage is a Rust run of its own, published as the run or beside the browser
 run. Requests made before the first test, such as the readiness check
 `webServer` waits on, are the run's and no test's.
@@ -242,10 +246,11 @@ run. Requests made before the first test, such as the readiness check
 The build runs with `--cap-lints=warn`, so a crate that denies warnings still
 builds with the probes in it.
 
-### A Rust Worker that `cargo test` starts
+### A Cloudflare Worker in Rust that `cargo test` starts
 
-Integration tests that start `wrangler dev` themselves -- to test a Worker in
-Cloudflare's own runtime -- measure the Worker too:
+Integration tests that start `wrangler dev` themselves -- to test a Cloudflare
+Worker written in Rust in workerd, Cloudflare's own runtime -- measure the
+Worker too, Durable Objects included:
 
 ```sh
 npx supercov -- cargo test
@@ -257,13 +262,20 @@ dev` builds it in the copy as usual. The tests find a `wrangler` of
 Supercov's first on `PATH`: for `wrangler dev` it picks an inspector port,
 starts a reader of the Worker through it, and then runs your `wrangler` with
 the test's own arguments, process and signals. What the Worker ran is
-credited to the test that started it, exactly, as its own coverage. The
-Worker crate counts though `cargo test` never compiles it, once a test has
-run it. This needs a `wrangler` on `PATH` when the run starts; without one,
-nothing is put in front of it. A run whose tests start no Worker still compiles the crate under
-`cargo test --workspace`; its files then say they are a Rust Worker no test
-started, in `gaps` and the file view, rather than reading as code the tests
-missed.
+credited to the test that started it, exactly, as its own coverage. This
+needs a `wrangler` on `PATH` when the run starts; without one, nothing is
+put in front of it.
+
+A Worker crate's code is what worker-build compiles: for wasm, as a release
+unless its `[build]` command passes `--dev`, never as a test, with the
+features the command and the crate's defaults enable. Code a
+`#[cfg(target_arch = "wasm32")]`, a feature or `debug_assertions` keeps out
+of that build is not counted, and wasm-only code is, whatever target
+`cargo test` builds the rest for. The crate counts whether or not
+`cargo test` compiles it (`cargo test -p host` does not) and whether or not
+a test started its Worker, so every run of the workspace has one
+denominator. Where no test of a run started a Worker, its files say so, in
+`gaps` and the file view, rather than reading as code the tests missed.
 
 `wrangler dev --remote` runs the Worker on Cloudflare's edge, and wrangler
 opens no inspector into it there, so nothing can read what it ran. A test
@@ -271,10 +283,64 @@ that starts it that way runs as usual; the Worker's files then say they ran
 remotely and could not be read. Start the Worker with `wrangler dev` to
 measure it.
 
+Code in a Durable Object (`#[durable_object]` and its `impl DurableObject`)
+is measured like the rest of the Worker and credited to the test whose
+requests reached it. So is a Worker that runs beside another in one
+`wrangler dev` (`-c plane/wrangler.toml -c runners/wrangler.toml`), reached
+only through the first's service bindings: wrangler's inspector shows one
+Worker of a session, and Supercov reads each through workerd's own, whose
+address a small preload in wrangler's Node process reports. A test that
+sets its own `NODE_OPTIONS` keeps them; the preload is added after. A workspace with several Worker crates counts each crate
+once, and runs of different tests -- each starting different Workers, or
+none -- merge with `supercov merge`. Tests that run a Worker only when its `build/` exists, as a test
+kit that will not start an unbuilt Worker does, run it: a `build/` you made
+beforehand and keep out of git is in the copy, and `wrangler dev` builds the
+crate with probes over it there.
+
+What a project needs:
+
+- `wrangler` on `PATH` in the job that runs Supercov, before the run starts,
+  such as `node_modules/.bin` of a project that installs it.
+- The `wasm32-unknown-unknown` target and `worker-build`, which the Worker's
+  `[build]` command runs.
+- The Worker crates inside the source Supercov measures, as workspace members
+  or under the project root.
+
+The project needs no `cfg` flag or build step of its own for Supercov.
+
+#### What a test harness can rely on
+
+- **Any configuration, anywhere.** A test may write its own wrangler
+  configuration, per test, outside the crate, with a `main` of its own: a
+  module that loads the built Worker and adds stand-ins or test controls.
+  Supercov leaves every configuration as it was written. When a test runs
+  `wrangler dev`, Supercov's `wrangler` hands it a copy of the configuration
+  it was given (`-c`, or the one wrangler finds from its directory), beside
+  the original as `.supercov-wrangler-<pid>-<n>.toml` (or `.json`), whose
+  `main` is a small entry that remembers the Worker's wasm instances and then
+  loads your `main`. The copy is removed once that `wrangler` exits. A Worker
+  is read when wasm built from the crate's measured source runs in it,
+  whatever the configuration's `main` imports.
+- **The measured build.** The configuration's `[build]` builds the crate
+  with worker-build (any `cwd`), or its `main` imports a build made in the
+  run's copy. A `build/` made before the run, without probes, has nothing to
+  read.
+- **Why a Worker was not measured.** Where tests started `wrangler dev` and
+  no measured build ran in it, the Worker's files name each `wrangler dev -c
+  <path>` the tests started, and why a configuration was left as it was (no
+  `main`, say), in `gaps` and the file view.
+- **`--inspector-port`.** A test may pass its own: Supercov reads the Worker
+  through that port.
+- **Knowing the run is measured.** `SUPERCOV_RUN_ID` is set in every process
+  a measured command starts, holding the run's id. The other `SUPERCOV_`
+  variables a test may see are Supercov's own wiring and change without
+  notice.
+- **Output.** `cargo test -- --nocapture` shows each test's output as it is
+  written, as plain `cargo test` does.
+
 The Worker built with probes stays in the copy: its `build/` output is never
-returned to the project, and neither is the copy's configuration, which
-points `main` at Supercov's entry. wrangler's `.wrangler/` state is not a
-build input, so writing it does not make the run stale.
+returned to the project, nor are wrangler's `.wrangler/` state and the
+configuration copies above. Writing them does not make the run stale.
 
 ### Rust tests compiled to wasm
 
@@ -424,8 +490,13 @@ Ruby 3.3 and newer support statement, method, branch and MC/DC measurement,
 including loops, iterator blocks, short-circuit operators, pattern matching,
 optional calls and exception paths.
 
-Some constructs have narrower coverage. Code in a non-main Ractor keeps line
-coverage but may lack other observations. Certain nested-return expressions
+Some constructs have narrower coverage. Code written inside a `Ractor.new`
+block keeps line coverage but may lack other observations. Code a non-main
+Ractor calls elsewhere runs as it would without Supercov, but what it runs
+there is not recorded: the run says so, and a line only a Ractor reached reads
+as not executed. A project whose code or tests mention `Ractor` gets probes a
+Ractor can call, which cost more than the usual ones (about a fifth more in a
+tight loop). Certain nested-return expressions
 limit normal-completion measurement. Constant predicates are folded as Ruby
 folds them, so unreachable alternatives do not become obligations.
 
@@ -508,8 +579,10 @@ beyond one deferred line per test that binds it to its evidence.
 
 `go test` builds one binary per package, so each test package records its own
 evidence and Supercov merges them. It also caches packages that passed, and a
-cached package does not run — so Supercov adds `-count=1` unless your command
-already says otherwise, and tells you it did.
+cached package does not run — so Supercov adds `-count=1` to `GOFLAGS` unless
+your command or `GOFLAGS` already says otherwise, and tells you it did. Through
+`GOFLAGS` it reaches `go test` however your command starts it, `make test`
+included.
 
 A test that calls `t.Parallel()` runs alongside others. Probes are a store into
 one array shared by the process, so nothing can say which of two concurrent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "4.19.0",
+  "version": "4.20.1",
   "description": "Coverage, security and code quality for coding agents",
   "keywords": [
     "coverage",
@@ -95,7 +95,10 @@
     "test:test262": "cargo build --release -p supercov && node scripts/test262-equivalence.mjs",
     "benchmark:check": "cargo build --release -p supercov && node scripts/rust-transform-benchmark.mjs",
     "benchmark:python": "cargo build -p supercov && node scripts/python-benchmark.mjs",
-    "check": "cargo fmt --all -- --check && cargo clippy --workspace --all-targets -- -D warnings && npm run test && npm run test:release-tooling && npm run test:runtime && npm run test:action && npm run test:rust-assets && npm run test:agent-commands && npm run test:assertions && npm run test:sweep-target && npm run test:skip-guard && npm run test:windows-tls && node scripts/package-preflight.mjs && node scripts/verify-binstall-metadata.mjs --offline",
+    "check": "npm run check:lint && npm run check:tests",
+    "check:lint": "cargo fmt --all -- --check && cargo clippy --workspace --all-targets -- -D warnings",
+    "check:tests": "npm run test && npm run check:tooling",
+    "check:tooling": "npm run test:release-tooling && npm run test:runtime && npm run test:action && npm run test:rust-assets && npm run test:agent-commands && npm run test:assertions && npm run test:sweep-target && npm run test:skip-guard && npm run test:windows-tls && node scripts/package-preflight.mjs && node scripts/verify-binstall-metadata.mjs --offline",
     "release:check": "cargo clean && node scripts/sweep-target.mjs && npm run check && npm run test:engine && npm run test:go && npm run test:jvm && npm run test:launcher && npm run test:fixture && npm run test:watchdog && npm run test:engine-contract && npm run test:agent && npm run test:child-attribution && npm run test:host-loader && npm run test:python && npm run test:ruby-coverage && npm run test:rust-public-cargo && npm run test:packed-npx && npm run test:clang-mcdc && npm run benchmark:check",
     "release:bump": "node scripts/bump-version.mjs",
     "sweep": "node scripts/sweep-target.mjs",
@@ -119,14 +122,14 @@
     "test:windows-tls": "node scripts/windows-tls-test.mjs"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "4.19.0",
-    "@supercov/cli-darwin-x64": "4.19.0",
-    "@supercov/cli-linux-arm64-gnu": "4.19.0",
-    "@supercov/cli-linux-arm64-musl": "4.19.0",
-    "@supercov/cli-linux-x64-gnu": "4.19.0",
-    "@supercov/cli-linux-x64-musl": "4.19.0",
-    "@supercov/cli-win32-arm64": "4.19.0",
-    "@supercov/cli-win32-x64": "4.19.0"
+    "@supercov/cli-darwin-arm64": "4.20.1",
+    "@supercov/cli-darwin-x64": "4.20.1",
+    "@supercov/cli-linux-arm64-gnu": "4.20.1",
+    "@supercov/cli-linux-arm64-musl": "4.20.1",
+    "@supercov/cli-linux-x64-gnu": "4.20.1",
+    "@supercov/cli-linux-x64-musl": "4.20.1",
+    "@supercov/cli-win32-arm64": "4.20.1",
+    "@supercov/cli-win32-x64": "4.20.1"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/runtime/javascript/runtime.mjs

@@ -979,22 +979,21 @@ function appendServer(record) {
   var _a8, _b, _c, _d;
   if (state.runtimeSnapshots) {
     const timestampMs = (_a8 = record.timestampMs) != null ? _a8 : Date.now();
-    const statement = record.statementId ? { statementId: record.statementId } : {};
     if (record.type === "decision") {
-      recordBrowserEvent(__spreadProps(__spreadValues(__spreadValues({
+      recordBrowserEvent(__spreadProps(__spreadValues({
         type: "decision",
         id: record.meta.id,
         vector: record.vector,
         timestampMs
-      }, record.phaseId ? { phaseId: record.phaseId } : {}), statement), {
+      }, record.phaseId ? { phaseId: record.phaseId } : {}), {
         environment: "server"
       }));
     } else {
-      recordBrowserEvent(__spreadProps(__spreadValues(__spreadValues({
+      recordBrowserEvent(__spreadProps(__spreadValues({
         type: "hit",
         id: record.id,
         timestampMs
-      }, record.phaseId ? { phaseId: record.phaseId } : {}), statement), {
+      }, record.phaseId ? { phaseId: record.phaseId } : {}), {
         environment: "server"
       }));
     }