supercov 0.0.21 → 0.0.23

package/docs/coverage-model.md

@@ -1,134 +1,84 @@
 # Coverage model
 
-Supercov derives coverage obligations from code structure. It reports which
-obligations ran and the quality of the available evidence, including line,
-branch, value-path, control-flow, and MC/DC 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.
 
-## Obligations
+## What Supercov measures
 
-An obligation is one thing the code structure requires a test to demonstrate.
-The denominator is fixed before the run from the source itself, so a percentage
-cannot drift when tests are added or removed.
-
-| Family | Obligation |
-| --- | --- |
-| Lines | Each executable line executes |
-| Statements | Each statement executes |
-| Functions | Each function is entered |
-| Branches | Each alternative is taken: `true`, `false`, switch fallthrough, and the implicit no-match arm |
-| MC/DC | Each atomic condition is shown to independently determine its decision |
-| Value selection | Optional-chain short-circuits, logical assignments, and parameter or destructuring defaults each resolve both ways |
-| Control flow | `try` versus `catch`, and zero-iteration versus entered `for-in` / `for-of` |
-
-The value-selection and control-flow families are the ones most tools omit.
-`a?.b`, `x ??= y` and `function f(a = 1)` each hide a decision that never
-appears as a branch in a conventional report, and a `for-of` that never runs
-with an empty collection is an untested path even though every line inside it
-is green.
-
-## MC/DC in one example
-
-Modified condition/decision coverage asks more than "was this condition true and
-false at some point". It asks whether each condition was shown to *independently
-change the outcome*, which requires a pair of executions differing in that one
-condition and producing different decisions.
-
-For `isAdmin || (total > limit && !locked)`:
-
-| Vector | `isAdmin` | `total > limit` | `!locked` | Decision |
-| --- | --- | --- | --- | --- |
-| v1 | F | T | T | true |
-| v2 | F | F | T | false |
-| v3 | F | T | F | false |
-| v4 | T | F | T | true |
-
-- v1 and v2 differ only in `total > limit` and disagree, so that condition is
-  proven.
-- v1 and v3 do the same for `!locked`.
-- v4 and v2 do the same for `isAdmin`.
-
-Remove v2 and two of the three proofs collapse, even though every condition has
-still been observed both true and false, and every line is still green. That is
-the gap MC/DC exists to catch, and it is why the criterion is required for the
-highest software assurance levels in avionics.
-
-Supercov stores **vector-level provenance**: which test produced each observed
-vector, not just which tests touched the decision. A filtered query therefore
-recomputes valid witness pairs for the tests it selected, rather than filtering
-a percentage computed for a different set. A witness assembled from one unit
-vector and one end-to-end vector counts for the combined suite and for neither
-level alone — and Supercov reports it that way.
-
-## Quality of evidence
-
-Not all coverage is equally convincing. Each line, branch alternative, vector
-and condition records how it was reached:
-
-| Level | Meaning |
+| Obligation | Question |
 | --- | --- |
