supercov 0.0.26 → 0.0.27

package/docs/cli.md

@@ -1,18 +1,34 @@
 # CLI reference
 
-Supercov runs locally. No command uploads source or coverage evidence.
+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
 npx supercov --help
 ```
 
+## Quick reference
+
+| Goal | Command |
+| --- | --- |
+| Measure a suite | `npx supercov -- <test command>` |
+| List recent runs | `npx supercov runs` |
+| 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>` |
+| Compare two runs | `npx supercov diff <older> <newer>` |
+| Combine shards | `npx supercov merge <id> <id> [...]` |
+| Remove local data | `npx supercov clean` |
+| Read bundled guides | `npx supercov docs` |
+
 ## Measure a test command
 
 ```sh
 npx supercov -- <test command>
 ```
 
-Everything after `--` is the command Supercov measures.
+Everything after `--` is passed to the test command:
 
 ```sh
 npx supercov -- npm test
@@ -21,42 +37,45 @@ npx supercov -- cargo test
 npx supercov -- cargo nextest run
 ```
 
-A coverage run exits with the test command's own status, so the wrapped command
-can remain a CI gate.
+Use the complete command you rely on before merging or deploying. A coverage run
+preserves the wrapped command's exit status, so it can remain a CI gate.
 
-## List runs
+## List and select runs
 
 ```sh
-npx supercov runs [--limit N] [--json]
+npx supercov runs
+npx supercov runs --limit 5
+npx supercov runs latest
+npx supercov runs <run-id>
 ```
 
-Runs are listed newest first. Use an immutable run id when work spans a session;
-use `latest` for interactive work.
+Runs are listed newest first. `latest` is convenient during an interactive
+loop. Use the immutable run id in automation, review notes, and work that spans
+sessions.
 
-## Query one run
+## Query a run
 
 ```sh
 npx supercov runs <run-id> [query] [options]
 ```
 
-| Query | What it answers |
+| Query | Use it to |
 | --- | --- |
-| no query | Overall completeness and measurement limits |
-| `kinds` | Coverage by semantic level, such as unit or E2E |
-| `runners` | Coverage by test runner |
-| `scope` | Included, excluded, and ambiguous source files |
-| `files` | All included files, ranked |
-| `gaps` | Files with useful open obligations or measurement limits |
-| `file <path>` | Open obligations in one file |
-| `decision <id \| path:line>` | Observed decision vectors and missing witnesses |
-| `line <path:line>` | Line state, nested obligations, and covering tests |
-| `test <id \| name>` | What one test contributes |
-| `minimize` | The smallest test subset that preserves selected coverage |
+| no query | Read the overall result, test outcome, completeness, and timings |
+| `gaps` | See only files with uncovered behavior or measurement limits |
+| `files` | See every included file, including fully covered files |
+| `file <path>` | Inspect the open obligations in one file |
+| `decision <id \| path:line>` | Understand missing boolean outcomes and MC/DC witnesses |
+| `line <path:line>` | See one line's state, obligations, and covering tests |
+| `test <id \| name>` | See the coverage attributed to one test |
+| `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 |
+| `minimize` | Find a small test subset that preserves a coverage target |
 
 Common examples:
 
 ```sh
-npx supercov runs latest
 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
@@ -64,38 +83,70 @@ npx supercov runs latest line app/routes/checkout.ts:57
 npx supercov runs latest test "checkout retry"
 ```
 
-## Query options
+Run any query with `--help` to see only the options valid for that query:
+
+```sh
+npx supercov runs latest --help
+npx supercov runs latest file --help
+```
+
+## Narrow a view
 
 | Option | Meaning |
 | --- | --- |
-| `--filter all \| passed \| failed` | Choose which test attempts contribute. `all` is the default. |
-| `--kind <kind>` | Restrict to a test level such as `unit`, `integration`, or `e2e`. |
-| `--runner <runner>` | Restrict a summary to one runner. |
-| `--limit N`, `--offset N` | Page through collection results. |
-| `--metric all \| lines \| statements \| functions \| branches \| mcdc` | Choose the obligations preserved by `minimize`. |
-| `--target 0..100` | Stop `minimize` when the selected metric reaches the target. |
-| `--json` | Return the stable machine-readable form when an integration needs it. |
+| `--filter all \| passed \| failed` | Recalculate the view from all, successful, or failed attempts |
+| `--kind <kind>` | Restrict to a test level such as `unit`, `integration`, or `e2e` |
+| `--runner <runner>` | Restrict to one runner |
+| `--metric all \| lines \| statements \| functions \| branches \| mcdc` | Choose a metric for `files`, `gaps`, `diff`, or `minimize` |
+| `--limit N`, `--offset N` | Page through a collection |
+| `--json` | Return the machine-readable form |
 
-Collections print a copyable next-page command. Ordinary text output is intended
-to work well for both people and coding agents.
+Collection output includes a copyable command for the next page.
+
+For a large file, group and rank its decisions:
+
+```sh
+npx supercov runs latest file app/routes/checkout.ts \
+  --group decision --sort missing
+```
 
 ## Compare runs
 
 ```sh
