// Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
// See LICENSE in the project root for license information.
///
import * as path from 'node:path';
import type { SpawnSyncReturns } from 'node:child_process';
import { JsonFile, type JsonObject, Executable } from '@rushstack/node-core-library';
import {
tryFindRushJsonLocation,
RUSH_LIB_NAME,
type RushLibModuleType,
requireRushLibUnderFolderPath,
sdkContext
} from './helpers';
declare const global: typeof globalThis & {
___rush___rushLibModule?: RushLibModuleType;
___rush___rushLibModuleFromEnvironment?: RushLibModuleType;
___rush___rushLibModuleFromInstallAndRunRush?: RushLibModuleType;
};
/**
* Type of {@link ISdkCallbackEvent.logMessage}
* @public
*/
export interface IProgressBarCallbackLogMessage {
/**
* A status message to print in the log window, or `undefined` if there are
* no further messages. This string may contain newlines.
*/
text: string;
/**
* The type of message. More message types may be added in the future.
*/
kind: 'info' | 'debug';
}
/**
* Event options for {@link ILoadSdkAsyncOptions.onNotifyEvent}
* @public
*/
export interface ISdkCallbackEvent {
/**
* Allows the caller to display log information about the operation.
*/
logMessage: IProgressBarCallbackLogMessage | undefined;
/**
* Allows the caller to display a progress bar for long-running operations.
*
* @remarks
* If a long-running operation is required, then `progressPercent` will
* start at 0.0 and count upwards and finish at 100.0 if the operation completes
* successfully. If the long-running operation has not yet started, or
* is not required, then the value will be `undefined`.
*/
progressPercent: number | undefined;
}
/**
* Type of {@link ILoadSdkAsyncOptions.onNotifyEvent}
* @public
*/
export type SdkNotifyEventCallback = (sdkEvent: ISdkCallbackEvent) => void;
/**
* Options for {@link RushSdkLoader.loadAsync}
* @public
*/
export interface ILoadSdkAsyncOptions {
/**
* The folder to start from when searching for the Rush workspace configuration.
* If this folder does not contain a `rush.json` file, then each parent folder
* will be searched. If `rush.json` is not found, then the SDK fails to load.
*/
rushJsonSearchFolder?: string;
/**
* A cancellation token that the caller can use to prematurely abort the operation.
*/
abortSignal?: AbortSignal;
/**
* Allows the caller to monitor the progress of the operation.
*/
onNotifyEvent?: SdkNotifyEventCallback;
}
/**
* Exposes operations that control how the `@microsoft/rush-lib` engine is
* located and loaded.
* @public
*/
export class RushSdkLoader {
/**
* Returns true if the Rush engine has already been loaded.
*/
public static get isLoaded(): boolean {
return sdkContext.rushLibModule !== undefined;
}
/**
* Manually load the Rush engine based on rush.json found for `rushJsonSearchFolder`.
* Throws an exception if {@link RushSdkLoader.isLoaded} is already `true`.
*
* @remarks
* This API supports an callback that can be used display a progress bar,
* log of operations, and allow the operation to be canceled prematurely.
*/
public static async loadAsync(options?: ILoadSdkAsyncOptions): Promise {
// SCENARIO 5: The rush-lib engine is loaded manually using rushSdkLoader.loadAsync().
if (!options) {
options = {};
}
if (RushSdkLoader.isLoaded) {
throw new Error('RushSdkLoader.loadAsync() failed because the Rush engine has already been loaded');
}
const onNotifyEvent: SdkNotifyEventCallback | undefined = options.onNotifyEvent;
let progressPercent: number | undefined = undefined;
const abortSignal: AbortSignal | undefined = options.abortSignal;
try {
const rushJsonSearchFolder: string = options.rushJsonSearchFolder ?? process.cwd();
if (onNotifyEvent) {
onNotifyEvent({
logMessage: {
kind: 'debug',
text: `Searching for rush.json starting from: ` + rushJsonSearchFolder
},
progressPercent
});
}
const rushJsonPath: string | undefined = tryFindRushJsonLocation(rushJsonSearchFolder);
if (!rushJsonPath) {
throw new Error(
'Unable to find rush.json in the specified folder or its parent folders:\n' +
`${rushJsonSearchFolder}\n`
);
}
const monorepoRoot: string = path.dirname(rushJsonPath);
const rushJson: JsonObject = await JsonFile.loadAsync(rushJsonPath);
const { rushVersion } = rushJson;
const installRunNodeModuleFolder: string = path.join(
monorepoRoot,
`common/temp/install-run/@microsoft+rush@${rushVersion}`
);
try {
// First, try to load the version of "rush-lib" that was installed by install-run-rush.js
if (onNotifyEvent) {
onNotifyEvent({
logMessage: {
kind: 'info',
text: `Trying to load ${RUSH_LIB_NAME} installed by install-run-rush`
},
progressPercent
});
}
sdkContext.rushLibModule = requireRushLibUnderFolderPath(installRunNodeModuleFolder);
} catch (e1) {
let installAndRunRushStderrContent: string = '';
try {
const installAndRunRushJSPath: string = path.join(
monorepoRoot,
'common/scripts/install-run-rush.js'
);
if (onNotifyEvent) {
onNotifyEvent({
logMessage: {
kind: 'info',
text: 'The Rush engine has not been installed yet. Invoking install-run-rush.js...'
},
progressPercent
});
}
// Start the installation
progressPercent = 0;
const installAndRunRushProcess: SpawnSyncReturns = Executable.spawnSync(
'node',
[installAndRunRushJSPath, '--help'],
{
stdio: 'pipe'
}
);
installAndRunRushStderrContent = installAndRunRushProcess.stderr;
if (installAndRunRushProcess.status !== 0) {
throw new Error(`The ${RUSH_LIB_NAME} package failed to install`);
}
if (abortSignal) {
_checkForCancel(abortSignal, onNotifyEvent, progressPercent);
}
// TODO: Implement incremental progress updates
progressPercent = 90;
// Retry to load "rush-lib" after install-run-rush run
if (onNotifyEvent) {
onNotifyEvent({
logMessage: {
kind: 'debug',
text: `Trying to load ${RUSH_LIB_NAME} installed by install-run-rush a second time`
},
progressPercent
});
}
sdkContext.rushLibModule = requireRushLibUnderFolderPath(installRunNodeModuleFolder);
progressPercent = 100;
} catch (e2) {
// eslint-disable-next-line no-console
console.error(`${installAndRunRushStderrContent}`);
throw new Error(`The ${RUSH_LIB_NAME} package failed to load`);
}
}
if (sdkContext.rushLibModule !== undefined) {
// to track which scenario is active and how it got initialized.
global.___rush___rushLibModuleFromInstallAndRunRush = sdkContext.rushLibModule;
if (onNotifyEvent) {
onNotifyEvent({
logMessage: {
kind: 'debug',
text: `Loaded ${RUSH_LIB_NAME} installed by install-run-rush`
},
progressPercent
});
}
}
} catch (e) {
if (onNotifyEvent) {
onNotifyEvent({
logMessage: {
kind: 'info',
text: 'The operation failed: ' + (e.message ?? 'An unknown error occurred')
},
progressPercent
});
}
throw e;
}
}
}
/**
* Throws an "AbortError" exception if abortSignal.aborted is true.
*/
function _checkForCancel(
abortSignal: AbortSignal,
onNotifyEvent: SdkNotifyEventCallback | undefined,
progressPercent: number | undefined
): void {
if (!abortSignal?.aborted) {
return;
}
if (onNotifyEvent) {
onNotifyEvent({
logMessage: {
kind: 'info',
text: `The operation was canceled`
},
progressPercent
});
}
const error: Error = new Error('The operation was canceled');
error.name = 'AbortError';
throw error;
}