@circleci/v8-coverage-collector 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Circle Internet Services, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# v8-coverage-collector
+
+Wrapper around v8's Profiler APIs used to gather coverage data for CircleCI's Smarter Testing Javascript plugins.
+
+The coverage collector can be used to collect precise coverage during the test run lifecycles.
+
+## Usage
+
+Add the package as a dependency
+
+```shell
+pnpm i @circleci/v8-coverage-collector
+```
+
+Use the provided APIs to collect and reset coverage during the test lifecycle events.
+
+```ts
+import {V8CoverageCollector} from '@circleci/v8-coverage-collector';
+
+export default class TestHookExample {
+  private inspector: V8CoverageCollector;
+
+  constructor() {
+    this.inspector = new V8CoverageCollector();
+  }
+
+  async onBeforeAll(): Promise<void> {
+    await this.inspector.connect()
+  }
+
+  async onBeforeTest(): Promise<void> {
+    await this.inspector.resetCoverage();
+  }
+
+  async onAfterTest(test: ExampleTest): Promise<void> {
+    await this.inspector
+      .collectCoverage(process.cwd(), test.file, test.name)
+      .then((result) => {
+        test.meta.testKey = result.testKey;
+        test.meta.coveredFiles = result.coveredFiles;
+      });
+  }
+
+  async onAfterAll(): Promise<void> {
+    await this.inspector.disconnect()
+  }
+}
+```
+
+## Development
+
+Install and use current node version.
+
+```shell
+NODE_VER=$(cat ./.nvmrc)
+nvm install $NODE_VER
+nvm use $NODE_VER
+```
+
+Install dependencies with pnpm.
+
+```shell
+pnpm install
+```
+
+Build the plugin.
+
+```shell
+pnpm build
+```
+
+Run tests.
+
+```shell
+pnpm test
+```

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * This module contains the CircleCI v8 coverage collector, used to gather
+ * coverage data for CircleCI's Smarter Testing JavaScript plugins.
+ *
+ * The coverage collector can be used to collect precise coverage during the
+ * test run lifecycles.
+ *
+ * @example
+ * ```ts
+ * import { V8CoverageCollector } from '@circleci/v8-coverage-collector';
+ *
+ * export default class TestHookExample {
+ *   private inspector: V8CoverageCollector;
+ *
+ *   constructor() {
+ *     this.inspector = new V8CoverageCollector();
+ *   }
+ *
+ *   async onBeforeAll(): Promise<void> {
+ *     await this.inspector.connect()
+ *   }
+ *
+ *   async onBeforeTest(): Promise<void> {
+ *     await this.inspector.resetCoverage();
+ *   }
+ *
+ *   async onAfterTest(test: ExampleTest): Promise<void> {
+ *     await this.inspector
+ *       .collectCoverage(process.cwd(), test.file, test.class, test.name)
+ *       .then((result) => {
+ *         test.meta.testKey = result.testKey;
+ *         test.meta.coveredFiles = result.coveredFiles;
+ *       });
+ *   }
+ *
+ *   async onAfterAll(): Promise<void> {
+ *     await this.inspector.disconnect()
+ *   }
+ * }
+ * ```
+ *
+ * @module
+ */
+/**
+ * TestCoverage is the response from {@link collectCoverage}
+ * for a given test file and name.
+ */
+export interface TestCoverage {
+    /**
+     * testKey is unique identifier for a given test.
+     *
+     * @example `{test file}::{test name}|{phase}`
+     *
+     * */
+    testKey: string;
+    /**
+     * coveredFiles is a list of found covered files, relative
+     * to the given working directory.
+     */
+    coveredFiles: string[];
+}
+/**
+ * V8CoverageCollector provides APIs for collecting coverage using the
+ * v8 Profile APIs.
+ */
+export declare class V8CoverageCollector {
+    private readonly session;
+    private readonly post;
+    constructor();
+    /**
+     * connect connects and enables the v8 Profiler APIs.
+     *
+     * @returns {Promise<void>}
+     */
+    connect(): Promise<void>;
+    /**
+     * disconnect disconnects and disables the v8 Profiler APIs.
+     *
+     * @returns {Promise<void>}
+     */
+    disconnect(): Promise<void>;
+    /**
+     * resetCoverage resets the execution counts of the coverage.
+     *
+     * @returns {Promise<void>}
+     */
+    resetCoverage(): Promise<void>;
+    /**
+     * collectCoverage collects coverage data since the last time
+     * {@link resetCoverage} was called.
+     *
+     * @param {string} wd
+     * @param {string} testFile
+     * @param {...string} scopes - one or more additional scope segments e.g. testClass, testName
+     * @returns {Promise<TestCoverage>}
+     */
+    collectCoverage(wd: string, testFile: string, ...scopes: string[]): Promise<TestCoverage>;
+    private testKey;
+    private coveredFiles;
+    private enable;
+    private disable;
+    private startPreciseCoverage;
+    private stopPreciseCoverage;
+    private takePreciseCoverage;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAaH;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;SAKK;IACL,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwD;;IAU7E;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;;;;;;;OAQG;IACG,eAAe,CACnB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,GAAG,MAAM,EAAE,MAAM,EAAE,GAClB,OAAO,CAAC,YAAY,CAAC;IAUxB,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,YAAY;YAcN,MAAM;YAIN,OAAO;YAIP,oBAAoB;YAOpB,mBAAmB;YAInB,mBAAmB;CAMlC"}

package/dist/index.js

@@ -0,0 +1,138 @@
+/**
+ * This module contains the CircleCI v8 coverage collector, used to gather
+ * coverage data for CircleCI's Smarter Testing JavaScript plugins.
+ *
+ * The coverage collector can be used to collect precise coverage during the
+ * test run lifecycles.
+ *
+ * @example
+ * ```ts
+ * import { V8CoverageCollector } from '@circleci/v8-coverage-collector';
+ *
+ * export default class TestHookExample {
+ *   private inspector: V8CoverageCollector;
+ *
+ *   constructor() {
+ *     this.inspector = new V8CoverageCollector();
+ *   }
+ *
+ *   async onBeforeAll(): Promise<void> {
+ *     await this.inspector.connect()
+ *   }
+ *
+ *   async onBeforeTest(): Promise<void> {
+ *     await this.inspector.resetCoverage();
+ *   }
+ *
+ *   async onAfterTest(test: ExampleTest): Promise<void> {
+ *     await this.inspector
+ *       .collectCoverage(process.cwd(), test.file, test.class, test.name)
+ *       .then((result) => {
+ *         test.meta.testKey = result.testKey;
+ *         test.meta.coveredFiles = result.coveredFiles;
+ *       });
+ *   }
+ *
+ *   async onAfterAll(): Promise<void> {
+ *     await this.inspector.disconnect()
+ *   }
+ * }
+ * ```
+ *
+ * @module
+ */
+import inspector from 'node:inspector';
+import { promisify } from 'node:util';
+import { relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * V8CoverageCollector provides APIs for collecting coverage using the
+ * v8 Profile APIs.
+ */
+export class V8CoverageCollector {
+    constructor() {
+        this.session = new inspector.Session();
+        this.post = promisify(this.session.post.bind(this.session));
+    }
+    /**
+     * connect connects and enables the v8 Profiler APIs.
+     *
+     * @returns {Promise<void>}
+     */
+    async connect() {
+        this.session.connect();
+        await this.enable();
+        await this.startPreciseCoverage();
+    }
+    /**
+     * disconnect disconnects and disables the v8 Profiler APIs.
+     *
+     * @returns {Promise<void>}
+     */
+    async disconnect() {
+        await this.stopPreciseCoverage();
+        await this.disable();
+        this.session.disconnect();
+    }
+    /**
+     * resetCoverage resets the execution counts of the coverage.
+     *
+     * @returns {Promise<void>}
+     */
+    async resetCoverage() {
+        await this.takePreciseCoverage();
+    }
+    /**
+     * collectCoverage collects coverage data since the last time
+     * {@link resetCoverage} was called.
+     *
+     * @param {string} wd
+     * @param {string} testFile
+     * @param {...string} scopes - one or more additional scope segments e.g. testClass, testName
+     * @returns {Promise<TestCoverage>}
+     */
+    async collectCoverage(wd, testFile, ...scopes) {
+        return this.takePreciseCoverage().then((result) => {
+            const testKey = this.testKey(wd, testFile, ...scopes);
+            return {
+                testKey: testKey,
+                coveredFiles: this.coveredFiles(wd, result),
+            };
+        });
+    }
+    testKey(wd, testFile, ...scopes) {
+        const s = [relative(wd, testFile), ...scopes];
+        return `${s.join('!!')}|run`;
+    }
+    coveredFiles(wd, result) {
+        return result
+            .map((s) => s.url)
+            .filter((s) => {
+            const url = URL.canParse(s) && new URL(s);
+            return (url &&
+                url.protocol === 'file:' &&
+                !url.pathname.includes('node_modules'));
+        })
+            .map((url) => relative(wd, fileURLToPath(url)));
+    }
+    async enable() {
+        await this.post('Profiler.enable');
+    }
+    async disable() {
+        await this.post('Profiler.disable');
+    }
+    async startPreciseCoverage() {
+        await this.post('Profiler.startPreciseCoverage', {
+            callCount: true,
+            detailed: false,
+        });
+    }
+    async stopPreciseCoverage() {
+        await this.post('Profiler.stopPreciseCoverage');
+    }
+    async takePreciseCoverage() {
+        const result = (await this.post('Profiler.takePreciseCoverage'));
+        return result.result;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@circleci/v8-coverage-collector",
+  "version": "0.2.0",
+  "description": "",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "oxlint --quiet",
+    "format": "prettier . --check"
+  },
+  "devDependencies": {
+    "@prettier/plugin-oxc": "^0.2.0",
+    "@types/node": "^24.0.0",
+    "oxlint": "^1.43.0",
+    "prettier": "^3.8.1",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "npm": "~11.15.0"
+  }
+}