supercov 0.0.44 → 0.0.45

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 --require-observed --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,22 @@ 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:
+Every new test run creates `assertions.json`. To investigate what tests assert:
 
 ```sh
-npx supercov runs latest assertions --file app/checkout/session.ts --limit 5 --json
-npx supercov runs latest assertions --pragmas --json
+npx supercov runs latest assertions --json
+# Pin data.run and edit the file at data.map.
 ```
 
-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.
+Inspect an entry with `runs <run> assertion <id>` and read archived code with
+`runs <run> source <path>`. Edit its `assertions.json`, declare credited nodes
+and broader watch inputs, then obtain expectedBasis tokens with `assertions validate --json` and save the examined tokens in the map or repeated `--flow ASSERTION/FLOW`. After the next run of
+the same command, its map automatically inherits prior work; repair affected entries. Supercov
+validates references and freshness, while the agent owns semantic meaning.
+Run `supercov docs assertion-agent` for the full mapping instructions. Validate
+with `runs <run> assertions validate`, save examined expectedBasis tokens in the map, then use
+`runs <run> assertions check --require-mappings --require-observed` as the
+completion gate. See [assertion maps](assertion-maps.md) for the contract and JS/TS limits.
 
 ## Example
 

package/docs/assertion-agent.md

@@ -0,0 +1,156 @@
+# Agent workflow for assertion maps
+
+You are the semantic author. Supercov supplies source identities, execution
+records, file hashes and a JSON validator. It does not infer or prove your
+explanations. Use your ordinary source-reading tools and edit one run-owned
+`assertions.json`; no model is embedded in Supercov.
+
+## Start with a real run
+
+1. Run the intended suite through `supercov -- <test command>` if no matching
+   current run exists. Use the full suite for a suite-wide result.
+2. Read `supercov runs --json`, pin its concrete run ID, then read
+   `supercov runs <run> assertions --json`. Edit `data.map`; the run creates it
+   automatically and inherits compatible prior work. Check `data.inheritance`
+   for fallback errors. Keep old runs and their maps.
+3. Read `supercov docs assertion-maps`. Page the assertion, statement, test and
+   change views. Do not mistake one page for the whole suite:
+
+   ```sh
+   supercov runs <run> assertions --limit 100 --json
+   supercov runs <run> assertions report --view statements --limit 100 --json
+   supercov runs <run> assertions report --view tests --limit 100 --json
+   supercov runs <run> assertions report --view changes --limit 100 --json
+   ```
+
+Follow `pagination.nextOffset` with `--offset`; restart if `revision` changes.
+Use a single map writer. Save edits atomically where your editor supports it.
+The outer object contains `schemaVersion: 2` and `assertions`; do not insert run IDs.
+
+## Investigate precise claims
+
+Read current test setup, inputs, mocks, callbacks, branches, callees, helper
+modules and relevant configuration. Current files must match the pinned run.
+Supercov retains hashes and identities, not a source checkout. Optional
+`runs <run> source <path> --offset 0 --limit 100` prints matching code with line
+numbers; `assertions files` lists input hashes even when files no longer match.
+
+Use `runs <run> assertion <id>` for the exact site and graph. Preserve its ID and
+full `at` anchor, usually the complete assertion call without a trailing semicolon.
+Use one-based UTF-8 byte columns, not character counts. An `inMap: false` site
+was recognized but is missing from the map; restore it when investigating.
+
+For each assertion:
+
+- Describe exactly what its predicate distinguishes in `observes`. Truthiness,
+  existence, length or substring checks do not imply equality of every field.
+- Write independently maintainable flows with stable IDs, `basis: null`, a
+  concrete explanation, exact nodes and authored edges to `$assertion`.
+- Use explicit `appliesTo: [{file, name}]` from the test view. File and name
+  must resolve unambiguously. Empty means no credit. Runtime IDs never belong
+  in selectors. Shared/parameterized sites may need multiple cases or flows.
+- Take production statement anchors from the `statements` view when possible.
+  Put only nodes you judge asserted in `countsAsAsserted`. Each counted node
+  needs an authored path to `$assertion`; a block does not credit nested code.
+- Put additional dependency paths in `watch`, as whole-file strings. Assertion,
+  selected-test and node files are already dependencies. Include setup, guards,
+  alternate paths and helpers your explanation relies on, even without nodes.
+- Preserve uncertainty in `questions`. Flow questions block that flow's credit.
+  Assertion questions record unfinished exploration without implying a known
+  total. There is no `analysis`, `mapped`, or `complete` flag.
+- A fixture-only or absence explanation can have `countsAsAsserted: []`. Explain
+  the absence, including ordering/barriers and the observation window. Never
+  credit an unexecuted body just because its execution would violate a check.
+
+Inspect `selectors`, `blockers`, `reasons`, empty `observedPassingTests`, and
+statement `at: null` entries. They may represent skipped tests, unsupported
+syntax, ambiguous test names or missing evidence. Do not borrow another site's
+identity, fabricate events, delete inconvenient entries or edit managed state.
+Zero-credit explanations are useful; invented credit is not.
+
+## Account for changes before finalizing flow tokens
+
+When inheriting a map, inspect **every** item in `--view changes`, including files
+already watched by some flows. Dependencies may be missing. In root
+`changeAssessments`, write one response per managed change ID:
+
+```json
+{
+  "id": "c_copy_from_changes_view",
+  "basis": null,
+  "affectedFlows": ["assertion-id/flow-id"],
+  "explanation": "What changed, which claims it affects, and why other existing claims remain valid."
+}
+```
+
+Include all known dependent flows still present, plus any others affected.
+Repair watches if the change reveals a missing dependency. An empty list needs
+an actual explanation. Removing a response does not clear the outstanding change.
+A changed test/assertion can affect all its flows; a production file used by one
+sibling may affect only that flow. No machine can tell you an expected flow total.
+
+Save the responses and graph edits. Run:
+
+```sh
+supercov assertions validate --file <map-path> --json
+supercov runs <run> assertions validate --json
+```
+
+For large maps, page `validate --view changes`, `validate --view flows`, or
+`validate --view errors` with `--offset` and `--limit`; tokens appear under
+`items` and overall validity still covers the whole map. Pin `revision` across pages.
+
+Validation checks shape, IDs, graph links, anchors and state binding. It returns
+`changes[].expectedBasis` and `flows[].expectedBasis`; null/stale tokens alone
+are unfinished work, not syntax errors. Copy change tokens **only after inspecting
+those impact assessments**, then save. Validate again and copy flow tokens only
+for claims you have examined. Save the map again. Change acknowledgements can
+invalidate additional flows, so obtain final flow tokens after change tokens.
+Changing a graph, selector, observation or watch after obtaining its token makes
+that token stale. Do not implement the hashing algorithm or manufacture tokens.
+
+There is no `review` command. All commands are read-only; acknowledgement is your
+explicit file edit. Passing reference validation does not prove your reasoning.
+
+## Check and report
+
+```sh
+supercov runs <run> assertions check --require-mappings --require-observed --json
+supercov runs <run> assertions report --view statements --limit 100 --json
+supercov runs <run>
+```
+
+Basic `check` permits untouched sites without flows, but fails on invalid or
+unfinished authored claims, open questions and outstanding change impact.
+`--require-mappings` requires at least one current observed explanation for every
+recognized passing site, including legitimate zero-credit explanations.
+`--require-observed` checks every site and selector. Neither means every semantic
+flow was found. Use `--min <percentage>` only for the project's chosen target.
+Do not lower a target or hide unknowns to make a check pass.
+
+The normal report includes the percentage immediately from the edited file.
+`notAssessed`, `pending`, `unavailable` and `notApplicable` have null percentages,
+not fabricated zeroes. A numeric partial-map result still reports counts of
+assertions without flows and claims needing work. Describe the score as
+agent-assessed statements; successful same-test coexecution is evidence, not
+proof of causality or mutation resistance.
+
+## Continue after edits
+
+Run the same suite command again. The new run carries IDs, explanations and
+unchanged acknowledgements using prior file hashes, without needing old source.
+Use `assertions --needs-attention` and the change view. Repair only affected
+claims; keep current siblings. Any dependency byte edit, including comments,
+requires rechecking. Unique relocation preserves identity as a suggestion;
+ambiguous/removed sites remain in `retiredAssertions`. Old v1 flows are imported
+as drafts with questions about selectors and graph paths; inspect them explicitly.
+
+Do not edit `assertions.state.json`. Dirty generations persist across reruns and
+reverts until current tokens are recorded. Resolved change responses are folded
+and retired on the next publication. Runtime evidence never carries forward.
+If source differs from the pinned run, rerun tests before continuing.
+
+Finish with the pinned run ID, status, numeric percentage/counts when available,
+assertions without flows, remaining questions/stale or unobserved claims, and
+verification commands used. Explain remaining limits. The property in `observes`
+matters: changing a credited line while preserving that property can still pass.