@specific.dev/spectest 0.79.2 → 0.81.0

package/dist/coverage.d.ts

@@ -8,22 +8,11 @@ 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-";
-/** Where golden keeps the conversion tools (`c8` and its dependencies),
- *  seen from the VM. `SPECTEST_COVERAGE_TOOLS_DIR` overrides it (tests).
- *  The daemon bind-mounts it read-only into every covered container at
- *  {@link NODE_COVERAGE_TOOLS_CONTAINER_DIR} when it exists. */
-export declare const NODE_COVERAGE_TOOLS_DIR = "/opt/spectest/coverage-tools";
-/** Where the container sees {@link NODE_COVERAGE_TOOLS_DIR}. */
-export declare const NODE_COVERAGE_TOOLS_CONTAINER_DIR = "/spectest/coverage-tools";
-/** The `c8` entry point, relative to the tools dir. */
-export declare const NODE_COVERAGE_C8_BIN = "node_modules/c8/bin/c8.js";
-/** The hidden subdirectory of the coverage dir where `node()` parks the
- *  V8 dumps it converts at one capture. Hidden, so the harness never
- *  ships them: the lcov is the report. Emptied at every capture — the
- *  lcov is this capture's delta, see {@link convertV8ReportsToLcov}. */
-export declare const NODE_COVERAGE_DUMPS_SUBDIR = ".v8";
-/** The lcov `node()` writes: the dumps of this capture, merged. */
-export declare const NODE_COVERAGE_LCOV = "node.lcov";
+/** 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. */
@@ -64,6 +53,9 @@ 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;
 }
@@ -146,50 +138,28 @@ export declare const NODE_COVERAGE_HOOK: string;
  * capture time — the server, and any wrapper it sits behind (`pnpm exec`,
  * `tsx`). Nothing for the app to write.
  *
- * At capture the dumps are **converted to lcov inside the container**
- * with `c8` (`c8 report`), and `node.lcov` is the one report that
- * ships. It holds **what ran since the previous capture**: V8 resets its
- * counters at every `takeCoverage()`, so a live server's dump after a
- * test is that test's own execution — the boot dump (everything loaded,
- * which at file level is everything "ran") lands in the bring-up
- * capture and nowhere else. A run's total is the union over its cases
- * on the server; a test's set is the test's own. Merging every dump on
- * the branch instead was tried first and would have made a long-lived
- * server's per-test set the boot set, every time. The conversion runs
- * in the container, not in the harness, because `v8-to-istanbul` needs
- * the script text (for byte offsets → lines) and the source maps
- * (`--enable-source-maps`, or a `sourceMappingURL` next to each file),
- * and only the container has them. `c8` comes from golden
- * ({@link NODE_COVERAGE_TOOLS_DIR}); on a guest without it the raw V8
- * documents ship instead, compacted ({@link compactV8Document}), as they
- * did before SDK 0.60.
+ * 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 resolveSourceMapFromContainer}). 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.
  */
 export declare function node(): CoverageAdapter;
-/** The VM-side tools dir, after the test override. */
-export declare function nodeCoverageToolsDir(): string;
-/** True when golden (or the override) ships `c8`. The daemon mounts the
- *  directory into covered containers on the same check, so what the VM
- *  has is what the container sees. */
-export declare function nodeCoverageToolsAvailable(): Promise<boolean>;
-/** The command `convertV8ReportsToLcov` runs in the container. From `/`,
- *  so lcov paths come out relative to the root (made absolute after). */
-export declare function nodeCoverageConvertCommand(): string;
-/**
- * Convert the V8 dumps written since the previous capture to one lcov,
- * `node.lcov`. New dumps at the root of the dir are compacted to the
- * app's scripts (their maps and `sourcesContent` kept — `v8-to-istanbul`
- * reads the original sources from there when they are not on disk, the
- * usual shape of a multi-stage image) and moved into `.v8/`, which is
- * emptied first; `c8 report` merges that directory. So the lcov is this
- * capture's delta: what the live processes ran since their last take,
- * plus every process that exited since. No new dump ⇒ `TN:` alone,
- * nothing ran. The `SF:` paths come out relative to `/` and are made
- * absolute, so they read as container paths like every other tool's.
- */
-export declare function convertV8ReportsToLcov(ctx: CoverageCaptureContext): Promise<void>;
-/** `SF:` records relative to `/` (what `c8` run from `/` writes) made
- *  absolute. An lcov with nothing in it becomes the empty report. */
-export declare function absoluteLcovPaths(lcov: string): string;
 /**
  * Ask every node process that holds a hook socket in `dir` for a dump.
  * A socket nobody answers (its process died without unlinking — SIGKILL,
@@ -197,27 +167,99 @@ export declare function absoluteLcovPaths(lcov: string): string;
  * answered with an error throws.
  */
 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 the app's own scripts. What Node
- * writes is everything the process loaded: `node:` internals, every
+ * 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`, the map entries of exactly those
- * scripts, minus `sourcesContent` (the sources are the repo) unless
- * `keepSourcesContent` — the lcov conversion reads original sources from
- * there. Still a V8 document — nothing is converted here.
+ * 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 {
+    dumps: number;
+    scripts: number;
+    bytesIn: number;
+    bytesOut: number;
+    /** Source maps read out of the container this capture. */
+    mapsFromContainer: 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 map of a script the dump carries no map for.
+ *  `null` when there is none. */
+export type SourceMapResolver = (scriptUrl: string) => Promise<SourceMapEntry | null>;
+/** 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 last `sourceMappingURL` comment of a script, or `null`. */
+export declare function sourceMappingUrlOf(script: string): string | null;
+/**
+ * The source map of `scriptUrl`, read out of the container: the script
+ * itself (for its `sourceMappingURL` and its line lengths), then the map
+ * — inline as a `data:` URL, a file the comment names, or, with no
+ * comment, `<script>.map` next to it. `null` when the script is not a
+ * `file://` URL, cannot be read, or the map is not there or not JSON; a
+ * map's `sourcesContent` is dropped.
+ * One read per script per branch: the caller remembers the outcome.
+ */
+export declare function resolveSourceMapFromContainer(ctx: CoverageCaptureContext, scriptUrl: string): Promise<SourceMapEntry | null>;
+/**
+ * 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 (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>;
+/**
+ * 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.
  */
-export declare function compactV8Document(doc: Record<string, unknown>, opts?: {
-    keepSourcesContent?: boolean;
-}): Record<string, unknown>;
-/** Compact every not-yet-compacted V8 document in `dir`, in place. */
-export declare function compactV8Reports(dir: string): Promise<void>;
+export declare function prepareV8Reports(dir: string, resolve?: SourceMapResolver): Promise<PrepareV8Stats>;
 /**
  * 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