supercov 0.0.43 → 0.0.44

package/docs/cli.md

@@ -4,7 +4,7 @@ Supercov has one command for measuring a suite and a small set of commands for
 reading the result. Text output is designed for people and coding agents. Add
 `--json` only when an integration needs a stable machine-readable response.
 
-```sh
+```sh supercov
 npx supercov --help
 ```
 
@@ -25,13 +25,13 @@ npx supercov --help
 
 ## Measure a test command
 
-```sh
+```sh supercov
 npx supercov -- <test command>
 ```
 
 Everything after `--` is passed to the test command:
 
-```sh
+```sh supercov
 npx supercov -- npm test
 npx supercov -- npx playwright test --project=chromium
 npx supercov -- cargo test
@@ -43,7 +43,7 @@ preserves the wrapped command's exit status, so it can remain a CI gate.
 
 ## List and select runs
 
-```sh
+```sh supercov
 npx supercov runs
 npx supercov runs --limit 5
 npx supercov runs latest
@@ -56,7 +56,7 @@ sessions.
 
 ## Query a run
 
-```sh
+```sh supercov
 npx supercov runs <run-id> [query] [options]
 ```
 
@@ -77,7 +77,7 @@ npx supercov runs <run-id> [query] [options]
 
 Common examples:
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --limit 10
 npx supercov runs latest file app/routes/checkout.ts
 npx supercov runs latest decision app/routes/checkout.ts:42
@@ -87,7 +87,7 @@ npx supercov runs latest test "checkout retry"
 
 Run any query with `--help` to see only the options valid for that query:
 
-```sh
+```sh supercov
 npx supercov runs latest --help
 npx supercov runs latest file --help
 npx supercov runs latest assertions --help
@@ -115,14 +115,14 @@ Collection output includes a copyable command for the next page.
 
 For a large file, group and rank its decisions:
 
-```sh
+```sh supercov
 npx supercov runs latest file app/routes/checkout.ts \
   --group decision --sort missing
 ```
 
 ## Compare runs
 
-```sh
+```sh supercov
 npx supercov diff <older-run> <newer-run>
 ```
 
@@ -132,13 +132,13 @@ Neither input run is changed.
 
 The same filters can focus a comparison:
 
-```sh
+```sh supercov
 npx supercov diff <older-run> <newer-run> --kind e2e
 ```
 
 ## Find a smaller test set
 
-```sh
+```sh supercov
 npx supercov runs latest minimize
 npx supercov runs latest minimize --metric branches --target 90
 ```
@@ -150,7 +150,7 @@ selected metric.
 
 ## Combine shards
 
-```sh
+```sh supercov
 npx supercov merge <shard-a> <shard-b> <shard-c>
 ```
 
@@ -160,7 +160,7 @@ incompatible merge rather than publishing a misleading aggregate.
 
 ## Clean local data
 
-```sh
+```sh supercov
 npx supercov clean --dry-run
 npx supercov clean --keep 20
 npx supercov clean
@@ -172,7 +172,7 @@ storage.
 
 ## Read bundled documentation
 
-```sh
+```sh supercov
 npx supercov docs
 npx supercov docs getting-started
 npx supercov docs troubleshooting
@@ -190,7 +190,7 @@ terminal or offline environment after the package has been downloaded.
 
 Examples:
 
