Crate oxc_coverage_instrument

Expand description

Istanbul-compatible JavaScript/TypeScript coverage instrumentation using the Oxc AST.

This crate parses JS/TS source with oxc_parser, identifies statements, functions, and branches, injects coverage counter expressions, and emits instrumented code. The coverage map output is compatible with Istanbul’s coverage-final.json format (consumed by Jest, Vitest, c8, nyc, Codecov).

§Example

use oxc_coverage_instrument::{instrument, InstrumentOptions};

let source = "function add(a, b) { return a + b; }";
let result = instrument(source, "add.js", &InstrumentOptions::default()).unwrap();

println!("Instrumented code:\n{}", result.code);
println!("Functions found: {}", result.coverage_map.fn_map.len());

§Coverage model

The coverage map tracks three dimensions:

Statements: every executable statement gets a counter
Functions: every function declaration, expression, arrow, and method
Branches: if/else, ternary, switch cases, logical &&/||

Function names are derived from the same Oxc parser used by other Oxc-based tools, so they match consistently across the ecosystem.

Structs§

BranchEntry: Branch entry in the coverage map.
FileCoverage: Coverage data for a single file. Serializes to Istanbul’s coverage-final.json format.
FnEntry: Function entry in the coverage map.
InstrumentOptions: Options for the instrument function.
InstrumentResult: Result of instrumenting a source file.
Location: A source location span with start and end positions.
Position: A 1-based line, 0-based column position.
PositionRemapper: A position-remap predicate over a parsed inputSourceMap.
RemapOptions: Options for the remap helpers. The default value preserves the legacy keep-generated-position behaviour for positions whose source-map lookup returns None, so existing callers that pass RemapOptions::default (or rely on the parameterless remap_coverage / remap_coverage_map helpers) see no change.
SourceMapStore: Stateful map store for the Mode B “continuous remap during collection” flow. Some runners (Jest with transform) instrument files incrementally and want to record each file’s source map as it is produced, then rewrite FileCoverage objects on the fly rather than once at report time.
UnhandledPragma: A coverage pragma comment that was found but not handled.
V8CoverageRange: A single V8 coverage range.
V8FunctionCoverage: A function’s coverage data as reported by the V8 inspector.

Enums§

DecoratorMode: How strip_typescript handles decorator syntax.
InstrumentError: Error type for instrumentation failures.
V8ToIstanbulError: Errors produced by the V8-to-Istanbul conversion.

Functions§

instrument: Instrument a JavaScript/TypeScript source file for coverage collection.
parse_coverage_map: Parse a coverage-final.json string into a map of file paths to coverage data.
remap_coverage: Remap a single FileCoverage through its embedded inputSourceMap.
remap_coverage_map: Remap every FileCoverage in a coverage map. Entries without an inputSourceMap pass through unchanged under their original key. Entries with an inputSourceMap are rewritten and re-keyed by their resolved original source path.
remap_coverage_map_with_loader: Like remap_coverage_map, but with a disk-read fallback for entries that lack an embedded inputSourceMap. The loader is called with the FileCoverage.path of each entry that needs an external map.
remap_coverage_map_with_loader_and_options: Like remap_coverage_map_with_loader, with a RemapOptions argument. See RemapOptions::drop_unmapped for the pruning semantics.
remap_coverage_map_with_options: Like remap_coverage_map, with a RemapOptions argument. See RemapOptions::drop_unmapped for the pruning semantics.
remap_coverage_with_loader: Like remap_coverage, but when the entry has no embedded inputSourceMap the supplied loader is consulted with the FileCoverage.path to fetch the source map JSON from disk or another source. Matches istanbul-lib-source-maps’s sourceStore callback used by nyc when the map sits next to the instrumented file rather than embedded inside the coverage object.
remap_coverage_with_loader_and_options: Like remap_coverage_with_loader, with a RemapOptions argument. See RemapOptions::drop_unmapped for the pruning semantics.
remap_coverage_with_options: Like remap_coverage, but with a RemapOptions argument. See RemapOptions::drop_unmapped for the pruning semantics.
v8_to_istanbul: Convert V8 function coverage into Istanbul FileCoverage.
v8_to_istanbul_with_loader: Like v8_to_istanbul, but with a loader for external sourceMappingURL references.