@plugjs/plug 0.0.1

package/types/index.d.ts

@@ -0,0 +1,14 @@
+/// <reference path="../extra/webassembly.d.ts" />
+export * from './assert.js';
+export * from './build.js';
+export * from './plugs.js';
+export * from './log.js';
+export * from './helpers.js';
+export type { MatchOptions, MatchResult } from './utils/match.js';
+export type { ParseOptions } from './utils/options.js';
+export type { WalkOptions } from './utils/walk.js';
+export type { AbsolutePath } from './paths.js';
+export type { Files, FilesBuilder } from './files.js';
+export type { FindOptions, Run } from './run.js';
+export type { Pipe, Plug, PlugFunction } from './pipe.js';
+export type { Task } from './task.js';

package/types/log/colors.d.ts

@@ -0,0 +1,25 @@
+import { AbsolutePath } from '../paths.js';
+/** Colorize an {@link AbsolutePath}. */
+export declare function $p(path: AbsolutePath): string;
+/** Colorize a _task name_. */
+export declare function $t(task: string): string;
+/** Colorize milliseconds. */
+export declare function $ms(millis: number): string;
+/** Colorize in gray. */
+export declare function $gry(string: any): string;
+/** Colorize in red. */
+export declare function $red(string: any): string;
+/** Colorize in green. */
+export declare function $grn(string: any): string;
+/** Colorize in yellow. */
+export declare function $ylw(string: any): string;
+/** Colorize in blue. */
+export declare function $blu(string: any): string;
+/** Colorize in magenta. */
+export declare function $mgt(string: any): string;
+/** Colorize in cyan. */
+export declare function $cyn(string: any): string;
+/** Colorize in white. */
+export declare function $wht(string: any): string;
+/** Underline. */
+export declare function $und(string: any): string;

package/types/log/emit.d.ts

@@ -0,0 +1,14 @@
+import { LogLevel } from './levels.js';
+/** Options for the {@link LogEmitter} function family */
+export interface LogEmitterOptions {
+    taskName: string;
+    level: LogLevel;
+    indent?: number;
+    prefix?: string;
+}
+/** Emit a line (or multiple lines) of text to the log */
+export declare type LogEmitter = (options: LogEmitterOptions, args: any[]) => void;
+/** Emit in full colors! */
+export declare const emitColor: LogEmitter;
+/** Emit in plain text! (no colors) */
+export declare const emitPlain: LogEmitter;

package/types/log/levels.d.ts

@@ -0,0 +1,52 @@
+/** Define a branded type for log levels */
+export declare type Level<N extends number> = N & {
+    __brand_log_level: never;
+};
+/** The `TRACE` log level */
+export declare const TRACE: Level<10>;
+/** The `DEBUG` log level */
+export declare const DEBUG: Level<20>;
+/** The `INFO` log level */
+export declare const INFO: Level<30>;
+/** The `NOTICE` log level (our default) */
+export declare const NOTICE: Level<40>;
+/** The `WARN` log level */
+export declare const WARN: Level<50>;
+/** The `ERROR` log level */
+export declare const ERROR: Level<60>;
+/** The `OFF` log level (no logs are emitted) */
+export declare const OFF: Level<9007199254740991>;
+/**  All our known log levels */
+export declare const logLevels: Readonly<{
+    TRACE: Level<10>;
+    DEBUG: Level<20>;
+    INFO: Level<30>;
+    NOTICE: Level<40>;
+    WARN: Level<50>;
+    ERROR: Level<60>;
+    OFF: Level<9007199254740991>;
+}>;
+/** The type of all our known log levels */
+export declare type LogLevels = typeof logLevels;
+/** ID of each one of our log levels (upper case) */
+export declare type LogLevelKey = keyof LogLevels;
+/** Canonical name of each one of our log levels (lower case) */
+export declare type LogLevelName = Lowercase<LogLevelKey>;
+/** A type identifying all our log level numbers */
+export declare type LogLevel = LogLevels[LogLevelKey];
+/** The type identifying a recognized log level as a `string`. */
+export declare type LogLevelString = LogLevelKey | LogLevelName;
+/**
+ * Convert a `string` (a {@link LogLevelString}) into a {@link LogLevel}.
+ *
+ * If the level specified is not a {@link LogLevelString}, the {@link NOTICE}
+ * level (our default) will be returned.
+ */
+export declare function getLevelNumber<L extends LogLevelString>(level: L): LogLevels[Uppercase<L>];
+/**
+ * Convert a `number` (a {@link LogLevel}) into a {@link LogLevelName}.
+ *
+ * If the level specified is not precisely a {@link LogLevel}, the
+ * closer {@link LogLevelName} will be returned.
+ */
+export declare function getLevelName<L extends LogLevel>(level: L): LogLevelName;

