supercov 0.0.16 → 0.0.18

package/README.md

@@ -7,6 +7,17 @@ suites.
 npx supercov -- npm test
 ```
 
+For coding agents, put the same rule in the repository instructions they read
+before running commands (for example `AGENTS.md` or `CLAUDE.md`):
+
+```md
+Measure coverage with `npx supercov -- npm test`. Prefix the project's full
+test command; do not substitute a single unit, integration, or E2E script.
+```
+
+`npx supercov --help` explains the full-command rule, and
+`npx supercov docs agent-loop` prints the bounded query workflow as Markdown.
+
 For local development before publication, a Supercov contributor can expose
 the checkout globally. Consumer repositories still remain untouched:
 
@@ -141,8 +152,9 @@ Use `--filter passed` for verified coverage from successful attempts of
 ultimately passing tests, or `--filter failed` to inspect only execution from
 failed attempts (including failed retries of flaky tests). Evidence records
 attempt status and classify each test as passed, failed, flaky, skipped, timed
-out, interrupted, or unknown. Passed and failed views are derived from the
-same immutable archive rather than duplicated into presentation files.
+out, interrupted, unknown, or selected but unstarted after fail-fast. Passed
+and failed views are derived from the same immutable archive rather than
+duplicated into presentation files.
 
 The run ID is positional because all coverage queries operate on one immutable
 run. `latest` is a convenience selector for interactive use. Every query
@@ -191,12 +203,13 @@ configuration, instrumenter, schema, and denominator fingerprints. It rewrites
 the run scope inside every evidence record, namespaces shard paths, publishes a
 new immutable run atomically, and leaves all input runs untouched. This is the
 distributed/multi-host primitive; incompatible shards fail clearly instead of
-producing a plausible but invalid aggregate.
+producing a plausible but invalid aggregate. A rejection names each exact
+domain that differs instead of presenting a generic list of possibilities.
 
 For a JavaScript or TypeScript project, the CLI:
 
 1. refreshes a stable isolated source namespace under
-   `.supercov/cache/workspace/<project>/`, links the existing
+   `supercov/workspace/<project>/`, links the existing
    dependency tree, and creates generated runner configuration and build output
    only there; file data uses copy-on-write reflinks where the filesystem
    supports them, and falls back to copying where it does not; the stable path
@@ -229,9 +242,10 @@ For a JavaScript or TypeScript project, the CLI:
    rebuilt afterward.
 
 Only the Supercov-owned `.supercov/` run store and marker-protected
-`.supercov/cache/workspace/` cache are modified in the user's checkout. A user-created
-`supercov/` directory without Supercov's ownership marker is never treated as
-storage. A per-project lock rejects overlapping runs before either can build. Run state is durably written
+`supercov/workspace/` cache are modified in the user's checkout. A user-created
+`supercov/` directory without Supercov's ownership marker remains ordinary
+project source; Supercov selects a deterministic non-dotted fallback container
+instead. A per-project lock rejects overlapping runs before either can build. Run state is durably written
 through preparing/building/testing/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

package/bin/supercov.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 
 import { spawn } from "node:child_process";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { resolveNativeBinary } from "./native.js";
 
 let rustBinary;
@@ -15,10 +17,17 @@ const child = spawn(
   process.argv.slice(2),
   {
     stdio: "inherit",
-    env: process.env,
+    env: {
+      ...process.env,
+      SUPERCOV_PACKAGE_ROOT: resolvePackageRoot(),
+    },
   },
 );
 
+function resolvePackageRoot() {
+  return dirname(dirname(fileURLToPath(import.meta.url)));
+}
+
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
   process.once(signal, () => {
     try {

package/docs/agent-loop.md

@@ -0,0 +1,157 @@
+# Agent loop
+
+Use Supercov in a repeatable agent loop: run the suite, query uncovered
+obligations, add a focused test, rerun, and compare results. This page covers
+the loop, the recommended prompt, and failure handling.
+
+## The shape of the loop
+
+```text
+run the suite  ->  ask what is open  ->  write one test  ->  re-run  ->  diff
+      ^                                                                   |
+      +-------------------------------------------------------------------+
+```
+
+Each pass should close a small number of related obligations and end with
+evidence that it did. An agent that writes ten tests before re-running has no
+way to attribute the outcome; an agent that re-runs after every trivial edit
+spends its budget on test execution instead of thinking.
+
+## One pass, in commands
+
+```sh
+# 1. Establish a baseline. Only needed once per session.
+npx supercov -- npm test
+
+# 2. Orient without loading a report into context.
+npx supercov runs latest --json
+npx supercov runs latest gaps --limit 5 --json
+
+# 3. Understand one target.
+npx supercov runs latest file app/checkout/session.ts --json
+npx supercov runs latest decision app/checkout/session.ts:64 --json
+
+# 4. Check what already exercises that line, to avoid writing a duplicate.
+npx supercov runs latest line app/checkout/session.ts:64 --json
+
+# 5. Write one test. Then re-run and prove the gain.
+npx supercov -- npm test
+npx supercov diff <previous-run-id> latest --json
+```
+
+Step 4 is the one agents skip and should not. `line` answers "what already
+executes this line", which usually reveals either an existing test to extend or
+the exact reason nothing reaches it.
+
+## A prompt you can paste
+
+```text
+You are improving test coverage for this repository using Supercov.
+
+Baseline:
+  npx supercov -- npm test
+
+Then repeat this loop until coverage completeness stops improving, the target
+is met, or you run out of time:
+
+1. npx supercov runs latest gaps --limit 5 --json
+2. Pick the file with the highest-value open obligations.
+3. npx supercov runs latest file <path> --json
+   npx supercov runs latest decision <path>:<line> --json
+   npx supercov runs latest line <path>:<line> --json
+4. Write ONE focused test that closes the specific obligations you just read.
+   The assertion must be meaningful on its own; never assert something trivial
+   just to execute a line.
+5. npx supercov -- npm test
+6. npx supercov diff <previous-run-id> latest --json
+   If the diff shows no gain, revert the test rather than keeping it.
+
+Rules:
+- Never modify application source to make coverage easier.
+- Never weaken or delete an existing assertion.
+- If a decision cannot be reached from any public entry point, say so and move
+  on instead of exporting internals to reach it.
+- Report the run ids you compared and the obligations you closed.
+```
+
+The last rule matters more than it looks. An unattended agent that cannot reach
+a branch will otherwise start reshaping the code so it can, which is exactly
+the failure mode that gives coverage targets a bad name.
+
+## Budgeting an overnight session
+
+Test execution dominates the wall clock, so the number of passes is roughly the
+time budget divided by suite duration. Two adjustments help:
+
+- Narrow the command while iterating. `npx supercov -- npx vitest run
+  app/checkout` produces a valid run over a smaller denominator; use the full
+  suite for the baseline and the final verification.
+- Let the build cache work. When the source, configuration and toolchain
+  fingerprint is unchanged, the instrumented build is reused and that phase
+  costs approximately nothing. Changing a dependency or a build config in the
+  middle of a session throws that away.
+
+## Choosing what to attack
+
+`gaps` is ordered to be useful, but not every open obligation deserves a test.
+For a project that prefers end-to-end evidence, start with the existing
+projection rather than inventing a new test taxonomy:
+
+```sh
+npx supercov runs latest gaps --kind e2e
+```
+
+Each file distinguishes obligations covered by another test kind from those
+uncovered everywhere. The former are candidates for stronger E2E coverage;
+the latter are gaps in the combined suite. When an error path cannot be reached
+through E2E, first check whether the test double can express that failure before
+falling back to a narrower unit test.
+
+Two queries help an agent argue about value rather than count:
+
+```sh
+# What does the suite prove today, minus redundancy?
+npx supercov runs latest minimize --filter passed
+
+# Reach a target with the smallest possible subset.
+npx supercov runs latest minimize --filter passed --metric mcdc --target 80
+```
+
+`minimize` is an exact branch-and-bound solver, not a greedy approximation: the
+subset it returns is a proved minimum. It refuses to answer for a view that
+contains background or unattributed evidence, because there is no honest way to
+name an exact subset of tests when the runner never exposed test boundaries.
+
+## Reading a run that is not the newest
+
+`latest` is a convenience for interactive use. An agent that resumes work later,
+or that compares across a session, should use the immutable run id:
+
+```sh
+npx supercov runs --limit 10 --json
+npx supercov runs run_0123456789abcdef gaps --json
+```
+
+Queries compare the stored fingerprint with the current workspace and mark a run
+stale when the code has moved on. Treat a stale run as history, not as a
+description of the working tree.
+
+## What to do about honest gaps
+
+Some obligations are open because the tooling says so, not because a test is
+missing:
+
+- **Background or unattributed evidence.** An unsupported runner, or work that
+  arrived without a carrier, is recorded under a first-class background scope.
+  It appears in the default all-attempt view and is excluded from per-test
+  passed-only coverage. Writing more tests will not move it; adding runner
+  support will.
+- **Ambiguous source scope.** A candidate file that Supercov could not
+  confidently classify as first-party blocks a complete verdict. Inspect with
+  `coverage scope` and set `SUPERCOV_SOURCE_ROOTS` to declare the authoritative
+  scope.
+- **Semantic-safety blockers.** A function whose source is coerced or reflected
+  on at runtime is left uninstrumented on purpose, and direct `eval` cannot have
+  a stable denominator at all. Both are recorded with their exact location.
+
+An agent should surface these rather than grind against them.

package/docs/cli.md

@@ -0,0 +1,145 @@
+# CLI reference
+
+Every command is local. Nothing is uploaded, and no command runs your test
+suite unless you ask it to.
+
+```sh
+supercov --help
+```
+
+## Creating a run
+
+```sh
+supercov -- <test command>
+```
+
+Everything after `--` is executed as written. Supercov propagates coverage
+through every Node child process the command launches, then publishes one
+immutable run.
+
+```sh
+npx supercov -- npm test
+npx supercov -- npx playwright test --project=chromium
+npx supercov -- npx vitest run app/checkout
+```
+
+A per-project lock rejects overlapping runs before either can build.
+
+## Listing runs
+
+```sh
+supercov runs [--limit N] [--json]
+```
+
+Runs are listed newest first with their id, duration, phase timings and
+integrity state. Use the id — not `latest` — when work spans a session.
+
+## Coverage queries
+
+All coverage queries take the form:
+
+```sh
+supercov runs <run-id> [query] [options]
+```
+
+`<run-id>` is positional because every coverage view belongs to exactly one
+immutable run. `latest` selects the newest local run.
+
+| Query | Answers |
+| --- | --- |
+| no query | Overall completeness for the selected view |
+| `kinds` | Completeness split by semantic level (`unit`, `e2e`, …) |
+| `runners` | Completeness split by executing runner |
+| `scope` | Which source files are included, excluded or ambiguous |
+| `files` | Every included source file, ranked |
+| `gaps` | Only files with unresolved obligations or measurement limits |
+| `file <path>` | Every open obligation in one file |
+| `decision <id \| path:line>` | Observed vectors and missing witnesses for one decision |
+| `line <path:line>` | Line state, nested obligations, covering tests, and phases |
+| `test <id \| name fragment>` | What one test contributes |
+| `minimize` | The smallest test subset that preserves coverage |
+
+### Options
+
+| Option | Applies to | Meaning |
+| --- | --- | --- |
+| `--filter all \| passed \| failed` | most queries | Which attempts contribute. `all` is the default and matches conventional tools. |
+| `--kind <kind>` | most queries | Restrict to a semantic level, for example `--kind e2e`. |
+| `--runner <runner>` | summary | Restrict to one executing runner, for example `--runner playwright`. |
+| `--metric all \| lines \| statements \| functions \| branches \| mcdc` | `minimize` | Which obligations the solver must preserve. |
+| `--target 0..100` | `minimize` | Stop once the metric reaches this level. |
+| `--limit N`, `--offset N` | collections | Pagination. Collections default to 20 items and print a copyable next-page command. |
+| `--json` | every query | The stable machine format. |
+
+### Examples
+
+```sh
+# Orient in a few lines.
+npx supercov runs latest
+npx supercov runs latest --filter passed
+npx supercov runs latest kinds
+
+# Find and open one target.
+npx supercov runs latest gaps --kind e2e --limit 10
+npx supercov runs latest file app/routes/example.ts
+npx supercov runs latest decision app/routes/example.ts:42
+npx supercov runs latest line app/routes/example.ts:57
+
+# Understand contribution and redundancy.
+npx supercov runs latest test "checkout retry"
+npx supercov runs latest minimize --filter passed
+npx supercov runs latest minimize --filter passed --metric mcdc --target 80
+```
+
+With `--kind`, gap and file queries additionally distinguish obligations covered
+only by other test levels from obligations uncovered everywhere. On a combined
+unit/E2E run, the default summary also prints the line count reached by other
+test kinds but not by E2E, followed by the exact `gaps --kind e2e` query.
+
+## Comparing runs
+
+```sh
+supercov diff <older-run> <newer-run> [--limit N] [--json]
+```
+
+Reports what the newer run covers that the older one did not, and what it lost.
+Both runs remain untouched.
+
+## Combining shards
+
+```sh
+supercov merge <run-id> <run-id> [...]
+```
+
+Accepts only runs with identical source, test, dependency, configuration,
+instrumenter, schema and denominator fingerprints. It rewrites the run scope
+inside every evidence record, namespaces shard paths, and publishes a new
+immutable run atomically. Input runs are never modified. Incompatible shards
+fail clearly rather than producing a plausible but invalid aggregate; the
+error names each exact fingerprint domain that differs.
+
+## Retention
+
+```sh
+supercov clean [--keep N] [--dry-run]
+```
+
+`clean` removes all history and the isolated build workspace by default.
+`--keep N` preserves the N newest runs. It never runs automatically, takes the
+same lock as a coverage run, refuses to race an active run, and deletes only
+exactly marker-owned Supercov storage.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `SUPERCOV_SOURCE_ROOTS` | Declares the authoritative first-party source scope, resolving ambiguity that would otherwise block a complete verdict. |
+| `SUPERCOV_TEST_KIND` | Declares the semantic level of the tests in this command, overriding every inference. |
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | The run or query succeeded. |
+| The test command's own code | A coverage run exits with the status of your command, so `supercov -- npm test` remains usable as a CI gate. |
+| `2` | Supercov itself failed: an unknown command, an unreadable run, an incompatible merge, or a lock conflict. |

package/docs/coverage-model.md

@@ -0,0 +1,134 @@
+# 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.
+
+## Obligations
+
+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 |
+| --- | --- |
+| 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%.

package/docs/evidence.md

@@ -0,0 +1,122 @@
+# Evidence and runs
+
+Each run stores one evidence artifact and its metadata. Reports, queries, and
+comparisons are derived from those files on demand.
+
+## What a run is
+
+```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
+```
+
+Two files. No HTML, no derived report, no query cache. 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.
+
+Run ids are UTC timestamps, which makes them sort chronologically and makes
+retention deterministic.
+
+## Derived, never stored
+
+Every coverage view — the summary, per-file rankings, gap lists, decision
+detail, per-test contribution, the minimizer, and the passed and failed filters
+— is reconstructed from the archive when you ask for it. Nothing is written back.
+
+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: the stored schema is the raw evidence, not a rendering of it.
+
+Fresh-process summary, files and gaps queries take roughly two tenths of a
+second on the reference run described in [Performance](/docs/performance).
+
+## Integrity and staleness
+
+Each run stores SHA-256 fingerprints for:
+
+- first-party source
+- test files
+- dependency lockfiles
+- test and build configuration
+- the instrumenter itself
+
+plus the evidence schema version and the Git revision and dirty state at the
+time of the run.
+
+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.
+
+## Comparing 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.
+
+## Merging shards
+
+```sh
+npx supercov merge <first-run-id> <second-run-id> [...]
+```
+
+`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
+
+Everything that can be interrupted is written to survive it.
+
+- 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.
+
+The published `run.json` is the durable terminal record, so terminal work state
+is not retained after publication.
+
+## Retention
+
+```sh
+npx supercov clean
+npx supercov clean --keep 20 --dry-run
+npx supercov clean --keep 20
+```
+
+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.