supercov 0.0.51 → 0.0.52

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
@@ -279,12 +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. `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.
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supercov",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "description": "Coverage for coding agents and software factories \ud83c\udf19",
   "license": "MIT",
   "repository": {
@@ -97,14 +97,14 @@
     "test:launcher": "go vet ./cmd/... && go test ./cmd/..."
   },
   "optionalDependencies": {
-    "@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"
+    "@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,