package/types/log/logger.d.ts

@@ -0,0 +1,31 @@
+import { LogLevel } from './levels.js';
+/** The basic interface giving access to log facilities. */
+export interface Log {
+    /** Log a `TRACE` message */
+    trace(...args: [any, ...any]): this;
+    /** Log a `DEBUG` message */
+    debug(...args: [any, ...any]): this;
+    /** Log an `INFO` message */
+    info(...args: [any, ...any]): this;
+    /** Log a `NOTICE` message */
+    notice(...args: [any, ...any]): this;
+    /** Log a `WARNING` message */
+    warn(...args: [any, ...any]): this;
+    /** Log an `ERROR` message */
+    error(...args: [any, ...any]): this;
+}
+/** A {@link Logger} extends the basic {@link Log} adding some state. */
+export interface Logger extends Log {
+    /** The current level for logging. */
+    level: LogLevel;
+    /** Enter a sub-level of logging, increasing indent */
+    enter(): this;
+    /** Enter a sub-level of logging, increasing indent */
+    enter(evel: LogLevel, message: string): this;
+    /** Leave a sub-level of logging, decreasing indent */
+    leave(): this;
+    /** Leave a sub-level of logging, decreasing indent */
+    leave(level: LogLevel, message: string): this;
+}
+/** Return a {@link Logger} associated with the specified task name. */
+export declare function getLogger(task?: string): Logger;

package/types/log/options.d.ts

@@ -0,0 +1,40 @@
+/// <reference types="node" resolution-mode="require"/>
+/// <reference types="node" resolution-mode="require"/>
+import { Writable } from 'node:stream';
+import { InspectOptions } from 'node:util';
+import { LogLevel } from './levels.js';
+/** Options for our {@link Logger} instances */
+export interface LogOptions {
+    /** The current output. */
+    output: Writable;
+    /** The current level for logging. */
+    level: LogLevel;
+    /** Whether to log in colors or not. */
+    colors: boolean;
+    /** Whether to enable the tasks spinner or not. */
+    spinner: boolean;
+    /** Width of the current terminal (if any) or `80`. */
+    lineLength: number;
+    /** The maximum length of a task name (for pretty alignment). */
+    taskLength: number;
+    /** The number of spaces used for indenting. */
+    indentSize: number;
+    /** Whether to show sources in reports or not. */
+    showSources: boolean;
+    /** The task name to be used by default if a task is not contextualized. */
+    defaultTaskName: string;
+    /** The options used by NodeJS for object inspection. */
+    readonly inspectOptions: InspectOptions;
+    /** Set an inspect option in {@link LogOptions.inspectOptions}). */
+    setInspectOption<K extends keyof InspectOptions>(key: K, value: InspectOptions[K]): void;
+    /** Add an event listener for the specified event. */
+    on(eventName: 'changed', listener: (logOptions: this) => void): this;
+    /** Add an event listener for the specified event triggering only once. */
+    once(eventName: 'changed', listener: (logOptions: this) => void): this;
+    /** Remove an event listener for the specified event. */
+    off(eventName: 'changed', listener: (logOptions: this) => void): this;
+    /** Convert for serialization, optionally overriding the default task name. */
+    fork(taskName?: string): Partial<LogOptions>;
+}
+/** Shared instance of our {@link LogOptions}. */
+export declare const logOptions: LogOptions;