-| Unexecuted | No evidence |
-| Executed | Reached during a test, with no explicit causal link |
-| Action-linked | Reached inside a recognised browser action such as `locator.click()` |
-| Assertion-linked | Reached inside an `expect()` matcher, or in the code path an assertion depends on |
-
-Only an explicit browser or server event can raise confidence to
-assertion-linked. Where Supercov has to fall back on timing correlation — an
-early cross-origin iframe probe, for example — the evidence stays
-execution-only and is labelled as such. Code reached outside a recognised
-action, such as setup work or a helper making its own HTTP requests, still has
-exact test attribution but may carry no action phase at all.
-
-In Playwright, the phase travels with the request: an action opened in the
-browser is still the active phase inside the server route it triggers, so a
-chain of `click → application decision → visible assertion` is queryable.
-
-## Provenance
-
-Every test carries two independent labels.
-
-**Runner** is the process that executed it — `playwright`, `vitest`, `jest`,
-`node`.
-
-**Kind** is its semantic level — `e2e`, `integration`, `component`, `unit`.
-Kind is resolved in descending confidence from an explicit `SUPERCOV_TEST_KIND`,
-then the Playwright project name, then the test path, then the runner default
-(Playwright is end-to-end, Vitest is unit). Queries preserve how the label was
-established, so an inferred kind is never presented as a declared one.
-
-Vitest module-import and setup execution is retained as a separate setup scope
-rather than being attributed to whichever test happened to run first.
-
-## Attempts and filters
-
-Evidence records attempt status, so a test is classified as passed, failed,
-flaky, skipped, timed out, interrupted, unknown, or selected but unstarted
-after fail-fast. `--filter` selects which attempts contribute to a view:
-
-- `all` — every executed attempt, including attempts that later failed. This is
-  the default and matches conventional coverage tools.
-- `passed` — successful attempts of tests that ultimately passed.
-- `failed` — failed attempts only, including failed retries of a flaky test.
-
-Passed and failed views are derived from the same immutable archive rather than
-duplicated into separate report files, so they cannot disagree.
-
-## When completeness is blocked
-
-A verdict is only useful if it refuses to be complete when it cannot be:
-
-- **Ambiguous scope.** Every candidate source file is retained as included,
-  excluded, or ambiguous. Ambiguity blocks a complete verdict and is
-  inspectable with `coverage scope`. Set `SUPERCOV_SOURCE_ROOTS` to declare the
-  authoritative scope.
-- **Semantic-safety blockers.** When application code coerces or observes a
-  function's own source, Supercov leaves that body uninstrumented and records
-  the blocker rather than transforming code whose text is being read.
-- **Unknowable denominators.** Direct `eval` and `Function` source cannot
-  receive a stable pre-run denominator. Their exact locations are recorded as
-  completeness blockers instead of being silently excluded.
-- **Unattributed evidence.** Execution that arrives without a carrier is stored
-  under a first-class background scope, visible in the all-attempt view and
-  excluded from per-test passed-only coverage.
-
-None of these are rounded away. A blocked verdict is more useful than a
-comfortable 100%.
+| 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? |
+
+The exact obligations depend on the language and source construct. Query one
+file or decision to see the concrete missing behavior:
+
+```sh
+npx supercov runs latest file app/checkout/session.ts
+npx supercov runs latest decision app/checkout/session.ts:64
+```
+
+## Why a line percentage is not enough
+
+A line can execute while an important outcome remains untested. For example,
+this decision has two conditions:
+
+```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 same principle applies to Rust boolean expressions and control flow.
+
+## Evidence confidence
+
+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.
+
+Use attempt filters to choose the evidence included in a view:
+
+```sh
+npx supercov runs latest --filter all
+npx supercov runs latest --filter passed
+npx supercov runs latest --filter failed
+```
+
+Use `--kind` when the project distinguishes test levels:
+
+```sh
+npx supercov runs latest gaps --kind e2e
+```
+
+A filtered view recomputes obligations from the selected evidence. It does not
+filter a percentage that was already calculated from something else.
+
+## Complete, uncovered, and blocked
+
+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:
+
+- 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.
+
+Inspect source scope with:
+
+```sh
+npx supercov runs latest scope
+```
+
+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%.

package/docs/evidence.md

@@ -1,127 +1,96 @@
 # Evidence and runs
 
-Each run stores one evidence artifact and its metadata. Reports, queries, and
-comparisons are derived from those files on demand.
+Every completed Supercov run is an immutable local record of what the suite
+executed. Queries, comparisons, and filtered views are derived from that record.
 
-## What a run is
+## What a run contains
 
-```text
-.supercov/runs/2026-08-24T01-25-11Z/
-  evidence.raw.gz   exact denominator manifest + raw per-worker and background evidence
-  run.json          fingerprints, phase timings, schema version, integrity state
-```
+A run records:
 
-Two durable source-of-truth files. No HTML or derived report is stored in the
-published run. Loose evidence written during the run is removed only after the
-whole run directory is atomically visible, so a run is either complete or
-absent.
+- 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.
 
-Run ids are UTC timestamps, which makes them sort chronologically and makes
-retention deterministic.
+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.
 
-## Derived views and their disposable cache
+## Read a run
 
-Every coverage view — the summary, per-file rankings, gap lists, decision
-detail, per-test contribution, the minimizer, and the passed and failed filters
-— is derived from the archive. The first query may write a disposable,
-integrity-bound query index beside the two durable files; later queries reuse
-it while the run identity remains valid. Delete that index at any time and
-Supercov reconstructs it from `evidence.raw.gz` without losing coverage data.
+```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
+```
 
-This is why `--filter passed` and `--filter all` can never contradict each
-other, and why a query added in a future version can answer questions about a
-run recorded today: raw evidence remains the source of truth, while the query
-index is only a rebuildable acceleration structure.
+Use `latest` while working interactively. Use the run id printed by `runs` for
+automation, review notes, and work that spans sessions.
 
-Fresh-process summary, files and gaps queries take roughly two tenths of a
-second on the reference run described in [Performance](/docs/performance).
+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.
 
-## Integrity and staleness
+## Filter attempts
 
-Each run stores SHA-256 fingerprints for:
+The same run can answer different questions without rerunning the suite:
 
-- first-party source
-- test files
-- dependency lockfiles
-- test and build configuration
-- the instrumenter itself
+```sh
+npx supercov runs latest --filter all
+npx supercov runs latest --filter passed
+npx supercov runs latest --filter failed
+```
 
-plus the evidence schema version and the Git revision and dirty state at the
-time of the run.
+- `all` includes every executed attempt and matches conventional coverage tools.
+- `passed` includes successful attempts of tests that ultimately passed.
+- `failed` isolates failed attempts, including failed retries of flaky tests.
 
-Queries compare the stored fingerprint against the current workspace and
-visibly mark a stale run. Evidence carrying a different run scope is rejected
-outright rather than merged in.
+Filtered views are recomputed from the stored evidence. They are not separate
+report files that can drift apart.
 
-## Comparing two runs
+## Compare two runs
 
 ```sh
 npx supercov diff <older-run> <newer-run>
