codeql.ts

import * as fs from "fs";
import * as path from "path";

import * as core from "@actions/core";
import * as toolrunner from "@actions/exec/lib/toolrunner";
import * as yaml from "js-yaml";
import * as semver from "semver";

import {
  CommandInvocationError,
  getActionVersion,
  getOptionalInput,
  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 type { ActionConfig } from "./config/action-config";
import { appendExtraQueryExclusions, type Config } from "./config-utils";
import { DocUrl } from "./doc-url";
import { EnvVar, getEnv, Env, ReadOnlyEnv } from "./environment";
import { getErrorMessage, isDiskConfigurationError } from "./errors";
import {
  CodeQLDefaultVersionInfo,
  Feature,
  FeatureEnablement,
} from "./feature-flags";
import { isAnalyzingDefaultBranch } from "./git-utils";
import { Language } from "./languages";
import type { Logger } from "./logging";
import { writeBaseDatabaseOidsFile, writeOverlayChangesFile } from "./overlay";
import { OverlayDatabaseMode } from "./overlay/overlay-database-mode";
import * as setupCodeql from "./setup-codeql";
import { ToolsDownloadStatusReport } from "./tools-download";
import { ToolsFeature, isSupportedToolsFeature } from "./tools-features";
import { shouldEnableIndirectTracing } from "./tracer-config";
import * as util from "./util";
import { BuildMode, CleanupLevel } from "./util";

export { isDiskConfigurationError } from "./errors";

type Options = Array<string | number | boolean>;

/**
 * Extra command line options for the codeql commands.
 */
interface ExtraOptions {
  "*"?: Options;
  database?: {
    "*"?: Options;
    init?: Options;
    "trace-command"?: Options;
    analyze?: Options;
    finalize?: Options;
  };
  resolve?: {
    "*"?: Options;
    extractor?: Options;
    queries?: Options;
  };
  github?: {
    "*"?: Options;
    "merge-results"?: Options;
  };
}

export interface CodeQL {
  /**
   * Get the path of the CodeQL executable.
   */
  getPath(): string;
  /**
   * Get a string containing the semver version of the CodeQL executable.
   */
  getVersion(): Promise<VersionInfo>;
  /**
   * Determines whether the CLI installation represented by this {@link CodeQL} instance
   * has at least the {@link requiredVersion}.
   */
  isVersionAtLeast(requiredVersion: string): Promise<boolean>;
  /**
   * Print version information about CodeQL.
   */
  printVersion(): Promise<void>;
  /**
   * Returns whether the CodeQL executable supports the specified feature.
   */
  supportsFeature(feature: ToolsFeature): Promise<boolean>;
  /**
   * Returns whether the provided language is traced.
   */
  isTracedLanguage(language: Language): Promise<boolean>;
  /**
   * Returns whether the provided language is scanned.
   */
  isScannedLanguage(language: Language): Promise<boolean>;
  /**
   * Run 'codeql database init --db-cluster'.
   */
  databaseInitCluster(
    config: Config,
    sourceRoot: string,
    processName: string | undefined,
    qlconfigFile: string | undefined,
  ): Promise<void>;
  /**
   * Runs the autobuilder for the given language.
   */
  runAutobuild(config: Config, language: Language): Promise<void>;
  /**
   * Extract code for a scanned language using 'codeql database trace-command'
   * and running the language extractor.
   */
  extractScannedLanguage(config: Config, language: Language): Promise<void>;
  /**
   * Extract code with 'codeql database trace-command --use-build-mode'. This can only be used when
   * the database specifies a build mode. This requires the `traceCommandUseBuildMode` tool feature.
   */
  extractUsingBuildMode(config: Config, language: Language): Promise<void>;
  /**
   * Finalize a database using 'codeql database finalize'.
   */
  finalizeDatabase(
    databasePath: string,
    threadsFlag: string,
    memoryFlag: string,
    enableDebugLogging: boolean,
  ): Promise<void>;
  /**
   * Run 'codeql resolve languages' with '--format=betterjson'.
   */
  resolveLanguages(options?: {
    filterToLanguagesWithQueries: boolean;
  }): Promise<ResolveLanguagesOutput>;
  /**
   * Run 'codeql resolve build-environment'
   */
  resolveBuildEnvironment(
    workingDir: string | undefined,
    language: string,
  ): Promise<ResolveBuildEnvironmentOutput>;

  /**
   * Clean up all the databases within a database cluster.
   */
  databaseCleanupCluster(
    config: Config,
    cleanupLevel: CleanupLevel,
  ): Promise<void>;
  /**
   * Run 'codeql database bundle'.
   *
   * @param alsoIncludeRelativePaths Additional paths that should be included in the bundle if
   * supported by the version of the CodeQL CLI.
   *
   * These paths are relative to the database root.
   *
   * Older versions of the CodeQL CLI do not support including additional paths in the bundle.
   * In those cases, this parameter will be ignored.
   */
  databaseBundle(
    databasePath: string,
    outputFilePath: string,
    dbName: string,
    includeDiagnostics: boolean,
    alsoIncludeRelativePaths: string[],
  ): Promise<void>;
  /**
   * Run 'codeql database run-queries'. If no `queries` are specified, then the CLI
   * will automatically use the `config-queries.qls` (if it exists) or default queries
   * for the language.
   */
  databaseRunQueries(
    databasePath: string,
    flags: string[],
    queries?: string[],
  ): Promise<void>;
  /**
   * Run 'codeql database interpret-results'.
   */
  databaseInterpretResults(
    databasePath: string,
    querySuitePaths: string[] | undefined,
    sarifFile: string,
    threadsFlag: string,
    verbosityFlag: string | undefined,
    sarifRunPropertyFlag: string | undefined,
    automationDetailsId: string | undefined,
    config: Config,
    features: FeatureEnablement,
  ): Promise<string>;
  /**
   * Run 'codeql database export-diagnostics'
   *
   * Note that the "--sarif-include-diagnostics" option is always used, as the command should
   * only be run if the ExportDiagnosticsEnabled feature flag is on.
   */
  databaseExportDiagnostics(
    databasePath: string,
    sarifFile: string,
    automationDetailsId: string | undefined,
  ): Promise<void>;
  /**
   * Run 'codeql diagnostics export'.
   */
  diagnosticsExport(
    sarifFile: string,
    automationDetailsId: string | undefined,
    config: ActionConfig<"tempDir">,
    diagnosticDir: string | undefined,
  ): Promise<void>;
  /** Get the location of an extractor for the specified language. */
  resolveExtractor(language: Language): Promise<string>;
  /**
   * Run 'codeql resolve queries --format=startingpacks'.
   */
  resolveQueriesStartingPacks(queries: string[]): Promise<string[]>;
  resolveDatabase(databasePath: string): Promise<ResolveDatabaseOutput>;
  /**
   * Run 'codeql github merge-results'.
   */
  mergeResults(
    sarifFiles: string[],
    outputFile: string,
    options: { mergeRunsFromEqualCategory?: boolean },
  ): Promise<void>;
}

export interface ResolveDatabaseOutput {
  overlayBaseSpecifier?: string;
}

export interface ResolveLanguagesOutput {
  aliases?: {
    [alias: string]: string;
  };
  extractors: {
    [language: string]: Array<{
      extractor_root: string;
      extractor_options?: any;
    }>;
  };
}

export interface ResolveBuildEnvironmentOutput {
  configuration?: {
    [language: string]: {
      [key: string]: unknown;
    };
  };
}

/**
 * Stores the CodeQL object, and is populated by `setupCodeQL` or `getCodeQL`.
 */
let cachedCodeQL: CodeQL | undefined = undefined;

/**
 * The oldest version of CodeQL that the Action will run with. This should be
 * at least three minor versions behind the current version and must include the
 * CLI versions shipped with each supported version of GHES.
 *
 * The version flags below can be used to conditionally enable certain features
 * on versions newer than this.
 */
const CODEQL_MINIMUM_VERSION = "2.20.7";

/**
 * This version will shortly become the oldest version of CodeQL that the Action will run with.
 */
const CODEQL_NEXT_MINIMUM_VERSION = "2.22.4";

/**
 * This is the version of GHES that was most recently deprecated.
 */
const GHES_VERSION_MOST_RECENTLY_DEPRECATED = "3.18";

/**
 * This is the deprecation date for the version of GHES that was most recently deprecated.
 */
const GHES_MOST_RECENT_DEPRECATION_DATE = "2026-10-16";

/** The CLI verbosity level to use for extraction in debug mode. */
const EXTRACTION_DEBUG_MODE_VERBOSITY = "progress++";

/**
 * Set up CodeQL CLI access.
 *
 * @param toolsInput
 * @param apiDetails
 * @param tempDir
 * @param variant
 * @param defaultCliVersion
 * @param rawLanguages Raw set of languages.
 * @param otherLanguagePacksReason Why the CodeQL CLI may need packs for languages other than
 *   `rawLanguages`, or `undefined` if it won't. If defined, the combined bundle is used. See
 *   `PerLanguageBundleOptions.otherLanguagePacksReason`.
 * @param useOverlayAwareDefaultCliVersion Whether to select an overlay-aware default CLI version.
 * @param features Information about the features that are enabled.
 * @param logger
 * @param checkVersion Whether to check that CodeQL CLI meets the minimum
 *        version requirement. Must be set to true outside tests.
 * @returns a { CodeQL, toolsVersion } object.
 */
export async function setupCodeQL(
  toolsInput: string | undefined,
  apiDetails: api.GitHubApiDetails,
  tempDir: string,
  variant: util.GitHubVariant,
  defaultCliVersion: CodeQLDefaultVersionInfo,
  rawLanguages: string[] | undefined,
  otherLanguagePacksReason: string | undefined,
  useOverlayAwareDefaultCliVersion: boolean,
  features: FeatureEnablement,
  logger: Logger,
  checkVersion: boolean,
): Promise<{
  codeql: CodeQL;
  toolsDownloadStatusReport?: ToolsDownloadStatusReport;
  toolsSource: setupCodeql.ToolsSource;
  toolsVersion: string;
}> {
  try {
    const {
      codeqlFolder,
      toolsDownloadStatusReport,
      toolsSource,
      toolsVersion,
    } = await setupCodeql.setupCodeQLBundle(
      toolsInput,
      apiDetails,
      tempDir,
      variant,
      defaultCliVersion,
      rawLanguages,
      otherLanguagePacksReason,
      useOverlayAwareDefaultCliVersion,
      features,
      logger,
    );

    let codeqlCmd = path.join(codeqlFolder, "codeql", "codeql");
    if (process.platform === "win32") {
      codeqlCmd += ".exe";
    } else if (process.platform !== "linux" && process.platform !== "darwin") {
      throw new util.ConfigurationError(
        `Unsupported platform: ${process.platform}`,
      );
    }

    cachedCodeQL = await getCodeQLForCmd(logger, codeqlCmd, checkVersion);
    return {
      codeql: cachedCodeQL,
      toolsDownloadStatusReport,
      toolsSource,
      toolsVersion,
    };
  } catch (rawError) {
    const e = api.wrapApiConfigurationError(rawError);
    const ErrorClass =
      e instanceof util.ConfigurationError || isDiskConfigurationError(e)
        ? util.ConfigurationError
        : Error;

    throw new ErrorClass(
      `Unable to download and extract CodeQL CLI: ${getErrorMessage(e)}${
        e instanceof Error && e.stack ? `\n\nDetails: ${e.stack}` : ""
      }`,
    );
  }
}

/**
 * Use the CodeQL executable located at the given path.
 */
export async function getCodeQL(logger: Logger, cmd: string): Promise<CodeQL> {
  if (cachedCodeQL === undefined) {
    cachedCodeQL = await getCodeQLForCmd(logger, cmd, true);
  }
  return cachedCodeQL;
}

/**
 * Overrides the CodeQL object. Only for use in tests that cannot override
 * CodeQL via dependency injection.
 *
 * Accepts a partial object. Any undefined methods will be implemented
 * to immediately throw an exception indicating which method is missing.
 */
export function setCodeQL(codeql: Partial<CodeQL>): void {
  cachedCodeQL = createStubCodeQL(codeql);
}

function resolveFunction<K extends keyof CodeQL, T extends CodeQL[K]>(
  partialCodeql: Partial<CodeQL>,
  methodName: K,
  defaultImplementation?: T,
): T {
  if (typeof partialCodeql[methodName] !== "function") {
    if (defaultImplementation !== undefined) {
      return defaultImplementation;
    }
    const dummyMethod = () => {
      throw new Error(`CodeQL ${methodName} method not correctly defined`);
    };
    return dummyMethod as unknown as T;
  }
  return partialCodeql[methodName] as T;
}

/**
 * Creates a stub CodeQL object. Only for use in tests.
 *
 * Accepts a partial object. Any undefined methods will be implemented
 * to immediately throw an exception indicating which method is missing.
 */
export function createStubCodeQL(partialCodeql: Partial<CodeQL>): CodeQL {
  return {
    getPath: resolveFunction(partialCodeql, "getPath", () => "/tmp/dummy-path"),
    getVersion: resolveFunction(partialCodeql, "getVersion", async () => ({
      version: "1.0.0",
    })),
    isVersionAtLeast: resolveFunction(
      partialCodeql,
      "isVersionAtLeast",
      async (requiredVersion) => {
        return (
          !!partialCodeql.getVersion &&
          semver.gte(
            (await partialCodeql.getVersion()).version,
            requiredVersion,
          )
        );
      },
    ),
    printVersion: resolveFunction(partialCodeql, "printVersion"),
    supportsFeature: resolveFunction(
      partialCodeql,
      "supportsFeature",
      async (feature) =>
        !!partialCodeql.getVersion &&
        isSupportedToolsFeature(await partialCodeql.getVersion(), feature),
    ),
    isTracedLanguage: resolveFunction(partialCodeql, "isTracedLanguage"),
    isScannedLanguage: resolveFunction(partialCodeql, "isScannedLanguage"),
    databaseInitCluster: resolveFunction(partialCodeql, "databaseInitCluster"),
    runAutobuild: resolveFunction(partialCodeql, "runAutobuild"),
    extractScannedLanguage: resolveFunction(
      partialCodeql,
      "extractScannedLanguage",
    ),
    extractUsingBuildMode: resolveFunction(
      partialCodeql,
      "extractUsingBuildMode",
    ),
    finalizeDatabase: resolveFunction(partialCodeql, "finalizeDatabase"),
    resolveLanguages: resolveFunction(
      partialCodeql,
      "resolveLanguages",
      async () => ({ aliases: {}, extractors: {} }),
    ),
    resolveBuildEnvironment: resolveFunction(
      partialCodeql,
      "resolveBuildEnvironment",
    ),
    databaseCleanupCluster: resolveFunction(
      partialCodeql,
      "databaseCleanupCluster",
    ),
    databaseBundle: resolveFunction(partialCodeql, "databaseBundle"),
    databaseRunQueries: resolveFunction(partialCodeql, "databaseRunQueries"),
    databaseInterpretResults: resolveFunction(
      partialCodeql,
      "databaseInterpretResults",
    ),
    databaseExportDiagnostics: resolveFunction(
      partialCodeql,
      "databaseExportDiagnostics",
    ),
    diagnosticsExport: resolveFunction(partialCodeql, "diagnosticsExport"),
    resolveExtractor: resolveFunction(partialCodeql, "resolveExtractor"),
    resolveQueriesStartingPacks: resolveFunction(
      partialCodeql,
      "resolveQueriesStartingPacks",
    ),
    resolveDatabase: resolveFunction(partialCodeql, "resolveDatabase"),
    mergeResults: resolveFunction(partialCodeql, "mergeResults"),
  };
}

/**
 * Return a CodeQL object for CodeQL CLI access.
 *
 * @param cmd Path to CodeQL CLI
 * @param checkVersion Whether to check that CodeQL CLI meets the minimum
 *        version requirement. Must be set to true outside tests.
 * @returns A new CodeQL object
 */
export async function getCodeQLForCmd(
  logger: Logger,
  cmd: string,
  checkVersion: boolean,
  env: Env = getEnv(),
): Promise<CodeQL> {
  const codeql: CodeQL = {
    getPath() {
      return cmd;
    },
    async getVersion() {
      const cacheFilePath = outputCache.getCommandCacheFilePath(env);
      let result = outputCache.getCachedCodeQlVersion(
        logger,
        cacheFilePath,
        cmd,
      );
      if (result === undefined) {
        result = await runCliJson<VersionInfo>(
          env,
          cmd,
          ["version", "--format=json"],
          {
            noStreamStdout: true,
          },
        );
        outputCache.cacheCodeQlVersion(cacheFilePath, cmd, result);
      }
      return result;
    },
    async isVersionAtLeast(requiredVersion: string) {
      return semver.gte((await this.getVersion()).version, requiredVersion);
    },
    async printVersion() {
      // Reuse the cached version information rather than invoking the CLI again.
      core.info(JSON.stringify(await this.getVersion(), null, 2));
    },
    async supportsFeature(feature: ToolsFeature) {
      return isSupportedToolsFeature(await this.getVersion(), feature);
    },
    async isTracedLanguage(language: Language) {
      const extractorPath = await this.resolveExtractor(language);
      const tracingConfigPath = path.join(
        extractorPath,
        "tools",
        "tracing-config.lua",
      );
      return fs.existsSync(tracingConfigPath);
    },
    async isScannedLanguage(language: Language) {
      return !(await this.isTracedLanguage(language));
    },
    async databaseInitCluster(
      config: Config,
      sourceRoot: string,
      processName: string | undefined,
      qlconfigFile: string | undefined,
    ) {
      const extraArgs = config.languages.map(
        (language) => `--language=${language}`,
      );
      if (await shouldEnableIndirectTracing(codeql, config)) {
        extraArgs.push("--begin-tracing");
        extraArgs.push(...(await getTrapCachingExtractorConfigArgs(config)));
        extraArgs.push(`--trace-process-name=${processName}`);
      }

      const codeScanningConfigFile = await writeCodeScanningConfigFile(
        config,
        logger,
      );
      const externalRepositoryToken = getOptionalInput(
        "external-repository-token",
      );
      extraArgs.push(`--codescanning-config=${codeScanningConfigFile}`);
      if (externalRepositoryToken) {
        extraArgs.push("--external-repository-token-stdin");
      }

      if (config.buildMode !== undefined) {
        extraArgs.push(`--build-mode=${config.buildMode}`);
      }
      if (qlconfigFile !== undefined) {
        extraArgs.push(`--qlconfig-file=${qlconfigFile}`);
      }

      const overlayDatabaseMode = config.overlayDatabaseMode;
      if (overlayDatabaseMode === OverlayDatabaseMode.Overlay) {
        const overlayChangesFile = await writeOverlayChangesFile(
          config,
          sourceRoot,
          logger,
        );
        extraArgs.push(`--overlay-changes=${overlayChangesFile}`);
      } else if (overlayDatabaseMode === OverlayDatabaseMode.OverlayBase) {
        extraArgs.push("--overlay-base");
      }

      const baselineFilesOptions = config.enableFileCoverageInformation
        ? [
            "--calculate-language-specific-baseline",
            "--sublanguage-file-coverage",
          ]
        : ["--no-calculate-baseline"];

      await runCli(
        env,
        cmd,
        [
          "database",
          "init",
          ...(overlayDatabaseMode === OverlayDatabaseMode.Overlay
            ? []
            : ["--force-overwrite"]),
          "--db-cluster",
          config.dbLocation,
          `--source-root=${sourceRoot}`,
          ...baselineFilesOptions,
          "--extractor-include-aliases",
          ...extraArgs,
          ...getExtraOptionsFromEnv(["database", "init"], {
            // Some user configs specify `--no-calculate-baseline` as an additional
            // argument to `codeql database init`. Therefore ignore the baseline file
            // options here to avoid specifying the same argument twice and erroring.
            //
            // Ignore `--overwrite` to avoid passing both `--force-overwrite` and `--overwrite` if
            // the user has configured `--overwrite`.
            ignoringOptions: [
              "--force-overwrite",
              "--overwrite",
              ...baselineFilesOptions,
            ],
          }),
        ],
        { stdin: externalRepositoryToken },
      );

      if (overlayDatabaseMode === OverlayDatabaseMode.OverlayBase) {
        await writeBaseDatabaseOidsFile(config, sourceRoot);
      }
    },
    async runAutobuild(config: Config, language: Language) {
      applyAutobuildAzurePipelinesTimeoutFix(env);

      const autobuildCmd = path.join(
        await this.resolveExtractor(language),
        "tools",
        process.platform === "win32" ? "autobuild.cmd" : "autobuild.sh",
      );

      // Bump the verbosity of the autobuild command if we're in debug mode
      if (config.debugMode) {
        env.set(
          EnvVar.CLI_VERBOSITY,
          env.getOptional(EnvVar.CLI_VERBOSITY) ??
            EXTRACTION_DEBUG_MODE_VERBOSITY,
        );
      }

      // On macOS, System Integrity Protection (SIP) typically interferes with
      // CodeQL build tracing of protected binaries.
      // The usual workaround is to prefix `$CODEQL_RUNNER` to build commands:
      // `$CODEQL_RUNNER` (not to be confused with the deprecated CodeQL Runner tool)
      // points to a simple wrapper binary included with the CLI, and the extra layer of
      // process indirection helps the tracer bypass SIP.

      // The above SIP workaround is *not* needed here.
      // At the `autobuild` step in the Actions workflow, we assume the `init` step
      // has successfully run, and will have exported `DYLD_INSERT_LIBRARIES`
      // into the environment of subsequent steps, to activate the tracer.
      // When `DYLD_INSERT_LIBRARIES` is set in the environment for a step,
      // the Actions runtime introduces its own workaround for SIP
      // (https://github.com/actions/runner/pull/416).
      await runCli(env, autobuildCmd);
    },
    async extractScannedLanguage(config: Config, language: Language) {
      await runCli(env, cmd, [
        "database",
        "trace-command",
        "--index-traceless-dbs",
        ...(await getTrapCachingExtractorConfigArgsForLang(config, language)),
        ...getExtractionVerbosityArguments(config.debugMode),
        ...getExtraOptionsFromEnv(["database", "trace-command"]),
        util.getCodeQLDatabasePath(config, language),
      ]);
    },
    async extractUsingBuildMode(config: Config, language: Language) {
      if (config.buildMode === BuildMode.Autobuild) {
        applyAutobuildAzurePipelinesTimeoutFix(env);
      }
      try {
        await runCli(env, cmd, [
          "database",
          "trace-command",
          "--use-build-mode",
          "--working-dir",
          process.cwd(),
          ...(await getTrapCachingExtractorConfigArgsForLang(config, language)),
          ...getExtractionVerbosityArguments(config.debugMode),
          ...getExtraOptionsFromEnv(["database", "trace-command"]),
          util.getCodeQLDatabasePath(config, language),
        ]);
      } catch (e) {
        if (config.buildMode === BuildMode.Autobuild) {
          const prefix =
            "We were unable to automatically build your code. " +
            "Please change the build mode for this language to manual and specify build steps " +
            `for your project. See ${DocUrl.AUTOMATIC_BUILD_FAILED} for more information.`;
          throw new util.ConfigurationError(`${prefix} ${getErrorMessage(e)}`);
        } else {
          throw e;
        }
      }
    },
    async finalizeDatabase(
      databasePath: string,
      threadsFlag: string,
      memoryFlag: string,
      enableDebugLogging: boolean,
    ) {
      const args = [
        "database",
        "finalize",
        "--finalize-dataset",
        threadsFlag,
        memoryFlag,
        ...getExtractionVerbosityArguments(enableDebugLogging),
        ...getExtraOptionsFromEnv(["database", "finalize"]),
        databasePath,
      ];
      await runCli(env, cmd, args);
    },
    async resolveLanguages(
      {
        filterToLanguagesWithQueries,
      }: {
        filterToLanguagesWithQueries: boolean;
      } = { filterToLanguagesWithQueries: false },
    ) {
      return runCliJson<ResolveLanguagesOutput>(env, cmd, [
        "resolve",
        "languages",
        "--format=betterjson",
        "--extractor-options-verbosity=4",
        "--extractor-include-aliases",
        // TODO: Unconditionally include `--filter-to-languages-with-queries`
        //       once CODEQL_MINIMUM_VERSION is at least v2.23.0
        //       — the first version to support this flag.
        ...(filterToLanguagesWithQueries
          ? ["--filter-to-languages-with-queries"]
          : []),
        ...getExtraOptionsFromEnv(["resolve", "languages"]),
      ]);
    },
    async resolveBuildEnvironment(
      workingDir: string | undefined,
      language: string,
    ) {
      const codeqlArgs = [
        "resolve",
        "build-environment",
        `--language=${language}`,
        "--extractor-include-aliases",
        ...getExtraOptionsFromEnv(["resolve", "build-environment"]),
      ];
      if (workingDir !== undefined) {
        codeqlArgs.push("--working-dir", workingDir);
      }
      return await runCliJson<ResolveBuildEnvironmentOutput>(
        env,
        cmd,
        codeqlArgs,
      );
    },
    async databaseRunQueries(
      databasePath: string,
      flags: string[],
      queries: string[] = [],
    ): Promise<void> {
      const codeqlArgs = [
        "database",
        "run-queries",
        ...flags,
        databasePath,
        "--min-disk-free=1024", // Try to leave at least 1GB free
        "-v",
        ...queries,
        ...getExtraOptionsFromEnv(["database", "run-queries"], {
          ignoringOptions: ["--expect-discarded-cache"],
        }),
      ];
      await runCli(env, cmd, codeqlArgs);
    },
    async databaseInterpretResults(
      databasePath: string,
      querySuitePaths: string[] | undefined,
      sarifFile: string,
      threadsFlag: string,
      verbosityFlag: string,
      sarifRunPropertyFlag: string | undefined,
      automationDetailsId: string | undefined,
      config: Config,
      features: FeatureEnablement,
    ): Promise<string> {
      const shouldExportDiagnostics = await features.getValue(
        Feature.ExportDiagnosticsEnabled,
        this,
      );
      const codeqlArgs = [
        "database",
        "interpret-results",
        threadsFlag,
        "--format=sarif-latest",
        verbosityFlag,
        `--output=${sarifFile}`,
        "--print-diagnostics-summary",
        "--print-metrics-summary",
        "--sarif-add-baseline-file-info",
        `--sarif-codescanning-config=${getGeneratedCodeScanningConfigPath(
          config,
        )}`,
        "--sarif-group-rules-by-pack",
        "--sarif-include-query-help=always",
        "--sublanguage-file-coverage",
        ...(await getJobRunUuidSarifOptions(env)),
        ...getExtraOptionsFromEnv(["database", "interpret-results"]),
      ];
      if (sarifRunPropertyFlag !== undefined) {
        codeqlArgs.push(sarifRunPropertyFlag);
      }
      if (automationDetailsId !== undefined) {
        codeqlArgs.push("--sarif-category", automationDetailsId);
      }
      if (shouldExportDiagnostics) {
        codeqlArgs.push("--sarif-include-diagnostics");
      } else {
        codeqlArgs.push("--no-sarif-include-diagnostics");
      }
      codeqlArgs.push(databasePath);
      if (querySuitePaths) {
        codeqlArgs.push(...querySuitePaths);
      }
      // Capture the stdout, which contains the analysis summary. Don't stream it to the Actions
      // logs to avoid printing it twice.
      return await runCli(env, cmd, codeqlArgs, {
        noStreamStdout: true,
      });
    },
    async databaseCleanupCluster(
      config: Config,
      cleanupLevel: CleanupLevel,
    ): Promise<void> {
      for (const language of config.languages) {
        const databasePath = util.getCodeQLDatabasePath(config, language);
        const codeqlArgs = [
          "database",
          "cleanup",
          databasePath,
          `--cache-cleanup=${cleanupLevel}`,
          ...getExtraOptionsFromEnv(["database", "cleanup"]),
        ];
        await runCli(env, cmd, codeqlArgs);
      }
    },
    async databaseBundle(
      databasePath: string,
      outputFilePath: string,
      databaseName: string,
      includeDiagnostics: boolean,
      alsoIncludeRelativePaths: string[],
    ): Promise<void> {
      const includeDiagnosticsArgs = includeDiagnostics
        ? ["--include-diagnostics"]
        : [];
      const args = [
        "database",
        "bundle",
        databasePath,
        `--output=${outputFilePath}`,
        `--name=${databaseName}`,
        ...includeDiagnosticsArgs,
        ...getExtraOptionsFromEnv(["database", "bundle"], {
          ignoringOptions: includeDiagnosticsArgs,
        }),
      ];
      if (
        await this.supportsFeature(ToolsFeature.BundleSupportsIncludeOption)
      ) {
        args.push(
          ...alsoIncludeRelativePaths.flatMap((relativePath) => [
            "--include",
            relativePath,
          ]),
        );
      }
      await new toolrunner.ToolRunner(cmd, args, {
        env: env.getDefined(),
      }).exec();
    },
    async databaseExportDiagnostics(
      databasePath: string,
      sarifFile: string,
      automationDetailsId: string | undefined,
    ): Promise<void> {
      const args = [
        "database",
        "export-diagnostics",
        `${databasePath}`,
        "--db-cluster", // Database is always a cluster for CodeQL versions that support diagnostics.
        "--format=sarif-latest",
        `--output=${sarifFile}`,
        "--sarif-include-diagnostics", // ExportDiagnosticsEnabled is always true if this command is run.
        "-vvv",
        ...getExtraOptionsFromEnv(["diagnostics", "export"]),
      ];
      if (automationDetailsId !== undefined) {
        args.push("--sarif-category", automationDetailsId);
      }
      await new toolrunner.ToolRunner(cmd, args, {
        env: env.getDefined(),
      }).exec();
    },
    async diagnosticsExport(
      sarifFile: string,
      automationDetailsId: string | undefined,
      config: ActionConfig<"tempDir">,
      diagnosticDir: string | undefined,
    ): Promise<void> {
      // We may be exporting diagnostics for a failed SARIF, in which case the configuration
      // file may not have been written to disk and there may not be a database. The CLI
      // will produce a SARIF for diagnostics from `diagnosticDir` without it. Therefore,
      // we check whether `configPath` exists and only provide it to the CLI if it does.
      // Although not needed, the CLI will produce an error if it
      // is provided with an argument to `--sarif-codescanning-config` that does not exist.
      let configPath: string | undefined =
        getGeneratedCodeScanningConfigPath(config);

      if (!fs.existsSync(configPath)) {
        // Warn if there is no configuration file, even though `config` claims that `init`
        // was successful. This shouldn't be happening.
        if (config.successfullyInitialised) {
          logger.warning(
            [
              `Expected a configuration file at '${configPath}', which does not exist.`,
              "Continuing with diagnostics export anyway, without a configuration file.",
            ].join(" "),
          );
        }

        configPath = undefined;
      }

      const args = [
        "diagnostics",
        "export",
        "--format=sarif-latest",
        `--output=${sarifFile}`,
        ...(configPath !== undefined
          ? [`--sarif-codescanning-config=${configPath}`]
          : []),
        ...(diagnosticDir !== undefined
          ? [`--diagnostic-dir=${diagnosticDir}`]
          : []),
        ...getExtraOptionsFromEnv(["diagnostics", "export"]),
      ];
      if (automationDetailsId !== undefined) {
        args.push("--sarif-category", automationDetailsId);
      }
      await new toolrunner.ToolRunner(cmd, args, {
        env: env.getDefined(),
      }).exec();
    },
    async resolveExtractor(language: Language): Promise<string> {
      // Request it using `format=json` so we don't need to strip the trailing new line generated by
      // the CLI.
      let extractorPath = "";
      await new toolrunner.ToolRunner(
        cmd,
        [
          "resolve",
          "extractor",
          "--format=json",
          `--language=${language}`,
          "--extractor-include-aliases",
          "-J-XX:-UsePerfData",
          ...getExtraOptionsFromEnv(["resolve", "extractor"]),
        ],
        {
          env: env.getDefined(),
          silent: true,
          listeners: {
            stdout: (data) => {
              extractorPath += data.toString();
            },
            stderr: (data) => {
              process.stderr.write(data);
            },
          },
        },
      ).exec();
      try {
        return JSON.parse(extractorPath) as string;
      } catch (err) {
        throw new Error(
          `Failed to parse extractor path for '${language}' from CLI: ${getErrorMessage(err)}\nOutput was: ${extractorPath}`,
        );
      }
    },
    async resolveQueriesStartingPacks(queries: string[]): Promise<string[]> {
      const codeqlArgs = [
        "resolve",
        "queries",
        "--format=startingpacks",
        ...getExtraOptionsFromEnv(["resolve", "queries"]),
        ...queries,
      ];
      return await runCliJson<string[]>(env, cmd, codeqlArgs, {
        noStreamStdout: true,
      });
    },
    async resolveDatabase(
      databasePath: string,
    ): Promise<ResolveDatabaseOutput> {
      const codeqlArgs = [
        "resolve",
        "database",
        databasePath,
        "--format=json",
        ...getExtraOptionsFromEnv(["resolve", "database"]),
      ];
      return await runCliJson<ResolveDatabaseOutput>(env, cmd, codeqlArgs, {
        noStreamStdout: true,
      });
    },
    async mergeResults(
      sarifFiles: string[],
      outputFile: string,
      {
        mergeRunsFromEqualCategory = false,
      }: { mergeRunsFromEqualCategory?: boolean },
    ): Promise<void> {
      const args = [
        "github",
        "merge-results",
        "--output",
        outputFile,
        ...getExtraOptionsFromEnv(["github", "merge-results"]),
      ];

      for (const sarifFile of sarifFiles) {
        args.push("--sarif", sarifFile);
      }

      if (mergeRunsFromEqualCategory) {
        args.push("--sarif-merge-runs-from-equal-category");
      }

      await runCli(env, cmd, args);
    },
  };
  // To ensure that status reports include the CodeQL CLI version wherever
  // possible, we want to call getVersion(), which populates the version value
  // used by status reporting, at the earliest opportunity. But invoking
  // getVersion() directly here breaks tests that only pretend to create a
  // CodeQL object. So instead we rely on the assumption that all non-test
  // callers would set checkVersion to true, and util.codeQlVersionAbove()
  // would call getVersion(), so the CLI version would be cached as soon as the
  // CodeQL object is created.
  if (
    checkVersion &&
    !(await codeql.isVersionAtLeast(CODEQL_MINIMUM_VERSION))
  ) {
    throw new util.ConfigurationError(
      `Expected a CodeQL CLI with version at least ${CODEQL_MINIMUM_VERSION} but got version ${
        (await codeql.getVersion()).version
      }`,
    );
  } else if (
    checkVersion &&
    env.getOptional(EnvVar.SUPPRESS_DEPRECATED_SOON_WARNING) !== "true" &&
    !(await codeql.isVersionAtLeast(CODEQL_NEXT_MINIMUM_VERSION))
  ) {
    const result = await codeql.getVersion();
    core.warning(
      `CodeQL CLI version ${result.version} was discontinued on ` +
        `${GHES_MOST_RECENT_DEPRECATION_DATE} alongside GitHub Enterprise Server ` +
        `${GHES_VERSION_MOST_RECENTLY_DEPRECATED} and will not be supported by the next minor ` +
        `release of the CodeQL Action. Please update to CodeQL CLI version ` +
        `${CODEQL_NEXT_MINIMUM_VERSION} or later. For instance, if you have specified a custom ` +
        "version of the CLI using the 'tools' input to the 'init' Action, you can remove this " +
        "input to use the default version.\n\n" +
        "Alternatively, if you want to continue using CodeQL CLI version " +
        `${result.version}, you can replace 'github/codeql-action/*@v${
          getActionVersion().split(".")[0]
        }' by 'github/codeql-action/*@v${getActionVersion()}' in your code scanning workflow to ` +
        "continue using this version of the CodeQL Action.",
    );
    env.export(EnvVar.SUPPRESS_DEPRECATED_SOON_WARNING, "true");
  }
  return codeql;
}

/**
 * Gets the options for `path` of `options` as an array of extra option strings.
 *
 * @param paths The CLI command components to get extra options for.
 * @param args Additional arguments for this function.
 * @param args.ignoringOptions
 *   Options that should be ignored, for example because they have already
 *   been passed and it is an error to pass them more than once.
 */
function getExtraOptionsFromEnv(
  paths: string[],
  { ignoringOptions }: { ignoringOptions?: string[] } = {},
) {
  const options: ExtraOptions = util.getExtraOptionsEnvParam();
  return getExtraOptions(options, paths, []).filter(
    (option) => !ignoringOptions?.includes(option),
  );
}

/**
 * Gets `options` as an array of extra option strings.
 *
 * - throws an exception mentioning `pathInfo` if this conversion is impossible.
 */
function asExtraOptions(options: any, pathInfo: string[]): string[] {
  if (options === undefined) {
    return [];
  }
  if (!Array.isArray(options)) {
    const msg = `The extra options for '${pathInfo.join(
      ".",
    )}' ('${JSON.stringify(options)}') are not in an array.`;
    throw new Error(msg);
  }
  return options.map((o) => {
    const t = typeof o;
    if (t !== "string" && t !== "number" && t !== "boolean") {
      const msg = `The extra option for '${pathInfo.join(
        ".",
      )}' ('${JSON.stringify(o)}') is not a primitive value.`;
      throw new Error(msg);
    }
    return `${o}`;
  });
}

/**
 * Gets the options for `path` of `options` as an array of extra option strings.
 *
 * - the special terminal step name '*' in `options` matches all path steps
 * - throws an exception if this conversion is impossible.
 *
 * Exported for testing.
 */
export function getExtraOptions(
  options: any,
  paths: string[],
  pathInfo: string[],
): string[] {
  const all = asExtraOptions(options?.["*"], pathInfo.concat("*"));
  const specific =
    paths.length === 0
      ? asExtraOptions(options, pathInfo)
      : getExtraOptions(
          options?.[paths[0]],
          paths?.slice(1),
          pathInfo.concat(paths[0]),
        );
  return all.concat(specific);
}

async function runCli(
  env: ReadOnlyEnv,
  cmd: string,
  args: string[] = [],
  opts: { stdin?: string; noStreamStdout?: boolean } = {},
): Promise<string> {
  try {
    return await runTool(env, cmd, args, opts);
  } catch (e) {
    if (e instanceof CommandInvocationError) {
      throw wrapCliConfigurationError(new CliError(e));
    }
    throw e;
  }
}

/**
 * Wraps the command executor {@link runCli} and tries to parse the output as JSON.
 *
 * @param env The environment variables.
 * @param cmd The command to run.
 * @param args The arguments to pass to the command.
 * @param opts The options for running the command.
 * @param opts.stdin Optional string to pass to the command's standard input.
 * @param opts.noStreamStdout Optional boolean to indicate whether to stream the command's standard output.
 * @returns The parsed JSON output from the command.
 */
async function runCliJson<T>(
  env: ReadOnlyEnv,
  cmd: string,
  args: string[] = [],
  opts: { stdin?: string; noStreamStdout?: boolean } = {},
): Promise<T> {
  const output = await runCli(env, cmd, args, opts);
  try {
    return JSON.parse(output) as T;
  } catch (e) {
    throw Error(
      `Unexpected output from codeql ${args.join(" ")}: ${getErrorMessage(e)}`,
    );
  }
}

/**
 * Writes the code scanning configuration that is to be used by the CLI.
 *
 * @param config The CodeQL Action state to write.
 * @param logger The logger to use.
 *
 * @returns The path to the generated user configuration file.
 */
async function writeCodeScanningConfigFile(
  config: Config,
  logger: Logger,
): Promise<string> {
  const codeScanningConfigFile = getGeneratedCodeScanningConfigPath(config);

  // Apply the `extraQueryExclusions` from the CodeQL Action state to the CLI configuration.
  // We do this here at the latest possible point before passing the CLI configuration on to
  // the CLI so that the `extraQueryExclusions` appear after all user-configured `query-filters`.
  // See the comment in `applyExtraQueryExclusions` for more information, as well as
  // https://github.com/github/codeql-action/pull/2938
  const augmentedConfig = appendExtraQueryExclusions(
    config.extraQueryExclusions,
    config.computedConfig,
  );

  logger.info(
    `Writing augmented user configuration file to ${codeScanningConfigFile}`,
  );
  logger.startGroup("Augmented user configuration file contents");
  logger.info(yaml.dump(augmentedConfig));
  logger.endGroup();

  fs.writeFileSync(codeScanningConfigFile, yaml.dump(augmentedConfig));
  return codeScanningConfigFile;
}

// This constant sets the size of each TRAP cache in megabytes.
const TRAP_CACHE_SIZE_MB = 1024;

export async function getTrapCachingExtractorConfigArgs(
  config: Config,
): Promise<string[]> {
  const result: string[][] = [];
  for (const language of config.languages)
    result.push(
      await getTrapCachingExtractorConfigArgsForLang(config, language),
    );
  return result.flat();
}

export async function getTrapCachingExtractorConfigArgsForLang(
  config: Config,
  language: Language,
): Promise<string[]> {
  const cacheDir = config.trapCaches[language];
  if (cacheDir === undefined) return [];
  const write = await isAnalyzingDefaultBranch(getEnv(), config.repositoryRoot);
  return [
    `-O=${language}.trap.cache.dir=${cacheDir}`,
    `-O=${language}.trap.cache.bound=${TRAP_CACHE_SIZE_MB}`,
    `-O=${language}.trap.cache.write=${write}`,
  ];
}

/**
 * Get the path to the code scanning configuration generated by the CLI.
 *
 * This will not exist if the configuration is being parsed in the Action.
 */
function getGeneratedCodeScanningConfigPath(
  config: ActionConfig<"tempDir">,
): string {
  return path.resolve(config.tempDir, "user-config.yaml");
}

function getExtractionVerbosityArguments(
  enableDebugLogging: boolean,
): string[] {
  return enableDebugLogging
    ? [`--verbosity=${EXTRACTION_DEBUG_MODE_VERBOSITY}`]
    : [];
}

/**
 * Updates the `JAVA_TOOL_OPTIONS` environment variable to resolve an issue with Azure Pipelines
 * timing out connections after 4 minutes and Maven not properly handling closed connections.
 *
 * Without the fix, long build processes will timeout when pulling down Java packages
 * https://developercommunity.visualstudio.com/content/problem/292284/maven-hosted-agent-connection-timeout.html
 */
function applyAutobuildAzurePipelinesTimeoutFix(env: Env) {
  const javaToolOptions = env.getOptional("JAVA_TOOL_OPTIONS") ?? "";
  env.set(
    "JAVA_TOOL_OPTIONS",
    [
      ...javaToolOptions.split(/\s+/),
      "-Dhttp.keepAlive=false",
      "-Dmaven.wagon.http.pool=false",
    ].join(" "),
  );
}

async function getJobRunUuidSarifOptions(env: ReadOnlyEnv) {
  const jobRunUuid = env.getOptional(EnvVar.JOB_RUN_UUID);

  return jobRunUuid ? [`--sarif-run-property=jobRunUuid=${jobRunUuid}`] : [];
}