package/types/log/report.d.ts

@@ -0,0 +1,64 @@
+import { AbsolutePath } from '../paths.js';
+import { LogLevels } from './levels.js';
+export declare type ReportLevel = LogLevels['NOTICE' | 'WARN' | 'ERROR'];
+/** A record for a {@link Report} */
+export interface ReportRecord {
+    /** The _level_ (or _severity_) of this {@link ReportRecord}. */
+    level: ReportLevel;
+    /** A detail message to associate with this {@link ReportRecord}. */
+    message: string | string[];
+    /**
+     * Tags to associate with this{@link ReportRecord}.
+     *
+     * Those are error categories, or error codes and are directly related with
+     * whatever produced the {@link Report}.
+     */
+    tags?: string[] | string | null | undefined;
+    /** Line number in the source code (starting at `1`) */
+    line?: number | null | undefined;
+    /** Column number in the source code (starting at `1`) */
+    column?: number | null | undefined;
+    /** Number of characters involved (`-1` means until the end of the line ) */
+    length?: number | null | undefined;
+    /** The {@link AbsolutePath} of the file associated with this. */
+    file?: AbsolutePath | null | undefined;
+    /** The _real source code_ associated with this (for error higlighting). */
+    source?: string | null | undefined;
+}
+/** A {@link Report} that will standardise the way we output information. */
+export interface Report {
+    /** The number of `notice` records _and_ annotations in this {@link Report}. */
+    readonly notices: number;
+    /** The number of `warning` records _and_ annotations in this {@link Report}. */
+    readonly warnings: number;
+    /** The number of `error` records _and_ annotations in this {@link Report}. */
+    readonly errors: number;
+    /** The number of `notice` records in this {@link Report}. */
+    readonly noticeRecords: number;
+    /** The number of `warning` records in this {@link Report}. */
+    readonly warningRecords: number;
+    /** The number of `error` records in this {@link Report}. */
+    readonly errorRecords: number;
+    /** The number of `notice` annotations in this {@link Report}. */
+    readonly noticeAnnotations: number;
+    /** The number of `warning` annotations in this {@link Report}. */
+    readonly warningAnnotations: number;
+    /** The number of `error` annotations in this {@link Report}. */
+    readonly errorAnnotations: number;
+    /** The number of _all_ records in this {@link Report} */
+    readonly records: number;
+    /** The number of _all_ annotations in this {@link Report} */
+    readonly annotations: number;
+    /** Checks whether this {@link Report} contains records or annotations */
+    readonly empty: boolean;
+    /** Add a new {@link ReportRecord | record} to this {@link Report}. */
+    add(...records: ReportRecord[]): this;
+    /** Add an annotation (small note) for a file in this report */
+    annotate(level: ReportLevel, file: AbsolutePath, note: string): this;
+    /** Attempt to load any source file missing from the reports */
+    loadSources(): Promise<void>;
+    /** Emit this {@link Report} and throw a build failure on error. */
+    done(showSources?: boolean | undefined): void;
+}
+/** Create a new {@link Report} with the given title */
+export declare function createReport(title: string, taskName: string): Report;

package/types/log/spinner.d.ts

@@ -0,0 +1,2 @@
+export declare const zapSpinner = "\u001B[0G\u001B[2K";
+export declare function setupSpinner(): void;

package/types/log.d.ts

@@ -0,0 +1,10 @@
+import { Log } from './log/logger.js';
+export * from './log/colors.js';
+export * from './log/levels.js';
+export * from './log/logger.js';
+export * from './log/options.js';
+export * from './log/report.js';
+/** The generic, shared `log` function type. */
+export declare type LogFunction = ((...args: [any, ...any]) => void) & Log;
+/** Our logging function (defaulting to the `NOTICE` level) */
+export declare const log: LogFunction;

package/types/paths.d.ts