-npx supercov diff <older-run> <newer-run> [--limit N] [--json]
+npx supercov diff <older-run> <newer-run>
 ```
 
-`diff` shows both gains and losses. Neither input run is changed.
+`diff` reports gains and losses. Use it after adding a test to prove that the
+expected behavior became covered without an unexplained regression elsewhere.
+Neither input run is changed.
 
-## Merge shards
+The same filters can focus a comparison:
 
 ```sh
-npx supercov merge <run-id> <run-id> [...]
+npx supercov diff <older-run> <newer-run> --kind e2e
 ```
 
-`merge` creates a new run from compatible shards. If source, configuration,
-toolchain, schema, or denominator fingerprints differ, it fails clearly rather
-than producing an invalid aggregate.
+## Find a smaller test set
+
+```sh
+npx supercov runs latest minimize
+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
+analysis aid, not permission to remove tests that protect behavior outside the
+selected metric.
+
+## Combine shards
+
+```sh
+npx supercov merge <shard-a> <shard-b> <shard-c>
+```
+
+Merge creates a new run. The inputs must describe the same source,
+configuration, toolchain, schema, and coverage denominator. Supercov rejects an
+incompatible merge rather than publishing a misleading aggregate.
 
 ## Clean local data
 
@@ -106,27 +157,38 @@ npx supercov clean
 ```
 
 By default, `clean` removes all stored runs and the isolated build cache.
-`--keep N` preserves the newest N runs. Cleanup only removes marker-owned
-Supercov storage.
+`--keep N` keeps the newest N runs. Cleanup removes only marker-owned Supercov
+storage.
 
 ## Read bundled documentation
 
 ```sh
 npx supercov docs
 npx supercov docs getting-started
+npx supercov docs troubleshooting
 ```
 
+The guides are installed with the package, so they remain available in a
+terminal or offline environment after the package has been downloaded.
+
 ## Environment variables
 
 | Variable | Use |
 | --- | --- |
-| `SUPERCOV_SOURCE_ROOTS` | Declare the authoritative first-party source roots when automatic scope is ambiguous. |
-| `SUPERCOV_TEST_KIND` | Declare the semantic level of the tests in the wrapped command. |
+| `SUPERCOV_SOURCE_ROOTS` | Set comma-separated first-party source roots when automatic discovery is ambiguous |
+| `SUPERCOV_TEST_KIND` | Label the wrapped command as a test level such as `unit` or `e2e` |
+
+Examples:
+
+```sh
+SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
+SUPERCOV_TEST_KIND=e2e npx supercov -- npx playwright test
+```
 
 ## Exit codes
 
 | Code | Meaning |
 | --- | --- |
-| `0` | The run or query succeeded. |
-| Test command's status | A coverage run preserves the wrapped command's exit status. |
-| `2` | Supercov itself could not complete the request. |
+| `0` | The command or query succeeded |
+| Wrapped command's code | The test command failed and Supercov preserved its status |
+| `2` | Supercov could not complete the request |

package/docs/coverage-model.md

@@ -1,51 +1,95 @@
-# Coverage model
+# Understanding coverage
 
-Supercov turns source structure into a fixed set of obligations before the test
-run. Tests can cover those obligations, but they cannot silently change what
-100% means.
+Supercov answers a more useful question than “which lines ran?” It shows which
+behaviors were exercised, which paths still need a test, and where measurement
+was incomplete.
+
+## Gaps and measurement limits are different
+
+An **uncovered gap** is behavior Supercov measured but did not observe. A test
+may be able to close it.
+
+A **measurement limit** means Supercov could not establish a complete boundary
+for some code or execution. Common causes include ambiguous source scope,
+dynamically created source, self-inspecting code, and an unsupported process or
+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
+npx supercov runs latest
+npx supercov runs latest gaps
+npx supercov runs latest scope
+```
 
 ## What Supercov measures
 
-| Obligation | Question |
+| Metric | The question it answers |
 | --- | --- |
 | Line | Did execution reach this source line? |
 | Statement | Did this executable statement run? |
 | Function | Was this function entered? |
 | Branch | Did each alternative execute? |
-| Decision vector | Which combinations of conditions were observed? |
-| MC/DC witness | Was each condition shown to affect its decision independently? |
-| Value path | Did language constructs such as defaults, optional chains, and logical assignments take each meaningful path? |
+| Decision vector | Which combinations of boolean conditions occurred? |
+| MC/DC witness | Was each condition shown to affect the decision independently? |
+| Value path | Did defaults, optional chains, logical assignments, and similar constructs take each meaningful path? |
 