-```sh
+```sh supercov
 SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
 SUPERCOV_TEST_KIND=e2e npx supercov -- npx playwright test
 ```

package/docs/code-verification.md

@@ -1,182 +1,4 @@
-# Example
+# Agent workflow
 
-This example measures coverage for a small checkout function. It includes the
-original tests, an additional test for an expired session, and commands for
-comparing the results.
-
-## Before you start
-
-You need Node.js 22 or newer and npm. Clone the repository and install the
-example's dependencies:
-
-```sh
-git clone --depth 1 https://github.com/supercorp-ai/supercov.git
-cd supercov/examples/checkout-verification
-npm ci
-```
-
-Run the commands below from this directory. The example uses Supercov 0.0.42
-and Node's built-in test runner. Both the original tests and the additional
-test are included. The first three steps do not require any file edits.
-
-## 1. Run the original tests
-
-In `src/session.js`, checkout is allowed only if the customer is signed in and
-their session has not expired:
-
-```js
-export function canCheckout(signedIn, expired) {
-  if (signedIn && !expired) return true;
-  return false;
-}
-```
-
-The two tests in `tests/session.test.js` check a valid session and a signed-out
-visitor:
-
-```js
-assert.equal(canCheckout(true, false), true);
-assert.equal(canCheckout(false, false), false);
-```
-
-Run those tests through Supercov, then open the summary:
-
-```sh
-npx supercov -- node --test tests/session.test.js
-npx supercov runs latest
-```
-
-Everything after `--` is the test command Supercov runs. In your own project,
-use your existing test command there.
-
-Both tests pass. The coverage section shows:
-
-```text
-Coverage
-  Lines      100.00% (3/3)
-  Branches   100.00% (2/2)
-  MC/DC      50.00% (1/2)
-```
-
-Line and branch coverage are 100% because the tests reach both `return true`
-and `return false`. The MC/DC result shows there is still a condition to test.
-
-Keep the run ID printed at the top of the summary. You'll use it to compare
-this run with the next one.
-
-## 2. Inspect the missing condition
-
-Ask about the decision on line 2:
-
-```sh
-npx supercov runs latest decision src/session.js:2
-```
-
-```text
-signedIn && !expired
-C1 covered + asserted: signedIn
-C2 MISSING: !expired
-confidence asserted; asserted MC/DC 1/2
-```
-
-MC/DC stands for Modified Condition/Decision Coverage. It checks whether each
-condition has independently affected the decision. The original tests show
-that changing `signedIn` changes the result, but neither test changes `expired`.
-That leaves one of two conditions covered: 50%.
-
-`C2 MISSING: !expired` points to the case to test: a customer who is still
-signed in, but whose session has expired. Checkout should be denied.
-
-## 3. Include the expired-session test
-
-`tests/expired-session.test.js` contains that test:
-
-```js
-test('an expired session cannot check out', () => {
-  assert.equal(canCheckout(true, true), false);
-});
-```
-
-Run both test files and open the new summary:
-
-```sh
-npx supercov -- node --test tests/session.test.js tests/expired-session.test.js
-npx supercov runs latest
-```
-
-All three tests pass:
-
-```text
-Coverage
-  Lines      100.00% (3/3)
-  Branches   100.00% (2/2)
-  MC/DC      100.00% (2/2)
-```
-
-Query the same decision again:
-
-```sh
-npx supercov runs latest decision src/session.js:2
-```
-
-The expiry condition is now covered. `asserted MC/DC 2/2` means both conditions
-have coverage evidence linked to passing assertions:
-
-```text
-C2 covered + asserted: !expired
-confidence asserted; asserted MC/DC 2/2
-```
-
-Compare the runs, replacing `<before-run-id>` with the ID you saved in step 1:
-
-```sh
-npx supercov diff <before-run-id> latest
-```
-
-```text
-lines +0pp, branches +0pp, MC/DC +50pp
-gained: 0 lines, 0 branches, 1 MC/DC conditions
-lost: 0 lines, 0 branches, 0 MC/DC conditions
-+ MC/DC src/session.js:2 C2 !expired
-```
-
-Line and branch coverage have not changed. The new test covers the missing
-expiry condition without changing application code.
-
-## 4. Check that the test catches a regression
-
-In this example only, temporarily remove the expiry check from `src/session.js`:
-
-```diff
--  if (signedIn && !expired) return true;
-+  if (signedIn) return true;
-```
-
-Run the original two tests against the changed function:
-
-```sh
-npx supercov -- node --test tests/session.test.js
-```
-
-Then include the expired-session test:
-
-```sh
-npx supercov -- node --test tests/session.test.js tests/expired-session.test.js
-```
-
-| Tests run against the changed function | Result |
-| --- | --- |
-| Original two tests | Both pass. |
-| All three tests | The expired-session test fails; the other two pass. |
-
-The new test expects `false`, but the changed function returns `true`. The
-second command should fail: that is the test catching the removed expiry check.
-
-Restore `&& !expired` in `src/session.js` when you finish, then rerun all three
-tests with the same command. They should pass again.
-
-## Next
-
-- [Full example and recorded output](https://github.com/supercorp-ai/supercov/tree/main/examples/checkout-verification) — source, tests, and the complete output excerpted above.
-- [Understanding coverage](coverage-model.md) — what each metric measures and what 100% means.
-- [Agent workflow](agent-loop.md) — use the same run, inspect, test, and compare steps with a coding agent.
+The tutorial is now part of [Agent workflow](agent-loop.md), including the
+prompt, recorded checkout example, and guidance for longer runs.

package/docs/coverage-model.md

@@ -17,7 +17,7 @@ runner boundary.
 Supercov keeps those states separate. It does not turn “unknown” into
 “uncovered,” and it does not round either one away to produce a reassuring 100%.
 
-```sh
+```sh supercov
 npx supercov runs latest
 npx supercov runs latest gaps
 npx supercov runs latest scope
@@ -39,7 +39,7 @@ The exact obligations depend on the language and source construct. You do not
 need to reason about all of them at once. Start with a file, then open a decision
 or line only when the missing behavior needs explanation:
 
-```sh
+```sh supercov
 npx supercov runs latest file app/checkout/session.ts
 npx supercov runs latest decision app/checkout/session.ts:64
 npx supercov runs latest line app/checkout/session.ts:64
@@ -92,7 +92,7 @@ each runner.
 
 The same stored run can answer different questions:
 
-```sh
+```sh supercov
 npx supercov runs latest --filter all
 npx supercov runs latest --filter passed
 npx supercov runs latest --filter failed
@@ -103,7 +103,7 @@ attempts. `failed` isolates failed attempts, including failed retries.
 
 You can also focus on a test level or runner:
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --kind e2e
 npx supercov runs latest gaps --runner playwright
 ```
