supercov 0.0.46 → 0.0.48

package/docs/assertion-maps.md

@@ -70,7 +70,7 @@ examined and acknowledged.
 | `appliesTo` | Select tests by project-relative file and exact displayed test name. |
 | `nodes`, `edges` | Record source locations and relationships ending at `$assertion`. |
 | `countsAsAsserted` | List the node IDs you judge to be checked by the assertion. |
-| `watch` | List additional files the explanation depends on, such as helpers or configuration. |
+| `watch` | List additional files the explanation depends on, such as helpers or configuration. Manifests, lockfiles and runner configuration are already tracked for the whole run; naming one here catches nothing, and the report says so. |
 | `questions` | Record unresolved investigation questions. Questions inside a flow block its credit. |
 
 Source anchors use project-relative paths with `/`, one-based lines and one-based
@@ -105,6 +105,46 @@ After examining a flow, copy its returned `expectedBasis` into that flow's
 do not generate it yourself. Editing a claim or its dependencies makes the old
 token stale.
 
+### What makes a review token stale
+
+A flow needs a fresh review when its claim changes, when a file it watches or a
+test it selects changes, or when the configuration that decides what executes
+changes: a transpiler, a test runner, an interpreter pin.
+
+Several things that sound like they should count do not, because an
+acknowledgement demanded for all of them at once stops being read.
+
+Cutting a release does not. A manifest is fingerprinted by what it declares, so
+a version number moving in `package.json`, `Cargo.toml`, `pyproject.toml` or a
+lockfile changes nothing. Neither does reformatting one.
+
+Upgrading Supercov does not. Your claims are about your code, and a new release
+re-derives the evidence they rest on rather than making them wrong. Only a
+deliberate change to the instrumenter contract counts.
+
+Upgrading a dependency does not make every flow stale either. It is recorded
+once, as a change to assess, and flows keep their credit until that assessment
+says otherwise. One explanation answers for the upgrade.
+
+Linters, formatters, type checkers and coverage settings never count, because
+none of them change what the code does when it runs.
+
+The ambient environment does not count: running from another directory, a new
+terminal session, a different package manager or another Node installation
+leaves current flows current. A behavioural difference that matters still shows
+up on its own, because credit requires a passing assertion occurrence and
+execution of the claimed statement in the same selected test.
+
+If your suite genuinely depends on particular variables, name them; only the
+ones you name participate, and an unset variable is recorded as absent.
+
+```sh supercov-example
+SUPERCOV_ASSERTION_CONTEXT_ENV=TZ,LANG npx supercov -- npm test
+```
+
+Use the same list for every run. Changing it changes the recorded context and
+asks for a fresh review.
+
 ```sh supercov-example
 npx supercov runs <run-id> assertions check --require-mappings
 npx supercov runs <run-id>

package/docs/assertions.md

@@ -1,132 +1,111 @@
-# Understanding assertion coverage
+# Assertion coverage
 
-Assertion coverage helps you see which parts of your JavaScript or TypeScript
-code are checked by tests. After a normal run, your coding agent records what
-each assertion checks in `assertions.json`. Supercov combines that map with the
-run's execution evidence and shows an **Assertions** percentage alongside Lines,
-Branches and MC/DC.
+Line coverage shows which code ran. Assertion coverage helps you see what the
+tests checked. Your coding agent traces assertions back to the source, and
+Supercov checks those links against recorded execution from the same test.
 
-## Start with your existing tests
+Assertion coverage measures JavaScript, TypeScript, Python, Ruby and Rust. The
+map format is the same for every one of them: an assertion is identified by its
+file, line and column, so a project written in more than one language keeps a
+single map.
 
-```sh supercov
-npx supercov -- npm test
-npx supercov runs latest assertions
-```
-
-Use your project's test command after `--`. Each run creates its own map and
-reuses compatible work from earlier runs of the same command. The assertions
-list shows the map's path and the assertions that still need attention.
+Python and Ruby report an assertion's line but not its column, so two
+assertions written on one line cannot be told apart and neither is credited.
+Put them on separate lines.
 
-Copy the printed run ID before asking an agent to edit the map. This keeps its
-work on the same run even if another test run finishes. You can give it this
-prompt, replacing `<run-id>` with that ID:
-
-```text
-Read the instructions from npx supercov docs assertion-agent. Build or update
-assertion coverage for run <run-id>. Investigate the tests and current source,
-then edit that run's assertions.json. Preserve reusable flows and explain
-uncertainty. Do not change application code or tests. Validate the map and
-show the assertion percentage, remaining gaps, and any missing evidence.
-```
+## A passing test can miss a wrong result
 
-You can use your usual coding agent. Supercov does not require a particular
-model or make model calls itself.
+This function confirms an order and calculates its total:
 
-## Read the percentage
-
-```sh supercov-example
-npx supercov runs <run-id>
+```js
+export function checkout(price, quantity) {
+  const total = price * quantity;
+  return { status: 'confirmed', total };
+}
 ```
 
