supercov 2.0.0 → 3.0.0

package/docs/cli.md

@@ -17,8 +17,11 @@ npx supercov --help
 | Read the newest run | `npx supercov runs latest` |
 | Find useful gaps | `npx supercov runs latest gaps` |
 | Inspect one file | `npx supercov runs latest file <path>` |
-| List assertions and their status | `npx supercov runs latest assertions` |
-| Inspect one assertion and its flows | `npx supercov runs latest assertion <id>` |
+| See how much executed code the tests assert | `npx supercov runs latest assertions` |
+| Assess it with Jev | `npx supercov runs latest assertions assess` |
+| Find what is not asserted in one file | `npx supercov runs latest assertions <path>` |
+| See each test's answer for one statement | `npx supercov runs latest assertions <path>:<line>` |
+| See what one test is judged to catch | `npx supercov runs latest assertions --test <name>` |
 | Read matching current source code | `npx supercov runs latest source <path>` |
 | Compare two runs | `npx supercov diff <older> <newer>` |
 | Open an interactive report | `npx supercov report` |
@@ -36,17 +39,17 @@ npx supercov --help
 ## Assess source quality
 
 ```sh supercov-example
-supercov quality                 # this repository
-supercov quality src/            # one directory
-supercov quality gaps            # only files something fired on
-supercov quality file src/a.ts   # one file, every check
-supercov quality scope           # which files are assessed, and why
-supercov quality snapshots       # saved assessments
-supercov quality diff <older> <newer>
-supercov security                # twelve security checks, every file
-supercov security gaps           # only files something fired on
-supercov security patch --base origin/main
-supercov security --run latest   # flagged files no test exercises
+npx supercov quality                 # this repository
+npx supercov quality src/            # one directory
+npx supercov quality gaps            # only files something fired on
+npx supercov quality file src/a.ts   # one file, every check
+npx supercov quality scope           # which files are assessed, and why
+npx supercov quality snapshots       # saved assessments
+npx supercov quality diff <older> <newer>
+npx supercov security                # twelve security checks, every file
+npx supercov security gaps           # only files something fired on
+npx supercov security patch --base origin/main
+npx supercov security --run latest   # flagged files no test exercises
 ```
 
 With no argument the subject is the repository you are standing in. Every
@@ -74,9 +77,9 @@ number is worth and which files get assessed.
 ## Review what a change introduced
 
 ```sh supercov-example
-supercov quality patch
-supercov quality patch --base origin/main
-supercov quality patch --base origin/main --annotate github --run latest
+npx supercov quality patch
+npx supercov quality patch --base origin/main
+npx supercov quality patch --base origin/main --annotate github --run latest
 ```
 
 The same twelve properties asked of a change, plus six risk checks that only
@@ -146,8 +149,7 @@ npx supercov runs <run-id> [query] [options]
 | `kinds` | Group coverage by test level, such as unit or E2E |
 | `runners` | Group coverage by test runner |
 | `scope` | Review included, excluded, and ambiguous source files |
-| `assertions` | List assertions, including sites without flows, with freshness and execution status |
-| `assertion <id>` | Inspect one assertion and its authored flows |
+| `assertions` | Read the share of executed statements the tests assert, and the ones they do not; `assertions assess` works it out |
 | `source <path>` | Read matching current project source with line numbers |
 | `minimize` | Find a small test subset that preserves a coverage target |
 
@@ -169,46 +171,34 @@ npx supercov runs latest file --help
 npx supercov runs latest assertions --help
 ```
 
-Assertion queries read the run-owned map. `source <path>` reads the matching current
-file directly. It prints source code with line numbers, preserving indentation;
-add `--json` only when you want structured `{line, text}` items. `--offset` is
-zero-based and `--limit` controls the number of source lines. Source and assertion
-investigation require current files that match the run. Rerun the suite after
-source changes to inherit the map into a new run.
+`source <path>` reads the matching current file directly. It prints source code
+with line numbers, preserving indentation; add `--json` only when you want
+structured `{line, text}` items. `--offset` is zero-based and `--limit` controls
+the number of source lines. The file must still match the run; rerun the suite
+after source changes.
 
 ### Assertion coverage
 
-The regular run summary includes assertion coverage when a map has been
-assessed. JSON reports expose it under `data.assertionCoverage`. Start with
-[Understanding assertion coverage](assertions.md), or use these commands to
-inspect and check a map:
-
 ```sh supercov-example
