supercov 0.0.25 → 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 -84
  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/README.md CHANGED
@@ -2,108 +2,94 @@
2
2
 
3
3
  **Coverage for coding agents working overnight.**
4
4
 
5
- **Supercov gives the agent the next test to write.** Each run returns the uncovered paths. The agent adds focused tests, reruns the suite, and continues while useful gaps remain.
5
+ **Supercov gives your coding agent the next useful test to write.** It runs the test command you already use, records local coverage evidence, and turns uncovered paths into small, actionable queries. Your agent writes a focused test, reruns the suite, proves what improved, and keeps going while useful gaps remain.
6
6
 
7
- Supercov wraps the test command you already run, records immutable local evidence, and returns bounded queries about the code paths that remain uncovered. Your agent writes the tests; Supercov tells it where.
7
+ No account, config file, import, custom reporter, or hosted service is required. Supercov is local, free, open source, and MIT licensed.
8
8
 
9
- No account, config file, import, custom reporter, or hosted service is required. Your source and coverage evidence stay on your machine. Supercov is free, open source, and MIT licensed.
9
+ [Website](https://supercov.com) · [Documentation](https://supercov.com/docs) · [npm](https://www.npmjs.com/package/supercov) · [GitHub](https://github.com/supercorp-ai/supercov)
10
10
 
11
- Supported by [Supercorp](https://supercorp.ai). Learn more at [supercov.com](https://supercov.com).
11
+ Supported by [Supercorp](https://supercorp.ai).
12
12
 
13
- ## Installation & Usage
13
+ ## Start with the suite you already have
14
14
 
15
- Run your existing test command through Supercov:
15
+ ```bash
16
+ npx supercov -- npm test
17
+ ```
18
+
19
+ Everything after `--` is your test command. Supercov runs it without changing your source, tests, runner configuration, or normal build output.
20
+
21
+ Then ask what is still uncovered:
22
+
23
+ ```bash
24
+ npx supercov runs latest gaps --limit 10
25
+ ```
26
+
27
+ After your agent adds a test, rerun the complete suite and prove the gain:
16
28
 
17
29
  ```bash
18
30
  npx supercov -- npm test
31
+ npx supercov diff <previous-run-id> latest
19
32
  ```
20
33
 
21
- Everything after `--` is your command, executed exactly as written. If your project uses a different command, pass that instead:
34
+ Use whichever complete test command the repository already trusts:
22
35
 
23
36
  ```bash
24
37
  npx supercov -- npx playwright test
25
38
  npx supercov -- pnpm test:e2e
26
- npx supercov -- npm run test:unit && npx supercov -- npm run test:e2e
27
39
  npx supercov -- cargo test
28
40
  npx supercov -- cargo nextest run
29
41
  ```
30
42
 
31
- Supercov requires Node.js 22 or newer. Rust projects currently use the Rust 1.95 toolchain; cargo-nextest 0.9.138 and 0.9.140 are supported. Package tools such as `npx` may contact the npm registry to download Supercov when it is not already cached; the Supercov CLI itself does not contact a Supercov service during a coverage run.
43
+ ## Give Supercov a job
32
44
 
33
- ## Language support
45
+ Paste one of these prompts into Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, or any coding agent that can run terminal commands.
34
46
 
35
- | Language | Status | Start with |
36
- | --- | --- | --- |
37
- | JavaScript | Available | `npx supercov -- npm test` |
38
- | TypeScript | Available | `npx supercov -- npm test` |
39
- | Rust | Available | `npx supercov -- cargo test` |
40
- | Python | Coming soon | — |
41
- | Zig | Coming soon | — |
42
- | PHP | Coming soon | — |
43
- | C | Coming soon | — |
44
-
45
- More languages are planned.
47
+ ### Write the first useful test
46
48
 
47
- ## Give it to your coding agent
49
+ ```text
50
+ Measure code coverage with `npx supercov`. Use the coverage evidence to choose
51
+ one useful missing test. Only edit tests. Run the repository's complete test
52
+ suite through Supercov again and report what improved.
53
+ ```
48
54
 
49
- Paste this into Claude Code, Codex, Cursor, Copilot, Gemini, or any coding agent that can run terminal commands:
55
+ ### Use leftover tokens on coverage
50
56
 
51
57
  ```text
52
- Use `npx supercov` to improve coverage. Only write tests. Keep going while
53
- useful gaps remain.
58
+ Measure code coverage with `npx supercov` and write tests til 100%. Only edit
59
+ tests. Keep going while useful gaps remain.
54
60
 
55
- Start with `npx supercov -- npm test`. Then use
56
- `npx supercov runs latest gaps --limit 5` to choose one useful target.
57
- Write one focused test, rerun the same full suite through Supercov, and verify
58
- the gain with `npx supercov diff <previous-run-id> latest`.
61
+ Run the repository's complete test suite through Supercov. Use
62
+ `npx supercov runs latest gaps --limit 5` to choose one useful target at a
63
+ time. Write a focused test, rerun the same complete suite, and use
64
+ `npx supercov diff <previous-run-id> latest` to verify the gain.
59
65
 
60
- Only edit tests. Never weaken assertions or change application code to make
61
- coverage easier. Stop when no useful gaps remain.
66
+ Never weaken assertions or change application code to make coverage easier.
67
+ Stop if the suite fails, the evidence is incomplete, or no useful gaps remain.
62
68
  ```
63
69
 
64
- Replace `npm test` with the repository's complete test command when needed.
70
+ ## The agent loop
65
71
 
66
- ## How it works
67
-
68
- Each run returns fresh, executable evidence, so coding agents can keep iterating without loading a large HTML report into context.
69
-
70
- 1. **Run the suite.** Supercov executes the command after `--` inside an isolated workspace without modifying your source, tests, runner configuration, or ordinary build output.
71
- 2. **Measure what happened.** It records a fixed coverage denominator and immutable evidence for the run.
72
- 3. **Ask what is open.** Short, paginated CLI queries identify uncovered files, lines, branches, decisions, and value paths without loading a large HTML report into an agent's context.
73
- 4. **Write and prove one test.** Your coding agent adds a focused test, reruns the suite, and uses `diff` to verify exactly what improved.
72
+ 1. **Run the real suite.** Supercov executes the command after `--` in an isolated workspace.
73
+ 2. **Find one useful gap.** Short, paginated queries show uncovered files, lines, branches, decisions, and value paths without loading a large HTML report into context.
74
+ 3. **Write one focused test.** The coding agent changes tests—not application code or coverage configuration.
75
+ 4. **Rerun and prove the gain.** `diff` shows exactly what the new test covered.
76
+ 5. **Repeat while useful gaps remain.** Failed tests, incomplete evidence, or ambiguous scope stay visible instead of being rounded away.
74
77
 
75
78
  Supercov supplies the coverage signal and evidence. It does not host, schedule, or replace your coding agent.
76
79
 
77
80
  ## Use leftover tokens on coverage
78
81
 
79
- Before a reset—or overnight—turn idle agent time into coverage that stays with the repository. Every pass should close a small number of useful gaps and finish with evidence that the tests still pass and coverage improved.
82
+ Before a reset—or overnight—turn idle agent time into coverage that stays with the repository. Each pass closes a small number of useful gaps and finishes with evidence that the tests still pass and coverage improved.
80
83
 
81
- ## Read the result
84
+ ## Use it in a software factory
82
85
 
83
- Start with the summary, then narrow to one useful target:
86
+ Add Supercov as a repeatable quality loop in an automated software factory. Your factory schedules the work; Supercov gives each agent a bounded next task and an immutable record of the result.
84
87
 
85
- ```bash
86
- # Recent runs and the latest summary
87
- npx supercov runs --limit 5
88
- npx supercov runs latest
89
-
90
- # The most useful open coverage obligations
91
- npx supercov runs latest gaps --limit 10
92
-
93
- # Details for one file or source location
94
- npx supercov runs latest file app/checkout/session.ts
95
- npx supercov runs latest decision app/checkout/session.ts:64
96
- npx supercov runs latest line app/checkout/session.ts:64
97
-
98
- # Prove what changed between two runs
99
- npx supercov diff <previous-run-id> latest
100
- ```
101
-
102
- Add `--json` to any query for the stable machine-readable format. Collections accept `--limit` and `--offset` and print a copyable next-page command.
88
+ Every pass runs the real suite, chooses an uncovered path, writes a focused test, reruns, and proves the gain. Fresh executable evidence lets agents keep iterating around the clock while failed tests and regressions stop the loop before they ship.
103
89
 
104
90
  ## Coverage agents can act on
105
91
 
106
- From lines and branches to MC/DC, every gap becomes the next test to write. Supercov measures more than a line percentage:
92
+ From lines and branches to MC/DC, every gap becomes a concrete test target. Supercov measures:
107
93
 
108
94
  - lines, statements, functions, and branches;
109
95
  - MC/DC independence witnesses;
@@ -111,55 +97,87 @@ From lines and branches to MC/DC, every gap becomes the next test to write. Supe
111
97
  - `try`/`catch` and zero-iteration control-flow paths; and
112
98
  - per-test provenance where the runner exposes exact test boundaries.
113
99
 
114
- The denominator is derived from source structure before the run, so adding or removing tests cannot silently change what 100% means. Ambiguous source scope, uninstrumented code, and missing evidence remain visible as completeness blockers instead of being rounded away.
100
+ The denominator comes from source structure before the run, so adding or removing tests cannot silently change what 100% means. Ambiguous source scope, uninstrumented code, and missing evidence remain visible as completeness blockers.
101
+
102
+ ## Supported languages
103
+
104
+ | Language | Status | Start with |
105
+ | --- | --- | --- |
106
+ | JavaScript | Available | `npx supercov -- npm test` |
107
+ | TypeScript | Available | `npx supercov -- npm test` |
108
+ | Rust | Available | `npx supercov -- cargo test` |
109
+ | Python | Coming soon | — |
110
+ | Zig | Coming soon | — |
111
+ | PHP | Coming soon | — |
112
+ | C | Coming soon | — |
113
+
114
+ Supercov requires Node.js 22 or newer. Rust support currently uses Rust 1.95; cargo-nextest 0.9.138 and 0.9.140 are supported.
115
115
 
116
- ## Works with your existing test suite
116
+ ## Supported test suites
117
117
 
118
- Runner support differs by attribution level. Supercov uses exact per-test attribution where an adapter is available and reports aggregate structural coverage rather than guessing for other runners.
118
+ Supercov uses exact per-test attribution where an adapter is available. For other supported runners, it reports aggregate structural coverage instead of guessing which test covered a path.
119
119
 
120
- | Runner | Attribution |
120
+ | Runner | Coverage attribution |
121
121
  | --- | --- |
122
122
  | Playwright | Exact per test, worker, retry, outcome, action, and assertion phase |
123
123
  | Vitest | Exact per test, with setup execution kept separate |
124
124
  | Jest | Exact per test, including concurrent and parameterized tests |
125
125
  | `node:test` | Exact per test |
126
- | AVA, Mocha, and other Node runners | Aggregate structural coverage |
126
+ | AVA and Mocha | Aggregate structural coverage |
127
127
  | Cargo's standard libtest runner | Exact test and attempt identity |
128
128
  | cargo-nextest | Exact test, attempt, retry, and binary identity |
129
129
 
130
- Supercov works with Vite, Next, Turbopack, Webpack, esbuild, SWC, and projects with no build step. A single command can collect evidence from several supported runners into one run.
130
+ Supercov works with Vite, Next, Turbopack, Webpack, esbuild, SWC, and projects with no build step. One command can collect evidence from several supported runners into a single run.
131
+
132
+ See [Supported languages and test suites](https://supercov.com/docs/supported-suites) for exact compatibility and attribution boundaries.
131
133
 
132
- See [Supported suites](https://supercov.com/docs/supported-suites) for exact compatibility and attribution boundaries.
134
+ ## Read the result
133
135
 
134
- ## Any coding agent
136
+ ```bash
137
+ # Recent runs and the latest summary
138
+ npx supercov runs --limit 5
139
+ npx supercov runs latest
140
+
141
+ # The most useful open coverage obligations
142
+ npx supercov runs latest gaps --limit 10
143
+
144
+ # Details for a file or source location
145
+ npx supercov runs latest file app/checkout/session.ts
146
+ npx supercov runs latest decision app/checkout/session.ts:64
147
+ npx supercov runs latest line app/checkout/session.ts:64
148
+
149
+ # What changed between two runs
150
+ npx supercov diff <previous-run-id> latest
151
+ ```
135
152
 
136
- Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot—and more. Any coding agent that can run terminal commands can use Supercov's concise text output or optional machine-readable format.
153
+ Collections accept `--limit` and `--offset` and print a copyable next-page command. Machine-readable output is available with `--json` when an integration needs it.
137
154
 
138
- ## Local and zero-edit
155
+ ## Local, private, and zero-edit
139
156
 
140
- Every run is stored locally under `.supercov/runs/<run-id>/`. Supercov also maintains a marker-protected isolated build cache under `supercov/workspace/`.
157
+ Run evidence stays under `.supercov/runs/<run-id>/`. Supercov also maintains a marker-protected isolated build cache under `supercov/workspace/`.
141
158
 
142
- It does not rewrite your source files, tests, imports, reporter list, runner configuration, dependency tree, or ordinary build output. An existing user-created `supercov/` directory is never adopted.
159
+ The Supercov CLI does not contact a Supercov service during a coverage run. Package tools such as `npx` may contact the npm registry to download Supercov when it is not already cached.
143
160
 
144
- Storage is controlled explicitly:
161
+ Supercov does not rewrite your source files, tests, imports, reporter list, runner configuration, dependency tree, or normal build output. An existing user-created `supercov/` directory is never adopted.
145
162
 
146
163
  ```bash
147
- npx supercov clean --dry-run # preview a full cleanup
148
- npx supercov clean --keep 20 # retain the 20 newest runs
164
+ npx supercov clean --dry-run # preview cleanup
165
+ npx supercov clean --keep 20 # keep the 20 newest runs
149
166
  npx supercov clean # remove all runs and the build cache
150
167
  ```
151
168
 
152
169
  ## Documentation
153
170
 
154
171
  - [Getting started](https://supercov.com/docs/getting-started)
155
- - [Agent loop](https://supercov.com/docs/agent-loop)
172
+ - [Agent workflow](https://supercov.com/docs/agent-loop)
173
+ - [Troubleshooting](https://supercov.com/docs/troubleshooting)
156
174
  - [CLI reference](https://supercov.com/docs/cli)
157
- - [Coverage model](https://supercov.com/docs/coverage-model)
158
- - [Supported suites](https://supercov.com/docs/supported-suites)
159
- - [Evidence and runs](https://supercov.com/docs/evidence)
160
- - [Verification](https://supercov.com/docs/verification)
161
- - [Workspace isolation](https://supercov.com/docs/workspace-isolation)
162
- - [Performance and storage](https://supercov.com/docs/performance)
175
+ - [Supported languages and test suites](https://supercov.com/docs/supported-suites)
176
+ - [Understanding coverage](https://supercov.com/docs/coverage-model)
177
+ - [Runs and evidence](https://supercov.com/docs/evidence)
178
+ - [Files, privacy, and cleanup](https://supercov.com/docs/workspace-isolation)
179
+ - [Trusting a result](https://supercov.com/docs/verification)
180
+ - [Speed and storage](https://supercov.com/docs/performance)
163
181
 
164
182
  ## Free and open source
165
183
 
package/docs/agent-loop.md CHANGED
@@ -1,7 +1,7 @@
1
- # Agent loop
1
+ # Agent workflow
2
2
 
3
- Use Supercov in a simple loop: run the suite, choose one useful gap, write one
4
- test, rerun, and prove what improved.
3
+ Supercov works best as a small, repeatable loop: run the suite, choose one useful
4
+ gap, write one test, rerun, and prove what improved.
5
5
 
6
6
  ```text
7
7
  run the suite → choose a gap → write one test → rerun → compare
@@ -9,33 +9,57 @@ run the suite → choose a gap → write one test → rerun → compare
9
9
  └────────────────────────────────────────────────────────────┘
10
10
  ```
11
11
 
12
- ## One pass
12
+ Supercov supplies the coverage signal and evidence. Your coding agent writes
13
+ the tests.
14
+
15
+ ## Choose the job
16
+
17
+ For one careful first pass, ask:
18
+
19
+ ```text
20
+ Measure code coverage with `npx supercov` and write the first useful test based
21
+ on coverage. Only edit tests. Rerun the complete suite and report what improved.
22
+ ```
23
+
24
+ For an overnight run or leftover token budget, ask:
25
+
26
+ ```text
27
+ Use `npx supercov` to improve coverage. Only write tests. Keep going while
28
+ useful gaps remain. Never weaken assertions or change application code to make
29
+ coverage easier. Stop at a measurement limit, unreachable behavior, or the end
30
+ of the available time budget. Report the run ids compared and what improved.
31
+ ```
32
+
33
+ The second prompt is intentionally open-ended, but 100% is a direction rather
34
+ than permission to write meaningless tests or reshape application code.
35
+
36
+ ## One safe pass
13
37
 
14
38
  ```sh
15
39
  # 1. Establish a baseline.
16
40
  npx supercov -- npm test
17
41
 
18
- # 2. Choose a useful target without loading a large report.
42
+ # 2. Ask for a short list of useful targets.
19
43
  npx supercov runs latest gaps --limit 5
20
44
 
21
- # 3. Understand the target and what already reaches it.
45
+ # 3. Inspect one target.
22
46
  npx supercov runs latest file app/checkout/session.ts
23
47
  npx supercov runs latest decision app/checkout/session.ts:64
24
48
  npx supercov runs latest line app/checkout/session.ts:64
25
49
 
26
- # 4. Write one focused test, then rerun and prove the gain.
50
+ # 4. Write one focused test, rerun, and prove the gain.
27
51
  npx supercov -- npm test
28
52
  npx supercov diff <previous-run-id> latest
29
53
  ```
30
54
 
31
- For Rust, replace `npm test` with `cargo test` or `cargo nextest run` in both
32
- runs. Keep the command identical between the baseline and comparison.
55
+ For Rust, use `cargo test` or `cargo nextest run` in both runs. Keep the baseline
56
+ and verification commands identical.
33
57
 
34
- The `line` query is useful before writing a test: it shows what already
35
- executes that line, which can reveal an existing test to extend instead of a
36
- duplicate to add.
58
+ The `line` query is useful before writing a test because it shows which tests
59
+ already reach that line. Extending a nearby test is often better than adding a
60
+ duplicate.
37
61
 
38
- ## Prompt for a coding agent
62
+ ## A complete prompt for longer runs
39
63
 
40
64
  ```text
41
65
  Use `npx supercov` to improve coverage. Only write tests. Keep going while
@@ -49,26 +73,29 @@ Run the repository's complete test command through Supercov. Then repeat:
49
73
  5. Rerun the same complete suite through Supercov.
50
74
  6. Run `npx supercov diff <previous-run-id> latest` to prove the gain.
51
75
 
52
- Only edit tests. Never weaken assertions or change application code to make
53
- coverage easier. Stop when no useful gaps remain, a gap is not reachable
54
- through a public behavior, or the time budget is exhausted. Report the run ids
55
- you compared and what improved.
76
+ Only edit tests. Never weaken assertions, delete tests, or change application
77
+ code to make coverage easier. Stop when no useful gap remains, a path is not
78
+ reachable through public behavior, Supercov reports a measurement limit, or
79
+ the time budget is exhausted. Report the run ids compared and what improved.
56
80
  ```
57
81
 
58
- ## Choose valuable gaps
82
+ ## Choose value, not just percentage
59
83
 
60
- `gaps` ranks unresolved obligations, but coverage count is not the same as
61
- product value. Prefer code that protects user-facing behavior, permissions,
62
- payments, state transitions, error recovery, and other high-consequence paths.
84
+ `gaps` ranks unresolved obligations, but the largest number is not always the
85
+ most valuable test. Prefer behavior around:
63
86
 
64
- Useful checks before writing a test:
87
+ - permissions and access control;
88
+ - payments and state transitions;
89
+ - retries, failures, and recovery;
90
+ - user-visible outcomes; and
91
+ - public APIs with consequential edge cases.
65
92
 
66
- - Is this behavior reachable through a public API or user action?
67
- - Does an existing test almost cover it?
68
- - Can the test make a meaningful assertion rather than merely execute a line?
69
- - Is the path actually dead code that should be reported for human review?
93
+ Before writing a test, ask whether the behavior is reachable, whether an
94
+ existing test almost covers it, and whether the new test can make a meaningful
95
+ assertion. Dead code is usually something to report for human review, not a
96
+ reason to manufacture a test.
70
97
 
71
- If the project separates test levels, focus the view:
98
+ If the repository separates test levels, narrow the view:
72
99
 
73
100
  ```sh
74
101
  npx supercov runs latest gaps --kind e2e --limit 10
@@ -77,23 +104,35 @@ npx supercov runs latest gaps --kind e2e --limit 10
77
104
  ## Keep the loop efficient
78
105
 
79
106
  - Begin and end with the complete test command.
80
- - While iterating, a narrower test command is fine if its smaller denominator
81
- is understood.
82
- - Write one related test at a time, then rerun. Large batches make failures and
83
- coverage gains harder to attribute.
84
- - Use immutable run ids when work spans several sessions. `latest` is a
85
- convenience for interactive use.
86
- - Treat a stale run as history when the source has changed since it was made.
107
+ - A focused command is fine during iteration, but finish against the full
108
+ denominator before reporting success.
109
+ - Write one related test at a time. Large batches make failures and gains hard
110
+ to explain.
111
+ - Use immutable run ids when work spans sessions. Use `latest` for an
112
+ interactive loop.
113
+ - Treat a run as history after the source or relevant configuration changes.
114
+
115
+ ## Use Supercov in a software factory
116
+
117
+ Your factory schedules agents; Supercov gives each pass a bounded coverage task
118
+ and a durable result. A worker can run the suite, choose a gap, write one test,
119
+ and return the before-and-after run ids. The next worker can inspect that result
120
+ without relying on a dashboard or the previous agent's memory.
121
+
122
+ Keep the same safety contract in unattended work: tests only, meaningful
123
+ assertions, full-suite verification, and an explicit stop when the remaining
124
+ items are measurement limits rather than testable gaps.
87
125
 
88
126
  ## Know when to stop
89
127
 
90
128
  Stop instead of grinding when:
91
129
 
92
130
  - no useful uncovered behavior remains;
93
- - the open path cannot be reached through a supported public behavior;
131
+ - the path cannot be reached through supported public behavior;
94
132
  - source scope is ambiguous and needs `SUPERCOV_SOURCE_ROOTS`;
95
- - execution belongs to an unsupported or unattributed runner; or
96
- - Supercov reports a completeness blocker rather than an ordinary test gap.
133
+ - the runner can provide only aggregate evidence for the question being asked;
134
+ - Supercov reports a measurement limit rather than an ordinary gap; or
135
+ - the next test would exist only to move a number.
97
136
 
98
- These states are reported explicitly so an agent does not reshape application
99
- code merely to reach a number.
137
+ See [Troubleshooting](troubleshooting.md) when a run appears incomplete or
138
+ unexpected.