@@ -115,13 +115,13 @@ percentage that was computed from a different set of tests.
 
 If the summary reports ambiguous source scope, inspect it:
 
-```sh
+```sh supercov
 npx supercov runs latest scope
 ```
 
 When first-party source lives in unusual directories, declare it explicitly:
 
-```sh
+```sh supercov
 SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
 ```
 

package/docs/evidence.md

@@ -6,7 +6,7 @@ without rerunning the tests.
 
 ## Find the run you want
 
-```sh
+```sh supercov
 npx supercov runs
 npx supercov runs --limit 10
 npx supercov runs latest
@@ -23,7 +23,7 @@ A run id is immutable. `latest` is only a convenient selector.
 
 ## Ask the same run different questions
 
-```sh
+```sh supercov
 npx supercov runs latest gaps --limit 10
 npx supercov runs latest file app/checkout/session.ts
 npx supercov runs latest line app/checkout/session.ts:64
@@ -45,7 +45,7 @@ new work from it.
 
 ## Focus on passed or failed attempts
 
-```sh
+```sh supercov
 npx supercov runs latest --filter all
 npx supercov runs latest --filter passed
 npx supercov runs latest --filter failed
@@ -60,7 +60,7 @@ reports that can drift apart.
 
 ## Compare before and after
 
-```sh
+```sh supercov
 npx supercov diff <older-run> <newer-run>
 ```
 
@@ -76,7 +76,7 @@ need to reproduce the result.
 
 ## Combine distributed shards
 
-```sh
+```sh supercov
 npx supercov merge <shard-a> <shard-b> <shard-c>
 ```
 
@@ -100,7 +100,7 @@ Completed runs live under `.supercov/runs/<run-id>/`. The isolated workspace and
 instrumented build cache may use more space than the compressed run itself.
 Nothing is pruned in the background.
 
-```sh
+```sh supercov
 npx supercov clean --dry-run
 npx supercov clean --keep 20
 npx supercov clean

package/docs/getting-started.md

