Refactor parameter helpers into cli/parsing directory

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

Author: Copilot

libraries/rush-lib/src/cli/parsing/associateParametersByPhase.ts

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
+// See LICENSE in the project root for license information.
+
+import { InternalError } from '@rushstack/node-core-library';
+import type { CommandLineParameter } from '@rushstack/ts-command-line';
+
+import type { IParameterJson, IPhase } from '../../api/CommandLineConfiguration';
+
+/**
+ * Associates command line parameters with their associated phases.
+ * This helper is used to populate the `associatedParameters` set on each phase
+ * based on the `associatedPhases` property of each parameter.
+ *
+ * @param customParameters - Map of parameter definitions to their CommandLineParameter instances
+ * @param knownPhases - Map of phase names to IPhase objects
+ */
+export function associateParametersByPhase(
+  customParameters: ReadonlyMap<IParameterJson, CommandLineParameter>,
+  knownPhases: ReadonlyMap<string, IPhase>
+): void {
+  for (const [parameterJson, tsCommandLineParameter] of customParameters) {
+    if (parameterJson.associatedPhases) {
+      for (const phaseName of parameterJson.associatedPhases) {
+        const phase: IPhase | undefined = knownPhases.get(phaseName);
+        if (!phase) {
+          throw new InternalError(`Could not find a phase matching ${phaseName}.`);
+        }
+        phase.associatedParameters.add(tsCommandLineParameter);
+      }
+    }
+  }
+}

…utilities/CommandLineParameterHelpers.ts …rc/cli/parsing/defineCustomParameters.tslibraries/rush-lib/src/utilities/CommandLineParameterHelpers.ts renamed to libraries/rush-lib/src/cli/parsing/defineCustomParameters.ts libraries/rush-lib/src/utilities/CommandLineParameterHelpers.ts renamed to libraries/rush-lib/src/cli/parsing/defineCustomParameters.ts

@@ -3,24 +3,23 @@
 
 import type { CommandLineAction, CommandLineParameter } from '@rushstack/ts-command-line';
 
-import type { IParameterJson } from '../api/CommandLineConfiguration';
-import { RushConstants } from '../logic/RushConstants';
-import type { ParameterJson } from '../api/CommandLineJson';
+import type { IParameterJson } from '../../api/CommandLineConfiguration';
+import { RushConstants } from '../../logic/RushConstants';
+import type { ParameterJson } from '../../api/CommandLineJson';
 
 /**
  * Helper function to create CommandLineParameter instances from parameter definitions.
  * This centralizes the logic for defining parameters based on their kind.
  *
  * @param action - The CommandLineAction to define the parameters on
  * @param associatedParameters - The set of parameter definitions
- * @returns A map from parameter longName to the created CommandLineParameter instance
+ * @param targetMap - The map to populate with parameter definitions to CommandLineParameter instances
  */
-export function createCommandLineParameters(
+export function defineCustomParameters(
   action: CommandLineAction,
-  associatedParameters: Iterable<IParameterJson>
-): Map<string, CommandLineParameter> {
-  const customParameters: Map<string, CommandLineParameter> = new Map();
-
+  associatedParameters: Iterable<IParameterJson>,
+  targetMap: Map<IParameterJson, CommandLineParameter>
+): void {
   for (const parameter of associatedParameters) {
     let tsCommandLineParameter: CommandLineParameter | undefined;
 
@@ -96,8 +95,6 @@ export function createCommandLineParameters(
         );
     }
 
-    customParameters.set(parameter.longName, tsCommandLineParameter);
+    targetMap.set(parameter, tsCommandLineParameter);
   }
-
-  return customParameters;
 }

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

@@ -5,7 +5,7 @@ import type { CommandLineParameter } from '@rushstack/ts-command-line';
 
 import { BaseRushAction, type IBaseRushActionOptions } from '../actions/BaseRushAction';
 import type { Command, CommandLineConfiguration, IParameterJson } from '../../api/CommandLineConfiguration';