-The exact obligations depend on the language and source construct. Query one
-file or decision to see the concrete missing behavior:
+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
 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
 ```
 
-## Why a line percentage is not enough
+## Why line coverage is not enough
 
-A line can execute while an important outcome remains untested. For example,
-this decision has two conditions:
+Consider:
 
 ```js
 if (user.isAdmin || user.ownsDocument) allowEdit();
 ```
 
-Executing the line proves very little by itself. Useful tests should show the
-admin condition matters, the ownership condition matters, and the denied path
-still works. Decision-vector and MC/DC queries expose the missing cases directly.
+The line can run even if the suite never proves that administrators are allowed,
+owners are allowed, and everyone else is denied. Branches, decision vectors, and
+MC/DC expose those missing cases instead of treating one executed line as proof
+that the decision is safe.
 
 The same principle applies to Rust boolean expressions and control flow.
 
-## Evidence confidence
+## What 100% means
+
+Supercov derives the coverage denominator from source structure before the test
+run. Adding or removing tests cannot silently change the definition of 100%.
+
+A complete result means every declared obligation was measured and covered. It
+does not mean the product has no bugs, the assertions are meaningful, or every
+possible input was tested. Review test quality and user-visible behavior, not
+only the percentage.
+
+If source cannot be measured safely, Supercov reports a measurement limit
+instead of claiming completeness.
 
-Where the runner exposes exact test boundaries, Supercov can show which test and
-attempt covered an obligation. Where it does not, execution is recorded as
-aggregate background evidence rather than assigned to a guessed test.
+## Exact and aggregate evidence
 
-Use attempt filters to choose the evidence included in a view:
+When a runner exposes test and attempt boundaries, Supercov can show which test
+covered an obligation. When it cannot, Supercov records aggregate background
+coverage without guessing which test caused it.
+
+Both are useful:
+
+- exact evidence helps you inspect or minimize individual tests;
+- aggregate evidence still shows whether the whole suite reached the source.
+
+See [Supported suites](supported-suites.md) for the attribution available from
+each runner.
+
+## Recalculate a view from selected tests
+
+The same stored run can answer different questions:
 
 ```sh
 npx supercov runs latest --filter all
@@ -53,32 +97,32 @@ npx supercov runs latest --filter passed
 npx supercov runs latest --filter failed
 ```
 
-Use `--kind` when the project distinguishes test levels:
+`all` matches the usual whole-run view. `passed` shows evidence from successful
+attempts. `failed` isolates failed attempts, including failed retries.
+
+You can also focus on a test level or runner:
 
 ```sh
 npx supercov runs latest gaps --kind e2e
+npx supercov runs latest gaps --runner playwright
 ```
 
-A filtered view recomputes obligations from the selected evidence. It does not
-filter a percentage that was already calculated from something else.
+These views are recalculated from stored evidence. Supercov is not filtering a
+percentage that was computed from a different set of tests.
 
-## Complete, uncovered, and blocked
+## Fix source scope before chasing gaps
 
-An ordinary uncovered obligation can be closed by a test. A completeness
-blocker means Supercov cannot honestly claim the source was fully measured.
-Common blockers are:
+If the summary reports ambiguous source scope, inspect it:
 
-- ambiguous first-party source scope;
-- source that must remain uninstrumented because code observes its own text;
-- dynamically created source without a stable pre-run denominator; and
-- execution that crossed an unsupported or unattributed runner boundary.
+```sh
+npx supercov runs latest scope
+```
 
-Inspect source scope with:
+When first-party source lives in unusual directories, declare it explicitly:
 
 ```sh
-npx supercov runs latest scope
+SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
 ```
 
-If automatic scope is ambiguous, declare the authoritative roots with
-`SUPERCOV_SOURCE_ROOTS`. Other blockers remain visible with their location and
-reason. Supercov does not round them away to produce a comfortable 100%.
+Choose roots that describe code the repository owns. Do not include dependencies
+or generated output merely to make a warning disappear.

package/docs/evidence.md

@@ -1,43 +1,49 @@
-# Evidence and runs
+# Runs and evidence
 
-Every completed Supercov run is an immutable local record of what the suite
-executed. Queries, comparisons, and filtered views are derived from that record.
+Every completed Supercov run is a local snapshot of what the suite executed.
+You can return to it, ask different questions, or compare it with a later run
+without rerunning the tests.
 
-## What a run contains
+## Find the run you want
 
-A run records:
+```sh
+npx supercov runs
+npx supercov runs --limit 10
+npx supercov runs latest
+```
+
+Use `latest` during an interactive loop. Use the printed run id when:
 
-- the fixed coverage denominator for the measured source;
-- observed lines, statements, functions, branches, and decision vectors;
-- test, attempt, runner, outcome, and phase identity where the runner exposes it;
-- source, test, dependency, configuration, toolchain, and schema fingerprints;
-- completeness blockers and unattributed background execution; and
-- phase timings and integrity information.
+- a task spans more than one session;
+- an automated worker must not race a newer run;
+- you are recording evidence in a pull request; or
+- you need a reproducible comparison later.
 
-Completed runs live under `.supercov/runs/<run-id>/`. The original evidence is
-not rewritten when you query it. Supercov may build a disposable local index to
-answer later queries faster; that index is derived data and can always be
-recreated from the immutable run.
+A run id is immutable. `latest` is only a convenient selector.
 
-## Read a run
+## Ask the same run different questions
 
 ```sh
