supercov 0.0.44 → 0.0.46

package/docs/assertion-maps.md

@@ -0,0 +1,236 @@
+# 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
+```
+
+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.
+
+## Describe an assertion and its flow
+
+This illustrative draft maps an equality check to a return statement:
+
+```json
+{
+  "schemaVersion": 2,
+  "assertions": [{
+    "id": "a_example",
+    "at": {
+      "file": "tests/value.test.ts",
+      "line": 5,
+      "column": 3,
+      "text": "assert.equal(value(), 1)"
+    },
+    "observes": ["The returned number equals one."],
+    "flows": [{
+      "id": "return-value",
+      "basis": null,
+      "appliesTo": [{ "file": "tests/value.test.ts", "name": "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;"
+        }
+      }],
+      "edges": [{ "from": "return", "to": "$assertion", "kind": "data" }],
+      "countsAsAsserted": ["return"],
+      "watch": []
+    }]
+  }]
+}
+```
+
+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 | What to write |
+| --- | --- |
+| 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.
+
+```sh supercov-example
+npx supercov runs <run-id> assertions check --require-mappings
+npx supercov runs <run-id>
+```
+
+| Check option | Requirement |
+| --- | --- |
+| 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
+```
+
+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.
+
+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.
+
+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.
+
+## Find the next part to investigate
+
+| Command after `supercov runs <run-id>` | Shows |
+| --- | --- |
+| `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
+{
+  "changeAssessments": [{
+    "id": "c_copy_from_changes_view",
+    "basis": null,
+    "affectedFlows": ["a_example/return-value"],
+    "explanation": "The edit affects the returned value. The independent sibling calculation is unchanged."
+  }]
+}
+```
+
+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.

package/docs/assertions.md

@@ -0,0 +1,132 @@
+# Understanding 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.
+
+## Start with your existing tests
+
+```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.
+
+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.
+```
+
+You can use your usual coding agent. Supercov does not require a particular
+model or make model calls itself.
+
+## Read the percentage
+
+```sh supercov-example
+npx supercov runs <run-id>
+```
+
+An illustrative report might show:
+
+```text
+Assertions 62.50% (50/80) — agent-assessed statements, whole run
+  18 assertions with flows; 7 without; 29 current flows; 3 stale; 2 draft
+```
+
+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.
+
+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.
+
+| 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. |
+
+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.
+
+## Check what an assertion actually protects
+
+Suppose `src/shipping.js` contains:
+
+```js
+export function shippingCost() {
+  return 4;
+}
+```
+
+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. |
+
+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.
+
+## Inspect a gap
+
+```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
+```
+
+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.
+
+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.
+
+## Keep the map when code changes
+
+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.
+
+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.
+
+## Use the score to guide changes
+
+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.
+
+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.

package/docs/cli.md

@@ -17,7 +17,9 @@ npx supercov --help
 | Read the newest run | `npx supercov runs latest` |
 | Find useful gaps | `npx supercov runs latest gaps` |
 | Inspect one file | `npx supercov runs latest file <path>` |
-| Inspect assertion evidence (JS/TS) | `npx supercov runs latest assertions` |
+| List assertions and their status | `npx supercov runs latest assertions` |
+| Inspect one assertion and its flows | `npx supercov runs latest assertion <id>` |
+| Read matching current source code | `npx supercov runs latest source <path>` |
 | Compare two runs | `npx supercov diff <older> <newer>` |
 | Combine shards | `npx supercov merge <id> <id> [...]` |
 | Remove local data | `npx supercov clean` |
@@ -72,7 +74,9 @@ npx supercov runs <run-id> [query] [options]
 | `kinds` | Group coverage by test level, such as unit or E2E |
 | `runners` | Group coverage by test runner |
 | `scope` | Review included, excluded, and ambiguous source files |
-| `assertions` | Analyze source-to-assertion evidence, gaps, and limits (JS/TS) |
+| `assertions` | List assertions, including sites without flows, with freshness and execution status |
+| `assertion <id>` | Inspect one assertion and its authored flows |
+| `source <path>` | Read matching current project source with line numbers |
 | `minimize` | Find a small test subset that preserves a coverage target |
 
 Common examples:
