@rushstack/heft/dist/heft.d.ts

Build all your JavaScript projects the same way: A way that works.

/**
 * Heft is a config-driven toolchain that invokes other popular tools such
 * as TypeScript, ESLint, Jest, Webpack, and API Extractor. You can use it to build
 * web applications, Node.js services, command-line tools, libraries, and more.
 *
 * @packageDocumentation
 */

/// <reference types="node" />

import { AsyncParallelHook } from 'tapable';
import { AsyncSeriesWaterfallHook } from 'tapable';
import { CommandLineChoiceListParameter } from '@rushstack/ts-command-line';
import { CommandLineChoiceParameter } from '@rushstack/ts-command-line';
import { CommandLineFlagParameter } from '@rushstack/ts-command-line';
import { CommandLineIntegerListParameter } from '@rushstack/ts-command-line';
import { CommandLineIntegerParameter } from '@rushstack/ts-command-line';
import { CommandLineParameter } from '@rushstack/ts-command-line';
import { CommandLineStringListParameter } from '@rushstack/ts-command-line';
import { CommandLineStringParameter } from '@rushstack/ts-command-line';
import { CustomValidationFunction } from '@rushstack/heft-config-file';
import * as fs from 'fs';
import { ICustomJsonPathMetadata } from '@rushstack/heft-config-file';
import { ICustomPropertyInheritance } from '@rushstack/heft-config-file';
import { IJsonPathMetadata } from '@rushstack/heft-config-file';
import { IJsonPathMetadataResolverOptions } from '@rushstack/heft-config-file';
import { IJsonPathsMetadata } from '@rushstack/heft-config-file';
import { InheritanceType } from '@rushstack/heft-config-file';
import { INonCustomJsonPathMetadata } from '@rushstack/heft-config-file';
import { IOriginalValueOptions } from '@rushstack/heft-config-file';
import { IPackageJson } from '@rushstack/node-core-library';
import { IProjectConfigurationFileSpecification } from '@rushstack/heft-config-file';
import { IPropertiesInheritance } from '@rushstack/heft-config-file';
import { IPropertyInheritance } from '@rushstack/heft-config-file';
import { IPropertyInheritanceDefaults } from '@rushstack/heft-config-file';
import { IRigConfig } from '@rushstack/rig-package';
import { ITerminal } from '@rushstack/terminal';
import { ITerminalProvider } from '@rushstack/terminal';
import type { Operation } from '@rushstack/operation-graph';
import type { OperationGroupRecord } from '@rushstack/operation-graph';
import { PathResolutionMethod } from '@rushstack/heft-config-file';
import { PropertyInheritanceCustomFunction } from '@rushstack/heft-config-file';

export { CommandLineChoiceListParameter }

export { CommandLineChoiceParameter }

export { CommandLineFlagParameter }

export { CommandLineIntegerListParameter }

export { CommandLineIntegerParameter }

export { CommandLineParameter }

export { CommandLineStringListParameter }

export { CommandLineStringParameter }

declare namespace ConfigurationFile {
    export {
        CustomValidationFunction,
        ICustomJsonPathMetadata,
        ICustomPropertyInheritance,
        IJsonPathMetadata,
        IJsonPathMetadataResolverOptions,
        IJsonPathsMetadata,
        INonCustomJsonPathMetadata,
        IOriginalValueOptions,
        IProjectConfigurationFileSpecification,
        IPropertiesInheritance,
        IPropertyInheritance,
        IPropertyInheritanceDefaults,
        InheritanceType,
        PathResolutionMethod,
        PropertyInheritanceCustomFunction
    }
}
export { ConfigurationFile }

/**
 * Glob a set of files and return a list of paths that match the provided patterns.
 *
 * @param patterns - Glob patterns to match against.
 * @param options - Options that are used when globbing the set of files.
 *
 * @public
 */
export declare type GlobFn = (pattern: string | string[], options?: IGlobOptions | undefined) => Promise<string[]>;

/**
 * @public
 */
