[rush] Add --node-diagnostic-dir parameter

Author: dmichon-msft

common/changes/@microsoft/rush/cpu-profiler-plugin_2025-02-07-01-10.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Add a new command line parameter `--node-diagnostic-dir=DIR` to phased commands that, when specified, tells all child build processes to write NodeJS diagnostics into `${DIR}/${packageName}/${phaseIdentifier}`. This is useful if `--cpu-prof` or `--heap-prof` are enabled, to avoid polluting workspace folders.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

libraries/rush-lib/src/api/test/__snapshots__/RushCommandLine.test.ts.snap

@@ -1244,6 +1244,14 @@ Object {
           "required": false,
           "shortName": undefined,
         },
+        Object {
+          "description": "Specifies the directory where Node.js diagnostic reports will be written. This directory will contain a subdirectory for each project and phase.",
+          "environmentVariable": undefined,
+          "kind": "String",
+          "longName": "--node-diagnostic-dir",
+          "required": false,
+          "shortName": undefined,
+        },
         Object {
           "description": "Selects a single instead of the default locale (en-us) for non-ship builds or all locales for ship builds.",
           "environmentVariable": undefined,
@@ -1382,6 +1390,14 @@ Object {
           "required": false,
           "shortName": undefined,
         },
+        Object {
+          "description": "Specifies the directory where Node.js diagnostic reports will be written. This directory will contain a subdirectory for each project and phase.",
+          "environmentVariable": undefined,
+          "kind": "String",
+          "longName": "--node-diagnostic-dir",
+          "required": false,
+          "shortName": undefined,
+        },
         Object {
           "description": "Perform a production build, including minification and localization steps",
           "environmentVariable": undefined,
@@ -1507,6 +1523,14 @@ Object {
           "required": false,
           "shortName": undefined,
         },
+        Object {
+          "description": "Specifies the directory where Node.js diagnostic reports will be written. This directory will contain a subdirectory for each project and phase.",
+          "environmentVariable": undefined,
+          "kind": "String",
+          "longName": "--node-diagnostic-dir",
+          "required": false,
+          "shortName": undefined,
+        },
         Object {
           "description": "Perform a production build, including minification and localization steps",
           "environmentVariable": undefined,

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

@@ -57,6 +57,7 @@ import { FlagFile } from '../../api/FlagFile';
 import { WeightedOperationPlugin } from '../../logic/operations/WeightedOperationPlugin';
 import { getVariantAsync, VARIANT_PARAMETER } from '../../api/Variants';
 import { Selection } from '../../logic/Selection';
+import { NodeDiagnosticDirPlugin } from '../../logic/operations/NodeDiagnosticDirPlugin';
 
 /**
  * Constructor parameters for PhasedScriptAction.
@@ -153,6 +154,7 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> {
   private readonly _installParameter: CommandLineFlagParameter | undefined;
   private readonly _variantParameter: CommandLineStringParameter | undefined;
   private readonly _noIPCParameter: CommandLineFlagParameter | undefined;
+  private readonly _nodeDiagnosticDirParameter: CommandLineStringParameter;
 
   public constructor(options: IPhasedScriptActionOptions) {
     super(options);
@@ -284,6 +286,14 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> {
       });
     }
 
+    this._nodeDiagnosticDirParameter = this.defineStringParameter({
+      parameterLongName: '--node-diagnostic-dir',
+      argumentName: 'DIRECTORY',
+      description:
+        'Specifies the directory where Node.js diagnostic reports will be written. ' +
+        'This directory will contain a subdirectory for each project and phase.'
+    });
+
     this.defineScriptParameters();
 
     for (const [{ associatedPhases }, tsCommandLineParameter] of this.customParameters) {
@@ -366,6 +376,13 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> {
       new ConsoleTimelinePlugin(terminal).apply(this.hooks);
     }
 
+    const diagnosticDir: string | undefined = this._nodeDiagnosticDirParameter.value;
+    if (diagnosticDir) {
+      new NodeDiagnosticDirPlugin({
+        diagnosticDir
+      }).apply(this.hooks);
+    }
+
     // Enable the standard summary
     new OperationResultSummarizerPlugin(terminal).apply(this.hooks);
 

libraries/rush-lib/src/cli/test/__snapshots__/CommandLineHelp.test.ts.snap

@@ -155,7 +155,7 @@ exports[`CommandLineHelp prints the help for each action: build 1`] = `
                   [-i PROJECT] [-I PROJECT]
                   [--to-version-policy VERSION_POLICY_NAME]
                   [--from-version-policy VERSION_POLICY_NAME] [-v] [-c]
-                  [--ignore-hooks] [-s] [-m]
+                  [--ignore-hooks] [--node-diagnostic-dir DIRECTORY] [-s] [-m]
                   
 
 This command is similar to \\"rush rebuild\\", except that \\"rush build\\" performs 
@@ -281,6 +281,10 @@ Optional arguments:
   --ignore-hooks        Skips execution of the \\"eventHooks\\" scripts defined 
                         in rush.json. Make sure you know what you are 
                         skipping.
+  --node-diagnostic-dir DIRECTORY
+                        Specifies the directory where Node.js diagnostic 
+                        reports will be written. This directory will contain 
+                        a subdirectory for each project and phase.
   -s, --ship            Perform a production build, including minification 
                         and localization steps
   -m, --minimal         Perform a fast build, which disables certain tasks 
@@ -432,7 +436,7 @@ exports[`CommandLineHelp prints the help for each action: import-strings 1`] = `
                            [-i PROJECT] [-I PROJECT]
                            [--to-version-policy VERSION_POLICY_NAME]
                            [--from-version-policy VERSION_POLICY_NAME] [-v]
-                           [--ignore-hooks]
+                           [--ignore-hooks] [--node-diagnostic-dir DIRECTORY]
                            [--locale {en-us,fr-fr,es-es,zh-cn}]
                            
 
@@ -541,6 +545,10 @@ Optional arguments:
   --ignore-hooks        Skips execution of the \\"eventHooks\\" scripts defined 
                         in rush.json. Make sure you know what you are 
                         skipping.
+  --node-diagnostic-dir DIRECTORY
+                        Specifies the directory where Node.js diagnostic 
+                        reports will be written. This directory will contain 
+                        a subdirectory for each project and phase.
   --locale {en-us,fr-fr,es-es,zh-cn}
                         Selects a single instead of the default locale 
                         (en-us) for non-ship builds or all locales for ship 
@@ -1030,7 +1038,8 @@ exports[`CommandLineHelp prints the help for each action: rebuild 1`] = `
                     [-i PROJECT] [-I PROJECT]
                     [--to-version-policy VERSION_POLICY_NAME]
                     [--from-version-policy VERSION_POLICY_NAME] [-v]
-                    [--ignore-hooks] [-s] [-m]
+                    [--ignore-hooks] [--node-diagnostic-dir DIRECTORY] [-s]
+                    [-m]
                     
 
 This command assumes that the package.json file for each project contains a 
@@ -1144,6 +1153,10 @@ Optional arguments:
   --ignore-hooks        Skips execution of the \\"eventHooks\\" scripts defined 
                         in rush.json. Make sure you know what you are 
                         skipping.
+  --node-diagnostic-dir DIRECTORY
+                        Specifies the directory where Node.js diagnostic 
+                        reports will be written. This directory will contain 
+                        a subdirectory for each project and phase.
   -s, --ship            Perform a production build, including minification 
                         and localization steps
   -m, --minimal         Perform a fast build, which disables certain tasks 

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

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import path from 'path';
+
+import { FileSystem } from '@rushstack/node-core-library';
+
+import type { IPhasedCommandPlugin, PhasedCommandHooks } from '../../pluginFramework/PhasedCommandHooks';
+import type { IEnvironment } from '../../utilities/Utilities';
+import type { Operation } from './Operation';
+import type { IOperationRunnerContext } from './IOperationRunner';
+import type { IOperationExecutionResult } from './IOperationExecutionResult';
+
+const PLUGIN_NAME: 'NodeDiagnosticDirPlugin' = 'NodeDiagnosticDirPlugin';
+
+export interface INodeDiagnosticDirPluginOptions {
+  diagnosticDir: string;
+}
+
+/**
+ * Phased command plugin that configures the NodeJS --diagnostic-dir option to contain the project and phase name.
+ */
+export class NodeDiagnosticDirPlugin implements IPhasedCommandPlugin {
+  private readonly _diagnosticsDir: string;
+
+  public constructor(options: INodeDiagnosticDirPluginOptions) {
+    this._diagnosticsDir = options.diagnosticDir;
+  }
+
+  public apply(hooks: PhasedCommandHooks): void {
+    const getDiagnosticDir = (operation: Operation): string | undefined => {
+      const { associatedProject } = operation;
+
+      if (!associatedProject) {
+        return;
+      }
+
+      const diagnosticDir: string = path.resolve(
+        this._diagnosticsDir,
+        associatedProject.packageName,
+        operation.logFilenameIdentifier
+      );
+
+      return diagnosticDir;
+    };
+
+    hooks.beforeExecuteOperation.tap(
+      PLUGIN_NAME,
+      (operation: IOperationRunnerContext & IOperationExecutionResult): undefined => {
+        const diagnosticDir: string | undefined = getDiagnosticDir(operation.operation);
+        if (!diagnosticDir) {
+          return;
+        }
+
+        // Not all versions of NodeJS create the directory, so ensure it exists:
+        FileSystem.ensureFolder(diagnosticDir);
+      }
+    );
+
+    hooks.createEnvironmentForOperation.tap(PLUGIN_NAME, (env: IEnvironment, operation: Operation) => {
+      const diagnosticDir: string | undefined = getDiagnosticDir(operation);
+      if (!diagnosticDir) {
+        return env;
+      }
+
+      const { NODE_OPTIONS } = env;
+
+      const diagnosticDirEnv: string = `--diagnostic-dir="${diagnosticDir}"`;
+
+      env.NODE_OPTIONS = NODE_OPTIONS ? `${NODE_OPTIONS} ${diagnosticDirEnv}` : diagnosticDirEnv;
+
+      return env;
+    });
+  }
+}