-npx supercov runs <run-id> assertions --needs-attention
-npx supercov runs <run-id> assertion <assertion-id>
-npx supercov runs <run-id> assertions report --view statements --file src/shipping.js
-npx supercov runs <run-id> assertions report --view excludedStatements
-npx supercov runs <run-id> assertions validate --json
-npx supercov runs <run-id> assertions check --require-mappings
+npx supercov runs <run-id> assertions assess --dry-run
+npx supercov runs <run-id> assertions assess
+npx supercov runs <run-id> assertions
+npx supercov runs <run-id> assertions --all --json
 ```
 
-Edit the file shown by `assertions`. Validation returns `expectedBasis` tokens;
-after examining a flow, save its token in the map before running `check`.
-`--require-mappings` requires explanations for recognized assertions observed
-passing. Add `--require-observed` when every mapped site and selector should have
-passing evidence, or `--min <percentage>` for a chosen target.
-
-To inspect one large flow, add `--flow <flow-id> --view nodes` or `--view edges`
-to the assertion detail command. `--compact` omits repeated source text from the
-report. Follow the printed next-page command or JSON `pagination.nextOffset`.
-Validation supports `--view flows`, `--view changes` and `--view errors` for large
-maps. The [map reference](assertion-maps.md) describes all fields and gates.
+`assertions assess` asks Jev, test by test, whether each statement the test ran
+would make it fail if changed, and saves the result to the run; it needs
+`TYPESAFE_API_KEY` for questions not answered before. `assertions` reads the
+saved result without the network. The regular run summary shows the same share,
+and JSON reports expose it under `data.assertionCoverage`. See
+[Assertion coverage](assertions.md) for what counts as asserted and how answers
+are reused across runs.
 
 ## Fail CI below a coverage floor
 
 ```sh supercov-example
-supercov runs check --min-lines 90 --min-branches 80 --min-mcdc 80
-supercov runs check --min-lines 100 --per-file --json
+npx supercov runs check --min-lines 90 --min-branches 80 --min-mcdc 80
+npx supercov runs check --min-lines 100 --per-file --json
 ```
 
 `check` reads a recorded run; it never runs tests again. Give a floor per metric
@@ -231,16 +221,11 @@ rather than a pass or a failure:
 - a requested metric left obligations unmeasured, so no exact judgement exists
 - a requested metric is not recorded by the language adapter
 
-Assertion coverage keeps its own check. Whether a test *examines* what it
-executes is a different question from whether a line ran, and
-`runs <id> assertions check` carries the freshness and acknowledgement rules
-that answer needs.
-
 ## Check the lines a change touches
 
 ```sh supercov-example
-supercov runs patch --base origin/main --min-lines 100
-supercov runs patch --base origin/main --annotate github
+npx supercov runs patch --base origin/main --min-lines 100
+npx supercov runs patch --base origin/main --annotate github
 ```
 
 `patch` answers whether the lines this change added or modified are tested. It
@@ -267,9 +252,9 @@ needs no token and posts no comment.
 ## Export for other tools
 
 ```sh supercov-example
