Dump soon to be uploaded SARIF on request

This introduces a new internal environment variable flag
(`CODEQL_ACTION_SARIF_DUMP_DIR`) that, when set to `true`, causes the
SARIF file that will be uploaded to be dumped to the specified
directory. The filename will be `upload.sarif` or `upload.quality.sarif`
depending on the upload target.

src/environment.ts

@@ -119,4 +119,10 @@ export enum EnvVar {
    * Whether to enable experimental extractors for CodeQL.
    */
   EXPERIMENTAL_FEATURES = "CODEQL_ENABLE_EXPERIMENTAL_FEATURES",
+
+  /**
+   * Whether and where to dump the processed SARIF file that would be uploaded, regardless of
+   * whether the upload is disabled. This is intended for testing and debugging purposes.
+   */
+  SARIF_DUMP_DIR = "CODEQL_ACTION_SARIF_DUMP_DIR",
 }

src/upload-lib.ts

@@ -696,6 +696,12 @@ export async function uploadSpecifiedFiles(
   validateUniqueCategory(sarif, uploadTarget.sentinelPrefix);
   logger.debug(`Serializing SARIF for upload`);
   const sarifPayload = JSON.stringify(sarif);
+
+  const dumpDir = process.env[EnvVar.SARIF_DUMP_DIR];
+  if (dumpDir) {
+    dumpSarifFile(sarifPayload, dumpDir, logger, uploadTarget);
+  }
+
   logger.debug(`Compressing serialized SARIF`);
   const zippedSarif = zlib.gzipSync(sarifPayload).toString("base64");
   const checkoutURI = url.pathToFileURL(checkoutPath).href;
@@ -742,6 +748,30 @@ export async function uploadSpecifiedFiles(
   };
 }
 
+/**
+ * Dumps the given processed SARIF file contents to `outputDir`.
+ */
+function dumpSarifFile(
+  sarifPayload: string,
+  outputDir: string,
+  logger: Logger,
+  uploadTarget: analyses.AnalysisConfig,
+) {
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  } else if (!fs.lstatSync(outputDir).isDirectory()) {
+    throw new ConfigurationError(
+      `The path specified by the CODEQL_ACTION_SARIF_DUMP_DIR environment variable exists and is not a directory: ${outputDir}`,
+    );
+  }
+  const outputFile = path.resolve(
+    outputDir,
+    `upload${uploadTarget.sarifExtension}`,
+  );
+  logger.info(`Dumping processed SARIF file to ${outputFile}`);
+  fs.writeFileSync(outputFile, sarifPayload);
+}
+
 const STATUS_CHECK_FREQUENCY_MILLISECONDS = 5 * 1000;
 const STATUS_CHECK_TIMEOUT_MILLISECONDS = 2 * 60 * 1000;