supercov 0.0.49 → 0.0.51

package/README.md

@@ -19,6 +19,10 @@ to add a test in your own project, with a recorded example to follow along.
 npx supercov -- npm test
 ```
 
+Other ways in, all the same binary at the same version: `brew install
+supercorp-ai/tap/supercov`, or for a Go project `go run
+github.com/supercorp-ai/supercov/cmd/supercov@latest`.
+
 Everything after `--` is your test command. Supercov runs it without changing your source, tests, runner configuration, or normal build output.
 
 Then ask what is still uncovered:

package/docs/assertion-agent.md

@@ -59,9 +59,10 @@ For each 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.
+- Add helper, configuration and other dependency files to `watch`. The
+  declarations holding your nodes, the top level of their files, the assertion
+  file and the selected test 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.
 
@@ -97,8 +98,11 @@ 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.
+When inheriting a map, read every entry in `--view changes`. Each names the
+flows it already made stale (`knownFlows`) and, under `exposed`, the tests that
+ran the changed code and how many flows they carry; start with those, and
+investigate whether other flows are affected too. A flow's own `notices` list changes near its
+nodes that could not have reached it.
 
 Add a `changeAssessments` entry for each managed change ID. Include all listed
 `knownFlows` that still exist, plus any other affected flows. Explain why the

package/docs/assertion-maps.md

@@ -107,13 +107,36 @@ 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 configuration that decides what executes
-changes: a transpiler, a test runner, an interpreter pin.
+A flow needs a fresh review when its claim changes; when a declaration holding
+one of its nodes changes -- the function, method or class the node sits in, or
+the top level of that file, its imports and constants; when that file's set of
+declarations changes, one added, removed or renamed; when a file it watches, a
+test it selects or its assertion's file changes; or when the configuration
+that decides what executes changes: a transpiler, a test runner, an
+interpreter pin.
+
+Each reason names what moved -- `src/server.js: Server.start (line 12)
+changed (holds this flow's return:31)` -- so you can look rather than reread.
 
 Several things that sound like they should count do not, because an
 acknowledgement demanded for all of them at once stops being read.
 
+Comments do not, nor blank lines or trailing whitespace: no program can tell.
+A comment the language itself reads is the exception and does count -- a Go
+`//go:embed` directive, a Ruby magic comment, a Rust doctest.
+
+A change to another declaration in a node's file does not. The claim rests on
+the code it names; the rest of the file is the author's to name in `watch` if
+it matters. Such a change is a notice on the flow (`notices` in the report),
+not a review, and it is asked about once, as a change to assess.
+
+Code the flow's test ran elsewhere does not make the flow stale either. A claim
+does not pass through every function its test happened to execute. What each
+test ran is recorded, and a changed file's change record says which tests ran
+the changed code and how many flows that exposes, so the one assessment the
+change asks for is asked of the right people -- and a change no selected test
+ran is not asked about at all.
+
 Cutting a release does not. A manifest is fingerprinted by what it declares, so
 a version number moving in `package.json`, `Cargo.toml`, `pyproject.toml` or a
 lockfile changes nothing. Neither does reformatting one.
@@ -233,11 +256,13 @@ 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.
+Each flow depends on the declarations holding its nodes and the top level of
+their files, on its assertion file, its selected test files and its extra
+`watch` files. A change to any of those requires another look at that flow;
+a comment, a blank line or another declaration's body does not. Independent
+sibling flows 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
@@ -255,9 +280,11 @@ response in the map's top-level `changeAssessments` array:
 ```
 
 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.
+that still exists and any additional affected flows. `knownFlows` are the flows
+the change has already made stale. `exposed` counts the flows whose selected
+tests ran the changed code and names those tests -- not stale for it, but the
+ones to think about; add the flows the change actually reaches. 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.

package/docs/cli.md

@@ -21,6 +21,7 @@ npx supercov --help
 | 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>` |
+| Find the tests a change affects | `npx supercov runs latest tests affected` |
 | Combine shards | `npx supercov merge <id> <id> [...]` |
 | Remove local data | `npx supercov clean` |
 | Read bundled guides | `npx supercov docs` |
@@ -289,6 +290,27 @@ target. It does not edit, delete, or skip tests for you. Treat the result as an
 analysis aid, not permission to remove tests that protect behavior outside the
 selected metric.
 
+## Find the tests a change affects
+
+```sh supercov
+npx supercov runs latest tests affected
+npx supercov runs latest tests affected --files
+npx supercov runs latest tests affected --json
+```
+
+`tests affected` names the tests of a run whose recorded execution the changes
+since that run could have reached: a change in code the test ran, in its test
+file, or in the shape of a file it ran code in -- a declaration added, removed
+or renamed. A change confined to code the test never ran does not count, and
+neither do comments, blank lines or trailing whitespace. A test that did not
+pass in the run is listed regardless.
+
+`--names` prints one affected test name per line and `--files` one test file
+per line, for a runner's filter. A dependency, lockfile, configuration or
+toolchain change affects every test and is reported as such. A source file
+added since the run is outside every test's record; the working-tree check
+says so, and the suite should run in full.
+
 ## Combine shards
 
 ```sh supercov

package/docs/getting-started.md

@@ -121,6 +121,20 @@ on crates.io (`cargo install supercov`). The first invocation may download
 Supercov from the registry. Supercov itself does not upload your source or
 coverage evidence to a Supercov service.
 
+Whichever language your project is in, you should not have to install another
+one first. Go runs it the way Go runs any tool, and without touching your
+`go.mod`:
+
+```sh supercov
+go run github.com/supercorp-ai/supercov/cmd/supercov@latest -- go test ./...
+```
+
+Homebrew installs the same binary for everything else, a JVM project included:
+
+```sh
+brew install supercorp-ai/tap/supercov
+```
+
 ## Files and cleanup
 
 Completed runs live under `.supercov/runs/`. Supercov also keeps an isolated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "description": "Coverage for coding agents and software factories \ud83c\udf19",
   "license": "MIT",
   "repository": {
@@ -76,7 +76,7 @@
     "benchmark:check": "cargo build --release -p supercov && node scripts/rust-transform-benchmark.mjs",
     "benchmark:python-monitoring": "cargo build -p supercov && node scripts/python-monitoring-benchmark.mjs",
     "check": "cargo fmt --all -- --check && cargo clippy --workspace --all-targets -- -D warnings && npm run test && npm run test:runtime && npm run test:rust-assets && npm run test:assertion-maps && node scripts/package-preflight.mjs && node scripts/verify-binstall-metadata.mjs --offline",
-    "release:check": "cargo clean && node scripts/sweep-target.mjs && npm run check && npm run test:engine && npm run test:go && npm run test:jvm && npm run test:fixture && npm run test:watchdog && npm run test:engine-contract && npm run test:agent && npm run test:child-attribution && npm run test:host-loader && npm run test:python-monitoring && npm run test:ruby-coverage && npm run test:rust-public-cargo && npm run test:packed-npx && npm run test:clang-mcdc && npm run benchmark:check",
+    "release:check": "cargo clean && node scripts/sweep-target.mjs && npm run check && npm run test:engine && npm run test:go && npm run test:jvm && npm run test:launcher && npm run test:fixture && npm run test:watchdog && npm run test:engine-contract && npm run test:agent && npm run test:child-attribution && npm run test:host-loader && npm run test:python-monitoring && npm run test:ruby-coverage && npm run test:rust-public-cargo && npm run test:packed-npx && npm run test:clang-mcdc && npm run benchmark:check",
     "release:bump": "node scripts/bump-version.mjs",
     "sweep": "node scripts/sweep-target.mjs",
     "oracle:rust": "cargo build --release -p supercov && node scripts/rust-coverage-oracle.mjs",
@@ -93,17 +93,18 @@
     "test:assertion-maps:js": "cargo build -p supercov && node scripts/assertion-map-schema.mjs --check && node scripts/assertion-map-js-integration.mjs && node scripts/assertion-dogfood-integration.mjs",
     "sync:assertion-schema": "cargo build -p supercov && node scripts/assertion-map-schema.mjs",
     "docs:sync": "node scripts/sync-docs.mjs",
-    "docs:check": "node scripts/sync-docs.mjs --check"
+    "docs:check": "node scripts/sync-docs.mjs --check",
+    "test:launcher": "go vet ./cmd/... && go test ./cmd/..."
   },
   "optionalDependencies": {
-    "@supercov/cli-darwin-arm64": "0.0.49",
-    "@supercov/cli-darwin-x64": "0.0.49",
-    "@supercov/cli-linux-arm64-gnu": "0.0.49",
-    "@supercov/cli-linux-arm64-musl": "0.0.49",
-    "@supercov/cli-linux-x64-gnu": "0.0.49",
-    "@supercov/cli-linux-x64-musl": "0.0.49",
-    "@supercov/cli-win32-arm64": "0.0.49",
-    "@supercov/cli-win32-x64": "0.0.49"
+    "@supercov/cli-darwin-arm64": "0.0.51",
+    "@supercov/cli-darwin-x64": "0.0.51",
+    "@supercov/cli-linux-arm64-gnu": "0.0.51",
+    "@supercov/cli-linux-arm64-musl": "0.0.51",
+    "@supercov/cli-linux-x64-gnu": "0.0.51",
+    "@supercov/cli-linux-x64-musl": "0.0.51",
+    "@supercov/cli-win32-arm64": "0.0.51",
+    "@supercov/cli-win32-x64": "0.0.51"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/schemas/assertions.schema.json

@@ -110,7 +110,7 @@
             "string",
             "null"
           ],
-          "pattern": "^scov2:[0-9a-f]{64}$"
+          "pattern": "^scov[23]:[0-9a-f]{64}$"
         },
         "explanation": {
           "type": "string"
@@ -236,7 +236,7 @@
             "string",
             "null"
           ],
-          "pattern": "^scov2:[0-9a-f]{64}$"
+          "pattern": "^scov[23]:[0-9a-f]{64}$"
         },
         "affectedFlows": {
           "type": "array",