-An illustrative report might show:
+The test checks the status, but not the total:
 
-```text
-Assertions 62.50% (50/80) — agent-assessed statements, whole run
-  18 assertions with flows; 7 without; 29 current flows; 3 stale; 2 draft
+```js
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { checkout } from './checkout.js';
+
+test('confirms an order', () => {
+  const order = checkout(25, 2);
+  assert.equal(order.status, 'confirmed');
+});
 ```
 
-Here, 50 of the run's 80 measured statements have a current explanation linking
-them to a passing assertion, with execution recorded in the same test. Each
-statement counts once, even when several assertions check it. Unexecuted code
-stays in the denominator. TypeScript imports that are known to disappear during
-compilation are excluded.
+Every line in the function runs. The test passes. But it would also pass if the
+total were `49` instead of `50`.
 
-The score describes the whole run. Filtering Lines or MC/DC by test kind does
-not change the assertion percentage. You do not need to rerun tests just to
-recalculate a map: save it and query the run again.
+## How the agent finds the gap
 
-| Report state | What to do |
-| --- | --- |
-| Not assessed | Ask your agent to start explaining the assertions. |
-| Pending | Inspect changed inputs, draft flows or stale flows before using a percentage. |
-| Unavailable | Check for a failed run, invalid map or source that no longer matches the run. |
-| Not applicable | The run has no measured statements. |
+1. **Supercov records execution:** which statements ran in each test and which
+   assertions passed.
+2. **Your agent traces each assertion** through the test and source to explain
+   what it checks. It saves those links in the run's `assertions.json` map.
+3. **Supercov checks the map against the run.** A statement needs a current
+   explanation, execution, and a passing assertion in the same test to count.
 
-A partially written map can have a useful percentage. Check the counts beside
-it: having some flows does not mean every relevant flow has been found.
+In this example, the agent follows the status assertion back to the returned
+order. It finds no check that reads the total:
 
-## Check what an assertion actually protects
+- `order.status` → must equal `'confirmed'`.
+- `order.total` → no assertion checks the calculated total.
 
-Suppose `src/shipping.js` contains:
+The agent adds the missing assertion to the existing test:
 
 ```js
-export function shippingCost() {
-  return 4;
-}
+assert.equal(order.total, 50);
 ```
 
-These tests all call the function, but they check different things. Here,
-`assert` comes from `node:assert/strict`:
-
-| Assertion | What it checks |
-| --- | --- |
-| `assert.equal(shippingCost(), 4)` | The cost is exactly `4`. Returning `5` would fail. |
-| `assert.ok(shippingCost())` | The cost is truthy. Returning `5` would still pass. |
-| `shippingCost(); assert.equal(7, 7)` | Nothing about the returned cost. The assertion compares constants. |
+It reruns the full suite and updates the map. A total of `49` now fails the
+test: two items at $25 must total $50. Line coverage has not changed, but the
+test now checks the calculation.
 
-Line coverage can be the same in all three cases. Even a credited statement can
-change without failing a test when the new value still satisfies the assertion.
-Read the mapped observation when deciding whether a test protects your change.
+## Try it in your project
 
-## Inspect a gap
+Open your project in your usual coding agent and paste this prompt. The agent
+can install Supercov and run the commands for you.
 
-```sh supercov-example
-npx supercov runs <run-id> assertions --needs-attention --limit 5
-npx supercov runs <run-id> assertion <assertion-id>
-npx supercov runs <run-id> assertions report --view statements --file src/shipping.js
-npx supercov runs <run-id> source src/shipping.js
+```text supercov-prompt
+Read npx supercov docs assertion-agent. Run the full test suite through
+Supercov, then build and validate its assertion map. Find one useful
+missing check and add an assertion for the expected behavior.
+Only change tests; do not weaken existing checks. Rerun the same suite
+and update the map. Show the test change, before-and-after assertion
+coverage, and any uncertainty or missing evidence.
 ```
 
-An assertion detail shows its exact location in the test, its recorded flows,
-and why each source node is credited, not credited or context only. Use this to
-find a missing scenario, strengthen a weak check or correct an explanation.
-See [Investigating assertion evidence](assertion-evidence.md) when execution
-or a passing assertion is missing.
+The agent uses your actual test command after `--`, for example
+`npx supercov -- npm test`. On later runs of the same command, Supercov reuses
+compatible mappings and flags explanations that need another look.
 
