supercov 0.0.26 → 0.0.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +102 -90
  2. package/docs/agent-loop.md +78 -39
  3. package/docs/cli.md +108 -46
  4. package/docs/coverage-model.md +81 -37
  5. package/docs/evidence.md +63 -48
  6. package/docs/getting-started.md +75 -55
  7. package/docs/performance.md +53 -43
  8. package/docs/supported-suites.md +75 -57
  9. package/docs/troubleshooting.md +143 -0
  10. package/docs/verification.md +59 -45
  11. package/docs/workspace-isolation.md +59 -38
  12. package/package.json +7 -7
package/docs/getting-started.md CHANGED
@@ -1,46 +1,32 @@
1
1
  # Getting started
2
2
 
3
- Supercov gives a coding agent the next test to write. Run the test command you
4
- already use, ask which useful paths remain uncovered, add a focused test, and
5
- repeat.
3
+ Supercov turns the test suite you already have into a list of useful tests to
4
+ write next. Run the suite once, inspect a coverage gap, add a focused test, and
5
+ compare the result.
6
6
 
7
7
  ```sh
8
8
  npx supercov -- npm test
9
9
  ```
10
10
 
11
11
  No account, config file, import, custom reporter, or hosted service is required.
12
+ Supercov supports JavaScript, TypeScript, and Rust today.
12
13
 
13
- ## Language support
14
+ ## Before you start
14
15
 
15
- | Language | Status | Start with |
16
- | --- | --- | --- |
17
- | JavaScript | Available | `npx supercov -- npm test` |
18
- | TypeScript | Available | `npx supercov -- npm test` |
19
- | Rust | Available | `npx supercov -- cargo test` |
20
- | Python | Coming soon | — |
21
- | Zig | Coming soon | — |
22
- | PHP | Coming soon | — |
23
- | C | Coming soon | — |
16
+ You need:
24
17
 
25
- More languages are planned. See [Supported suites](/docs/supported-suites) for
26
- the runners and attribution available today.
18
+ - Node.js 22 or newer;
19
+ - a test command that already works in the repository; and
20
+ - for Rust, the Rust 1.95 toolchain.
27
21
 
28
- ## Requirements
22
+ The CLI is distributed through npm, even for Rust projects. The first `npx`
23
+ invocation may download Supercov from the npm registry. Supercov itself does not
24
+ upload your source or coverage evidence to a Supercov service.
29
25
 
30
- - Node.js 22 or newer. The current CLI is distributed through npm, including
31
- when it measures a Rust project.
32
- - A working test command for the project.
33
- - For Rust, the Rust 1.95 toolchain. `cargo test` is supported directly;
34
- `cargo nextest run` is supported with cargo-nextest 0.9.138 or 0.9.140.
26
+ ## 1. Run your real test command
35
27
 
36
- Package tools such as `npx` may contact the npm registry to download Supercov
37
- when it is not cached. The Supercov CLI does not contact a Supercov service
38
- during a coverage run, and your source and evidence stay on your machine.
39
-
40
- ## Run the complete suite
41
-
42
- Everything after `--` is your test command. Use the same command you trust
43
- before merging or deploying:
28
+ Everything after `--` is the command Supercov measures. Start with the same
29
+ complete command you trust before merging or deploying:
44
30
 
45
31
  ```sh
46
32
  # JavaScript or TypeScript
@@ -53,37 +39,64 @@ npx supercov -- cargo test
53
39
  npx supercov -- cargo nextest run
54
40
  ```
55
41
 
56
- If one command launches several supported runners, Supercov combines their
57
- evidence into one run.
42
+ Supercov runs that command in an isolated, instrumented copy of the project.
43
+ The command keeps its normal arguments, environment, output, and exit status.
44
+ If one command launches several supported runners, their evidence lands in one
45
+ run.
58
46
 
59
- ## Find the next test
47
+ ## 2. Read the first result
60
48
 
61
- Start broad, then open one useful target:
49
+ Open the newest run:
62
50
 
