Persist CodeQL version output to file rather than environment

src/cli/output-cache.test.ts

@@ -0,0 +1,121 @@
+import * as fs from "fs";
+import path from "path";
+
+import test from "ava";
+
+import { EnvVar } from "../environment";
+import { getTestEnv, setupTests } from "../testing-utils";
+import * as util from "../util";
+
+import * as outputCache from "./output-cache";
+
+setupTests(test);
+
+test.serial(
+  "getCachedCodeQlVersion reuses a version persisted by an earlier step",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "codeql-action-command-cache.json");
+      fs.writeFileSync(
+        cacheFile,
+        JSON.stringify({
+          cmd: "/path/to/codeql",
+          entries: { version: { version: "2.20.0" } },
+        }),
+        "utf8",
+      );
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+      t.deepEqual(outputCache.getCachedCodeQlVersion(env, "/path/to/codeql"), {
+        version: "2.20.0",
+      });
+    });
+  },
+);
+
+test.serial(
+  "getCachedCodeQlVersion ignores a persisted version from a different CLI",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "version.json");
+      fs.writeFileSync(
+        cacheFile,
+        JSON.stringify({
+          cmd: "/path/to/other-codeql",
+          version: { version: "2.20.0" },
+        }),
+        "utf8",
+      );
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+      t.is(
+        outputCache.getCachedCodeQlVersion(env, "/path/to/codeql"),
+        undefined,
+      );
+    });
+  },
+);
+
+test.serial(
+  "getCachedCodeQlVersion ignores a malformed persisted value",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "version.json");
+      fs.writeFileSync(cacheFile, "not valid json", "utf8");
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+      t.is(
+        outputCache.getCachedCodeQlVersion(env, "/path/to/codeql"),
+        undefined,
+      );
+    });
+  },
+);
+
+test.serial(
+  "getCachedCodeQlVersion ignores a persisted value with the wrong structure",
+  async (t) => {
+    await util.withTmpDir(async (tmpDir: string) => {
+      const cacheFile = path.join(tmpDir, "version.json");
+      const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+
+      const testValues = [
+        { cmd: "/path/to/codeql" },
+        { entries: { version: { version: "2.20.0" } } },
+        { cmd: "/path/to/codeql", entries: {} },
+        { cmd: "/path/to/codeql", entries: { version: {} } },
+        { cmd: "/path/to/codeql", entries: { version: null } },
+        { cmd: "/path/to/codeql", entries: { version: "2.20.0" } },
+        { cmd: "/path/to/codeql", entries: { version: { version: null } } },
+        { cmd: "/path/to/codeql", entries: { version: { version: 2.2 } } },
+        { cmd: "/path/to/codeql", entries: { version: { version: 2 } } },
+        {
+          cmd: "/path/to/codeql",
+          entries: { version: { version: "2.20.0", overlayVersion: "1" } },
+        },
+        {
+          cmd: "/path/to/codeql",
+          entries: { version: { version: "2.20.0", features: "nope" } },
+        },
+      ].map((v) => JSON.stringify(v));
+
+      for (const value of testValues) {
+        fs.writeFileSync(cacheFile, value, "utf8");
+        t.is(
+          outputCache.getCachedCodeQlVersion(env, "/path/to/codeql"),
+          undefined,
+          value,
+        );
+      }
+    });
+  },
+);
+
+test.serial("getCachedCodeQlVersion ignores non-existent file", async (t) => {
+  await util.withTmpDir(async (tmpDir: string) => {
+    const env = getTestEnv({ [EnvVar.TEMP]: tmpDir });
+    t.notThrows(() => {
+      t.is(
+        outputCache.getCachedCodeQlVersion(env, "/path/to/codeql"),
+        undefined,
+      );
+    });
+  });
+});

src/cli/output-cache.ts