-An absence check, such as “no message was received,” can be useful without
-crediting a message-sending statement that never ran. Its map should explain
-what was observed, when observation ended and why that was sufficient.
+## Read the result
 
-## Keep the map when code changes
+The agent can show the summary and the statement-level report for a file:
+
+```sh
+npx supercov runs <run-id>
+npx supercov runs <run-id> assertions report --view statements --file checkout.js
+```
 
-Run the same suite command again after editing source or tests. Supercov copies
-reusable mappings into the new run and identifies flows that need another look.
-One changed dependency can affect a single flow; changing the assertion itself
-can affect all its flows. Your agent can update those parts instead of starting
-over.
+**Assertions** is the percentage of measured source statements linked to
+passing assertions by the agent's map. It is not a count of assertions. Each
+statement counts once; statements that never ran remain in the total.
 
-Investigation uses your current project files. A run retains the map and file
-identities, but does not keep a complete source checkout. If the source no
-longer matches, rerun tests before continuing the map.
+An unmapped statement is a place to investigate, not proof of a missing test:
+the agent may not have mapped its existing check yet.
 
-## Use the score to guide changes
+The strength of the check still matters. `assert.ok(order.total)` accepts both
+`49` and `50`; `assert.equal(order.total, 50)` distinguishes them. Review the
+expected behavior, not just the percentage.
 
-Use MC/DC to find missing condition cases and assertion coverage to investigate
-what those tests check. Improve the weakest observations and the gaps relevant
-to your change, then run the full suite again.
+Supercov does not generate or execute mutated code for this assessment. Unlike
+mutation testing, it does not test whether deliberately introduced bugs are
+caught. The agent's explanations still need review.
 
-Neither percentage proves that every possible bug will fail a test. A high
-score is most useful together with the recorded observations and a review of
-the behavior you intend to preserve. See [Assertion map format](assertion-maps.md)
-for editing and validation, or [Trusting results](verification.md) for the
-broader test-review workflow.
+For the detailed workflow, see [Mapping assertions with an agent](assertion-agent.md).
+For a result you cannot explain, see [Investigating assertion evidence](assertion-evidence.md).

package/docs/cli.md

@@ -132,6 +132,115 @@ report. Follow the printed next-page command or JSON `pagination.nextOffset`.
 Validation supports `--view flows`, `--view changes` and `--view errors` for large
 maps. The [map reference](assertion-maps.md) describes all fields and gates.
 