@@ -1,68 +1,50 @@
 # Getting started
 
-Supercov turns the test suite you already have into a list of useful tests to
-write next. Run the suite once, inspect a coverage gap, add a focused test, and
-compare the result.
+Open your project in a coding agent that can run terminal commands, then paste
+this prompt:
 
-```sh
-npx supercov -- npm test
+```text supercov-prompt
+Measure code coverage with npx supercov and write one missing test.
+Only change tests. Rerun the full test suite and show me the test you
+added and the before-and-after coverage.
 ```
 
-No account, config file, import, custom reporter, or hosted service is required.
-Supercov supports JavaScript, TypeScript, Rust, Python, and Ruby today.
+Your agent can install Supercov if needed. It runs the commands and edits the
+tests; you don't need to do those steps yourself.
 
-## Before you start
+When it finishes, review the test change and coverage comparison in your
+conversation. Ask separately if you want a commit or pull request.
 
-You need:
+No account, config file, import, custom reporter, or hosted service is required.
+Supercov supports JavaScript, TypeScript, Rust, Python, and Ruby today.
 
-- macOS (arm64 or x64), Linux (arm64 or x64, glibc 2.28 or newer or musl), or
-  Windows (arm64 or x64);
-- Node.js 22 or newer;
-- a test command that already works in the repository; and
-- for Rust, the Rust 1.95 toolchain;
-- for Python, CPython 3.12 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).
+## What the agent does
 
-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
-on PyPI as `supercov-cli` (`uvx --from supercov-cli supercov`) and on RubyGems
-as `supercov` (`gem install supercov`), at the same version, and the source is
-on crates.io (`cargo install supercov`). The first invocation may download
-Supercov from the registry. Supercov itself does not upload your source or
-coverage evidence to a Supercov service.
+The commands below show how the agent measures coverage and checks its work.
+You can also run them yourself if you prefer using the terminal.
 
-## 1. Run your real test command
+### 1. Run your real test command
 
-Everything after `--` is the command Supercov measures. Start with the same
-complete command you trust before merging or deploying:
+The agent runs your repository's complete test suite through Supercov:
 
-```sh
-# JavaScript or TypeScript
+```sh supercov-example
 npx supercov -- npm test
-npx supercov -- npx playwright test
-npx supercov -- pnpm test:e2e
-
-# Rust
-npx supercov -- cargo test
-npx supercov -- cargo nextest run
-
-# Python
-npx supercov -- pytest
-
-# Ruby
-npx supercov -- rspec
 ```
 
+Everything after `--` is the command Supercov measures. The agent should use
+the same complete command your project uses before merging or deploying.
+If the project has several suites, tell it which one to use.
+
 Supercov runs that command in an isolated, instrumented copy of the project.
 The command keeps its normal arguments, environment, output, and exit status.
 If one command launches several supported runners, their evidence lands in one
 run.
 
-## 2. Read the first result
+### 2. Read the first result
 
-Open the newest run:
+The agent reads the newest run:
 
-```sh
+```sh supercov-example
 npx supercov runs latest
 ```
 
@@ -76,18 +58,19 @@ An uncovered gap is a candidate for a test. A measurement limit is different:
 it means Supercov cannot honestly account for that code yet. Do not try to test
 away a measurement limit.
 
-## 3. Choose one useful gap
+### 3. Choose one useful gap
 
-Ask for a short list, then inspect one file:
+The agent asks for a short list of gaps, then inspects one file. It uses your
+project's file paths in place of the examples:
 
-```sh
+```sh supercov-example
 npx supercov runs latest gaps --limit 10
 npx supercov runs latest file app/checkout/session.ts
 ```
 
-Use the more specific queries when you need them:
+It can use more specific queries to understand the gap:
 