-supercov runs report --format lcov --output coverage/lcov.info
-supercov runs report --format cobertura --output coverage/cobertura.xml
-supercov runs report --format html --output coverage/report
+npx supercov runs report --format lcov --output coverage/lcov.info
+npx supercov runs report --format cobertura --output coverage/cobertura.xml
+npx supercov runs report --format html --output coverage/report
 ```
 
 Both are written from the same view `check` and `patch` read, so a viewer,
@@ -401,11 +386,72 @@ neither do comments, blank lines or trailing whitespace. A test that did not
 pass in the run is listed regardless.
 
 `--names` prints one affected test name per line and `--files` one test file
-per line, for a runner's filter. A dependency, lockfile, configuration or
+per line, for a runner's filter. A Vitest, Playwright or node:test test inside
+`describe` blocks is printed as the blocks and the test joined by spaces
+(`small charges`), which is what `vitest -t`, `--grep` and
+`--test-name-pattern` match. A dependency, lockfile, configuration or
 toolchain change affects every test and is reported as such. A source file
 added since the run is outside every test's record; the working-tree check
 says so, and the suite should run in full.
 
+### Which affected tests check the change
+
+When the run has an [assertion assessment](assertions.md), `tests affected`
+also says, for each affected test, whether it was judged to catch a change to
+the statements that changed in code it ran, and lists those tests first. A run
+without an assessment answers from coverage alone, as above.
+
+```sh supercov
+npx supercov runs latest assertions assess              # once, on the run
+# ... edit code ...
+npx supercov runs latest assertions assess --changed    # ask every test that ran the changed code
+npx supercov runs latest tests affected --names --ran-changed
+```
+
+The assessment stops asking about a statement once one test catches it, so on
+its own it knows only some tests' answers. `assess --changed` asks, for the
+statements in code changed since the run, every test that ran them: typically
+a few requests per commit. After it, `--ran-changed` leaves out the affected
+tests that ran the changed declaration but none of the changed statements, and
+`--asserting` also those judged to catch no change to them. Tests whose own
+file changed or that did not pass stay, and so does any test never asked. With
+an assessment or without, `--names` and `--files` list first the tests whose
+own file or name shares words with a changed file (`test_receivebuffer.py` for
+`_receivebuffer.py`), the verdicts breaking ties.
+
+Measured by applying random changes and running the suite:
+
+| Project | Breaking changes (failing tests) | Coverage's set | `--ran-changed` | `--asserting` | A failing test in the first three |
+| --- | --- | --- | --- | --- | --- |
+| h11 (Python, 78 tests) | 23 (153) | all 153 in 28 tests | all 153 in 23.5 | 141 in 19.9 | 18 of 23 |
+| go-version (Go, 31 tests) | 36 (140) | all 140 in 10.1 | all 140 in 9.8 | 133 in 9.4 | 32 of 36 |
+
+`--ran-changed` never dropped a failing test; `--asserting` dropped 5 to 8% of
+them. `assess --changed` cost about a tenth of a cent per change.
+
+Measured on real history: at each of a project's recent commits, the source
+the commit replaced was put back -- someone reintroducing what it fixed -- and
+the commit's own tests run against it:
+
+| Project | Commits (breaking) | Failing tests | Kept by coverage's set | Kept by `--asserting` | Tests selected (coverage / `--asserting`) of all |
+| --- | --- | --- | --- | --- | --- |
+| h11 (Python) | 60 (13) | 27 | 27 | 27 | 25.2 / 24.9 of 75 |
+| go-version (Go) | 24 (2) | 3 | 3 | 3 | 15.2 / 14.1 of 25 |
+| dry-inflector (Ruby) | 12 (7) | 26 | 26 | 26 | 813 / 718 of 1,109 |
+| uuid (TypeScript, node:test) | 4 (3) | 6 | 6 | 6 | 13.2 / 11.5 of 64 |
+| dtolnay/semver (Rust) | 20 (0) | 0 | -- | -- | 27.9 / 25.9 of 38 |
+| commons-cli (Java) | 15 (7) | 12 | 12 | 12 | 159 / 143 of 985 |
+
+No failing test was left out of the set to run. On real commits the
+assessment narrows little -- Jev judges most tests that ran a changed line to
+catch the change -- and its verdicts alone ranked a failing test in the first
+three for only 6 of 32 breaking commits. Ranking by name, with the verdicts
+breaking ties, put one there for 10 of those 32, and for 15 of 25 breaking
+commits in four projects it was not designed on (hashie, Masterminds/semver,
+itsdangerous, java-classmate), where file order managed 11; without an
+assessment, name alone managed 8 and 12. After a project's first
+assessment, each commit cost under a cent.
+
 ## Combine shards
 
 ```sh supercov
@@ -461,6 +507,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_BUILD_COMMAND` | The build a JavaScript project's tests need, as words or a JSON array, such as `yarn workspace web build` in a monorepo whose root `build` builds every package. Without it Supercov runs the project's `build` script, through the package manager that started the tests, when the tests need built output |
 
 Examples:
 
@@ -477,3 +524,8 @@ SUPERCOV_TEST_KIND=e2e npx supercov -- npx playwright test
 | Wrapped command's code | The test command failed and Supercov preserved its status |
 | `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 |
