@specific.dev/spectest 0.82.0 → 0.83.0

package/dist/coverage.d.ts

@@ -144,9 +144,12 @@ export declare const NODE_COVERAGE_DUMP_PREFIX = "node-";
  * - 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, ranges and counts as V8 reported them. Nothing
- *   when nothing ran. Still a V8 coverage document (`result`), plus
- *   `spectestScript` on each script naming its record.
+ *   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

package/dist/coverage.js

@@ -156,9 +156,12 @@ export const NODE_COVERAGE_DUMP_PREFIX = "node-";
  * - 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, ranges and counts as V8 reported them. Nothing
- *   when nothing ran. Still a V8 coverage document (`result`), plus
- *   `spectestScript` on each script naming its record.
+ *   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
@@ -331,10 +334,27 @@ export const NODE_COVERAGE_HOOK = `"use strict";
       }
       post("Debugger.disable");
     }
+    // A ran function is 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. Small numbers, so the dump gzips to
+    // less than half of V8's own JSON; name and block flag live in the
+    // script record, joined on the extent.
     const doc = {
-      spectestVersion: 1,
+      spectestVersion: 2,
       result: kept.map(function (s) {
-        return { url: s.url, scriptId: s.scriptId, spectestScript: idOf(s.url), functions: s.functions.filter(ran) };
+        return {
+          url: s.url,
+          spectestScript: idOf(s.url),
+          functions: s.functions.filter(ran).map(function (f) {
+            const first = f.ranges[0];
+            const out = [first.startOffset, first.endOffset - first.startOffset, first.count];
+            for (let i = 1; i < f.ranges.length; i++) {
+              const r = f.ranges[i];
+              out.push(r.startOffset - first.startOffset, r.endOffset - r.startOffset, r.count);
+            }
+            return out;
+          }),
+        };
       }),
     };
     const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + process.pid + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";

package/dist/harness/coverage.d.ts

@@ -57,9 +57,10 @@ export declare function hasLcovSourceFile(text: string): boolean;
 export declare function isLcovShaped(text: string): boolean;
 /**
  * True when `text` looks like a V8 coverage JSON document — what
- * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
- * `result` array of scripts. A cheap shape check, not a parse (a report
- * can be megabytes); the control plane parses for real.
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write, and the shape the
+ * `node()` hook's dumps keep: an object with a `result` array of
+ * scripts. A cheap shape check, not a parse (a report can be
+ * megabytes); the control plane parses for real.
  */
 export declare function isV8CoverageJson(text: string): boolean;
 /** True when `text` is a script record the `node()` hook writes

package/dist/harness/coverage.js

@@ -56,9 +56,10 @@ export function isLcovShaped(text) {
 }
 /**
  * True when `text` looks like a V8 coverage JSON document — what
- * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
- * `result` array of scripts. A cheap shape check, not a parse (a report
- * can be megabytes); the control plane parses for real.
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write, and the shape the
+ * `node()` hook's dumps keep: an object with a `result` array of
+ * scripts. A cheap shape check, not a parse (a report can be
+ * megabytes); the control plane parses for real.
  */
 export function isV8CoverageJson(text) {
     return /^\s*\{/.test(text) && /"result"\s*:\s*\[/.test(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.82.0",
+  "version": "0.83.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/coverage.test.ts

@@ -159,7 +159,7 @@ const WRAPPER_JS =
 
 interface Dump {
   spectestVersion: number;
-  result: { url: string; spectestScript: string; functions: { functionName: string; ranges: { count: number }[] }[] }[];
+  result: { url: string; spectestScript: string; functions: number[][] }[];
 }
 interface ScriptRecord {
   spectestScript: {
@@ -190,6 +190,11 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     }
     return out;
   }
+  /** The names of a dump's ran functions, joined to the record on the extent. */
+  function ranNames(dump: Dump, rec: ScriptRecord["spectestScript"]): string[] {
+    const byExtent = new Map(rec.functions.map(([name, start, end]) => [`${start}-${end}`, name]));
+    return dump.result[0]!.functions.map((f) => byExtent.get(`${f[0]}-${f[0]! + f[1]!}`) ?? "?");
+  }
   async function scratch(): Promise<string> {
     resetNodeCoverageMemory();
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), "spectest-covhook-"));
@@ -221,11 +226,14 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
       await node().capture!(fakeCtx(dir));
       const [name] = await dumpsIn(dir);
       const dump = await readDump(dir, name!);
-      expect(dump.spectestVersion).toBe(1);
+      expect(dump.spectestVersion).toBe(2);
       expect(dump.result.map((s) => s.url)).toEqual([`file://${path.join(dir, "server.js")}`]);
       const fns = dump.result[0]!.functions;
-      expect(fns.every((f) => f.ranges.some((r) => r.count > 0))).toBe(true);
+      // Triples: the extent, then blocks relative to it; some count > 0.
+      expect(fns.every((f) => f.length >= 3 && f.length % 3 === 0)).toBe(true);
+      expect(fns.every((f) => f.some((_, i) => i % 3 === 2 && f[i]! > 0))).toBe(true);
       const rec = (await records(dir)).get(`file://${path.join(dir, "server.js")}`)!;