@@ -0,0 +1,160 @@
+import * as fs from "fs";
+import path from "path";
+
+import { getTemporaryDirectory } from "../actions-util";
+import { Env } from "../environment";
+
+import type { VersionInfo } from "./types";
+
+/**
+ * The keys of the command cache. Each key corresponds to a command whose output we cache.
+ */
+export enum CommandCacheKey {
+  Version = "version",
+}
+
+/**
+ * The mapping of CLI commands to the types of the output of each command that we cache.
+ */
+export type CommandCacheKeyOutputMap = {
+  [CommandCacheKey.Version]: VersionInfo;
+};
+
+/**
+ * The type of the command cache that is persisted to disk.
+ */
+export interface OutputCache<K extends CommandCacheKey> {
+  cmd: string;
+  entries: {
+    [P in K]: CommandCacheKeyOutputMap[K];
+  };
+}
+
+/**
+ * The name of the temporary file that backs the on-disk cache of
+ * CLI responses between workflow steps.
+ */
+const COMMAND_CACHE_FILENAME = "codeql-action-command-cache.json";
+
+/**
+ * The module-global variable that caches the CodeQL CLI version in-memory.
+ */
+let cachedCodeQlVersion: undefined | VersionInfo = undefined;
+
+/**
+ * Resets the in-process cache of the CodeQL CLI version. Only for use in tests,
+ * which exercise multiple "steps" within a single process.
+ */
+export function resetCachedCodeQlVersion(): void {
+  cachedCodeQlVersion = undefined;
+}
+
+/**
+ * Returns the path to the temporary file that backs the
+ * on-disk cache of CLI responses between workflow steps.
+ */
+function getCommandCacheFilePath(env: Env): string {
+  return path.join(getTemporaryDirectory(env), COMMAND_CACHE_FILENAME);
+}
+
+/**
+ * Caches the CodeQL CLI version both in-memory and on disk.
+ * @param cmd The path to the CodeQL CLI.
+ * @param version The version information to cache.
+ * @param env The environment variables to use.
+ */
+export function cacheCodeQlVersion(
+  cmd: string,
+  version: VersionInfo,
+  env: Env,
+): void {
+  if (cachedCodeQlVersion !== undefined) {
+    throw new Error("cacheCodeQlVersion() should be called only once");
+  }
+  cachedCodeQlVersion = version;
+  const outputCache = {
+    cmd,
+    entries: { [CommandCacheKey.Version]: version },
+  } satisfies OutputCache<CommandCacheKey.Version>;
+  // Persist the version so that subsequent Actions steps, which run in separate
+  // processes, can reuse it rather than invoking `codeql version` again. We
+  // record the CLI path so that a different step using a different CodeQL bundle
+  // doesn't pick up a stale version.
+  fs.writeFileSync(
+    getCommandCacheFilePath(env),
+    JSON.stringify(outputCache),
+    "utf8",
+  );
+}
+
+/**
+ * Returns the cached CodeQL CLI version, if any.
+ * @param env The environment variables to use.
+ * @param cmd The path to the CodeQL CLI.
+ */
+export function getCachedCodeQlVersion(
+  env: Env,
+  cmd?: string,
+): undefined | VersionInfo {
+  if (cachedCodeQlVersion !== undefined) {
+    return cachedCodeQlVersion;
+  }
+  // Fall back to the value persisted by an earlier Actions step, if any. This is
+  // best-effort: any malformed or mismatched value is ignored so that the caller
+  // invokes `codeql version` instead.
+  let serialized: string;
+  try {
+    serialized = fs.readFileSync(getCommandCacheFilePath(env), "utf8");
+  } catch {
+    return undefined;
+  }
+  let persisted: unknown;
+  try {
+    persisted = JSON.parse(serialized);
+  } catch {
+    return undefined;
+  }
+  if (
+    !isOutputCache(persisted) ||
+    (cmd !== undefined && persisted.cmd !== cmd)
+  ) {
+    return undefined;
+  }
+  // Memoize the parsed value so that subsequent calls in this process don't
+  // re-parse the environment variable.
+  cachedCodeQlVersion = persisted.entries[CommandCacheKey.Version];
+  return cachedCodeQlVersion;
+}
+
+/**
+ * Determines whether a value is a `VersionInfo` object.
+ * @param x The value to test
+ */
+function isVersionInfo(x: unknown): x is VersionInfo {
+  const candidate = x as Partial<VersionInfo> | null;
+  return (
+    typeof candidate === "object" &&
+    candidate !== null &&
+    typeof candidate.version === "string" &&
+    (candidate.features === undefined ||
+      (typeof candidate.features === "object" &&
+        candidate.features !== null)) &&
+    (candidate.overlayVersion === undefined ||
+      typeof candidate.overlayVersion === "number")
+  );
+}
+
+/**
+ * Determines whether a value is a `OutputCache` object.
+ * @param x The value to test
+ */
+function isOutputCache(x: unknown): x is OutputCache<CommandCacheKey.Version> {
+  const candidate = x as Partial<OutputCache<CommandCacheKey.Version>> | null;
+  return (
+    typeof candidate === "object" &&
+    candidate !== null &&
+    typeof candidate.cmd === "string" &&
+    candidate.entries !== undefined &&
+    isVersionInfo(candidate.entries[CommandCacheKey.Version])
+  );
+}

src/cli/types.ts

