@rushstack/rush-sdk 5.169.3 → 5.170.1-pr5378.0

package/lib-dts/logic/operations/IOperationRunner.d.ts

@@ -4,6 +4,17 @@ import type { OperationStatus } from './OperationStatus';
 import type { OperationMetadataManager } from './OperationMetadataManager';
 import type { IStopwatchResult } from '../../utilities/Stopwatch';
 import type { IEnvironment } from '../../utilities/Utilities';
+/**
+ * A snapshot of a previous operation execution, passed to runners to inform incremental behavior.
+ *
+ * @beta
+ */
+export interface IOperationLastState {
+    /**
+     * The status from the previous execution of this operation.
+     */
+    readonly status: OperationStatus;
+}
 /**
  * Information passed to the executing `IOperationRunner`
  *
@@ -49,6 +60,12 @@ export interface IOperationRunnerContext {
      * it later (for example to re-print errors at end of execution).
      */
     error?: Error;
+    /**
+     * Returns a callback that invalidates this operation so that it will be re-executed in the next iteration.
+     * The returned callback captures only the minimal state needed, avoiding retention of the full context.
+     * Callers should store the result rather than calling this method repeatedly.
+     */
+    getInvalidateCallback(): (reason: string) => void;
     /**
      * Invokes the specified callback with a terminal that is associated with this operation.
      *
@@ -61,7 +78,7 @@ export interface IOperationRunnerContext {
 }
 /**
  * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
- * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * `OperationGraph`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
  * implementation manages the actual process for running a single operation.
  *
  * @beta
@@ -93,13 +110,26 @@ export interface IOperationRunner {
      * analysis purposes.
      */
     readonly isNoOp?: boolean;
+    /**
+     * If true, this runner currently owns some kind of active resource (e.g. a service or a watch process).
+     * This can be used to determine if the operation is "in progress" even if it is not currently executing.
+     * If the runner supports this property, it should update it as appropriate during execution.
+     * The property is optional to avoid breaking existing implementations of IOperationRunner.
+     */
+    readonly isActive?: boolean;
     /**
      * Method to be executed for the operation.
+     * @param context - The context object containing information about the execution environment.
+     * @param lastState - The last execution result of this operation, if any.
      */
-    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+    executeAsync(context: IOperationRunnerContext, lastState?: IOperationLastState): Promise<OperationStatus>;
     /**
      * Return a hash of the configuration that affects the operation.
      */
     getConfigHash(): string;
+    /**
+     * If this runner performs any background work to optimize future runs, this method will clean it up.
+     */
+    closeAsync?(): Promise<void>;
 }
 //# sourceMappingURL=IOperationRunner.d.ts.map

package/lib-dts/logic/operations/IPCOperationRunner.d.ts

@@ -1,16 +1,15 @@
-import type { OperationRequestRunCallback } from '@rushstack/operation-graph';
 import type { IPhase } from '../../api/CommandLineConfiguration';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
