supercov 0.0.51 → 0.0.53

package/README.md

@@ -136,17 +136,23 @@ The denominator comes from source structure before the run, so adding or removin
 
 ## Install for your language
 
-The same binary ships through each language's own package manager, at the same version, from one release:
+Measuring a project should not start by installing another language. The same binary, at the same version, from one release:
 
 ```bash
-npx supercov -- npm test                          # npm
-uvx --from supercov-cli supercov -- pytest        # PyPI
-gem install supercov && supercov -- bundle exec rspec   # RubyGems
-cargo binstall supercov && supercov -- cargo test  # crates.io
+npx supercov -- npm test                                 # npm
+uvx --from supercov-cli supercov -- pytest               # PyPI
+gem install supercov && supercov -- bundle exec rspec    # RubyGems
+cargo binstall supercov && supercov -- cargo test        # crates.io
+go run github.com/supercorp-ai/supercov/cmd/supercov@latest -- go test ./...   # Go
+brew install supercorp-ai/tap/supercov && supercov -- ./gradlew test           # Homebrew
 ```
 
 `pip install supercov-cli` and `gem install supercov` install a wheel or gem that carries the binary for your platform; nothing is compiled. `cargo binstall` downloads that same binary from the GitHub release, while plain `cargo install supercov` builds it from source and needs Rust 1.95.
 
+A Go project needs Go and nothing else. Like any `go run` with a version suffix it resolves by module path and ignores the `go.mod` in your current directory, so it neither needs nor touches your module.
+
+Java and Kotlin have no registry of their own here, so a JVM project takes the binary directly -- Homebrew above, `npx` if Node is already present, or the platform archive from the [latest release](https://github.com/supercorp-ai/supercov/releases/latest). Maven and Gradle are driven as your test command, not as a plugin. Supercov adds the JUnit Platform launcher its measurement needs to the build file inside its own isolated workspace copy -- your `pom.xml` or `build.gradle` is never edited.
+
 ## Supported languages
 
 | Language | Status | Start with |
@@ -156,7 +162,7 @@ cargo binstall supercov && supercov -- cargo test  # crates.io
 | Rust | Available | `npx supercov -- cargo test` |
 | Python | Available | `npx supercov -- pytest` |
 | Ruby | Available | `npx supercov -- rspec` |
-| Go | Available | `npx supercov -- go test ./...` |
+| Go | Available | `go run github.com/supercorp-ai/supercov/cmd/supercov@latest -- go test ./...` |
 | Java | Available | `npx supercov -- mvn test` |
 | Kotlin | Available | `npx supercov -- ./gradlew test` |
 | Zig | Coming soon | — |

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.53",
   "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.53",
+    "@supercov/cli-darwin-x64": "0.0.53",
+    "@supercov/cli-linux-arm64-gnu": "0.0.53",
+    "@supercov/cli-linux-arm64-musl": "0.0.53",
+    "@supercov/cli-linux-x64-gnu": "0.0.53",
+    "@supercov/cli-linux-x64-musl": "0.0.53",
+    "@supercov/cli-win32-arm64": "0.0.53",
+    "@supercov/cli-win32-x64": "0.0.53"
   },
   "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/runtime/javascript/runtime.mjs

@@ -751,8 +751,19 @@ function withNodeAssertionPhase(operation, source, callback) {
   const scope = context.scope;
   if (!scope)
     return callback();
-  const existing = context.phaseId && assertionPhaseState(scope).phaseIds.has(context.phaseId);
-  if (existing)
+  // A lexically instrumented occurrence is an authored assertion site in its
+  // own right, even when it runs inside another assertion's callback: the
+  // validator passed to assert.throws is the ordinary case, and its inner
+  // assertions are what claim *what* the error says. Skipping every nested
+  // phase left those with no passing occurrence, so they could never earn
+  // credit however carefully they were mapped.
+  //
+  // What must still be skipped is the same call seen twice -- the module proxy
+  // firing inside the lexical wrapper. That path has no lexical source and
+  // arrives as a lazy stack fallback, so the shape of `source` tells them
+  // apart without comparing coordinates the transform has moved.
+  const nested = context.phaseId && assertionPhaseState(scope).phaseIds.has(context.phaseId);
+  if (nested && typeof source !== "string")
     return callback();
   // A lexical occurrence already identifies its source. Stack fallback is lazy
   // and qualified so transformed coordinates cannot impersonate original ones.
@@ -1244,20 +1255,35 @@ function tryBegin(successId, catchId) {
   return { successId, catchId, caught: false };
 }
 function tryCatch(frame, value) {
-  frame.caught = true;
+  // Record the outcome the moment it is known, not when the construct is left.
+  // The commit used to sit in the generated `finally`, and `process.exit()` in
+  // a catch body skips `finally` -- so a catch that ran and whose statements
+  // were credited was still reported as never entered. Statement probes fire
+  // in place and survived, which is what made the report contradict itself.
+  if (!frame.caught) {
+    frame.caught = true;
+    coverageHit(frame.catchId);
+  }
   return value;
 }
 function tryEnd(frame) {
-  coverageHit(frame.caught ? frame.catchId : frame.successId);
+  // Completing without catching is only knowable here.
+  if (!frame.caught) coverageHit(frame.successId);
 }
 function loopBegin(zeroId, enteredId) {
   return { zeroId, enteredId, entered: false };
 }
 function loopEntered(frame) {
-  frame.entered = true;
+  // Same reason as tryCatch: a loop body that exits the process would
+  // otherwise report zero iterations. Guarded so a loop still counts once,
+  // however many times it iterates.
+  if (!frame.entered) {
+    frame.entered = true;
+    coverageHit(frame.enteredId);
+  }
 }
 function loopEnd(frame) {
-  coverageHit(frame.entered ? frame.enteredId : frame.zeroId);
+  if (!frame.entered) coverageHit(frame.zeroId);
 }
 function mcdcBegin(id, meta) {
   if (!state.decisions.has(id)) {