63
51
  ```sh
64
52
  npx supercov runs latest
53
+ ```
54
+
55
+ The summary answers three practical questions:
56
+
57
+ 1. Did the test command pass?
58
+ 2. How much behavior did the suite cover?
59
+ 3. Is anything genuinely uncovered, or was some code impossible to measure?
60
+
61
+ An uncovered gap is a candidate for a test. A measurement limit is different:
62
+ it means Supercov cannot honestly account for that code yet. Do not try to test
63
+ away a measurement limit.
64
+
65
+ ## 3. Choose one useful gap
66
+
67
+ Ask for a short list, then inspect one file:
68
+
69
+ ```sh
65
70
  npx supercov runs latest gaps --limit 10
66
71
  npx supercov runs latest file app/checkout/session.ts
72
+ ```
73
+
74
+ Use the more specific queries when you need them:
75
+
76
+ ```sh
67
77
  npx supercov runs latest decision app/checkout/session.ts:64
78
+ npx supercov runs latest line app/checkout/session.ts:64
68
79
  ```
69
80
 
70
- The output is short and paginated so a coding agent can use it directly. Add
71
- `--json` only when a tool specifically needs machine-readable output.
81
+ `file` is usually the best place to start. `decision` explains missing boolean
82
+ outcomes and MC/DC witnesses. `line` shows the obligations and tests associated
83
+ with one source line.
72
84
 
73
- ## Add a test and prove the gain
85
+ ## 4. Add a test and prove the gain
74
86
 
75
- Write one focused test, rerun the same complete command, and compare the two
76
- runs:
87
+ Write one focused test with a meaningful assertion. Then rerun the same complete
88
+ command and compare the two runs:
77
89
 
78
90
  ```sh
79
91
  npx supercov -- npm test
80
92
  npx supercov diff <previous-run-id> latest
81
93
  ```
82
94
 
83
- For Rust, rerun the same `cargo test` or `cargo nextest run` command you used
84
- for the baseline.
95
+ For Rust, rerun the same `cargo test` or `cargo nextest run` command used for the
96
+ baseline. A useful change leaves the suite passing and shows the expected gain
97
+ without an unexplained loss elsewhere.
85
98
 
86
- ## Give the loop to an agent
99
+ ## Give the loop to a coding agent
87
100
 
88
101
  Paste this into any coding agent that can run terminal commands:
89
102
 
@@ -92,30 +105,37 @@ Use `npx supercov` to improve coverage. Only write tests. Keep going while
92
105
  useful gaps remain.
93
106
 
94
107
  Run the repository's complete test command through Supercov. Use
95
- `npx supercov runs latest gaps --limit 5` to choose one useful target. Write
96
- one focused test, rerun the complete suite, and verify the gain with
108
+ `npx supercov runs latest gaps --limit 5` to choose one useful target. Inspect
109
+ the target, write one focused test with meaningful assertions, rerun the same
110
+ complete suite, and verify the gain with
97
111
  `npx supercov diff <previous-run-id> latest`.
98
112
 
99
113
  Never weaken assertions or change application code to make coverage easier.
100
- Stop when no useful gaps remain.
114
+ Stop when no useful gap remains or Supercov reports a measurement limit instead
115
+ of an ordinary gap.
101
116
  ```
102
117
 
103
- ## Local files and cleanup
118
+ Replace `npm test` with the repository's real complete test command when needed.
104
119
 
105
- Completed runs live under `.supercov/runs/`. Supercov also maintains a
106
- marker-protected isolated workspace for instrumented builds. It does not rewrite
107
- your source, tests, imports, runner configuration, dependency tree, or ordinary
108
- build output.
120
+ ## Files and cleanup
121
+
122
+ Completed runs live under `.supercov/runs/`. Supercov also keeps an isolated
123
+ workspace for instrumented builds. These files are local and ignored by Git.
124
+ Supercov does not rewrite your source, tests, imports, runner configuration,
125
+ dependencies, or ordinary build output.
109
126
 
110
127
  ```sh
111
- npx supercov clean --dry-run # preview a full cleanup
112
- npx supercov clean --keep 20 # retain the 20 newest runs
128
+ npx supercov clean --dry-run # preview what would be removed
129
+ npx supercov clean --keep 20 # keep the 20 newest runs
113
130
  npx supercov clean # remove all runs and the build cache