-import type { IOperationRunner, IOperationRunnerContext } from './IOperationRunner';
+import type { IOperationRunner, IOperationRunnerContext, IOperationLastState } from './IOperationRunner';
 import { OperationStatus } from './OperationStatus';
 export interface IIPCOperationRunnerOptions {
     phase: IPhase;
     project: RushConfigurationProject;
     name: string;
-    commandToRun: string;
+    initialCommand: string;
+    incrementalCommand: string | undefined;
     commandForHash: string;
     persist: boolean;
-    requestRun: OperationRequestRunCallback;
     ignoredParameterValues: ReadonlyArray<string>;
 }
 /**
@@ -23,16 +22,17 @@ export declare class IPCOperationRunner implements IOperationRunner {
     readonly silent: boolean;
     readonly warningsAreAllowed: boolean;
     private readonly _rushProject;
-    private readonly _commandToRun;
+    private readonly _initialCommand;
+    private readonly _incrementalCommand;
     private readonly _commandForHash;
     private readonly _persist;
-    private readonly _requestRun;
     private readonly _ignoredParameterValues;
     private _ipcProcess;
     private _processReadyPromise;
     constructor(options: IIPCOperationRunnerOptions);
-    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+    get isActive(): boolean;
+    executeAsync(context: IOperationRunnerContext, lastState?: IOperationLastState): Promise<OperationStatus>;
     getConfigHash(): string;
-    shutdownAsync(): Promise<void>;
+    closeAsync(): Promise<void>;
 }
 //# sourceMappingURL=IPCOperationRunner.d.ts.map

package/lib-dts/logic/operations/Operation.d.ts

@@ -2,6 +2,18 @@ import type { RushConfigurationProject } from '../../api/RushConfigurationProjec
 import type { IPhase } from '../../api/CommandLineConfiguration';
 import type { IOperationRunner } from './IOperationRunner';
 import type { IOperationSettings } from '../../api/RushProjectConfiguration';
+import { type Parallelism } from './ParseParallelism';
+/**
+ * State for the `enabled` property of an `Operation`.
+ *
+ * - `true`: The operation should be executed if it or any dependencies changed.
+ * - `false`: The operation should be skipped.
+ * - `"ignore-dependency-changes"`: The operation should be executed if there are local changes in the project,
+ *   otherwise it should be skipped. This is useful for operations like "test" where you may want to skip
+ *   testing projects that haven't changed.
+ * @alpha
+ */
+export type OperationEnabledState = boolean | 'ignore-dependency-changes';
 /**
  * Options for constructing a new Operation.
  * @alpha
@@ -15,6 +27,18 @@ export interface IOperationOptions {
      * The Rush project associated with this Operation
      */
     project: RushConfigurationProject;
