[rush] (BREAKING CHANGE) Overhaul watch-mode to facilitate orchestration

apps/rush/package.json

@@ -48,6 +48,7 @@
     "@rushstack/rush-amazon-s3-build-cache-plugin": "workspace:*",
     "@rushstack/rush-azure-storage-build-cache-plugin": "workspace:*",
     "@rushstack/rush-http-build-cache-plugin": "workspace:*",
+    "@rushstack/rush-serve-plugin": "workspace:*",
     "@types/heft-jest": "1.0.1",
     "@types/semver": "7.5.0"
   }

apps/rush/src/start-dev.ts

@@ -29,6 +29,7 @@ function includePlugin(pluginName: string, pluginPackageName?: string): void {
 includePlugin('rush-amazon-s3-build-cache-plugin');
 includePlugin('rush-azure-storage-build-cache-plugin');
 includePlugin('rush-http-build-cache-plugin');
+includePlugin('rush-serve-plugin');
 // Including this here so that developers can reuse it without installing the plugin a second time
 includePlugin('rush-azure-interactive-auth-plugin', '@rushstack/rush-azure-storage-build-cache-plugin');
 

common/changes/@microsoft/rush/watch-rework_2025-09-26-23-50.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "(PLUGIN BREAKING CHANGE) Overhaul watch-mode commands such that the graph is only created once at the start of command invocation, along with a stateful manager object. Plugins may now access the manager object and use it to orchestrate and tap into the build process.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/config/rush-plugins/rush-serve-plugin.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush-serve-plugin-options.schema.json",
+  "phasedCommands": ["start"],
+  "portParameterLongName": "--port",
+  "globalRouting": [
+    {
+      "workspaceRelativeFile": "rush-plugins/rush-serve-plugin/dashboard.html",
+      "servePath": "/"
+    }
+  ],
+  "buildStatusWebSocketPath": "/ws",
+  "logServePath": "/logs"
+}

common/config/rush/command-line.json

@@ -237,24 +237,25 @@
       // Used for very simple builds that don't support CLI arguments like `--production` or `--fix`
       "name": "_phase:lite-build",
       "dependencies": {
-        "upstream": ["_phase:lite-build", "_phase:build"]
+        "upstream": ["_phase:build"]
       },
       "missingScriptBehavior": "silent",
       "allowWarningsOnSuccess": false
     },
     {
       "name": "_phase:build",
       "dependencies": {
-        "self": ["_phase:lite-build"],
-        "upstream": ["_phase:build"]
+        // Don't need to declare the dependency on _phase:build because it is transitive via _phase:lite-build
+        "self": ["_phase:lite-build"]
       },
       "missingScriptBehavior": "log",
       "allowWarningsOnSuccess": false
     },
     {
       "name": "_phase:test",
       "dependencies": {
-        "self": ["_phase:lite-build", "_phase:build"]
+        // Dependency on _phase:lite-build is transitive via _phase:build
+        "self": ["_phase:build"]
       },
       "missingScriptBehavior": "silent",
       "allowWarningsOnSuccess": false
@@ -486,6 +487,14 @@
       "associatedPhases": ["_phase:build", "_phase:test"],
       "associatedCommands": ["build", "rebuild", "test", "retest"]
     },