-npx supercov diff <older-run> <newer-run> --json
 ```
 
-`diff` reports what the newer run covers that the older one did not, and what
-it lost. Both inputs are immutable and untouched, which is what makes the
-comparison meaningful: neither side can have been rewritten by the act of
-comparing them.
+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.
 
-## Merging shards
+## Combine shards
 
 ```sh
-npx supercov merge <first-run-id> <second-run-id> [...]
+npx supercov merge <shard-a> <shard-b> [...]
 ```
 
-`merge` accepts only runs whose source, test, dependency, configuration,
-instrumenter, schema and denominator fingerprints are identical. It rewrites
-the run scope inside every evidence record, namespaces shard paths, and
-publishes a new immutable run atomically. Input runs are never modified or
-deleted.
-
-This is the distributed and multi-host primitive. Incompatible shards fail with
-the exact differing fingerprint domains rather than producing a plausible but
-invalid aggregate — two shards built from different source trees do not have a
-common denominator, and no amount of arithmetic creates one.
-
-## Durability
+Merge creates a new immutable run. Shards must have matching source,
+configuration, toolchain, schema, and denominator fingerprints. Input runs are
+never changed.
 
-Everything that can be interrupted is written to survive it.
+## Integrity and incomplete evidence
 
-- Evidence archive, metadata and state writes use sibling temporary files,
-  `fsync`, and atomic rename.
-- Lock acquisition uses exclusive creation followed by `fsync`.
-- Run state is written durably through the preparing, building, testing and
-  publishing phases.
-- `SIGINT`, `SIGTERM` and `SIGHUP` are forwarded to the entire child process
-  group.
-- If the process is killed without a cleanup opportunity, the next invocation
-  marks the dead PID's run abandoned and refreshes the isolated namespace
-  before reusing it.
+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.
 
-The published `run.json` is the durable terminal record, so terminal work state
-is not retained after publication.
+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.
 
 ## Retention
 
+Runs remain until you remove them:
+
 ```sh
-npx supercov clean
-npx supercov clean --keep 20 --dry-run
+npx supercov clean --dry-run
 npx supercov clean --keep 20