+    /**
+     * If set to false, this operation will be skipped during evaluation (return OperationStatus.Skipped).
+     * This is useful for plugins to alter the scope of the operation graph across executions,
+     * e.g. to enable or disable unit test execution, or to include or exclude dependencies.
+     *
+     * The special value "ignore-dependency-changes" can be used to indicate that this operation should only
+     * be executed if there are local changes in the project. This is useful for operations like
+     * "test" where you may want to skip testing projects that haven't changed.
+     *
+     * The default value is `true`, meaning the operation will be executed if it or any dependencies change.
+     */
+    enabled?: OperationEnabledState;
     /**
      * When the scheduler is ready to process this `Operation`, the `runner` implements the actual work of
      * running the operation.
@@ -31,7 +55,7 @@ export interface IOperationOptions {
 }
 /**
  * The `Operation` class is a node in the dependency graph of work that needs to be scheduled by the
- * `OperationExecutionManager`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
+ * `OperationGraph`. Each `Operation` has a `runner` member of type `IOperationRunner`, whose
  * implementation manages the actual process of running a single operation.
  *
  * The graph of `Operation` instances will be cloned into a separate execution graph after processing.
@@ -67,17 +91,23 @@ export declare class Operation {
      */
     runner: IOperationRunner | undefined;
     /**
-     * The weight for this operation. This scalar is the contribution of this operation to the
-     * `criticalPathLength` calculation above. Modify to indicate the following:
-     * - `weight` === 1: indicates that this operation has an average duration
-     * - `weight` > 1: indicates that this operation takes longer than average and so the scheduler
-     *     should try to favor starting it over other, shorter operations. An example might be an operation that
-     *     bundles an entire application and runs whole-program optimization.
-     * - `weight` < 1: indicates that this operation takes less time than average and so the scheduler
-     *     should favor other, longer operations over it. An example might be an operation to unpack a cached
-     *     output, or an operation using NullOperationRunner, which might use a value of 0.
-     */
-    weight: number;
+     * The concurrency weight for this operation. When coerced to an integer via `coerceParallelism`,
+     * this value represents how many concurrency slots the operation consumes while running.
+     *
+     * May be specified as:
+     * - A raw `number`: used directly as the slot count (e.g. `2` consumes two slots).
+     * - An `IParallelismScalar` (e.g. `{ scalar: 0.5 }`): coerced relative to the graph's
+     *   configured `maxParallelism` at execution time, so the weight scales with the available
+     *   concurrency rather than being fixed at parse time.
+     *
+     * Coerced values guide scheduling as follows:
+     * - `1` slot: typical operation consuming one logical thread.
+     * - `> 1` slots: operation that spawns multiple threads or requires significant RAM; reserving
+     *   extra slots prevents overloading the machine (e.g. a whole-program bundler or a test suite
+     *   that runs its own internal parallelism).
+     * - `0` slots: effectively free (e.g. a no-op or cache-restore step).
+     */
+    weight: Parallelism;
     /**
      * Get the operation settings for this operation, defaults to the values defined in
      *  the project configuration.
@@ -87,8 +117,14 @@ export declare class Operation {
      * If set to false, this operation will be skipped during evaluation (return OperationStatus.Skipped).
      * This is useful for plugins to alter the scope of the operation graph across executions,
      * e.g. to enable or disable unit test execution, or to include or exclude dependencies.
-     */
-    enabled: boolean;
+     *
+     * The special value "ignore-dependency-changes" can be used to indicate that this operation should only
+     * be executed if there are local changes in the project. This is useful for operations like
+     * "test" where you may want to skip testing projects that haven't changed.
+     *
+     * The default value is `true`, meaning the operation will be executed if it or any dependencies change.
+     */
+    enabled: OperationEnabledState;
     constructor(options: IOperationOptions);
     /**
      * The name of this operation, for logging.

package/lib-dts/logic/operations/OperationExecutionRecord.d.ts

@@ -7,7 +7,7 @@ import { Stopwatch } from '../../utilities/Stopwatch';
 import { OperationMetadataManager } from './OperationMetadataManager';
 import type { IPhase } from '../../api/CommandLineConfiguration';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
-import type { IOperationExecutionResult } from './IOperationExecutionResult';
+import type { IOperationExecutionResult, IOperationStateHashComponents } from './IOperationExecutionResult';
 import type { IInputsSnapshot } from '../incremental/InputsSnapshot';
 import type { IEnvironment } from '../../utilities/Utilities';
 import { type ILogFilePaths } from './ProjectLogWritable';
@@ -16,12 +16,22 @@ import { type ILogFilePaths } from './ProjectLogWritable';
  */
 export interface IOperationExecutionRecordContext {
     streamCollator: StreamCollator;
-    onOperationStatusChanged?: (record: OperationExecutionRecord) => void;
+    onOperationStateChanged?: (record: OperationExecutionRecord) => void;
     createEnvironment?: (record: OperationExecutionRecord) => IEnvironment;
+    invalidate?: (operations: Iterable<Operation>, reason: string) => void;
     inputsSnapshot: IInputsSnapshot | undefined;
+    maxParallelism: number;
     debugMode: boolean;
     quietMode: boolean;
 }
+/**
+ * Context object for the executeAsync() method.
+ * @internal
+ */
+export interface IOperationExecutionContext {
+    onStartAsync: (record: OperationExecutionRecord) => Promise<OperationStatus | undefined>;
+    onResultAsync: (record: OperationExecutionRecord) => Promise<void>;
+}
 /**
  * Internal class representing everything about executing an operation
  *
@@ -37,6 +47,10 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
      * it later (for example to re-print errors at end of execution).
      */
     error: Error | undefined;