+    {
+      "longName": "--port",
+      "parameterKind": "integer",
+      "argumentName": "PORT",
+      "description": "The port to use for the server",
+      "associatedPhases": [],
+      "associatedCommands": ["start"]
+    },
     {
       "longName": "--update-snapshots",
       "parameterKind": "flag",

common/config/rush/experiments.json

@@ -76,7 +76,7 @@
    * Enable this experiment if you want "rush" and "rushx" commands to resync injected dependencies
    * by invoking "pnpm-sync" during the build.
    */
-  "usePnpmSyncForInjectedDependencies": true
+  "usePnpmSyncForInjectedDependencies": true,
 
   /**
    * If set to true, Rush will generate a `project-impact-graph.yaml` file in the repository root during `rush update`.
@@ -88,7 +88,7 @@
    * of `_phase:<name>` if they exist. The created child process will be provided with an IPC channel and expected to persist
    * across invocations.
    */
-  // "useIPCScriptsInWatchMode": true,
+  "useIPCScriptsInWatchMode": true
 
   /**
    * (UNDER DEVELOPMENT) The Rush alerts feature provides a way to send announcements to engineers

common/config/rush/nonbrowser-approved-packages.json

@@ -306,6 +306,10 @@
       "name": "@rushstack/rush-sdk",
       "allowedCategories": [ "libraries", "tests", "vscode-extensions" ]
     },
+    {
+      "name": "@rushstack/rush-serve-plugin",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "@rushstack/set-webpack-public-path-plugin",
       "allowedCategories": [ "libraries", "tests" ]

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

@@ -29,6 +29,7 @@ import type { StdioSummarizer } from '@rushstack/terminal';
 import { SyncHook } from 'tapable';
 import { SyncWaterfallHook } from 'tapable';
 import { Terminal } from '@rushstack/terminal';
+import type { TerminalWritable } from '@rushstack/terminal';
 
 // @public
 export class ApprovedPackagesConfiguration {
@@ -342,6 +343,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 +411,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 +433,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 +487,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,21 +619,52 @@ export interface _IOperationBuildCacheOptions {
 }
 
 // @alpha
-export interface IOperationExecutionResult {
+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;
     readonly stdioSummarizer: StdioSummarizer;
     readonly stopwatch: IStopwatchResult;
 }
 
+// @alpha
+export interface IOperationGraph {
+    readonly abortController: AbortController;
+    abortCurrentIterationAsync(): Promise<void>;
+    addTerminalDestination(destination: TerminalWritable): void;
+    closeRunnersAsync(operations?: Iterable<Operation>): Promise<void>;
+    debugMode: boolean;
+    executeScheduledIterationAsync(): Promise<boolean>;
+    readonly hasScheduledIteration: boolean;
+    readonly hooks: OperationGraphHooks;
+    invalidateOperations(operations?: Iterable<Operation>, reason?: string): void;
+    readonly lastExecutionResults: ReadonlyMap<Operation, IOperationExecutionResult>;
+    readonly operations: ReadonlySet<Operation>;
+    parallelism: number;
+    pauseNextIteration: boolean;
+    quietMode: boolean;
+    removeTerminalDestination(destination: TerminalWritable, close?: boolean): boolean;
+    scheduleIterationAsync(options: IOperationGraphIterationOptions): Promise<boolean>;
+    setEnabledStates(operations: Iterable<Operation>, targetState: Operation['enabled'], mode: 'safe' | 'unsafe'): boolean;
+    readonly status: OperationStatus;
+}
+
+// @alpha
+export interface IOperationGraphContext extends ICreateOperationsContext {
+    readonly initialSnapshot?: IInputsSnapshot;
+}
+
+// @alpha
+export interface IOperationGraphIterationOptions {
+    // (undocumented)
+    inputsSnapshot?: IInputsSnapshot;
+    startTime?: number;
+}
+
 // @internal (undocumented)
 export interface _IOperationMetadata {
     // (undocumented)
@@ -653,6 +689,7 @@ export interface _IOperationMetadataManagerOptions {
 
 // @alpha
 export interface IOperationOptions {
+    enabled?: OperationEnabledState;
     logFilenameIdentifier: string;
     phase: IPhase;
     project: RushConfigurationProject;
@@ -663,8 +700,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 +790,11 @@ export interface IPhasedCommand extends IRushCommand {
     readonly sessionAbortController: AbortController;
 }
 
+// @alpha
+export interface IPhasedCommandPlugin {
+    apply(hooks: PhasedCommandHooks): void;
+}
+
 // @public
 export interface IPnpmLockfilePolicies {
     disallowInsecureSha1?: {
@@ -998,7 +1042,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;
@@ -1012,7 +1056,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)
@@ -1021,6 +1065,43 @@ export class _OperationBuildCache {
     trySetCacheEntryAsync(terminal: ITerminal, specifiedCacheId?: string): Promise<boolean>;
 }
 
+// @alpha
+export type OperationEnabledState = boolean | 'ignore-dependency-changes';
+
+// @alpha
+export class OperationGraphHooks {
+    readonly afterExecuteIterationAsync: AsyncSeriesWaterfallHook<[
+    OperationStatus,
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationGraphIterationOptions
+    ]>;
+    readonly afterExecuteOperationAsync: AsyncSeriesHook<[
+    IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+    readonly beforeExecuteIterationAsync: AsyncSeriesBailHook<[
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationGraphIterationOptions
+    ], OperationStatus | undefined | void>;
+    readonly beforeExecuteOperationAsync: AsyncSeriesBailHook<[
+    IOperationRunnerContext & IOperationExecutionResult
+    ], OperationStatus | undefined>;
+    readonly configureIteration: SyncHook<[
+    ReadonlyMap<Operation, IConfigurableOperation>,
+    ReadonlyMap<Operation, IOperationExecutionResult>,
+    IOperationGraphIterationOptions
+    ]>;
+    readonly createEnvironmentForOperation: SyncWaterfallHook<[
+    IEnvironment,
+    IOperationRunnerContext & IOperationExecutionResult
+    ]>;
+    readonly onEnableStatesChanged: SyncHook<[ReadonlySet<Operation>]>;
+    readonly onExecutionStatesUpdated: SyncHook<[ReadonlySet<IOperationExecutionResult>]>;
+    readonly onGraphStateChanged: SyncHook<[IOperationGraph]>;
+    readonly onInvalidateOperations: SyncHook<[Iterable<Operation>, string | undefined]>;
+    readonly onIterationScheduled: SyncHook<[ReadonlyMap<Operation, IOperationExecutionResult>]>;
+    readonly onWaitingForChanges: SyncHook<void>;
+}
+
 // @internal
 export class _OperationMetadataManager {
     constructor(options: _IOperationMetadataManagerOptions);
@@ -1150,26 +1231,12 @@ 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 createOperations: AsyncSeriesWaterfallHook<[Set<Operation>, ICreateOperationsContext]>;
-    readonly onOperationStatusChanged: SyncHook<[IOperationExecutionResult]>;
-    readonly shutdownAsync: AsyncParallelHook<void>;
-    readonly waitingForChanges: SyncHook<void>;
+    readonly onGraphCreatedAsync: AsyncSeriesHook<[IOperationGraph, IOperationGraphContext]>;
 }
 
 // @public