114
131
  ```
115
132
 
133
+ If the first run does not look right, go to [Troubleshooting](troubleshooting.md)
134
+ before changing the project.
135
+
116
136
  ## Next
117
137
 
118
- - [Agent loop](/docs/agent-loop) — a repeatable coverage workflow for coding agents.
119
- - [CLI reference](/docs/cli) — commands and filters.
120
- - [Coverage model](/docs/coverage-model) — what Supercov measures.
121
- - [Supported suites](/docs/supported-suites) — languages, runners, and current limits.
138
+ - [Agent workflow](agent-loop.md) — run a safe, repeatable coverage loop.
139
+ - [Supported suites](supported-suites.md) — check languages, runners, and limits.
140
+ - [Coverage model](coverage-model.md) — understand gaps, metrics, and measurement limits.
141
+ - [CLI reference](cli.md) — find every command and filter.
package/docs/performance.md CHANGED
@@ -1,68 +1,77 @@
1
- # Performance and storage
1
+ # Speed and storage
2
2
 
3
- Test execution usually dominates a Supercov run. Supercov records the other
4
- phases separately so you can see whether time is going into workspace setup,
5
- instrumentation, the test command, or evidence publication.
3
+ A Supercov run includes your test command, an instrumented build, and evidence
4
+ publication. The first pass is usually the slowest; repeated passes can reuse
5
+ the isolated build when the relevant inputs have not changed.
6
6
 
7
- ## Read run timings
7
+ ## See where the time went
8
8
 
9
9
  ```sh
10
- npx supercov runs --limit 5
11
10
  npx supercov runs latest
12
11
  ```
13
12
 
14
- Each run records:
13
+ The summary separates:
15
14
 
16
- | Phase | Includes |
15
+ | Phase | What it includes |
17
16
  | --- | --- |
18
- | Initialization | Recovery, locking, project discovery, and fingerprints |
19
- | Workspace preparation | Refreshing the isolated project workspace |
20
- | Adapter setup | Preparing runner integration and runtime files |
21
- | Instrumented build | Building instrumented source, or near-zero on an exact cache hit |
22
- | Test command | The wrapped command, including runner and remote latency |
23
- | Evidence publication | Validation, archive creation, summary analysis, and atomic publication |
17
+ | Initialization | Recovery, project discovery, and input checks |
18
+ | Workspace preparation | Refreshing the isolated project copy |
19
+ | Adapter setup | Preparing the runner integration |
20
+ | Instrumented build | Building measured source, or almost nothing on a cache hit |
21
+ | Test command | The wrapped command, including browser, VM, or remote latency |
22
+ | Evidence publication | Validating and storing the completed run |
24
23
 
25
- The same fields are available in `run.json` and in `runs --json` when an
26
- integration needs machine-readable timings.
24
+ The first `npx` invocation may also download the package. That download happens
25
+ before Supercov starts and is not coverage-engine overhead.
27
26
 
28
- ## Keep repeated runs fast
27
+ ## Keep an agent loop fast
29
28
 
30
- - Use the same complete command for the baseline and final verification.
31
- - Let the isolated build cache survive between passes.
32
- - Avoid changing dependencies, build configuration, or toolchains in the
33
- middle of a coverage loop unless the test requires it.
34
- - Use a focused test command while iterating, then finish with the full suite.
35
- - Query the stored run instead of rerunning merely to inspect a different view.
29
+ - Keep the isolated build cache between passes.
30
+ - Avoid changing dependencies, build configuration, or toolchains during the
31
+ loop unless the test requires it.
32
+ - Query the stored run instead of rerunning merely to open another view.
33
+ - Write one related test at a time, then rerun.
34
+ - Use a focused test command while iterating when appropriate, but finish with
35
+ the same complete command used for the baseline.
36
36
 
37
- Supercov reuses an instrumented build only when the relevant source,
38
- configuration, dependencies, toolchain, build mode, and instrumenter identity
39
- match exactly. A mismatch causes a fresh build rather than risking stale
40
- coverage.
37
+ Supercov reuses an instrumented build only when source, dependencies,
38
+ configuration, toolchain, build mode, and instrumenter identity match. A
39
+ possible mismatch triggers a fresh build rather than risking stale coverage.
41
40
 
42
- ## Measure end-to-end overhead
41
+ ## Use focused runs carefully
43
42
 
44
- Supercov never runs the test command a second time automatically because tests
45
- may write data, call paid services, or be intentionally non-repeatable. To
46
- measure overhead, compare the original and wrapped command under the same cache
47
- state:
43
+ A narrow test command can shorten the inner loop:
44
+
45
+ ```sh
46
+ npx supercov -- npx vitest run app/checkout/session.test.ts
47
+ ```
48
+
49
+ That run has a narrower evidence set than the complete suite. Before reporting
50
+ success, rerun the repository's full command and compare against a full-suite
51
+ baseline.
52
+
53
+ ## Measure overhead in your project
54
+
55
+ Compare the original and wrapped command under similar cache conditions:
48
56
 
49
57
  ```sh
