[rush] Add project-level parameter ignoring to prevent unnecessary cache invalidation

[Copilot]

Summary

Custom command-line parameters currently propagate to all projects in a Rush command, causing cache invalidation even when parameters don't affect specific operations. This PR adds parameterNamesToIgnore to rush-project.json to exclude irrelevant parameters from cache key calculation and command invocation.

Fixes #5432

Details

Schema & Interface

• Added parameterNamesToIgnore?: string[] to IOperationSettings in rush-project.json
• Field accepts parameter longName values (e.g., --production, --verbose)

Core Logic

• Refactored getCustomParameterValuesByPhase → getCustomParameterValuesByOperation
• Returns { parameterValues, ignoredParameterValues } for filtered parameters and logging
• Filters parameters by checking operation.settings.parameterNamesToIgnore against parameter longName
• Uses appendToArgList for both included and ignored parameters to get actual CLI values
• Returns arrays instead of Sets to allow duplicate arguments

Runners

• ShellOperationRunner and IPCOperationRunner accept ignoredParameterValues
• Log ignored parameters via terminal.writeLine() before invocation with clear message indicating project-level configuration

Plugins

• IPCOperationRunnerPlugin uses new getCustomParameterValuesByOperation function
• ShardedPhaseOperationPlugin derives ignored values from operation settings for both collator and shard operations

Parameter Parsing Helpers

• Created cli/parsing/defineCustomParameters.ts helper that accepts a target map to avoid copying
• Map is keyed by IParameterJson for consistency
• Created companion cli/parsing/associateParametersByPhase.ts helper extracted from PhasedScriptAction
• Refactored BaseScriptAction and PhasedScriptAction to use shared helpers
• Both helpers are used in comprehensive unit tests

Configuration Example

{
  "operationSettings": [
    {
      "operationName": "_phase:build",
      "parameterNamesToIgnore": ["--production"]
    }
  ]
}

The --production parameter will be excluded from command invocation and cache key for this operation, preventing cache breaks when the parameter changes but doesn't affect the build output.

How it was tested

• Added comprehensive unit tests with all parameter types (flag, string, choice, stringList)
• Created test repository configurations where each parameter type is filtered in at least one operation
• Tests use CommandLineParser.executeWithoutErrorHandlingAsync() to properly parse parameter values through the standard parsing flow
• Verified that parameters are correctly filtered based on parameterNamesToIgnore configuration
• All existing tests pass (503 tests)
• Manual verification that ignored parameters are properly logged

Impacted documentation

• rush-project.schema.json - Updated with new parameterNamesToIgnore field
• Documentation should be updated to explain the new field and its usage at: https://rushjs.io/pages/configs/rush-project_json/

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[rush] Feature Request - Allow project-level ignoring of custom command-line parameters</issue_title>
<issue_description>## Summary
Currently support for custom parameters in command-line.json is all-or-nothing with respect to which projects they get forwarded to. Which phases they get forwarded to is configurable, however.

Since the exact CLI is used as part of the cache key for the build cache (and propagates into downstream operations since they include the cache keys of their dependencies), this means that if you have a CLI parameter (e.g. --production) that has no effect on a given project, adding or removing the parameter will cause a cache break without providing any value.

We should allow projects to mark (via rush-project.json) that for a given operation, certain custom command-line parameters should be discarded when deriving the CLI.

Details

Add a new field parameterNamesToIgnore (name negotiable) in the operationSettings sub-objects in rush-project.json that is an array of the parameterLongName values defined in command-line.json.

When expanding the command line arguments to be passed to ShellOperationRunner, any custom parameters that match the parameterNamesToIgnore entry for the operation should be discarded. We emit a verbose log line alongside the "Invoking ..." log that remarks on any parameters that were ignored.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@microsoft/rush globally installed version?	5.162.0
rushVersion from rush.json?	5.162.0
useWorkspaces from rush.json?	Yes
Operating system?	Linux
Would you consider contributing a PR?	Yes
Node.js version (node -v)?	22.16.0
</issue_description>

<agent_instructions>The getCustomParameterValuesByPhase helper in ShellOperationRunnerPlugin will need to be updated to instead be getCustomParameterValuesForOperation and take in the full Operation instance so that it can access the operationSettings object and filter out any ignored parameters. It should also return both the serialized parameter values and an array of the ignored parameter values, since the latter will be used for logging.
The internal state map for this helper should collate a Set instead of precalculating the flattened array.

ShellOperationRunner and IPCOperationRunner should both accept the ignoredParameterValues property so that they can log it during startup.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [rush] Feature Request - Allow project-level ignoring of custom command-line parameters #5432

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[dmichon-msft]

@copilot address feedback

[dmichon-msft]

@copilot Follow the provided guidance for how to properly unit test the ignoring of command line parameters.

[iclanton]

@copilot Run rush change --no-fetch --bulk --bump-type minor --message "<DESCRIBE THE CHANGE HERE>" to generate the necessary change file. Make sure you replace <DESCRIBE THE CHANGE HERE> with a description of this change which will show up in the changelog when this is published.

[Copilot]

@copilot Run rush change --no-fetch --bulk --bump-type minor --message "<DESCRIBE THE CHANGE HERE>" to generate the necessary change file. Make sure you replace <DESCRIBE THE CHANGE HERE> with a d...

Generated change file in commit 4063f98.

[dmichon-msft]

Just a minor touchup to the change file remaining

[D4N14L]

This took a lot more wiring in than I would have thought... maybe an argument for discussing changes here, but certainly not for this PR.