Update makeTelemetryDiagnostic doc

Bump the npm-minor group with 3 updates

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 See the [releases page](https://github.com/github/codeql-action/releases) for the relevant changes to the CodeQL CLI and language packs.
 
+## [UNRELEASED]
+
+No user facing changes.
+
 ## 4.31.9 - 16 Dec 2025
 
 No user facing changes.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeql",
-  "version": "4.31.9",
+  "version": "4.31.10",
   "private": true,
   "description": "CodeQL action",
   "scripts": {
@@ -24,12 +24,12 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@actions/artifact": "^4.0.0",
+    "@actions/artifact": "^5.0.1",
     "@actions/artifact-legacy": "npm:@actions/artifact@^1.1.2",
-    "@actions/cache": "^4.1.0",
-    "@actions/core": "^1.11.1",
-    "@actions/exec": "^1.1.1",
-    "@actions/github": "^6.0.0",
+    "@actions/cache": "^5.0.1",
+    "@actions/core": "^2.0.1",
+    "@actions/exec": "^2.0.0",
+    "@actions/github": "^6.0.1",
     "@actions/glob": "^0.5.0",
     "@actions/http-client": "^3.0.0",
     "@actions/io": "^2.0.0",
@@ -51,7 +51,7 @@
     "@ava/typescript": "6.0.0",
     "@eslint/compat": "^2.0.0",
     "@eslint/eslintrc": "^3.3.3",
-    "@eslint/js": "^9.39.1",
+    "@eslint/js": "^9.39.2",
     "@microsoft/eslint-formatter-sarif": "^3.1.0",
     "@octokit/types": "^16.0.0",
     "@types/archiver": "^7.0.0",
@@ -61,7 +61,7 @@
     "@types/node-forge": "^1.3.14",
     "@types/semver": "^7.7.1",
     "@types/sinon": "^21.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/eslint-plugin": "^8.49.0",
     "@typescript-eslint/parser": "^8.48.0",
     "ava": "^6.4.1",
     "esbuild": "^0.27.1",

src/config-utils.test.ts

@@ -978,6 +978,7 @@ interface OverlayDatabaseModeTestSetup {
   languages: Language[];
   codeqlVersion: string;
   gitRoot: string | undefined;
+  gitVersion: string | undefined;
   codeScanningConfig: configUtils.UserConfig;
   diskUsage: DiskUsage | undefined;
   memoryFlagValue: number;
@@ -992,6 +993,7 @@ const defaultOverlayDatabaseModeTestSetup: OverlayDatabaseModeTestSetup = {
   languages: [KnownLanguage.javascript],
   codeqlVersion: CODEQL_OVERLAY_MINIMUM_VERSION,
   gitRoot: "/some/git/root",
+  gitVersion: gitUtils.GIT_MINIMUM_VERSION_FOR_OVERLAY,
   codeScanningConfig: {},
   diskUsage: {
     numAvailableBytes: 50_000_000_000,
@@ -1070,6 +1072,7 @@ const getOverlayDatabaseModeMacro = test.macro({
           setup.buildMode,
           undefined,
           setup.codeScanningConfig,
+          setup.gitVersion,
           logger,
         );
 
@@ -1773,6 +1776,32 @@ test(
   },
 );
 
+test(
+  getOverlayDatabaseModeMacro,
+  "Fallback due to old git version",
+  {
+    overlayDatabaseEnvVar: "overlay",
+    gitVersion: "2.30.0", // Version below required 2.38.0
+  },
+  {
+    overlayDatabaseMode: OverlayDatabaseMode.None,
+    useOverlayDatabaseCaching: false,
+  },
+);
+
+test(
+  getOverlayDatabaseModeMacro,
+  "Fallback when git version cannot be determined",
+  {
+    overlayDatabaseEnvVar: "overlay",
+    gitVersion: undefined,
+  },
+  {
+    overlayDatabaseMode: OverlayDatabaseMode.None,
+    useOverlayDatabaseCaching: false,
+  },
+);
+
 // Exercise language-specific overlay analysis features code paths
 for (const language in KnownLanguage) {
   test(

src/config-utils.ts

@@ -3,6 +3,7 @@ import * as path from "path";
 import { performance } from "perf_hooks";
 
 import * as yaml from "js-yaml";
+import * as semver from "semver";
 
 import { getActionVersion, isAnalyzingPullRequest } from "./actions-util";
 import {
@@ -22,11 +23,17 @@ import {
   parseUserConfig,
   UserConfig,
 } from "./config/db-config";
+import { addDiagnostic, makeTelemetryDiagnostic } from "./diagnostics";
 import { shouldPerformDiffInformedAnalysis } from "./diff-informed-analysis-utils";
 import * as errorMessages from "./error-messages";
 import { Feature, FeatureEnablement } from "./feature-flags";
 import { RepositoryProperties } from "./feature-flags/properties";
-import { getGitRoot, isAnalyzingDefaultBranch } from "./git-utils";
+import {
+  getGitRoot,
+  getGitVersionOrThrow,
+  GIT_MINIMUM_VERSION_FOR_OVERLAY,
+  isAnalyzingDefaultBranch,
+} from "./git-utils";
 import { KnownLanguage, Language } from "./languages";
 import { Logger } from "./logging";
 import {
@@ -45,6 +52,7 @@ import {
   isDefined,
   checkDiskUsage,
   getCodeQLMemoryLimit,
+  getErrorMessage,
 } from "./util";
 
 export * from "./config/db-config";
@@ -709,6 +717,7 @@ export async function getOverlayDatabaseMode(
   buildMode: BuildMode | undefined,
   ramInput: string | undefined,
   codeScanningConfig: UserConfig,
+  gitVersion: string | undefined,
   logger: Logger,
 ): Promise<{
   overlayDatabaseMode: OverlayDatabaseMode;
@@ -811,6 +820,22 @@ export async function getOverlayDatabaseMode(
     );
     return nonOverlayAnalysis;
   }
+  if (gitVersion === undefined) {
+    logger.warning(
+      `Cannot build an ${overlayDatabaseMode} database because ` +
+        "the Git version could not be determined. " +
+        "Falling back to creating a normal full database instead.",
+    );
+    return nonOverlayAnalysis;
+  }
+  if (!semver.gte(gitVersion, GIT_MINIMUM_VERSION_FOR_OVERLAY)) {
+    logger.warning(
+      `Cannot build an ${overlayDatabaseMode} database because ` +
+        `the installed Git version is older than ${GIT_MINIMUM_VERSION_FOR_OVERLAY}. ` +
+        "Falling back to creating a normal full database instead.",
+    );
+    return nonOverlayAnalysis;
+  }
 
   return {
     overlayDatabaseMode,
@@ -903,6 +928,15 @@ export async function initConfig(
     config.computedConfig["query-filters"] = [];
   }
 
+  let gitVersion: string | undefined = undefined;
+  try {
+    gitVersion = await getGitVersionOrThrow();
+    logger.info(`Using Git version ${gitVersion}`);
+    await logGitVersionTelemetry(config, gitVersion);
+  } catch (e) {
+    logger.debug(`Could not determine Git version: ${getErrorMessage(e)}`);
+  }
+
   // The choice of overlay database mode depends on the selection of languages
   // and queries, which in turn depends on the user config and the augmentation
   // properties. So we need to calculate the overlay database mode after the
@@ -916,6 +950,7 @@ export async function initConfig(
       config.buildMode,
       inputs.ramInput,
       config.computedConfig,
+      gitVersion,
       logger,
     );
   logger.info(
@@ -1316,3 +1351,23 @@ export function getPrimaryAnalysisConfig(config: Config): AnalysisConfig {
     ? CodeScanning
     : CodeQuality;
 }
+
+/** Logs the Git version as a telemetry diagnostic. */
+async function logGitVersionTelemetry(
+  config: Config,
+  gitVersion: string,
+): Promise<void> {
+  if (config.languages.length > 0) {
+    addDiagnostic(
+      config,
+      // Arbitrarily choose the first language. We could also choose all languages, but that
+      // increases the risk of misinterpreting the data.
+      config.languages[0],
+      makeTelemetryDiagnostic(
+        "codeql-action/git-version-telemetry",
+        "Git version telemetry",
+        { gitVersion },
+      ),
+    );
+  }
+}

src/diagnostics.ts

@@ -185,3 +185,27 @@ export function flushDiagnostics(config: Config) {
   // Reset the unwritten diagnostics array.
   unwrittenDiagnostics = [];
 }
+
+/**
+ * Creates a telemetry-only diagnostic message. This is a convenience function
+ * for creating diagnostics that should only be sent to telemetry and not
+ * displayed on the status page or CLI summary table.
+ *
+ * @param id An identifier under which it makes sense to group this diagnostic message
+ * @param name Display name
+ * @param attributes Structured metadata
+ */
+export function makeTelemetryDiagnostic(
+  id: string,
+  name: string,
+  attributes: { [key: string]: any },
+): DiagnosticMessage {
+  return makeDiagnostic(id, name, {
+    attributes,
+    visibility: {
+      cliSummaryTable: false,
+      statusPage: false,
+      telemetry: true,
+    },
+  });
+}

src/git-utils.test.ts

@@ -315,7 +315,6 @@ test("getFileOidsUnderPath returns correct file mapping", async (t) => {
         "a47c11f5bfdca7661942d2c8f1b7209fb0dfdf96_src/git-utils.ts",
     );
 
-  try {
   const result = await gitUtils.getFileOidsUnderPath("/fake/path");
 
   t.deepEqual(result, {
@@ -329,13 +328,10 @@ test("getFileOidsUnderPath returns correct file mapping", async (t) => {
     ["ls-files", "--recurse-submodules", "--format=%(objectname)_%(path)"],
     "Cannot list Git OIDs of tracked files.",
   ]);
-  } finally {
-    runGitCommandStub.restore();
-  }
 });
 
 test("getFileOidsUnderPath handles quoted paths", async (t) => {
-  const runGitCommandStub = sinon
+  sinon
     .stub(gitUtils as any, "runGitCommand")
     .resolves(
       "30d998ded095371488be3a729eb61d86ed721a18_lib/normal-file.js\n" +
@@ -343,7 +339,6 @@ test("getFileOidsUnderPath handles quoted paths", async (t) => {
         'a47c11f5bfdca7661942d2c8f1b7209fb0dfdf96_"lib/file\\twith\\ttabs.js"',
     );
 
-  try {
   const result = await gitUtils.getFileOidsUnderPath("/fake/path");
 
   t.deepEqual(result, {
@@ -351,26 +346,17 @@ test("getFileOidsUnderPath handles quoted paths", async (t) => {
     "lib/file with spaces.js": "d89514599a9a99f22b4085766d40af7b99974827",
     "lib/file\twith\ttabs.js": "a47c11f5bfdca7661942d2c8f1b7209fb0dfdf96",
   });
-  } finally {
-    runGitCommandStub.restore();
-  }
 });
 
 test("getFileOidsUnderPath handles empty output", async (t) => {
-  const runGitCommandStub = sinon
-    .stub(gitUtils as any, "runGitCommand")
-    .resolves("");
+  sinon.stub(gitUtils as any, "runGitCommand").resolves("");
 
-  try {
   const result = await gitUtils.getFileOidsUnderPath("/fake/path");
   t.deepEqual(result, {});
-  } finally {
-    runGitCommandStub.restore();
-  }
 });
 
 test("getFileOidsUnderPath throws on unexpected output format", async (t) => {
-  const runGitCommandStub = sinon
+  sinon
     .stub(gitUtils as any, "runGitCommand")
     .resolves(
       "30d998ded095371488be3a729eb61d86ed721a18_lib/git-utils.js\n" +
@@ -378,7 +364,6 @@ test("getFileOidsUnderPath throws on unexpected output format", async (t) => {
         "a47c11f5bfdca7661942d2c8f1b7209fb0dfdf96_src/git-utils.ts",
     );
 
-  try {
   await t.throwsAsync(
     async () => {
       await gitUtils.getFileOidsUnderPath("/fake/path");
@@ -388,7 +373,51 @@ test("getFileOidsUnderPath throws on unexpected output format", async (t) => {
       message: 'Unexpected "git ls-files" output: invalid-line-format',
     },
   );
-  } finally {
-    runGitCommandStub.restore();
-  }
+});
+
+test("getGitVersionOrThrow returns version for valid git output", async (t) => {
+  sinon.stub(gitUtils as any, "runGitCommand").resolves("git version 2.40.0\n");
+
+  const version = await gitUtils.getGitVersionOrThrow();
+  t.is(version, "2.40.0");
+});
+
+test("getGitVersionOrThrow throws for invalid git output", async (t) => {
+  sinon.stub(gitUtils as any, "runGitCommand").resolves("invalid output");
+
+  await t.throwsAsync(
+    async () => {
+      await gitUtils.getGitVersionOrThrow();
+    },
+    {
+      instanceOf: Error,
+      message: "Could not parse Git version from output: invalid output",
+    },
+  );
+});
+
+test("getGitVersionOrThrow handles Windows-style git output", async (t) => {
+  sinon
+    .stub(gitUtils as any, "runGitCommand")
+    .resolves("git version 2.40.0.windows.1\n");
+
+  const version = await gitUtils.getGitVersionOrThrow();
+  // Should extract just the major.minor.patch portion
+  t.is(version, "2.40.0");
+});
+
+test("getGitVersionOrThrow throws when git command fails", async (t) => {
+  sinon
+    .stub(gitUtils as any, "runGitCommand")
+    .rejects(new Error("git not found"));
+
+  await t.throwsAsync(
+    async () => {
+      await gitUtils.getGitVersionOrThrow();
+    },
+    {
+      instanceOf: Error,
+      message: "git not found",
+    },
+  );
 });

src/git-utils.ts

@@ -9,6 +9,34 @@ import {
 } from "./actions-util";
 import { ConfigurationError, getRequiredEnvParam } from "./util";
 
+/**
+ * Minimum Git version required for overlay analysis. The `git ls-files --format`
+ * option, which is used by `getFileOidsUnderPath`, was introduced in Git 2.38.0.
+ */
+export const GIT_MINIMUM_VERSION_FOR_OVERLAY = "2.38.0";
+
+/**
+ * Gets the version of Git installed on the system and throws an error if
+ * the version cannot be determined.
+ *
+ * @returns The Git version string (e.g., "2.40.0").
+ * @throws {Error} if the version could not be determined.
+ */
+export async function getGitVersionOrThrow(): Promise<string> {
+  const stdout = await runGitCommand(
+    undefined,
+    ["--version"],
+    "Failed to get git version.",
+  );
+  // Git version output can vary: "git version 2.40.0" or "git version 2.40.0.windows.1"
+  // We capture just the major.minor.patch portion to ensure semver compatibility.
+  const match = stdout.match(/git version (\d+\.\d+\.\d+)/);
+  if (match?.[1]) {
+    return match[1];
+  }
+  throw new Error(`Could not parse Git version from output: ${stdout.trim()}`);
+}
+
 export const runGitCommand = async function (
   workingDirectory: string | undefined,
   args: string[],

src/init-action.ts

@@ -33,6 +33,7 @@ import {
   flushDiagnostics,
   logUnwrittenDiagnostics,
   makeDiagnostic,
+  makeTelemetryDiagnostic,
 } from "./diagnostics";
 import { EnvVar } from "./environment";
 import { Feature, Features } from "./feature-flags";
@@ -425,17 +426,10 @@ async function run() {
         // Arbitrarily choose the first language. We could also choose all languages, but that
         // increases the risk of misinterpreting the data.
         config.languages[0],
-        makeDiagnostic(
+        makeTelemetryDiagnostic(
           "codeql-action/bundle-download-telemetry",
           "CodeQL bundle download telemetry",
-          {
-            attributes: toolsDownloadStatusReport,
-            visibility: {
-              cliSummaryTable: false,
-              statusPage: false,
-              telemetry: true,
-            },
-          },
+          toolsDownloadStatusReport,
         ),
       );
     }
@@ -794,17 +788,10 @@ async function recordZstdAvailability(
     // Arbitrarily choose the first language. We could also choose all languages, but that
     // increases the risk of misinterpreting the data.
     config.languages[0],
-    makeDiagnostic(
+    makeTelemetryDiagnostic(
       "codeql-action/zstd-availability",
       "Zstandard availability",
-      {
-        attributes: zstdAvailability,
-        visibility: {
-          cliSummaryTable: false,
-          statusPage: false,
-          telemetry: true,
-        },
-      },
+      zstdAvailability,
     ),
   );
 }