-```sh
+```sh supercov-example
 npx supercov runs latest decision app/checkout/session.ts:64
 npx supercov runs latest line app/checkout/session.ts:64
 ```
@@ -96,40 +79,45 @@ npx supercov runs latest line app/checkout/session.ts:64
 outcomes and MC/DC witnesses. `line` shows the obligations and tests associated
 with one source line.
 
-## 4. Add a test and prove the gain
+### 4. Add a test and prove the gain
 
-Write one focused test with a meaningful assertion. Then rerun the same complete
-command and compare the two runs:
+The agent writes one focused test with a meaningful assertion. It then reruns
+the same complete command and compares the two runs:
 
-```sh
+```sh supercov-example
 npx supercov -- npm test
 npx supercov diff <previous-run-id> latest
 ```
 
-For Rust, rerun the same `cargo test` or `cargo nextest run` command used for the
-baseline. A useful change leaves the suite passing and shows the expected gain
-without an unexplained loss elsewhere.
+A useful change leaves the suite passing and shows the expected gain without
+an unexplained loss elsewhere. Review what the new test actually checks, not
+just the percentage.
 
-## Give the loop to a coding agent
+For a recorded example and prompts for longer runs, see
+[Agent workflow](agent-loop.md).
 
-Paste this into any coding agent that can run terminal commands:
+## Environment requirements
 
-```text
-Use `npx supercov` to improve coverage. Only write tests. Keep going while
-useful gaps remain.
+These requirements apply wherever the agent runs commands: your machine,
+a container, or a remote workspace. The agent can check them and tell you
+if anything is missing.
 
-Run the repository's complete test command through Supercov. Use
-`npx supercov runs latest gaps --limit 5` to choose one useful target. Inspect
-the target, write one focused test with meaningful assertions, rerun the same
-complete suite, and verify the gain with
-`npx supercov diff <previous-run-id> latest`.
-
-Never weaken assertions or change application code to make coverage easier.
-Stop when no useful gap remains or Supercov reports a measurement limit instead
-of an ordinary gap.
-```
+- macOS (arm64 or x64), Linux (arm64 or x64, glibc 2.28 or newer or musl), or
+  Windows (arm64 or x64);
+- Node.js 22 or newer when using the npm package;
+- a working test command, including its dependencies, environment variables,
+  and any local services;
+- for Rust, the Rust 1.95 toolchain;
+- for Python, CPython 3.12 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).
 
-Replace `npm test` with the repository's real complete test command when needed.
+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
+on PyPI as `supercov-cli` (`uvx --from supercov-cli supercov`) and on RubyGems
+as `supercov` (`gem install supercov`), at the same version, and the source is
+on crates.io (`cargo install supercov`). The first invocation may download
+Supercov from the registry. Supercov itself does not upload your source or
+coverage evidence to a Supercov service.
 
 ## Files and cleanup
 
@@ -138,7 +126,7 @@ workspace for instrumented builds. These files are local and ignored by Git.
 Supercov does not rewrite your source, tests, imports, runner configuration,
 dependencies, or ordinary build output.
 
-```sh
+```sh supercov
 npx supercov clean --dry-run   # preview what would be removed
 npx supercov clean --keep 20   # keep the 20 newest runs
 npx supercov clean             # remove all runs and the build cache

package/docs/performance.md

@@ -6,7 +6,7 @@ the isolated build when the relevant inputs have not changed.
 
 ## See where the time went
 
-```sh
+```sh supercov
 npx supercov runs latest
 ```
 
@@ -42,7 +42,7 @@ possible mismatch triggers a fresh build rather than risking stale coverage.
 
 A narrow test command can shorten the inner loop:
 
-```sh
+```sh supercov
 npx supercov -- npx vitest run app/checkout/session.test.ts
 ```
 
@@ -54,7 +54,7 @@ baseline.
 
 Compare the original and wrapped command under similar cache conditions:
 
-```sh
+```sh supercov
 /usr/bin/time -p npm test
 /usr/bin/time -p npx supercov -- npm test
 ```
@@ -73,7 +73,7 @@ than stored as a full report for every filter.
 The isolated workspace may be larger because it can contain an instrumented
 build cache. Supercov does not delete history in the background.
 
-```sh
+```sh supercov
 npx supercov clean --dry-run
 npx supercov clean --keep 20
 npx supercov clean