+
+`quality` and `security` exit `0` for a complete report in which some files
+could not be assessed, such as a file larger than the model accepts; each is
+listed in the report with its reason, and stderr says how many. They exit `2`
+when no file could be assessed.

package/docs/coverage-model.md

@@ -150,9 +150,8 @@ or generated output merely to make a warning disappear.
 
 ## Assertion percentage
 
-When a run has an `assertions.json` map, its regular summary also shows
-agent-assessed assertion coverage: credited measured statements divided by all
-measured statements. This row always describes the whole archived run,
-independently of `--filter`, `--kind` and `--runner`. It is separate from the
-structural metrics above. See [assertion maps](assertion-maps.md) for credit,
-freshness and incomplete-map rules.
+When a run has been assessed with `assertions assess`, its regular summary also
+shows assertion coverage: executed statements a test is judged to catch
+breaking, divided by all assessed statements. This row always describes the
+whole run, independently of `--filter`, `--kind` and `--runner`, and is separate
+from the structural metrics above. See [assertion coverage](assertions.md).

package/docs/evidence.md

@@ -134,14 +134,3 @@ SUPERCOV_TEST_KIND=integration npx supercov -- npm test
 
 Supported values are `unit`, `component`, `integration` and `e2e`. Use separate
 runs when different suites need different classifications.
-
-## When assertion evidence is missing
-
-A test can make assertions without executing measured application code. It
-might check static data or a dependency, or use work performed in shared setup.
-Missing attribution across an asynchronous boundary can also leave a gap.
-
-The assertion detail explains why a mapped node did or did not receive credit.
-Use [Investigating assertion evidence](assertion-evidence.md) to distinguish
-these cases. The report's runtime action-phase counts are separate from the
-assertion map; zero action-phase lines does not mean zero asserted statements.

package/docs/getting-started.md

@@ -139,7 +139,7 @@ if anything is missing.
 - for Go, Go 1.22 or newer;
 - for Java and Kotlin, JDK 17 or newer, with Maven or Gradle;
 - for Python, CPython 3.9 or newer with pytest or unittest;
-- for Ruby, Ruby 3.4 or newer with RSpec, Minitest, test-unit or Cucumber (3.3 measures lines, methods and simple branches only).
+- for Ruby, Ruby 3.3 or newer with RSpec, Minitest, test-unit or Cucumber.
 
 The CLI is a native binary. `npx supercov` picks the build for your operating
 system and architecture, and nothing is compiled on install; the same binary is

package/docs/performance.md

@@ -130,18 +130,10 @@ Use `--dry-run` to preview cleanup. Keep enough run history for active reviews
 and automation; remove the cache only when reclaiming space matters more than a
 faster next run.
 
-## Keep assertion investigation fast
+## Keep assertion assessments fast and cheap
 
