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

[octogonz]

Summary

The Rush Stack VS Code extension works in debug mode but currently is broken when published to the marketplace, because it relies on @rushstack/rush-sdk to load rush-lib, but there is now way to specify the rushJsonSearchFolder to search for rush.json.

Details

Today, rush-sdk automatically discovers and loads rush-lib as part of a synchronous operation of require():

// Magic happens here:
const rushSdk = require('@rushstack/rush-sdk`);

For the VS Code extension, we need to carefully control when rush-lib is loaded, where it's loaded from, and report progress for the underlying npm install operation, and also cancel the installation if needed. The new API looks like this:

import { RushSdkLoader, ISdkCallbackEvent } from '@rushstack/rush-sdk/loader';

// Use an AbortController to cancel the operation after a certain time period
const abortController = new AbortController();
setTimeout(() => {
  abortController.abort();
}, 1000);

if (!RushSdkLoader.alreadyLoaded) {
  await RushSdkLoader.loadAsync({
    // the search for rush.json starts here:
    rushJsonSearchFolder: "path/to/my-repo/apps/my-app",

    abortSignal: abortController.signal,

    onNotifyEvent: (event: ISdkCallbackEvent) => {
      if (event.logMessage) {
        // Your tool can show progress about the loading:
        if (event.logMessage.kind === 'info') {
          console.log(event.logMessage.text);
        }
      }

      if (event.progressBarPercent !== undefined) {
        // If installation takes a long time, your tool can display a progress bar
        displayYourProgressBar(event.progressBarPercent);
      }
    }
  });
}

// Any subsequent attempts to call require() will return the same instance
// that was loaded above.
const rushSdk = require('@rushstack/rush-sdk');
const config = rushSdk.RushConfiguration.loadFromDefaultLocation();

The actual install currently still runs via Executable.spawnSync() so the async and progress monitoring will currently block the main thread and the progress bar jumps from 0 to 100%. We'll improve the underlying implementation in a future PR.

How it was tested

There are 5 scenarios for Rush SDK:

• Scenario 1: Rush plugins
• Scenario 2: Jest tests
• Scenario 3: Shell commands spawned by an already running Rush
• Scenario 4: Scripts that call require("@rushstack/rush-sdk")
• Scenario 5: This new rushSdkProxy.loadAsync() API for the VS Code extension

Impacted documentation

rush-sdk is currently considered "experimental" and only has README.md docs

@dmichon-msft @iclanton @william2958 @chengcyber

[iclanton]

Consider extracting this into an exported function (https://github.com/microsoft/rushstack/blob/main/libraries/rush-lib/src/scripts/install-run-rush.ts#L20-L44) and using it. Since this project is webpacked, that should be easy.

[octogonz]

@iclanton wrote:

Consider extracting this into an exported function (https://github.com/microsoft/rushstack/blob/main/libraries/rush-lib/src/scripts/install-run-rush.ts#L20-L44) and using it. Since this project is webpacked, that should be easy.

@dmichon-msft suggested the same thing in #4270 (comment)

I feel like we should get this PR merged to unblock further work on the VS Code extension, and then come back and improve rush-sdk in separate PRs.