export declare class HeftConfiguration {
    private _slashNormalizedBuildFolderPath;
    private _projectConfigFolderPath;
    private _tempFolderPath;
    private _rigConfig;
    private _rigPackageResolver;
    private readonly _knownConfigurationFiles;
    /**
     * Project build folder path. This is the folder containing the project's package.json file.
     */
    readonly buildFolderPath: string;
    /**
     * {@link HeftConfiguration.buildFolderPath} with all path separators converted to forward slashes.
     */
    get slashNormalizedBuildFolderPath(): string;
    /**
     * The path to the project's "config" folder.
     */
    get projectConfigFolderPath(): string;
    /**
     * The project's temporary folder.
     *
     * @remarks This folder exists at \<project root\>/temp. In general, this folder is used to store temporary
     * output from tasks under task-specific subfolders, and is not intended to be directly written to.
     * Instead, plugins should write to the directory provided by HeftTaskSession.taskTempFolderPath
     */
    get tempFolderPath(): string;
    /**
     * The rig.json configuration for this project, if present.
     */
    get rigConfig(): IRigConfig;
    /**
     * The rig package resolver, which can be used to rig-resolve a requested package.
     */
    get rigPackageResolver(): IRigPackageResolver;
    /**
     * Terminal instance to facilitate logging.
     */
    readonly globalTerminal: ITerminal;
    /**
     * Terminal provider for the provided terminal.
     */
    readonly terminalProvider: ITerminalProvider;
    /**
     * The Heft tool's package.json
     */
    get heftPackageJson(): IPackageJson;
    /**
     * The package.json of the project being built
     */
    get projectPackageJson(): IPackageJson;
    /**
     * The number of CPU cores available to the process. This can be used to determine how many tasks can be run
     * in parallel.
     */
    readonly numberOfCores: number;
    private constructor();
    /**
     * Performs the search for rig.json and initializes the `HeftConfiguration.rigConfig` object.
     * @internal
     */
    _checkForRigAsync(): Promise<void>;
    /**
     * Attempts to load a riggable project configuration file using blocking, synchronous I/O.
     * @param options - The options for the configuration file loader from `@rushstack/heft-config-file`. If invoking this function multiple times for the same file, reuse the same object.
     * @param terminal - The terminal to log messages during configuration file loading.
     * @returns The configuration file, or undefined if it could not be loaded.
     */
    tryLoadProjectConfigurationFile<TConfigFile>(options: IProjectConfigurationFileSpecification<TConfigFile>, terminal: ITerminal): TConfigFile | undefined;
    /**
     * Attempts to load a riggable project configuration file using asynchronous I/O.
     * @param options - The options for the configuration file loader from `@rushstack/heft-config-file`. If invoking this function multiple times for the same file, reuse the same object.
     * @param terminal - The terminal to log messages during configuration file loading.
     * @returns A promise that resolves to the configuration file, or undefined if it could not be loaded.
     */
    tryLoadProjectConfigurationFileAsync<TConfigFile>(options: IProjectConfigurationFileSpecification<TConfigFile>, terminal: ITerminal): Promise<TConfigFile | undefined>;
    /**
     * @internal
     */
    static initialize(options: _IHeftConfigurationInitializationOptions): HeftConfiguration;
    private _getConfigFileLoader;
}

/**
 * Used to specify a selection of files to copy from a specific source folder to one
 * or more destination folders.
 *
 * @public
 */
export declare interface ICopyOperation extends IFileSelectionSpecifier {
    /**
     * Absolute paths to folders which files or folders should be copied to.
     */
    destinationFolders: string[];
    /**
     * Copy only the file and discard the relative path from the source folder.
     */
    flatten?: boolean;
    /**
     * Hardlink files instead of copying.
     *
     * @remarks
     * If the sourcePath is a folder, the contained directory structure will be re-created
     * and all files will be individually hardlinked. This means that folders will be new
     * filesystem entities and will have separate folder metadata, while the contained files
     * will maintain normal hardlink behavior. This is done since folders do not have a
     * cross-platform equivalent of a hardlink, and since file symlinks provide fundamentally
     * different functionality in comparison to hardlinks.
     */
    hardlink?: boolean;
}

/**
 * Used to specify a selection of source files to delete from the specified source folder.
 *
 * @public
 */
export declare interface IDeleteOperation extends IFileSelectionSpecifier {
}

/**
 * Used to specify a selection of one or more files.
 *
 * @public
 */
export declare interface IFileSelectionSpecifier {
    /**
     * Absolute path to the target. The provided sourcePath can be to a file or a folder. If
     * fileExtensions, excludeGlobs, or includeGlobs are specified, the sourcePath is assumed
     * to be a folder. If it is not a folder, an error will be thrown.
     */
    sourcePath?: string;
    /**
     * File extensions that should be included from the source folder. Only supported when the sourcePath
     * is a folder.
     */
    fileExtensions?: string[];
    /**
     * Globs that should be explicitly excluded. This takes precedence over globs listed in "includeGlobs" and
     * files that match the file extensions provided in "fileExtensions". Only supported when the sourcePath
     * is a folder.
     */
    excludeGlobs?: string[];
    /**
     * Globs that should be explicitly included. Only supported when the sourcePath is a folder.
     */
    includeGlobs?: string[];
}

