// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. // See LICENSE in the project root for license information. import { Async, FileSystem } from '@rushstack/node-core-library'; import { _OperationBuildCache as OperationBuildCache, OperationStatus, type Operation, type IOperationExecutionResult, type IOperationGraphIterationOptions, type ILogger, type IBaseOperationExecutionResult, type IPhasedCommand, type IRushPlugin, type RushSession } from '@rushstack/rush-sdk'; import { CommandLineParameterKind, type CommandLineParameter } from '@rushstack/ts-command-line'; const PLUGIN_NAME: 'RushBridgeCachePlugin' = 'RushBridgeCachePlugin'; const CACHE_ACTION_READ: 'read' = 'read'; const CACHE_ACTION_WRITE: 'write' = 'write'; type CacheAction = typeof CACHE_ACTION_READ | typeof CACHE_ACTION_WRITE; export interface IBridgeCachePluginOptions { readonly actionParameterName: string; readonly requireOutputFoldersParameterName: string | undefined; } export class BridgeCachePlugin implements IRushPlugin { public readonly pluginName: string = PLUGIN_NAME; readonly #actionParameterName: string; readonly #requireOutputFoldersParameterName: string | undefined; public constructor(options: IBridgeCachePluginOptions) { this.#actionParameterName = options.actionParameterName; this.#requireOutputFoldersParameterName = options.requireOutputFoldersParameterName; if (!this.#actionParameterName) { throw new Error( 'The "actionParameterName" option must be provided for the BridgeCachePlugin. Please see the plugin README for details.' ); } } public apply(session: RushSession): void { session.hooks.runAnyPhasedCommand.tapPromise(PLUGIN_NAME, async (command: IPhasedCommand) => { command.hooks.onGraphCreatedAsync.tap(PLUGIN_NAME, async (graph, context) => { const { customParameters, buildCacheConfiguration } = context; const cacheAction: CacheAction | undefined = this.#getCacheAction(customParameters); if (cacheAction !== undefined) { if (!buildCacheConfiguration?.buildCacheEnabled) { throw new Error( `The build cache must be enabled to use the "${this.#actionParameterName}" parameter.` ); } const { rushConfiguration: { experimentsConfiguration: { configuration: { omitAppleDoubleFilesFromBuildCache, useDirectFileTransfersForBuildCache = false } } } } = context; const logger: ILogger = session.getLogger(PLUGIN_NAME); const { terminal } = logger; const requireOutputFolders: boolean = this.#isRequireOutputFoldersFlagSet(customParameters); graph.hooks.beforeExecuteIterationAsync.tapPromise( PLUGIN_NAME, async ( operationRecords: ReadonlyMap, iterationOptions: IOperationGraphIterationOptions ): Promise => { const filteredOperations: IBaseOperationExecutionResult[] = []; for (const record of operationRecords.values()) { const { operation } = record; // The graph can also hold operations outside the command's selection, such as the // dependencies of a project selected with `--only`, or every project's operations in // a Rush daemon engine. Those operations are disabled, so leave their outputs and // cache entries alone. if (operation.enabled !== false && !operation.isNoOp) { filteredOperations.push(record); } } if (!filteredOperations.length) { return; // nothing to do, continue normal execution } let successCount: number = 0; await Async.forEachAsync( filteredOperations, async (operationExecutionResult: IBaseOperationExecutionResult) => { const projectBuildCache: OperationBuildCache = OperationBuildCache.forOperation( operationExecutionResult, { buildCacheConfiguration, terminal, excludeAppleDoubleFiles: !!omitAppleDoubleFilesFromBuildCache, useDirectFileTransfersForBuildCache } ); const { operation } = operationExecutionResult; if (cacheAction === CACHE_ACTION_READ) { const success: boolean = await projectBuildCache.tryRestoreFromCacheAsync(terminal); if (success) { ++successCount; terminal.writeLine( `Operation "${operation.name}": Outputs have been restored from the build cache."` ); terminal.writeLine(`Cache key: ${projectBuildCache.cacheId}`); } else { terminal.writeWarningLine( `Operation "${operation.name}": Outputs could not be restored from the build cache.` ); } } else if (cacheAction === CACHE_ACTION_WRITE) { if ( requireOutputFolders && operation.settings?.outputFolderNames && operation.settings?.outputFolderNames?.length > 0 ) { const projectFolder: string = operation.associatedProject?.projectFolder; const missingFolders: string[] = []; operation.settings.outputFolderNames.forEach((outputFolderName: string) => { if (!FileSystem.exists(`${projectFolder}/${outputFolderName}`)) { missingFolders.push(outputFolderName); } }); if (missingFolders.length > 0) { terminal.writeWarningLine( `Operation "${operation.name}": The following output folders do not exist: "${missingFolders.join('", "')}". Skipping cache population.` ); return; } } const success: boolean = await projectBuildCache.trySetCacheEntryAsync(terminal); if (success) { ++successCount; terminal.writeLine( `Operation "${operation.name}": Existing outputs have been successfully written to the build cache."` ); terminal.writeLine(`Cache key: ${projectBuildCache.cacheId}`); } else { terminal.writeErrorLine( `Operation "${operation.name}": An error occurred while writing existing outputs to the build cache.` ); } } }, { concurrency: graph.parallelism } ); terminal.writeLine( `Cache operation "${cacheAction}" completed successfully for ${successCount} out of ${filteredOperations.length} operations.` ); // Bail out with a status indicating success; treat cache read as FromCache. Because this // status is successful, the OperationGraph reports the individual operations (which were // intentionally not executed) as Skipped rather than Aborted. return cacheAction === CACHE_ACTION_READ ? OperationStatus.FromCache : OperationStatus.Success; } ); } }); }); } #getCacheAction( customParameters: ReadonlyMap ): CacheAction | undefined { const cacheActionParameter: CommandLineParameter | undefined = customParameters.get( this.#actionParameterName ); if (cacheActionParameter) { if (cacheActionParameter.kind !== CommandLineParameterKind.Choice) { throw new Error( `The parameter "${this.#actionParameterName}" must be a choice. Please check the plugin configuration.` ); } if ( cacheActionParameter.alternatives.size !== 2 || !cacheActionParameter.alternatives.has(CACHE_ACTION_READ) || !cacheActionParameter.alternatives.has(CACHE_ACTION_WRITE) ) { throw new Error( `The parameter "${this.#actionParameterName}" must have exactly two choices: "${CACHE_ACTION_READ}" and "${CACHE_ACTION_WRITE}". Please check the plugin configuration.` ); } const value: string | undefined = cacheActionParameter.value; switch (value) { case CACHE_ACTION_READ: case CACHE_ACTION_WRITE: return value; case undefined: return undefined; default: throw new Error( `The parameter "${this.#actionParameterName}" must be one of: "${CACHE_ACTION_READ}" or "${CACHE_ACTION_WRITE}". Received: "${value}". Please check the plugin configuration.` ); } } return undefined; } #isRequireOutputFoldersFlagSet( customParameters: ReadonlyMap ): boolean { if (!this.#requireOutputFoldersParameterName) { return false; } const requireOutputFoldersParam: CommandLineParameter | undefined = customParameters.get( this.#requireOutputFoldersParameterName ); if (!requireOutputFoldersParam) { return false; } if (requireOutputFoldersParam.kind !== CommandLineParameterKind.Flag) { throw new Error(`The parameter "${this.#requireOutputFoldersParameterName}" must be a flag.`); } return requireOutputFoldersParam.value; } }