Add disabled reason

2026-10-30 17:39:50 +00:00 · 2026-02-25 14:22:13 +00:00
parent 70db156dcb
commit 182427800c
3 changed files with 109 additions and 52 deletions
--- a/src/config-utils.test.ts
+++ b/src/config-utils.test.ts
@@ -12,6 +12,7 @@ import * as api from "./api-client";
 import { CachingKind } from "./caching-utils";
 import { createStubCodeQL } from "./codeql";
 import * as configUtils from "./config-utils";
+import { OverlayDisabledReason } from "./config-utils";
 import * as errorMessages from "./error-messages";
 import { Feature } from "./feature-flags";
 import { RepositoryProperties } from "./feature-flags/properties";
@@ -1018,8 +1019,7 @@ const getOverlayDatabaseModeMacro = test.macro({
    expected: {
      overlayDatabaseMode: OverlayDatabaseMode;
      useOverlayDatabaseCaching: boolean;
-      skippedDueToCachedStatus?: boolean;
-      disabledByRepositoryProperty?: boolean;
+      disabledReason?: OverlayDisabledReason;
    },
  ) => {
    return await withTmpDir(async (tempDir) => {
@@ -1091,11 +1091,11 @@ const getOverlayDatabaseModeMacro = test.macro({
          logger,
        );

-        t.deepEqual(result, {
-          skippedDueToCachedStatus: false,
-          disabledByRepositoryProperty: false,
-          ...expected,
-        });
+        if (!("disabledReason" in expected)) {
+          expected.disabledReason = undefined;
+        }
+
+        t.deepEqual(result, expected);
      } finally {
        // Restore the original environment
        process.env = originalEnv;
@@ -1150,6 +1150,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1232,6 +1233,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1250,6 +1252,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1294,6 +1297,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1337,6 +1341,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1355,6 +1360,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1393,7 +1399,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
-    skippedDueToCachedStatus: true,
+    disabledReason: OverlayDisabledReason.SkippedDueToCachedStatus,
  },
 );

@@ -1413,7 +1419,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
-    skippedDueToCachedStatus: true,
+    disabledReason: OverlayDisabledReason.SkippedDueToCachedStatus,
  },
 );

@@ -1434,6 +1440,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1454,6 +1461,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1474,6 +1482,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1494,6 +1503,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1508,6 +1518,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1522,6 +1533,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1536,6 +1548,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1605,6 +1618,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1645,6 +1659,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1663,6 +1678,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.InsufficientResources,
  },
 );

@@ -1702,6 +1718,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1722,6 +1739,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1742,6 +1760,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1762,6 +1781,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1776,6 +1796,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1790,6 +1811,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1804,6 +1826,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.FeatureNotEnabled,
  },
 );

@@ -1857,6 +1880,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.IncompatibleBuildMode,
  },
 );

@@ -1871,6 +1895,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.IncompatibleBuildMode,
  },
 );

@@ -1884,6 +1909,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.IncompatibleCodeQl,
  },
 );

@@ -1897,6 +1923,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.NoGitRoot,
  },
 );

@@ -1910,6 +1937,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.IncompatibleGit,
  },
 );

@@ -1923,6 +1951,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
+    disabledReason: OverlayDisabledReason.IncompatibleGit,
  },
 );

@@ -1940,7 +1969,7 @@ test(
  {
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
-    disabledByRepositoryProperty: true,
+    disabledReason: OverlayDisabledReason.DisabledByRepositoryProperty,
  },
 );

@@ -1989,6 +2018,7 @@ for (const language in KnownLanguage) {
    {
      overlayDatabaseMode: OverlayDatabaseMode.None,
      useOverlayDatabaseCaching: false,
+      disabledReason: OverlayDisabledReason.FeatureNotEnabled,
    },
  );
 }
--- a/src/config-utils.ts
+++ b/src/config-utils.ts
@@ -69,6 +69,30 @@ import {
  DiskUsage,
 } from "./util";

