Add support for RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH environment variable

Author: iclanton

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

@@ -238,6 +238,7 @@ export class EnvironmentConfiguration {
     static get buildCacheCredential(): string | undefined;
     static get buildCacheEnabled(): boolean | undefined;
     static get buildCacheOverrideJson(): string | undefined;
+    static get buildCacheOverrideJsonFilePath(): string | undefined;
     static get buildCacheWriteAllowed(): boolean | undefined;
     static get cobuildContextId(): string | undefined;
     static get cobuildLeafProjectLogOnlyAllowed(): boolean | undefined;
@@ -276,6 +277,7 @@ export const EnvironmentVariableNames: {
     readonly RUSH_BUILD_CACHE_ENABLED: "RUSH_BUILD_CACHE_ENABLED";
     readonly RUSH_BUILD_CACHE_WRITE_ALLOWED: "RUSH_BUILD_CACHE_WRITE_ALLOWED";
     readonly RUSH_BUILD_CACHE_OVERRIDE_JSON: "RUSH_BUILD_CACHE_OVERRIDE_JSON";
+    readonly RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH: "RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH";
     readonly RUSH_COBUILD_CONTEXT_ID: "RUSH_COBUILD_CONTEXT_ID";
     readonly RUSH_COBUILD_RUNNER_ID: "RUSH_COBUILD_RUNNER_ID";
     readonly RUSH_COBUILD_LEAF_PROJECT_LOG_ONLY_ALLOWED: "RUSH_COBUILD_LEAF_PROJECT_LOG_ONLY_ALLOWED";

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

@@ -220,13 +220,22 @@ export class BuildCacheConfiguration {
         `${EnvironmentVariableNames.RUSH_BUILD_CACHE_OVERRIDE_JSON} environment variable`
       );
     } else {
-      try {
-        buildCacheJson = await JsonFile.loadAndValidateAsync(jsonFilePath, BUILD_CACHE_JSON_SCHEMA);
-      } catch (e) {
-        if (!FileSystem.isNotExistError(e)) {
-          throw e;
-        } else {
-          return undefined;
+      const buildCacheOverrideJsonFilePath: string | undefined =
+        EnvironmentConfiguration.buildCacheOverrideJsonFilePath;
+      if (buildCacheOverrideJsonFilePath) {
+        buildCacheJson = await JsonFile.loadAndValidateAsync(
+          buildCacheOverrideJsonFilePath,
+          BUILD_CACHE_JSON_SCHEMA
+        );
+      } else {
+        try {
+          buildCacheJson = await JsonFile.loadAndValidateAsync(jsonFilePath, BUILD_CACHE_JSON_SCHEMA);
+        } catch (e) {
+          if (!FileSystem.isNotExistError(e)) {
+            throw e;
+          } else {
+            return undefined;
+          }
         }
       }
     }

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

@@ -150,9 +150,28 @@ export const EnvironmentVariableNames = {
    *
    * This is useful for testing purposes, or for OSS repos that are have a local-only cache, but can have
    * a different cache configuration in CI/CD pipelines.
+   *
+   * @remarks
+   * This is similar to {@link EnvironmentVariableNames.RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH}, but it allows you to specify
+   * a JSON string instead of a file path. The two environment variables are mutually exclusive, meaning you can
+   * only use one of them at a time.
    */
   RUSH_BUILD_CACHE_OVERRIDE_JSON: 'RUSH_BUILD_CACHE_OVERRIDE_JSON',
 
+  /**
+   * Set this environment variable to the path to a `build-cache.json` file to override the build cache configuration
+   * that normally lives at `common/config/rush/build-cache.json`.
+   *
+   * This is useful for testing purposes, or for OSS repos that are have a local-only cache, but can have
+   * a different cache configuration in CI/CD pipelines.
+   *
+   * @remarks
+   * This is similar to {@link EnvironmentVariableNames.RUSH_BUILD_CACHE_OVERRIDE_JSON}, but it allows you to specify
+   * a file path instead of a JSON string. The two environment variables are mutually exclusive, meaning you can
+   * only use one of them at a time.
+   */
+  RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH: 'RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH',
+
   /**
    * Setting this environment variable opts into running with cobuilds. The context id should be the same across
    * multiple VMs, but changed when it is a new round of cobuilds.
@@ -261,6 +280,8 @@ export class EnvironmentConfiguration {
 
   private static _buildCacheOverrideJson: string | undefined;
 
+  private static _buildCacheOverrideJsonFilePath: string | undefined;
+
   private static _cobuildContextId: string | undefined;
 
   private static _cobuildRunnerId: string | undefined;
@@ -380,6 +401,15 @@ export class EnvironmentConfiguration {
     return EnvironmentConfiguration._buildCacheOverrideJson;
   }
 
+  /**
+   * If set, overrides the build cache configuration that normally lives at `common/config/rush/build-cache.json`.
+   * See {@link EnvironmentVariableNames.RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH}
+   */
+  public static get buildCacheOverrideJsonFilePath(): string | undefined {
+    EnvironmentConfiguration._ensureValidated();
+    return EnvironmentConfiguration._buildCacheOverrideJsonFilePath;
+  }
+
   /**
    * Provides a determined cobuild context id if configured
    * See {@link EnvironmentVariableNames.RUSH_COBUILD_CONTEXT_ID}
@@ -542,6 +572,11 @@ export class EnvironmentConfiguration {
             break;
           }
 
+          case EnvironmentVariableNames.RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH: {
+            EnvironmentConfiguration._buildCacheOverrideJsonFilePath = value;
+            break;
+          }
+
           case EnvironmentVariableNames.RUSH_COBUILD_CONTEXT_ID: {
             EnvironmentConfiguration._cobuildContextId = value;
             break;
@@ -603,6 +638,17 @@ export class EnvironmentConfiguration {
       );
     }
 
+    if (
+      EnvironmentConfiguration._buildCacheOverrideJsonFilePath &&
+      EnvironmentConfiguration._buildCacheOverrideJson
+    ) {
+      throw new Error(
+        `Environment variable ${EnvironmentVariableNames.RUSH_BUILD_CACHE_OVERRIDE_JSON_FILE_PATH} and ` +
+          `${EnvironmentVariableNames.RUSH_BUILD_CACHE_OVERRIDE_JSON} are mutually exclusive. ` +
+          `Only one may be specified.`
+      );
+    }
+
     // See doc comment for EnvironmentConfiguration._getRushGlobalFolderOverride().
     EnvironmentConfiguration._rushGlobalFolderOverride =
       EnvironmentConfiguration._getRushGlobalFolderOverride(process.env);