50
58
  /usr/bin/time -p npm test
51
59
  /usr/bin/time -p npx supercov -- npm test
52
60
  ```
53
61
 
54
- Use several alternating pairs and compare medians. Do not compare a cold
55
- package, browser, build, or VM cache with a warm one. A first `npx` download is
56
- package-acquisition time, not coverage-engine time.
62
+ Alternate the two commands several times and compare typical runs. Do not
63
+ compare a cold package, browser, build, or VM cache with a warm one. Supercov
64
+ never runs the test command a second time automatically because suites may write
65
+ data, call paid services, or be intentionally non-repeatable.
57
66
 
58
- ## Storage
67
+ ## Understand disk usage
59
68
 
60
- Each completed run stores compressed raw evidence and a small metadata file
61
- under `.supercov/runs/<run-id>/`. Query views are derived from that evidence;
62
- Supercov does not retain a separate full report for every filter.
69
+ Each completed run stores compressed evidence and metadata under
70
+ `.supercov/runs/<run-id>/`. Query views are derived from that evidence rather
71
+ than stored as a full report for every filter.
63
72
 
64
- The isolated workspace can be larger than a run because it may contain an
65
- instrumented build cache. Control retention explicitly:
73
+ The isolated workspace may be larger because it can contain an instrumented
74
+ build cache. Supercov does not delete history in the background.
66
75
 
67
76
  ```sh
68
77
  npx supercov clean --dry-run
@@ -70,5 +79,6 @@ npx supercov clean --keep 20
70
79
  npx supercov clean
