[heft] (BREAKING CHANGE) Revert task/phase start/finish hooks to be synchronous

apps/heft/src/cli/HeftActionRunner.ts

@@ -387,32 +387,32 @@ export class HeftActionRunner {
           parallelism: this._parallelism,
           abortSignal,
           requestRun,
-          beforeExecuteOperationAsync: async (
+          beforeExecuteOperation(
             operation: Operation<IHeftTaskOperationMetadata, IHeftPhaseOperationMetadata>
-          ) => {
+          ): void {
             if (taskStart.isUsed()) {
-              await taskStart.promise({ operation });
+              taskStart.call({ operation });
             }
           },
-          afterExecuteOperationAsync: async (
+          afterExecuteOperation(
             operation: Operation<IHeftTaskOperationMetadata, IHeftPhaseOperationMetadata>
-          ) => {
+          ): void {
             if (taskFinish.isUsed()) {
-              await taskFinish.promise({ operation });
+              taskFinish.call({ operation });
             }
           },
-          beforeExecuteOperationGroupAsync: async (
+          beforeExecuteOperationGroup(
             operationGroup: OperationGroupRecord<IHeftPhaseOperationMetadata>
-          ) => {
+          ): void {
             if (operationGroup.metadata.phase && phaseStart.isUsed()) {
-              await phaseStart.promise({ operation: operationGroup });
+              phaseStart.call({ operation: operationGroup });
             }
           },
-          afterExecuteOperationGroupAsync: async (
+          afterExecuteOperationGroup(
             operationGroup: OperationGroupRecord<IHeftPhaseOperationMetadata>
-          ) => {
+          ): void {
             if (operationGroup.metadata.phase && phaseFinish.isUsed()) {
-              await phaseFinish.promise({ operation: operationGroup });
+              phaseFinish.call({ operation: operationGroup });
             }
           }
         };

apps/heft/src/pluginFramework/HeftLifecycle.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { AsyncParallelHook } from 'tapable';
+import { AsyncParallelHook, SyncHook } from 'tapable';
 import { InternalError } from '@rushstack/node-core-library';
 
 import { HeftPluginConfiguration } from '../configuration/HeftPluginConfiguration';
@@ -72,10 +72,10 @@ export class HeftLifecycle extends HeftPluginHost {
       toolStart: new AsyncParallelHook<IHeftLifecycleToolStartHookOptions>(),
       toolFinish: new AsyncParallelHook<IHeftLifecycleToolFinishHookOptions>(),
       recordMetrics: internalHeftSession.metricsCollector.recordMetricsHook,
-      taskStart: new AsyncParallelHook<IHeftTaskStartHookOptions>(['task']),
-      taskFinish: new AsyncParallelHook<IHeftTaskFinishHookOptions>(['task']),
-      phaseStart: new AsyncParallelHook<IHeftPhaseStartHookOptions>(['phase']),
-      phaseFinish: new AsyncParallelHook<IHeftPhaseFinishHookOptions>(['phase'])
+      taskStart: new SyncHook<IHeftTaskStartHookOptions>(['task']),
+      taskFinish: new SyncHook<IHeftTaskFinishHookOptions>(['task']),
+      phaseStart: new SyncHook<IHeftPhaseStartHookOptions>(['phase']),
+      phaseFinish: new SyncHook<IHeftPhaseFinishHookOptions>(['phase'])
     };
   }
 

apps/heft/src/pluginFramework/HeftLifecycleSession.ts

@@ -2,7 +2,7 @@
 // See LICENSE in the project root for license information.
 
 import * as path from 'path';
-import type { AsyncParallelHook } from 'tapable';
+import type { AsyncParallelHook, SyncHook } from 'tapable';
 
 import type { IHeftRecordMetricsHookOptions, MetricsCollector } from '../metrics/MetricsCollector';
 import type { ScopedLogger, IScopedLogger } from './logging/ScopedLogger';
@@ -144,35 +144,35 @@ export interface IHeftLifecycleHooks {
 
   /**
    * 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>)`.
+   * to execute. To use it, call `taskStart.tap(<pluginName>, <callback>)`.
    *
    * @public
    */
-  taskStart: AsyncParallelHook<IHeftTaskStartHookOptions>;
+  taskStart: SyncHook<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>)`.
+   * execution. To use it, call `taskFinish.tap(<pluginName>, <callback>)`.
    *
    * @public
    */
-  taskFinish: AsyncParallelHook<IHeftTaskFinishHookOptions>;
+  taskFinish: SyncHook<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>)`.
+   * begun to execute. To use it, call `phaseStart.tap(<pluginName>, <callback>)`.
    *
    * @public
    */
-  phaseStart: AsyncParallelHook<IHeftPhaseStartHookOptions>;
+  phaseStart: SyncHook<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>)`.
+   * execution. To use it, call `phaseFinish.tap(<pluginName>, <callback>)`.
    *
    * @public
    */
-  phaseFinish: AsyncParallelHook<IHeftPhaseFinishHookOptions>;
+  phaseFinish: SyncHook<IHeftPhaseFinishHookOptions>;
 }
 
 /**

build-tests/heft-example-lifecycle-plugin/src/index.ts

@@ -15,7 +15,7 @@ export const PLUGIN_NAME: 'example-lifecycle-plugin' = 'example-lifecycle-plugin
 export default class ExampleLifecyclePlugin implements IHeftLifecyclePlugin {
   public apply(session: IHeftLifecycleSession): void {
     const { logger } = session;
-    session.hooks.taskFinish.tapPromise(PLUGIN_NAME, async (options: IHeftTaskFinishHookOptions) => {
+    session.hooks.taskFinish.tap(PLUGIN_NAME, (options: IHeftTaskFinishHookOptions) => {
       const {
         operation: {
           metadata: { task },
@@ -29,7 +29,7 @@ export default class ExampleLifecyclePlugin implements IHeftLifecyclePlugin {
       }
     });
 
-    session.hooks.taskStart.tapPromise(PLUGIN_NAME, async (options: IHeftTaskStartHookOptions) => {
+    session.hooks.taskStart.tap(PLUGIN_NAME, (options: IHeftTaskStartHookOptions) => {
       const {
         operation: {
           metadata: { task }
@@ -38,7 +38,7 @@ export default class ExampleLifecyclePlugin implements IHeftLifecyclePlugin {
       logger.terminal.writeLine(`--- ${task.taskName} started ---`);
     });
 
-    session.hooks.phaseStart.tapPromise(PLUGIN_NAME, async (options: IHeftPhaseStartHookOptions) => {
+    session.hooks.phaseStart.tap(PLUGIN_NAME, (options: IHeftPhaseStartHookOptions) => {
       const {
         operation: {
           metadata: { phase }
@@ -47,7 +47,7 @@ export default class ExampleLifecyclePlugin implements IHeftLifecyclePlugin {
       logger.terminal.writeLine(`--- ${phase.phaseName} started ---`);
     });
 
-    session.hooks.phaseFinish.tapPromise(PLUGIN_NAME, async (options: IHeftPhaseFinishHookOptions) => {
+    session.hooks.phaseFinish.tap(PLUGIN_NAME, (options: IHeftPhaseFinishHookOptions) => {
       const {
         operation: {
           metadata: { phase },

common/changes/@rushstack/heft/sync-hooks_2025-09-29-22-50.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft",
+      "comment": "(BREAKING CHANGE) Make the `taskStart`/`taskFinish`/`phaseStart`/`phaseFinish` hooks synchronous to signify that they are not intended to be used for expensive work.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft"
+}

common/changes/@rushstack/operation-graph/sync-hooks_2025-09-29-22-50.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/operation-graph",
+      "comment": "(BREAKING CHANGE) Revert the extensibility points for `(before/after)ExecuteOperation(Group)?Async` to be synchronous to signify that they are only meant for logging, not for expensive work.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/operation-graph"
+}

common/reviews/api/heft.api.md

@@ -38,6 +38,7 @@ 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';
+import type { SyncHook } from 'tapable';
 
 export { CommandLineChoiceListParameter }
 
@@ -152,11 +153,11 @@ export interface IHeftLifecycleCleanHookOptions {
 // @public
 export interface IHeftLifecycleHooks {
     clean: AsyncParallelHook<IHeftLifecycleCleanHookOptions>;
-    phaseFinish: AsyncParallelHook<IHeftPhaseFinishHookOptions>;
-    phaseStart: AsyncParallelHook<IHeftPhaseStartHookOptions>;
+    phaseFinish: SyncHook<IHeftPhaseFinishHookOptions>;
+    phaseStart: SyncHook<IHeftPhaseStartHookOptions>;
     recordMetrics: AsyncParallelHook<IHeftRecordMetricsHookOptions>;
-    taskFinish: AsyncParallelHook<IHeftTaskFinishHookOptions>;
-    taskStart: AsyncParallelHook<IHeftTaskStartHookOptions>;
+    taskFinish: SyncHook<IHeftTaskFinishHookOptions>;
+    taskStart: SyncHook<IHeftTaskStartHookOptions>;
     toolFinish: AsyncParallelHook<IHeftLifecycleToolFinishHookOptions>;
     toolStart: AsyncParallelHook<IHeftLifecycleToolStartHookOptions>;
 }

common/reviews/api/operation-graph.api.md

@@ -30,8 +30,8 @@ export interface ICancelCommandMessage {
 
 // @beta
 export interface IExecuteOperationContext extends Omit<IOperationRunnerContext, 'isFirstRun' | 'requestRun'> {
-    afterExecuteAsync(operation: Operation, state: IOperationState): Promise<void>;
-    beforeExecuteAsync(operation: Operation, state: IOperationState): Promise<void>;
+    afterExecute(operation: Operation, state: IOperationState): void;
+    beforeExecute(operation: Operation, state: IOperationState): void;
     queueWork(workFn: () => Promise<OperationStatus>, priority: number): Promise<OperationStatus>;
     requestRun?: OperationRequestRunCallback;
     terminal: ITerminal;
@@ -48,13 +48,13 @@ export interface IOperationExecutionOptions<TOperationMetadata extends {} = {},
     // (undocumented)
     abortSignal: AbortSignal;
     // (undocumented)
-    afterExecuteOperationAsync?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => Promise<void>;
+    afterExecuteOperation?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => void;
     // (undocumented)
-    afterExecuteOperationGroupAsync?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => Promise<void>;
+    afterExecuteOperationGroup?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => void;
     // (undocumented)
-    beforeExecuteOperationAsync?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => Promise<void>;
+    beforeExecuteOperation?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => void;
     // (undocumented)
-    beforeExecuteOperationGroupAsync?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => Promise<void>;
+    beforeExecuteOperationGroup?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => void;
     // (undocumented)
     parallelism: number;
     // (undocumented)

libraries/operation-graph/src/Operation.ts

@@ -62,12 +62,12 @@ export interface IExecuteOperationContext extends Omit<IOperationRunnerContext,
   /**
    * Function to invoke before execution of an operation, for logging.
    */
-  beforeExecuteAsync(operation: Operation, state: IOperationState): Promise<void>;
+  beforeExecute(operation: Operation, state: IOperationState): void;
 
   /**
    * Function to invoke after execution of an operation, for logging.
    */
-  afterExecuteAsync(operation: Operation, state: IOperationState): Promise<void>;
+  afterExecute(operation: Operation, state: IOperationState): void;
 
   /**
    * Function used to schedule the concurrency-limited execution of an operation.
@@ -328,7 +328,7 @@ export class Operation<TMetadata extends {} = {}, TGroupMetadata extends {} = {}
         return innerState.status;
       }
 
-      await context.beforeExecuteAsync(this, innerState);
+      context.beforeExecute(this, innerState);
 
       innerState.stopwatch.start();
       innerState.status = OperationStatus.Executing;
@@ -365,7 +365,7 @@ export class Operation<TMetadata extends {} = {}, TGroupMetadata extends {} = {}
       }
 
       state.stopwatch.stop();
-      await context.afterExecuteAsync(this, state);
+      context.afterExecute(this, state);
 
       return state.status;
     }, /* priority */ this.criticalPathLength ?? 0);

libraries/operation-graph/src/OperationExecutionManager.ts

@@ -26,10 +26,10 @@ export interface IOperationExecutionOptions<
 
   requestRun?: OperationRequestRunCallback;
 
-  beforeExecuteOperationAsync?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => Promise<void>;
-  afterExecuteOperationAsync?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => Promise<void>;
-  beforeExecuteOperationGroupAsync?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => Promise<void>;
-  afterExecuteOperationGroupAsync?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => Promise<void>;
+  beforeExecuteOperation?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => void;
+  afterExecuteOperation?: (operation: Operation<TOperationMetadata, TGroupMetadata>) => void;
+  beforeExecuteOperationGroup?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => void;
+  afterExecuteOperationGroup?: (operationGroup: OperationGroupRecord<TGroupMetadata>) => void;
 }
 
 /**
@@ -126,28 +126,26 @@ export class OperationExecutionManager<TOperationMetadata extends {} = {}, TGrou
           return workQueue.pushAsync(workFn, priority);
         },
 
-        beforeExecuteAsync: async (
-          operation: Operation<TOperationMetadata, TGroupMetadata>
-        ): Promise<void> => {
+        beforeExecute: (operation: Operation<TOperationMetadata, TGroupMetadata>): void => {
           // Initialize group if uninitialized and log the group name
           const { group, runner } = operation;
           if (group) {
             if (!startedGroups.has(group)) {
               startedGroups.add(group);
               group.startTimer();
               terminal.writeLine(` ---- ${group.name} started ---- `);
-              await executionOptions.beforeExecuteOperationGroupAsync?.(group);
+              executionOptions.beforeExecuteOperationGroup?.(group);
             }
           }
           if (!runner?.silent) {
-            await executionOptions.beforeExecuteOperationAsync?.(operation);
+            executionOptions.beforeExecuteOperation?.(operation);
           }
         },
 
-        afterExecuteAsync: async (
+        afterExecute: (
           operation: Operation<TOperationMetadata, TGroupMetadata>,
           state: IOperationState
-        ): Promise<void> => {
+        ): void => {
           const { group, runner } = operation;
           if (group) {
             group.setOperationAsComplete(operation, state);
@@ -165,7 +163,7 @@ export class OperationExecutionManager<TOperationMetadata extends {} = {}, TGrou
           }
 
           if (!runner?.silent) {
-            await executionOptions.afterExecuteOperationAsync?.(operation);
+            executionOptions.afterExecuteOperation?.(operation);
           }
 
           if (group) {
@@ -180,7 +178,7 @@ export class OperationExecutionManager<TOperationMetadata extends {} = {}, TGrou
               terminal.writeLine(
                 ` ---- ${group.name} ${finishedLoggingWord} (${group.duration.toFixed(3)}s) ---- `
               );
-              await executionOptions.afterExecuteOperationGroupAsync?.(group);
+              executionOptions.afterExecuteOperationGroup?.(group);
             }
           }
         }