/**
 * A supported subset of options used when globbing files.
 *
 * @public
 */
export declare interface IGlobOptions {
    /**
     * Current working directory that the glob pattern will be applied to.
     */
    cwd?: string;
    /**
     * Whether or not the returned file paths should be absolute.
     *
     * @defaultValue false
     */
    absolute?: boolean;
    /**
     * Patterns to ignore when globbing.
     */
    ignore?: string[];
    /**
     * Whether or not to include dot files when globbing.
     *
     * @defaultValue false
     */
    dot?: boolean;
}

/**
 * @internal
 */
export declare interface _IHeftConfigurationInitializationOptions {
    /**
     * The working directory the tool was executed in.
     */
    cwd: string;
    /**
     * Terminal instance to facilitate logging.
     */
    terminalProvider: ITerminalProvider;
    /**
     * The number of CPU cores available to the process. This is used to determine how many tasks can be run in parallel.
     */
    numberOfCores: number;
}

/**
 * The default parameters provided by Heft.
 *
 * @public
 */
export declare interface IHeftDefaultParameters {
    /**
     * Whether or not the `--clean` flag was passed to Heft.
     *
     * @public
     */
    readonly clean: boolean;
    /**
     * Whether or not the `--debug` flag was passed to Heft.
     *
     * @public
     */
    readonly debug: boolean;
    /**
     * Whether or not the `--verbose` flag was passed to the Heft action.
     *
     * @public
     */
    readonly verbose: boolean;
    /**
     * Whether or not the `--production` flag was passed to the Heft action.
     *
     * @public
     */
    readonly production: boolean;
    /**
     * The locales provided to the Heft action via the `--locales` parameter.
     *
     * @public
     */
    readonly locales: Iterable<string>;
    /**
     * Whether or not the Heft action is running in watch mode.
     */
    readonly watch: boolean;
}

/**
 * Options provided to the clean hook.
 *
 * @public
 */
export declare interface IHeftLifecycleCleanHookOptions {
    /**
     * Add delete operations, which will be performed at the beginning of Heft execution.
     *
     * @public
     */
    addDeleteOperations: (...deleteOperations: IDeleteOperation[]) => void;
}

/**
 * Hooks that are available to the lifecycle plugin.
 *
 * @public
 */