+    /**
+     * If true, this operation should be executed. If false, it should be skipped.
+     */
+    enabled: boolean;
     /**
      * This number represents how far away this Operation is from the furthest "root" operation (i.e.
      * an operation with no consumers). This helps us to calculate the critical path (i.e. the
@@ -81,6 +95,7 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
     readonly stdioSummarizer: StdioSummarizer;
     readonly problemCollector: ProblemCollector;
     readonly runner: IOperationRunner;
+    readonly weight: number;
     readonly associatedPhase: IPhase;
     readonly associatedProject: RushConfigurationProject;
     readonly _operationMetadataManager: OperationMetadataManager;
@@ -92,14 +107,14 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
     private _stateHashComponents;
     constructor(operation: Operation, context: IOperationExecutionRecordContext);
     get name(): string;
-    get weight(): number;
     get debugMode(): boolean;
     get quietMode(): boolean;
     get collatedWriter(): CollatedWriter;
     get nonCachedDurationMs(): number | undefined;
     get cobuildRunnerId(): string | undefined;
     get environment(): IEnvironment | undefined;
-    get metadataFolderPath(): string | undefined;
+    getInvalidateCallback(): (reason: string) => void;
+    get metadataFolderPath(): string;
     get isTerminal(): boolean;
     /**
      * The current execution status of an operation. Operations start in the 'ready' state,
@@ -111,7 +126,7 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
     set status(newStatus: OperationStatus);
     get silent(): boolean;
     getStateHash(): string;
-    getStateHashComponents(): ReadonlyArray<string>;
+    getStateHashComponents(): IOperationStateHashComponents;
     /**
      * {@inheritdoc IOperationRunnerContext.runWithTerminalAsync}
      */
@@ -119,9 +134,6 @@ export declare class OperationExecutionRecord implements IOperationRunnerContext
         createLogFile: boolean;
         logFileSuffix: string;
     }): Promise<T>;
-    executeAsync({ onStart, onResult }: {
-        onStart: (record: OperationExecutionRecord) => Promise<OperationStatus | undefined>;
-        onResult: (record: OperationExecutionRecord) => Promise<void>;
-    }): Promise<void>;
+    executeAsync(lastState: OperationExecutionRecord | undefined, executeContext: IOperationExecutionContext): Promise<void>;
 }
 //# sourceMappingURL=OperationExecutionRecord.d.ts.map

package/lib-dts/logic/operations/OperationGraph.d.ts

