@specific.dev/spectest 0.81.1 → 0.83.0

package/dist/coverage.d.ts

@@ -8,11 +8,6 @@ export declare const NODE_COVERAGE_EMPTY_REPORT = "coverage-spectest-empty.json"
 /** Prefix of the per-process sockets the node hook answers on, relative
  *  to the coverage dir: `.ctl-<pid>`. */
 export declare const NODE_COVERAGE_SOCKET_PREFIX = ".ctl-";
-/** Key of the content hash (`sha256:<hex>`) a shipped `source-map-cache`
- *  entry carries, and key of the stub that stands in for an entry that
- *  shipped earlier on the same branch. See {@link compactV8Document}. */
-export declare const SOURCE_MAP_HASH_KEY = "spectestHash";
-export declare const SOURCE_MAP_REF_KEY = "spectestRef";
 /** What `configure` learns about the service it rewrites. */
 export interface CoverageConfigureInfo {
     /** The services-map key. */
@@ -53,9 +48,6 @@ export interface CoverageCaptureContext {
     }>;
     /** Write one report file (name relative to the directory). */
     writeReport(name: string, content: string): Promise<void>;
-    /** Read one file out of the container (`docker cp`). `null` when it
-     *  does not exist. Absent on a context that has no container. */
-    readContainerFile?(containerPath: string): Promise<Buffer | null>;
     /** Aborts when the per-service capture budget runs out. */
     signal: AbortSignal;
 }
@@ -109,55 +101,89 @@ export declare function coverageAdapters(cov: ServiceCoverage | undefined): read
 export declare function applyCoverageAdapters<S extends ServiceConfig>(key: string, svc: S): S;
 /** `env` with `value` appended to `name` (space-separated), or set. */
 export declare function appendEnvFlag(env: Readonly<Record<string, string>> | undefined, name: string, value: string): Record<string, string>;
