Move logging messages to downstream function and add deprecation notice

CHANGELOG.md

@@ -12,7 +12,7 @@ No user facing changes.
 
 - Add a compatibility matrix of supported CodeQL Action, CodeQL CLI, and GitHub Enterprise Server versions to the [README.md](README.md). [#2273](https://github.com/github/codeql-action/pull/2273)
 - Avoid printing out a warning for a missing `on.push` trigger when the CodeQL Action is triggered via a `workflow_call` event. [#2274](https://github.com/github/codeql-action/pull/2274)
-- Add `tools: linked` option for input of `init` action. [#2281](https://github.com/github/codeql-action/pull/2281)
+- The `tools: latest` input to the `init` Action has been renamed to `tools: linked`. This option specifies that the Action should use the tools shipped at the same time as the Action. The old name will continue to work for backwards compatibility, but we recommend that new workflows use the new name. [#2281](https://github.com/github/codeql-action/pull/2281)
 
 ## 3.25.4 - 08 May 2024
 

lib/setup-codeql.js

@@ -226,6 +226,7 @@ async function getCodeQLSource(toolsInput, defaultCliVersion, apiDetails, varian
     if (toolsInput &&
         !CODEQL_BUNDLE_VERSION_ALIAS.includes(toolsInput) &&
         !toolsInput.startsWith("http")) {
+        logger.info("Using CodeQL CLI from local path $path");
         return {
             codeqlTarPath: toolsInput,
             sourceType: "local",
@@ -245,9 +246,11 @@ async function getCodeQLSource(toolsInput, defaultCliVersion, apiDetails, varian
      */
     const forceShippedTools = toolsInput && CODEQL_BUNDLE_VERSION_ALIAS.includes(toolsInput);
     if (forceShippedTools) {
-        logger.info("Overriding the version of the CodeQL tools by the version shipped with the Action since " +
+        logger.info(`Overriding the version of the CodeQL tools by ${defaultCliVersion.cliVersion}, the version shipped with the Action since ` +
-            `"tools: linked" or "tools: latest" was requested. The version shipped with the Action is ` +
+            `tools: ${toolsInput} was requested.`);
-            `${defaultCliVersion.cliVersion}.`);
+        if (toolsInput === "latest") {
+            logger.warning("The 'latest' alias for the CodeQL tools has been deprecated. Please use 'linked' instead.");
+        }
     }
     /** CLI version number, for example 2.12.6. */
     let cliVersion;
@@ -337,10 +340,12 @@ async function getCodeQLSource(toolsInput, defaultCliVersion, apiDetails, varian
         logger.info(`Did not find CodeQL tools version ${humanReadableVersion} in the toolcache.`);
     }
     if (codeqlFolder) {
+        const version = cliVersion ?? humanReadableVersion;
+        logger.info(`Using CodeQL CLI version ${version} from toolcache at ${codeqlFolder}`);
         return {
             codeqlFolder,
             sourceType: "toolcache",
-            toolsVersion: cliVersion ?? humanReadableVersion,
+            toolsVersion: version,
         };
     }
     // If we don't find the requested version on Enterprise, we may allow a
@@ -357,12 +362,14 @@ async function getCodeQLSource(toolsInput, defaultCliVersion, apiDetails, varian
     if (!url) {
         url = await getCodeQLBundleDownloadURL(tagName, apiDetails, logger);
     }
+    const toolsVersion = cliVersion ?? humanReadableVersion;
+    logger.info(`Using CodeQL CLI version ${toolsVersion} downloaded from ${url}.`);
     return {
         bundleVersion: tagName && tryGetBundleVersionFromTagName(tagName, logger),
         cliVersion,
         codeqlURL: url,
         sourceType: "download",
-        toolsVersion: cliVersion ?? humanReadableVersion,
+        toolsVersion,
     };
 }
 exports.getCodeQLSource = getCodeQLSource;
@@ -381,6 +388,8 @@ async function tryGetFallbackToolcacheVersion(cliVersion, tagName, logger) {
     return fallbackVersion;
 }
 exports.tryGetFallbackToolcacheVersion = tryGetFallbackToolcacheVersion;
+// Exported using `export const` for testing purposes. Specifically, we want to
+// be able to stub this function and have other functions in this file use that stub.
 const downloadCodeQL = async function (codeqlURL, maybeBundleVersion, maybeCliVersion, apiDetails, variant, tempDir, logger) {
     const parsedCodeQLURL = new URL(codeqlURL);
     const searchParams = new URLSearchParams(parsedCodeQLURL.search);
@@ -496,7 +505,6 @@ function getCanonicalToolcacheVersion(cliVersion, bundleVersion, logger) {
  */
 async function setupCodeQLBundle(toolsInput, apiDetails, tempDir, variant, defaultCliVersion, logger) {
     const source = await getCodeQLSource(toolsInput, defaultCliVersion, apiDetails, variant, logger);
-    logger.info(`Using CodeQL CLI version ${source.toolsVersion} from ${source.sourceType}.`);
     let codeqlFolder;
     let toolsVersion = source.toolsVersion;
     let toolsDownloadDurationMs;

lib/setup-codeql.test.js

@@ -93,14 +93,22 @@ ava_1.default.beforeEach(() => {
     });
 });
 (0, ava_1.default)("getCodeQLSource correctly returns bundled CLI version when tools == latest", async (t) => {
+    const loggedMessages = [];
+    const logger = (0, testing_utils_1.getRecordingLogger)(loggedMessages);
     await (0, util_1.withTmpDir)(async (tmpDir) => {
         (0, testing_utils_1.setupActionsVars)(tmpDir, tmpDir);
-        const source = await setupCodeql.getCodeQLSource("latest", testing_utils_1.SAMPLE_DEFAULT_CLI_VERSION, testing_utils_1.SAMPLE_DOTCOM_API_DETAILS, util_1.GitHubVariant.DOTCOM, (0, logging_1.getRunnerLogger)(true));
+        const source = await setupCodeql.getCodeQLSource("latest", testing_utils_1.SAMPLE_DEFAULT_CLI_VERSION, testing_utils_1.SAMPLE_DOTCOM_API_DETAILS, util_1.GitHubVariant.DOTCOM, logger);
+        // First, ensure that the CLI version is the linked version, so that backwards
+        // compatibility is maintained.
         t.is(source.toolsVersion, testing_utils_1.LINKED_CLI_VERSION.cliVersion);
         t.is(source.sourceType, "download");
+        // Afterwards, ensure that we see the deprecation message in the log.
+        const expected_message = "The 'latest' alias for the CodeQL tools has been deprecated. Please use 'linked' instead.";
+        t.assert(loggedMessages.some((msg) => typeof msg.message === "string" &&
+            msg.message.includes(expected_message)));
     });
 });
-(0, ava_1.default)("setupCodeQLBundle logs the CodeQL CLI version being used", async (t) => {
+(0, ava_1.default)("setupCodeQLBundle logs the CodeQL CLI version being used when asked to use linked tools", async (t) => {
     const loggedMessages = [];
     const logger = (0, testing_utils_1.getRecordingLogger)(loggedMessages);
     // Stub the downloadCodeQL function to prevent downloading artefacts
@@ -116,12 +124,34 @@ ava_1.default.beforeEach(() => {
         // Basic sanity check that the version we got back is indeed
         // the linked (default) CLI version.
         t.is(result.toolsVersion, testing_utils_1.LINKED_CLI_VERSION.cliVersion);
-        const expected_message = {
-            type: "info",
-            message: `Using CodeQL CLI version ${testing_utils_1.LINKED_CLI_VERSION.cliVersion} from download.`,
-        };
         // Ensure message logging CodeQL CLI version was present in user logs.
-        t.assert(loggedMessages.some((msg) => msg.message === expected_message.message));
+        const expected_message = `Using CodeQL CLI version ${testing_utils_1.LINKED_CLI_VERSION.cliVersion}`;
+        t.assert(loggedMessages.some((msg) => typeof msg.message === "string" &&
+            msg.message.includes(expected_message)));
+    });
+});
+(0, ava_1.default)("setupCodeQLBundle logs the CodeQL CLI version being used when asked to download a non-default bundle", async (t) => {
+    const loggedMessages = [];
+    const logger = (0, testing_utils_1.getRecordingLogger)(loggedMessages);
+    const bundleUrl = "https://github.com/github/codeql-action/releases/download/codeql-bundle-v2.16.0/codeql-bundle-linux64.tar.gz";
+    const expectedVersion = "2.16.0";
+    // Stub the downloadCodeQL function to prevent downloading artefacts
+    // during testing from being called.
+    sinon.stub(setupCodeql, "downloadCodeQL").resolves({
+        toolsVersion: expectedVersion,
+        codeqlFolder: "codeql",
+        toolsDownloadDurationMs: 200,
+    });
+    await (0, util_1.withTmpDir)(async (tmpDir) => {
+        (0, testing_utils_1.setupActionsVars)(tmpDir, tmpDir);
+        const result = await setupCodeql.setupCodeQLBundle(bundleUrl, testing_utils_1.SAMPLE_DOTCOM_API_DETAILS, "tmp/codeql_action_test/", util_1.GitHubVariant.DOTCOM, testing_utils_1.SAMPLE_DEFAULT_CLI_VERSION, logger);
+        // Basic sanity check that the version we got back is indeed the version that the
+        // bundle contains..
+        t.is(result.toolsVersion, expectedVersion);
+        // Ensure message logging CodeQL CLI version was present in user logs.
+        const expected_message = `Using CodeQL CLI version 2.16.0 downloaded from ${bundleUrl}.`;
+        t.assert(loggedMessages.some((msg) => typeof msg.message === "string" &&
+            msg.message.includes(expected_message)));
     });
 });
 //# sourceMappingURL=setup-codeql.test.js.map

src/setup-codeql.test.ts

@@ -114,6 +114,9 @@ test("getCodeQLSource correctly returns bundled CLI version when tools == linked
 });
 
 test("getCodeQLSource correctly returns bundled CLI version when tools == latest", async (t) => {
+  const loggedMessages: LoggedMessage[] = [];
+  const logger = getRecordingLogger(loggedMessages);
+
   await withTmpDir(async (tmpDir) => {
     setupActionsVars(tmpDir, tmpDir);
     const source = await setupCodeql.getCodeQLSource(
@@ -121,15 +124,28 @@ test("getCodeQLSource correctly returns bundled CLI version when tools == latest
       SAMPLE_DEFAULT_CLI_VERSION,
       SAMPLE_DOTCOM_API_DETAILS,
       GitHubVariant.DOTCOM,
-      getRunnerLogger(true),
+      logger,
     );
 
+    // First, ensure that the CLI version is the linked version, so that backwards
+    // compatibility is maintained.
     t.is(source.toolsVersion, LINKED_CLI_VERSION.cliVersion);
     t.is(source.sourceType, "download");
+
+    // Afterwards, ensure that we see the deprecation message in the log.
+    const expected_message: string =
+      "The 'latest' alias for the CodeQL tools has been deprecated. Please use 'linked' instead.";
+    t.assert(
+      loggedMessages.some(
+        (msg) =>
+          typeof msg.message === "string" &&
+          msg.message.includes(expected_message),
+      ),
+    );
   });
 });
 
-test("setupCodeQLBundle logs the CodeQL CLI version being used", async (t) => {
+test("setupCodeQLBundle logs the CodeQL CLI version being used when asked to use linked tools", async (t) => {
   const loggedMessages: LoggedMessage[] = [];
   const logger = getRecordingLogger(loggedMessages);
 
@@ -156,14 +172,57 @@ test("setupCodeQLBundle logs the CodeQL CLI version being used", async (t) => {
     // the linked (default) CLI version.
     t.is(result.toolsVersion, LINKED_CLI_VERSION.cliVersion);
 
-    const expected_message: LoggedMessage = {
-      type: "info",
-      message: `Using CodeQL CLI version ${LINKED_CLI_VERSION.cliVersion} from download.`,
-    };
-
     // Ensure message logging CodeQL CLI version was present in user logs.
+    const expected_message: string = `Using CodeQL CLI version ${LINKED_CLI_VERSION.cliVersion}`;
     t.assert(
-      loggedMessages.some((msg) => msg.message === expected_message.message),
+      loggedMessages.some(
+        (msg) =>
+          typeof msg.message === "string" &&
+          msg.message.includes(expected_message),
+      ),
+    );
+  });
+});
+
+test("setupCodeQLBundle logs the CodeQL CLI version being used when asked to download a non-default bundle", async (t) => {
+  const loggedMessages: LoggedMessage[] = [];
+  const logger = getRecordingLogger(loggedMessages);
+
+  const bundleUrl =
+    "https://github.com/github/codeql-action/releases/download/codeql-bundle-v2.16.0/codeql-bundle-linux64.tar.gz";
+  const expectedVersion = "2.16.0";
+
+  // Stub the downloadCodeQL function to prevent downloading artefacts
+  // during testing from being called.
+  sinon.stub(setupCodeql, "downloadCodeQL").resolves({
+    toolsVersion: expectedVersion,
+    codeqlFolder: "codeql",
+    toolsDownloadDurationMs: 200,
+  });
+
+  await withTmpDir(async (tmpDir) => {
+    setupActionsVars(tmpDir, tmpDir);
+    const result = await setupCodeql.setupCodeQLBundle(
+      bundleUrl,
+      SAMPLE_DOTCOM_API_DETAILS,
+      "tmp/codeql_action_test/",
+      GitHubVariant.DOTCOM,
+      SAMPLE_DEFAULT_CLI_VERSION,
+      logger,
+    );
+
+    // Basic sanity check that the version we got back is indeed the version that the
+    // bundle contains..
+    t.is(result.toolsVersion, expectedVersion);
+
+    // Ensure message logging CodeQL CLI version was present in user logs.
+    const expected_message: string = `Using CodeQL CLI version 2.16.0 downloaded from ${bundleUrl}.`;
+    t.assert(
+      loggedMessages.some(
+        (msg) =>
+          typeof msg.message === "string" &&
+          msg.message.includes(expected_message),
+      ),
     );
   });
 });

src/setup-codeql.ts

@@ -288,6 +288,7 @@ export async function getCodeQLSource(
     !CODEQL_BUNDLE_VERSION_ALIAS.includes(toolsInput) &&
     !toolsInput.startsWith("http")
   ) {
+    logger.info("Using CodeQL CLI from local path $path");
     return {
       codeqlTarPath: toolsInput,
       sourceType: "local",
@@ -310,10 +311,15 @@ export async function getCodeQLSource(
     toolsInput && CODEQL_BUNDLE_VERSION_ALIAS.includes(toolsInput);
   if (forceShippedTools) {
     logger.info(
-      "Overriding the version of the CodeQL tools by the version shipped with the Action since " +
+      `Overriding the version of the CodeQL tools by ${defaultCliVersion.cliVersion}, the version shipped with the Action since ` +
-        `"tools: linked" or "tools: latest" was requested. The version shipped with the Action is ` +
+        `tools: ${toolsInput} was requested.`,
-        `${defaultCliVersion.cliVersion}.`,
     );
+
+    if (toolsInput === "latest") {
+      logger.warning(
+        "The 'latest' alias for the CodeQL tools has been deprecated. Please use 'linked' instead.",
+      );
+    }
   }
 
   /** CLI version number, for example 2.12.6. */
@@ -436,10 +442,14 @@ export async function getCodeQLSource(
   }
 
   if (codeqlFolder) {
+    const version = cliVersion ?? humanReadableVersion;
+    logger.info(
+      `Using CodeQL CLI version ${version} from toolcache at ${codeqlFolder}`,
+    );
     return {
       codeqlFolder,
       sourceType: "toolcache",
-      toolsVersion: cliVersion ?? humanReadableVersion,
+      toolsVersion: version,
     };
   }
 
@@ -464,12 +474,16 @@ export async function getCodeQLSource(
     url = await getCodeQLBundleDownloadURL(tagName!, apiDetails, logger);
   }
 
+  const toolsVersion = cliVersion ?? humanReadableVersion;
+  logger.info(
+    `Using CodeQL CLI version ${toolsVersion} downloaded from ${url}.`,
+  );
   return {
     bundleVersion: tagName && tryGetBundleVersionFromTagName(tagName, logger),
     cliVersion,
     codeqlURL: url,
     sourceType: "download",
-    toolsVersion: cliVersion ?? humanReadableVersion,
+    toolsVersion,
   };
 }
 
@@ -494,6 +508,8 @@ export async function tryGetFallbackToolcacheVersion(
   return fallbackVersion;
 }
 
+// Exported using `export const` for testing purposes. Specifically, we want to
+// be able to stub this function and have other functions in this file use that stub.
 export const downloadCodeQL = async function (
   codeqlURL: string,
   maybeBundleVersion: string | undefined,
@@ -693,10 +709,6 @@ export async function setupCodeQLBundle(
     logger,
   );
 
-  logger.info(
-    `Using CodeQL CLI version ${source.toolsVersion} from ${source.sourceType}.`,
-  );
-
   let codeqlFolder: string;
   let toolsVersion = source.toolsVersion;
   let toolsDownloadDurationMs: number | undefined;