supercov 0.0.44 → 0.0.46

package/README.md

@@ -46,22 +46,30 @@ npx supercov -- python -m unittest
 npx supercov -- bundle exec rspec
 ```
 
-## Inspect assertion evidence (JS/TS)
+## Map what assertions check
 
-After a run, inspect what existing assertions appear to check:
+Each normal test run creates an assertion map automatically. An agent can
+optionally fill in what the assertions check:
 
 ```sh
-npx supercov runs latest assertions --limit 5
-npx supercov runs latest assertions --pragmas --json
-npx supercov runs latest assertions --evidence /tests --limit 5 --json
+npx supercov runs latest assertions --json
+# Pin the returned run ID. Inspect assertions and the source that ran:
+npx supercov runs <run> assertion <assertion-id>
+npx supercov runs <run> source src/example.ts
+# Edit assertions.json, then validate and acknowledge:
+npx supercov runs <run> assertions validate --json
+# Copy examined expectedBasis tokens into assertions.json; save again.
+npx supercov runs <run> assertions check --require-mappings --json
+npx supercov runs <run>  # includes the assertion percentage in the regular report
 ```
 
-This npm-only query uses the run archive and matching source; it adds no new
-test-time instrumentation. It requires a compatible project TypeScript compiler
-API (5.8.3 and native 7.0.2 are tested). Results are candidates, not proof
-that changes are safe or a verified assertion percentage. Follow
-[`assertion-evidence.md`](docs/assertion-evidence.md) for provenance, optional
-assertion hints, pagination, and limitations.
+After code or tests change, run the same test command again. Supercov reuses the
+newest available map for that command and language and identifies dirty flows. Rust owns
+validation, change tracking and reporting; the agent supplies semantic reasoning.
+The score is agent-assessed and separate from MC/DC. See
+[assertion maps](docs/assertion-maps.md) for the format and JS/TS limits, or run
+`supercov docs assertion-agent` for the agent workflow. `supercov assertions schema`
+exports the editor schema; `assertions validate --file <path>` checks JSON syntax.
 
 ## Give Supercov a job
 
@@ -170,7 +178,7 @@ Supercov uses exact per-test attribution where an adapter is available. For othe
 | --- | --- |
 | Playwright | Exact per test, worker, retry, outcome, action, and assertion phase |
 | Vitest | Exact per test, with setup execution kept separate |
-| Jest | Exact per test, including parameterized tests; `expect` assertions link the evidence they check |
+| Jest | Exact per test, including parameterized tests; exact `expect` occurrence identity for assertion maps |
 | `node:test` | Exact per test |
 | AVA and Mocha | Aggregate structural coverage |
 | Cargo's standard libtest runner | Exact test, attempt, and passing-assertion identity |
@@ -223,6 +231,7 @@ npx supercov clean             # remove all runs and the build cache
 
 - [Getting started](https://supercov.com/docs/getting-started)
 - [Agent workflow](https://supercov.com/docs/agent-loop)
+- [Understanding assertions](docs/assertions.md)
 - [Troubleshooting](https://supercov.com/docs/troubleshooting)
 - [CLI reference](https://supercov.com/docs/cli)
 - [Supported languages and test suites](https://supercov.com/docs/supported-suites)

package/docs/agent-loop.md

@@ -53,18 +53,26 @@ The `line` query is useful before writing a test because it shows which tests
 already reach that line. Extending a nearby test is often better than adding a
 duplicate.
 
-For supported JS/TS projects, inspect assertion evidence before adding tests:
+## Add assertion coverage
 
-```sh
-npx supercov runs latest assertions --file app/checkout/session.ts --limit 5 --json
-npx supercov runs latest assertions --pragmas --json
+For JavaScript and TypeScript projects, you can also ask the agent to explain
+what each test assertion checks. Every normal run creates an `assertions.json`
+map and carries forward compatible work from earlier runs of the same command.
+
+```sh supercov
+npx supercov runs latest assertions
+npx supercov docs assertion-agent
 ```
 
-This post-run query needs the matching source and a compatible
-project TypeScript API. An `evident` candidate is not a proof of safety; keep
-test gaps separate from analysis limits. Follow the returned evidence pointers
-and `pagination.nextOffset`, pinning `--analysis` and the run id while paging.
-See [assertion evidence](assertion-evidence.md) for requirements and examples.
+Keep the printed run ID fixed while editing. The agent reads matching current
+source, updates the map, validates its references and saves review tokens for
+the explanations it examined. The regular run report then shows the assertion
+percentage. It does not need another test run just to read the edited map.
+
+Start with [Understanding assertion coverage](assertions.md) for a copyable
+prompt. [Mapping assertions with an agent](assertion-agent.md) gives the complete
+editing and checking loop. Use the evidence and recorded observations alongside
+MC/DC when deciding which tests need stronger checks.
 
 ## Example
 

package/docs/assertion-agent.md