+/** Env var the hook reads: the coverage directory inside the container. */
+export declare const NODE_COVERAGE_DIR_ENV = "SPECTEST_COVERAGE_DIR";
+/** Subdirectory of the coverage dir where the hook writes one record per
+ *  script (`scripts/<id>.json`, {@link NODE_COVERAGE_HOOK}). Shipped
+ *  once, like a dump. */
+export declare const NODE_COVERAGE_SCRIPTS_SUBDIR = "scripts";
+/** Hidden subdirectory holding one empty marker per script record ever
+ *  written on this branch. The hook's "written already?" check, which
+ *  must survive the harness shipping and removing the record; hidden,
+ *  so the harness never reads it. */
+export declare const NODE_COVERAGE_MARKERS_SUBDIR = ".spectest/scripts";
+/** Name prefix of the dumps the hook writes: `node-<pid>-<thread>-<ms>-<n>.json`. */
+export declare const NODE_COVERAGE_DUMP_PREFIX = "node-";
 /**
- * The hook `node()` mounts and `--require`s into every node process of
- * the container. Node writes V8 coverage JSON into `NODE_V8_COVERAGE`
- * when a process exits; a long-lived server never exits, so the hook
- * binds a Unix socket in the coverage directory and calls
- * `v8.takeCoverage()` on request. **Every** process binds its own socket
- * (`.ctl-<pid>`) — there is no "first process owns it" rule, because the
- * first node process is often a wrapper (`pnpm exec`, the `tsx` binary,
- * `npm run`) whose child is the real server; a single socket on the
- * wrapper dumped the wrapper and silently never the server (reported by
- * a user 2026-08-27). At capture spectest asks every live socket and
- * unlinks the stale ones. Unref'd, so a short-lived process still exits.
- * Main thread only: a worker thread inherits `NODE_OPTIONS`, and tsx's
- * ESM loader thread bound the shared per-pid path last, so every
- * `--import tsx` server answered with the loader's coverage — the app's
- * main thread was never dumped (found in the same user's first full run).
- * No signal is used: signals are claimed by frameworks (SIGUSR2 stops a
- * Temporal worker, restarts nodemon), a socket is nobody's.
+ * The hook `node()` mounts at {@link NODE_COVERAGE_HOOK_PATH} and
+ * `--require`s into every node process of the service. **It is the
+ * collector**: nothing outside the process reads, converts or looks
+ * anything up. Runs in every thread (a worker thread inherits
+ * `NODE_OPTIONS`); reads one env var, {@link NODE_COVERAGE_DIR_ENV}; uses
+ * node built-ins only, so it runs in any image that runs node.
+ *
+ * What it does:
+ *
+ * - Starts V8 precise (block, counted) coverage through the in-process
+ *   inspector session. `NODE_V8_COVERAGE` is **not** set: Node would then
+ *   write everything the process loaded at every exit — `node:`
+ *   internals, every `node_modules` file, and the whole source map of
+ *   every script that carries a `sourceMappingURL` comment, with or
+ *   without `--enable-source-maps`. For a bundled CLI that was 12 MB per
+ *   invocation, inside the test's own time, parsed again at capture.
+ * - **Takes** on request — the main thread binds a Unix socket
+ *   `.ctl-<pid>` in the coverage directory and takes on `dump\n`; every
+ *   process binds its own (the first node process is often a wrapper,
+ *   `pnpm exec`, `tsx`, `npm run`) — and in every thread's `exit`
+ *   handler, which is how a short-lived CLI and a worker thread report.
+ *   The in-process session answers synchronously, so the exit handler
+ *   has the result before the process is gone. A take resets V8's
+ *   counters: every dump is the delta since the previous take. No
+ *   signal is used: signals are claimed by frameworks (SIGUSR2 stops a
+ *   Temporal worker, restarts nodemon), a socket is nobody's.
+ * - Writes a **dump** `node-<pid>-<thread>-<ms>-<n>.json`: the app's own
+ *   scripts (`file://`, outside `node_modules` and `.cache`, not the
+ *   hook) in which some range count is above zero, and of each only the
+ *   functions that ran, each one flat array: `[start, length, count]`
+ *   for its extent (V8's first range), then `[offset from start,
+ *   length, count]` per block range in V8's order. Name and block flag
+ *   are in the record, joined on the extent. Nothing when nothing ran.
+ *   `{ spectestVersion: 2, result: [{ url, spectestScript, functions:
+ *   [[s, l, c, o, l, c, …], …] }] }`.
+ * - Writes, **once per script per branch**, a **script record**
+ *   `scripts/<id>.json` (`id` = sha256 of the URL): the length of every
+ *   line of the source V8 compiled (`Debugger.getScriptSource`, so a
+ *   transpiled module — tsx, ts-node, a bundler's register hook — is
+ *   described by the text V8 ran, not the file on disk), every function
+ *   with its extent (the skeleton: what a dump's "ran" functions are a
+ *   subset of, so a never-run function is known to exist), and the
+ *   source map: the inline `data:` map in the text, the file the last
+ *   `sourceMappingURL` comment names, or `<script>.map` next to the
+ *   script; `sourcesContent` dropped (the sources are the repository).
+ *   "Once per branch" is a marker file under `.spectest/scripts/`: the
+ *   directory is shared by every process of the service and forks with
+ *   the environment, so a record written at bring-up or by an ancestor
+ *   is never written again, whichever process comes next.
+ *
+ * The harness ships new dumps and new records as they are. It parses
+ * nothing and touches no container; the control plane derives lines
+ * from the stored documents (`SUBSET_RUNS.md`).
  */
 export declare const NODE_COVERAGE_HOOK: string;
 /**
  * Coverage for a Node service — a long-lived server, or a container whose
  * node processes are short-lived CLIs run by `ctx.exec`. Sets
- * `NODE_V8_COVERAGE` to the coverage directory (every node process in the
- * container then writes V8 coverage JSON when it exits) and `--require`s
- * a hook that lets spectest ask every live node process for a dump at
- * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
- * `tsx`). Nothing for the app to write.
- *
- * What ships is the V8 documents themselves, compacted
- * ({@link compactV8Document}): the app's own scripts that ran, and each
- * script's source map once per branch. A map comes from Node's own
- * `source-map-cache` when Node found one through the script's
- * `sourceMappingURL` (it caches maps under NODE_V8_COVERAGE with or
- * without `--enable-source-maps`), else from `<script>.map` next to the
- * script, read out of the container once
- * ({@link resolveSourceMapsFromContainer}). The second way is the one to
- * build a short-lived bundled process in: a map Node finds is serialized
- * whole into every exit dump — 12 MB per invocation for a bundled CLI,
- * inside the test's own time — and parsed again by the harness; a map
- * with no comment costs nothing there. Nothing is converted in the VM.
- * A dump is a **delta** by construction: V8 resets its counters at every
- * `takeCoverage()`, so a live server's dump after a test is that test's
- * own execution, and the boot dump (everything loaded) lands in the
- * bring-up capture and nowhere else. The control plane derives lines
- * from the stored documents, off the test run. Converting to lcov in
- * the container (`c8`, SDK 0.60 to 0.79) took seconds per capture per
- * service on a real project, inside the test run; a real project turned
- * coverage off because of it, and the conversion went.
+ * {@link NODE_COVERAGE_DIR_ENV} to the coverage directory and
+ * `--require`s {@link NODE_COVERAGE_HOOK}, which collects everything in
+ * the process. Nothing for the app to write, and nothing the harness
+ * reads out of the container: at capture it asks every live process for
+ * a take over its socket and lists what appeared in the directory —
+ * dumps and script records — for the harness to ship as they are. A
+ * dump is a delta by construction (V8 resets its counters at every
+ * take), so the report after a test is that test's own execution and
+ * the boot dump lands in the bring-up capture alone. Each capture ships
+ * only its own files: what an earlier capture on this branch shipped is
+ * removed first (module memory, forks with the environment).
  */
 export declare function node(): CoverageAdapter;
 /**
@@ -169,113 +195,24 @@ export declare function node(): CoverageAdapter;
 export declare function dumpAllNodeProcesses(dir: string, signal: AbortSignal): Promise<number>;
 /** Forget the branch memory (tests). */
 export declare function resetNodeCoverageMemory(): void;
