// 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 { RushConfigurationProject } from '../../api/RushConfigurationProject'; import { RushConstants } from '../RushConstants'; import { NullOperationRunner } from './NullOperationRunner'; import { convertSlashesForWindows, ShellOperationRunner } from './ShellOperationRunner'; import { OperationStatus } from './OperationStatus'; import type { ICreateOperationsContext, IPhasedCommandPlugin, PhasedCommandHooks } from '../../pluginFramework/PhasedCommandHooks'; import type { Operation } from './Operation'; import type { RushConfiguration } from '../../api/RushConfiguration'; import type { IOperationRunner } from './IOperationRunner'; import { IS_WINDOWS, quoteShellArgumentIfNeeded } from '../../utilities/executionUtilities'; export const PLUGIN_NAME: 'ShellOperationRunnerPlugin' = 'ShellOperationRunnerPlugin'; /** * Core phased command plugin that provides the functionality for executing an operation via shell command. */ export class ShellOperationRunnerPlugin implements IPhasedCommandPlugin { public apply(hooks: PhasedCommandHooks): void { hooks.createOperationsAsync.tap( PLUGIN_NAME, function createShellOperations( operations: Set, context: ICreateOperationsContext ): Set { const { rushConfiguration, isIncrementalBuildAllowed, isWatch } = context; const getCustomParameterValues: (operation: Operation) => ICustomParameterValuesForOperation = getCustomParameterValuesByOperation(); 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 { parameterValues: customParameterValues, ignoredParameterValues } = getCustomParameterValues(operation); const displayName: string = getDisplayName(phase, project); const { name: phaseName, shellCommand } = phase; const { scripts } = project.packageJson; // This is the command that will be used to identify the cache entry for this operation const commandForHash: string | undefined = shellCommand ?? scripts?.[phaseName]; // For execution of non-initial watch iterations, prefer the `:incremental` script if it exists. // However, the `shellCommand` value still takes precedence per the spec for that feature. // Outside watch mode, the `:incremental` script only runs where a long-lived host (rushd) registers an // incremental execution guard for the operation (IncrementalExecutionGuardPlugin). Without one, every // command runs the initial script, as a single `rush build` does: the incremental script may keep the // outputs of deleted inputs, and outside watch mode its results could be written to the build cache. const initialCommand: string | undefined = shellCommand ?? scripts?.[phaseName]; const incrementalCommand: string | undefined = !isIncrementalBuildAllowed ? undefined : isWatch ? (shellCommand ?? scripts?.[`${phaseName}:incremental`]) : shellCommand === undefined ? scripts?.[`${phaseName}:incremental`] : undefined; operation.runner = initializeShellOperationRunner({ phase, project, displayName, commandForHash, initialCommand, incrementalCommand, incrementalCommandRequiresGuard: !isWatch, customParameterValues, ignoredParameterValues, rushConfiguration }); } } return operations; } ); } } export function initializeShellOperationRunner(options: { phase: IPhase; project: RushConfigurationProject; displayName: string; rushConfiguration: RushConfiguration; initialCommand: string | undefined; incrementalCommand: string | undefined; /** * See `IShellOperationRunnerOptions.incrementalCommandRequiresGuard`. Defaults to false. */ incrementalCommandRequiresGuard?: boolean; commandForHash?: string; /** * The custom parameter values. Each one is quoted for the shell if it needs it. */ customParameterValues: ReadonlyArray; /** * Arguments that are already written for the shell, such as the sharding arguments. * They are appended after the custom parameter values, without quoting. */ preformattedArguments?: ReadonlyArray; ignoredParameterValues: ReadonlyArray; }): IOperationRunner { const { phase, project, initialCommand: rawInitialCommand, incrementalCommand: rawIncrementalCommand, incrementalCommandRequiresGuard = false, displayName, ignoredParameterValues } = options; if (typeof rawInitialCommand !== 'string' && phase.missingScriptBehavior === 'error') { throw new Error( `The project '${project.packageName}' does not define a '${phase.name}' command in the 'scripts' section of its package.json` ); } if (rawInitialCommand) { const { commandForHash: rawCommandForHash, customParameterValues, preformattedArguments } = options; const initialCommand: string = formatCommand( rawInitialCommand, customParameterValues, preformattedArguments ); let incrementalCommand: string | undefined = rawIncrementalCommand ? formatCommand(rawIncrementalCommand, customParameterValues, preformattedArguments) : undefined; if (incrementalCommandRequiresGuard && incrementalCommand === initialCommand) { // Running it as the incremental command would only prevent its results from being cached. incrementalCommand = undefined; } const commandForHash: string = rawCommandForHash ? formatCommand(rawCommandForHash, customParameterValues, preformattedArguments) : initialCommand; return new ShellOperationRunner({ initialCommand, incrementalCommand, incrementalCommandRequiresGuard, commandForHash, displayName, phase, rushProject: project, ignoredParameterValues }); } else { // Empty build script indicates a no-op, so use a no-op runner return new NullOperationRunner({ name: displayName, result: OperationStatus.NoOp, silent: phase.missingScriptBehavior === 'silent' }); } } /** * 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; /** * The serialized custom parameter values that were ignored for this operation */ ignoredParameterValues: ReadonlyArray; } /** * Helper function to collect all parameter arguments for a phase */ function collectPhaseParameterArguments(phase: IPhase): string[] { const customParameterList: string[] = []; for (const tsCommandLineParameter of phase.associatedParameters) { tsCommandLineParameter.appendToArgList(customParameterList); } return customParameterList; } /** * 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 { const customParametersByPhase: Map = new Map(); function getCustomParameterValuesForPhase(phase: IPhase): ReadonlyArray { let customParameterList: string[] | undefined = customParametersByPhase.get(phase); if (!customParameterList) { customParameterList = collectPhaseParameterArguments(phase); customParametersByPhase.set(phase, customParameterList); } return customParameterList; } 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 values for a given operation */ export function getCustomParameterValuesByOperation(): ( operation: Operation ) => ICustomParameterValuesForOperation { const customParametersByPhase: Map = new Map(); function getCustomParameterValuesForOp(operation: Operation): ICustomParameterValuesForOperation { const { associatedPhase: phase, settings } = operation; // Check if there are any parameters to ignore const parameterNamesToIgnore: string[] | undefined = settings?.parameterNamesToIgnore; if (!parameterNamesToIgnore || parameterNamesToIgnore.length === 0) { // No filtering needed - use the cached parameter list for efficiency let customParameterList: string[] | undefined = customParametersByPhase.get(phase); if (!customParameterList) { customParameterList = collectPhaseParameterArguments(phase); customParametersByPhase.set(phase, customParameterList); } return { parameterValues: customParameterList, ignoredParameterValues: [] }; } // Filtering is needed - we must iterate through parameter objects to check longName // Note: We cannot use the cached parameter list here because we need access to // the parameter objects to get their longName property for filtering const ignoreSet: Set = new Set(parameterNamesToIgnore); const filteredParameterValues: string[] = []; const ignoredParameterValues: string[] = []; for (const tsCommandLineParameter of phase.associatedParameters) { const parameterLongName: string = tsCommandLineParameter.longName; tsCommandLineParameter.appendToArgList( ignoreSet.has(parameterLongName) ? ignoredParameterValues : filteredParameterValues ); } return { parameterValues: filteredParameterValues, ignoredParameterValues }; } return getCustomParameterValuesForOp; } /** * Appends the custom parameter values to a command, each quoted for the shell that runs the command * if it needs it (see `quoteShellArgumentIfNeeded`), and then the preformatted arguments as they are. */ export function formatCommand( rawCommand: string, customParameterValues: ReadonlyArray, preformattedArguments: ReadonlyArray = [], isWindows: boolean = IS_WINDOWS ): string { if (!rawCommand) { return ''; } else { const shellArguments: string[] = customParameterValues.map((value: string) => quoteShellArgumentIfNeeded(value, isWindows) ); shellArguments.push(...preformattedArguments); const fullCommand: string = `${rawCommand} ${shellArguments.join(' ')}`; return isWindows ? convertSlashesForWindows(fullCommand) : fullCommand; } } export function getDisplayName(phase: IPhase, project: RushConfigurationProject): string { if (phase.isSynthetic) { // Because this is a synthetic phase, just use the project name because there aren't any other phases return project.packageName; } else { const phaseNameWithoutPrefix: string = phase.name.slice(RushConstants.phaseNamePrefix.length); return `${project.packageName} (${phaseNameWithoutPrefix})`; } }