supercov 0.0.45 → 0.0.46

package/README.md

@@ -59,7 +59,7 @@ 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> assertions check --require-mappings --json
 npx supercov runs <run>  # includes the assertion percentage in the regular report
 ```
 

package/docs/agent-loop.md

@@ -53,22 +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.
 
-Every new test run creates `assertions.json`. To investigate what tests assert:
+## Add assertion coverage
 
-```sh
-npx supercov runs latest assertions --json
-# Pin data.run and edit the file at data.map.
+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
 ```
 
-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.
+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

@@ -1,156 +1,146 @@
-# 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.
+# 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
+```
 
-For each assertion:
+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.
 
-- 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."
-}
-```
+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.
 
-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.
+## Write precise explanations
 
-Save the responses and graph edits. Run:
+For each assertion:
 
-```sh
-supercov assertions validate --file <map-path> --json
-supercov runs <run> assertions validate --json
+- 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
 ```
 
-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.
+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.
 
-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.
+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.
 
-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 summarize
 
-## 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>
+```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>
 ```
 
-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.
+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.

package/docs/assertion-evidence.md

@@ -1,9 +1,103 @@
-# Assertion evidence
-
-The earlier automatic JS/TS analyzer has been replaced by agent-authored
-assertion maps. Use [Understanding assertion coverage](assertions.md) to get
-started, [Agent-authored assertion maps](assertion-maps.md) for the file format
-and CLI reference, and [the agent instructions](assertion-agent.md) to build or
-update a map. Existing structural runs remain readable; mapping requires a new
-run with an assertion input manifest. Old `--pragmas`, `--analysis` and `--evidence`
-options do not apply to the map workflow.
+# Investigating assertion evidence
+
+Use assertion details when a statement runs but receives no assertion credit,
+or when a mapped assertion has no passing occurrence. The report shows the
+recorded explanation and the evidence supporting it separately.
+
+```sh supercov-example
+npx supercov runs <run-id> assertions --needs-attention --limit 5
+npx supercov runs <run-id> assertion <assertion-id>
+```
+
+Replace the placeholders with the run and assertion IDs from your report.
+
+## Follow one assertion
+
+The detail identifies the exact assertion in the test and the source nodes in
+each flow. Each node has an explanation and a credit decision:
+
+| Decision | Meaning |
+| --- | --- |
+| Credited | The map counts this statement, its flow is current, and the selected passing test supplies both assertion and execution evidence. |
+| Not credited | The map claims this statement, but a reference, freshness or execution requirement is missing. Read the reason beside it. |
+| Context only | The node helps explain the assertion; the map does not claim it as an asserted statement. |
+
+The agent's explanation describes why a value or behavior reaches the assertion.
+Supercov's credit reason describes what the recorded evidence supports. A credit
+decision does not independently prove that explanation.
+
+## When a test has no source coverage
+
+You may see a warning that a test made assertions but has no source-coverage
+evidence. For example, a test might check a third-party parser, a constant, or
+configuration without calling measured application code.
+
+It can also mean application code ran in shared setup or across a process or
+network boundary that was not attributed to the test. Missing evidence alone
+cannot distinguish these cases. Inspect the test and the relevant statement:
+
+```sh supercov-example
+npx supercov runs <run-id> assertions report --view tests --limit 20
+npx supercov runs <run-id> assertions report --view statements --file src/shipping.js
+```
+
+In JSON output, a statement's `executionEvidence` distinguishes any recorded
+execution, passing tests and execution outside those tests. The tests view
+includes outcomes and identifies setup scopes. Use that information to decide
+whether to add a test, adjust the test setup or investigate measurement.
+
+## When a mapped assertion was not observed
+
+An assertion can appear in source without being reached in this run. Common
+causes include skipped or TODO tests and untaken branches inside passing tests.
+An unsupported custom assertion form or missing attribution can also prevent
+Supercov from recording the occurrence.
+
+Read the selected test's outcome before changing the map. A recorded skipped
+test and a test with no record are different cases. A passing sibling test does
+not supply evidence for an assertion it never reached.
+
+Use the stricter gate when you expect every mapped assertion and selected test
+to have passing evidence:
+
+```sh supercov-example
+npx supercov runs <run-id> assertions check --require-observed
+```
+
+This gate can intentionally fail for a suite with TODO or skipped cases. Keep
+those entries visible instead of deleting them to make the check pass.
+
+## Shared setup and asynchronous work
+
+Code executed once in shared setup does not count as execution by every test
+that later uses its result. Setup remains visible separately. If a statement
+needs its own test evidence, arrange a test that executes it and checks its
+behavior.
+
+Per-test `t.after` assertions are included for Node's test runner. Supported HTTP
+requests and test-owned WebSocket connections can carry a test's attribution
+into callbacks. A WebSocket shared across tests may still lack enough information
+to distinguish individual messages. Do not assign that work to a test merely
+because it ran around the same time.
+
+The regular report's **Runtime action phases** section is also separate from
+assertion coverage. Zero lines recorded inside action phases does not mean the
+agent-authored map credits zero statements.
+
+## Read a large flow
+
+Page the nodes and edges of one flow when the complete graph is too large:
+
+```sh supercov-example
+npx supercov runs <run-id> assertion <assertion-id> --flow <flow-id> --view nodes --limit 10 --compact
+npx supercov runs <run-id> assertion <assertion-id> --flow <flow-id> --view edges --limit 10
+npx supercov runs <run-id> source src/shipping.js --offset 0 --limit 20
+```
+
+`--compact` leaves source locations and credit reasons visible while omitting
+repeated source text. It only changes the displayed report. Follow the printed
+next-page command, or `pagination.nextOffset` in JSON, until the view is complete.
+Never copy compact report objects back into `assertions.json`.
+
+See [Assertion map format](assertion-maps.md) for fields and validation rules,
+and [Mapping assertions with an agent](assertion-agent.md) for the editing loop.