+npx supercov clean
 ```
 
-Cleanup never runs automatically. `clean` removes explicit history, orphaned
-and terminal transient data, and the marker-owned build workspace; `--keep N`
-preserves the N newest runs. It acquires the same lock as a coverage run,
-refuses to race an active run, and never touches unowned paths.
-
-## Phase timings
-
-Every run records monotonic durations for initialization, workspace
-preparation, adapter setup, the instrumented build, your unchanged test command,
-and evidence publication. They are stored in `run.json` and returned by
-`supercov runs --json`.
-
-These are timings, not an overhead claim. A test script that performs its own
-build may overlap work with the instrumented-build phase, and true end-to-end
-overhead requires an explicit control run — which Supercov never performs
-automatically, because an arbitrary test command can write data or cost money.
-[Performance](/docs/performance) documents the comparison methodology.
+Cleanup takes the same project lock as a coverage run and removes only
+marker-owned Supercov data.

package/docs/getting-started.md

@@ -1,147 +1,121 @@
 # Getting started
 
-Supercov measures coverage for JavaScript, TypeScript, and Rust test suites.
-Prefix the command you already run; no config file, import, or reporter is
-required.
+Supercov gives a coding agent the next test to write. Run the test command you
+already use, ask which useful paths remain uncovered, add a focused test, and
+repeat.
 
 ```sh
 npx supercov -- npm test
 ```
 
-Everything after `--` is your command, executed exactly as written.
+No account, config file, import, custom reporter, or hosted service is required.
 
-## Requirements
+## Language support
 
-| Requirement | Detail |
-| --- | --- |
-| Node.js | 22 or newer |
-| Project | JavaScript or TypeScript, with a runnable test command |
-| Disk | A `.supercov/` directory in the project root, which Supercov creates |
+| Language | Status | Start with |
+| --- | --- | --- |
+| JavaScript | Available | `npx supercov -- npm test` |
+| TypeScript | Available | `npx supercov -- npm test` |
+| Rust | Available | `npx supercov -- cargo test` |
+| Python | Coming soon | — |
+| Zig | Coming soon | — |
+| PHP | Coming soon | — |
+| C | Coming soon | — |
 
-No Supercov account or hosted service is required. During a coverage run, the
-Supercov CLI does not contact a Supercov service and no part of your source or
-evidence leaves the machine. Package tools such as `npx` may still contact the
-npm registry to resolve or download Supercov when it is not already cached.
+More languages are planned. See [Supported suites](/docs/supported-suites) for
+the runners and attribution available today.
 
-## Your first run
+## Requirements
 
-From the project root:
+- Node.js 22 or newer. The current CLI is distributed through npm, including
+  when it measures a Rust project.
+- A working test command for the project.
+- For Rust, the Rust 1.95 toolchain. `cargo test` is supported directly;
+  `cargo nextest run` is supported with cargo-nextest 0.9.138 or 0.9.140.
 
-```sh
-npx supercov -- npm test
-```
+Package tools such as `npx` may contact the npm registry to download Supercov
+when it is not cached. The Supercov CLI does not contact a Supercov service
+during a coverage run, and your source and evidence stay on your machine.
 
-The run prints its phases as it goes — initialization, workspace preparation,
-adapter setup, the instrumented build, your unchanged test command, and
-evidence publication — and finishes by publishing one immutable run under
-`.supercov/runs/<run-id>/`. The run id is a UTC timestamp, so run ids sort
-chronologically.
+## Run the complete suite
 
-If the command you normally use is not `npm test`, use that instead:
+Everything after `--` is your test command. Use the same command you trust
+before merging or deploying:
 
 ```sh
+# JavaScript or TypeScript
+npx supercov -- npm test
 npx supercov -- npx playwright test
 npx supercov -- pnpm test:e2e
-npx supercov -- npm run test:unit && npx supercov -- npm run test:e2e
+
+# Rust
+npx supercov -- cargo test
+npx supercov -- cargo nextest run
 ```
 
-A single Supercov run can collect several runners. Coverage from a command that
-launches Vitest and Playwright ends up in one run, with each test labelled by
-the runner that executed it.
+If one command launches several supported runners, Supercov combines their
+evidence into one run.
 
-## Read the result
+## Find the next test
 
-Start with the summary, then narrow. Every query names one run; `latest`
-selects the newest local run.
+Start broad, then open one useful target:
 
 ```sh
-# What runs exist?
-npx supercov runs --limit 5
-
-# How complete is the newest one?
 npx supercov runs latest
-
-# Which files hold the most open obligations?
 npx supercov runs latest gaps --limit 10
-
-# What exactly is open in one file?
 npx supercov runs latest file app/checkout/session.ts
