ast-v8-to-istanbul

[![Version][version-badge]][npm-url]
[![Downloads][downloads-url]][npm-url]

> - Speed of V8 coverage 🏎
> - Accuracy of Istanbul coverage 🔍

Ignoring code | Source maps | Istanbul Compatibility | Limitations

---

AST-aware v8-to-istanbul.

Unopinionated - _bring-your-own_ AST parser and source maps.

Passes all 195 tests^* of istanbul-lib-instrument. ✅

Test cases run against:
- vite/parseAst ✅
- acorn ✅
- oxc-parser ✅
- @babel/parser ✅

See example report at https://ariperkkio.github.io/ast-v8-to-istanbul.

``ts
import { convert } from "ast-v8-to-istanbul";
import { parseAstAsync } from "vite";
import type { CoverageMapData } from "istanbul-lib-coverage";

const data: CoverageMapData = await convert({
// Bring-your-own AST parser
ast: parseAstAsync(),

// Code of the executed file (not the source file)
code: "function sum(a, b) {\n return a + b ...",

// Execution wrapper offset
wrapperLength: 0,

// Script coverage of the executed file
coverage: {
scriptId: "123",
url: "file:///absolute/path/to/dist/index.js",
functions: [
{
functionName: "sum",
ranges: [{ startOffset: 223, endOffset: 261, count: 0 }],
isBlockCoverage: false,
},
// ... etc
],
},

// Source map of the executed file
sourceMap: {
version: 3,
sources: ["../sources.ts"],
sourcesContent: ["export function sum(a: number, b: number) {\n..."],
mappings: ";AAAO,SAAS,...",
names: [],
},
});
`

Ignoring code

$3

#### Ignore hints

See live example at https://ariperkkio.github.io/ast-v8-to-istanbul/ignore-examples.html.

The typical ignore hints from nyc are supported: https://github.com/istanbuljs/nyc?tab=readme-ov-file#parsing-hints-ignoring-lines:

> / istanbul ignore if */: ignore the next if statement.
> / istanbul ignore else */: ignore the else portion of an if statement.
> / istanbul ignore next */: ignore the next _thing_ in the source-code (functions, if statements, classes, you name it).
> / istanbul ignore file */: ignore an entire source-file (this should be placed at the top of the file).

In addition to istanbul keyword, you can use v8, c8 and node:coverage:

- / istanbul ignore if /
- / v8 ignore else /
- / c8 ignore file /
- / node:coverage ignore next /

Also start and stop ignore hints from original v8-to-istanbul are supported.
These ignore hints are checked from the original sources instead of transpiled code.

> / v8 ignore start */: start ignoring lines
> / v8 ignore stop */: stop ignoring lines
> : start ignoring lines
> : stop ignoring lines
> anything / v8 ignore start */ anything: start ignoring lines
> anything / v8 ignore stop */ anything: stop ignoring lines

#### Class methods

The ignore-class-method from nyc is also supported: https://github.com/istanbuljs/nyc?tab=readme-ov-file#ignoring-methods

> You can ignore every instance of a method simply by adding its name to the ignore-class-method array in your nyc config.

`ts
import { convert } from "ast-v8-to-istanbul";

await convert({
ignoreClassMethods: ['render']
});
`

#### Ignore after remapping

You can ignore source code after coverage results have been remapped back to original sources using ignoreSourceCode.
This is a high level API that can be exposed to end-users by tooling developers.

It's mostly intended for excluding code that is incorrectly shown in coverage report when compilers add generated code in the source maps.

Note that as the exclusion happens after remapping, this option is slower than ignoreNode option.

`ts
function ignoreSourceCode(
code: string,
type: "function" | "statement" | "branch",
location: Record<"start" | "end", { line: number; column: number }>,
): boolean | void;
`

`ts
import { convert } from "ast-v8-to-istanbul";

await convert({
ignoreSourceCode: (code, type, location) => {
// Ignore all "noop()" calls
if(type === "function" && code.includes("noop(")) {
return true;
}

// In Vue "