@@ -0,0 +1,146 @@
+# Mapping assertions with an agent
+
+Use these instructions when asking a coding agent to create or update an
+assertion map. The agent reads your tests and source, explains what each
+assertion checks, and edits the run's `assertions.json`. Supercov supplies the
+run evidence and checks the file's references and freshness.
+
+Start with [Understanding assertion coverage](assertions.md) for a prompt you
+can copy. The steps below are the agent's working instructions.
+
+## Choose a run and keep it fixed
+
+1. Use a matching current run, or run the requested suite through
+   `supercov -- <test command>`. Use the full suite for a suite-wide result.
+2. Read `supercov runs latest assertions --json` and keep `data.run` fixed for
+   this investigation. Edit the file at `data.map`.
+3. Check `data.inheritance` for reused work or fallback errors. Keep the old
+   runs and maps. Inspect changes before renewing inherited flows.
+4. Read the [map format](assertion-maps.md), also available through
+   `supercov docs assertion-maps`.
+
+Use a single writer for the map. Save atomically if your editor supports it.
+Do not change application code or tests unless the user also requested those
+changes. Never edit `assertions.state.json` or the run's recorded evidence.
+
+## Inspect the assertions and source
+
+```sh supercov-example
+npx supercov runs <run-id> assertions --limit 100 --json
+npx supercov runs <run-id> assertions report --view statements --limit 100 --json
+npx supercov runs <run-id> assertions report --view tests --limit 100 --json
+npx supercov runs <run-id> assertions report --view changes --limit 100 --json
+npx supercov runs <run-id> assertion <assertion-id>
+npx supercov runs <run-id> source src/shipping.js --offset 0 --limit 100
+```
+
+Follow every `pagination.nextOffset`; a page is not the whole result. Restart a
+paged read if its `revision` changes. Current source must match the pinned run.
+Use ordinary source-reading tools to inspect setup, inputs, mocks, callbacks,
+branches, called functions, helpers and relevant configuration.
+
+Preserve each assertion's ID and complete `at` anchor. Locations use one-based
+lines and UTF-8 byte columns. Restore recognized sites marked `inMap: false`
+when investigating them; removing an entry does not remove the assertion from
+Supercov's list.
+
+## Write precise explanations
+
+For each assertion:
+
+- Describe exactly what its predicate distinguishes in `observes`. Existence,
+  truthiness, length and substring checks do not imply equality of every field.
+- Split independently maintainable explanations into flows with stable IDs.
+  Start a new or changed flow with `basis: null`.
+- Choose `appliesTo` tests from the tests view using their exact file and name.
+  Select applicable cases explicitly for shared or parameterized assertions.
+- Use complete source statements from the statements view as node anchors when
+  possible. Write the relationships that connect those nodes to `$assertion`.
+- Put a node in `countsAsAsserted` only when its behavior is checked by this
+  assertion. Every counted node needs a recorded path to `$assertion`.
+  Counting a guard or block does not count the nested body automatically.
+- Add helper, configuration and other dependency files to `watch`. Assertion,
+  selected-test and node files are already dependencies. Include relevant guards
+  and alternatives even when they do not appear as graph nodes.
+- Keep uncertainty in `questions`. A flow's unresolved questions block its
+  credit. Assertion-level questions record broader unfinished investigation.
+
+A fixture-only or absence explanation can have `countsAsAsserted: []`. For
+absence, describe the ordering or barrier and the observation window. Never
+credit an unexecuted body merely because executing it would violate the check.
+
+There is no known number of flows an assertion should have. Do not label an
+assertion complete just because you recorded one explanation.
+
+## Check why a node receives no credit
+
+Read the node's credit reason in assertion detail, or its computed `nodeCredit`
+entry in JSON. Compare the statement's execution evidence and selected test's
+outcome. Keep these report fields out of the editable map.
+
+A source node can be context only, lack a measured statement, have stale inputs,
+or lack matching passing assertion and execution evidence. Shared setup and
+background execution do not count as execution by every consuming test. Skipped
+and TODO tests supply no passing witness. An unobserved site in a passing test
+can indicate an untaken branch or missing measurement.
+
+Do not borrow another assertion's identity or another test's execution. Preserve
+zero-credit explanations when they accurately describe what the test checks.
+Use `assertions report --view excludedStatements` to inspect erased TypeScript
+imports. See [Investigating assertion evidence](assertion-evidence.md) for
+asynchronous and missing-evidence cases.
+
+For a large flow, page `assertion <id> --flow <flow-id> --view nodes --json` and
+`--view edges` separately. `--compact` omits repeated source text from the
+report; read the matching source separately and never save the compact objects
+back into the map.
+
+## Assess changes before renewing flows
+
+When inheriting a map, read every entry in `--view changes`. Recorded file
+watches are a starting point; investigate whether other flows are affected too.
+
+Add a `changeAssessments` entry for each managed change ID. Include all listed
+`knownFlows` that still exist, plus any other affected flows. Explain why the
+remaining claims are unaffected. An empty affected-flow list needs a reason.
+Repair missing watches and update the affected graphs or selectors.
+
+Save these edits, then validate:
+
+```sh supercov-example
+npx supercov assertions validate --file <map-path> --json
+npx supercov runs <run-id> assertions validate --view changes --json
+npx supercov runs <run-id> assertions validate --view flows --json
+```
+
+Page the validation views too. Overall validity covers the whole map even when
+only one page is returned. Copy change `expectedBasis` tokens only after
+examining the corresponding impact assessments, then save. Validate again and
+copy flow tokens only for the claims you have examined.
+
+Obtain final flow tokens after saving change tokens: a change assessment can
+invalidate additional flows. Treat tokens as opaque; do not implement their
+hashing or manufacture them. Changing a claim after getting its token makes
+that token stale.
+
+## Check and summarize
+
+```sh supercov-example
+npx supercov runs <run-id> assertions check --require-mappings --json
+npx supercov runs <run-id> assertions report --view statements --limit 100 --json
+npx supercov runs <run-id>
+```
+
+Add `--require-observed` when every mapped site and test selector is expected to
+have passing evidence. Report skipped, TODO or untaken cases when that gate is
+unmet. Use `--min <percentage>` only for the user's chosen target; do not lower
+it or hide gaps to make a check pass.
+
+Report the run ID, map path, assertion percentage and counts, unresolved changes,
+missing execution and useful next tests. Distinguish statements credited by the
+map from raw line coverage and MC/DC. Mention which claims were newly examined
+and which were reused.
+
+A valid file does not prove the explanation or its completeness. A credited
+statement can change without failing a test when the edit preserves the observed
+property. Keep that distinction clear when recommending code changes.