Rename pass -> iteration

Author: dmichon-msft

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

@@ -618,24 +618,31 @@ export interface _IOperationBuildCacheOptions {
     terminal: ITerminal;
 }
 
+// @alpha
+export interface IOperationExecutionIterationOptions {
+    // (undocumented)
+    inputsSnapshot?: IInputsSnapshot;
+    startTime?: number;
+}
+
 // @alpha
 export interface IOperationExecutionManager {
     readonly abortController: AbortController;
-    abortCurrentPassAsync(): Promise<void>;
+    abortCurrentIterationAsync(): Promise<void>;
     addTerminalDestination(destination: TerminalWritable): void;
     closeRunnersAsync(operations?: Iterable<Operation>): Promise<void>;
     debugMode: boolean;
-    executeQueuedPassAsync(): Promise<boolean>;
-    readonly hasQueuedPass: boolean;
+    executeScheduledIterationAsync(): Promise<boolean>;
+    readonly hasScheduledIteration: 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>;
+    pauseNextIteration: boolean;
     quietMode: boolean;
     removeTerminalDestination(destination: TerminalWritable, close?: boolean): boolean;
-    runNextPassBehavior: RunNextPassBehavior;
+    scheduleIterationAsync(options: IOperationExecutionIterationOptions): Promise<boolean>;
     setEnabledStates(operations: Iterable<Operation>, targetState: Operation['enabled'], mode: 'safe' | 'unsafe'): boolean;
     readonly status: OperationStatus;
 }
@@ -645,13 +652,6 @@ export interface IOperationExecutionManagerContext extends ICreateOperationsCont
     readonly initialSnapshot?: IInputsSnapshot;
 }
 
