[rush] Bring back the Variants feature.

apps/lockfile-explorer/src/cli/lint/actions/CheckAction.ts

@@ -102,7 +102,7 @@ export class CheckAction extends CommandLineAction {
 
     const projectFolder: string = project.projectFolder;
     const subspace: Subspace = project.subspace;
-    const shrinkwrapFilename: string = subspace.getCommittedShrinkwrapFilename();
+    const shrinkwrapFilename: string = subspace.getCommittedShrinkwrapFilePath();
     let doc: Lockfile | LockfileV6;
     if (this._docMap.has(shrinkwrapFilename)) {
       doc = this._docMap.get(shrinkwrapFilename)!;

common/changes/@microsoft/rush/bring-back-variants_2024-09-18-21-01.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush",
+      "comment": "Bring back the Variants feature that was removed in https://github.com/microsoft/rushstack/pull/4538.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush"
+}

common/changes/@rushstack/lockfile-explorer/bring-back-variants_2024-09-19-19-58.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/lockfile-explorer",
+      "comment": "Update to use a new API from rush-sdk.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/lockfile-explorer"
+}

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

@@ -18,6 +18,7 @@ import { IPackageJson } from '@rushstack/node-core-library';
 import { IPrefixMatch } from '@rushstack/lookup-by-path';
 import { ITerminal } from '@rushstack/terminal';
 import { ITerminalProvider } from '@rushstack/terminal';
+import { JsonNull } from '@rushstack/node-core-library';
 import { JsonObject } from '@rushstack/node-core-library';
 import { LookupByPath } from '@rushstack/lookup-by-path';
 import { PackageNameParser } from '@rushstack/node-core-library';
@@ -128,7 +129,7 @@ export class CommonVersionsConfiguration {
     getAllPreferredVersions(): Map<string, string>;
     getPreferredVersionsHash(): string;
     readonly implicitlyPreferredVersions: boolean | undefined;
-    static loadFromFile(jsonFilename: string, rushConfiguration?: RushConfiguration): CommonVersionsConfiguration;
+    static loadFromFile(jsonFilePath: string, rushConfiguration?: RushConfiguration): CommonVersionsConfiguration;
     readonly preferredVersions: Map<string, string>;
     save(): boolean;
 }