-Save `assertions.json` and query the run to see the updated score. Supercov does
-not rerun tests or call a model to calculate the report. Repeated queries reuse
-the previous assessment while checking that your source still matches the run.
-Editing the map automatically refreshes that assessment.
-
-For large maps, ask for a short page instead of the whole graph. Within one
-flow, `--view nodes` or `--view edges` pages the details; `--compact` omits repeated
-source text while keeping locations and credit reasons. See
-[Investigating assertion evidence](assertion-evidence.md#read-a-large-flow).
-
-The disposable `assertions.report.cache.json` and `assertions.summary.cache.json`
-files live beside the map. A missing or damaged cache is rebuilt. Removing it affects the next query's speed, not
-your saved explanations.
+`assertions assess` asks only questions it has not answered before; answers live
+in `.supercov/assertions/` and are reused across runs whenever the question is
+the same. `--workers N` raises the requests in flight (default 8) for a faster,
+slightly costlier pass. `--dry-run` prints the estimate without sending
+anything.

package/docs/quality.md

@@ -1,6 +1,6 @@
 # Understanding quality
 
-`supercov quality` tells you what is in your code: twelve named properties,
+`npx supercov quality` tells you what is in your code: twelve named properties,
 checked file by file, so a score is never a number you have to take on faith.
 
 Judgments come from [Jev](https://typesafe.ai), which answers typed questions

package/docs/security.md

@@ -1,10 +1,10 @@
 # Security surface
 
-`supercov security` tells you what security-relevant surface each file shows:
+`npx supercov security` tells you what security-relevant surface each file shows:
 twelve named checks, asked file by file, each mapped to the weakness classes it
 stands for. There is no score. A file is clean, or it names what fired.
 
-Judgments come from [Jev](https://typesafe.ai), the same way `supercov quality`
+Judgments come from [Jev](https://typesafe.ai), the same way `npx supercov quality`
 gets them. Set `TYPESAFE_API_KEY`, and optionally another provider, as described
 in [quality](quality.md); reading a saved assessment never needs a key.
 
@@ -50,16 +50,47 @@ attempt measured on the labelled corpus fired on unguarded handlers the
 application leaves open by design as often as on the ones it should not.
 
 
-Measured with this command on fifteen held-out repositories of a
-140-repository labelled corpus, whole repositories, at finding level: F1
-0.47 with 54% precision and 41% recall, where Semgrep scores 0.14, the
-general agentic LLM scanners 0.50 to 0.60, and the two leaders 0.76 and
-0.77, at about two cents per repository against 30 cents to 4 dollars for
-the agentic scanners. Injection, secrets, path, redirect and mass
-assignment are found at 70 to 90% recall; authorisation and authentication
-at 10%, because the guard that decides them lives in another file. A file
-too large for one request is read in windows at declaration boundaries.
-
+Measured with 2.0.1 on the 72 held-out repositories of RealVuln, a
+140-repository labelled corpus, scored by its own rule: F1 0.42 with 42%
+precision and 43% recall, in a median of 10 seconds and about 5 cents a
+repository. The strongest agent-based scanners score 0.69 to 0.71 but take
+5 to 9 minutes and about $4 a repository; Semgrep's default rules score 0.11.
+Redirects, injection, unsafe code execution and paths taken from a request
+are found at 79 to 89% recall; authorisation (11%) and authentication (24%)
+are the weakest, because the guard that decides them lives in another file.
+Every scanner's results are at
+[supercov.com/docs/security-benchmark](https://supercov.com/docs/security-benchmark).
+A file too large for one request is read in windows at declaration
+boundaries, or at line boundaries where Supercov has no parser for it, such as
+a template.
+
+## What is read
+
+Security reads every source file, template and configuration file that the
+conventions do not exclude, including files under no recognised source root,
+because code a project did not declare is deployed as often as not.
+`npx supercov security scope` lists exactly the files a run reads and why the
+rest were left out. Three kinds are left out because they are not the code
+under review:
+
+- **Tests and generated output**, as for `quality`.
+- **Vendored and minified JavaScript.** A minified file anywhere, and in a
+  served or vendor directory (`static/`, `public/`, `assets/`, `plugins/`,
+  `vendor/`, `lib/`) a file with a licence banner or a well-known library's
+  name, such as `jquery.flot.js` or `swagger-ui-bundle.js`.
+- **JSON data.** A JSON file is read when its name or directory says it
+  configures something (`config.json`, `proxy.conf.json`, `appsettings.json`,
+  `secrets.json`, anything under `config/`), and not when it holds data such
+  as translations, schema snapshots or scanner output.
+
+A directory called `target/` is build output only when a build that writes
+there (Cargo, Maven, Gradle, sbt, Leiningen) is declared beside it; otherwise
+it is read like any other. Name a file directly to read it whatever the scope
+says: `npx supercov security static/js/app.min.js`.
+
+A run that could not assess a few files still exits 0: each one is in the
+report with its reason, and stderr says how many. It exits 2 only when no
+file could be assessed.
 ## Across files
 
 The second pass also labels every function of every file, on the same

package/docs/supported-suites.md

@@ -50,9 +50,11 @@ Supercov reports the level it actually observed. It does not guess.
 | --- | --- |
 | Playwright | Exact per test, worker, retry, outcome, action, and assertion phase |
 | Vitest | Exact per test, with setup execution kept separate; Browser Mode included |
-| Jest | Exact per test, including parameterized tests, with the user's own configuration, setup files and reporters kept; passing `expect` occurrences are identified for assertion maps |
+| Jest | Exact per test, including parameterized tests, with the user's own configuration, setup files and reporters kept |
 | `node:test` | Exact per test |
-| AVA and Mocha | Aggregate structural coverage |
+| Mocha | Exact per test and retry, `--parallel` included, with setup execution kept separate |
+| AVA | Exact per test, concurrent tests included, in worker threads or child processes |
+| node-tap 15 and newer | Exact per subtest, nested and parallel (`t.jobs`) subtests included |
 | Other Node-based runners | Aggregate when their processes remain visible to Supercov |
 | Browser component runners without an adapter | Aggregate structural coverage |
 
@@ -81,9 +83,6 @@ obligations. `{value}` is reached exactly when the tree is, and
 `onClick={() => save()}` is measured where the handler is called rather than
 where it is created.
 
-`expect.element(...)`, `expect.soft(...)` and `expect.poll(...)` are recognised
-as assertions, so their passing occurrences are available to assertion maps.
-
 ### React and React Native
 
 React components can use Testing Library with Vitest/jsdom, Vitest Browser Mode,
@@ -93,11 +92,10 @@ it does not measure Hermes, native modules, simulator/device execution, Detox or
 Maestro. React SSR hydration is exercised in jsdom and Chromium; this does not
 establish Next.js Server Components, streaming SSR or server actions.
 
-An assertion map can explain which displayed value, accessible name, disabled
-state or error message a test checks. JSX expression coverage and a passing
-assertion are evidence for reviewing that explanation, not automatic semantic
-proof. A button being rendered does not establish that its disabled state was
-checked. Keep your existing runner and matchers.
+Assertion coverage treats a JSX expression as a statement: it asks whether a
+test would notice the displayed value, accessible name, disabled state or error
+message becoming undefined. A button being rendered does not establish that its
+disabled state was checked. Keep your existing runner and matchers.
 
 The [React verification example](https://github.com/supercorp-ai/supercov/tree/main/examples/react-verification)
 shows a fully executed checkout whose weak tests accept four UI regressions,
@@ -118,11 +116,6 @@ Supercov runs the project's build inside the isolated copy before testing.
 Keep using your normal test and build commands. Instrumentation does not
 require changing the project's TypeScript settings.
 
-For assertion maps, Node, Vitest, Jest and Playwright's Node-side assertions
-supply supported passing-occurrence evidence. Custom assertion wrappers and
-browser-side checks can have additional observation limits. See
-[Assertion evidence](assertion-evidence.md) before interpreting a missing occurrence.
-
 ### Browsers, servers, and child processes
 
 Playwright support includes Chromium, Firefox, and WebKit, along with pages,
@@ -169,6 +162,19 @@ modules. Statements, functions, branches, boolean decisions, loops and error
 propagation are measured. Const contexts and macro expansions remain visible
 with explicit measurement limitations.
 
+Test code is not measured, as cargo-llvm-cov and cargo-tarpaulin leave it out:
+files under a `tests`, `examples` or `benches` directory, files named
+`tests.rs`, `*_tests.rs` or `*-tests.rs`, everything a test target or a
+`#[cfg(test)]` module declares, and items marked `#[cfg(test)]`, `#[test]` or
+`#[bench]`. Its assertions still mark which evidence a passing assertion
+witnessed.
+
+Neither is code the compiler never builds for the target: a `#[cfg(windows)]`
+function on Linux, or one behind `#[cfg(not(target_os = "macos"))]` on a Mac,
+is not counted. Only predicates the target settles (`unix`, `windows`,
+`target_*`) are decided; an item behind a feature or a custom cfg is counted
+either way.
+
 Use the repository's normal flags after the wrapped command:
 
 ```sh
@@ -200,7 +206,8 @@ comprehensions, short-circuit operators, `match` cases and exception paths.
 Child interpreters, threads and thread pools can retain the calling test's
 identity. The report also distinguishes execution before a passing assertion
 from later execution. These phase records alone do not prove which values the
-assertion checks.
+assertion checks; [assertion coverage](assertions.md) measures which executed
+statements the pytest and unittest tests would catch breaking.
 
 Interpreters launched with `-I`, `-E` or `-S` ignore the required startup hook
 and are not measured. Code compiled from strings at runtime has no source
@@ -222,23 +229,21 @@ npx supercov -- python -m unittest
 | Runner | Attribution | Current requirement |
 | --- | --- | --- |
 | RSpec | Exact example and before/example/after phase identity | Ruby 3.4 or newer for full measurement; run with `npx supercov -- rspec` or `bundle exec rspec` |
-| Minitest (including Minitest::Spec and ActiveSupport::TestCase) | Exact test and setup/test/teardown identity; a test's coverage is a lower bound (see below); skips recorded | `ruby -Itest ...`, `rake test`, `rails test` |
+| Minitest (including Minitest::Spec and ActiveSupport::TestCase) | Exact test and setup/test/teardown identity; skips recorded | `ruby -Itest ...`, `rake test`, `rails test` |
 | test-unit | Exact test and setup/test/teardown identity; omissions and pendings recorded | `ruby -Itest ...`, `rake test` |
 | parallel_tests, Rails process workers | Exact per worker process | Workers inherit the run through `RUBYOPT`; verified on a Rails app with bootsnap, Zeitwerk and two forked workers |
 | Thread-parallel Minitest (`parallelize_me!`, `parallelize(with: :threads)`) | Probe observations exact per test; line, method and simple-branch observations made while phases overlapped go to the run, declared | |
 | Cucumber | Exact scenario identity (`features/x.feature:LINE`), hook steps as setup/teardown | `cucumber`, `bundle exec cucumber` |
 
-Ruby reports a line the first time it executes and never again, which is what
-makes collecting coverage cheap enough to leave on. So a test is credited with
-the lines it was first to reach, and a later test running the same lines is
-credited with none of them: what a test is credited with is really its own, and
-what it is not credited with is not evidence it did not run the code.
-
-Totals are unaffected — every line is credited to exactly one test. What this
-changes is per-test reporting: `supercov runs <id> test <name>` gives its
-numbers as "at least", and `tests affected` reports a test whose own record
-cannot settle the question as **undetermined** rather than unaffected, so
-`--names` includes it in the set to run.
+Every test is credited with every line it runs: each statement of an
+instrumented file carries a probe. Code Supercov cannot instrument -- a file
+it could not compile with its probes, or a `Ractor.new` block, where no probe
+can run -- falls back to Ruby's one-shot line coverage, which reports a line
+the first time it executes and never again. There a test is credited with the
+lines it was first to reach; what it is not credited with is not evidence it
+did not run the code. The run says so, per-test numbers there read "at least",
+and `tests affected` reports a test whose own record cannot settle the
+question as **undetermined**, so `--names` includes it in the set to run.
 
 Your project runs in place with its own interpreter and bundle. Supercov loads
 through `RUBYOPT`; application files on disk and their backtrace line numbers
@@ -246,11 +251,9 @@ stay unchanged. RSpec, Minitest and test-unit assertions can identify execution
 before a passing assertion. That timing evidence alone does not show which
 values the assertion checks.
 
-Ruby 3.4 and newer support statement, method, branch and MC/DC measurement,
+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. Ruby 3.3 supplies Ruby's own line, method
-and branch coverage; obligations requiring additional instrumentation are
-reported as measurement limits.
+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
@@ -300,7 +303,7 @@ which costs whatever its parallelism was worth — on sixteen I/O-bound JUnit
 tests across fifteen cores, 3.6x. Either way the coverage totals are the same;
 what changes is whether a line can be traced to the test that ran it.
 
-`supercov runs latest` reports which you got, under `Attribution`.
+`npx supercov runs latest` reports which you got, under `Attribution`.
 
 ## Go
 
@@ -332,7 +335,7 @@ measured the same way: `go test` runs both, and what they reach is real
 coverage no test can claim.
 
 Such a test is still recorded as having run, with its outcome, and credited
-with no coverage. `supercov runs <id> test <name>` says that rather than
+with no coverage. `npx supercov runs <id> test <name>` says that rather than
 reporting zeroes, coverage percentages leave it out, and `tests affected` lists
 it as **undetermined**: nothing can say a change missed it, so `--names`
 includes it in the set to run. A package where every test calls `t.Parallel()`
@@ -347,10 +350,6 @@ no way to run code on `os.Exit`, and a `TestMain` need not reach the `m.Run()`
 call Supercov wraps — `goleak.VerifyTestMain(m)` runs the suite and exits
 itself. Without periodic writes such a run recorded nothing at all.
 
-For assertion maps, `t.Error`, `t.Errorf`, `t.Fatal`, `t.Fatalf` and testify's
-`assert` and `require` are inventoried. A Go test states its claim with an `if`
-and reports the violation, so the report is the site.
-
 A repository with several modules works either way it is laid out. A directory
 with a `go.mod` of its own that no `go.work` names is a different module, and
 `go test ./...` walks past it, so Supercov leaves it alone. A `go.work`
@@ -372,7 +371,7 @@ npx supercov -- go test ./core/... ./app/...
 | Kotest | Exact per test, under the names Kotest itself reports | — |
 | Spock | Exact per feature, under the names Spock itself reports | — |
 | TestNG | Exact per test, each data-provider invocation its own | — |
-| JUnit 4 alone | Exact per test, through Vintage — see below | Maven |
+| JUnit 4 alone | Exact per test, through Vintage — see below | Maven or Gradle |
 
 Multi-module builds are measured module by module: each compiles its own source
 set and forks its own JVM, so each gets a runtime and records evidence of its
@@ -391,10 +390,11 @@ report name the same thing.
 JUnit 4 on its own is not a platform engine and does not run on one. Maven and
 Gradle choose a test provider from what is on the classpath, so putting the
 platform there makes the build pick a provider that finds no engine and fail.
-For a Maven module, Supercov adds `junit-vintage-engine` to the copy — the
-platform's own way of running exactly those JUnit 4 tests through the lifecycle
-it listens to — and measures them; your own build still runs JUnit 4 as it did.
-A Gradle module is left alone and told about rather than broken.
+Supercov adds `junit-vintage-engine` to the copy — the platform's own way of
+running exactly those JUnit 4 tests through the lifecycle it listens to — and
+measures them; your own build still runs JUnit 4 as it did. In a Gradle build
+the copy also switches each JUnit 4 module's test tasks to `useJUnitPlatform()`,
+leaving any task the build already put on the platform or on TestNG as it was.
 
 Supercov instruments an isolated copy and leaves your build file alone. In the
 copy it adds a test-scoped `junit-platform-launcher`, because the listener is
@@ -423,15 +423,11 @@ same goes for a loop over a constant, `while (true)`, which can only go one
 way. A Kotlin `contract { }` has to stay the first statement of its function,
 so the probe that records the function being entered is written after it.
 
-Every one of these is named in the run: ask for `supercov runs latest
+Every one of these is named in the run: ask for `npx supercov runs latest
 limitations` and each appears with its file, its line, and why it was left
 alone. A source file the parser cannot read is declared there too, so a hole in
 the denominator stays visible after the build log is gone.
 
-For assertion maps, forms spelled `assertSomething`, `assertThat` or `fail` are
-inventoried, which covers JUnit, TestNG, AssertJ, Hamcrest and kotlin.test.
-Kotest's infix matchers are not.
-
 ```sh
 npx supercov -- mvn test
 npx supercov -- ./gradlew test

package/docs/troubleshooting.md

@@ -93,11 +93,18 @@ outside that loader. Supercov declares this boundary on the affected file,
 including on Python 3.9–3.11. It does not silently rewrite the child command,
 which could change imports, `sys.argv`, or process behavior.
 
-A file can therefore have tests that touched it through an import, while a
-separate direct execution makes its overall coverage unmeasured. Those lines
-are excluded from both the measured denominator and the uncovered-lines list.
-Inspect the file's measurement limitations before treating a zero denominator
-as complete coverage.
+A file that tests also import stays measured: what the imports ran is
+counted, and the file carries the limitation, because lines it shows as
+uncovered may have run in the direct execution. Its numbers are a lower bound,
+and the run reports its measurement as incomplete. A file that is only ever
+run directly has nothing observed, and is left out of the measured denominator
+and the uncovered-lines list; inspect its measurement limitations before
+treating a zero denominator as complete coverage.
+
+To have a script measured, run it through the import system:
+`python -m package.module`, or, for a file whose name is not a module name
+such as `bin/anti-drift-gate.py`, `runpy.run_path("bin/anti-drift-gate.py",
+run_name="__main__")` from a test.
 
 ## Python subprocess output or timeout assertions fail