-// @alpha
-export interface IOperationExecutionPassOptions {
-    // (undocumented)
-    inputsSnapshot?: IInputsSnapshot;
-    startTime?: number;
-}
-
 // @alpha
 export interface IOperationExecutionResult extends IBaseOperationExecutionResult {
     readonly enabled: boolean;
@@ -1066,25 +1066,25 @@ export type OperationEnabledState = boolean | 'ignore-dependency-changes';
 
 // @alpha
 export class OperationExecutionHooks {
+    readonly afterExecuteIterationAsync: AsyncSeriesWaterfallHook<[
+    OperationStatus,
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationExecutionIterationOptions
+    ]>;
     readonly afterExecuteOperationAsync: AsyncSeriesHook<[
     IOperationRunnerContext & IOperationExecutionResult
     ]>;
-    readonly afterExecuteOperationsAsync: AsyncSeriesWaterfallHook<[
-    OperationStatus,
+    readonly beforeExecuteIterationAsync: AsyncSeriesBailHook<[
     ReadonlyMap<Operation, IOperationExecutionResult>,
-    IOperationExecutionPassOptions
-    ]>;
+    IOperationExecutionIterationOptions
+    ], OperationStatus | undefined | void>;
     readonly beforeExecuteOperationAsync: AsyncSeriesBailHook<[
     IOperationRunnerContext & IOperationExecutionResult
     ], OperationStatus | undefined>;
-    readonly beforeExecuteOperationsAsync: AsyncSeriesBailHook<[
-    ReadonlyMap<Operation, IOperationExecutionResult>,
-    IOperationExecutionPassOptions
-    ], OperationStatus | undefined | void>;
-    readonly configureRun: SyncHook<[
+    readonly configureIteration: SyncHook<[
     ReadonlyMap<Operation, IConfigurableOperation>,
     ReadonlyMap<Operation, IOperationExecutionResult>,
-    IOperationExecutionPassOptions
+    IOperationExecutionIterationOptions
     ]>;
     readonly createEnvironmentForOperation: SyncWaterfallHook<[
     IEnvironment,
@@ -1093,8 +1093,8 @@ export class OperationExecutionHooks {
     readonly onEnableStatesChanged: SyncHook<[ReadonlySet<Operation>]>;
     readonly onExecutionStatesUpdated: SyncHook<[ReadonlySet<IOperationExecutionResult>]>;
     readonly onInvalidateOperations: SyncHook<[Iterable<Operation>, string | undefined]>;
+    readonly onIterationScheduled: SyncHook<[ReadonlyMap<Operation, IOperationExecutionResult>]>;
     readonly onManagerStateChanged: SyncHook<[IOperationExecutionManager]>;
-    readonly onPassQueued: SyncHook<[ReadonlyMap<Operation, IOperationExecutionResult>]>;
     readonly onWaitingForChanges: SyncHook<void>;
 }
 
@@ -1299,9 +1299,6 @@ 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;

libraries/rush-lib/src/api/EventHooks.ts

@@ -6,7 +6,7 @@ import { Enum } from '@rushstack/node-core-library';
 import type { IEventHooksJson } from './RushConfiguration';
 
 /**
- * Events happen during Rush runs.
+ * Events happen during Rush invocation.
  * @beta
  */
 export enum Event {

libraries/rush-lib/src/cli/scriptActions/PhasedScriptAction.ts

@@ -17,7 +17,7 @@ import type { Subspace } from '../../api/Subspace';
 import type { IPhasedCommand } from '../../pluginFramework/RushLifeCycle';
 import {
   type IOperationExecutionManagerContext,
-  type IOperationExecutionPassOptions,
+  type IOperationExecutionIterationOptions,
   PhasedCommandHooks,
   type ICreateOperationsContext
 } from '../../pluginFramework/PhasedCommandHooks';
@@ -596,7 +596,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
         destinations: [StdioWritable.instance],
         parallelism,
         isWatch,
-        runNextPassBehavior: 'automatic',
+        pauseNextIteration: false,
         getInputsSnapshotAsync,
         abortController: this.sessionAbortController,
         telemetry: executionTelemetryHandler
@@ -614,7 +614,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
 
       const abortPromise: Promise<void> = once(this.sessionAbortController.signal, 'abort').then(() => {
         terminal.writeLine(`Exiting watch mode...`);
-        return executionManager.abortCurrentPassAsync();
+        return executionManager.abortCurrentIterationAsync();
       });
 
       await measureAsyncFn(`${PERF_PREFIX}:executionManager`, async () => {
@@ -629,7 +629,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
         terminal
       };
 
-      const initialPassOptions: IOperationExecutionPassOptions = {
+      const initialIterationOptions: IOperationExecutionIterationOptions = {
         inputsSnapshot: initialSnapshot,
         // Mark as starting at time 0, which is process startup.
         startTime: 0
@@ -659,7 +659,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
         watcher.clearStatus();
 
         await measureAsyncFn(`${PERF_PREFIX}:executeOperationsInner`, async () => {
-          return await executionManager.executeAsync(initialPassOptions);
+          return await executionManager.executeAsync(initialIterationOptions);
         });
 
         await abortPromise;
@@ -668,7 +668,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
       } else {
         await measureAsyncFn(`${PERF_PREFIX}:runInitialPhases`, () =>
           measureAsyncFn(`${PERF_PREFIX}:executeOperations`, () =>
-            this._executeOperationsAsync(executeOptions, initialPassOptions)
+            this._executeOperationsAsync(executeOptions, initialIterationOptions)
           )
         );
       }
@@ -684,22 +684,22 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
    */
   private async _executeOperationsAsync(
     options: IExecuteOperationsOptions,
-    passOptions: IOperationExecutionPassOptions
+    iterationOptions: IOperationExecutionIterationOptions
   ): Promise<void> {
     const { executionManager, ignoreHooks, stopwatch, isWatch, terminal } = options;
 
     let success: boolean = false;
     let result: IExecutionResult | undefined;
 
-    if (passOptions.startTime) {
-      (stopwatch as { startTime: number }).startTime = passOptions.startTime;
+    if (iterationOptions.startTime) {
+      (stopwatch as { startTime: number }).startTime = iterationOptions.startTime;
     }
 
     try {
       const definiteResult: IExecutionResult = await measureAsyncFn(
         `${PERF_PREFIX}:executeOperationsInner`,
         async () => {
-          return await executionManager.executeAsync(passOptions);
+          return await executionManager.executeAsync(iterationOptions);
         }
       );
       success = definiteResult.status === OperationStatus.Success;

libraries/rush-lib/src/index.ts

@@ -162,13 +162,12 @@ export {
 
 export {
   type ICreateOperationsContext,
-  type IOperationExecutionPassOptions,
+  type IOperationExecutionIterationOptions,
   type IOperationExecutionManagerContext,
   type IOperationExecutionManager,
   type IPhasedCommandPlugin,
   PhasedCommandHooks,
-  OperationExecutionHooks,
-  type RunNextPassBehavior
+  OperationExecutionHooks
 } from './pluginFramework/PhasedCommandHooks';
 
 export type { IRushPlugin } from './pluginFramework/IRushPlugin';

libraries/rush-lib/src/logic/ProjectWatcher.ts

@@ -16,7 +16,7 @@ import type { RushConfiguration } from '../api/RushConfiguration';
 import type { RushConfigurationProject } from '../api/RushConfigurationProject';
 import type { IOperationExecutionManager } from '../pluginFramework/PhasedCommandHooks';
 import type { Operation } from './operations/Operation';
-import type { IOperationExecutionPassOptions } from '../pluginFramework/PhasedCommandHooks';
+import type { IOperationExecutionIterationOptions } from '../pluginFramework/PhasedCommandHooks';
 import { OperationStatus } from './operations/OperationStatus';
 
 export interface IProjectWatcherOptions {
@@ -85,15 +85,15 @@ export class ProjectWatcher {
     // Initialize stdin listener early so keybinds are available immediately
     this._ensureStdin();
 
-    // Capture snapshot (if provided) prior to executing next operations pass (will replace initial snapshot)
-    executionManager.hooks.beforeExecuteOperationsAsync.tapPromise(
+    // Capture snapshot (if provided) prior to executing next iteration (will replace initial snapshot)
+    executionManager.hooks.beforeExecuteIterationAsync.tapPromise(
       'ProjectWatcher',
       async (
         records: ReadonlyMap<Operation, unknown>,
-        passOptions: IOperationExecutionPassOptions
+        iterationOptions: IOperationExecutionIterationOptions
       ): Promise<void> => {
         this.clearStatus();
-        this._lastSnapshot = passOptions.inputsSnapshot;
+        this._lastSnapshot = iterationOptions.inputsSnapshot;
         await this._stopWatchingAsync();
       }
     );
@@ -121,19 +121,11 @@ export class ProjectWatcher {
     this._setStatus(this._lastStatus ?? 'Waiting for changes...');
   }
 
-  /**
-   * Waits for a change to the package-deps of one or more of the selected projects, since the previous invocation.
-   * Will return immediately the first time it is invoked, since no state has been recorded.
-   * If no change is currently present, watches the source tree of all selected projects for file changes.
-   * `waitForChange` is not allowed to be called multiple times concurrently.
-   */
-  // Previous waitForChangeAsync logic removed; watching is now driven by execution manager lifecycle.
-
   private _setStatus(status: string): void {
-    const isPaused: boolean = this._executionManager.runNextPassBehavior === 'manual';
-    const hasQueuedPass: boolean = this._executionManager.hasQueuedPass;
+    const isPaused: boolean = this._executionManager.pauseNextIteration === true;
+    const hasScheduledIteration: boolean = this._executionManager.hasScheduledIteration;
     const modeLabel: string = isPaused ? 'PAUSED' : 'WATCHING';
-    const pendingLabel: string = hasQueuedPass ? ' PENDING' : '';
+    const pendingLabel: string = hasScheduledIteration ? ' PENDING' : '';
     const statusLines: string[] = [`[${modeLabel}${pendingLabel}] Watch Status: ${status}`];
     if (this._stdinListening) {
       const em: IOperationExecutionManager = this._executionManager;
@@ -144,7 +136,7 @@ export class ProjectWatcher {
       );
       // Second line: keybind help kept concise to avoid overwhelming output
       lines.push(
-        ' keys(active): [q]quit [a]abort-pass [i]invalidate [x]close-runners [d]debug ' +
+        ' keys(active): [q]quit [a]abort-iteration [i]invalidate [x]close-runners [d]debug ' +
           '[v]verbose [w]pause/resume [b]build [+/-]parallelism'
       );
       statusLines.push(...lines.map((l) => `  ${l}`));
@@ -286,14 +278,14 @@ export class ProjectWatcher {
     if (this._debounceHandle) {
       clearTimeout(this._debounceHandle);
     }
-    this._debounceHandle = setTimeout(() => this._queueNextPass(), this._debounceMs);
+    this._debounceHandle = setTimeout(() => this._scheduleIteration(), this._debounceMs);
   }
 
-  private _queueNextPass(): void {
-    this._setStatus('File change detected. Queuing new pass...');
+  private _scheduleIteration(): void {
+    this._setStatus('File change detected. Queuing new iteration...');
     this._executionManager
-      .queuePassAsync({} as IOperationExecutionPassOptions)
-      .catch((e) => this._terminal.writeErrorLine(`Failed to queue pass: ${(e as Error).message}`));
+      .scheduleIterationAsync({} as IOperationExecutionIterationOptions)
+      .catch((e) => this._terminal.writeErrorLine(`Failed to queue iteration: ${(e as Error).message}`));
   }
 
   /** Setup stdin listener for interactive keybinds */
@@ -351,8 +343,8 @@ export class ProjectWatcher {
           manager.abortController.abort();
           return; // stop processing further chars
         case 'a':
-          void manager.abortCurrentPassAsync().then(() => {
-            this._setStatus('Current pass aborted');
+          void manager.abortCurrentIterationAsync().then(() => {
+            this._setStatus('Current iteration aborted');
           });
           break;
         case 'i':
@@ -373,8 +365,9 @@ export class ProjectWatcher {
           this._setStatus(`Verbose mode ${!manager.quietMode ? 'enabled' : 'disabled'}`);
           break;
         case 'w':
-          manager.runNextPassBehavior = manager.runNextPassBehavior === 'automatic' ? 'manual' : 'automatic';
-          this._setStatus(manager.runNextPassBehavior === 'manual' ? 'Watch paused' : 'Watch resumed');
+          // Toggle pauseNextIteration mode
+          manager.pauseNextIteration = !manager.pauseNextIteration;
+          this._setStatus(manager.pauseNextIteration ? 'Watch paused' : 'Watch resumed');
           break;
         case '+':
         case '=':
@@ -385,12 +378,12 @@ export class ProjectWatcher {
           break;
         case 'b':
           // Queue and (if manual) execute
-          void manager.queuePassAsync({ startTime: performance.now() }).then((queued) => {
+          void manager.scheduleIterationAsync({ startTime: performance.now() }).then((queued) => {
             if (queued) {
-              if (manager.runNextPassBehavior === 'manual') {
-                void manager.executeQueuedPassAsync();
+              if (manager.pauseNextIteration === true) {
+                void manager.executeScheduledIterationAsync();
               }
-              this._setStatus('Build pass queued');
+              this._setStatus('Build iteration queued');
             } else {
               this._setStatus('No work to queue');
             }

libraries/rush-lib/src/logic/operations/BuildPlanPlugin.ts

@@ -6,7 +6,7 @@ import type { ITerminal } from '@rushstack/terminal';
 import type {
   IOperationExecutionManager,
   IOperationExecutionManagerContext,
-  IOperationExecutionPassOptions,
+  IOperationExecutionIterationOptions,
   IPhasedCommandPlugin,
   PhasedCommandHooks
 } from '../../pluginFramework/PhasedCommandHooks';
@@ -47,18 +47,18 @@ export class BuildPlanPlugin implements IPhasedCommandPlugin {
     hooks.executionManagerAsync.tap(
       PLUGIN_NAME,
       (manager: IOperationExecutionManager, context: IOperationExecutionManagerContext) => {
-        manager.hooks.configureRun.tap(PLUGIN_NAME, (currentStates, lastStates, passOptions) => {
-          createBuildPlan(currentStates, passOptions, context);
+        manager.hooks.configureIteration.tap(PLUGIN_NAME, (currentStates, lastStates, iterationOptions) => {
+          createBuildPlan(currentStates, iterationOptions, context);
         });
       }
     );
 
     function createBuildPlan(
       recordByOperation: ReadonlyMap<Operation, IConfigurableOperation>,
-      passOptions: IOperationExecutionPassOptions,
+      iterationOptions: IOperationExecutionIterationOptions,
       context: IOperationExecutionManagerContext
     ): void {
-      const { inputsSnapshot } = passOptions;
+      const { inputsSnapshot } = iterationOptions;
       const { projectConfigurations } = context;
       const disjointSet: DisjointSet<Operation> = new DisjointSet<Operation>();
       const operations: Operation[] = [...recordByOperation.keys()];