@@ -0,0 +1,13 @@
+export interface VersionInfo {
+  version: string;
+  features?: { [name: string]: boolean };
+  /**
+   * The overlay version helps deal with backward incompatible changes for
+   * overlay analysis. When a precompiled query pack reports the same overlay
+   * version as the CodeQL CLI, we can use the CodeQL CLI to perform overlay
+   * analysis with that pack. Otherwise, if the overlay versions are different,
+   * or if either the pack or the CLI does not report an overlay version,
+   * we need to revert to non-overlay analysis.
+   */
+  overlayVersion?: number;
+}

src/codeql.ts

@@ -12,10 +12,12 @@ import {
   runTool,
 } from "./actions-util";
 import * as api from "./api-client";
+import * as outputCache from "./cli/output-cache";
+import type { VersionInfo } from "./cli/types";
 import { CliError, wrapCliConfigurationError } from "./cli-errors";
 import { appendExtraQueryExclusions, type Config } from "./config-utils";
 import { DocUrl } from "./doc-url";
-import { EnvVar } from "./environment";
+import { EnvVar, getEnv } from "./environment";
 import {
   CodeQLDefaultVersionInfo,
   Feature,
@@ -215,20 +217,6 @@ export interface CodeQL {
   ): Promise<void>;
 }
 
-export interface VersionInfo {
-  version: string;
-  features?: { [name: string]: boolean };
-  /**
-   * The overlay version helps deal with backward incompatible changes for
-   * overlay analysis. When a precompiled query pack reports the same overlay
-   * version as the CodeQL CLI, we can use the CodeQL CLI to perform overlay
-   * analysis with that pack. Otherwise, if the overlay versions are different,
-   * or if either the pack or the CLI does not report an overlay version,
-   * we need to revert to non-overlay analysis.
-   */
-  overlayVersion?: number;
-}
-
 export interface ResolveDatabaseOutput {
   overlayBaseSpecifier?: string;
 }
@@ -502,7 +490,7 @@ async function getCodeQLForCmd(
       return cmd;
     },
     async getVersion() {
-      let result = util.getCachedCodeQlVersion(cmd);
+      let result = outputCache.getCachedCodeQlVersion(getEnv(), cmd);
       if (result === undefined) {
         result = await runCliJson<VersionInfo>(
           cmd,
@@ -511,7 +499,7 @@ async function getCodeQLForCmd(
             noStreamStdout: true,
           },
         );
-        util.cacheCodeQlVersion(cmd, result);
+        outputCache.cacheCodeQlVersion(cmd, result, getEnv());
       }
       return result;
     },

src/environment.ts

@@ -39,12 +39,6 @@ export enum EnvVar {
    */
   CODE_SCANNING_REF = "CODE_SCANNING_REF",
 
-  /**
-   * `PersistedVersionInfo` for the CodeQL CLI, so later Actions steps can reuse it instead of
-   * invoking `codeql version` again.
-   */
-  CODEQL_VERSION_INFO = "CODEQL_ACTION_CLI_VERSION_INFO",
-
   /** Whether the CodeQL Action has invoked the Go autobuilder. */
   DID_AUTOBUILD_GOLANG = "CODEQL_ACTION_DID_AUTOBUILD_GOLANG",
 

src/status-report.ts

@@ -14,6 +14,7 @@ import {
   isSelfHostedRunner,
 } from "./actions-util";
 import { getAnalysisKey, getApiClient } from "./api-client";
+import { getCachedCodeQlVersion } from "./cli/output-cache";
 import type { Config } from "./config/action-config";
 import type { ComputedInput, InputName } from "./config/inputs";
 import { parseRegistriesWithoutCredentials } from "./config/pack-registries";
@@ -30,7 +31,6 @@ import { registryBaseSchema } from "./start-proxy/types";
 import {
   ConfigurationError,
   getRequiredEnvParam,
-  getCachedCodeQlVersion,
   isInTestMode,
   GITHUB_DOTCOM_URL,
   DiskUsage,
@@ -376,7 +376,7 @@ export async function createStatusReportBase(
       core.exportVariable(EnvVar.WORKFLOW_STARTED_AT, workflowStartedAt);
     }
     const runnerOs = getRequiredEnvParam("RUNNER_OS");
-    const codeQlCliVersion = getCachedCodeQlVersion();
+    const codeQlCliVersion = getCachedCodeQlVersion(getEnv());
     const actionRef = process.env["GITHUB_ACTION_REF"] || "";
     const testingEnvironment = getTestingEnvironment();
     // re-export the testing environment variable so that it is available to subsequent steps,