// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license. // See LICENSE in the project root for license information. import { AsyncParallelHook, SyncHook } from 'tapable'; import { InternalError } from '@rushstack/node-core-library'; import { HeftPluginConfiguration } from '../configuration/HeftPluginConfiguration'; import { HeftPluginHost } from './HeftPluginHost'; import type { InternalHeftSession } from './InternalHeftSession'; import type { IHeftConfigurationJsonPluginSpecifier } from '../utilities/CoreConfigFiles'; import type { HeftLifecyclePluginDefinition, HeftPluginDefinitionBase } from '../configuration/HeftPluginDefinition'; import type { IHeftLifecyclePlugin, IHeftPlugin } from './IHeftPlugin'; import { HeftLifecycleSession, type IHeftLifecycleCleanHookOptions, type IHeftLifecycleHooks, type IHeftLifecycleToolStartHookOptions, type IHeftLifecycleToolFinishHookOptions, type IHeftLifecycleSession, type IHeftTaskStartHookOptions, type IHeftTaskFinishHookOptions, type IHeftPhaseStartHookOptions, type IHeftPhaseFinishHookOptions } from './HeftLifecycleSession'; import type { ScopedLogger } from './logging/ScopedLogger'; export interface IHeftLifecycleContext { lifecycleSession?: HeftLifecycleSession; pluginOptions?: object; } export class HeftLifecycle extends HeftPluginHost { readonly #internalHeftSession: InternalHeftSession; readonly #lifecyclePluginSpecifiers: IHeftConfigurationJsonPluginSpecifier[]; readonly #lifecycleHooks: IHeftLifecycleHooks; readonly #lifecycleContextByDefinition: Map = new Map(); readonly #lifecyclePluginsByDefinition: Map< HeftLifecyclePluginDefinition, IHeftLifecyclePlugin > = new Map(); #lifecycleLogger: ScopedLogger | undefined; #isInitialized: boolean = false; public get hooks(): IHeftLifecycleHooks { return this.#lifecycleHooks; } public get pluginDefinitions(): Iterable { if (!this.#isInitialized) { throw new InternalError( 'HeftLifecycle.ensureInitializedAsync() must be called before accessing HeftLifecycle.pluginDefinitions.' ); } return this.#lifecycleContextByDefinition.keys(); } public constructor( internalHeftSession: InternalHeftSession, lifecyclePluginSpecifiers: IHeftConfigurationJsonPluginSpecifier[] ) { super(); this.#internalHeftSession = internalHeftSession; this.#lifecyclePluginSpecifiers = lifecyclePluginSpecifiers; this.#lifecycleHooks = { clean: new AsyncParallelHook(), toolStart: new AsyncParallelHook(), toolFinish: new AsyncParallelHook(), recordMetrics: internalHeftSession.metricsCollector.recordMetricsHook, taskStart: new SyncHook(['task']), taskFinish: new SyncHook(['task']), phaseStart: new SyncHook(['phase']), phaseFinish: new SyncHook(['phase']) }; } protected async applyPluginsInternalAsync(): Promise { await this.ensureInitializedAsync(); // Load up all plugins concurrently const loadPluginPromises: Promise>[] = []; for (const [pluginDefinition, lifecycleContext] of this.#lifecycleContextByDefinition) { if (!lifecycleContext.lifecycleSession) { // Generate the plugin-specific session lifecycleContext.lifecycleSession = new HeftLifecycleSession({ debug: this.#internalHeftSession.debug, heftConfiguration: this.#internalHeftSession.heftConfiguration, loggingManager: this.#internalHeftSession.loggingManager, metricsCollector: this.#internalHeftSession.metricsCollector, logger: this.#internalHeftSession.loggingManager.requestScopedLogger( `lifecycle:${pluginDefinition.pluginName}` ), lifecycleHooks: this.hooks, lifecycleParameters: this.#internalHeftSession.parameterManager.getParametersForPlugin(pluginDefinition), pluginDefinition: pluginDefinition, pluginHost: this }); } loadPluginPromises.push( this.#getLifecyclePluginForPluginDefinitionAsync(pluginDefinition, lifecycleContext.lifecycleSession) ); } // Promise.all maintains the order of the input array const plugins: IHeftLifecyclePlugin[] = await Promise.all(loadPluginPromises); // Iterate through and apply the plugins let pluginIndex: number = 0; for (const [pluginDefinition, lifecycleContext] of this.#lifecycleContextByDefinition) { const lifecyclePlugin: IHeftLifecyclePlugin = plugins[pluginIndex++]; try { // Apply the plugin. We know the session should exist because we generated it above. lifecyclePlugin.apply( lifecycleContext.lifecycleSession!, this.#internalHeftSession.heftConfiguration, lifecycleContext.pluginOptions ); } catch (error) { throw new Error( `Error applying plugin ${JSON.stringify(pluginDefinition.pluginName)} from package ` + `${JSON.stringify(pluginDefinition.pluginPackageName)}: ${error}` ); } } // Do a second pass to apply the plugin access requests for each plugin pluginIndex = 0; for (const [pluginDefinition] of this.#lifecycleContextByDefinition) { const lifecyclePlugin: IHeftLifecyclePlugin = plugins[pluginIndex++]; this.resolvePluginAccessRequests(lifecyclePlugin, pluginDefinition); } } public async ensureInitializedAsync(): Promise { if (!this.#isInitialized) { this.#isInitialized = true; // Load up all plugin configurations concurrently const pluginConfigurationPromises: Promise[] = []; for (const pluginSpecifier of this.#lifecyclePluginSpecifiers) { const { pluginPackageRoot, pluginPackage } = pluginSpecifier; pluginConfigurationPromises.push( HeftPluginConfiguration.loadFromPackageAsync(pluginPackageRoot, pluginPackage) ); } // Promise.all maintains the order of the input array const pluginConfigurations: HeftPluginConfiguration[] = await Promise.all(pluginConfigurationPromises); // Iterate through and generate the lifecycle context for each plugin let pluginConfigurationIndex: number = 0; for (const pluginSpecifier of this.#lifecyclePluginSpecifiers) { const pluginConfiguration: HeftPluginConfiguration = pluginConfigurations[pluginConfigurationIndex++]; const pluginDefinition: HeftPluginDefinitionBase = pluginConfiguration.getPluginDefinitionBySpecifier(pluginSpecifier); // Ensure the plugin is a lifecycle plugin const isLifecyclePlugin: boolean = pluginConfiguration.isLifecyclePluginDefinition(pluginDefinition); if (!isLifecyclePlugin) { throw new Error( `Plugin ${JSON.stringify(pluginDefinition.pluginName)} from package ` + `${JSON.stringify(pluginSpecifier.pluginPackage)} is not a lifecycle plugin.` ); } // Ensure there are no duplicate plugin names within the same package if (this.#lifecycleContextByDefinition.has(pluginDefinition)) { throw new Error( `Lifecycle plugin ${JSON.stringify(pluginDefinition.pluginName)} from package ` + `${JSON.stringify(pluginSpecifier.pluginPackage)} cannot be specified more than once.` ); } // Validate the plugin options const pluginOptions: object | undefined = pluginSpecifier.options; pluginDefinition.validateOptions(pluginOptions); // Partially populate the context. The session will be populated while applying the plugins. const lifecycleContext: IHeftLifecycleContext = { pluginOptions }; this.#lifecycleContextByDefinition.set(pluginDefinition, lifecycleContext); } } } public get lifecycleLogger(): ScopedLogger { let logger: ScopedLogger | undefined = this.#lifecycleLogger; if (!logger) { logger = this.#internalHeftSession.loggingManager.requestScopedLogger(`lifecycle`); this.#lifecycleLogger = logger; } return logger; } public async getSessionForPluginDefinitionAsync( pluginDefinition: HeftLifecyclePluginDefinition ): Promise { await this.ensureInitializedAsync(); const lifecycleContext: IHeftLifecycleContext | undefined = this.#lifecycleContextByDefinition.get(pluginDefinition); if (!lifecycleContext) { throw new InternalError( `Could not find lifecycle context for plugin ${JSON.stringify(pluginDefinition.pluginName)}.` ); } if (!lifecycleContext.lifecycleSession) { throw new InternalError( `Lifecycle session for plugin ${JSON.stringify( pluginDefinition.pluginName )} has not been created yet.` ); } return lifecycleContext.lifecycleSession; } async #getLifecyclePluginForPluginDefinitionAsync( pluginDefinition: HeftLifecyclePluginDefinition, lifecycleSession: IHeftLifecycleSession ): Promise> { let lifecyclePlugin: IHeftPlugin | undefined = this.#lifecyclePluginsByDefinition.get(pluginDefinition); if (!lifecyclePlugin) { lifecyclePlugin = await pluginDefinition.loadPluginAsync(lifecycleSession.logger); this.#lifecyclePluginsByDefinition.set(pluginDefinition, lifecyclePlugin); } return lifecyclePlugin; } }