@@ -0,0 +1,125 @@
+import { type TerminalWritable } from '@rushstack/terminal';
+import type { Operation } from './Operation';
+import { OperationStatus } from './OperationStatus';
+import { OperationExecutionRecord } from './OperationExecutionRecord';
+import type { IExecutionResult } from './IOperationExecutionResult';
+import type { IInputsSnapshot } from '../incremental/InputsSnapshot';
+import type { IOperationGraph, IOperationGraphIterationOptions } from './IOperationGraph';
+import { OperationGraphHooks } from '../../pluginFramework/OperationGraphHooks';
+import { type Parallelism } from './ParseParallelism';
+import type { ITelemetryData } from '../Telemetry';
+export interface IOperationGraphTelemetry {
+    initialExtraData: Record<string, unknown>;
+    changedProjectsOnlyKey: string | undefined;
+    nameForLog: string;
+    log: (telemetry: ITelemetryData) => void;
+}
+export interface IOperationGraphOptions {
+    quietMode: boolean;
+    debugMode: boolean;
+    parallelism: Parallelism;
+    allowOversubscription: boolean;
+    destinations: Iterable<TerminalWritable>;
+    /** Optional maximum allowed parallelism. Defaults to `getNumberOfCores()`. */
+    maxParallelism?: number;
+    /**
+     * Controller used to signal abortion of the entire execution session (e.g. terminating watch mode).
+     * Consumers (e.g. ProjectWatcher) can subscribe to this to perform cleanup.
+     */
+    abortController: AbortController;
+    isWatch?: boolean;
+    pauseNextIteration?: boolean;
+    telemetry?: IOperationGraphTelemetry;
+    getInputsSnapshotAsync?: () => Promise<IInputsSnapshot | undefined>;
+}
+/**
+ * A class which manages the execution of a set of tasks with interdependencies.
+ */
+export declare class OperationGraph implements IOperationGraph {
+    readonly hooks: OperationGraphHooks;
+    readonly operations: Set<Operation>;
+    readonly abortController: AbortController;
+    private readonly _sortedOperations;
+    resultByOperation: Map<Operation, OperationExecutionRecord>;
+    private _parallelism;
+    private _maxParallelism;
+    private _debugMode;
+    private _quietMode;
+    private _allowOversubscription;
+    private _pauseNextIteration;
+    private readonly _isWatch;
+    private readonly _telemetry;
+    private readonly _getInputsSnapshotAsync;
+    /**
+     * Records invalidated during the current iteration that could not be marked `Ready` immediately
+     * because their record object is shared between `resultByOperation` and the active iteration's
+     * `records` map (mutating it mid-iteration would corrupt the summarizer's view of results).
+     * Maps each record to the invalidation reason; applied once the iteration completes.
+     */
+    private readonly _deferredInvalidations;
+    private _currentIteration;
+    private _scheduledIteration;
+    private _terminalSplitter;
+    private _idleTimeout;
+    /** Tracks if a graph state change notification has been scheduled for next tick. */
+    private _graphStateChangeScheduled;
+    private _status;
+    constructor(operations: Set<Operation>, options: IOperationGraphOptions);
+    /**
+     * {@inheritDoc IOperationGraph.setEnabledStates}
+     */
+    setEnabledStates(operations: Iterable<Operation>, targetState: Operation['enabled'], mode: 'safe' | 'unsafe'): boolean;
+    get parallelism(): number;
+    set parallelism(value: Parallelism);
+    get debugMode(): boolean;
+    set debugMode(value: boolean);
+    get quietMode(): boolean;
+    set quietMode(value: boolean);
+    get allowOversubscription(): boolean;
+    set allowOversubscription(value: boolean);
+    get pauseNextIteration(): boolean;
+    set pauseNextIteration(value: boolean);
+    get hasScheduledIteration(): boolean;
+    get status(): OperationStatus;
+    get terminalDestinations(): ReadonlySet<TerminalWritable>;
+    private _setStatus;
+    private _setScheduledIteration;
+    closeRunnersAsync(operations?: Operation[]): Promise<void>;
+    invalidateOperations(operations?: Iterable<Operation>, reason?: string): void;
+    /**
+     * Shorthand for scheduling an iteration then executing it.
+     * Call `abortCurrentIterationAsync()` to cancel the execution of any operations that have not yet begun execution.
+     * @param iterationOptions - Options for this execution iteration.
+     * @returns A promise which is resolved when all operations have been processed to a final state.
+     */
+    executeAsync(iterationOptions: IOperationGraphIterationOptions): Promise<IExecutionResult>;
+    /**
+     * Queues a new execution iteration.
+     * @param iterationOptions - Options for this execution iteration.
+     * @returns A promise that resolves to true if the iteration was successfully queued, or false if it was not.
+     */
+    scheduleIterationAsync(iterationOptions: IOperationGraphIterationOptions): Promise<boolean>;
+    /**
+     * Executes all operations which have been registered, returning a promise which is resolved when all operations have been processed to a final state.
+     * Aborts the current iteration first, if any.
+     */
+    executeScheduledIterationAsync(): Promise<boolean>;
+    abortCurrentIterationAsync(): Promise<void>;
+    addTerminalDestination(destination: TerminalWritable): void;
+    removeTerminalDestination(destination: TerminalWritable, close?: boolean): boolean;
+    private _setIdleTimeout;
+    private _onIdle;
+    private _scheduleIterationAsync;
+    /**
+     * Debounce configuration change notifications so that multiple property setters invoked within the same tick
+     * only trigger the hook once. This avoids redundant re-computation in listeners (e.g. UI refresh) while preserving
+     * ordering guarantees that the notification occurs after the initiating state changes are fully applied.
+     */
+    private _scheduleManagerStateChanged;
+    /**
+     * Executes all operations which have been registered, returning a promise which is resolved when all operations have been processed to a final state.
+     * The abortController can be used to cancel the execution of any operations that have not yet begun execution.
+     */
+    private _executeInnerAsync;
+}
+//# sourceMappingURL=OperationGraph.d.ts.map