+## Fail CI below a coverage floor
+
+```sh supercov-example
+supercov runs check --min-lines 90 --min-branches 80 --min-mcdc 80
+supercov runs check --min-lines 100 --per-file --json
+```
+
+`check` reads a recorded run; it never runs tests again. Give a floor per metric
+with `--min-lines`, `--min-statements`, `--min-functions`, `--min-branches` or
+`--min-mcdc`. `--per-file` applies the same floors to every file that has
+eligible obligations, in addition to the whole run. Both report the counts
+behind the percentage and, for lines, where the gaps are.
+
+Floors are compared against the counts, never a rounded percentage: 9,999
+covered lines out of 10,000 displays as 99.99% and fails a 100% floor, and a
+run that displayed `100.00%` could never pass one while something is uncovered.
+
+A check answers only when the run can answer. These end the command with `2`
+rather than a pass or a failure:
+
+- the wrapped test command did not pass, so a gate over it would turn a red CI
+  run green
+- the run no longer matches the current checkout
+- a requested metric has nothing eligible, which is not the same as complete
+- a requested metric left obligations unmeasured, so no exact judgement exists
+- a requested metric is not recorded by the language adapter
+
+Assertion coverage keeps its own check. Whether a test *examines* what it
+executes is a different question from whether a line ran, and
+`runs <id> assertions check` carries the freshness and acknowledgement rules
+that answer needs.
+
+## Check the lines a change touches
+
+```sh supercov-example
+supercov runs patch --base origin/main --min-lines 100
+supercov runs patch --base origin/main --annotate github
+```
+
+`patch` answers whether the lines this change added or modified are tested. It
+compares against the **merge base** with `--base`, not that branch's tip, so
+commits other people landed after you branched are not counted as your
+obligation. A shallow checkout has no merge base; fetch with full history
+(`actions/checkout` takes `fetch-depth: 0`).
+
+The denominator is the changed lines the run measured. Comments, blank lines and
+declarations fall out because the language adapter already decided they are not
+executable, not because `patch` guesses at syntax. Deleted lines are excluded:
+there is nothing left to cover. Untracked new source counts as entirely added.
+
+A change with nothing executable in it reports **No executable changes** and
+passes, rather than claiming 100% for a patch that changed only comments. A
+changed file that looks like product source but is absent from the run is named
+separately, because treating it as zero uncovered lines would report success for
+code nothing ran.
+
+`--annotate github` prints workflow-command annotations on stdout, combining
+adjacent misses into one range and capping the total (`--max-annotations`). It
+needs no token and posts no comment.
+
+## Export for other tools
+
+```sh supercov-example
+supercov runs report --format lcov --output coverage/lcov.info
+supercov runs report --format cobertura --output coverage/cobertura.xml
+supercov runs report --format html --output coverage/report
+```
+
+Both are written from the same view `check` and `patch` read, so a viewer,
+hosted service or CI integration sees the totals Supercov enforced. Paths are
+repository-relative with forward slashes, ordering is stable, and the file is
+written atomically; an existing file is kept unless you pass `--force`. Without
+`--output` the report goes to stdout and diagnostics to stderr, so a redirect
+captures only the report.
+
+Supercov records that a line ran, not how many times, so `DA:` and `hits` state
+`1` or `0`. They are not execution frequencies, and Supercov will not invent
+one to fill a field.
+
+MC/DC conditions are not exported as ordinary branches. A consumer would then
+show condition obligations as branch coverage, which is a different
+measurement; that evidence stays in the JSON view and the HTML report. A report
+from a failed or stale run is still written, with a warning on stderr — only
+`check` refuses to pass on one.
+
+### The HTML report
+
+`--format html` writes one self-contained document. It opens from a copied CI
+artifact with no server, no network and no login, and nothing is fetched from a
+CDN. Because a source path is never used as an output path, a filename cannot
+write outside the directory you named, and no directory is ever cleared to
+regenerate a report.
+
+It has three levels: the run's metric counts, a filterable and sortable file
+table, and a source view marking each line covered or not covered in words and
+a glyph as well as colour. Every line links as `#<file>:<line>`, so a CI summary
+can point someone at the obligation rather than at the report.
+
+Four states stay distinct, because collapsing them into one score is how a
+report starts to mislead: **uncovered** (measured, nothing reached it), **not
+applicable** (nothing eligible), **partly measured** (Supercov declined some
+obligations, which are excluded from every count) and **stale** (the run no
+longer matches the checkout). A failed suite says so beside its numbers.
+
+Source text is embedded only when the run still matches the checkout; otherwise
+the report shows line numbers and explains why. Embedding makes a report
+portable and also means it contains your code — worth knowing before uploading
+one as a public artifact.
+
 ## Narrow a view
 
 | Option | Meaning |
@@ -233,4 +342,5 @@ SUPERCOV_TEST_KIND=e2e npx supercov -- npx playwright test
 | --- | --- |
 | `0` | The command or query succeeded |
 | Wrapped command's code | The test command failed and Supercov preserved its status |
-| `2` | Supercov could not complete the request |
+| `1` | A valid measurement failed a policy you set, such as a coverage floor |
+| `2` | Supercov could not complete the request, or the evidence cannot answer it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "description": "Coverage for coding agents and software factories \ud83c\udf19",
   "license": "MIT",
   "repository": {
@@ -94,14 +94,14 @@
     "docs:check": "node scripts/sync-docs.mjs --check"
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "0.0.46",
-    "@supercov/cli-darwin-x64": "0.0.46",
-    "@supercov/cli-linux-arm64-gnu": "0.0.46",
-    "@supercov/cli-linux-arm64-musl": "0.0.46",
-    "@supercov/cli-linux-x64-gnu": "0.0.46",
-    "@supercov/cli-linux-x64-musl": "0.0.46",
-    "@supercov/cli-win32-arm64": "0.0.46",
-    "@supercov/cli-win32-x64": "0.0.46"
+    "@supercov/cli-darwin-arm64": "0.0.48",
+    "@supercov/cli-darwin-x64": "0.0.48",
+    "@supercov/cli-linux-arm64-gnu": "0.0.48",
+    "@supercov/cli-linux-arm64-musl": "0.0.48",
+    "@supercov/cli-linux-x64-gnu": "0.0.48",
+    "@supercov/cli-linux-x64-musl": "0.0.48",
+    "@supercov/cli-win32-arm64": "0.0.48",
+    "@supercov/cli-win32-x64": "0.0.48"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",