export declare interface IHeftLifecycleHooks {
    /**
     * The `clean` hook is called at the beginning of Heft execution. It can be used to clean up
     * any files or folders that may be produced by the plugin. To use it, call
     * `clean.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    clean: AsyncParallelHook<IHeftLifecycleCleanHookOptions>;
    /**
     * The `toolStart` hook is called at the beginning of Heft execution, after the `clean` hook. It is
     * called before any phases have begun to execute. To use it, call
     * `toolStart.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    toolStart: AsyncParallelHook<IHeftLifecycleToolStartHookOptions>;
    /**
     * The `toolFinish` hook is called at the end of Heft execution. It is called after all phases have
     * completed execution. Plugins that tap this hook are resposible for handling the scenario in which
     * `toolStart` threw an error, since this hook is used to clean up any resources allocated earlier
     * in the lifecycle and therefore runs even in error conditions. To use it, call
     * `toolFinish.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    toolFinish: AsyncParallelHook<IHeftLifecycleToolFinishHookOptions>;
    /**
     * The `recordMetrics` hook is called at the end of every Heft execution pass. It is called after all
     * phases have completed execution (or been canceled). In a watch run, it will be called several times
     * in between `toolStart` and (if the session is gracefully interrupted via Ctrl+C), `toolFinish`.
     * In a non-watch run, it will be invoked exactly once between `toolStart` and `toolFinish`.
     *  To use it, call `recordMetrics.tapPromise(<pluginName>, <callback>)`.
     * @public
     */
    recordMetrics: AsyncParallelHook<IHeftRecordMetricsHookOptions>;
    /**
     * The `taskStart` hook is called at the beginning of a task. It is called before the task has begun
     * to execute. To use it, call `taskStart.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    taskStart: AsyncParallelHook<IHeftTaskStartHookOptions>;
    /**
     * The `taskFinish` hook is called at the end of a task. It is called after the task has completed
     * execution. To use it, call `taskFinish.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    taskFinish: AsyncParallelHook<IHeftTaskFinishHookOptions>;
    /**
     * The `phaseStart` hook is called at the beginning of a phase. It is called before the phase has
     * begun to execute. To use it, call `phaseStart.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    phaseStart: AsyncParallelHook<IHeftPhaseStartHookOptions>;
    /**
     * The `phaseFinish` hook is called at the end of a phase. It is called after the phase has completed
     * execution. To use it, call `phaseFinish.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    phaseFinish: AsyncParallelHook<IHeftPhaseFinishHookOptions>;
}

/**
 * The interface that Heft lifecycle plugins must implement. Lifecycle plugins are used to provide
 * functionality that affects the lifecycle of the Heft run. As such, they do not belong to any particular
 * Heft phase.
 *
 * @public
 */
export declare interface IHeftLifecyclePlugin<TOptions = void> extends IHeftPlugin<IHeftLifecycleSession, TOptions> {
}

/**
 * The lifecycle session is responsible for providing session-specific information to Heft lifecycle
 * plugins. The session provides access to the hooks that Heft will run as part of lifecycle execution,
 * as well as access to parameters provided via the CLI. The session is also how you request access to
 * other lifecycle plugins.
 *
 * @public
 */
export declare interface IHeftLifecycleSession {
    /**
     * The hooks available to the lifecycle plugin.
     *
     * @public
     */
    readonly hooks: IHeftLifecycleHooks;
    /**
     * Contains default parameters provided by Heft, as well as CLI parameters requested by the lifecycle
     * plugin.
     *
     * @public
     */
    readonly parameters: IHeftParameters;
    /**
     * The temp folder for the lifecycle plugin. This folder is unique for each lifecycle plugin,
     * and will be cleaned when Heft is run with `--clean`.
     *
     * @public
     */
    readonly tempFolderPath: string;
    /**
     * The scoped logger for the lifecycle plugin. Messages logged with this logger will be prefixed
     * with the plugin name, in the format `[lifecycle:<pluginName>]`. It is highly recommended that
     * writing to the console be performed via the logger, as it will ensure that logging messages
     * are labeled with the source of the message.
     *
     * @public
     */
    readonly logger: IScopedLogger;
    /**
     * Set a a callback which will be called if and after the specified plugin has been applied.
     * This can be used to tap hooks on another lifecycle plugin that exists within the same phase.
     *
     * @public
     */
    requestAccessToPluginByName<T extends object>(pluginToAccessPackage: string, pluginToAccessName: string, pluginApply: (pluginAccessor: T) => void): void;
}

/**
 * Options provided to the toolFinish hook.
 *
 * @public
 */
export declare interface IHeftLifecycleToolFinishHookOptions {
}

/**
 * Options provided to the toolStart hook.
 *
 * @public
 */
export declare interface IHeftLifecycleToolStartHookOptions {
}

/**
 * Parameters provided to a Heft plugin.
 *
 * @public
 */
export declare interface IHeftParameters extends IHeftDefaultParameters {
    /**
     * Get a choice parameter that has been defined in heft-plugin.json.
     *
     * @public
     */
    getChoiceParameter(parameterLongName: string): CommandLineChoiceParameter;
    /**
     * Get a choice list parameter that has been defined in heft-plugin.json.
     *
     * @public
     */
    getChoiceListParameter(parameterLongName: string): CommandLineChoiceListParameter;
    /**
     * Get a flag parameter that has been defined in heft-plugin.json.
     *
     * @public
     */
    getFlagParameter(parameterLongName: string): CommandLineFlagParameter;
    /**
     * Get an integer parameter that has been defined in heft-plugin.json.
     *
     * @public
     */
    getIntegerParameter(parameterLongName: string): CommandLineIntegerParameter;
    /**
     * Get an integer list parameter that has been defined in heft-plugin.json.
     *
     * @public
     */
    getIntegerListParameter(parameterLongName: string): CommandLineIntegerListParameter;
    /**
     * Get a string parameter that has been defined in heft-plugin.json.
     *
     * @public
     */
    getStringParameter(parameterLongName: string): CommandLineStringParameter;
    /**
     * Get a string list parameter that has been defined in heft-plugin.json.
     *
     * @public
     */
    getStringListParameter(parameterLongName: string): CommandLineStringListParameter;
}

/**
 * The type of {@link IHeftTaskSession.parsedCommandLine}, which exposes details about the
 * command line that was used to invoke Heft.
 * @public
 */
export declare interface IHeftParsedCommandLine {
    /**
     * Returns the subcommand passed on the Heft command line, before any aliases have been expanded.
     * This can be useful when printing error messages that need to refer to the invoked command line.
     *
     * @remarks
     * For example, if the invoked command was `heft test --verbose`, then `commandName`
     * would be `test`.
     *
     * Suppose the invoked command was `heft start` which is an alias for `heft build-watch --serve`.
     * In this case, the `commandName` would be `start`.  To get the expanded name `build-watch`,
     * use {@link IHeftParsedCommandLine.unaliasedCommandName} instead.
     *
     * When invoking phases directly using `heft run`, the `commandName` is `run`.
     *
     * @see {@link IHeftParsedCommandLine.unaliasedCommandName}
     */
    readonly commandName: string;
    /**
     * Returns the subcommand passed on the Heft command line, after any aliases have been expanded.
     * This can be useful when printing error messages that need to refer to the invoked command line.
     *
     * @remarks
     * For example, if the invoked command was `heft test --verbose`, then `unaliasedCommandName`
     * would be `test`.
     *
     * Suppose the invoked command was `heft start` which is an alias for `heft build-watch --serve`.
     * In this case, the `unaliasedCommandName` would be `build-watch`.  To get the alias name
     * `start`, use @see {@link IHeftParsedCommandLine.commandName} instead.
     *
     * When invoking phases directly using `heft run`, the `unaliasedCommandName` is `run`.
     *
     * @see {@link IHeftParsedCommandLine.commandName}
     */
    readonly unaliasedCommandName: string;
}

/**
 * @public
 */
export declare interface IHeftPhase {
    readonly phaseName: string;
    readonly phaseDescription: string | undefined;
    cleanFiles: ReadonlySet<IDeleteOperation>;
    consumingPhases: ReadonlySet<IHeftPhase>;
    dependencyPhases: ReadonlySet<IHeftPhase>;
    tasks: ReadonlySet<IHeftTask>;
    tasksByName: ReadonlyMap<string, IHeftTask>;
}

/**
 * @public
 */
export declare interface IHeftPhaseFinishHookOptions {
    operation: OperationGroupRecord<IHeftPhaseOperationMetadata>;
}

/**
 * Metadata for an operation that represents a phase.
 * @public
 */
export declare interface IHeftPhaseOperationMetadata {
    phase: IHeftPhase;
}

/**
 * @public
 */
export declare interface IHeftPhaseStartHookOptions {
    operation: OperationGroupRecord<IHeftPhaseOperationMetadata>;
}

/**
 * The interface used for all Heft plugins.
 *
 * @public
 */
export declare interface IHeftPlugin<TSession extends IHeftLifecycleSession | IHeftTaskSession = IHeftLifecycleSession | IHeftTaskSession, TOptions = void> {
    /**
     * The accessor provided by the plugin. This accessor can be obtained by other plugins within the same
     * phase by calling `session.requestAccessToPlugin(...)`, and is used by other plugins to interact with
     * hooks or properties provided by the host plugin.
     */
    readonly accessor?: object;
    /**
     * Apply the plugin to the session. Plugins are expected to hook into session hooks to provide plugin
     * implementation. The `apply(...)` method is called once per phase.
     *
     * @param session - The session to apply the plugin to.
     * @param heftConfiguration - The Heft configuration.
     * @param pluginOptions - Options for the plugin, specified in heft.json.
     */
    apply(session: TSession, heftConfiguration: HeftConfiguration, pluginOptions?: TOptions): void;
}

/**
 * @public
 */
export declare interface IHeftRecordMetricsHookOptions {
    /**
     * @public
     */
    metricName: string;
    /**
     * @public
     */
    metricData: IMetricsData;
}

/**
 * @public
 */
export declare interface IHeftTask {
    readonly parentPhase: IHeftPhase;
    readonly taskName: string;
    readonly consumingTasks: ReadonlySet<IHeftTask>;
    readonly dependencyTasks: ReadonlySet<IHeftTask>;
}

/**
 * Options provided to the `registerFileOperations` hook.
 *
 * @public
 */
export declare interface IHeftTaskFileOperations {
    /**
     * Copy operations to be performed following the `run` or `runIncremental` hook. These operations will be
     * performed after the task `run` or `runIncremental` hook has completed.
     *
     * @public
     */
    copyOperations: Set<ICopyOperation>;
    /**
     * Delete operations to be performed following the `run` or `runIncremental` hook. These operations will be
     * performed after the task `run` or `runIncremental` hook has completed.
     *
     * @public
     */
    deleteOperations: Set<IDeleteOperation>;
}

/**
 * @public
 */
export declare interface IHeftTaskFinishHookOptions {
    operation: Operation<IHeftTaskOperationMetadata>;
}

/**
 * Hooks that are available to the task plugin.
 *
 * @public
 */
export declare interface IHeftTaskHooks {
    /**
     * The `run` hook is called after all dependency task executions have completed during a normal
     * run, or during a watch mode run when no `runIncremental` hook is provided. It is where the
     * plugin can perform its work. To use it, call `run.tapPromise(<pluginName>, <callback>)`.
     *
     * @public
     */
    readonly run: AsyncParallelHook<IHeftTaskRunHookOptions>;
    /**
     * If provided, the `runIncremental` hook is called after all dependency task executions have completed
     * during a watch mode run. It is where the plugin can perform incremental work. To use it, call
     * `run.tapPromise(<pluginName>, <callback>)`.
     */
    readonly runIncremental: AsyncParallelHook<IHeftTaskRunIncrementalHookOptions>;
    /**
     * If provided, the `registerFileOperations` hook is called exactly once before the first time either
     * `run` or `runIncremental` would be invoked to provide the plugin an opportunity to request
     * dynamic file copy or deletion operations.
     */
    readonly registerFileOperations: AsyncSeriesWaterfallHook<IHeftTaskFileOperations>;
}

/**
 * Metadata for an operation that represents a task.
 * @public
 */
export declare interface IHeftTaskOperationMetadata {
    task: IHeftTask;
    phase: IHeftPhase;
}

/**
 * The interface that Heft task plugins must implement. Task plugins are used to provide the implementation
 * of a specific task.
 *
 * @public
 */
export declare interface IHeftTaskPlugin<TOptions = void> extends IHeftPlugin<IHeftTaskSession, TOptions> {
}

/**
 * Options provided to the `run` hook.
 *
 * @public
 */
export declare interface IHeftTaskRunHookOptions {
    /**
     * An abort signal that is used to abort the build. This can be used to stop operations early and allow
     * for a new build to be started.
     *
     * @beta
     */
    readonly abortSignal: AbortSignal;
    /**
     * Reads the specified globs and returns the result.
     */
    readonly globAsync: GlobFn;
}

/**
 * Options provided to the 'runIncremental' hook.
 *
 * @public
 */
export declare interface IHeftTaskRunIncrementalHookOptions extends IHeftTaskRunHookOptions {
    /**
     * A callback that can be invoked to tell the Heft runtime to schedule an incremental run of this
     * task. If a run is already pending, does nothing.
     */
    readonly requestRun: () => void;
    /**
     * Reads the specified globs and returns the result, filtering out files that have not changed since the last execution.
     * All file system calls while reading the glob are tracked and will be watched for changes.
     *
     * If a change to the monitored files is detected, the task will be scheduled for re-execution.
     */
    readonly watchGlobAsync: WatchGlobFn;
    /**
     * Access to the file system view that powers `watchGlobAsync`.
     * This is useful for plugins that do their own file system operations but still want to leverage Heft for watching.
     */
    readonly watchFs: IWatchFileSystem;
}

/**
 * The task session is responsible for providing session-specific information to Heft task plugins.
 * The session provides access to the hooks that Heft will run as part of task execution, as well as
 * access to parameters provided via the CLI. The session is also how you request access to other task
 * plugins.
 *
 * @public
 */
export declare interface IHeftTaskSession {
    /**
     * The name of the task. This is defined in "heft.json".
     *
     * @public
     */
    readonly taskName: string;
    /**
     * The hooks available to the task plugin.
     *
     * @public
     */
    readonly hooks: IHeftTaskHooks;
    /**
     * Contains default parameters provided by Heft, as well as CLI parameters requested by the task
     * plugin.
     *
     * @public
     */
    readonly parameters: IHeftParameters;
    /**
     * Exposes details about the command line that was used to invoke Heft.
     * This value is initially `undefined` and later filled in after the command line has been parsed.
     */
    readonly parsedCommandLine: IHeftParsedCommandLine;
    /**
     * The temp folder for the task. This folder is unique for each task, and will be cleaned
     * when Heft is run with `--clean`.
     *
     * @public
     */
    readonly tempFolderPath: string;
    /**
     * The scoped logger for the task. Messages logged with this logger will be prefixed with
     * the phase and task name, in the format `[<phaseName>:<taskName>]`. It is highly recommended
     * that writing to the console be performed via the logger, as it will ensure that logging messages
     * are labeled with the source of the message.
     *
     * @public
     */
    readonly logger: IScopedLogger;
    /**
     * Set a a callback which will be called if and after the specified plugin has been applied.
     * This can be used to tap hooks on another plugin that exists within the same phase.
     *
     * @public
     */
    requestAccessToPluginByName<T extends object>(pluginToAccessPackage: string, pluginToAccessName: string, pluginApply: (pluginAccessor: T) => void): void;
}

/**
 * @public
 */
export declare interface IHeftTaskStartHookOptions {
    operation: Operation<IHeftTaskOperationMetadata>;
}

/**
 * Used to specify a selection of files to copy from a specific source folder to one
 * or more destination folders.
 *
 * @public
 */
export declare interface IIncrementalCopyOperation extends ICopyOperation {
    /**
     * If true, the file will be copied only if the source file is contained in the
     * IHeftTaskRunIncrementalHookOptions.changedFiles map.
     */
    onlyIfChanged?: boolean;
}

/**
 * @public
 */
export declare interface IMetricsData {
    /**
     * The command that was executed.
     */
    command: string;
    /**
     * Whether or not the command ran into errors
     */
    encounteredError?: boolean;
    /**
     * The total execution duration of all user-defined tasks from `heft.json`, in milliseconds.
     * This metric is for measuring the cumulative time spent on the underlying build steps for a project.
     * If running in watch mode, this will be the duration of the most recent incremental build.
     */
    taskTotalExecutionMs: number;
    /**
     * The total duration before Heft started executing user-defined tasks, in milliseconds.
     * This metric is for tracking the contribution of Heft itself to total build duration.
     */
    bootDurationMs: number;
    /**
     * How long the process has been alive, in milliseconds.
     * This metric is for watch mode, to analyze how long developers leave individual Heft sessions running.
     */
    totalUptimeMs: number;
    /**
     * The name of the operating system provided by NodeJS.
     */
    machineOs: string;
    /**
     * The processor's architecture.
     */
    machineArch: string;
    /**
     * The number of processor cores.
     */
    machineCores: number;
    /**
     * The processor's model name.
     */
    machineProcessor: string;
    /**
     * The total amount of memory the machine has, in megabytes.
     */
    machineTotalMemoryMB: number;
    /**
     * A map of commandline parameter names to their effective values
     */
    commandParameters: Record<string, string>;
}

/**
 * @internal
 */
export declare interface _IPerformanceData {
    taskTotalExecutionMs: number;
    encounteredError?: boolean;
}

/**
 * Options for `fs.readdir`
 * @public
 */
export declare interface IReaddirOptions {
    /**
     * If true, readdir will return `fs.Dirent` objects instead of strings.
     */
    withFileTypes: true;
}

/**
 * Rig resolves requested tools from the project's Heft rig.
 *
 * @remarks For more information on rig resolution, see
 * https://rushstack.io/pages/heft/rig_packages/#3-riggable-dependencies
 *
 * @public
 */
export declare interface IRigPackageResolver {
    resolvePackageAsync(packageName: string, terminal: ITerminal): Promise<string>;
}

/**
 * Interface used by scripts that are run by the RunScriptPlugin.
 *
 * @beta
 */
export declare interface IRunScript {
    /**
     * The method that is called by the RunScriptPlugin to run the script.
     */
    runAsync: (options: IRunScriptOptions) => Promise<void>;
}

/**
 * Options provided to scripts that are run using the RunScriptPlugin.
 *
 * @beta
 */
export declare interface IRunScriptOptions {
    heftTaskSession: IHeftTaskSession;
    heftConfiguration: HeftConfiguration;
    runOptions: IHeftTaskRunHookOptions;
    scriptOptions: Record<string, unknown>;
}

/**
 * A logger which is used to emit errors and warnings to the console, as well as to write
 * to the console. Messaged emitted by the scoped logger are prefixed with the name of the
 * scoped logger.
 *
 * @public
 */
export declare interface IScopedLogger {
    /**
     * The name of the scoped logger. Logging messages will be prefixed with this name.
     */
    readonly loggerName: string;
    /**
     * The terminal used to write messages to the console.
     */
    readonly terminal: ITerminal;
    /**
     * Indicates if the logger has emitted any errors.
     */
    readonly hasErrors: boolean;
    /**
     * Call this function to emit an error to the heft runtime.
     */
    emitError(error: Error): void;
    /**
     * Call this function to emit an warning to the heft runtime.
     */
    emitWarning(warning: Error): void;
    /**
     * Reset the errors and warnings for this scoped logger.
     */
    resetErrorsAndWarnings(): void;
}

/**
 * Information about the state of a watched file.
 * @public
 */
export declare interface IWatchedFileState {
    /**
     * If the file has changed since the last invocation.
     */
    changed: boolean;
}

/**
 * Interface contract for heft plugins to use the `WatchFileSystemAdapter`
 * @public
 */
export declare interface IWatchFileSystem {
    /**
     * Synchronous readdir. Watches the directory for changes.
     *
     * @see fs.readdirSync
     */
    readdirSync(filePath: string): string[];
    readdirSync(filePath: string, options: IReaddirOptions): fs.Dirent[];
    /**
     * Asynchronous readdir. Watches the directory for changes.
     *
     * @see fs.readdir
     */
    readdir(filePath: string, callback: ReaddirStringCallback): void;
    readdir(filePath: string, options: IReaddirOptions, callback: ReaddirDirentCallback): void;
    /**
     * Asynchronous lstat. Watches the file for changes, or if it does not exist, watches to see if it is created.
     * @see fs.lstat
     */
    lstat(filePath: string, callback: StatCallback): void;
    /**
     * Synchronous lstat. Watches the file for changes, or if it does not exist, watches to see if it is created.
     * @see fs.lstatSync
     */
    lstatSync(filePath: string): fs.Stats;
    /**
     * Asynchronous stat. Watches the file for changes, or if it does not exist, watches to see if it is created.
     * @see fs.stat
     */
    stat(filePath: string, callback: StatCallback): void;
    /**
     * Synchronous stat. Watches the file for changes, or if it does not exist, watches to see if it is created.
     * @see fs.statSync
     */
    statSync(filePath: string): fs.Stats;
    /**
     * Tells the adapter to track the specified file (or folder) as used.
     * Returns an object containing data about the state of said file (or folder).
     * Uses promise-based API.
     */
    getStateAndTrackAsync(filePath: string): Promise<IWatchedFileState>;
    /**
     * Tells the adapter to track the specified file (or folder) as used.
     * Returns an object containing data about the state of said file (or folder).
     * Uses synchronous API.
     */
    getStateAndTrack(filePath: string): IWatchedFileState;
}

/**
 * @internal
 * A simple performance metrics collector. A plugin is required to pipe data anywhere.
 */
export declare class _MetricsCollector {
    readonly recordMetricsHook: AsyncParallelHook<IHeftRecordMetricsHookOptions>;
    private _bootDurationMs;
    private _startTimeMs;
    /**
     * Start metrics log timer.
     */
    setStartTime(): void;
    /**
     * Record metrics to the installed plugin(s).
     *
     * @param command - Describe the user command, e.g. `start` or `build`
     * @param parameterMap - Optional map of parameters to their values
     * @param performanceData - Optional performance data
     */
    recordAsync(command: string, performanceData?: Partial<_IPerformanceData>, parameters?: Record<string, string>): Promise<void>;
}

/**
 * Callback for `fs.readdir` when `withFileTypes` is true
 * @public
 */
export declare type ReaddirDirentCallback = (error: NodeJS.ErrnoException | null, files: fs.Dirent[]) => void;

/**
 * Callback for `fs.readdir` when `withFileTypes` is not specified or false
 * @public
 */
export declare type ReaddirStringCallback = (error: NodeJS.ErrnoException | null, files: string[]) => void;

/**
 * Callback for `fs.stat` and `fs.lstat`
 * @public
 */
export declare type StatCallback = (error: NodeJS.ErrnoException | null, stats: fs.Stats) => void;

/**
 * Glob a set of files and return a map of paths that match the provided patterns to their current state in the watcher.
 *
 * @param patterns - Glob patterns to match against.
 * @param options - Options that are used when globbing the set of files.
 *
 * @public
 */
export declare type WatchGlobFn = (pattern: string | string[], options?: IGlobOptions | undefined) => Promise<Map<string, IWatchedFileState>>;

export { }