supercov 0.0.45 → 0.0.47

package/docs/assertion-maps.md

@@ -1,30 +1,26 @@
-# Assertion maps
-
-Each normal test run creates `assertions.json` in its run directory. Any coding
-agent can edit that file to describe what specific assertions observe and which
-statements contribute to those observations. Rust handles syntax, references,
-input freshness, reuse and reporting. Supercov does not run an embedded model or
-reconstruct the agent's semantic reasoning with a static analyzer.
-
-## Run, investigate, save
-
-```sh
-supercov -- npm test
-supercov runs latest assertions --json
-# Pin the returned run ID; edit data.map using matching current project files.
-supercov runs <run> assertions report --view changes --json
-supercov runs <run> assertions validate --json
-# After investigating, copy expectedBasis tokens into the corresponding entries.
-supercov runs <run> assertions check --require-mappings --require-observed --json
-supercov runs <run>
+# Assertion map format
+
+Edit a run's `assertions.json` to record which assertions check which source
+statements. Start with [Understanding assertion coverage](assertions.md) if you
+want an agent to create the map for you. This reference covers the fields and
+commands used to inspect, update and validate it.
+
+## Open the run's map
+
+```sh supercov
+npx supercov runs latest assertions --json
 ```
 
-There is no `init` or `review` command. `validate` is read-only: it returns the
-expected acknowledgements, and the agent saves them in the one editable file.
-A token says that the author acknowledges these particular inputs and this
-particular claim. It is not proof, a signature, or a model confidence score.
+The response gives you `data.run` and `data.map`. Use that run ID throughout the
+edit. A normal run creates the file automatically and inherits compatible work
+from earlier runs of the same test command and language.
+
+Only edit `assertions.json`. Keep `assertions.state.json` and the run's evidence
+unchanged. Use current project files that match the run when investigating.
 
-## File format, version 2
+## Describe an assertion and its flow
+
+This illustrative draft maps an equality check to a return statement:
 
 ```json
 {
@@ -32,7 +28,9 @@ particular claim. It is not proof, a signature, or a model confidence score.
   "assertions": [{
     "id": "a_example",
     "at": {
-      "file": "tests/value.test.ts", "line": 5, "column": 3,
+      "file": "tests/value.test.ts",
+      "line": 5,
+      "column": 3,
       "text": "assert.equal(value(), 1)"
     },
     "observes": ["The returned number equals one."],
@@ -40,10 +38,15 @@ particular claim. It is not proof, a signature, or a model confidence score.
       "id": "return-value",
       "basis": null,
       "appliesTo": [{ "file": "tests/value.test.ts", "name": "value" }],
-      "explanation": "The function's returned number reaches the equality assertion through value().",
+      "explanation": "value() returns the number compared by the assertion.",
       "nodes": [{
         "id": "return",
-        "at": { "file": "src/value.ts", "line": 2, "column": 3, "text": "return 1;" }
+        "at": {
+          "file": "src/value.ts",
+          "line": 2,
+          "column": 3,
+          "text": "return 1;"
+        }
       }],
       "edges": [{ "from": "return", "to": "$assertion", "kind": "data" }],
       "countsAsAsserted": ["return"],
@@ -53,156 +56,173 @@ particular claim. It is not proof, a signature, or a model confidence score.
 }
 ```
 
-This is an illustrative draft; its anchors and test selector must match a real
-run before it can receive credit. `basis: null` explicitly means unacknowledged.
-`supercov assertions schema` exports the schema generated from the same Rust
-types as the parser. The published editor schema is `schemas/assertions.schema.json`.
-`supercov assertions validate --file <path> --json` checks JSON shape without a run.
+Use the actual assertion IDs, test names and source locations from your run.
+The example remains a draft until its references match and its flow has been
+examined and acknowledged.
 
-| Field | Meaning |
+| Field | What to write |
 | --- | --- |
-| `id`, `at` | Persistent assertion identity and exact assertion expression. |
-| `observes` | What the predicate distinguishes; an existence check does not check every field. |
-| `flows` | Recorded explanations. An empty array means none are recorded; there is no known total. |
-| `questions` | Optional assertion-level investigation questions. They do not establish completeness. |
-| Flow `id` | Stable within its assertion; `assertion-id/flow-id` identifies the claim. |
-| Flow `basis` | Null, or the opaque `scov2:<64 lowercase hex digits>` token supplied by validation. |
-| `appliesTo` | Explicit project-relative test file and exact displayed test name. Empty means no execution credit. |
-| `nodes`, `edges` | Exact source anchors and authored relationships ending at the reserved `$assertion` sink. |
-| `countsAsAsserted` | The node IDs judged asserted. Context nodes earn no automatic credit. |
-| `watch` | Additional whole-file dependencies as path strings. |
-| Flow `questions` | Optional unresolved questions; any entry blocks this flow's credit. |
-
-Anchors use project-relative `/` paths, one-based lines and one-based UTF-8 byte
-columns. Preserve exact text, including multiline expressions. IDs use letters,
-digits, `_`, `-`, or `.`. Edges have `from`, `to`, `kind`, and optional explanatory
-`basis` text; that edge text is distinct from the flow's acknowledgement token.
-Every counted node needs a path through the authored edges to `$assertion`.
-The checker traverses this JSON graph only; it does not infer source dependencies.
-A counted node must match one measured statement exactly to earn credit. A block
-or guard does not implicitly credit its nested body.
-
-A zero-credit explanation is useful for a fixture-only check or an absence check:
-explain the observation and use `countsAsAsserted: []`. An absent event cannot
-credit an unexecuted body. An executed guard can receive credit only when the
-author judges that the predicate observes its behavior.
-
-## Percentage and report states
-
-The regular `supercov runs <run>` report reads the map on demand. Its primary
-percentage is the union of eligible, explicitly counted measured statements,
-divided by **all measured statements** in the run. Unexecuted and unanchored
-measured statements remain in the denominator. Duplicate claims count once.
-Line credit requires all measured statements on that line to be credited.
-
-Eligibility requires valid references, current input acknowledgement, no open
-flow questions, a passing run, an exact passing assertion occurrence, and
-statement execution attributed to the same selected passing test. File + name
-selectors must resolve unambiguously. A missing or unobserved selector contributes
-nothing; an observed sibling selector can still contribute. Coexecution supports
-the agent's claim but does not establish causality or temporal ordering.
-
-| `summary.status` | Public percentage |
+| Assertion `id`, `at` | Preserve the assertion's ID and exact test expression. |
+| `observes` | Describe the property checked, such as an exact value, length or substring. |
+| `flows` | Explain the routes from relevant source to this assertion. An empty array means no explanations are recorded. |
+| Flow `id` | Choose a stable name within the assertion, such as `return-value`. |
+| Flow `basis` | Start with `null`. After review, copy the token returned by validation. |
+| `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. |
+| `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
+UTF-8 byte columns. Preserve exact text, including multiline expressions. IDs
+use letters, digits, `_`, `-` or `.`. Edge `basis` is optional explanatory text;
+it is separate from the flow's review token.
+
+Every counted node needs a path through the recorded edges to `$assertion` and
+must match a measured statement exactly. Counting an `if` statement does not
+also count every statement inside it. Nodes that only provide context can stay
+in the graph without appearing in `countsAsAsserted`.
+
+Test selectors must be unambiguous. An empty `appliesTo` supplies no execution
+credit. For a shared assertion, select the applicable test cases explicitly.
+An absence or fixture-only check can use `countsAsAsserted: []`; explain what
+was observed and, for absence, the ordering and observation window.
+
+## Validate and acknowledge your edits
+
+```sh supercov-example
+npx supercov assertions schema --json
+npx supercov assertions validate --file <map-path> --json
+npx supercov runs <run-id> assertions validate --json
+```
+
+The first command exports the editor schema. File validation checks JSON shape.
+Run validation also checks IDs, source anchors, graph links, selected tests and
+changed inputs. It does not edit the map or prove the explanation.
+
+After examining a flow, copy its returned `expectedBasis` into that flow's
+`basis`, save the file, and run `check`. Treat the token as an opaque value;
+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 project's dependencies, configuration or
+the instrumenter change. 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>
+```
+
+| Check option | Requirement |
 | --- | --- |
-| `available` | Numeric, including a meaningful 0 when a current observed explanation credits nothing. |
-| `notAssessed` | Null: no flow explanations have been recorded. |
-| `pending` | Null: change impact remains outstanding, or no eligible current explanation exists. |
-| `unavailable` | Null or an unavailable report: failed run, invalid identities, mismatching source or unreadable map. |
-| `notApplicable` | Null: no measured statements exist. |
-
-For example:
-
-```text
-Assertions 62.50% (50/80) — agent-assessed statements, whole run
-  18 assertions with flows; 7 without; 29 current flows; 3 stale; 2 draft
-Assertions not assessed — No recorded flow explanations
-Assertions pending — Source changes need impact assessment
+| No extra option | Authored claims and references are valid and current, questions and change assessments are resolved, and the run passed. Untouched assertions without flows are allowed. |
+| `--require-mappings` | Every recognized assertion observed passing has a current explanation, including legitimate zero-credit explanations. |
+| `--require-observed` | Every listed assertion and explicit test selector has matching passing evidence. |
+| `--min <percentage>` | The available assertion percentage meets your target. |
+
+Use `--require-observed` when every mapped site is expected to run. Skipped,
+TODO and untaken cases can make it fail even when their explanations are useful.
+Neither gate establishes that every possible flow has been found.
+
+`validate` exits with code 2 for syntax or reference errors. A null or stale
+review token alone is not a syntax error. `check` exits with code 2 when a
+requested requirement is unmet.
+
+## Understand statement credit
+
+The percentage counts the union of explicitly claimed measured statements with
+current flows, a passing assertion and execution in the same selected passing
+test. Duplicate claims count once. Unexecuted statements remain in the
+denominator. A line receives assertion credit only when all measured statements
+on it receive credit.
+
+TypeScript imports known to disappear during compilation are excluded. Inspect
+their locations with:
+
+```sh supercov-example
+npx supercov runs <run-id> assertions report --view excludedStatements
 ```
 
-A partial map can produce a useful numeric score. Counts show assertions with
-and without flows, current/draft/stale/invalid flows, unobserved assertions,
-questions and pending changes. There is no `mapped` or `complete` status. The
-number of missing semantic flows is unknown. `current` means the claim has no
-freshness/reference/question blockers; selector evidence is reported separately.
-Diagnostic statement counts remain inspectable while change impact is pending;
-the public percentage stays null.
+This includes explicit `import type` and, for supported tsc/tsx/ts-node settings,
+imports used only as types. Runtime, mixed and side-effect imports remain.
+Preserving compiler settings and configurations that Supercov cannot resolve
+keep ambiguous imports in the denominator. Older runs keep their recorded totals.
+
+An assertion detail explains each node's credit decision. In JSON, computed
+`nodeCredit` entries include the decision, reason codes, matched statement IDs
+and matching tests. Keep these report fields out of the editable map. See
+[Investigating assertion evidence](assertion-evidence.md) for missing execution,
+shared setup and asynchronous cases.
 
-JSON regular reports expose this under `data.assertionCoverage.summary`; detailed
-assertion reports use `data.summary`. `assertionCoverage.available` indicates
-whether the report could be read, while `summary.status` describes whether its
-percentage is available. Structural filters do not change the assertion score:
-it describes the whole run, as its label says. MC/DC remains a separate metric.
-`revision` binds each response to the map, managed state and run evidence.
+A numeric result can come from a partial map. `current` means the flow has no
+freshness, reference or question blockers; it does not mean all source nodes
+receive credit or every relevant flow is known. The normal report shows counts
+of assertions without flows and flows still needing attention beside the score.
 
-## Resource commands
+JSON regular reports put the summary at `data.assertionCoverage.summary`.
+Assertion reports use `data.summary`. A `summary.status` of `available` supplies
+a percentage; `notAssessed`, `pending`, `unavailable` and `notApplicable` do not.
+The assertion summary always covers the whole run, even when other coverage
+metrics or the returned items are filtered.
 
-| Command | Shows |
+## Find the next part to investigate
+
+| Command after `supercov runs <run-id>` | Shows |
 | --- | --- |
-| `runs <run> assertions` | Recognized and authored assertions, including sites missing from the map. |
-| `runs <run> assertions --needs-attention` | Assertions without flows, with open questions, or with flows needing investigation/evidence. |
-| `runs <run> assertion <id>` | One exact assertion and its graph, freshness, selectors and evidence. |
-| `runs <run> source <path>` | Matching current source, printed as code with line numbers. |
-| `runs <run> assertions files` | Input paths, byte sizes and SHA-256 hashes; works even with a stale checkout. |
-| `runs <run> assertions report --view <view>` | `summary`, `assertions`, `statements`, `tests`, `changes`, `creditedLines`, or `unassertedLines`. |
-| `runs <run> assertions validate --json` | Shape/reference errors, changes and flow `expectedBasis` tokens. Read-only. |
-| `runs <run> assertions check` | Read-only policy gates. |
-
-`--file <path>` filters assertion/statement/line items, never the summary.
-List views support `--offset <n> --limit <1..1000>` and `--json`. Follow
-`pagination.nextOffset`; restart a multi-page read if `revision` changes.
-Source defaults to 20 lines and prints `34 │ code here`. Source JSON uses
-`{line, text}` items for integrations. It is usable with malformed map JSON but
-requires current files matching the run. There is no separate inventory command.
-
-Large validation responses can be paged with `validate --view flows|changes|errors`
-and `--offset`/`--limit`. Entries appear under `items`; overall `valid` and
-`errorCount` still cover the whole map. Default validation returns all entries.
-
-`validate` returns exit 2 for syntax/reference errors, not merely null/stale
-acknowledgements. `check` returns exit 2 for invalid references, failed runs,
-unacknowledged/stale/invalid flows, open questions, pending impact assessments,
-or an unverifiable checkout. An incremental map with untouched empty sites is
-allowed by basic `check`. Optional gates:
-
-- `--require-mappings`: every recognized assertion observed passing has at least
-  one eligible current explanation. A zero-credit explanation qualifies. This
-  is not a claim that every flow is known.
-- `--require-observed`: every listed assertion and every explicit selector has
-  matching passing evidence. Empty selectors fail this gate.
-- `--min <0..100>`: the public statement percentage must be numeric and meet the target.
-
-## Reuse after source or test changes
-
-Run the same test command again. Before publication, Supercov selects the newest
-usable map for that exact command and language. A malformed newer candidate is
-reported under `inheritance.skipped`; fallback claims require fresh acknowledgement.
-Publication writes evidence, map and managed state together atomically. Previous
-runs stay untouched. Finish editing the newest map before starting its successor.
-
-The run stores a hash manifest and assertion identities, not complete source
-files. Current project files supply the source for investigation. Managed
-`assertions.state.json` (version 3) binds evidence and input identities and stores
-invalidation generations, outstanding change records and inheritance metadata.
-It contains no second semantic graph. Only `assertions.json` is agent-editable.
-No query changes either file.
-
-A flow depends on the assertion file, each selected test file, every node file,
-and extra `watch` files. Any byte change in those files, including comments or
-blank lines, invalidates that flow. Other sibling flows can remain current.
-Changes to the assertion/observation affect all its flows. Context/dependency/
-instrumenter changes invalidate inherited claims conservatively. Flow tokens
-bind the claim (excluding their own token), context, sorted dependency hashes,
-and effective invalidation generation; they exclude run IDs and runtime events.
-
-Exact identities retain IDs. Unique snippets or unique identical-file renames
-can relocate as suggestions. A sole unmatched old/new assertion in the same file
-can retain its ID as a changed candidate. Ambiguous/removed assertions remain
-under `retiredAssertions` with explanations. Unresolved changes stay stale across
-reruns and reverts until acknowledged. Every new run supplies fresh evidence.
-
-Every added, edited or removed file in the captured analysis scope enters the
-change queue, even if a flow already watches it. Known dependencies are a starting
-point, not proof that other flows are unaffected. Read `--view changes` and edit:
+| `assertions` | Assertions, including those without recorded flows. |
+| `assertions --needs-attention` | Missing explanations, questions, stale or draft flows, and claimed nodes without credit. |
+| `assertion <id>` | One assertion, its flows and node-credit reasons. |
+| `source <path>` | Matching current code with line numbers. |
+| `assertions files` | Captured input paths, sizes and hashes, even if the checkout is stale. |
+| `assertions report --view <view>` | `summary`, `assertions`, `statements`, `tests`, `changes`, `creditedLines`, `unassertedLines` or `excludedStatements`. |
+
+Use `--file <path>` to filter applicable list views; the summary still describes
+the whole run. Lists support `--offset`, `--limit` and `--json`. Follow the
+printed next-page command or JSON `pagination.nextOffset` until it is null.
+Restart a paged read if `revision` changes while you are reading it.
+
+An assertion detail pages whole flows by default. For a large individual flow,
+use `--flow <flow-id> --view nodes` and `--view edges`. Add `--compact` to omit
+repeated source text while retaining locations. Read that text with `source`;
+do not save compact report objects into the map.
+
+Large validation results support `--view flows`, `--view changes` or
+`--view errors`. Each page still reports validity for the entire map. The source
+command pages lines; JSON source output uses `{line, text}` objects for integrations.
+
+## Update the map after a change
+
+Run the same test command again, then edit the new run's map. Supercov carries
+forward compatible mappings and leaves the previous run unchanged. If a newer
+map cannot be reused, `inheritance.skipped` explains the fallback.
+
+Each flow depends on its assertion file, selected test files, node files and
+extra `watch` files. A change to any of those files requires another look at that
+flow, even if only a comment changed. Independent sibling flows can stay current.
+Changing the assertion or its observation affects all its flows. Dependency,
+configuration and instrumentation changes can affect many flows.
+
+Start with `assertions report --view changes`. Investigate every listed change,
+including effects on flows that did not yet watch the changed file. Add a
+response in the map's top-level `changeAssessments` array:
 
 ```json
 {
@@ -210,43 +230,28 @@ point, not proof that other flows are unaffected. Read `--view changes` and edit
     "id": "c_copy_from_changes_view",
     "basis": null,
     "affectedFlows": ["a_example/return-value"],
-    "explanation": "The edit affects the returned value; the independent sibling computation is unchanged."
+    "explanation": "The edit affects the returned value. The independent sibling calculation is unchanged."
   }]
 }
 ```
 
-This is an excerpt. Include all `knownFlows` that still exist, plus any additional
-claims affected by the change. Repair missing watches when appropriate. An empty
-list needs an explanation of why existing claims are unaffected; it does not
-mean the changed code is tested. Save responses, validate, copy examined change
-tokens, save, then validate again for final flow tokens. Impact assignment can
-invalidate another flow, so this order matters. Tokens have no circular dependency.
-Deleting a response does not clear its managed change record.
-
-On the next run, resolved changes are folded into per-flow generation baselines
-and retired. Unchanged equivalent runs preserve current tokens. Pending records
-survive and their responses must match the current input manifest. The scope is
-finite: uncaptured external state is not automatically monitored.
-
-Version-1 maps remain importable during carry; graphs and IDs are preserved,
-span watches become file watches, and all flow tokens start null. Former test
-names are retained in investigation questions until file-qualified selectors are
-provided. Missing sink edges are not invented. Legacy evidence may contain full
-source, used only to recover hashes. No migration writes into the old run.
-
-## Limits and validation
-
-The JS/TS verification matrix covers Node ESM/CommonJS/native TypeScript, Vitest
-TypeScript, Jest CommonJS and Playwright's Node-side TypeScript assertions,
-including aliases, shared parameterized sites and async rejection matchers.
-Unsupported/custom sites can be documented, but JS/TS credit requires the exact
-recognized expression and operation in runtime evidence. This does not infer
-browser assertion identity or data flows through external services.
-
-The map is an agent assessment. A credited statement can be changed without
-failing a test when the change preserves the observed property. Neither 100%
-assertion coverage nor 100% MC/DC proves mutation resistance or safety for every
-change. Use the observation and graph to select tests and identify missing
-checks; sample mutation audits can independently evaluate the authored claims.
-See [the agent workflow](assertion-agent.md), [assertion evidence](assertion-evidence.md),
-and [verification](verification.md).
+This is an excerpt to add to your existing map. Include every entry in `knownFlows`
+that still exists and any additional affected flows. An empty list needs an
+explanation of why existing claims are unaffected; it does not mean the changed
+code is tested.
+
+Save the assessments and graph edits, validate, and copy the examined change
+tokens. Save again, then validate once more before copying final flow tokens.
+Assessing a change can make another flow stale, so the order matters. Removing
+an assessment or reverting a file does not by itself clear an unresolved change.
+
+Keep removed or ambiguous assertion records for review under `retiredAssertions`.
+Follow the supplied questions when inheriting older maps. Do not invent source
+links or evidence to clear a warning.
+
+## Keep queries fast
+
+Reports reuse a disposable assessment cache while checking that sources still
+match. Editing the map invalidates the cached assessment automatically. Queries
+never acknowledge flows or change the authored map. See [Speed and storage](performance.md)
+for keeping repeated investigation fast.