@@ -258,6 +259,7 @@ export const EnvironmentVariableNames: {
     readonly RUSH_PREVIEW_VERSION: "RUSH_PREVIEW_VERSION";
     readonly RUSH_ALLOW_UNSUPPORTED_NODEJS: "RUSH_ALLOW_UNSUPPORTED_NODEJS";
     readonly RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD: "RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD";
+    readonly RUSH_VARIANT: "RUSH_VARIANT";
     readonly RUSH_PARALLELISM: "RUSH_PARALLELISM";
     readonly RUSH_ABSOLUTE_SYMLINKS: "RUSH_ABSOLUTE_SYMLINKS";
     readonly RUSH_PNPM_STORE_PATH: "RUSH_PNPM_STORE_PATH";
@@ -1126,7 +1128,7 @@ export class RepoStateFile {
     get packageJsonInjectedDependenciesHash(): string | undefined;
     get pnpmShrinkwrapHash(): string | undefined;
     get preferredVersionsHash(): string | undefined;
-    refreshState(rushConfiguration: RushConfiguration, subspace: Subspace | undefined): boolean;
+    refreshState(rushConfiguration: RushConfiguration, subspace: Subspace | undefined, variant?: string): boolean;
 }
 
 // @public
@@ -1159,6 +1161,11 @@ export class RushConfiguration {
     readonly commonTempFolder: string;
     // @deprecated
     get commonVersions(): CommonVersionsConfiguration;
+    readonly currentVariantJsonFilePath: string;
+    // Warning: (ae-forgotten-export) The symbol "ICurrentVariantJson" needs to be exported by the entry point index.d.ts
+    //
+    // @internal (undocumented)
+    _currentVariantJsonLoadingPromise: Promise<ICurrentVariantJson | undefined> | undefined;
     // @beta
     readonly customTipsConfiguration: CustomTipsConfiguration;
     // @beta
@@ -1176,12 +1183,13 @@ export class RushConfiguration {
     findProjectByShorthandName(shorthandProjectName: string): RushConfigurationProject | undefined;
     findProjectByTempName(tempProjectName: string): RushConfigurationProject | undefined;
     // @deprecated (undocumented)
-    getCommittedShrinkwrapFilename(subspace?: Subspace): string;
+    getCommittedShrinkwrapFilename(subspace?: Subspace, variant?: string): string;
     // @deprecated (undocumented)
-    getCommonVersions(subspace?: Subspace): CommonVersionsConfiguration;
+    getCommonVersions(subspace?: Subspace, variant?: string): CommonVersionsConfiguration;
     // @deprecated (undocumented)
-    getCommonVersionsFilePath(subspace?: Subspace): string;
-    getImplicitlyPreferredVersions(subspace?: Subspace): Map<string, string>;
+    getCommonVersionsFilePath(subspace?: Subspace, variant?: string): string;
+    getCurrentlyInstalledVariantAsync(): Promise<string | undefined>;
+    getImplicitlyPreferredVersions(subspace?: Subspace, variant?: string): Map<string, string>;
     // @deprecated (undocumented)
     getPnpmfilePath(subspace?: Subspace): string;
     getProjectByName(projectName: string): RushConfigurationProject | undefined;
@@ -1201,8 +1209,6 @@ export class RushConfiguration {
     readonly gitSampleEmail: string;
     readonly gitTagSeparator: string | undefined;
     readonly gitVersionBumpCommitMessage: string | undefined;
-    // @internal @deprecated
-    readonly _hasVariantsField: boolean;
     readonly hotfixChangeEnabled: boolean;
     static loadFromConfigurationFile(rushJsonFilename: string): RushConfiguration;
     // (undocumented)
@@ -1261,6 +1267,8 @@ export class RushConfiguration {
     tryGetSubspace(subspaceName: string): Subspace | undefined;
     // (undocumented)
     static tryLoadFromDefaultLocation(options?: ITryFindRushJsonLocationOptions): RushConfiguration | undefined;
+    // @beta
+    readonly variants: ReadonlySet<string>;
     // @beta (undocumented)
     readonly versionPolicyConfiguration: VersionPolicyConfiguration;
     // @beta (undocumented)
@@ -1368,6 +1376,7 @@ export class RushConstants {
     static readonly rushTempNpmScope: '@rush-temp';
     static readonly rushTempProjectsFolderName: 'projects';
     static readonly rushUserConfigurationFolderName: '.rush-user';
+    static readonly rushVariantsFolderName: 'variants';
     static readonly rushWebSiteUrl: 'https://rushjs.io';
     static readonly subspacesConfigFilename: 'subspaces.json';
     // (undocumented)
@@ -1391,8 +1400,8 @@ export class _RushInternals {
 
 // @beta
 export class RushLifecycleHooks {
-    readonly afterInstall: AsyncSeriesHook<[IRushCommand, Subspace]>;
-    readonly beforeInstall: AsyncSeriesHook<[IGlobalCommand, Subspace]>;
+    readonly afterInstall: AsyncSeriesHook<[IRushCommand, Subspace, string | undefined]>;
+    readonly beforeInstall: AsyncSeriesHook<[IGlobalCommand, Subspace, string | undefined]>;
     readonly flushTelemetry: AsyncParallelHook<[ReadonlyArray<ITelemetryData>]>;
     readonly initialize: AsyncSeriesHook<IRushCommand>;
     readonly runAnyGlobalCustomCommand: AsyncSeriesHook<IGlobalCommand>;
@@ -1458,14 +1467,16 @@ export class Subspace {
     _addProject(project: RushConfigurationProject): void;
     // @beta
     contains(project: RushConfigurationProject): boolean;
-    // @beta
+    // @deprecated (undocumented)
     getCommittedShrinkwrapFilename(): string;
     // @beta
-    getCommonVersions(): CommonVersionsConfiguration;
+    getCommittedShrinkwrapFilePath(variant?: string): string;
     // @beta
-    getCommonVersionsFilePath(): string;
+    getCommonVersions(variant?: string): CommonVersionsConfiguration;
     // @beta
-    getPackageJsonInjectedDependenciesHash(): string | undefined;
+    getCommonVersionsFilePath(variant?: string): string;
+    // @beta
+    getPackageJsonInjectedDependenciesHash(variant?: string): string | undefined;
     // @beta
     getPnpmConfigFilePath(): string;
     // @beta
@@ -1486,10 +1497,14 @@ export class Subspace {
     getSubspaceTempFolderPath(): string;
     // @beta
     getTempShrinkwrapFilename(): string;
-    // @beta
+    // @deprecated (undocumented)
     getTempShrinkwrapPreinstallFilename(subspaceName?: string | undefined): string;
     // @beta
-    get shouldEnsureConsistentVersions(): boolean;
+    getTempShrinkwrapPreinstallFilePath(): string;
+    // @beta
+    getVariantDependentSubspaceConfigFolderPath(variant: string | undefined): string;
+    // @beta
+    shouldEnsureConsistentVersions(variant?: string): boolean;
     // (undocumented)
     readonly subspaceName: string;
 }

libraries/rush-lib/assets/rush-init/rush.json

@@ -273,6 +273,39 @@
     "postRushx": []
   },
 
+  /**
+   * Installation variants allow you to maintain a parallel set of configuration files that can be
+   * used to build the entire monorepo with an alternate set of dependencies.  For example, suppose
+   * you upgrade all your projects to use a new release of an important framework, but during a transition period
+   * you intend to maintain compatibility with the old release.  In this situation, you probably want your
+   * CI validation to build the entire repo twice: once with the old release, and once with the new release.
+   *
+   * Rush "installation variants" correspond to sets of config files located under this folder:
+   *
+   *   common/config/rush/variants/<variant_name>
+   *
+   * The variant folder can contain an alternate common-versions.json file.  Its "preferredVersions" field can be used
+   * to select older versions of dependencies (within a loose SemVer range specified in your package.json files).
+   * To install a variant, run "rush install --variant <variant_name>".
+   *
+   * For more details and instructions, see this article:  https://rushjs.io/pages/advanced/installation_variants/
+   */
+   "variants": [
+    /*[BEGIN "HYPOTHETICAL"]*/
+    {
+      /**
+       * The folder name for this variant.
+       */
+      "variantName": "old-sdk",
+
+      /**
+       * An informative description
+       */
+      "description": "Build this repo using the previous release of the SDK"
+    }
+    /*[END "HYPOTHETICAL"]*/
+  ],
+
   /**
    * Rush can collect anonymous telemetry about everyday developer activity such as
    * success/failure of installs, builds, and other operations.  You can use this to identify

libraries/rush-lib/src/api/CommonVersionsConfiguration.ts

@@ -185,16 +185,16 @@ export class CommonVersionsConfiguration {
    * If the file has not been created yet, then an empty object is returned.
    */
   public static loadFromFile(
-    jsonFilename: string,
+    jsonFilePath: string,
     rushConfiguration?: RushConfiguration
   ): CommonVersionsConfiguration {
     let commonVersionsJson: ICommonVersionsJson | undefined = undefined;
 
-    if (FileSystem.exists(jsonFilename)) {
-      commonVersionsJson = JsonFile.loadAndValidate(jsonFilename, CommonVersionsConfiguration._jsonSchema);
+    if (FileSystem.exists(jsonFilePath)) {
+      commonVersionsJson = JsonFile.loadAndValidate(jsonFilePath, CommonVersionsConfiguration._jsonSchema);
     }
 
-    return new CommonVersionsConfiguration(commonVersionsJson, jsonFilename, rushConfiguration);
+    return new CommonVersionsConfiguration(commonVersionsJson, jsonFilePath, rushConfiguration);
   }
 
   private static _deserializeTable<TValue>(

libraries/rush-lib/src/api/EnvironmentConfiguration.ts

@@ -50,6 +50,14 @@ export const EnvironmentVariableNames = {
    */
   RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD: 'RUSH_ALLOW_WARNINGS_IN_SUCCESSFUL_BUILD',
 
+  /**
+   * This variable selects a specific installation variant for Rush to use when installing
+   * and linking package dependencies.
+   * For more information, see the command-line help for the `--variant` parameter
+   * and this article:  https://rushjs.io/pages/advanced/installation_variants/
+   */
+  RUSH_VARIANT: 'RUSH_VARIANT',
+
   /**
    * Specifies the maximum number of concurrent processes to launch during a build.
    * For more information, see the command-line help for the `--parallelism` parameter for "rush build".
@@ -533,6 +541,7 @@ export class EnvironmentConfiguration {
 
           case EnvironmentVariableNames.RUSH_PARALLELISM:
           case EnvironmentVariableNames.RUSH_PREVIEW_VERSION:
+          case EnvironmentVariableNames.RUSH_VARIANT:
           case EnvironmentVariableNames.RUSH_DEPLOY_TARGET_FOLDER:
             // Handled by @microsoft/rush front end
             break;