@@ -0,0 +1,76 @@
+/** A _branded_ `string` representing an _absolute_ path name */
+export declare type AbsolutePath = string & {
+    __brand_absolute_path: never;
+};
+/** Resolve a path into an {@link AbsolutePath} */
+export declare function resolveAbsolutePath(directory: AbsolutePath, ...paths: string[]): AbsolutePath;
+/**
+ * Resolve a path as a relative path to the directory specified, returning the
+ * relative child path or `undefined` if the specified path was not a child.
+ *
+ * The `path` specified here _could_ also be another {@link AbsolutePath}
+ * therefore something like this will work:
+ *
+ * ```
+ * resolveRelativeChildPath('/foo', '/foo/bar')
+ * // will yield `bar`
+ * ```
+ */
+export declare function resolveRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string | undefined;
+/**
+ * Asserts that a path is a relative path to the directory specified, failing
+ * the build if it's not (see also {@link resolveRelativeChildPath}).
+ */
+export declare function assertRelativeChildPath(directory: AbsolutePath, ...paths: string[]): string;
+/** Checks that the specified path is an {@link AbsolutePath} */
+export declare function isAbsolutePath(path: string): path is AbsolutePath;
+/** Asserts that the specified path is an {@link AbsolutePath} */
+export declare function assertAbsolutePath(p: string): asserts p is AbsolutePath;
+/** Return the {@link AbsolutePath} parent of another */
+export declare function getAbsoluteParent(path: AbsolutePath): AbsolutePath;
+/**
+ * Return the {@link process.cwd() | current working directory} as an
+ * {@link AbsolutePath}.
+ */
+export declare function getCurrentWorkingDirectory(): AbsolutePath;
+/**
+ * Return the absolute path of a file relative to the given `__fileurl`, where
+ * `__fileurl` is either CommonJS's own `__filename` variable, or EcmaScript's
+ * `import.meta.url` (so either an absolute path name, or a `file:///...` url).
+ *
+ * If further `paths` are specified, those will be resolved as relative paths
+ * to the original `__fileurl` so we can easily write something like this:
+ *
+ * ```
+ * const dataFile = resolveFilename(__fileurl, 'data.json')
+ * // if we write this in "/foo/bar/baz.(ts|js|cjs|mjs)"
+ * // `dataFile` will now be "/foo/bar/data.json"
+ * ```
+ */
+export declare function requireFilename(__fileurl: string, ...paths: string[]): AbsolutePath;
+/**
+ * Return the absolute path of a file which can be _required_ or _imported_
+ * by Node (or forked to via `child_process.fork`).
+ *
+ * This leverages {@link requireFilename} to figure out the starting point where
+ * to look for files, and will _try_ to match the same extension of `__fileurl`
+ * (so, `.ts` for `ts-node`, `.mjs` for ESM modules, ...).
+ */
+export declare function requireResolve(__fileurl: string, module: string): AbsolutePath;
+/**
+ * Return the _common_ path amongst all specified paths.
+ *
+ * While the first `path` _must_ be an {@link AbsolutePath}, all other `paths`
+ * can be _relative_ and will be resolved against the first `path`.
+ */
+export declare function commonPath(path: AbsolutePath, ...paths: string[]): AbsolutePath;
+/**
+ * Resolves the specified path as an {@link AbsolutePath} and checks it is a
+ * _file_, returning `undefined` if it is not.
+ */
+export declare function isFile(path: AbsolutePath, ...paths: string[]): AbsolutePath | undefined;
+/**
+ * Resolves the specified path as an {@link AbsolutePath} and checks it is a
+ * _directory_, returning `undefined` if it is not.
+ */
+export declare function isDirectory(path: AbsolutePath, ...paths: string[]): AbsolutePath | undefined;

package/types/pipe.d.ts

