Fix API.md

Author: dmichon-msft

common/reviews/api/rush-lib.api.md

@@ -342,6 +342,14 @@ export type GetCacheEntryIdFunction = (options: IGenerateCacheEntryIdOptions) =>
 // @beta
 export type GetInputsSnapshotAsyncFn = () => Promise<IInputsSnapshot | undefined>;
 
+// @alpha (undocumented)
+export interface IBaseOperationExecutionResult {
+    getStateHash(): string;
+    getStateHashComponents(): ReadonlyArray<string>;
+    readonly metadataFolderPath: string | undefined;
+    readonly operation: Operation;
+}
+
 // @internal (undocumented)
 export interface _IBuiltInPluginConfiguration extends _IRushPluginConfigurationBase {
     // (undocumented)
@@ -402,6 +410,11 @@ export interface ICobuildLockProvider {
     setCompletedStateAsync(context: Readonly<ICobuildContext>, state: ICobuildCompletedState): Promise<void>;
 }
 
+// @alpha
+export interface IConfigurableOperation extends IBaseOperationExecutionResult {
+    enabled: boolean;
+}
+
 // @public
 export interface IConfigurationEnvironment {
     [environmentVariableName: string]: IConfigurationEnvironmentVariable;
@@ -419,17 +432,14 @@ export interface ICreateOperationsContext {
     readonly changedProjectsOnly: boolean;
     readonly cobuildConfiguration: CobuildConfiguration | undefined;
     readonly customParameters: ReadonlyMap<string, CommandLineParameter>;
+    readonly generateFullGraph?: boolean;
     readonly includePhaseDeps: boolean;
-    readonly invalidateOperation?: ((operation: Operation, reason: string) => void) | undefined;
     readonly isIncrementalBuildAllowed: boolean;
-    readonly isInitial: boolean;
     readonly isWatch: boolean;
     readonly parallelism: number;
-    readonly phaseOriginal: ReadonlySet<IPhase>;
     readonly phaseSelection: ReadonlySet<IPhase>;
     readonly projectConfigurations: ReadonlyMap<RushConfigurationProject, RushProjectConfiguration>;
     readonly projectSelection: ReadonlySet<RushConfigurationProject>;
-    readonly projectsInUnknownState: ReadonlySet<RushConfigurationProject>;
     readonly rushConfiguration: RushConfiguration;
 }
 
@@ -476,12 +486,6 @@ export interface IEnvironmentConfigurationInitializeOptions {
     doNotNormalizePaths?: boolean;
 }
 
-// @alpha
-export interface IExecuteOperationsContext extends ICreateOperationsContext {
-    readonly abortController: AbortController;
-    readonly inputsSnapshot?: IInputsSnapshot;
-}
-
 // @alpha
 export interface IExecutionResult {
     readonly operationResults: ReadonlyMap<Operation, IOperationExecutionResult>;
@@ -614,14 +618,43 @@ export interface _IOperationBuildCacheOptions {
 }
 
 // @alpha
-export interface IOperationExecutionResult {
+export interface IOperationExecutionManager {
+    readonly abortController: AbortController;
+    abortCurrentPassAsync(): Promise<void>;
+    closeRunnersAsync(operations?: Iterable<Operation>): Promise<void>;
+    debugMode: boolean;
+    executeQueuedPassAsync(): Promise<boolean>;
+    readonly hasQueuedPass: boolean;
+    readonly hooks: OperationExecutionHooks;
+    invalidateOperations(operations?: Iterable<Operation>, reason?: string): void;
+    readonly lastExecutionResults: ReadonlyMap<Operation, IOperationExecutionResult>;
+    readonly operations: ReadonlySet<Operation>;
+    parallelism: number;
+    queuePassAsync(options: IOperationExecutionPassOptions): Promise<boolean>;
+    quietMode: boolean;
+    runNextPassBehavior: RunNextPassBehavior;
+    setEnabledStates(operations: Iterable<Operation>, targetState: Operation['enabled'], mode: 'safe' | 'unsafe'): boolean;
+    readonly status: OperationStatus;
+}
+
+// @alpha
+export interface IOperationExecutionManagerContext extends ICreateOperationsContext {
+    readonly initialSnapshot?: IInputsSnapshot;
+}
+
+// @alpha
+export interface IOperationExecutionPassOptions {
+    // (undocumented)
+    inputsSnapshot?: IInputsSnapshot;
+    startTime?: number;
+}
+
+// @alpha
+export interface IOperationExecutionResult extends IBaseOperationExecutionResult {
+    readonly enabled: boolean;
     readonly error: Error | undefined;
-    getStateHash(): string;
-    getStateHashComponents(): ReadonlyArray<string>;
     readonly logFilePaths: ILogFilePaths | undefined;
-    readonly metadataFolderPath: string | undefined;
     readonly nonCachedDurationMs: number | undefined;
-    readonly operation: Operation;
     readonly problemCollector: IProblemCollector;
     readonly silent: boolean;
     readonly status: OperationStatus;
@@ -653,6 +686,7 @@ export interface _IOperationMetadataManagerOptions {
 
 // @alpha
 export interface IOperationOptions {
+    enabled?: OperationEnabledState;
     logFilenameIdentifier: string;
     phase: IPhase;
     project: RushConfigurationProject;
@@ -663,8 +697,10 @@ export interface IOperationOptions {
 // @beta
 export interface IOperationRunner {
     cacheable: boolean;
-    executeAsync(context: IOperationRunnerContext): Promise<OperationStatus>;
+    closeAsync?(): Promise<void>;
+    executeAsync(context: IOperationRunnerContext, lastState?: {}): Promise<OperationStatus>;
     getConfigHash(): string;
+    readonly isActive?: boolean;
     readonly isNoOp?: boolean;
     readonly name: string;
     reportTiming: boolean;
@@ -751,6 +787,11 @@ export interface IPhasedCommand extends IRushCommand {
     readonly sessionAbortController: AbortController;
 }
 
+// @alpha
+export interface IPhasedCommandPlugin {
+    apply(hooks: PhasedCommandHooks): void;
+}
+
 // @public
 export interface IPnpmLockfilePolicies {
     disallowInsecureSha1?: {
@@ -994,7 +1035,7 @@ export class Operation {
     readonly consumers: ReadonlySet<Operation>;
     deleteDependency(dependency: Operation): void;
     readonly dependencies: ReadonlySet<Operation>;
-    enabled: boolean;
+    enabled: OperationEnabledState;
     get isNoOp(): boolean;
     logFilenameIdentifier: string;
     get name(): string;
@@ -1008,7 +1049,7 @@ export class _OperationBuildCache {
     // (undocumented)
     get cacheId(): string | undefined;
     // (undocumented)
-    static forOperation(executionResult: IOperationExecutionResult, options: _IOperationBuildCacheOptions): _OperationBuildCache;
+    static forOperation(executionResult: IBaseOperationExecutionResult, options: _IOperationBuildCacheOptions): _OperationBuildCache;
     // (undocumented)
     static getOperationBuildCache(options: _IProjectBuildCacheOptions): _OperationBuildCache;
     // (undocumented)
@@ -1017,6 +1058,43 @@ export class _OperationBuildCache {
     trySetCacheEntryAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
 }
 
+// @alpha
+export type OperationEnabledState = boolean | 'ignore-dependency-changes';
+
+// @alpha
+export class OperationExecutionHooks {
+    readonly afterExecuteOperationAsync: AsyncSeriesHook<[
+    IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+    readonly afterExecuteOperationsAsync: AsyncSeriesWaterfallHook<[
+    OperationStatus,
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationExecutionPassOptions
+    ]>;
+    readonly beforeExecuteOperationAsync: AsyncSeriesBailHook<[
+    IOperationRunnerContext & IOperationExecutionResult
+    ], OperationStatus | undefined>;
+    readonly beforeExecuteOperationsAsync: AsyncSeriesBailHook<[
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationExecutionPassOptions
+    ], OperationStatus | undefined | void>;
+    readonly configureRun: SyncHook<[
+    ReadonlyMap<Operation, IConfigurableOperation>,
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationExecutionPassOptions
+    ]>;
+    readonly createEnvironmentForOperation: SyncWaterfallHook<[
+    IEnvironment,
+    IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+    readonly onEnableStatesChanged: SyncHook<[ReadonlySet<Operation>]>;
+    readonly onExecutionStatesUpdated: SyncHook<[ReadonlySet<IOperationExecutionResult>]>;
+    readonly onInvalidateOperations: SyncHook<[Iterable<Operation>, string | undefined]>;
+    readonly onManagerStateChanged: SyncHook<[IOperationExecutionManager]>;
+    readonly onPassQueued: SyncHook<[ReadonlyMap<Operation, IOperationExecutionResult>]>;
+    readonly onWaitingForChanges: SyncHook<void>;
+}
+
 // @internal
 export class _OperationMetadataManager {
     constructor(options: _IOperationMetadataManagerOptions);
@@ -1146,26 +1224,15 @@ export abstract class PackageManagerOptionsConfigurationBase implements IPackage
 
 // @alpha
 export class PhasedCommandHooks {
-    readonly afterExecuteOperation: AsyncSeriesHook<[
-    IOperationRunnerContext & IOperationExecutionResult
-    ]>;
-    readonly afterExecuteOperations: AsyncSeriesHook<[IExecutionResult, IExecuteOperationsContext]>;
-    readonly beforeExecuteOperation: AsyncSeriesBailHook<[
-    IOperationRunnerContext & IOperationExecutionResult
-    ], OperationStatus | undefined>;
-    readonly beforeExecuteOperations: AsyncSeriesHook<[
-    Map<Operation, IOperationExecutionResult>,
-    IExecuteOperationsContext
-    ]>;
     readonly beforeLog: SyncHook<ITelemetryData, void>;
-    readonly createEnvironmentForOperation: SyncWaterfallHook<[
-    IEnvironment,
-    IOperationRunnerContext & IOperationExecutionResult
+    readonly createOperationsAsync: AsyncSeriesWaterfallHook<[
+    Set<Operation>,
+    ICreateOperationsContext
+    ]>;
+    readonly executionManagerAsync: AsyncSeriesHook<[
+    IOperationExecutionManager,
+    IOperationExecutionManagerContext
     ]>;
-    readonly createOperations: AsyncSeriesWaterfallHook<[Set<Operation>, ICreateOperationsContext]>;
-    readonly onOperationStatusChanged: SyncHook<[IOperationExecutionResult]>;
-    readonly shutdownAsync: AsyncParallelHook<void>;
-    readonly waitingForChanges: SyncHook<void>;
 }
 
 // @public
@@ -1229,6 +1296,9 @@ export class RepoStateFile {
     refreshState(rushConfiguration: RushConfiguration, subspace: Subspace | undefined, variant?: string): boolean;
 }
 
+// @alpha (undocumented)
+export type RunNextPassBehavior = 'manual' | 'automatic';
+
 // @public
 export class Rush {
     static launch(launcherVersion: string, options: ILaunchOptions): void;