+/**
+ * The reason why overlay analysis was disabled, if applicable.
+ */
+export enum OverlayDisabledReason {
+  /** Overlay analysis was disabled by a repository property. */
+  DisabledByRepositoryProperty = "disabled-by-repository-property",
+  /** Overlay analysis feature was not enabled. */
+  FeatureNotEnabled = "feature-not-enabled",
+  /** The build mode is incompatible with overlay analysis. */
+  IncompatibleBuildMode = "incompatible-build-mode",
+  /** The CodeQL CLI version is too old to support overlay analysis. */
+  IncompatibleCodeQl = "incompatible-codeql",
+  /** The Git version could not be determined or is too old. */
+  IncompatibleGit = "incompatible-git",
+  /** The runner does not have enough disk space or memory. */
+  InsufficientResources = "insufficient-resources",
+  /** The source root is not inside a git repository. */
+  NoGitRoot = "no-git-root",
+  /** Overlay analysis was skipped because it previously failed with similar hardware resources. */
+  SkippedDueToCachedStatus = "skipped-due-to-cached-status",
+  /** Disk usage could not be determined during the overlay status check. */
+  UnableToDetermineDiskUsage = "unable-to-determine-disk-usage",
+}
+
 export * from "./config/db-config";

 /**
@@ -759,13 +783,11 @@ export async function getOverlayDatabaseMode(
 ): Promise<{
  overlayDatabaseMode: OverlayDatabaseMode;
  useOverlayDatabaseCaching: boolean;
-  skippedDueToCachedStatus: boolean;
-  disabledByRepositoryProperty: boolean;
+  disabledReason: OverlayDisabledReason | undefined;
 }> {
  let overlayDatabaseMode = OverlayDatabaseMode.None;
  let useOverlayDatabaseCaching = false;
-  let skippedDueToCachedStatus = false;
-  let disabledByRepositoryProperty = false;
+  let disabledReason: OverlayDisabledReason | undefined;

  const modeEnv = process.env.CODEQL_OVERLAY_DATABASE_MODE;
  // Any unrecognized CODEQL_OVERLAY_DATABASE_MODE value will be ignored and
@@ -788,7 +810,7 @@ export async function getOverlayDatabaseMode(
        `because the ${RepositoryPropertyName.DISABLE_OVERLAY} repository property is set to true.`,
    );
    overlayDatabaseMode = OverlayDatabaseMode.None;
-    disabledByRepositoryProperty = true;
+    disabledReason = OverlayDisabledReason.DisabledByRepositoryProperty;
  } else if (
    await isOverlayAnalysisFeatureEnabled(
      features,
@@ -821,11 +843,13 @@ export async function getOverlayDatabaseMode(
      ))
    ) {
      overlayDatabaseMode = OverlayDatabaseMode.None;
+      disabledReason = OverlayDisabledReason.InsufficientResources;
    } else if (checkOverlayStatus && diskUsage === undefined) {
      logger.warning(
        `Unable to determine disk usage, therefore setting overlay database mode to ${OverlayDatabaseMode.None}.`,
      );
      overlayDatabaseMode = OverlayDatabaseMode.None;
+      disabledReason = OverlayDisabledReason.UnableToDetermineDiskUsage;
    } else if (
      checkOverlayStatus &&
      diskUsage &&
@@ -837,7 +861,7 @@ export async function getOverlayDatabaseMode(
          "disk space, and CodeQL version.",
      );
      overlayDatabaseMode = OverlayDatabaseMode.None;
-      skippedDueToCachedStatus = true;
+      disabledReason = OverlayDisabledReason.SkippedDueToCachedStatus;
    } else if (isAnalyzingPullRequest()) {
      overlayDatabaseMode = OverlayDatabaseMode.Overlay;
      useOverlayDatabaseCaching = true;
@@ -853,17 +877,18 @@ export async function getOverlayDatabaseMode(
          "with caching because we are analyzing the default branch.",
      );
    }
+  } else {
+    disabledReason = OverlayDisabledReason.FeatureNotEnabled;
  }

-  const nonOverlayAnalysis = {
+  const disabledResult = (reason: OverlayDisabledReason | undefined) => ({
    overlayDatabaseMode: OverlayDatabaseMode.None,
    useOverlayDatabaseCaching: false,
-    skippedDueToCachedStatus,
-    disabledByRepositoryProperty,
-  };
+    disabledReason: reason,
+  });

  if (overlayDatabaseMode === OverlayDatabaseMode.None) {
-    return nonOverlayAnalysis;
+    return disabledResult(disabledReason);
  }

  if (
@@ -886,7 +911,7 @@ export async function getOverlayDatabaseMode(
        `build-mode is set to "${buildMode}" instead of "none". ` +
        "Falling back to creating a normal full database instead.",
    );
-    return nonOverlayAnalysis;
+    return disabledResult(OverlayDisabledReason.IncompatibleBuildMode);
  }
  if (!(await codeQlVersionAtLeast(codeql, CODEQL_OVERLAY_MINIMUM_VERSION))) {
    logger.warning(
@@ -894,7 +919,7 @@ export async function getOverlayDatabaseMode(
        `the CodeQL CLI is older than ${CODEQL_OVERLAY_MINIMUM_VERSION}. ` +
        "Falling back to creating a normal full database instead.",
    );
-    return nonOverlayAnalysis;
+    return disabledResult(OverlayDisabledReason.IncompatibleCodeQl);
  }
  if ((await getGitRoot(sourceRoot)) === undefined) {
    logger.warning(
@@ -902,7 +927,7 @@ export async function getOverlayDatabaseMode(
        `the source root "${sourceRoot}" is not inside a git repository. ` +
        "Falling back to creating a normal full database instead.",
    );
-    return nonOverlayAnalysis;
+    return disabledResult(OverlayDisabledReason.NoGitRoot);
  }
  if (gitVersion === undefined) {
    logger.warning(
@@ -910,7 +935,7 @@ export async function getOverlayDatabaseMode(
        "the Git version could not be determined. " +
        "Falling back to creating a normal full database instead.",
    );
-    return nonOverlayAnalysis;
+    return disabledResult(OverlayDisabledReason.IncompatibleGit);
  }
  if (!gitVersion.isAtLeast(GIT_MINIMUM_VERSION_FOR_OVERLAY)) {
    logger.warning(
@@ -918,14 +943,13 @@ export async function getOverlayDatabaseMode(
        `the installed Git version is older than ${GIT_MINIMUM_VERSION_FOR_OVERLAY}. ` +
        "Falling back to creating a normal full database instead.",
    );
-    return nonOverlayAnalysis;
+    return disabledResult(OverlayDisabledReason.IncompatibleGit);
  }

  return {
    overlayDatabaseMode,
    useOverlayDatabaseCaching,
-    skippedDueToCachedStatus,
-    disabledByRepositoryProperty,
+    disabledReason,
  };
 }

@@ -1075,8 +1099,7 @@ export async function initConfig(
  const {
    overlayDatabaseMode,
    useOverlayDatabaseCaching,
-    skippedDueToCachedStatus: overlaySkippedDueToCachedStatus,
-    disabledByRepositoryProperty: overlayDisabledByRepositoryProperty,
+    disabledReason: overlayDisabledReason,
  } = await getOverlayDatabaseMode(
    inputs.codeql,
    inputs.features,
@@ -1096,7 +1119,9 @@ export async function initConfig(
  config.overlayDatabaseMode = overlayDatabaseMode;
  config.useOverlayDatabaseCaching = useOverlayDatabaseCaching;

-  if (overlaySkippedDueToCachedStatus) {
+  if (
+    overlayDisabledReason === OverlayDisabledReason.SkippedDueToCachedStatus
+  ) {
    addNoLanguageDiagnostic(
      config,
      makeDiagnostic(
@@ -1125,7 +1150,9 @@ export async function initConfig(
    );
  }

-  if (overlayDisabledByRepositoryProperty) {
+  if (
+    overlayDisabledReason === OverlayDisabledReason.DisabledByRepositoryProperty
+  ) {
    addNoLanguageDiagnostic(
      config,
      makeDiagnostic(