@@ -0,0 +1,152 @@
+import { Files } from './files.js';
+import { Run } from './run.js';
+/**
+ * The {@link Plug} interface describes an extension mechanism for our build.
+ */
+export interface Plug<T extends Files | undefined> {
+    pipe(files: Files, run: Run): T | Promise<T>;
+}
+/**
+ * A type identifying a {@link Plug} as a `function`
+ */
+export declare type PlugFunction<T extends Files | undefined> = Plug<T>['pipe'];
+/**
+ * A {@link Pipe} represents a sequence of operations performed by
+ * a series of {@link Plug | Plugs}.
+ */
+export interface Pipe {
+}
+/**
+ * The {@link Pipe} abstract class exposes the prototype upon which all
+ * extension plugs will be installed on.
+ */
+export declare abstract class Pipe implements Pipe {
+    abstract plug(plug: Plug<Files> | PlugFunction<Files>): Pipe & Promise<Files>;
+    abstract plug(plug: Plug<undefined> | PlugFunction<undefined>): Promise<undefined>;
+}
+/** Implementation of our {@link Pipe}. */
+export declare class PipeImpl<T extends Files | undefined> extends Pipe implements Promise<T> {
+    #private;
+    constructor(start: T | Promise<T>, run: Run);
+    plug<T extends Files | undefined>(arg: Plug<T> | PlugFunction<T>): Pipe & Promise<T>;
+    then<T1 = T, T2 = never>(onfulfilled?: ((value: T) => T1 | PromiseLike<T1>) | null | undefined, onrejected?: ((reason: any) => T2 | PromiseLike<T2>) | null | undefined): Promise<T1 | T2>;
+    catch<T0 = never>(onrejected?: ((reason: any) => T0 | PromiseLike<T0>) | null | undefined): Promise<T0 | T>;
+    finally(onfinally?: (() => void) | null | undefined): Promise<T>;
+    [Symbol.toStringTag]: string;
+}
+/** The names which can be installed as direct plugs. */
+export declare type PlugName = string & Exclude<keyof Pipe, 'plug' | keyof Promise<Files>>;
+/** A convenience type identifying a {@link Plug} constructor. */
+export declare type PlugConstructor = new (...args: any) => Plug<Files | undefined>;
+/** Convert the resulting type of a {@link Plug} for use in a {@link Pipe} */
+declare type PlugReturnForPipe<T> = T extends Plug<infer R> ? R extends Files ? Promise<Files> & Pipe : R extends undefined ? Promise<undefined> : never : never;
+/**
+ * Map constructors into an array of all known overloads.
+ *
+ * This is a _royal_ pain in the ass, as we need to distinguish between
+ * all possible number of overloads of a constructor... Limit to 5 of them!
+ *
+ * Also, the empty constructor (when specified in the overloads) will simply
+ * match the first case (most overloads) and generate functions somewhat like
+ *
+ * (...args: unknown[]) => never
+ * (...args: unknown[]) => never
+ * (...args: unknown[]) => never
+ * () => PlugReturnForPipe<R3>
+ * (arg: Options) => PlugReturnForPipe<R4>
+ *
+ * Somehow inferring the result to `Function` or the right type and ANDing all
+ * those together here doesn't work, so we create this array and we'll AND
+ * all its members in the PipeExtension<...> type.
+ */
+declare type PlugConstructorOverloads<T extends PlugConstructor> = T extends {
+    new (...args: infer A0): infer R0;
+    new (...args: infer A1): infer R1;
+    new (...args: infer A2): infer R2;
+    new (...args: infer A3): infer R3;
+    new (...args: infer A4): infer R4;
+} ? [
+    R0 extends Plug<Files | undefined> ? ((...args: A0) => PlugReturnForPipe<R0>) : Function,
+    R1 extends Plug<Files | undefined> ? ((...args: A1) => PlugReturnForPipe<R1>) : Function,
+    R2 extends Plug<Files | undefined> ? ((...args: A2) => PlugReturnForPipe<R2>) : Function,
+    R3 extends Plug<Files | undefined> ? ((...args: A3) => PlugReturnForPipe<R3>) : Function,
+    R4 extends Plug<Files | undefined> ? ((...args: A4) => PlugReturnForPipe<R4>) : Function
+] : T extends {
+    new (...args: infer A0): infer R0;
+    new (...args: infer A1): infer R1;
+    new (...args: infer A2): infer R2;
+    new (...args: infer A3): infer R3;
+} ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
+    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function,
+    R2 extends Plug<Files | undefined> ? (...args: A2) => PlugReturnForPipe<R2> : Function,
+    R3 extends Plug<Files | undefined> ? (...args: A3) => PlugReturnForPipe<R3> : Function
+] : T extends {
+    new (...args: infer A0): infer R0;
+    new (...args: infer A1): infer R1;
+    new (...args: infer A2): infer R2;
+} ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
+    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function,
+    R2 extends Plug<Files | undefined> ? (...args: A2) => PlugReturnForPipe<R2> : Function
+] : T extends {
+    new (...args: infer A0): infer R0;
+    new (...args: infer A1): infer R1;
+} ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function,
+    R1 extends Plug<Files | undefined> ? (...args: A1) => PlugReturnForPipe<R1> : Function
+] : T extends {
+    new (...args: infer A0): infer R0;
+} ? [
+    R0 extends Plug<Files | undefined> ? (...args: A0) => PlugReturnForPipe<R0> : Function
+] : never;
+/**
+ * A convenience type to easily annotate installed {@link Plug Plugs}.
+ *
+ * See also {@link install}.
+ *
+ * ```
+ * export class Write implements Plug {
+ *   // ... the plug implementation lives here
+ * }
+ *
+ * install('write', Write)
+ *
+ * declare module '../pipe' {
+ *   export interface Pipe {
+ *     write: PipeExtension<typeof Write>
+ *   }
+ * }
+ * ```
+ */
+export declare type PipeExtension<T extends PlugConstructor, A = PlugConstructorOverloads<T>> = A extends readonly [infer First, ...infer Rest] ? First & PipeExtension<T, Rest> : A extends readonly [infer Only] ? Only : Function;
+/**
+ * Install a {@link Plug} into our {@link Pipe} prototype, and return a static
+ * creator function for the {@link Plug} itself.
+ *
+ * This allows our shorthand syntax for well-defined plugs such as:
+ *
+ * ```
+ * find('./src', '*.ts').write('./target')
+ * // Nicer and easier than...
+ * find('./src', '*.ts').plug(new Write('./target'))
+ * ```
+ *
+ * Use this alongside interface merging like:
+ *
+ * ```
+ * export class Write implements Plug {
+ *   // ... the plug implementation lives here
+ * }
+ *
+ * install('write', Write)
+ *
+ * declare module '../pipe' {
+ *   export interface Pipe {
+ *     write: PipeExtension<typeof Write>
+ *   }
+ * }
+ * ```
+ */
+export declare function install<C extends PlugConstructor>(name: PlugName, ctor: C): void;
+export {};