71
80
  ```
72
81
 
73
- Supercov never prunes runs in the background. Cleanup is explicit so historical
74
- evidence does not disappear during an unattended agent session.
82
+ Use `--dry-run` to preview cleanup. Keep enough run history for active reviews
83
+ and automation; remove the cache only when reclaiming space matters more than a
84
+ faster next run.
package/docs/supported-suites.md CHANGED
@@ -1,25 +1,42 @@
1
- # Supported suites
1
+ # Supported languages and test suites
2
2
 
3
- Supercov supports JavaScript, TypeScript, and Rust today. Support is exact when
4
- Supercov can identify individual test attempts; otherwise it reports aggregate
5
- coverage without guessing which test caused a hit.
3
+ Supercov supports JavaScript, TypeScript, and Rust today. Start with the same
4
+ test command the repository already uses; Supercov detects supported runners
5
+ inside that command.
6
6
 
7
- ## Languages
7
+ ```sh
8
+ npx supercov -- npm test
9
+ npx supercov -- npx playwright test
10
+ npx supercov -- cargo test
11
+ ```
12
+
13
+ ## Language support
8
14
 
9
- | Language | Status | Supported commands |
15
+ | Language | Status | Start with |
10
16
  | --- | --- | --- |
11
- | JavaScript | Available | Existing Node-based test commands |
12
- | TypeScript | Available | Existing Node-based test commands and build pipelines |
13
- | Rust | Available | `cargo test`, `cargo nextest run` |
17
+ | JavaScript | Available | `npx supercov -- npm test` |
18
+ | TypeScript | Available | `npx supercov -- npm test` |
19
+ | Rust | Available | `npx supercov -- cargo test` |
14
20
  | Python | Coming soon | — |
15
21
  | Zig | Coming soon | — |
16
22
  | PHP | Coming soon | — |
17
23
  | C | Coming soon | — |
18
24
 
19
- More languages will follow. The current npm-distributed CLI requires Node.js 22
20
- or newer for every language.
25
+ The npm-distributed CLI requires Node.js 22 or newer for every language.
26
+
27
+ ## What exact and aggregate mean
28
+
29
+ **Exact attribution** means Supercov knows which test, attempt, retry, and
30
+ runner produced the coverage. Queries such as `test`, `passed`, and `failed`
31
+ can use that identity.
32
+
33
+ **Aggregate coverage** means Supercov knows the source executed but cannot
34
+ truthfully assign it to one test. Whole-run `gaps` and `file` queries still
35
+ work; per-test questions are limited.
21
36
 
22
- ## JavaScript and TypeScript runners
37
+ Supercov reports the level it actually observed. It does not guess.
38
+
39
+ ## JavaScript and TypeScript
23
40
 
24
41
  | Runner | Attribution |
25
42
  | --- | --- |
@@ -27,72 +44,73 @@ or newer for every language.
27
44
  | Vitest | Exact per test, with setup execution kept separate |
28
45
  | Jest | Exact per test, including concurrent and parameterized tests |
29
46
  | `node:test` | Exact per test |
30
- | AVA, Mocha, and other Node runners | Aggregate structural coverage |
47
+ | AVA and Mocha | Aggregate structural coverage |
48
+ | Other Node-based runners | Aggregate when their processes remain visible to Supercov |
31
49
  | Browser component runners without an adapter | Aggregate structural coverage |
32
50
 
33
- Aggregate evidence is still included in the full-run view. It is labelled as
34
- background rather than being assigned to a test that may not have caused it.
35
-
36
- A single command may launch several runners. Supercov combines their evidence
37
- into one run and keeps the runner identity where exact attribution is available.
51
+ One command may launch several runners. Supercov combines their evidence into
52
+ one run and preserves runner identity wherever the runner exposes it.
38
53
 
39
- ## Rust runners
54
+ ### Builds and source formats
40
55
 
41
- | Runner | Attribution | Current boundary |
42
- | --- | --- | --- |
43
- | Cargo's standard libtest runner | Exact test and attempt identity | Run with `npx supercov -- cargo test` |
44
- | cargo-nextest | Exact test, attempt, retry, and binary identity | Run with cargo-nextest 0.9.138 or 0.9.140 |
56
+ JavaScript and TypeScript projects may use Vite, Next, Turbopack, Webpack,
57
+ esbuild, SWC, `tsc`, or no build step. ESM, CommonJS, JavaScript, JSX,
58
+ TypeScript, and TSX are supported.
45
59
 
46
- Rust support currently follows the Rust 1.95 toolchain and preserves Cargo's
47
- test selection, scheduling, fail-fast behavior, environment, and exit status.
48
- `cross` is not supported yet. Unsupported command shapes fail clearly rather
49
- than falling back to plausible but inaccurate attribution.
60
+ Supercov instruments an isolated copy. It does not ask you to add an import,
61
+ reporter, plugin, or alternate build output.
50
62
 
51
- ## Builds and source formats
63
+ ### Browsers, servers, and child processes
52
64
 
53
- JavaScript and TypeScript projects can use Vite, Vitest, Next, Turbopack,
54
- Webpack, esbuild, SWC, `tsc`, or no build step. ESM and CommonJS are supported,
55
- along with modern JavaScript, JSX, TypeScript, and TSX syntax.
65
+ Playwright support includes Chromium, Firefox, and WebKit, along with pages,
66
+ frames, popups, workers, request contexts, WebSockets, and test-launched child
67
+ processes where the runner exposes their identity.
56
68
 
57
- Supercov instruments an isolated workspace. It does not add imports, reporters,
58
- or plugins to the authored project, and it does not overwrite the project's
59
- ordinary build output.
69
+ Node child processes inherit coverage automatically. Long-running servers get
70
+ a short drain window after the test command finishes so buffered evidence can
71
+ arrive. Work without a reliable test identity is kept as background coverage
72
+ instead of being assigned to an arbitrary test.
60
73
 
61
- ## Browsers
74
+ ## Rust
62
75
 
63
- Playwright coverage supports Chromium, Firefox, and WebKit. It follows pages,
64
- frames, popups, workers, request contexts, WebSockets, and test-spawned child
65
- processes where the runner exposes the required identity.
76
+ | Runner | Attribution | Current requirement |
77
+ | --- | --- | --- |
78
+ | Cargo's standard libtest runner | Exact test and attempt identity | Rust 1.95; run with `npx supercov -- cargo test` |
79
+ | cargo-nextest | Exact test, attempt, retry, and binary identity | cargo-nextest 0.9.138 or 0.9.140 |
66
80
 
67
- ## Background processes and servers
81
+ Supercov preserves Cargo's test selection, scheduling, fail-fast behavior,
82
+ environment, and exit status. Use the repository's normal flags after the
83
+ wrapped command:
68
84
 
69
- Node child processes inherit coverage automatically. Long-running servers are
70
- given a short drain window after the test command finishes so buffered evidence
71
- can arrive before the run is published.
85
+ ```sh
86
+ npx supercov -- cargo test --workspace
87
+ npx supercov -- cargo nextest run --workspace
88
+ ```
72
89
 
73
- If work arrives without a reliable test identity, Supercov records it as
74
- background evidence. The default whole-run view includes it; passed-only and
75
- per-test views do not pretend it belongs to a particular test.
90
+ `cross` is not supported yet. Unsupported command shapes fail with an
91
+ explanation instead of silently falling back to plausible but inaccurate
92
+ attribution.
76
93
 
77
94
  ## Containers, VMs, and remote execution
78
95
 
79
96
  Supercov can collect from supported processes launched through a container, VM,
80
- or remote executor when the command exposes a discoverable launch boundary and
81
- the Supercov runtime can be carried into that environment. Mounted workspaces
82
- and local child-process launchers are the most direct path.
97
+ or remote executor when it can see the launch boundary, carry the instrumented
98
+ workspace into that environment, and receive evidence back.
83
99
 
84
- If the remote boundary hides how code is launched or cannot return evidence,
85
- Supercov reports the missing coverage boundary. It does not silently treat
86
- remote execution as measured.
100
+ Mounted workspaces and local child-process launchers are the most direct path.
101
+ If an executor hides how code is launched or cannot return evidence, Supercov
102
+ reports the missing boundary rather than claiming unseen code was measured.
87
103
 
88
- ## Distributed suites
104
+ ## If your runner is not listed
89
105
 
90
- Run shards separately, then merge compatible run ids:
106
+ For a Node-based runner, try the complete command and inspect the result:
91
107
 
92
108
  ```sh