-/** Remove from `dir` the reports an earlier capture shipped. */
-export declare function removeShippedV8Reports(dir: string): Promise<void>;
-/** A script is the app's own when it is a file outside node_modules —
- *  and not our hook, which every dump would otherwise carry. */
-export declare function isAppScriptUrl(url: string): boolean;
-interface V8Range {
-    count?: unknown;
-}
-interface V8Function {
-    ranges?: V8Range[];
-}
-interface V8Script {
-    url?: unknown;
-    functions?: V8Function[];
-}
-/** True when any range of any function of the script has a count above
- *  zero: something in it ran since the previous take. A script whose
- *  every count is zero is one V8 still lists after a reset; it says
- *  nothing and is dropped. */
-export declare function scriptExecuted(script: V8Script): boolean;
-/**
- * Compact one V8 coverage document to what the derivation needs. What
- * Node writes is everything the process loaded: `node:` internals, every
- * `node_modules` file, and — under `--enable-source-maps` — a
- * `source-map-cache` with each file's full map **and its sources**,
- * repeated in every dump. Measured on a real project: a 12–20 MiB dump
- * per capture, of which the app's own coverage was under 0.5 MiB, and a
- * suite that hit the 64 MiB cap on its third test. Kept: `file://`
- * scripts outside `node_modules` in which something ran, and the map
- * entries of exactly those scripts, minus `sourcesContent` (the sources
- * are the repo). Each kept map entry carries its content hash under
- * {@link SOURCE_MAP_HASH_KEY}; when `shipped` holds the same hash for the
- * URL — the map went out with an earlier dump on this branch — a stub
- * `{ [SOURCE_MAP_REF_KEY]: hash }` stands in for it, and the reader finds
- * the map in an earlier capture of the branch. `shipped` is updated in
- * place. Still a V8 document — nothing is converted here.
- */
-export declare function compactV8Document(doc: Record<string, unknown>, shipped?: Map<string, string>): Record<string, unknown>;
-/** What {@link prepareV8Reports} did, for the capture's log line. */
-export interface PrepareV8Stats {
+/** Remove from `dir` the files an earlier capture shipped. */
+export declare function removeShippedNodeReports(dir: string): Promise<void>;
+/** What {@link collectNodeReports} found, for the capture's log line. */
+export interface NodeReportStats {
     dumps: number;
+    dumpBytes: number;
     scripts: number;
-    bytesIn: number;
-    bytesOut: number;
-    /** Source maps read out of the container this capture. */
-    mapsFromContainer: number;
+    scriptBytes: number;
 }
-/** One `source-map-cache` entry in the shape Node writes: the map (its
- *  `sourcesContent` dropped), the generated script's line lengths, and
- *  the map's own URL. */
-export interface SourceMapEntry {
-    url: string | null;
-    data: Record<string, unknown>;
-    lineLengths: number[];
-}
-/** Finds the source maps of the scripts a dump carries no map for, in
- *  one go. A script absent from the result has none. */
-export type SourceMapResolver = (scriptUrls: string[]) => Promise<Map<string, SourceMapEntry>>;
-/**
- * The probe {@link resolveSourceMapsFromContainer} runs in the container:
- * one `sh` loop over every script path, printing `<path>\t<ref>` — the
- * last `sourceMappingURL` value in the file, else `<path>.map` when that
- * file exists, else `-`; `!` for a script that is not there. One exec per
- * capture per service, whatever the number of scripts: a Next.js server
- * loads hundreds of chunk scripts with no map, and a `docker cp` per
- * script (the first cut) took a capture past its budget on a busy host.
- */
-export declare function sourceMapProbeCommand(scriptPaths: string[]): string;
-/** The length of every line of `text`, the way Node computes it for
- *  `source-map-cache`: split on `\n` (and U+2028/2029), `\r` kept, the
- *  last line included. Lengths in UTF-16 units, which is what V8's byte
- *  offsets count in. */
-export declare function lineLengthsOf(text: string): number[];
-/**
- * The source maps of `scriptUrls`, read out of the container. One probe
- * exec ({@link sourceMapProbeCommand}) finds, per script, the map a
- * `sourceMappingURL` comment names or `<script>.map` next to it; only a
- * script that has one is then read (`docker cp`, the script for its line
- * lengths and the map file, or the inline `data:` map decoded). A map's
- * `sourcesContent` is dropped. Scripts that are not `file://` URLs, have
- * no map, or whose map is not there or not JSON are absent from the
- * result. The caller remembers every outcome, so this runs once per
- * script per branch.
- *
- * With no comment the map next to the script is the shape to build a
- * short-lived bundled process in: Node caches a map it finds through a
- * comment into every dump it writes under NODE_V8_COVERAGE, flag or no
- * flag, and a bundled CLI's map is tens of MB per exit; a map it does not
- * find costs nothing there.
- */
-export declare function resolveSourceMapsFromContainer(ctx: CoverageCaptureContext, scriptUrls: string[]): Promise<Map<string, SourceMapEntry>>;
-/**
- * Give every kept script of a compacted document a `source-map-cache`
- * entry it lacks: a stub when the map shipped earlier on this branch,
- * else the map `resolve` finds (asked once for all such scripts; shipped
- * whole, with its hash, and remembered), else nothing — and that outcome
- * is remembered too, so a script with no map is looked up once per
- * branch. Returns how many maps `resolve` supplied.
- */
-export declare function attachSourceMaps(doc: Record<string, unknown>, resolve: SourceMapResolver, shipped?: Map<string, string>, missing?: Set<string>): Promise<number>;
+/** True for a dump the hook wrote (`node-*.json`). */
+export declare function isNodeDumpName(name: string): boolean;
 /**
- * Compact, in place, every `coverage-*.json` in `dir` that no earlier
- * capture shipped, attach the maps the dump lacks through `resolve`
- * ({@link attachSourceMaps}), and mark it shipped. A dump mid-write (not
- * yet valid JSON) is left for the next capture.
+ * Mark shipped every dump at the root of `dir` and every script record
+ * under `scripts/` that no earlier capture shipped, and count them.
+ * Nothing is read: the hook wrote each file whole (write + rename), and
+ * the harness ships them as they are.
  */
-export declare function prepareV8Reports(dir: string, resolve?: SourceMapResolver): Promise<PrepareV8Stats>;
+export declare function collectNodeReports(dir: string): Promise<NodeReportStats>;
 /**
  * Coverage for the frontend a service serves. The code runs in the guest
  * browser — spectest's own process — so no report can be written by the