-npx supercov runs --limit 10
-npx supercov runs latest
 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
 ```
 
-Use `latest` while working interactively. Use the run id printed by `runs` for
-automation, review notes, and work that spans sessions.
+These queries read stored evidence. They do not run the test suite again or
+rewrite the original run. Supercov may create a disposable local index to make
+later queries faster; it can rebuild that index from the run.
+
+## Understand stale runs
 
-Queries compare the stored fingerprint with the current workspace. A stale run
-remains valid history, but it is no longer presented as a description of the
-current source.
+Supercov compares a stored run with the current workspace. If relevant source,
+tests, dependencies, configuration, or toolchain inputs changed, the run is
+marked stale.
 
-## Filter attempts
+A stale run is still valid history. It simply should not be presented as the
+current state of the repository. Run the complete suite again before choosing
+new work from it.
 
-The same run can answer different questions without rerunning the suite:
+## Focus on passed or failed attempts
 
 ```sh
 npx supercov runs latest --filter all
@@ -45,46 +51,54 @@ npx supercov runs latest --filter passed
 npx supercov runs latest --filter failed
 ```
 
-- `all` includes every executed attempt and matches conventional coverage tools.
-- `passed` includes successful attempts of tests that ultimately passed.
+- `all` includes every executed attempt and matches the normal whole-run view.
+- `passed` uses successful attempts from tests that ultimately passed.
 - `failed` isolates failed attempts, including failed retries of flaky tests.
 
-Filtered views are recomputed from the stored evidence. They are not separate
-report files that can drift apart.
+The views are recalculated from the same stored evidence. They are not separate
+reports that can drift apart.
 
-## Compare two runs
+## Compare before and after
 
 ```sh
 npx supercov diff <older-run> <newer-run>
 ```
 
-The diff shows newly covered and newly uncovered obligations. It is the easiest
-way to prove that a focused test changed coverage without losing behavior
-elsewhere.
+The diff shows both newly covered and newly uncovered obligations. Use it after
+a focused test to answer:
+
+1. Did the expected behavior become covered?
+2. Did anything unexpectedly become uncovered?
+3. Did the source boundary or measurement completeness change?
+
+Keep the compared run ids in the agent summary or pull request when someone may
+need to reproduce the result.
 
-## Combine shards
+## Combine distributed shards
 
 ```sh
-npx supercov merge <shard-a> <shard-b> [...]
+npx supercov merge <shard-a> <shard-b> <shard-c>
 ```
 
-Merge creates a new immutable run. Shards must have matching source,
-configuration, toolchain, schema, and denominator fingerprints. Input runs are
-never changed.
+Merge creates a new run and leaves the inputs unchanged. Shards must describe
+the same source, configuration, toolchain, schema, and coverage denominator.
+Supercov rejects incompatible inputs rather than producing a misleading total.
 
-## Integrity and incomplete evidence
+## What a run remembers
 
-Supercov validates evidence before publishing a run. Corrupt, truncated,
-duplicated, or contradictory input is rejected or surfaced as an explicit
-measurement limit. It is never silently converted into a clean percentage.
+A run contains the coverage denominator, observed obligations, test and runner
+identity where available, test outcomes and attempts, source and configuration
+identity, measurement limits, and phase timings.
 
-Likewise, ambiguous source scope, uninstrumented code, and execution without a
-reliable test identity remain visible. See [Coverage model](/docs/coverage-model)
-for how these states affect completeness.
+That is enough to answer later queries while keeping the original evidence
+immutable. Corrupt, truncated, stale, or incompatible data is surfaced as such;
+it is not opened as a plausible clean report.
 
-## Retention
+## Storage and retention
 
-Runs remain until you remove them:
+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
 npx supercov clean --dry-run
@@ -92,5 +106,6 @@ npx supercov clean --keep 20
 npx supercov clean
 ```
 
-Cleanup takes the same project lock as a coverage run and removes only
+Preview cleanup first. The final command removes all runs and the isolated build
+cache; `--keep 20` preserves the 20 newest runs. Cleanup removes only
 marker-owned Supercov data.