supercov 2.0.0 → 3.0.0

package/runtime/javascript/tap.mjs

@@ -0,0 +1,130 @@
+// Supercov node-tap adapter. The tap CLI runs each test file as a process of
+// its own and marks it with TAP_CHILD_ID; there the preload imports this
+// adapter, which patches the class every subtest is made by -- TestBase in
+// @tapjs/core (tap 18 and newer), Test in libtap (tap 15-16) -- so a suite
+// runs exactly as written. tap may run subtests in parallel (t.jobs)
+// and runs each body through an AsyncResource made when the subtest is, so
+// each subtest is made, and therefore runs, inside a coverage carrier of its
+// own, as node:test subtests do. What ran under it is written with the
+// subtest's outcome once it ends. The file's own top level, outside any
+// subtest, counts for the run. It computes no coverage.
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { beginBufferedServerEvidence, flushBufferedServerEvidence, takeNodeAssertionPhases, withCoverageCarrier, } from "./runtime.mjs";
+import { runnerExecutionScope, writeRunnerEvidence } from "./runnerEvidence.mjs";
+
+// The classes that make subtests in the project's tap.
+async function subtestClasses() {
+    const classes = [];
+    let fromTap;
+    try {
+        const fromProject = createRequire(join(process.cwd(), "package.json"));
+        const tap = realpathSync(dirname(fromProject.resolve("tap/package.json")));
+        fromTap = createRequire(join(tap, "package.json"));
+    }
+    catch {
+        return classes;
+    }
+    let core;
+    try {
+        core = dirname(fromTap.resolve("@tapjs/core/package.json"));
+    }
+    catch {
+        core = undefined;
+    }
+    if (core) {
+        // An ESM test file gets the ESM build and a CommonJS one the
+        // CommonJS build; they are different classes, so both are patched.
+        try {
+            classes.push((await import(pathToFileURL(join(core, "dist", "esm", "test-base.js")).href)).TestBase);
+        }
+        catch {
+            // Not every release ships both builds.
+        }
+        try {
+            classes.push(createRequire(import.meta.url)(join(core, "dist", "commonjs", "test-base.js")).TestBase);
+        }
+        catch {
+            // As above.
+        }
+        return classes;
+    }
+    // libtap is CommonJS, and its exports hide lib/: reach it from its main.
+    try {
+        const lib = dirname(fromTap.resolve("libtap"));
+        classes.push(createRequire(import.meta.url)(join(lib, "test.js")));
+    }
+    catch {
+        // Neither tap's own classes nor libtap's: tap 14 or older.
+    }
+    return classes;
+}
+
+export async function adaptTap(testFile) {
+    const evidenceDirectory = process.env.SUPERCOV_EVIDENCE_DIR;
+    if (!evidenceDirectory)
+        return;
+    for (const Class of await subtestClasses()) {
+        if (typeof Class?.prototype?.sub === "function" && !Class.prototype.sub.supercovTap)
+            patch(Class, testFile, evidenceDirectory);
+    }
+}
+
+function patch(TestBase, testFile, evidenceDirectory) {
+    const sub = TestBase.prototype.sub;
+    // Subtests of one parent that share a name, told apart by order.
+    const registrations = new WeakMap();
+    TestBase.prototype.sub = function supercovTapSub(Class, extra = {}, caller = this.sub) {
+        const names = [];
+        for (let test = this; test?.parent; test = test.parent)
+            names.unshift(test.name);
+        const name = [...names, extra.name || "(unnamed test)"].join(" > ");
+        const counts = registrations.get(this) ?? new Map();
+        registrations.set(this, counts);
+        const ordinal = counts.get(name) ?? 0;
+        counts.set(name, ordinal + 1);
+        const identity = {
+            runner: "tap",
+            file: testFile,
+            name,
+            ...(ordinal ? { registrationOrdinal: ordinal } : {}),
+        };
+        const scope = runnerExecutionScope(identity);
+        beginBufferedServerEvidence(scope);
+        let written = false;
+        const finish = (status) => {
+            if (written)
+                return;
+            written = true;
+            writeRunnerEvidence(identity, status, scope, evidenceDirectory, takeNodeAssertionPhases(scope), flushBufferedServerEvidence(scope));
+        };
+        // Both libtap and @tapjs/core announce the subtest they make, before
+        // they may start it and take it off their lists.
+        let subtest;
+        const made = (test) => {
+            subtest ??= test;
+        };
+        this.on?.("subtestAdd", made);
+        let result;
+        try {
+            result = withCoverageCarrier({ version: 1, scope }, () => Reflect.apply(sub, this, [Class, extra, caller]));
+        }
+        finally {
+            this.removeListener?.("subtestAdd", made);
+        }
+        if (!subtest) {
+            // Skipped, todo or filtered out: tap records a pass and makes no
+            // subtest. Nor does a parent that bailed out or already ended.
+            finish("skipped");
+            return result;
+        }
+        const settle = () => finish(extra.skip || extra.todo ? "skipped"
+            : typeof subtest.passing === "function" && !subtest.passing() ? "failed"
+                : "passed");
+        Promise.resolve(result).then(settle, () => finish("failed"));
+        return result;
+    };
+    TestBase.prototype.sub.supercovTap = true;
+}

