@piwitests/instrumentation-nitro 0.60.0 → 0.61.0

package/README.md

@@ -1,6 +1,6 @@
 # @piwitests/instrumentation-nitro
 
-Nitro / Nuxt server plugin for [Piwi Dashboard](https://piwitests.dev) — captures Warning and Error log entries per HTTP request and delivers them to the Piwi Dashboard reporter via the `X-Piwi-Logs` response header.
+Nitro / Nuxt server plugin for [Piwi Dashboard](https://piwitests.dev) — captures Warning and Error log entries per HTTP request and delivers them to the Piwi Dashboard reporter via the `X-Piwi-Logs` response header, and, in a coverage build, the server code each test ran.
 
 During a Playwright test run, the reporter reads this header from every response and stores the entries alongside the network request. The entries are then available in the Piwi Dashboard test-case view and are included in the AI diagnosis context.
 
@@ -44,6 +44,44 @@ export default defineNuxtConfig({ nitro: { modules: ['@piwitests/instrumentation
 
 The manifest then lists every route Nitro scanned (`routes/`, `api/`) and every handler the config declares, middleware and a fallback catch-all (`/**`) left out, each with its method (`GET` for a route that answers any method), its pattern (`/api/orders/:id`) and its file relative to the git repository. Without the module, it lists only the routes the server has answered since it started (a route handler matched, so neither a 404 nor a public asset), which the reporter, reading it before any test runs, rarely sees. Nuxt pages are rendered by one catch-all route, so they are not listed: name them in a `piwi.manifest.json`.
 
+## Server coverage
+
+A **coverage build** records, per Playwright test, the server files, functions and lines the test ran, even when the
+tests run in parallel against one server. The Piwi reporter collects it with `coverage: { server: 'lines' }`
+([server coverage](https://piwitests.dev/features/server-coverage)). It needs the module above and the plugin, and
+`PIWI_COVERAGE_BUILD=true` when the server is built:
+
+```bash
+PIWI_COVERAGE_BUILD=true npx nitro build          # or nitro dev, or nuxi build for a Nuxt app's server/ code
+PIWI_TEST_LOGS_DISABLED=false node .output/server/index.mjs
+```
+
+```powershell
+$env:PIWI_COVERAGE_BUILD='true'; npx nitro build
+$env:PIWI_TEST_LOGS_DISABLED='false'; node .output/server/index.mjs
+```
+
+- **What the build does:** after Nitro's own transforms, the module instruments the server's own modules (under the
+  repository, outside `node_modules`): each function looks up the request being served when it is called, and each
+  statement marks itself as run. The lines are mapped to your source files through the build's source maps, when the
+  server is built, so the server reads no source map while it runs.
+- **Per request:** a response whose request ran instrumented code carries `X-Piwi-Coverage: <process key>.<sequence>.<secret>`;
+  the reporter asks `POST /__piwi/coverage/collect` for the coverage of the ids a test received, and
+  `GET /__piwi/coverage/run` for the run's. The answers are the ASP.NET Core package's. A request the server makes to
+  itself (`$fetch` while rendering) counts for the request that made it. A module's top-level code, which runs when the
+  module loads, counts for no test.
+- **Which lines:** the statements and functions Istanbul counts, each statement at its first line, so a file's
+  executable lines are the ones Vitest's coverage counts for it, and the dashboard's
+  [combined coverage](https://piwitests.dev/features/combined-coverage) counts both suites on the same lines.
+- **`PIWI_COVERAGE_MODE=run`** records the run level only, with no request named.
+- **Guards:** a coverage build refuses to start where `NODE_ENV` is `production` (which `nitro build` sets in the
+  server) unless `PIWI_TEST_LOGS_DISABLED=false`, and warns where the plugin is otherwise off.
+  `PIWI_COVERAGE_FORBIDDEN=true` at build time makes a coverage build fail. Never ship a coverage build: it runs slower
+  code, and its endpoints serve source paths and line numbers.
+- **Not covered:** dependencies Nitro keeps external, a Nuxt application's pages and components rendered on the
+  server, class field initializers, and callbacks a library runs outside the request's async context (they count for
+  no test).
+
 ## What gets captured
 
 | Source                               | What is captured                               |

package/dist/coverage-runtime.d.ts

@@ -0,0 +1,131 @@
+export type CoverageGranularity = 'files' | 'functions' | 'lines';
+export type LineRange = [number, number];
+/**
+ * One instrumented file in the span table: its repository-relative path, the
+ * checksum of its source, and per function (0 is the module's top-level code)
+ * its line range and the line of each payload entry (entry 0 has none: 0).
+ */
+export interface CoverageTableFile {
+    path: string;
+    checksums: string[];
+    /** Per function, its first and last line; null for the top-level code. */
+    f: Array<LineRange | null>;
+    /** Per function, the line of each entry; 0 when unknown, and for entry 0. */
+    s: number[][];
+}
+/** The span table the build writes: the instrumented files, by file id. */
+export interface CoverageTable {
+    v: 1;
+    files: Record<string, CoverageTableFile>;
+}
+/** The coverage of one request: per registered module, per function, its payload. */
+export interface RequestCoverage {
+    p: Array<Array<Uint8Array | undefined> | undefined>;
+    /** Instrumented code ran for the request: its response gets an id. */
+    ran: boolean;
+    /** Collected, evicted or never named: later writes go to the run level. */
+    closed: boolean;
+    /** The id its response carried, once named. */
+    id?: string;
+    /** About how many bytes its payloads hold. */
+    bytes: number;
+}
+export interface CoverageFile {
+    path: string;
+    runtime: 'server';
+    functions?: LineRange[];
+    lines?: LineRange[];
+    executable?: LineRange[];
+    allFunctions?: LineRange[];
+    checksums?: string[];
+}
+/** Ended requests kept until collected, at most. */
+export declare const MAX_KEPT_REQUESTS = 5000;
+/** Bytes of payloads kept, about, at most. */
+export declare const MAX_KEPT_BYTES: number;
+/** Request ids per collection call, at most. */
+export declare const MAX_IDS_PER_CALL = 10000;
+interface CoverageState {
+    run: boolean;
+    modules: CoverageModule[];
+    byId: Map<string, CoverageModule>;
+    table: CoverageTable | null;
+    tableSource: string | null;
+    enabled: boolean;
+    instanceId: string;
+    startedAt: string;
+    sequence: number;
+    kept: Map<string, RequestCoverage>;
+    keptBytes: number;
+    /**
+     * The payloads of the requests closed last, oldest first, read again by the run level: code a request started can
+     * still run once it is collected (a promise not awaited), and writes into the payloads it already holds.
+     */
+    closed: RequestCoverage['p'][];
+    closedBytes: number;
+}
+/** An instrumented module: its shared payloads, and the lookup its functions call on entry. */
+export declare class CoverageModule {
+    readonly id: string;
+    /** Its index in the state, the index of its payloads in a request's coverage. */
+    readonly n: number;
+    /** The payload length of each function. */
+    readonly l: number[];
+    /** The shared payload of each function, the run level. */
+    readonly s: Uint8Array[];
+    private readonly state;
+    constructor(id: string, 
+    /** Its index in the state, the index of its payloads in a request's coverage. */
+    n: number, 
+    /** The payload length of each function. */
+    l: number[], 
+    /** The shared payload of each function, the run level. */
+    s: Uint8Array[], state: CoverageState);
+    /** The payload function `i` records into: the request's being served, else the shared one. */
+    f(i: number): Uint8Array;
+}
+/** Called by each instrumented module when it loads: its file id and the payload length of each function. */
+export declare function __piwiModule(id: string, lengths: number[]): CoverageModule;
+/**
+ * Called once at startup by the plugin the module generates, with the span
+ * table as JSON. A coverage build refuses to start in production unless the
+ * plugin is explicitly enabled there, and warns in any other environment
+ * where it serves no coverage.
+ */
+export declare function enableCoverage(table: string): void;
+/** Whether this process runs a coverage build. */
+export declare function coverageActive(): boolean;
+/** A new request's coverage, or undefined when nothing records per request. */
+export declare function beginRequestCoverage(): RequestCoverage | undefined;
+/**
+ * The id a response names its request's coverage by, once instrumented code ran
+ * for it; the request is then kept until collected. Undefined when nothing ran.
+ */
+export declare function nameRequest(coverage: RequestCoverage): string | undefined;
+/** Called when the response is done: a request no response named goes to the run level. */
+export declare function settleRequest(coverage: RequestCoverage): void;
+export declare function instance(): {
+    id: string;
+    startedAt: string;
+};
+export declare function parseGranularity(value: unknown): CoverageGranularity;
+export declare class CoverageRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Answer `POST /__piwi/coverage/collect`: per group, the coverage of its
+ * requests merged, and the ids not held (`missing`); the requests answered are
+ * forgotten, their coverage kept at run level.
+ */
+export declare function collectCoverage(body: unknown): object;
+/**
+ * Answer `GET /__piwi/coverage/run`: the code that ran outside any request,
+ * every request collected or evicted, and the requests still kept; at `lines`,
+ * each file's executable lines and every function, for every file of the span
+ * table, loaded or not.
+ */
+export declare function runCoverage(granularity: CoverageGranularity): object;
+/** Forget every module and request: for tests. */
+export declare function resetCoverageForTests(): void;
+export {};

package/dist/coverage-runtime.js

@@ -0,0 +1,377 @@
+/**
+ * The coverage recorder of a coverage build (`PIWI_COVERAGE_BUILD=true`). The
+ * coverage transform (`coverage-transform.ts`) makes every instrumented module
+ * register here (`__piwiModule`) and every function ask its module for its
+ * payload when it is called: a `Uint8Array` where entry 0 marks the function as
+ * entered and each other entry one statement as run.
+ *
+ * - Inside a request, a function records into that request's payload, found
+ *   through the request store the plugin sets (`requestScope`); outside one, or
+ *   once its request is collected, into the shared payload, the run level.
+ * - A module's top-level code always records into the shared payload.
+ * - The plugin names a request on its response (`X-Piwi-Coverage`) when
+ *   instrumented code ran for it, and keeps it until the reporter collects it
+ *   (`POST /__piwi/coverage/collect`), up to `MAX_KEPT_REQUESTS` and
+ *   `MAX_KEPT_BYTES`, the oldest going first. `GET /__piwi/coverage/run` answers
+ *   the run level: the shared payloads and the requests still kept.
+ *
+ * The answers have the shape of the ASP.NET Core package's: the reporter reads
+ * them the same way. Line numbers come from the span table the build wrote
+ * (`enableCoverage`), never from a source map at run time.
+ *
+ * The state lives on a global, so a second copy of this module in the bundle
+ * records into the same one.
+ */
+import { randomBytes } from 'node:crypto';
+import { requestScope } from './request-scope.js';
+/** Ended requests kept until collected, at most. */
+export const MAX_KEPT_REQUESTS = 5000;
+/** Bytes of payloads kept, about, at most. */
+export const MAX_KEPT_BYTES = 64 * 1024 * 1024;
+/** Request ids per collection call, at most. */
+export const MAX_IDS_PER_CALL = 10_000;
+const STATE_KEY = Symbol.for('piwitests.coverage');
+const globals = globalThis;
+function state() {
+    return (globals[STATE_KEY] ??= {
+        run: process.env.PIWI_COVERAGE_MODE === 'run',
+        modules: [],
+        byId: new Map(),
+        table: null,
+        tableSource: null,
+        enabled: false,
+        instanceId: randomBytes(6).toString('hex'),
+        startedAt: new Date().toISOString(),
+        sequence: 0,
+        kept: new Map(),
+        keptBytes: 0,
+        closed: [],
+        closedBytes: 0,
+    });
+}
+/** An instrumented module: its shared payloads, and the lookup its functions call on entry. */
+export class CoverageModule {
+    constructor(id, 
+    /** Its index in the state, the index of its payloads in a request's coverage. */
+    n, 
+    /** The payload length of each function. */
+    l, 
+    /** The shared payload of each function, the run level. */
+    s, state) {
+        this.id = id;
+        this.n = n;
+        this.l = l;
+        this.s = s;
+        this.state = state;
+    }
+    /** The payload function `i` records into: the request's being served, else the shared one. */
+    f(i) {
+        if (this.state.run)
+            return this.s[i];
+        const coverage = requestScope.getStore()?.coverage;
+        if (coverage === undefined || coverage.closed)
+            return this.s[i];
+        let functions = coverage.p[this.n];
+        if (functions === undefined)
+            functions = coverage.p[this.n] = [];
+        let payload = functions[i];
+        if (payload === undefined) {
+            const length = this.l[i];
+            payload = functions[i] = new Uint8Array(length);
+            coverage.bytes += length + 32;
+            // A request already named is kept: what it records from now on counts toward the kept bytes too.
+            if (coverage.id)
+                this.state.keptBytes += length + 32;
+            coverage.ran = true;
+        }
+        return payload;
+    }
+}
+/** Called by each instrumented module when it loads: its file id and the payload length of each function. */
+export function __piwiModule(id, lengths) {
+    const current = state();
+    const known = current.byId.get(id);
+    if (known && known.l.length === lengths.length && known.l.every((length, i) => length === lengths[i]))
+        return known;
+    const module = new CoverageModule(id, current.modules.length, lengths, lengths.map((length) => new Uint8Array(length)), current);
+    current.modules.push(module);
+    current.byId.set(id, module);
+    return module;
+}
+/** Whether the guard the plugin applies lets it serve coverage in this environment. */
+function servesCoverage() {
+    const env = process.env.NODE_ENV;
+    if (process.env.PIWI_TEST_LOGS_DISABLED === 'true')
+        return false;
+    return env === 'development' || env === 'test' || process.env.PIWI_TEST_LOGS_DISABLED === 'false';
+}
+/**
+ * Called once at startup by the plugin the module generates, with the span
+ * table as JSON. A coverage build refuses to start in production unless the
+ * plugin is explicitly enabled there, and warns in any other environment
+ * where it serves no coverage.
+ */
+export function enableCoverage(table) {
+    const current = state();
+    current.enabled = true;
+    current.tableSource = table;
+    current.table = null;
+    if (servesCoverage())
+        return;
+    const message = 'this server was built with Piwi coverage (PIWI_COVERAGE_BUILD=true), which runs slower code and serves source paths and line numbers';
+    if (process.env.NODE_ENV === 'production') {
+        throw new Error(`[piwi] ${message}: refusing to start in production. Build without PIWI_COVERAGE_BUILD, or set PIWI_TEST_LOGS_DISABLED=false to serve it anyway.`);
+    }
+    console.warn(`[piwi] ${message}, and serves no coverage in this environment (NODE_ENV=${process.env.NODE_ENV ?? 'unset'}).`);
+}
+/** Whether this process runs a coverage build. */
+export function coverageActive() {
+    const current = globals[STATE_KEY];
+    return current !== undefined && (current.enabled || current.modules.length > 0);
+}
+/** A new request's coverage, or undefined when nothing records per request. */
+export function beginRequestCoverage() {
+    if (!coverageActive() || state().run)
+        return undefined;
+    return { p: [], ran: false, closed: false, bytes: 0 };
+}
+/** Add a request's payloads to the shared ones, the run level. */
+function mergeShared(payloads) {
+    const { modules } = state();
+    payloads.forEach((functions, n) => {
+        const module = modules[n];
+        if (!functions || !module)
+            return;
+        functions.forEach((payload, i) => {
+            if (!payload)
+                return;
+            const shared = module.s[i];
+            if (!shared)
+                return;
+            for (let k = 0; k < payload.length; k++)
+                if (payload[k])
+                    shared[k] = 1;
+        });
+    });
+}
+/**
+ * Add a request's payloads to the run level and stop handing them out. They stay among the closed ones until
+ * `MAX_KEPT_REQUESTS` or `MAX_KEPT_BYTES` pushes them out, merged once more then, so what a function already running
+ * still records is not lost.
+ */
+function close(coverage) {
+    if (coverage.closed)
+        return;
+    coverage.closed = true;
+    mergeShared(coverage.p);
+    const current = state();
+    current.closed.push(coverage.p);
+    current.closedBytes += coverage.bytes;
+    while (current.closed.length > MAX_KEPT_REQUESTS || current.closedBytes > MAX_KEPT_BYTES) {
+        const oldest = current.closed.shift();
+        mergeShared(oldest);
+        current.closedBytes -= bytesOf(oldest);
+    }
+    coverage.p = [];
+}
+function bytesOf(payloads) {
+    let bytes = 0;
+    for (const functions of payloads)
+        for (const payload of functions ?? [])
+            if (payload)
+                bytes += payload.length + 32;
+    return bytes;
+}
+/**
+ * The id a response names its request's coverage by, once instrumented code ran
+ * for it; the request is then kept until collected. Undefined when nothing ran.
+ */
+export function nameRequest(coverage) {
+    if (coverage.id)
+        return coverage.id;
+    if (!coverage.ran || coverage.closed)
+        return undefined;
+    const current = state();
+    coverage.id = `${current.instanceId}.${++current.sequence}.${randomBytes(16).toString('hex')}`;
+    current.kept.set(coverage.id, coverage);
+    current.keptBytes += coverage.bytes;
+    for (const [id, oldest] of current.kept) {
+        if (current.kept.size <= MAX_KEPT_REQUESTS && current.keptBytes <= MAX_KEPT_BYTES)
+            break;
+        if (id === coverage.id)
+            break;
+        forget(id, oldest);
+    }
+    return coverage.id;
+}
+/** Called when the response is done: a request no response named goes to the run level. */
+export function settleRequest(coverage) {
+    if (!coverage.id)
+        close(coverage);
+}
+function forget(id, coverage) {
+    const current = state();
+    current.kept.delete(id);
+    current.keptBytes -= coverage.bytes;
+    close(coverage);
+}
+function table() {
+    const current = state();
+    if (!current.table) {
+        let parsed = null;
+        try {
+            parsed = current.tableSource ? JSON.parse(current.tableSource) : null;
+        }
+        catch {
+            parsed = null;
+        }
+        current.table = parsed?.v === 1 && parsed.files ? parsed : { v: 1, files: {} };
+    }
+    return current.table;
+}
+function toRanges(values) {
+    const sorted = [...new Set(values)].filter((value) => value > 0).sort((a, b) => a - b);
+    const ranges = [];
+    for (const value of sorted) {
+        const last = ranges[ranges.length - 1];
+        if (last && value === last[1] + 1)
+            last[1] = value;
+        else
+            ranges.push([value, value]);
+    }
+    return ranges;
+}
+function uniqueFunctions(ranges) {
+    const byKey = new Map();
+    for (const range of ranges)
+        byKey.set(`${range[0]}:${range[1]}`, range);
+    return [...byKey.values()].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+}
+/** Add one function's payload to its file's accumulator. */
+function addPayload(files, module, i, payload) {
+    const file = table().files[module.id];
+    if (!file)
+        return;
+    let ran = false;
+    for (let k = 0; k < payload.length; k++)
+        if (payload[k])
+            ran = true;
+    if (!ran)
+        return;
+    let accumulator = files.get(file.path);
+    if (!accumulator)
+        files.set(file.path, (accumulator = { file, functions: [], lines: [] }));
+    const range = file.f[i];
+    if (range && payload[0])
+        accumulator.functions.push(range);
+    const lines = file.s[i] ?? [];
+    for (let k = 1; k < payload.length; k++) {
+        const line = lines[k];
+        if (payload[k] && line)
+            accumulator.lines.push(line);
+    }
+}
+function addRequest(files, coverage) {
+    const { modules } = state();
+    coverage.p.forEach((functions, n) => {
+        const module = modules[n];
+        if (!functions || !module)
+            return;
+        functions.forEach((payload, i) => payload && addPayload(files, module, i, payload));
+    });
+}
+function fileOf(accumulator, granularity) {
+    const out = { path: accumulator.file.path, runtime: 'server' };
+    if (granularity === 'files')
+        return out;
+    out.functions = uniqueFunctions(accumulator.functions);
+    if (granularity === 'lines')
+        out.lines = toRanges(accumulator.lines);
+    out.checksums = accumulator.file.checksums;
+    return out;
+}
+export function instance() {
+    const current = state();
+    return { id: current.instanceId, startedAt: current.startedAt };
+}
+export function parseGranularity(value) {
+    return value === 'files' || value === 'functions' ? value : 'lines';
+}
+export class CoverageRequestError extends Error {
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Answer `POST /__piwi/coverage/collect`: per group, the coverage of its
+ * requests merged, and the ids not held (`missing`); the requests answered are
+ * forgotten, their coverage kept at run level.
+ */
+export function collectCoverage(body) {
+    const request = body;
+    if (!request || typeof request !== 'object' || !Array.isArray(request.groups)) {
+        throw new CoverageRequestError(400, 'expected { granularity, groups: [{ key, requests }] }');
+    }
+    const granularity = parseGranularity(request.granularity);
+    const groups = request.groups;
+    const ids = groups.reduce((count, group) => count + (Array.isArray(group?.requests) ? group.requests.length : 0), 0);
+    if (ids > MAX_IDS_PER_CALL)
+        throw new CoverageRequestError(413, `at most ${MAX_IDS_PER_CALL} request ids per call`);
+    const current = state();
+    const answered = [];
+    const out = groups.map((group) => {
+        const files = new Map();
+        const missing = [];
+        for (const id of Array.isArray(group?.requests) ? group.requests : []) {
+            const coverage = typeof id === 'string' ? current.kept.get(id) : undefined;
+            if (!coverage) {
+                if (typeof id === 'string')
+                    missing.push(id);
+                continue;
+            }
+            addRequest(files, coverage);
+            answered.push([id, coverage]);
+        }
+        return { key: group?.key, files: [...files.values()].map((file) => fileOf(file, granularity)), missing };
+    });
+    for (const [id, coverage] of answered)
+        if (current.kept.has(id))
+            forget(id, coverage);
+    return { v: 1, instance: instance(), groups: out };
+}
+/**
+ * Answer `GET /__piwi/coverage/run`: the code that ran outside any request,
+ * every request collected or evicted, and the requests still kept; at `lines`,
+ * each file's executable lines and every function, for every file of the span
+ * table, loaded or not.
+ */
+export function runCoverage(granularity) {
+    const current = state();
+    const files = new Map();
+    for (const payloads of current.closed)
+        mergeShared(payloads);
+    for (const module of current.modules)
+        module.s.forEach((payload, i) => addPayload(files, module, i, payload));
+    for (const coverage of current.kept.values())
+        addRequest(files, coverage);
+    const out = [...files.values()].map((file) => fileOf(file, granularity));
+    if (granularity === 'lines') {
+        const byPath = new Map(out.map((file) => [file.path, file]));
+        for (const file of Object.values(table().files)) {
+            let entry = byPath.get(file.path);
+            if (!entry) {
+                entry = { path: file.path, runtime: 'server', functions: [], lines: [], checksums: file.checksums };
+                byPath.set(file.path, entry);
+                out.push(entry);
+            }
+            entry.executable = toRanges(file.s.flatMap((lines) => lines.slice(1)));
+            entry.allFunctions = uniqueFunctions(file.f.filter((range) => range !== null));
+        }
+    }
+    return { v: 1, instance: instance(), files: out.sort((a, b) => a.path.localeCompare(b.path)) };
+}
+/** Forget every module and request: for tests. */
+export function resetCoverageForTests() {
+    delete globals[STATE_KEY];
+}

package/dist/coverage-transform.d.ts

@@ -0,0 +1,68 @@
+import MagicString from 'magic-string';
+import { type SourceMapInput } from '@jridgewell/trace-mapping';
+import type { CoverageTableFile } from './coverage-runtime.js';
+/** The id of the plugin the module generates to hand the span table to the runtime. */
+export declare const COVERAGE_PLUGIN_ID = "#piwi/coverage";
+/** The source of the generated plugin: it hands the span table to the runtime at startup. */
+export declare function coveragePluginSource(runtimePath: string): string;
+/** An ESTree node as Rollup's parser returns it. */
+interface Node {
+    type: string;
+    start: number;
+    end: number;
+    [key: string]: unknown;
+}
+/**
+ * The offset of an arrow function's `=>`: the first one from `from` (the end of its last parameter, else its start)
+ * that is not inside a comment.
+ */
+export declare function arrowToken(code: string, from: number, to: number): number;
+export interface InstrumentResult {
+    code: string;
+    map: ReturnType<MagicString['generateMap']>;
+    file: CoverageTableFile;
+}
+export interface InstrumentOptions {
+    /** The file's id in the span table. */
+    fileId: string;
+    /** The import specifier of the coverage runtime. */
+    runtime: string;
+    /** Its path relative to the repository root, `/`-separated. */
+    path: string;
+    /** The checksums of its source, `sha256:<hex>`. */
+    checksums: string[];
+    /** The original line of a 1-based line and 0-based column of `code`; null when unknown. */
+    originalLine: (line: number, column: number) => number | null;
+}
+/** Instrument one module's code, given its ESTree (`Program`). */
+export declare function instrument(code: string, program: Node, options: InstrumentOptions): InstrumentResult;
+/** The Rollup plugin context methods the transform uses. */
+interface TransformContext {
+    parse(code: string): unknown;
+    getCombinedSourcemap(): SourceMapInput;
+}
+export interface CoveragePluginOptions {
+    /** The repository root: paths are relative to it, and only files under it are instrumented. */
+    root: string;
+    /** The coverage runtime's file, imported by every instrumented module. */
+    runtime: string;
+    /** Directories whose files are never instrumented: the integration's own. */
+    exclude: string[];
+}
+/** Whether a module id is application code the transform instruments. */
+export declare function instrumentable(id: string, options: CoveragePluginOptions): boolean;
+/** The Rollup plugin of a coverage build. */
+export declare function coverageRollupPlugin(options: CoveragePluginOptions): {
+    name: string;
+    transform(this: TransformContext, code: string, id: string): {
+        code: string;
+        map: import("magic-string").SourceMap;
+    } | null;
+    renderChunk(this: {
+        getModuleIds(): IterableIterator<string>;
+    }, code: string): {
+        code: string;
+        map: import("magic-string").SourceMap;
+    } | null;
+};
+export {};

package/dist/coverage-transform.js

@@ -0,0 +1,306 @@
+/**
+ * The coverage transform: the Rollup plugin the Nitro module adds to a coverage
+ * build (`PIWI_COVERAGE_BUILD=true`). It runs after Nitro's own transforms, so
+ * it reads JavaScript, and rewrites each application module so that:
+ *
+ * - the module registers with the coverage runtime (`__piwiModule`), with the
+ *   payload length of each of its functions;
+ * - each function, on entry, asks for its payload (`__piwi_m.f(i)`: the request's
+ *   being served, else the shared one) and marks entry 0;
+ * - each statement marks its own entry before it runs;
+ * - top-level statements mark the module's shared payload, the run level.
+ *
+ * The statements and functions are those `istanbul-lib-instrument` counts, and
+ * a statement's line is its first line (a variable's, its initializer's), as
+ * Istanbul and Vitest's coverage count them. Lines are mapped to the original
+ * file through the combined source map at build time and written into the span
+ * table the generated plugin hands to the runtime; a module carries only its
+ * file id and payload lengths.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import MagicString from 'magic-string';
+import { LEAST_UPPER_BOUND, TraceMap, originalPositionFor } from '@jridgewell/trace-mapping';
+/** The id of the plugin the module generates to hand the span table to the runtime. */
+export const COVERAGE_PLUGIN_ID = '#piwi/coverage';
+/** What the generated plugin carries until the bundle is rendered, then the span table as JSON. */
+const TABLE_PLACEHOLDER = '__PIWI_COVERAGE_TABLE__';
+const TABLE_PLACEHOLDER_LITERAL = /(["'])__PIWI_COVERAGE_TABLE__\1/;
+/** The source of the generated plugin: it hands the span table to the runtime at startup. */
+export function coveragePluginSource(runtimePath) {
+    return [
+        `import { enableCoverage } from ${JSON.stringify(runtimePath)};`,
+        `export default function piwiCoverage() {`,
+        `  enableCoverage(${JSON.stringify(TABLE_PLACEHOLDER)});`,
+        `}`,
+        '',
+    ].join('\n');
+}
+const FUNCTIONS = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
+/** The statements Istanbul counts, besides variable declarators with an initializer. */
+const STATEMENTS = new Set([
+    'ExpressionStatement',
+    'BreakStatement',
+    'ContinueStatement',
+    'DebuggerStatement',
+    'ReturnStatement',
+    'ThrowStatement',
+    'TryStatement',
+    'IfStatement',
+    'ForStatement',
+    'ForInStatement',
+    'ForOfStatement',
+    'WhileStatement',
+    'DoWhileStatement',
+    'SwitchStatement',
+    'WithStatement',
+    'LabeledStatement',
+]);
+/** The nodes whose `body` is a list of statements, each taking its own marker. */
+const LISTS = new Set(['Program', 'BlockStatement', 'StaticBlock']);
+/** The node keys a statement's own body sits under: a statement there, if not a block, is wrapped in one. */
+const BODY_KEYS = new Set(['consequent', 'alternate', 'body']);
+/**
+ * The offset of an arrow function's `=>`: the first one from `from` (the end of its last parameter, else its start)
+ * that is not inside a comment.
+ */
+export function arrowToken(code, from, to) {
+    for (let i = from; i < to; i++) {
+        if (code.startsWith('/*', i)) {
+            const end = code.indexOf('*/', i + 2);
+            i = end < 0 ? to : end + 1;
+        }
+        else if (code.startsWith('//', i)) {
+            const end = code.indexOf('\n', i + 2);
+            i = end < 0 ? to : end;
+        }
+        else if (code.startsWith('=>', i)) {
+            return i;
+        }
+    }
+    return code.lastIndexOf('=>', to);
+}
+function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.type === 'string';
+}
+/** Instrument one module's code, given its ESTree (`Program`). */
+export function instrument(code, program, options) {
+    const out = new MagicString(code);
+    const functions = [];
+    const top = { index: 0, payload: '__piwi_t', entries: [] };
+    functions.push({ range: null, scope: top });
+    const lineStarts = [0];
+    for (let i = 0; i < code.length; i++)
+        if (code.charCodeAt(i) === 10)
+            lineStarts.push(i + 1);
+    const lineOf = (offset) => {
+        let low = 0;
+        let high = lineStarts.length - 1;
+        while (low < high) {
+            const middle = (low + high + 1) >> 1;
+            if (lineStarts[middle] <= offset)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        return options.originalLine(low + 1, offset - lineStarts[low]) ?? 0;
+    };
+    /** The markers a statement adds, or none: its entries are added to the scope. */
+    const markersFor = (statement, scope) => {
+        let target = statement;
+        if (statement.type === 'ExportNamedDeclaration' && isNode(statement.declaration))
+            target = statement.declaration;
+        const offsets = [];
+        if (target.type === 'VariableDeclaration') {
+            for (const declarator of target.declarations ?? []) {
+                if (isNode(declarator.init))
+                    offsets.push(declarator.init.start);
+            }
+        }
+        else if (STATEMENTS.has(target.type)) {
+            offsets.push(target.start);
+        }
+        let markers = '';
+        for (const offset of offsets) {
+            scope.entries.push(offset);
+            markers += `${scope.payload}[${scope.entries.length}]=1;`;
+        }
+        return markers;
+    };
+    const visitList = (statements, scope) => {
+        for (const statement of statements) {
+            if (FUNCTIONS.has(statement.type)) {
+                visitFunction(statement, null, '');
+                continue;
+            }
+            if (statement.type === 'BlockStatement' || statement.type === 'StaticBlock') {
+                visitList(statement.body, scope);
+                continue;
+            }
+            const markers = markersFor(statement, scope);
+            if (markers)
+                out.appendLeft(statement.start, markers);
+            visitChildren(statement, scope);
+        }
+    };
+    const visitFunction = (fn, parent, key) => {
+        const isMethod = parent !== null &&
+            key === 'value' &&
+            (parent.type === 'MethodDefinition' || (parent.type === 'Property' && (parent.method || parent.kind !== 'init')));
+        const start = isMethod ? parent.start : fn.start;
+        const own = { index: functions.length, payload: '__piwi_p', entries: [] };
+        functions.push({ range: [start, Math.max(start, fn.end - 1)], scope: own });
+        const prologue = `const __piwi_p=(__piwi_m||__piwi_mi()).f(${own.index});__piwi_p[0]=1;`;
+        for (const param of fn.params ?? [])
+            visit(param, fn, 'params', own);
+        const body = fn.body;
+        if (body.type === 'BlockStatement') {
+            const statements = body.body;
+            let at = body.start + 1;
+            for (const statement of statements) {
+                if (statement.type !== 'ExpressionStatement' || typeof statement.directive !== 'string')
+                    break;
+                at = statement.end;
+            }
+            // After a directive, whose semicolon may be missing (`"use strict"` then a new line).
+            out.appendLeft(at, at > body.start + 1 ? `;${prologue}` : prologue);
+            visitList(statements.filter((statement) => typeof statement.directive !== 'string'), own);
+            return;
+        }
+        // An expression body: `x => expr` becomes `x => {…; return (expr)}`.
+        own.entries.push(body.start);
+        const params = fn.params ?? [];
+        const last = params[params.length - 1];
+        const arrow = arrowToken(code, last ? last.end : fn.start, body.start);
+        out.appendLeft(arrow + 2, `{${prologue}__piwi_p[1]=1;return (`);
+        out.prependLeft(fn.end, ')}');
+        visit(body, fn, 'body', own);
+    };
+    const visitChildren = (node, scope) => {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === 'type' || key === 'start' || key === 'end')
+                continue;
+            if (Array.isArray(value)) {
+                if ((node.type === 'SwitchCase' && key === 'consequent') || LISTS.has(node.type)) {
+                    visitList(value.filter(isNode), scope);
+                    continue;
+                }
+                for (const item of value)
+                    if (isNode(item))
+                        visit(item, node, key, scope);
+            }
+            else if (isNode(value)) {
+                visit(value, node, key, scope);
+            }
+        }
+    };
+    const visit = (node, parent, key, scope) => {
+        if (FUNCTIONS.has(node.type)) {
+            visitFunction(node, parent, key);
+            return;
+        }
+        if (node.type === 'BlockStatement' || node.type === 'StaticBlock') {
+            visitList(node.body, scope);
+            return;
+        }
+        // A statement standing as another's body (`if (a) b();`) is wrapped in a block to take its marker. A labeled
+        // statement's body is left as it is, so `continue label` keeps its loop.
+        if (parent !== null &&
+            parent.type !== 'LabeledStatement' &&
+            BODY_KEYS.has(key) &&
+            !Array.isArray(parent[key]) &&
+            (STATEMENTS.has(node.type) || node.type === 'VariableDeclaration') &&
+            !FUNCTIONS.has(parent.type)) {
+            const markers = markersFor(node, scope);
+            if (markers) {
+                out.appendLeft(node.start, `{${markers}`);
+                out.prependLeft(node.end, '}');
+            }
+        }
+        visitChildren(node, scope);
+    };
+    const body = program.body;
+    let at = 0;
+    for (const statement of body) {
+        if (statement.type !== 'ExpressionStatement' || typeof statement.directive !== 'string')
+            break;
+        at = statement.end;
+    }
+    visitList(body.filter((statement) => typeof statement.directive !== 'string'), top);
+    const lengths = functions.map(({ scope }) => scope.entries.length + 1);
+    // Before the top-level statements' markers, which may sit at the same offset.
+    out.prependLeft(at, (at > 0 ? ';' : '') +
+        `import { __piwiModule as __piwiM } from ${JSON.stringify(options.runtime)};` +
+        `var __piwi_m;function __piwi_mi(){return __piwi_m=__piwiM(${JSON.stringify(options.fileId)},${JSON.stringify(lengths)});}` +
+        `__piwi_mi();var __piwi_t=__piwi_m.s[0];`);
+    const file = {
+        path: options.path,
+        checksums: options.checksums,
+        f: functions.map(({ range }) => {
+            if (!range)
+                return null;
+            const first = lineOf(range[0]);
+            const last = lineOf(range[1]);
+            return first > 0 && last >= first ? [first, last] : null;
+        }),
+        s: functions.map(({ scope }) => [0, ...scope.entries.map(lineOf)]),
+    };
+    return { code: out.toString(), map: out.generateMap({ hires: true, includeContent: false }), file };
+}
+const SOURCE = /\.(?:[cm]?[jt]s|[jt]sx)$/;
+const GENERATED = /\/(?:node_modules|\.nitro|\.nuxt|\.output)\//;
+/** Whether a module id is application code the transform instruments. */
+export function instrumentable(id, options) {
+    if (id.startsWith('\0') || id.includes('?'))
+        return false;
+    const path = id.replace(/\\/g, '/');
+    const root = `${options.root.replace(/\\/g, '/').replace(/\/$/, '')}/`;
+    if (!path.startsWith(root) || GENERATED.test(path) || !SOURCE.test(path) || path.endsWith('.d.ts'))
+        return false;
+    return !options.exclude.some((dir) => path.startsWith(`${dir.replace(/\\/g, '/').replace(/\/$/, '')}/`));
+}
+/** The Rollup plugin of a coverage build. */
+export function coverageRollupPlugin(options) {
+    const files = new Map();
+    const root = `${options.root.replace(/\\/g, '/').replace(/\/$/, '')}/`;
+    return {
+        name: 'piwi-coverage',
+        transform(code, id) {
+            if (!instrumentable(id, options))
+                return null;
+            const path = id.replace(/\\/g, '/').slice(root.length);
+            let source;
+            try {
+                source = readFileSync(id);
+            }
+            catch {
+                return null;
+            }
+            const fileId = createHash('sha256').update(path).digest('hex').slice(0, 16);
+            const traced = new TraceMap(this.getCombinedSourcemap());
+            const result = instrument(code, this.parse(code), {
+                fileId,
+                runtime: options.runtime,
+                path,
+                checksums: [`sha256:${createHash('sha256').update(source).digest('hex')}`],
+                originalLine: (line, column) => originalPositionFor(traced, { line, column }).line ??
+                    originalPositionFor(traced, { line, column, bias: LEAST_UPPER_BOUND }).line,
+            });
+            files.set(id, { fileId, file: result.file });
+            return { code: result.code, map: result.map };
+        },
+        renderChunk(code) {
+            const match = TABLE_PLACEHOLDER_LITERAL.exec(code);
+            if (!match)
+                return null;
+            const live = new Set(this.getModuleIds());
+            const table = { v: 1, files: {} };
+            for (const [id, { fileId, file }] of files)
+                if (live.has(id))
+                    table.files[fileId] = file;
+            const out = new MagicString(code);
+            out.overwrite(match.index, match.index + match[0].length, JSON.stringify(JSON.stringify(table)));
+            return { code: out.toString(), map: out.generateMap({ hires: true }) };
+        },
+    };
+}

package/dist/index.js

@@ -1,4 +1,3 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomBytes } from 'node:crypto';
 import { gzipSync } from 'node:zlib';
 import { consola } from 'consola';
@@ -6,6 +5,8 @@ import { createError } from 'h3';
 import { verifyProbeHeader, ProbeNonceCache } from './probe.js';
 import { buildRouteManifest, recordObservedRoute, matchedRoutePattern, } from './manifest.js';
 import { declaredRoutes } from './route-table.js';
+import { requestScope } from './request-scope.js';
+import { beginRequestCoverage, collectCoverage, coverageActive, CoverageRequestError, nameRequest, parseGranularity, runCoverage, settleRequest, } from './coverage-runtime.js';
 import { routeMatchesRequest, faultStatus, faultDelayMs, isThrowFault, isExtremeFault, isDataFault, isDependencyFault, dependencyCallMatches, mutateResponseBody, appliedFaultLabel, } from './faults.js';
 export { verifyProbeHeader, signProbeMessage, probeSigningMessage, PROBE_TTL_MS, } from './probe.js';
 export { buildRouteManifest, recordObservedRoute, collapsePathPattern } from './manifest.js';
@@ -69,10 +70,11 @@ function pushSpan(store, span) {
 }
 /** Signed probe nonces already honored this process, so a header is single-use. */
 const probeNonces = new ProbeNonceCache();
-// Links consola calls and recorded spans to the request being handled. The store
-// is scoped with als.run() around the whole downstream handler chain: a binding
-// made with enterWith() from a request hook dies with the hook's own async scope.
-const als = new AsyncLocalStorage();
+// Links consola calls, recorded spans and coverage to the request being handled.
+// The store is scoped with als.run() around the whole downstream handler chain: a
+// binding made with enterWith() from a request hook dies with the hook's own async
+// scope. The coverage runtime reads the same store (`request-scope.ts`).
+const als = requestScope;
 /**
  * Record a server-side span for the in-flight request. Shows up in the Piwi
  * Dashboard test-case view (and AI diagnosis) under the request's root span.
@@ -84,8 +86,9 @@ export function recordServerSpan(span) {
     if (store)
         pushSpan(store, span);
 }
-// The consola reporter is process-global — register it only once.
-let reporterAdded = false;
+// The consola reporter is process-global, and so is the request store it writes into: register it once per
+// process, even when the bundle holds two copies of this module.
+const REPORTER_KEY = Symbol.for('piwitests.consolaReporter');
 // Capture and probe verification run only in development and test (the ASP.NET
 // package's default allow-list is Development and Test): NODE_ENV must be
 // `development` or `test`. Any other value, or none at all (`node
@@ -100,6 +103,69 @@ const TEST_LOGS_DISABLED = process.env.PIWI_TEST_LOGS_DISABLED === 'true' ||
 const PROBE_SECRET = process.env.PIWI_PROBE_SECRET || undefined;
 /** The declared-surface route path the plugin serves outside production. */
 const MANIFEST_PATH = '/__piwi/manifest';
+/** The coverage endpoints a coverage build serves beside the manifest. */
+const COVERAGE_COLLECT_PATH = '/__piwi/coverage/collect';
+const COVERAGE_RUN_PATH = '/__piwi/coverage/run';
+/** Largest collection body read, in bytes. */
+const MAX_COVERAGE_BODY_BYTES = 1024 * 1024;
+/** The body of a request as JSON, refused past `MAX_COVERAGE_BODY_BYTES`. */
+async function readJsonBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_COVERAGE_BODY_BYTES)
+            throw new CoverageRequestError(413, 'the body is limited to 1 MB');
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new CoverageRequestError(400, 'the body is not JSON');
+    }
+}
+/** Answer a coverage endpoint; false when the request is not one, so it reaches the application. */
+function serveCoverage(event, requestPath) {
+    if ((requestPath !== COVERAGE_COLLECT_PATH && requestPath !== COVERAGE_RUN_PATH) || !coverageActive())
+        return false;
+    const res = event.node.res;
+    const method = String(event.method ?? event.node.req.method ?? 'GET').toUpperCase();
+    const answer = (status, body) => {
+        res.statusCode = status;
+        res.setHeader('Content-Type', 'application/json');
+        res.setHeader('Cache-Control', 'no-store');
+        res.end(JSON.stringify(body));
+    };
+    const fail = (error) => error instanceof CoverageRequestError
+        ? answer(error.status, { error: error.message })
+        : answer(500, { error: errorMessageOf(error) });
+    if (requestPath === COVERAGE_RUN_PATH) {
+        if (method !== 'GET') {
+            answer(405, { error: 'GET only' });
+            return true;
+        }
+        const query = new URL(String(event.node.req.url ?? ''), 'http://localhost').searchParams;
+        try {
+            answer(200, runCoverage(parseGranularity(query.get('granularity'))));
+        }
+        catch (error) {
+            fail(error);
+        }
+        return true;
+    }
+    if (method !== 'POST') {
+        answer(405, { error: 'POST only' });
+        return true;
+    }
+    readJsonBody(event.node.req)
+        .then((body) => answer(200, collectCoverage(body)))
+        .catch(fail);
+    return true;
+}
+function errorMessageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 /**
  * Routes the server has matched this process, accumulated for `/__piwi/manifest`
  * next to the declared ones: Nitro exposes no runtime route table, so without the
@@ -126,8 +192,9 @@ function resolveHandlerFile(event) {
 const piwiTestLogs = (nitroApp) => {
     if (TEST_LOGS_DISABLED)
         return;
-    if (!reporterAdded) {
-        reporterAdded = true;
+    const globals = globalThis;
+    if (!globals[REPORTER_KEY]) {
+        globals[REPORTER_KEY] = true;
         consola.addReporter({
             log(logObj) {
                 if (logObj.level > 1)
@@ -156,6 +223,8 @@ const piwiTestLogs = (nitroApp) => {
         // returned early when log capture is disabled): the routes the module declared,
         // then the ones observed.
         const requestPath = String(event.path ?? event.node.req.url ?? '').split('?')[0] ?? '';
+        if (serveCoverage(event, requestPath))
+            return;
         if (requestPath === MANIFEST_PATH) {
             const routes = new Map();
             for (const route of [...declaredRoutes(), ...observedRoutes.values()])
@@ -167,11 +236,14 @@ const piwiTestLogs = (nitroApp) => {
             return;
         }
         const enclosing = als.getStore();
+        const nested = enclosing !== undefined && !enclosing.ended;
+        const coverage = nested ? enclosing.coverage : beginRequestCoverage();
         const store = {
             logs: [],
             spans: [],
             startMs: Date.now(),
-            ...(enclosing && !enclosing.ended ? { parent: enclosing } : {}),
+            ...(nested ? { parent: enclosing } : {}),
+            ...(coverage ? { coverage } : {}),
         };
         event.context._piwiLogs = store.logs;
         event.context._piwiSpans = store.spans;
@@ -210,6 +282,19 @@ const piwiTestLogs = (nitroApp) => {
         // 'beforeResponse' hook (h3 skips onBeforeResponse once the error handler
         // has called res.end).
         const res = event.node.res;
+        // Name the request's coverage on its response once instrumented code ran for it. Every way of sending headers
+        // goes through writeHead (`end` and `write` call it when nothing did), so a streamed response is named too. A
+        // request the server makes to itself is named by the outer one.
+        if (coverage && !nested) {
+            const originalWriteHead = res.writeHead;
+            res.writeHead = function (...args) {
+                const id = nameRequest(coverage);
+                if (id && !res.headersSent)
+                    res.setHeader('X-Piwi-Coverage', id);
+                return originalWriteHead.apply(this, args);
+            };
+            res.once('close', () => settleRequest(coverage));
+        }
         const originalEnd = res.end.bind(res);
         res.end = (...args) => {
             if (!res.headersSent) {

package/dist/module.js

@@ -6,13 +6,50 @@
  * ```
  *
  * In Nuxt, the same entry goes under `nitro.modules`. Without it, `/__piwi/manifest`
- * lists only the routes the server has answered. Modules run before Nitro scans its
+ * lists only the routes the server has answered. With `PIWI_COVERAGE_BUILD=true`
+ * set when the server is built, it also makes a coverage build. Modules run before Nitro scans its
  * route files, so the table is read when the server is bundled, again on each
  * rebuild in development.
  */
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { COVERAGE_PLUGIN_ID, coveragePluginSource, coverageRollupPlugin } from './coverage-transform.js';
 import { ROUTE_TABLE_ID, declaredRoutesOf, routeTablePlugin } from './route-table.js';
+/** This package's own directory: its files are never instrumented. */
+const packageDir = dirname(dirname(fileURLToPath(import.meta.url)));
+/** The coverage runtime beside this file: the built one, or the source when the module runs from source. */
+function coverageRuntimePath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const built = join(here, 'coverage-runtime.js');
+    return existsSync(built) ? built : join(here, 'coverage-runtime.ts');
+}
+/**
+ * A coverage build (`PIWI_COVERAGE_BUILD=true` when the server is built): the
+ * coverage transform instruments the application's modules, Nitro writes the
+ * source maps it reads, and a generated plugin hands the span table to the
+ * coverage runtime at startup. `PIWI_COVERAGE_FORBIDDEN=true` makes such a
+ * build fail, for a pipeline whose output must never carry it.
+ */
+function setUpCoverage(nitro, root) {
+    if (process.env.PIWI_COVERAGE_BUILD !== 'true')
+        return;
+    if (process.env.PIWI_COVERAGE_FORBIDDEN === 'true') {
+        throw new Error('[piwi] PIWI_COVERAGE_BUILD=true in a build where PIWI_COVERAGE_FORBIDDEN=true: a coverage build must not reach this output.');
+    }
+    const runtime = coverageRuntimePath();
+    nitro.options.sourceMap = true;
+    nitro.options.virtual[COVERAGE_PLUGIN_ID] = () => coveragePluginSource(runtime);
+    nitro.options.plugins.unshift(COVERAGE_PLUGIN_ID);
+    // Last, so it reads what Nitro's own transforms (esbuild) produce. Each build makes its config anew (a development
+    // server's full reload too), so each gets its own plugin.
+    nitro.hooks.hook('rollup:before', (_nitro, config) => {
+        const plugins = (config.plugins ??= []);
+        if (!plugins.some((plugin) => plugin?.name === 'piwi-coverage')) {
+            plugins.push(coverageRollupPlugin({ root, runtime, exclude: [packageDir] }));
+        }
+    });
+}
 /** The repository root above `dir` (the closest folder holding `.git`), else `dir` itself. */
 function repositoryRoot(dir) {
     for (let current = dir;; current = dirname(current)) {
@@ -28,6 +65,7 @@ const piwiRouteTable = {
         const root = repositoryRoot(nitro.options.rootDir);
         nitro.options.virtual[ROUTE_TABLE_ID] = () => routeTablePlugin(declaredRoutesOf([...nitro.scannedHandlers, ...nitro.options.handlers], root));
         nitro.options.plugins.push(ROUTE_TABLE_ID);
+        setUpCoverage(nitro, root);
     },
 };
 export default piwiRouteTable;

package/dist/request-scope.d.ts

@@ -0,0 +1,2 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+export declare const requestScope: AsyncLocalStorage<object>;

package/dist/request-scope.js

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/**
+ * The request being served, shared by the plugin (logs, spans, probes) and the
+ * coverage runtime. It lives on a global so both read the same store even when
+ * the server bundle holds two copies of this module: the plugin can load from
+ * `node_modules` while the coverage runtime is bundled, or the reverse.
+ */
+const SCOPE_KEY = Symbol.for('piwitests.requestScope');
+const globals = globalThis;
+export const requestScope = (globals[SCOPE_KEY] ??= new AsyncLocalStorage());

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@piwitests/instrumentation-nitro",
-  "version": "0.60.0",
-  "description": "Nitro/Nuxt server plugin for sending backend logs to Piwi Dashboard via the X-Piwi-Logs response header",
+  "version": "0.61.0",
+  "description": "Nitro/Nuxt server plugin for Piwi Dashboard: backend logs (X-Piwi-Logs), server spans, probes, the route manifest and per-test server coverage",
   "homepage": "https://piwitests.dev",
   "repository": {
     "type": "git",
@@ -21,6 +21,10 @@
     "./module": {
       "types": "./dist/module.d.ts",
       "import": "./dist/module.js"
+    },
+    "./coverage-runtime": {
+      "types": "./dist/coverage-runtime.d.ts",
+      "import": "./dist/coverage-runtime.js"
     }
   },
   "keywords": [
@@ -29,7 +33,8 @@
     "playwright",
     "piwi-dashboard",
     "server-logs",
-    "test-results"
+    "test-results",
+    "code-coverage"
   ],
   "author": "piwitests",
   "license": "MIT",
@@ -43,6 +48,13 @@
   "files": [
     "dist/"
   ],
+  "dependencies": {
+    "@jridgewell/trace-mapping": "^0.3.31",
+    "magic-string": "^0.30.21"
+  },
+  "devDependencies": {
+    "rollup": "^4.65.0"
+  },
   "peerDependencies": {
     "consola": ">=3.0.0",
     "h3": ">=1.0.0",