Add parameter ignoring feature to rush-lib

Co-authored-by: dmichon-msft <26827560+dmichon-msft@users.noreply.github.com>

Author: Copilot

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

@@ -670,6 +670,7 @@ export interface IOperationSettings {
     ignoreChangedProjectsOnlyFlag?: boolean;
     operationName: string;
     outputFolderNames?: string[];
+    parameterNamesToIgnore?: string[];
     sharding?: IRushPhaseSharding;
     weight?: number;
 }

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

@@ -146,6 +146,14 @@ export interface IOperationSettings {
    * If true, this operation will never be skipped by the `--changed-projects-only` flag.
    */
   ignoreChangedProjectsOnlyFlag?: boolean;
+
+  /**
+   * An optional list of custom command-line parameter names (their `parameterLongName` values from
+   * command-line.json) that should be ignored when invoking the command for this operation.
+   * This allows a project to opt out of parameters that don't affect its operation, preventing
+   * unnecessary cache invalidation for this operation and its consumers.
+   */
+  parameterNamesToIgnore?: string[];
 }
 
 interface IOldRushProjectJson {

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

@@ -30,6 +30,7 @@ export interface IIPCOperationRunnerOptions {
   commandForHash: string;
   persist: boolean;
   requestRun: OperationRequestRunCallback;
+  ignoredParameterNames: ReadonlyArray<string>;
 }
 
 function isAfterExecuteEventMessage(message: unknown): message is IAfterExecuteEventMessage {
@@ -59,6 +60,7 @@ export class IPCOperationRunner implements IOperationRunner {
   private readonly _commandForHash: string;
   private readonly _persist: boolean;
   private readonly _requestRun: OperationRequestRunCallback;
+  private readonly _ignoredParameterNames: ReadonlyArray<string>;
 
   private _ipcProcess: ChildProcess | undefined;
   private _processReadyPromise: Promise<void> | undefined;
@@ -75,6 +77,7 @@ export class IPCOperationRunner implements IOperationRunner {
 
     this._persist = options.persist;
     this._requestRun = options.requestRun;
+    this._ignoredParameterNames = options.ignoredParameterNames;
   }
 
   public async executeAsync(context: IOperationRunnerContext): Promise<OperationStatus> {
@@ -85,6 +88,11 @@ export class IPCOperationRunner implements IOperationRunner {
           // Run the operation
           terminal.writeLine('Invoking: ' + this._commandToRun);
 
+          // Log any ignored parameters in verbose mode
+          if (this._ignoredParameterNames.length > 0) {
+            terminal.writeVerboseLine(`Ignored parameters: ${this._ignoredParameterNames.join(', ')}`);
+          }
+
           const { rushConfiguration, projectFolder } = this._rushProject;
 
           const { environment: initialEnvironment } = context;

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

@@ -1,7 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import type { IPhase } from '../../api/CommandLineConfiguration';
 import type {
   ICreateOperationsContext,
   IPhasedCommandPlugin,
@@ -14,7 +13,8 @@ import { OperationStatus } from './OperationStatus';
 import {
   PLUGIN_NAME as ShellOperationPluginName,
   formatCommand,
-  getCustomParameterValuesByPhase,
+  getCustomParameterValuesForOperation,
+  type ICustomParameterValuesForOperation,
   getDisplayName
 } from './ShellOperationRunnerPlugin';
 
@@ -45,8 +45,8 @@ export class IPCOperationRunnerPlugin implements IPhasedCommandPlugin {
 
         currentContext = context;
 
-        const getCustomParameterValuesForPhase: (phase: IPhase) => ReadonlyArray<string> =
-          getCustomParameterValuesByPhase();
+        const getCustomParameterValues: (operation: Operation) => ICustomParameterValuesForOperation =
+          getCustomParameterValuesForOperation();
 
         for (const operation of operations) {
           const { associatedPhase: phase, associatedProject: project, runner } = operation;
@@ -73,7 +73,8 @@ export class IPCOperationRunnerPlugin implements IPhasedCommandPlugin {
           // for this operation (or downstream operations) to be restored from the build cache.
           const commandForHash: string | undefined = phase.shellCommand ?? scripts?.[phaseName];
 
-          const customParameterValues: ReadonlyArray<string> = getCustomParameterValuesForPhase(phase);
+          const { parameterValues: customParameterValues, ignoredParameterNames } =
+            getCustomParameterValues(operation);
           const commandToRun: string = formatCommand(rawScript, customParameterValues);
 
           const operationName: string = getDisplayName(phase, project);
@@ -86,6 +87,7 @@ export class IPCOperationRunnerPlugin implements IPhasedCommandPlugin {
               commandToRun,
               commandForHash,
               persist: true,
+              ignoredParameterNames,
               requestRun: (requestor: string, detail?: string) => {
                 const operationState: IOperationExecutionResult | undefined =
                   operationStatesByRunner.get(ipcOperationRunner);

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

@@ -137,7 +137,8 @@ function spliceShards(existingOperations: Set<Operation>, context: ICreateOperat
         displayName: collatorDisplayName,
         rushConfiguration,
         commandToRun,
-        customParameterValues: collatorParameters
+        customParameterValues: collatorParameters,
+        ignoredParameterNames: []
       });
 
       const shardOperationName: string = `${phase.name}:shard`;
@@ -207,7 +208,8 @@ function spliceShards(existingOperations: Set<Operation>, context: ICreateOperat
           commandToRun: baseCommand,
           customParameterValues: shardedParameters,
           displayName: shardDisplayName,
-          rushConfiguration
+          rushConfiguration,
+          ignoredParameterNames: []
         });
 
         shardOperation.addDependency(preShardOperation);

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

@@ -20,6 +20,7 @@ export interface IShellOperationRunnerOptions {
   displayName: string;
   commandToRun: string;
   commandForHash: string;
+  ignoredParameterNames: ReadonlyArray<string>;
 }
 
 /**
@@ -44,6 +45,8 @@ export class ShellOperationRunner implements IOperationRunner {
 
   private readonly _rushProject: RushConfigurationProject;
 
+  private readonly _ignoredParameterNames: ReadonlyArray<string>;
+
   public constructor(options: IShellOperationRunnerOptions) {
     const { phase } = options;
 
@@ -53,6 +56,7 @@ export class ShellOperationRunner implements IOperationRunner {
     this._rushProject = options.rushProject;
     this.commandToRun = options.commandToRun;
     this._commandForHash = options.commandForHash;
+    this._ignoredParameterNames = options.ignoredParameterNames;
   }
 
   public async executeAsync(context: IOperationRunnerContext): Promise<OperationStatus> {
@@ -75,6 +79,11 @@ export class ShellOperationRunner implements IOperationRunner {
         // Run the operation
         terminal.writeLine(`Invoking: ${this.commandToRun}`);
 
+        // Log any ignored parameters in verbose mode
+        if (this._ignoredParameterNames.length > 0) {
+          terminal.writeVerboseLine(`Ignored parameters: ${this._ignoredParameterNames.join(', ')}`);
+        }
+
         const { rushConfiguration, projectFolder } = this._rushProject;
 
         const { environment: initialEnvironment } = context;

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

@@ -31,15 +31,17 @@ export class ShellOperationRunnerPlugin implements IPhasedCommandPlugin {
       ): Set<Operation> {
         const { rushConfiguration, isInitial } = context;
 
-        const getCustomParameterValuesForPhase: (phase: IPhase) => ReadonlyArray<string> =
-          getCustomParameterValuesByPhase();
+        const getCustomParameterValues: (operation: Operation) => ICustomParameterValuesForOperation =
+          getCustomParameterValuesForOperation();
+
         for (const operation of operations) {
           const { associatedPhase: phase, associatedProject: project } = operation;
 
           if (!operation.runner) {
             // This is a shell command. In the future, may consider having a property on the initial operation
             // to specify a runner type requested in rush-project.json
-            const customParameterValues: ReadonlyArray<string> = getCustomParameterValuesForPhase(phase);
+            const { parameterValues: customParameterValues, ignoredParameterNames } =
+              getCustomParameterValues(operation);
 
             const displayName: string = getDisplayName(phase, project);
             const { name: phaseName, shellCommand } = phase;
@@ -63,6 +65,7 @@ export class ShellOperationRunnerPlugin implements IPhasedCommandPlugin {
               commandForHash,
               commandToRun,
               customParameterValues,
+              ignoredParameterNames,
               rushConfiguration
             });
           }
@@ -82,8 +85,9 @@ export function initializeShellOperationRunner(options: {
   commandToRun: string | undefined;
   commandForHash?: string;
   customParameterValues: ReadonlyArray<string>;
+  ignoredParameterNames: ReadonlyArray<string>;
 }): IOperationRunner {
-  const { phase, project, commandToRun: rawCommandToRun, displayName } = options;
+  const { phase, project, commandToRun: rawCommandToRun, displayName, ignoredParameterNames } = options;
 
   if (typeof rawCommandToRun !== 'string' && phase.missingScriptBehavior === 'error') {
     throw new Error(
@@ -104,7 +108,8 @@ export function initializeShellOperationRunner(options: {
       commandForHash,
       displayName,
       phase,
-      rushProject: project
+      rushProject: project,
+      ignoredParameterNames
     });
   } else {
     // Empty build script indicates a no-op, so use a no-op runner
@@ -116,30 +121,110 @@ export function initializeShellOperationRunner(options: {
   }
 }
 
+/**
+ * Result of filtering custom parameters for an operation
+ */
+export interface ICustomParameterValuesForOperation {
+  /**
+   * The serialized custom parameter values that should be included in the command
+   */
+  parameterValues: ReadonlyArray<string>;
+  /**
+   * The names of parameters that were ignored for this operation
+   */
+  ignoredParameterNames: ReadonlyArray<string>;
+}
+
 /**
  * Memoizer for custom parameter values by phase
  * @returns A function that returns the custom parameter values for a given phase
  */
 export function getCustomParameterValuesByPhase(): (phase: IPhase) => ReadonlyArray<string> {
-  const customParametersByPhase: Map<IPhase, string[]> = new Map();
+  const customParametersByPhase: Map<IPhase, Set<string>> = new Map();
 
   function getCustomParameterValuesForPhase(phase: IPhase): ReadonlyArray<string> {
-    let customParameterValues: string[] | undefined = customParametersByPhase.get(phase);
-    if (!customParameterValues) {
-      customParameterValues = [];
+    let customParameterSet: Set<string> | undefined = customParametersByPhase.get(phase);
+    if (!customParameterSet) {
+      const customParameterValues: string[] = [];
       for (const tsCommandLineParameter of phase.associatedParameters) {
         tsCommandLineParameter.appendToArgList(customParameterValues);
       }
 
-      customParametersByPhase.set(phase, customParameterValues);
+      customParameterSet = new Set(customParameterValues);
+      customParametersByPhase.set(phase, customParameterSet);
     }
 
-    return customParameterValues;
+    return Array.from(customParameterSet);
   }
 
   return getCustomParameterValuesForPhase;
 }
 
+/**
+ * Gets custom parameter values for an operation, filtering out any parameters that should be ignored
+ * based on the operation's settings.
+ * @returns A function that returns the filtered custom parameter values and ignored parameter names for a given operation
+ */
+export function getCustomParameterValuesForOperation(): (
+  operation: Operation
+) => ICustomParameterValuesForOperation {
+  const customParametersByPhase: Map<IPhase, Set<string>> = new Map();
+
+  function getCustomParameterValuesForOp(operation: Operation): ICustomParameterValuesForOperation {
+    const { associatedPhase: phase, settings } = operation;
+
+    // Get or compute the set of all custom parameters for this phase
+    let customParameterSet: Set<string> | undefined = customParametersByPhase.get(phase);
+    if (!customParameterSet) {
+      customParameterSet = new Set();
+      for (const tsCommandLineParameter of phase.associatedParameters) {
+        const tempArgs: string[] = [];
+        tsCommandLineParameter.appendToArgList(tempArgs);
+        for (const arg of tempArgs) {
+          customParameterSet.add(arg);
+        }
+      }
+
+      customParametersByPhase.set(phase, customParameterSet);
+    }
+
+    // If there are no parameters to ignore, return early with all parameters
+    const parameterNamesToIgnore: string[] | undefined = settings?.parameterNamesToIgnore;
+    if (!parameterNamesToIgnore || parameterNamesToIgnore.length === 0) {
+      return {
+        parameterValues: Array.from(customParameterSet),
+        ignoredParameterNames: []
+      };
+    }
+
+    // Create a set of parameter long names to ignore for fast lookup
+    const ignoreSet: Set<string> = new Set(parameterNamesToIgnore);
+
+    // Filter out ignored parameters and track which ones were ignored
+    const filteredParameterValues: string[] = [];
+    const ignoredParameterNames: string[] = [];
+
+    for (const tsCommandLineParameter of phase.associatedParameters) {
+      const parameterLongName: string = tsCommandLineParameter.longName;
+
+      if (ignoreSet.has(parameterLongName)) {
+        // This parameter should be ignored for this operation
+        ignoredParameterNames.push(parameterLongName);
+      } else {
+        // Include this parameter in the command
+        tsCommandLineParameter.appendToArgList(filteredParameterValues);
+      }
+    }
+
+    return {
+      parameterValues: filteredParameterValues,
+      ignoredParameterNames
+    };
+  }
+
+  return getCustomParameterValuesForOp;
+}
+
 export function formatCommand(rawCommand: string, customParameterValues: ReadonlyArray<string>): string {
   if (!rawCommand) {
     return '';

libraries/rush-lib/src/schemas/rush-project.schema.json

@@ -110,6 +110,14 @@
           "ignoreChangedProjectsOnlyFlag": {
             "type": "boolean",
             "description": "If true, this operation never be skipped by the `--changed-projects-only` flag. This is useful for projects that bundle code from other packages."
+          },
+          "parameterNamesToIgnore": {
+            "type": "array",
+            "description": "An optional list of custom command-line parameter names (their parameterLongName values from command-line.json) that should be ignored when invoking the command for this operation. This allows a project to opt out of parameters that don't affect its operation, preventing unnecessary cache invalidation for this operation and its consumers.",
+            "items": {
+              "type": "string"
+            },
+            "uniqueItems": true
           }
         }
       }