[rush-sdk] Introduce a proxy API for customizing how rush-lib is loaded

common/changes/@microsoft/rush/octogonz-rush-sdk-proxy_2023-08-04-23-41.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "@rushstack/rush-sdk now exposes a proxy API for customizing how the Rush engine is loaded and monitoring progress",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/reviews/api/rush-sdk.api.md

@@ -0,0 +1,58 @@
+## API Report File for "@rushstack/rush-sdk"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+/// <reference types="node" />
+
+// @public
+export interface ILoadSdkAsyncOptions {
+    abortSignal?: AbortSignal;
+    onNotifyEvent?: SdkNotifyEventCallback;
+    rushJsonSearchFolder?: string;
+}
+
+// @public
+export interface IProgressBarCallbackLogMessage {
+    message: string;
+    messageType: 'info' | 'debug';
+}
+
+// @public
+export interface ISdkCallbackEvent {
+    logMessage: IProgressBarCallbackLogMessage | undefined;
+    progressBarPercent: number | undefined;
+    state: SdkCallbackState;
+}
+
+// @public
+export namespace rushSdkProxy {
+    export function loadAsync(options?: ILoadSdkAsyncOptions): Promise<void>;
+}
+
+// @public
+export type SdkCallbackState =
+/**
+* The task has started and is still running.
+*/
+'running'
+/**
+* The task has completed successfully. No further events will be fired.
+*/
+| 'succeeded'
+/**
+* The task was aborted by the caller. No further events will be fired.
+*/
+| 'aborted'
+/**
+* The task has failed due to an error. No further events will be fired.
+*/
+| 'failed';
+
+// @public
+export type SdkNotifyEventCallback = (sdkEvent: ISdkCallbackEvent) => void;
+
+// (No @packageDocumentation comment for this package)
+
+```

libraries/rush-sdk/config/api-extractor.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+  "mainEntryPointFilePath": "<projectFolder>/lib-shim/proxy.d.ts",
+
+  "apiReport": {
+    "enabled": true,
+    "reportFolder": "../../../common/reviews/api"
+  },
+
+  "docModel": {
+    "enabled": false,
+    "apiJsonFilePath": "../../../common/temp/api/<unscopedPackageName>.api.json"
+  },
+
+  "dtsRollup": {
+    "enabled": true,
+    "publicTrimmedFilePath": "<projectFolder>/dist/proxy.d.ts"
+  }
+}

libraries/rush-sdk/package.json

@@ -10,6 +10,17 @@
   "homepage": "https://rushjs.io",
   "main": "lib-shim/index.js",
   "typings": "dist/rush-lib.d.ts",
+  "exports": {
+    ".": "./lib-shim/index.js",
+    "./proxy": "./lib-shim/proxy.js"
+  },
+  "typesVersions": {
+    "*": {
+      "proxy": [
+        "./dist/proxy.d.ts"
+      ]
+    }
+  },
   "scripts": {
     "build": "heft build --clean",
     "_phase:build": "heft run --only build -- --clean",
@@ -29,6 +40,7 @@
     "@rushstack/stream-collator": "workspace:*",
     "@rushstack/ts-command-line": "workspace:*",
     "@rushstack/terminal": "workspace:*",
+    "@types/node": "14.18.36",
     "@types/semver": "7.5.0",
     "@types/webpack-env": "1.18.0"
   }

libraries/rush-sdk/src/helpers.ts

@@ -0,0 +1,71 @@
+// 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 'path';
+import { Import, FileSystem } from '@rushstack/node-core-library';
+import type { EnvironmentVariableNames } from '@microsoft/rush-lib';
+
+export const RUSH_LIB_NAME: '@microsoft/rush-lib' = '@microsoft/rush-lib';
+export const RUSH_LIB_PATH_ENV_VAR_NAME: typeof EnvironmentVariableNames.RUSH_LIB_PATH = '_RUSH_LIB_PATH';
+
+export type RushLibModuleType = Record<string, unknown>;
+
+export interface ISdkContext {
+  rushLibModule: RushLibModuleType | undefined;
+}
+
+export const sdkContext: ISdkContext = {
+  rushLibModule: undefined
+};
+
+/**
+ * Find the rush.json location and return the path, or undefined if a rush.json can't be found.
+ *
+ * @privateRemarks
+ * Keep this in sync with `RushConfiguration.tryFindRushJsonLocation`.
+ */
+export function tryFindRushJsonLocation(startingFolder: string): string | undefined {
+  let currentFolder: string = startingFolder;
+
+  // Look upwards at parent folders until we find a folder containing rush.json
+  for (let i: number = 0; i < 10; ++i) {
+    const rushJsonFilename: string = path.join(currentFolder, 'rush.json');
+
+    if (FileSystem.exists(rushJsonFilename)) {
+      return rushJsonFilename;
+    }
+
+    const parentFolder: string = path.dirname(currentFolder);
+    if (parentFolder === currentFolder) {
+      break;
+    }
+
+    currentFolder = parentFolder;
+  }
+
+  return undefined;
+}
+
+export function _require<TResult>(moduleName: string): TResult {
+  if (typeof __non_webpack_require__ === 'function') {
+    // If this library has been bundled with Webpack, we need to call the real `require` function
+    // that doesn't get turned into a `__webpack_require__` statement.
+    // `__non_webpack_require__` is a Webpack macro that gets turned into a `require` statement
+    // during bundling.
+    return __non_webpack_require__(moduleName);
+  } else {
+    return require(moduleName);
+  }
+}
+
+/**
+ * Require `@microsoft/rush-lib` under the specified folder path.
+ */
+export function requireRushLibUnderFolderPath(folderPath: string): RushLibModuleType {
+  const rushLibModulePath: string = Import.resolveModule({
+    modulePath: RUSH_LIB_NAME,
+    baseFolderPath: folderPath
+  });
+
+  return _require(rushLibModulePath);
+}