package/lib-dts/logic/operations/OperationStatus.d.ts

@@ -57,4 +57,8 @@ export declare enum OperationStatus {
  * @alpha
  */
 export declare const TERMINAL_STATUSES: Set<OperationStatus>;
+/**
+ * The set of statuses that are considered successful and don't trigger a rebuild if current.
+ */
+export declare const SUCCESS_STATUSES: Set<OperationStatus>;
 //# sourceMappingURL=OperationStatus.d.ts.map

package/lib-dts/logic/operations/ParseParallelism.d.ts

@@ -0,0 +1,33 @@
+export declare function getNumberOfCores(): number;
+/**
+ * A parallelism value expressed as a fraction of total available concurrency slots.
+ * @beta
+ */
+export interface IParallelismScalar {
+    readonly scalar: number;
+}
+/**
+ * A parallelism value, either as an absolute integer count or a scalar fraction of available parallelism.
+ * @beta
+ */
+export type Parallelism = number | IParallelismScalar;
+/**
+ * Since the JSON value is a string, it must be a percentage like "50%",
+ * which we parse into a scalar in the range (0, 1].
+ * The caller is responsible for multiplying by the available parallelism.
+ */
+export declare function parseParallelismPercent(weight: string): number;
+/**
+ * Coerces a `Parallelism` value to a concrete integer number of concurrency units, given the
+ * maximum number of available slots.
+ *
+ * - Raw numeric values are clamped to `[minimum, maxParallelism]`.
+ * - Scalar values are multiplied by `maxParallelism`, floored, and clamped to `[Math.max(1, minimum), maxParallelism]`.
+ */
+export declare function coerceParallelism(parallelism: Parallelism, maxParallelism: number, minimum?: number): number;
+/**
+ * Parses a command line specification for desired parallelism.
+ * Factored out to enable unit tests
+ */
+export declare function parseParallelism(rawParallelism: string | undefined): Parallelism;
+//# sourceMappingURL=ParseParallelism.d.ts.map

package/lib-dts/logic/operations/ShellOperationRunner.d.ts

@@ -1,12 +1,13 @@
 import type { IPhase } from '../../api/CommandLineConfiguration';
 import type { RushConfigurationProject } from '../../api/RushConfigurationProject';
-import type { IOperationRunner, IOperationRunnerContext } from './IOperationRunner';
+import type { IOperationRunner, IOperationRunnerContext, IOperationLastState } from './IOperationRunner';
 import { OperationStatus } from './OperationStatus';
 export interface IShellOperationRunnerOptions {
     phase: IPhase;
     rushProject: RushConfigurationProject;
     displayName: string;
-    commandToRun: string;
+    initialCommand: string;
+    incrementalCommand: string | undefined;
     commandForHash: string;
     ignoredParameterValues: ReadonlyArray<string>;
 }
@@ -21,18 +22,18 @@ export declare class ShellOperationRunner implements IOperationRunner {
     readonly silent: boolean;
     readonly cacheable: boolean;
     readonly warningsAreAllowed: boolean;
-    readonly commandToRun: string;
     /**
      * The creator is expected to use a different runner if the command is known to be a noop.
      */
     readonly isNoOp: boolean;
     private readonly _commandForHash;
+    private readonly _initialCommand;
+    private readonly _incrementalCommand;
     private readonly _rushProject;
     private readonly _ignoredParameterValues;
     constructor(options: IShellOperationRunnerOptions);
-    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+    executeAsync(context: IOperationRunnerContext, lastState?: IOperationLastState): Promise<OperationStatus>;
     getConfigHash(): string;
-    private _executeAsync;
 }
 /**
  * When running a command from the "scripts" block in package.json, if the command

package/lib-dts/logic/operations/ShellOperationRunnerPlugin.d.ts

@@ -16,7 +16,8 @@ export declare function initializeShellOperationRunner(options: {
     project: RushConfigurationProject;
     displayName: string;
     rushConfiguration: RushConfiguration;
-    commandToRun: string | undefined;
+    initialCommand: string | undefined;
+    incrementalCommand: string | undefined;
     commandForHash?: string;
     customParameterValues: ReadonlyArray<string>;
     ignoredParameterValues: ReadonlyArray<string>;

package/lib-dts/logic/operations/ValidateOperationsPlugin.d.ts

@@ -1,13 +1,11 @@
 import type { ITerminal } from '@rushstack/terminal';
 import type { IPhasedCommandPlugin, PhasedCommandHooks } from '../../pluginFramework/PhasedCommandHooks';
 /**
- * Core phased command plugin that provides the functionality for generating a base operation graph
- * from the set of selected projects and phases.
+ * Core phased command plugin that verifies correctness of the entries in rush-project.json
  */
 export declare class ValidateOperationsPlugin implements IPhasedCommandPlugin {
     private readonly _terminal;
     constructor(terminal: ITerminal);
     apply(hooks: PhasedCommandHooks): void;
-    private _validateOperations;
 }
 //# sourceMappingURL=ValidateOperationsPlugin.d.ts.map

package/lib-dts/pluginFramework/OperationGraphHooks.d.ts

@@ -0,0 +1,129 @@
+import { AsyncSeriesBailHook, AsyncSeriesHook, AsyncSeriesWaterfallHook, SyncHook, SyncWaterfallHook } from 'tapable';
+import type { Operation } from '../logic/operations/Operation';
+import type { IOperationExecutionResult, IConfigurableOperation } from '../logic/operations/IOperationExecutionResult';
+import type { OperationStatus } from '../logic/operations/OperationStatus';
+import type { IOperationRunnerContext } from '../logic/operations/IOperationRunner';
+import type { ITelemetryData } from '../logic/Telemetry';
+import type { IEnvironment } from '../utilities/Utilities';
+import type { IOperationGraph, IOperationGraphIterationOptions } from '../logic/operations/IOperationGraph';
+/**
+ * Hooks into the execution process for operations within the graph.
+ *
+ * Per-iteration lifecycle:
+ * 1. `configureIteration` - Synchronously decide which operations to enable for the next iteration.
+ * 2. `onIterationScheduled` - Fires after the iteration is prepared but before execution begins, if it has any enabled operations.
+ * 3. `beforeExecuteIterationAsync` - Async hook that can bail out the iteration entirely.
+ * 4. Operations execute (status changes reported via `onExecutionStatesUpdated`).
+ * 5. `afterExecuteIterationAsync` - Fires after all operations in the iteration have settled.
+ * 6. `onIdle` - Fires when the graph enters idle state awaiting changes (watch mode only).
+ *
+ * Additional hooks:
+ * - `onEnableStatesChanged` - Fires when `setEnabledStates` mutates operation enabled flags.
+ * - `onInvalidateOperations` - Fires when operations are invalidated (e.g. by file watchers).
+ * - `onGraphStateChanged` - Fires on any observable graph state change.
+ *
+ * @alpha
+ */
+export declare class OperationGraphHooks {
+    /**
+     * Hook invoked to decide what work a potential new iteration contains.
+     * Use the `lastExecutedRecords` to determine which operations are new or have had their inputs changed.
+     * Set the `enabled` states on the values in `initialRecords` to control which operations will be executed.
+     *
+     * @remarks
+     * This hook is synchronous to guarantee that the `lastExecutedRecords` map remains stable for the
+     * duration of configuration. This hook often executes while an execution iteration is currently running, so
+     * operations could complete if there were async ticks during the configuration phase.
+     *
+     * If no operations are marked for execution, the iteration will not be scheduled.
+     * If there is an existing scheduled iteration, it will remain.
+     */
+    readonly configureIteration: SyncHook<[
+        ReadonlyMap<Operation, IConfigurableOperation>,
+        ReadonlyMap<Operation, IOperationExecutionResult>,
+        IOperationGraphIterationOptions
+    ]>;
+    /**
+     * Hook invoked before operation start for an iteration. Allows a plugin to perform side-effects or
+     * short-circuit the entire iteration.
+     *
+     * If any tap returns an {@link OperationStatus}, the remaining taps are skipped and the iteration will
+     * end immediately with that status. All operations which have not yet executed will be marked
+     * Aborted.
+     */
+    readonly beforeExecuteIterationAsync: AsyncSeriesBailHook<[
+        ReadonlyMap<Operation, IOperationExecutionResult>,
+        IOperationGraphIterationOptions
+    ], OperationStatus | undefined | void>;
+    /**
+     * Batched hook invoked when one or more operation statuses have changed during the same microtask.
+     * The hook receives an array of the operation execution results that changed status.
+     * @remarks
+     * This hook is batched to reduce noise when updating many operations synchronously in quick succession.
+     */
+    readonly onExecutionStatesUpdated: SyncHook<[ReadonlySet<IOperationExecutionResult>]>;
+    /**
+     * Hook invoked when one or more operations have their enabled state mutated via
+     * {@link IOperationGraph.setEnabledStates}. Provides the set of operations whose
+     * enabled state actually changed.
+     */
+    readonly onEnableStatesChanged: SyncHook<[ReadonlySet<Operation>]>;
+    /**
+     * Hook invoked immediately after a new execution iteration is scheduled (i.e. operations selected and prepared),
+     * before any operations in that iteration have started executing. Can be used to snapshot planned work,
+     * drive UIs, or pre-compute auxiliary data.
+     */
+    readonly onIterationScheduled: SyncHook<[ReadonlyMap<Operation, IOperationExecutionResult>]>;
+    /**
+     * Hook invoked when any observable state on the operation graph changes.
+     * This includes configuration mutations (parallelism, quiet/debug modes, pauseNextIteration)
+     * as well as dynamic state (status transitions, scheduled iteration availability, etc.).
+     * Hook is series for stable output.
+     */
+    readonly onGraphStateChanged: SyncHook<[IOperationGraph]>;
+    /**
+     * Hook invoked when operations are invalidated for any reason.
+     */
+    readonly onInvalidateOperations: SyncHook<[Iterable<Operation>, string | undefined]>;
+    /**
+     * Hook invoked after an iteration has finished and the command is watching for changes.
+     * May be used to display additional relevant data to the user.
+     * Only relevant when running in watch mode.
+     */
+    readonly onIdle: SyncHook<void>;
+    /**
+     * Hook invoked after executing a set of operations.
+     * Hook is series for stable output.
+     */
+    readonly afterExecuteIterationAsync: AsyncSeriesWaterfallHook<[
+        OperationStatus,
+        ReadonlyMap<Operation, IOperationExecutionResult>,
+        IOperationGraphIterationOptions
+    ]>;
+    /**
+     * Hook invoked after executing an iteration, before the telemetry entry is written.
+     * Allows the caller to augment or modify the log entry.
+     */
+    readonly beforeLog: SyncHook<ITelemetryData, void>;
+    /**
+     * Hook invoked before executing a operation.
+     */
+    readonly beforeExecuteOperationAsync: AsyncSeriesBailHook<[
+        IOperationRunnerContext & IOperationExecutionResult
+    ], OperationStatus | undefined>;
+    /**
+     * Hook invoked to define environment variables for an operation.
+     * May be invoked by the runner to get the environment for the operation.
+     */
+    readonly createEnvironmentForOperation: SyncWaterfallHook<[
+        IEnvironment,
+        IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+    /**
+     * Hook invoked after executing a operation.
+     */
+    readonly afterExecuteOperationAsync: AsyncSeriesHook<[
+        IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+}
+//# sourceMappingURL=OperationGraphHooks.d.ts.map