package/types/plugs/copy.d.ts

@@ -0,0 +1,27 @@
+import { Files } from '../files.js';
+import { Plug } from '../pipe.js';
+import { Run } from '../run.js';
+/** Options for copying files */
+export interface CopyOptions {
+    /** Whether to allow overwriting or not (default `false`). */
+    overwrite?: boolean;
+    /** If specified, use this `mode` (octal string) when creating files. */
+    mode?: string | number;
+    /** If specified, use this `mode` (octal string) when creating directories. */
+    dirMode?: string | number;
+    /** If specified, this function will be invoked to rename files. */
+    rename?: (relative: string) => string;
+}
+/** Copy the curent {@link Files} to a different directory */
+export declare class Copy implements Plug<Files> {
+    private readonly _directory;
+    private readonly _options;
+    constructor(directory: string, options?: CopyOptions);
+    pipe(files: Files, run: Run): Promise<Files>;
+}
+declare module '../pipe.js' {
+    interface Pipe {
+        /** Copy the curent {@link Files} to a different directory */
+        copy: PipeExtension<typeof Copy>;
+    }
+}

package/types/plugs/coverage/analysis.d.ts

@@ -0,0 +1,104 @@
+import { RawSourceMap } from 'source-map';
+import { Logger } from '../../log.js';
+import { AbsolutePath } from '../../paths.js';
+/** 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 declare 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 {};