supercov 0.0.50 → 0.0.52

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

@@ -70,7 +70,7 @@ examined and acknowledged.
 | `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. Manifests, lockfiles and runner configuration are already tracked for the whole run; naming one here catches nothing, and the report says so. |
+| `watch` | List additional files the explanation depends on, such as helpers or configuration. A watched file is depended on **as a whole**: any change to it that is not a comment is a review. Use it for a file your claim reasons about but holds no node of yours -- including claims about what a file does *not* contain, which no node can anchor. Naming a file that already holds this flow's nodes widens the flow from those declarations to the whole file, so a neighbouring function's body becomes a review again; that is sometimes what you mean, and the report says when you have done it. Manifests, lockfiles and runner configuration are already tracked for the whole run; naming one catches nothing, and the report says so. A redundant entry is free to take back out: it is not part of what the acknowledgement rests on, so removing one keeps the flow's credit. |
 | `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
@@ -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
@@ -254,10 +279,25 @@ 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.
+This is an excerpt to add to your existing map. `affectedFlows` is your
+judgement: the flows this change invalidates, and only those. It is not a
+restatement of `knownFlows` -- Supercov already holds that list and does not
+ask you to retype it. **Every flow you name loses its acknowledgement and has
+to be reread**, so naming a flow is a decision, and naming all of them is the
+expensive one.
+
+To make that judgement, read what the change view gives you. `knownFlows`
+counts the flows the change has already made stale and samples them. `exposed`
+counts the flows whose selected tests ran the changed code and names those
+tests -- not stale for it, but the ones most worth thinking about. Neither is
+a verdict: under an integration suite every test runs most of the code, so
+exposure is a place to look, not a list to copy.
+
+An empty list is the normal outcome for a change that touches no claim, and it
+is the contract this channel exists to provide: one explanation answers for the
+change and every dependent keeps its credit. It still needs an explanation of
+why existing claims are unaffected, and 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "0.0.50",
+  "version": "0.0.52",
   "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.50",
-    "@supercov/cli-darwin-x64": "0.0.50",
-    "@supercov/cli-linux-arm64-gnu": "0.0.50",
-    "@supercov/cli-linux-arm64-musl": "0.0.50",
-    "@supercov/cli-linux-x64-gnu": "0.0.50",
-    "@supercov/cli-linux-x64-musl": "0.0.50",
-    "@supercov/cli-win32-arm64": "0.0.50",
-    "@supercov/cli-win32-x64": "0.0.50"
+    "@supercov/cli-darwin-arm64": "0.0.52",
+    "@supercov/cli-darwin-x64": "0.0.52",
+    "@supercov/cli-linux-arm64-gnu": "0.0.52",
+    "@supercov/cli-linux-arm64-musl": "0.0.52",
+    "@supercov/cli-linux-x64-gnu": "0.0.52",
+    "@supercov/cli-linux-x64-musl": "0.0.52",
+    "@supercov/cli-win32-arm64": "0.0.52",
+    "@supercov/cli-win32-x64": "0.0.52"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.55.0",

package/runtime/javascript/provenance.mjs

@@ -4,13 +4,50 @@ const NORMALIZED_KINDS = [
     ["integration", /(^|[/_.-])(integration|int)([/_.-]|$)/i],
     ["e2e", /(^|[/_.-])(e2e|end-to-end|offline|online)([/_.-]|$)/i],
 ];
-function classifiedKind(value) {
-    if (!value)
+// A runner that can only drive the whole system through its external interface
+// is evidence, not a guess. Nothing else here is: a token in a filename is a
+// convention someone may not have followed.
+const STRONG_RUNNER_KINDS = { playwright: "e2e" };
+// The most specific token in a segment wins, not the first one this list
+// happens to hold. `checkout-integration-e2e` is an e2e spec whose name notes
+// what it integrates; ordering by array position called it an integration.
+function segmentKind(segment) {
+    if (!segment)
         return undefined;
     // gatewayE2e.test.ts and responseIntegration.test.ts are conventional
     // camel-case paths too. Do not infer kinds from test titles or API usage.
-    const words = value.replace(/([a-z0-9])([A-Z])/g, "$1-$2");
-    return NORMALIZED_KINDS.find(([, pattern]) => pattern.test(words))?.[0];
+    const words = segment.replace(/([a-z0-9])([A-Z])/g, "$1-$2");
+    let best;
+    for (const [kind, pattern] of NORMALIZED_KINDS) {
+        const found = words.search(pattern);
+        if (found >= 0 && (best === undefined || found > best.at))
+            best = { kind, at: found };
+    }
+    return best?.kind;
+}
+function classifiedKind(value) {
+    if (!value)
+        return undefined;
+    return segmentKind(value);
+}
+// A directory is a deliberate choice about where a suite lives; a filename is
+// often just a description of the thing under test. Read directories from the
+// deepest inwards, so the nearest enclosing suite wins.
+function directoryKind(file) {
+    if (!file)
+        return undefined;
+    const segments = file.split(/[/\\]/).slice(0, -1);
+    for (let index = segments.length - 1; index >= 0; index -= 1) {
+        const kind = segmentKind(segments[index]);
+        if (kind)
+            return kind;
+    }
+    return undefined;
+}
+function basenameKind(file) {
+    if (!file)
+        return undefined;
+    return segmentKind(file.split(/[/\\]/).pop());
 }
 export function inferTestProvenance({ runner, file, project, explicitKind, }) {
     if (explicitKind?.trim()) {
@@ -30,20 +67,42 @@ export function inferTestProvenance({ runner, file, project, explicitKind, }) {
             source: "project",
         };
     }
-    const pathKind = classifiedKind(file);
-    if (pathKind) {
+    // A directory outranks the runner: putting a Playwright spec under
+    // `tests/integration/` is a statement about that suite.
+    const directory = directoryKind(file);
+    if (directory) {
+        return {
+            runner,
+            kind: directory,
+            ...(project ? { project } : {}),
+            source: "path",
+        };
+    }
+    // A filename token does not. `storefront-empire-integration.spec.ts` drove
+    // a real browser; reading `integration` out of its name reported 102 lines
+    // as untouched by E2E while a browser had rendered them. The runner knows
+    // better than the filename here, so it is asked first.
+    const strong = STRONG_RUNNER_KINDS[runner];
+    if (strong) {
+        return {
+            runner,
+            kind: strong,
+            ...(project ? { project } : {}),
+            source: "runner-default",
+        };
+    }
+    const basename = basenameKind(file);
+    if (basename) {
         return {
             runner,
-            kind: pathKind,
+            kind: basename,
             ...(project ? { project } : {}),
             source: "path",
         };
     }
-    const defaultKind = runner === "playwright"
-        ? "e2e"
-        : runner === "vitest" || runner === "jest" || runner === "node:test"
-            ? "unit"
-            : "unknown";
+    const defaultKind = runner === "vitest" || runner === "jest" || runner === "node:test"
+        ? "unit"
+        : "unknown";
     return {
         runner,
         kind: defaultKind,

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",