@@ -93,12 +97,40 @@ npx supercov runs latest file --help
 npx supercov runs latest assertions --help
 ```
 
-The npm-only `assertions` query runs after tests against matching source. It
-reports unverified candidates, not a proven assertion score or permission to
-change behavior. Its filters differ from the structural queries below; see
-[assertion evidence](assertion-evidence.md) for requirements, pagination, and
-optional assertion hints. The guide is also available through
-`npx supercov docs assertion-evidence`.
+Assertion queries read the run-owned map. `source <path>` reads the matching current
+file directly. It prints source code with line numbers, preserving indentation;
+add `--json` only when you want structured `{line, text}` items. `--offset` is
+zero-based and `--limit` controls the number of source lines. Source and assertion
+investigation require current files that match the run. Rerun the suite after
+source changes to inherit the map into a new run.
+
+### Assertion coverage
+
+The regular run summary includes assertion coverage when a map has been
+assessed. JSON reports expose it under `data.assertionCoverage`. Start with
+[Understanding assertion coverage](assertions.md), or use these commands to
+inspect and check a map:
+
+```sh supercov-example
+npx supercov runs <run-id> assertions --needs-attention
+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> assertions report --view excludedStatements
+npx supercov runs <run-id> assertions validate --json
+npx supercov runs <run-id> assertions check --require-mappings
+```
+
+Edit the file shown by `assertions`. Validation returns `expectedBasis` tokens;
+after examining a flow, save its token in the map before running `check`.
+`--require-mappings` requires explanations for recognized assertions observed
+passing. Add `--require-observed` when every mapped site and selector should have
+passing evidence, or `--min <percentage>` for a chosen target.
+
+To inspect one large flow, add `--flow <flow-id> --view nodes` or `--view edges`
+to the assertion detail command. `--compact` omits repeated source text from the
+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.
 
 ## Narrow a view
 

package/docs/coverage-model.md

@@ -33,6 +33,7 @@ npx supercov runs latest scope
 | Branch | Did each alternative execute? |
 | Decision vector | Which combinations of boolean conditions occurred? |
 | MC/DC witness | Was each condition shown to affect the decision independently? |
+| Assertion coverage | Which measured statements are linked to passing checks by the agent-authored map? |
 | Value path | Did defaults, optional chains, logical assignments, and similar constructs take each meaningful path? |
 
 The exact obligations depend on the language and source construct. You do not
@@ -71,6 +72,14 @@ does not mean the product has no bugs, the assertions are meaningful, or every
 possible input was tested. Review test quality and user-visible behavior, not
 only the percentage.
 
+TypeScript imports known to disappear during compilation do not add runtime
+statement obligations. The assertion report's `excludedStatements` view lists
+these locations. Imports that still execute, including side-effect imports,
+remain in the denominator.
+
+To review what your JavaScript and TypeScript tests actually check, see
+[Understanding assertions](assertions.md).
+
 If source cannot be measured safely, Supercov reports a measurement limit
 instead of claiming completeness.
 
@@ -138,3 +147,12 @@ the bundler consumes them at build time; nothing about them runs.
 
 Choose roots that describe code the repository owns. Do not include dependencies
 or generated output merely to make a warning disappear.
+
+## Assertion percentage
+
+When a run has an `assertions.json` map, its regular summary also shows
+agent-assessed assertion coverage: credited measured statements divided by all
+measured statements. This row always describes the whole archived run,
+independently of `--filter`, `--kind` and `--runner`. It is separate from the
+structural metrics above. See [assertion maps](assertion-maps.md) for credit,
+freshness and incomplete-map rules.

package/docs/evidence.md

@@ -109,3 +109,31 @@ npx supercov clean
 Preview cleanup first. The final command removes all runs and the isolated build
 cache; `--keep 20` preserves the 20 newest runs. Cleanup removes only
 marker-owned Supercov data.
+
+## Understand test kinds
+
+Reports group tests by kind, such as unit, integration or E2E. Supercov uses
+recognized file names and runner information; a kind is a classification, not
+proof of what the test checks. A name such as `gatewayE2e.test.ts` identifies an
+E2E test. Ambiguous names keep the runner's default, and the report tells you
+how many tests use that default.
+
+If your suite has a known kind, set it when running the command:
+
+```sh supercov-example
+SUPERCOV_TEST_KIND=integration npx supercov -- npm test
+```
+
+Supported values are `unit`, `component`, `integration` and `e2e`. Use separate
+runs when different suites need different classifications.
+
+## When assertion evidence is missing
+
+A test can make assertions without executing measured application code. It
+might check static data or a dependency, or use work performed in shared setup.
+Missing attribution across an asynchronous boundary can also leave a gap.
+
+The assertion detail explains why a mapped node did or did not receive credit.
+Use [Investigating assertion evidence](assertion-evidence.md) to distinguish
+these cases. The report's runtime action-phase counts are separate from the
+assertion map; zero action-phase lines does not mean zero asserted statements.

package/docs/performance.md

@@ -82,3 +82,19 @@ npx supercov clean
 Use `--dry-run` to preview cleanup. Keep enough run history for active reviews
 and automation; remove the cache only when reclaiming space matters more than a
 faster next run.
+
+## Keep assertion investigation fast
+
+Save `assertions.json` and query the run to see the updated score. Supercov does
+not rerun tests or call a model to calculate the report. Repeated queries reuse
+the previous assessment while checking that your source still matches the run.
+Editing the map automatically refreshes that assessment.
+
+For large maps, ask for a short page instead of the whole graph. Within one
+flow, `--view nodes` or `--view edges` pages the details; `--compact` omits repeated
+source text while keeping locations and credit reasons. See
+[Investigating assertion evidence](assertion-evidence.md#read-a-large-flow).
+
+The disposable `assertions.report.cache.json` file lives beside the map. A missing
+or damaged cache is rebuilt. Removing it affects the next query's speed, not
+your saved explanations.