@plugjs/cov8/dist/analysis.d.ts

V8 Coverage Plugin for the PlugJS Build System ==============================================

import type { Logger } from '@plugjs/plug/logging';
import type { AbsolutePath } from '@plugjs/plug/paths';
import type { RawSourceMap } from 'source-map';
/** Coverage range */
export interface V8CoveredRange {
    /** The offset in the script of the first character covered */
    startOffset: number;
    /** The offset (exclusive) in the script of the last character covered */
    endOffset: number;
    /** The number of times the specified offset was covered */
    count: number;
}
/** Coverage report per function as invoked by Node */
export interface V8CoveredFunction {
    /** The name of the function being covered */
    functionName: string;
    /** A flag indicating whether fine-grained (precise) coverage is available */
    isBlockCoverage: boolean;
    /**
     * The ranges covered.
     *
     * The first range indicates the whole function.
     */
    ranges: V8CoveredRange[];
}
/** Coverage result for a particlar script as seen by Node */
export interface V8CoverageResult {
    /** The script ID, uniquely identifying the script within the Node process */
    scriptId: string;
    /** The URL of the script (might not be unique, if the script is loaded multiple times) */
    url: string;
    /** Per-function report of coverage */
    functions: V8CoveredFunction[];
}
/** Cached source map for a coverage result */
export interface V8SourceMapCache {
    /** The line lengths (sans EOL) in the transpiled code */
    lineLengths: number[];
    /** The source map associated with the transpiled code */
    data: RawSourceMap | null;
    /** The url (if any) of the sourcemap, for resolving relative paths */
    url: string | null;
}
/** The RAW coverage data as emitted by Node, parsed from JSON */
export interface V8CoverageData {
    /**
     * Coverage results, per script.
     *
     * The first element in the array describes the coverage for the whole script.
     */
    'result': V8CoverageResult[];
    /** Timestamp when coverage was taken */
    'timestamp'?: number;
    /** Source maps caches keyed by `result[?].url` */
    'source-map-cache'?: Record<string, V8SourceMapCache>;
}
/**
 * The bias for source map analisys (defaults to `least_upper_bound`).
 *
 * We use `least_upper_bound` here, as it's the _opposite_ of the default
 * `greatest_lower_bound`, and we _reverse_ the lookup of the sourcemaps (from
 * source code to generated code).
 */
export type SourceMapBias = 'greatest_lower_bound' | 'least_upper_bound' | 'none' | undefined;
/** Interface providing coverage data */
export interface CoverageAnalyser {
    /** Return the number of coverage passes for the given location */
    coverage(source: string, line: number, column: number): number;
    /** Destroy this instance */
    destroy(): void;
}
/** Basic abstract class implementing the {@link CoverageAnalyser} class */
declare abstract class CoverageAnalyserImpl implements CoverageAnalyser {
    protected readonly _log: Logger;
    constructor(_log: Logger);
    abstract init(): Promise<this>;
    abstract destroy(): void;
    abstract coverage(source: string, line: number, column: number): number;
}
/** Associate one or more {@link CoverageAnalyser} with different sources */
export declare class SourcesCoverageAnalyser extends CoverageAnalyserImpl {
    private readonly _filename;
    private readonly _mappings;
    constructor(log: Logger, _filename: AbsolutePath);
    hasMappings(): boolean;
    add(source: string, analyser: CoverageAnalyserImpl): void;
    init(): Promise<this>;
    destroy(): void;
    coverage(source: string, line: number, column: number): number;
}
/** Combine multiple {@link CoverageAnalyser} instances together */
export declare class CombiningCoverageAnalyser extends CoverageAnalyserImpl {
    private readonly _analysers;
    add(analyser: CoverageAnalyserImpl): void;
    init(): Promise<this>;
    destroy(): void;
    coverage(source: string, line: number, column: number): number;
}
/**
 * Analyse coverage for the specified source files, using the data from the
 * specified coverage files and produce a {@link CoverageReport}.
 */
export declare function createAnalyser(sourceFiles: AbsolutePath[], coverageFiles: AbsolutePath[], sourceMapBias: SourceMapBias, log: Logger): Promise<CoverageAnalyser>;
export {};