package/runtime/javascript/transport.mjs

@@ -4,6 +4,11 @@ export const COVERAGE_SCOPE_COOKIE = "__supercov_scope";
 export const COVERAGE_PHASE_COOKIE = "__supercov_phase";
 export const COVERAGE_CARRIER_ENV = "SUPERCOV_CONTEXT";
 export const DEFAULT_SERVER_EVIDENCE_ROOT = "/tmp/supercov-server-evidence";
+// Buffer as it was when Supercov loaded. Tests replace globals -- axios's set
+// `globalThis.Buffer = undefined` to check it copes -- and the runtime runs
+// inside those tests; it must not fail where the application does not.
+var capturedBuffer = typeof Buffer === "undefined" ? void 0 : Buffer;
+
 function configuredServerEvidenceRoot() {
     return typeof process !== "undefined" &&
         process.env?.["SUPERCOV_SERVER_EVIDENCE_ROOT"]
@@ -68,13 +73,13 @@ export function decodeCoverageScope(encoded) {
     }
 }
 export function encodeCoverageCarrier(carrier) {
-    return Buffer.from(JSON.stringify(carrier), "utf8").toString("base64url");
+    return capturedBuffer.from(JSON.stringify(carrier), "utf8").toString("base64url");
 }
 export function decodeCoverageCarrier(encoded) {
     if (!encoded)
         return undefined;
     try {
-        const value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        const value = JSON.parse(capturedBuffer.from(encoded, "base64url").toString("utf8"));
         if (value.version !== 1)
             return undefined;
         if (value.scope) {

package/runtime/javascript/vitest.mjs

@@ -1,10 +1,9 @@
 import { createHash } from "node:crypto";
-import { mkdirSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 import { afterEach, beforeEach } from "vitest";
 import { coverageSnapshot as localCoverageSnapshot, activateCoverageScope as localActivateCoverageScope, enableRuntimeSnapshotEvidence as localEnableRuntimeSnapshotEvidence, resetCoverage as localResetCoverage, takeNodeAssertionPhases as localTakeNodeAssertionPhases, } from "./runtime.mjs";
 import { inferTestProvenance } from "./provenance.mjs";
-import { atomicWriteFileSync } from "./atomic.mjs";
+import { appendEvidenceRecord } from "./atomic.mjs";
 const evidenceDirectory = process.env["SUPERCOV_EVIDENCE_DIR"];
 const emittedSetupFiles = new Set();
 const attempts = new Map();
@@ -39,12 +38,10 @@ function titlePath(task) {
     }
     return names;
 }
-function writeEvidence(payload, suffix) {
+function writeEvidence(payload) {
     if (!evidenceDirectory)
         return;
-    const directory = resolve(process.cwd(), evidenceDirectory, suffix);
-    mkdirSync(directory, { recursive: true });
-    atomicWriteFileSync(resolve(directory, "mcdc.json"), `${JSON.stringify(payload)}\n`);
+    appendEvidenceRecord(resolve(process.cwd(), evidenceDirectory), "vitest-worker", payload);
 }
 beforeEach((context) => {
     const task = context.task;
@@ -72,7 +69,7 @@ beforeEach((context) => {
                 runtime: [setupSnapshot],
                 browser: [],
                 server: [],
-            }, `vitest-${task.file.id}-setup`);
+            });
         }
     }
     const testId = `vitest:${task.id}`;
@@ -118,7 +115,7 @@ afterEach((context) => {
         browser: [],
         server: [],
     };
-    writeEvidence(payload, `vitest-${task.id}-${retry}`);
+    writeEvidence(payload);
     activeScopes.delete(task.id);
     runtime.activateCoverageScope();
 });

package/runtime/javascript/vitestReporter.mjs

@@ -1,8 +1,7 @@
-import { mkdirSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { inferTestProvenance } from "./provenance.mjs";
-import { atomicWriteFileSync } from "./atomic.mjs";
+import { appendEvidenceRecord } from "./atomic.mjs";
 function sourcePath(moduleId) {
     const absolute = moduleId.startsWith("file:")
         ? fileURLToPath(moduleId)
@@ -63,11 +62,8 @@ export default class SupercovVitestReporter {
             browser: [],
             server: [],
         };
-        const safeId = testCase.id.replace(/[^a-zA-Z0-9_-]/g, "_");
         this.reportedAttempts.add(`${testCase.id}:${retry}`);
-        const directory = resolve(process.cwd(), evidenceDirectory, `vitest-${safeId}-${retry}-status`);
-        mkdirSync(directory, { recursive: true });
-        atomicWriteFileSync(resolve(directory, "mcdc.json"), `${JSON.stringify(payload)}\n`);
+        appendEvidenceRecord(resolve(process.cwd(), evidenceDirectory), "vitest-status", payload);
     }
     /** Vitest 2 compatibility; Vitest 3+ uses onTestCaseResult above. */
     onFinished(files = []) {
@@ -111,10 +107,7 @@ export default class SupercovVitestReporter {
                     browser: [],
                     server: [],
                 };
-                const safeId = String(task.id ?? names.join("-")).replace(/[^a-zA-Z0-9_-]/g, "_");
-                const directory = resolve(process.cwd(), evidenceDirectory, `vitest-${safeId}-${retry}-status`);
-                mkdirSync(directory, { recursive: true });
-                atomicWriteFileSync(resolve(directory, "mcdc.json"), `${JSON.stringify(payload)}\n`);
+                appendEvidenceRecord(resolve(process.cwd(), evidenceDirectory), "vitest-status", payload);
             }
             for (const child of task.tasks ?? [])
                 visit(child, file);

package/docs/assertion-agent.md

@@ -1,150 +0,0 @@
-# Mapping assertions with an agent
-
-Use these instructions when asking a coding agent to create or update an
-assertion map. The agent reads your tests and source, explains what each
-assertion checks, and edits the run's `assertions.json`. Supercov supplies the
-run evidence and checks the file's references and freshness.
-
-Start with [Understanding assertion coverage](assertions.md) for a prompt you
-can copy. The steps below are the agent's working instructions.
-
-## Choose a run and keep it fixed
-
-1. Use a matching current run, or run the requested suite through
-   `supercov -- <test command>`. Use the full suite for a suite-wide result.
-2. Read `supercov runs latest assertions --json` and keep `data.run` fixed for
-   this investigation. Edit the file at `data.map`.
-3. Check `data.inheritance` for reused work or fallback errors. Keep the old
-   runs and maps. Inspect changes before renewing inherited flows.
-4. Read the [map format](assertion-maps.md), also available through
-   `supercov docs assertion-maps`.
-
-Use a single writer for the map. Save atomically if your editor supports it.
-Do not change application code or tests unless the user also requested those
-changes. Never edit `assertions.state.json` or the run's recorded evidence.
-
-## Inspect the assertions and source
-
-```sh supercov-example
-npx supercov runs <run-id> assertions --limit 100 --json
-npx supercov runs <run-id> assertions report --view statements --limit 100 --json
-npx supercov runs <run-id> assertions report --view tests --limit 100 --json
-npx supercov runs <run-id> assertions report --view changes --limit 100 --json
-npx supercov runs <run-id> assertion <assertion-id>
-npx supercov runs <run-id> source src/shipping.js --offset 0 --limit 100
-```
-
-Follow every `pagination.nextOffset`; a page is not the whole result. Restart a
-paged read if its `revision` changes. Current source must match the pinned run.
-Use ordinary source-reading tools to inspect setup, inputs, mocks, callbacks,
-branches, called functions, helpers and relevant configuration.
-
-Preserve each assertion's ID and complete `at` anchor. Locations use one-based
-lines and UTF-8 byte columns. Restore recognized sites marked `inMap: false`
-when investigating them; removing an entry does not remove the assertion from
-Supercov's list.
-
-## Write precise explanations
-
-For each assertion:
-
-- Describe exactly what its predicate distinguishes in `observes`. Existence,
-  truthiness, length and substring checks do not imply equality of every field.
-- Split independently maintainable explanations into flows with stable IDs.
-  Start a new or changed flow with `basis: null`.
-- Choose `appliesTo` tests from the tests view using their exact file and name.
-  Select applicable cases explicitly for shared or parameterized assertions.
-- Use complete source statements from the statements view as node anchors when
-  possible. Write the relationships that connect those nodes to `$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`. 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.
-
-A fixture-only or absence explanation can have `countsAsAsserted: []`. For
-absence, describe the ordering or barrier and the observation window. Never
-credit an unexecuted body merely because executing it would violate the check.
-
-There is no known number of flows an assertion should have. Do not label an
-assertion complete just because you recorded one explanation.
-
-## Check why a node receives no credit
-
-Read the node's credit reason in assertion detail, or its computed `nodeCredit`
-entry in JSON. Compare the statement's execution evidence and selected test's
-outcome. Keep these report fields out of the editable map.
-
-A source node can be context only, lack a measured statement, have stale inputs,
-or lack matching passing assertion and execution evidence. Shared setup and
-background execution do not count as execution by every consuming test. Skipped
-and TODO tests supply no passing witness. An unobserved site in a passing test
-can indicate an untaken branch or missing measurement.
-
-Do not borrow another assertion's identity or another test's execution. Preserve
-zero-credit explanations when they accurately describe what the test checks.
-Use `assertions report --view excludedStatements` to inspect erased TypeScript
-imports. See [Investigating assertion evidence](assertion-evidence.md) for
-asynchronous and missing-evidence cases.
-
-For a large flow, page `assertion <id> --flow <flow-id> --view nodes --json` and
-`--view edges` separately. `--compact` omits repeated source text from the
-report; read the matching source separately and never save the compact objects
-back into the map.
-
-## Assess changes before renewing flows
-
-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
-remaining claims are unaffected. An empty affected-flow list needs a reason.
-Repair missing watches and update the affected graphs or selectors.
-
-Save these edits, then validate:
-
-```sh supercov-example
-npx supercov assertions validate --file <map-path> --json
-npx supercov runs <run-id> assertions validate --view changes --json
-npx supercov runs <run-id> assertions validate --view flows --json
-```
-
-Page the validation views too. Overall validity covers the whole map even when
-only one page is returned. Copy change `expectedBasis` tokens only after
-examining the corresponding impact assessments, then save. Validate again and
-copy flow tokens only for the claims you have examined.
-
-Obtain final flow tokens after saving change tokens: a change assessment can
-invalidate additional flows. Treat tokens as opaque; do not implement their
-hashing or manufacture them. Changing a claim after getting its token makes
-that token stale.
-
-## Check and summarize
-
-```sh supercov-example
-npx supercov runs <run-id> assertions check --require-mappings --json
-npx supercov runs <run-id> assertions report --view statements --limit 100 --json
-npx supercov runs <run-id>
-```
-
-Add `--require-observed` when every mapped site and test selector is expected to
-have passing evidence. Report skipped, TODO or untaken cases when that gate is
-unmet. Use `--min <percentage>` only for the user's chosen target; do not lower
-it or hide gaps to make a check pass.
-
-Report the run ID, map path, assertion percentage and counts, unresolved changes,
-missing execution and useful next tests. Distinguish statements credited by the
-map from raw line coverage and MC/DC. Mention which claims were newly examined
-and which were reused.
-
-A valid file does not prove the explanation or its completeness. A credited
-statement can change without failing a test when the edit preserves the observed
-property. Keep that distinction clear when recommending code changes.

package/docs/assertion-evidence.md

@@ -1,103 +0,0 @@
-# Investigating assertion evidence
-
-Use assertion details when a statement runs but receives no assertion credit,
-or when a mapped assertion has no passing occurrence. The report shows the
-recorded explanation and the evidence supporting it separately.
-
-```sh supercov-example
-npx supercov runs <run-id> assertions --needs-attention --limit 5
-npx supercov runs <run-id> assertion <assertion-id>
-```
-
-Replace the placeholders with the run and assertion IDs from your report.
-
-## Follow one assertion
-
-The detail identifies the exact assertion in the test and the source nodes in
-each flow. Each node has an explanation and a credit decision:
-
-| Decision | Meaning |
-| --- | --- |
-| Credited | The map counts this statement, its flow is current, and the selected passing test supplies both assertion and execution evidence. |
-| Not credited | The map claims this statement, but a reference, freshness or execution requirement is missing. Read the reason beside it. |
-| Context only | The node helps explain the assertion; the map does not claim it as an asserted statement. |
-
-The agent's explanation describes why a value or behavior reaches the assertion.
-Supercov's credit reason describes what the recorded evidence supports. A credit
-decision does not independently prove that explanation.
-
-## When a test has no source coverage
-
-You may see a warning that a test made assertions but has no source-coverage
-evidence. For example, a test might check a third-party parser, a constant, or
-configuration without calling measured application code.
-
-It can also mean application code ran in shared setup or across a process or
-network boundary that was not attributed to the test. Missing evidence alone
-cannot distinguish these cases. Inspect the test and the relevant statement:
-
-```sh supercov-example
-npx supercov runs <run-id> assertions report --view tests --limit 20
-npx supercov runs <run-id> assertions report --view statements --file src/shipping.js
-```
-
-In JSON output, a statement's `executionEvidence` distinguishes any recorded
-execution, passing tests and execution outside those tests. The tests view
-includes outcomes and identifies setup scopes. Use that information to decide
-whether to add a test, adjust the test setup or investigate measurement.
-
-## When a mapped assertion was not observed
-
-An assertion can appear in source without being reached in this run. Common
-causes include skipped or TODO tests and untaken branches inside passing tests.
-An unsupported custom assertion form or missing attribution can also prevent
-Supercov from recording the occurrence.
-
-Read the selected test's outcome before changing the map. A recorded skipped
-test and a test with no record are different cases. A passing sibling test does
-not supply evidence for an assertion it never reached.
-
-Use the stricter gate when you expect every mapped assertion and selected test
-to have passing evidence:
-
-```sh supercov-example
-npx supercov runs <run-id> assertions check --require-observed
-```
-
-This gate can intentionally fail for a suite with TODO or skipped cases. Keep
-those entries visible instead of deleting them to make the check pass.
-
-## Shared setup and asynchronous work
-
-Code executed once in shared setup does not count as execution by every test
-that later uses its result. Setup remains visible separately. If a statement
-needs its own test evidence, arrange a test that executes it and checks its
-behavior.
-
-Per-test `t.after` assertions are included for Node's test runner. Supported HTTP
-requests and test-owned WebSocket connections can carry a test's attribution
-into callbacks. A WebSocket shared across tests may still lack enough information
-to distinguish individual messages. Do not assign that work to a test merely
-because it ran around the same time.
-
-The regular report's **Runtime action phases** section is also separate from
-assertion coverage. Zero lines recorded inside action phases does not mean the
-agent-authored map credits zero statements.
-
-## Read a large flow
-
-Page the nodes and edges of one flow when the complete graph is too large:
-
-```sh supercov-example
-npx supercov runs <run-id> assertion <assertion-id> --flow <flow-id> --view nodes --limit 10 --compact
-npx supercov runs <run-id> assertion <assertion-id> --flow <flow-id> --view edges --limit 10
-npx supercov runs <run-id> source src/shipping.js --offset 0 --limit 20
-```
-
-`--compact` leaves source locations and credit reasons visible while omitting
-repeated source text. It only changes the displayed report. Follow the printed
-next-page command, or `pagination.nextOffset` in JSON, until the view is complete.
-Never copy compact report objects back into `assertions.json`.
-
-See [Assertion map format](assertion-maps.md) for fields and validation rules,
-and [Mapping assertions with an agent](assertion-agent.md) for the editing loop.