93
- npx supercov merge <shard-a> <shard-b> <shard-c>
109
+ npx supercov -- npm test
110
+ npx supercov runs latest runners
111
+ npx supercov runs latest scope
94
112
  ```
95
113
 
96
- All shards must describe the same source, configuration, toolchain, schema, and
97
- coverage denominator. Incompatible shards are rejected with the mismatched
98
- domains listed.
114
+ Aggregate coverage may already be useful even without exact per-test identity.
115
+ If a supported runner appears incomplete, see [Troubleshooting](troubleshooting.md)
116
+ and include the exact command and runner output when opening an issue.
package/docs/troubleshooting.md ADDED
@@ -0,0 +1,143 @@
1
+ # Troubleshooting
2
+
3
+ Start with the run summary. It usually tells you whether the problem is the test
4
+ command, source discovery, runner attribution, or a measurement boundary.
5
+
6
+ ```sh
7
+ npx supercov runs latest
8
+ npx supercov runs latest scope
9
+ npx supercov runs latest runners
10
+ ```
11
+
12
+ ## `npx` cannot start Supercov
13
+
14
+ The first `npx supercov` invocation may need to reach the npm registry. Check
15
+ Node.js first:
16
+
17
+ ```sh
18
+ node --version
19
+ npx supercov --version
20
+ ```
21
+
22
+ Supercov requires Node.js 22 or newer. Registry, proxy, authentication, or
23
+ offline-cache errors happen before the Supercov CLI starts; resolve them as you
24
+ would for another npm package.
25
+
26
+ ## No application source was found
27
+
28
+ Run the same command from the repository root. If first-party code lives in an
29
+ unusual directory, declare the source roots explicitly:
30
+
31
+ ```sh
32
+ SUPERCOV_SOURCE_ROOTS=src,app npx supercov -- npm test
33
+ ```
34
+
35
+ Then inspect what Supercov included and excluded:
36
+
37
+ ```sh
38
+ npx supercov runs latest scope
39
+ ```
40
+
41
+ Do not broaden the roots to dependencies or generated output merely to remove a
42
+ warning. The goal is an honest boundary around code the repository owns.
43
+
44
+ ## The tests pass but coverage is missing
45
+
46
+ First check runner and source scope:
47
+
48
+ ```sh
49
+ npx supercov runs latest runners
50
+ npx supercov runs latest scope
51
+ npx supercov runs latest gaps
52
+ ```
53
+
54
+ Some runners expose exact test boundaries; others provide only aggregate
55
+ coverage. Processes inside a container, VM, remote executor, or hidden launcher
56
+ may also sit beyond the instrumentation boundary. Supercov reports that limit
57
+ instead of assigning execution to a test that may not have caused it.
58
+
59
+ Compare the command with [Supported suites](supported-suites.md). If the runner
60
+ should be supported, preserve the summary and exact command when reporting the
61
+ problem.
62
+
63
+ ## A run is marked stale
64
+
65
+ A stored run remains valid history, but it stops describing the current
66
+ workspace after relevant source, tests, dependencies, configuration, or
67
+ toolchain inputs change. Rerun the same complete command to create a current
68
+ baseline:
69
+
70
+ ```sh
71
+ npx supercov -- npm test
72
+ ```
73
+
74
+ Use immutable run ids in review notes and automation. Use `latest` only when the
75
+ newest local run is the one you intend to inspect.
76
+
77
+ ## `gaps` shows a measurement limit
78
+
79
+ A measurement limit is not an uncovered path. It means Supercov could not
80
+ establish a complete measurement boundary—for example, because source scope is
81
+ ambiguous, code creates source dynamically, or execution crossed an unsupported
82
+ boundary.
83
+
84
+ Read the reason in the summary, `scope`, or `gaps` output. Fix a configuration
85
+ problem when one is named. Otherwise stop the coverage loop and report the
86
+ limit; do not change application code or add a meaningless test to chase 100%.
87
+
88
+ ## Coverage is aggregate instead of per test
89
+
90
+ Aggregate coverage still shows which source ran, but Supercov cannot truthfully
91
+ say which individual test caused it. This is expected for Node runners without
92
+ an exact adapter and for background work without a reliable test identity.
93
+
94
+ Use the whole-run `gaps` and `file` views. Per-test queries become useful when
95
+ the runner exposes exact test and attempt boundaries.
96
+
97
+ ## A second command says Supercov is busy
98
+
99
+ One project can publish or clean one coverage store at a time. Let the active
100
+ run finish before starting another Supercov command. If a process was
101
+ interrupted, the next command recovers its unpublished staging state; completed
102
+ runs remain intact.
103
+
104
+ ## The first run is slow
105
+
106
+ The first run may include the npm download, browser or toolchain startup,
107
+ workspace creation, and an instrumented build. Repeated runs can reuse the
108
+ isolated build when source, dependencies, configuration, toolchain, and build
109
+ mode still match.
110
+
111
+ Inspect the recorded phases with:
112
+
113
+ ```sh
114
+ npx supercov runs latest
115
+ ```
116
+
117
+ See [Speed and storage](performance.md) for practical ways to shorten a loop.
118
+
119
+ ## Supercov is using too much disk space
120
+
121
+ Preview cleanup, then choose how much history to keep:
122
+
123
+ ```sh
124
+ npx supercov clean --dry-run
125
+ npx supercov clean --keep 20
126
+ npx supercov clean
127
+ ```
128
+
129
+ The final command removes all stored runs and the isolated build cache. Cleanup
130
+ only removes marker-owned Supercov data.
131
+
132
+ ## Ask for help
133
+
134
+ Open an issue in the [Supercov repository](https://github.com/supercorp-ai/supercov/issues)
135
+ with:
136
+
137
+ - `npx supercov --version`;
138
+ - the exact wrapped test command;
139
+ - the relevant summary, `scope`, and `runners` output; and
140
+ - a small reproduction when the repository can be shared.
141
+
142
+ Do not include secrets, private source, or raw evidence from a repository you
143
+ cannot share.