Add CachingKind enum to control whether to restore or store caches

src/analyze-action.ts

@@ -16,6 +16,7 @@ import {
 } from "./analyze";
 import { getApiDetails, getGitHubVersion } from "./api-client";
 import { runAutobuild } from "./autobuild";
+import { shouldStoreCache } from "./caching-utils";
 import { getCodeQL } from "./codeql";
 import { Config, getConfig } from "./config-utils";
 import { uploadDatabases } from "./database-upload";
@@ -330,7 +331,7 @@ async function run() {
     );
 
     // Store dependency cache(s) if dependency caching is enabled.
-    if (config.dependencyCachingEnabled) {
+    if (shouldStoreCache(config.dependencyCachingEnabled)) {
       await uploadDependencyCaches(config, logger);
     }
 

src/caching-utils.ts

@@ -1,5 +1,9 @@
+import * as core from "@actions/core";
+
+import { getOptionalInput, isDefaultSetup } from "./actions-util";
+import { EnvVar } from "./environment";
 import { Logger } from "./logging";
-import { tryGetFolderBytes } from "./util";
+import { isHostedRunner, tryGetFolderBytes } from "./util";
 
 /**
  * Returns the total size of all the specified paths.
@@ -16,3 +20,70 @@ export async function getTotalCacheSize(
   );
   return sizes.map((a) => a || 0).reduce((a, b) => a + b, 0);
 }
+
+/* Enumerates caching modes. */
+export enum CachingKind {
+  /** Do not restore or store any caches. */
+  None = "none",
+  /** Store caches, but do not restore any existing ones. */
+  Store = "store",
+  /** Restore existing caches, but do not store any new ones. */
+  Restore = "restore",
+  /** Restore existing caches, and store new ones. */
+  Full = "full",
+}
+
+/** Returns a value indicating whether new caches should be stored, based on `kind`. */
+export function shouldStoreCache(kind: CachingKind): boolean {
+  return kind === CachingKind.Full || kind === CachingKind.Store;
+}
+
+/** Returns a value indicating whether existing caches should be restored, based on `kind`. */
+export function shouldRestoreCache(kind: CachingKind): boolean {
+  return kind === CachingKind.Full || kind === CachingKind.Restore;
+}
+
+/**
+ * Parses the `upload` input into an `UploadKind`, converting unspecified and deprecated upload
+ * inputs appropriately.
+ */
+export function getCachingKind(input: string | undefined): CachingKind {
+  switch (input) {
+    case undefined:
+    case "none":
+    case "off":
+    case "false":
+      return CachingKind.None;
+    case "full":
+    case "on":
+    case "true":
+      return CachingKind.Full;
+    case "store":
+      return CachingKind.Store;
+    case "restore":
+      return CachingKind.Restore;
+    default:
+      core.warning(
+        `Unrecognized 'dependency-caching' input: ${input}. Defaulting to 'none'.`,
+      );
+      return CachingKind.None;
+  }
+}
+
+/** Determines whether dependency caching is enabled. */
+export function getDependencyCachingEnabled(): CachingKind {
+  // If the workflow specified something always respect that
+  const dependencyCaching =
+    getOptionalInput("dependency-caching") ||
+    process.env[EnvVar.DEPENDENCY_CACHING];
+  if (dependencyCaching !== undefined) return getCachingKind(dependencyCaching);
+
+  // On self-hosted runners which may have dependencies installed centrally, disable caching by default
+  if (!isHostedRunner()) return CachingKind.None;
+
+  // Disable in advanced workflows by default.
+  if (!isDefaultSetup()) return CachingKind.None;
+
+  // On hosted runners, enable dependency caching by default
+  return CachingKind.Full;
+}

src/config-utils.test.ts

@@ -7,6 +7,7 @@ import * as yaml from "js-yaml";
 import * as sinon from "sinon";
 
 import * as api from "./api-client";
+import { CachingKind } from "./caching-utils";
 import {
   CodeQL,
   getCachedCodeQL,
@@ -52,7 +53,7 @@ function createTestInitConfigInputs(
       configInput: undefined,
       buildModeInput: undefined,
       trapCachingEnabled: false,
-      dependencyCachingEnabled: false,
+      dependencyCachingEnabled: CachingKind.None,
       debugMode: false,
       debugArtifactName: "",
       debugDatabaseName: "",
@@ -348,7 +349,7 @@ test("load non-empty input", async (t) => {
       augmentationProperties: configUtils.defaultAugmentationProperties,
       trapCaches: {},
       trapCacheDownloadTime: 0,
-      dependencyCachingEnabled: false,
+      dependencyCachingEnabled: CachingKind.None,
     };
 
     const languagesInput = "javascript";

src/config-utils.ts

@@ -6,6 +6,7 @@ import * as yaml from "js-yaml";
 import * as semver from "semver";
 
 import * as api from "./api-client";
+import { CachingKind, getCachingKind } from "./caching-utils";
 import { CodeQL } from "./codeql";
 import { Feature, FeatureEnablement } from "./feature-flags";
 import { Language, parseLanguage } from "./languages";
@@ -137,8 +138,8 @@ export interface Config {
    */
   trapCacheDownloadTime: number;
 
-  /** A value indicating whether dependency caching is enabled. */
-  dependencyCachingEnabled: boolean;
+  /** A value indicating how dependency caching should be used. */
+  dependencyCachingEnabled: CachingKind;
 }
 
 /**
@@ -396,7 +397,7 @@ export interface InitConfigInputs {
   configInput: string | undefined;
   buildModeInput: string | undefined;
   trapCachingEnabled: boolean;
-  dependencyCachingEnabled: boolean;
+  dependencyCachingEnabled: string | undefined;
   debugMode: boolean;
   debugArtifactName: string;
   debugDatabaseName: string;
@@ -481,7 +482,7 @@ export async function getDefaultConfig({
     augmentationProperties,
     trapCaches,
     trapCacheDownloadTime,
-    dependencyCachingEnabled,
+    dependencyCachingEnabled: getCachingKind(dependencyCachingEnabled),
   };
 }
 
@@ -587,7 +588,7 @@ async function loadConfig({
     augmentationProperties,
     trapCaches,
     trapCacheDownloadTime,
-    dependencyCachingEnabled,
+    dependencyCachingEnabled: getCachingKind(dependencyCachingEnabled),
   };
 }
 

src/init-action.ts

@@ -13,9 +13,12 @@ import {
   getRequiredInput,
   getTemporaryDirectory,
   persistInputs,
-  isDefaultSetup,
 } from "./actions-util";
 import { getGitHubVersion } from "./api-client";
+import {
+  getDependencyCachingEnabled,
+  shouldRestoreCache,
+} from "./caching-utils";
 import { CodeQL } from "./codeql";
 import * as configUtils from "./config-utils";
 import { downloadDependencyCaches } from "./dependency-caching";
@@ -560,7 +563,7 @@ async function run() {
     }
 
     // Restore dependency cache(s), if they exist.
-    if (config.dependencyCachingEnabled) {
+    if (shouldRestoreCache(config.dependencyCachingEnabled)) {
       await downloadDependencyCaches(config.languages, logger);
     }
 
@@ -724,24 +727,6 @@ async function recordZstdAvailability(
   );
 }
 
-/** Determines whether dependency caching is enabled. */
-function getDependencyCachingEnabled(): boolean {
-  // If the workflow specified something always respect that
-  const dependencyCaching =
-    getOptionalInput("dependency-caching") ||
-    process.env[EnvVar.DEPENDENCY_CACHING];
-  if (dependencyCaching !== undefined) return dependencyCaching === "true";
-
-  // On self-hosted runners which may have dependencies installed centrally, disable caching by default
-  if (!isHostedRunner()) return false;
-
-  // Disable in advanced workflows by default.
-  if (!isDefaultSetup()) return false;
-
-  // On hosted runners, enable dependency caching by default
-  return true;
-}
-
 async function runWrapper() {
   try {
     await run();