+      expect(ranNames(dump, rec).sort()).toEqual(["", "tick"]);
       expect(rec.lineLengths).toEqual([28, 51, 0]);
       expect(rec.functions.map((f) => f[0])).toEqual(["", "tick"]);
       expect(rec.sourceMap).toBeNull();
@@ -241,7 +249,7 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
       expect(names.length).toBe(1);
       expect(names[0]).not.toBe(name);
       const second = await readDump(dir, names[0]!);
-      expect(second.result[0]!.functions.map((f) => f.functionName)).toEqual(["tick"]);
+      expect(ranNames(second, rec)).toEqual(["tick"]);
       expect((await fs.readdir(path.join(dir, NODE_COVERAGE_SCRIPTS_SUBDIR))).length).toBe(0);
     } finally {
       server.kill("SIGKILL");
@@ -277,14 +285,14 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     await node().capture!(fakeCtx(dir));
     const names = await dumpsIn(dir);
     expect(names.length).toBe(2);
+    const recs = await records(dir);
+    expect(recs.size).toBe(1);
+    const rec = recs.get(`file://${path.join(dir, "cli.js")}`)!;
     for (const n of names) {
       const d = await readDump(dir, n);
       expect(d.result.map((s) => s.url)).toEqual([`file://${path.join(dir, "cli.js")}`]);
-      expect(d.result[0]!.functions.map((f) => f.functionName).sort()).toEqual(["", "used"]);
+      expect(ranNames(d, rec).sort()).toEqual(["", "used"]);
     }
-    const recs = await records(dir);
-    expect(recs.size).toBe(1);
-    const rec = recs.get(`file://${path.join(dir, "cli.js")}`)!;
     expect(rec.functions.map((f) => f[0])).toEqual(["", "used", "unused"]);
     expect(rec.lineLengths).toEqual([28, 30, 7, 0]);
     expect(rec.sourceMap!.url).toBe(`file://${path.join(dir, "cli.js.map")}`);
@@ -333,11 +341,13 @@ describe.if(hasNode)("nodeCoverage hook (real node)", () => {
     expect(names.length).toBe(2);
     const byThread = new Map<string, Dump>();
     for (const n of names) byThread.set(n.split("-")[2]!, await readDump(dir, n));
+    const recs = await records(dir);
+    expect(recs.size).toBe(1); // one script, one record, whichever thread came first
+    const rec = recs.get(`file://${path.join(dir, "threads.js")}`)!;
     const worker = [...byThread.entries()].find(([t]) => t !== "0")![1];
-    expect(worker.result[0]!.functions.some((f) => f.functionName === "inWorker")).toBe(true);
+    expect(ranNames(worker, rec)).toContain("inWorker");
     const main = byThread.get("0")!;
-    expect(main.result[0]!.functions.some((f) => f.functionName === "inWorker")).toBe(false);
-    expect((await records(dir)).size).toBe(1); // one script, one record, whichever thread came first
+    expect(ranNames(main, rec)).not.toContain("inWorker");
   });
 
   test("a stale socket left by a killed process is removed at capture", async () => {

package/src/coverage.ts

@@ -258,9 +258,12 @@ export const NODE_COVERAGE_DUMP_PREFIX = "node-";
  * - 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, ranges and counts as V8 reported them. Nothing
- *   when nothing ran. Still a V8 coverage document (`result`), plus
- *   `spectestScript` on each script naming its record.
+ *   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
@@ -433,10 +436,27 @@ export const NODE_COVERAGE_HOOK = `"use strict";
       }
       post("Debugger.disable");
     }
+    // A ran function is 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. Small numbers, so the dump gzips to
+    // less than half of V8's own JSON; name and block flag live in the
+    // script record, joined on the extent.
     const doc = {
-      spectestVersion: 1,
+      spectestVersion: 2,
       result: kept.map(function (s) {
-        return { url: s.url, scriptId: s.scriptId, spectestScript: idOf(s.url), functions: s.functions.filter(ran) };
+        return {
+          url: s.url,
+          spectestScript: idOf(s.url),
+          functions: s.functions.filter(ran).map(function (f) {
+            const first = f.ranges[0];
+            const out = [first.startOffset, first.endOffset - first.startOffset, first.count];
+            for (let i = 1; i < f.ranges.length; i++) {
+              const r = f.ranges[i];
+              out.push(r.startOffset - first.startOffset, r.endOffset - r.startOffset, r.count);
+            }
+            return out;
+          }),
+        };
       }),
     };
     const name = ${JSON.stringify(NODE_COVERAGE_DUMP_PREFIX)} + process.pid + "-" + wt.threadId + "-" + Date.now() + "-" + seq++ + ".json";

package/src/harness/coverage.ts

@@ -108,9 +108,10 @@ export function isLcovShaped(text: string): boolean {
 
 /**
  * True when `text` looks like a V8 coverage JSON document — what
- * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write: an object with a
- * `result` array of scripts. A cheap shape check, not a parse (a report
- * can be megabytes); the control plane parses for real.
+ * `NODE_V8_COVERAGE` / `v8.takeCoverage()` write, and the shape the
+ * `node()` hook's dumps keep: an object with a `result` array of
+ * scripts. A cheap shape check, not a parse (a report can be
+ * megabytes); the control plane parses for real.
  */
 export function isV8CoverageJson(text: string): boolean {
   return /^\s*\{/.test(text) && /"result"\s*:\s*\[/.test(text);