+npx supercov runs latest decision app/checkout/session.ts:64
 ```
 
-Output is written for an agent reading a terminal: short, paginated, and
-carrying a copyable next-page command. Add `--json` to any query for the stable
-machine format.
+The output is short and paginated so a coding agent can use it directly. Add
+`--json` only when a tool specifically needs machine-readable output.
 
-## Add a test and prove it landed
+## Add a test and prove the gain
 
-Write a test the normal way, then re-run and compare:
+Write one focused test, rerun the same complete command, and compare the two
+runs:
 
 ```sh
 npx supercov -- npm test
 npx supercov diff <previous-run-id> latest
 ```
 
-`diff` reports what the newer run covers that the older one did not. To check
-one specific test's contribution rather than the whole run:
+For Rust, rerun the same `cargo test` or `cargo nextest run` command you used
+for the baseline.
 
-```sh
-npx supercov runs latest test "rejects a locked order"
-```
-
-## What Supercov writes
+## Give the loop to an agent
 
-Supercov owns two marker-protected locations inside your project:
+Paste this into any coding agent that can run terminal commands:
 
 ```text
-.supercov/
-  runs/<run-id>/evidence.raw.gz   exact denominator manifest + raw evidence
-  runs/<run-id>/run.json          fingerprints, phase timings, integrity
-supercov/
-  workspace/<project>/            isolated build namespace, reused between runs
-```
+Use `npx supercov` to improve coverage. Only write tests. Keep going while
+useful gaps remain.
 
-Your source files, test files, runner configuration and ordinary build output
-are never modified, overwritten or rebuilt. Both owned locations carry their
-own gitignore; an existing user `supercov/` directory is never adopted.
+Run the repository's complete test command through Supercov. Use
+`npx supercov runs latest gaps --limit 5` to choose one useful target. Write
+one focused test, rerun the complete suite, and verify the gain with
+`npx supercov diff <previous-run-id> latest`.
 
-Storage is bounded by you, not by a background process:
-
-```sh
-npx supercov clean                      # remove every stored run and build cache
-npx supercov clean --keep 20            # retain the 20 newest runs
-npx supercov clean --keep 20 --dry-run  # show what would be removed
+Never weaken assertions or change application code to make coverage easier.
+Stop when no useful gaps remain.
 ```
 
-## Choosing what counts
+## Local files and cleanup
 
-Two options change the meaning of a number rather than its presentation, so
-they are worth knowing early.
+Completed runs live under `.supercov/runs/`. Supercov also maintains a
+marker-protected isolated workspace for instrumented builds. It does not rewrite
+your source, tests, imports, runner configuration, dependency tree, or ordinary
+build output.
 
-`--filter` selects which attempts contribute:
-
-- `all` (default) counts every executed attempt, including attempts that later
-  failed. This matches what conventional coverage tools report.
-- `passed` counts only successful attempts of tests that ultimately passed —
-  verified coverage.
-- `failed` counts only failed attempts, which is useful when diagnosing a flaky
-  test's real execution path.
-
-`--kind` selects a semantic test level such as `e2e`, `integration`,
-`component` or `unit`. Kind is resolved from an explicit `SUPERCOV_TEST_KIND`,
-then the Playwright project name, then the test path, then the runner default.
-Queries record how the label was established, so an inferred kind is never
-presented as one you declared.
-
-Filtered queries recompute every obligation from the selected tests instead of
-filtering an already-computed percentage. This matters most for MC/DC, where a
-witness pair assembled from one unit vector and one end-to-end vector counts for
-the combined suite but not for either level alone.
+```sh
+npx supercov clean --dry-run   # preview a full cleanup
+npx supercov clean --keep 20   # retain the 20 newest runs
+npx supercov clean             # remove all runs and the build cache
+```
 
-## Where to go next
+## Next
 
-- [Agent loop](/docs/agent-loop) — the unattended workflow this is designed for.
-- [CLI reference](/docs/cli) — every command and flag.
-- [Coverage model](/docs/coverage-model) — what an obligation is, and why the
-  denominator is larger than lines and branches.
-- [Supported suites](/docs/supported-suites) — where attribution is exact and
-  where it is aggregate.
+- [Agent loop](/docs/agent-loop) — a repeatable coverage workflow for coding agents.
+- [CLI reference](/docs/cli) — commands and filters.
+- [Coverage model](/docs/coverage-model) — what Supercov measures.
+- [Supported suites](/docs/supported-suites) — languages, runners, and current limits.