-import { createCommandLineParameters } from '../../utilities/CommandLineParameterHelpers';
+import { defineCustomParameters } from '../parsing/defineCustomParameters';
 
 /**
  * Constructor parameters for BaseScriptAction
@@ -42,19 +42,6 @@ export abstract class BaseScriptAction<TCommand extends Command> extends BaseRus
     }
 
     // Use the centralized helper to create CommandLineParameter instances
-    const parametersByLongName: Map<string, CommandLineParameter> = createCommandLineParameters(
-      this,
-      this.command.associatedParameters
-    );
-
-    // Map them by IParameterJson for internal use
-    for (const parameter of this.command.associatedParameters) {
-      const tsCommandLineParameter: CommandLineParameter | undefined = parametersByLongName.get(
-        parameter.longName
-      );
-      if (tsCommandLineParameter) {
-        this.customParameters.set(parameter, tsCommandLineParameter);
-      }
-    }
+    defineCustomParameters(this, this.command.associatedParameters, this.customParameters);
   }
 }

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

@@ -3,7 +3,7 @@
 
 import type { AsyncSeriesHook } from 'tapable';
 
-import { AlreadyReportedError, InternalError } from '@rushstack/node-core-library';
+import { AlreadyReportedError } from '@rushstack/node-core-library';
 import { type ITerminal, Terminal, Colorize } from '@rushstack/terminal';
 import type {
   CommandLineFlagParameter,
@@ -33,6 +33,7 @@ import { SelectionParameterSet } from '../parsing/SelectionParameterSet';
 import type { IPhase, IPhasedCommandConfig } from '../../api/CommandLineConfiguration';
 import type { Operation } from '../../logic/operations/Operation';
 import type { OperationExecutionRecord } from '../../logic/operations/OperationExecutionRecord';
+import { associateParametersByPhase } from '../parsing/associateParametersByPhase';
 import { PhasedOperationPlugin } from '../../logic/operations/PhasedOperationPlugin';
 import { ShellOperationRunnerPlugin } from '../../logic/operations/ShellOperationRunnerPlugin';
 import { Event } from '../../api/EventHooks';
@@ -327,17 +328,8 @@ export class PhasedScriptAction extends BaseScriptAction<IPhasedCommandConfig> i
 
     this.defineScriptParameters();
 
-    for (const [{ associatedPhases }, tsCommandLineParameter] of this.customParameters) {
-      if (associatedPhases) {
-        for (const phaseName of associatedPhases) {
-          const phase: IPhase | undefined = this._knownPhases.get(phaseName);
-          if (!phase) {
-            throw new InternalError(`Could not find a phase matching ${phaseName}.`);
-          }
-          phase.associatedParameters.add(tsCommandLineParameter);
-        }
-      }
-    }
+    // Associate parameters with their respective phases
+    associateParametersByPhase(this.customParameters, this._knownPhases);
   }
 
   public async runAsync(): Promise<void> {

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

@@ -4,17 +4,15 @@
 import path from 'node:path';
 import { JsonFile } from '@rushstack/node-core-library';
 import { ConsoleTerminalProvider, Terminal } from '@rushstack/terminal';
-import {
-  CommandLineAction,
-  type CommandLineParameter,
-  type CommandLineFlagParameter,
-  type CommandLineStringParameter,
-  type CommandLineChoiceParameter,
-  type CommandLineStringListParameter
-} from '@rushstack/ts-command-line';
+import { CommandLineAction, type CommandLineParameter } from '@rushstack/ts-command-line';
 
 import { RushConfiguration } from '../../../api/RushConfiguration';
-import { CommandLineConfiguration, type IPhasedCommandConfig } from '../../../api/CommandLineConfiguration';
+import {
+  CommandLineConfiguration,
+  type IPhasedCommandConfig,
+  type IParameterJson,
+  type IPhase
+} from '../../../api/CommandLineConfiguration';
 import type { Operation } from '../Operation';
 import type { ICommandLineJson } from '../../../api/CommandLineJson';
 import { PhasedOperationPlugin } from '../PhasedOperationPlugin';
@@ -24,7 +22,8 @@ import {
   PhasedCommandHooks
 } from '../../../pluginFramework/PhasedCommandHooks';
 import { RushProjectConfiguration } from '../../../api/RushProjectConfiguration';
-import { createCommandLineParameters } from '../../../utilities/CommandLineParameterHelpers';
+import { defineCustomParameters } from '../../../cli/parsing/defineCustomParameters';
+import { associateParametersByPhase } from '../../../cli/parsing/associateParametersByPhase';
 
 interface ISerializedOperation {
   name: string;
@@ -174,48 +173,58 @@ describe(ShellOperationRunnerPlugin.name, () => {
     });
 
     // Create CommandLineParameter instances from the parameter definitions
-    const customParametersMap: Map<string, CommandLineParameter> = createCommandLineParameters(
-      action,
-      buildCommand.associatedParameters
-    );
+    const customParametersMap: Map<IParameterJson, CommandLineParameter> = new Map();
+    defineCustomParameters(action, buildCommand.associatedParameters, customParametersMap);
 
     // Set values on the parameters to test filtering
+    // Create a map by longName for easier lookup
+    const paramsByLongName: Map<string, { param: IParameterJson; cli: CommandLineParameter }> = new Map();
+    for (const [param, cli] of customParametersMap) {
+      paramsByLongName.set(param.longName, { param, cli });
+    }
+
     // Set --production flag
-    const productionParam = customParametersMap.get('--production') as CommandLineFlagParameter | undefined;
-    if (productionParam) {
-      (productionParam as unknown as { _setValue(value: boolean): void })._setValue(true);
+    const production = paramsByLongName.get('--production');
+    if (production) {
+      (production.cli as unknown as { _setValue(value: boolean): void })._setValue(true);
     }
 
     // Set --verbose flag
-    const verboseParam = customParametersMap.get('--verbose') as CommandLineFlagParameter | undefined;
-    if (verboseParam) {
-      (verboseParam as unknown as { _setValue(value: boolean): void })._setValue(true);
+    const verbose = paramsByLongName.get('--verbose');
+    if (verbose) {
+      (verbose.cli as unknown as { _setValue(value: boolean): void })._setValue(true);
     }
 
     // Set --config parameter
-    const configParam = customParametersMap.get('--config') as CommandLineStringParameter | undefined;
-    if (configParam) {
-      (configParam as unknown as { _setValue(value: string): void })._setValue('/path/to/config.json');
+    const config = paramsByLongName.get('--config');
+    if (config) {
+      (config.cli as unknown as { _setValue(value: string): void })._setValue('/path/to/config.json');
     }
 
     // Set --mode parameter
-    const modeParam = customParametersMap.get('--mode') as CommandLineChoiceParameter | undefined;
-    if (modeParam) {
-      (modeParam as unknown as { _setValue(value: string): void })._setValue('prod');
+    const mode = paramsByLongName.get('--mode');
+    if (mode) {
+      (mode.cli as unknown as { _setValue(value: string): void })._setValue('prod');
     }
 
     // Set --tags parameter
-    const tagsParam = customParametersMap.get('--tags') as CommandLineStringListParameter | undefined;
-    if (tagsParam) {
-      (tagsParam as unknown as { _setValue(value: string[]): void })._setValue(['tag1', 'tag2']);
+    const tags = paramsByLongName.get('--tags');
+    if (tags) {
+      (tags.cli as unknown as { _setValue(value: string[]): void })._setValue(['tag1', 'tag2']);
     }
 
-    // Update the phase's associatedParameters to use our created CommandLineParameters
+    // Associate parameters with phases using the helper
+    // Create a map of phase names to phases for the helper
+    const phasesMap: Map<string, IPhase> = new Map();
     for (const phase of buildCommand.phases) {
-      phase.associatedParameters.clear();
-      for (const param of customParametersMap.values()) {
-        phase.associatedParameters.add(param);
-      }
+      phasesMap.set(phase.name, phase);
+    }
+    associateParametersByPhase(customParametersMap, phasesMap);
+
+    // Create customParameters map for ICreateOperationsContext (keyed by longName)
+    const customParametersForContext: Map<string, CommandLineParameter> = new Map();
+    for (const [param, cli] of customParametersMap) {
+      customParametersForContext.set(param.longName, cli);
     }
 
     const fakeCreateOperationsContext: Pick<
@@ -234,7 +243,7 @@ describe(ShellOperationRunnerPlugin.name, () => {
       projectsInUnknownState: new Set(rushConfiguration.projects),
       projectConfigurations,
       rushConfiguration,
-      customParameters: customParametersMap
+      customParameters: customParametersForContext
     };
 
     const hooks: PhasedCommandHooks = new PhasedCommandHooks();