refactor: rename overlay-disabled reason and add changelog entry

CHANGELOG.md

@@ -4,7 +4,7 @@ See the [releases page](https://github.com/github/codeql-action/releases) for th
 
 ## [UNRELEASED]
 
-No user facing changes.
+- For performance and accuracy reasons, [improved incremental analysis](https://github.com/github/roadmap/issues/1158) will now only be enabled on a pull request when diff-informed analysis is also enabled for that run. If diff-informed analysis is unavailable (for example, because the PR diff ranges could not be computed), the action will fall back to a full analysis. [#3791](https://github.com/github/codeql-action/pull/3791)
 
 ## 4.35.3 - 01 May 2026
 

lib/init-action.js

@@ -107294,7 +107294,7 @@ async function applyIncrementalAnalysisSettings(config, hasDiffRanges, codeql, l
     await addOverlayDisablementDiagnostics(
       config,
       codeql,
-      "pr-diff-ranges-not-computed" /* PrDiffRangesNotComputed */
+      "diff-informed-analysis-not-enabled" /* DiffInformedAnalysisNotEnabled */
     );
   }
   if (hasDiffRanges) {

src/config-utils.test.ts

@@ -21,6 +21,7 @@ import { GitVersionInfo } from "./git-utils";
 import { BuiltInLanguage, Language } from "./languages";
 import { getRunnerLogger } from "./logging";
 import { CODEQL_OVERLAY_MINIMUM_VERSION } from "./overlay";
+import * as overlayDiagnostics from "./overlay/diagnostics";
 import { OverlayDisabledReason } from "./overlay/diagnostics";
 import { OverlayDatabaseMode } from "./overlay/overlay-database-mode";
 import * as overlayStatus from "./overlay/status";
@@ -2245,6 +2246,9 @@ test("applyIncrementalAnalysisSettings: disables overlay analysis when diff rang
   config.useOverlayDatabaseCaching = true;
   const codeql = createStubCodeQL({});
   const logger = getRunnerLogger(true);
+  const addDiagnosticsStub = sinon
+    .stub(overlayDiagnostics, "addOverlayDisablementDiagnostics")
+    .resolves();
 
   await configUtils.applyIncrementalAnalysisSettings(
     config,
@@ -2256,6 +2260,11 @@ test("applyIncrementalAnalysisSettings: disables overlay analysis when diff rang
   t.is(config.overlayDatabaseMode, OverlayDatabaseMode.None);
   t.is(config.useOverlayDatabaseCaching, false);
   t.deepEqual(config.extraQueryExclusions, []);
+  t.true(addDiagnosticsStub.calledOnce);
+  t.is(
+    addDiagnosticsStub.firstCall.args[2],
+    OverlayDisabledReason.DiffInformedAnalysisNotEnabled,
+  );
 });
 
 test("applyIncrementalAnalysisSettings: adds exclusions for diff-informed-only runs", async (t) => {

src/config-utils.ts

@@ -1107,7 +1107,7 @@ export async function applyIncrementalAnalysisSettings(
     await addOverlayDisablementDiagnostics(
       config,
       codeql,
-      OverlayDisabledReason.PrDiffRangesNotComputed,
+      OverlayDisabledReason.DiffInformedAnalysisNotEnabled,
     );
   }
 

src/overlay/diagnostics.ts

@@ -40,12 +40,14 @@ export enum OverlayDisabledReason {
   /** The top-level overlay analysis feature flag is not enabled. */
   OverallFeatureNotEnabled = "overall-feature-not-enabled",
   /**
-   * Overlay analysis was selected for a pull request, but the PR diff ranges
-   * needed for diff-informed analysis could not be computed. Overlay analysis
-   * has only been validated in combination with diff-informed analysis, so we
-   * fall back to a non-overlay analysis in this case.
+   * Overlay analysis was selected for a pull request, but diff-informed
+   * analysis was not enabled for the run (for example, because the
+   * `DiffInformedQueries` feature flag is off, the GHES version is too old,
+   * or the PR diff ranges could not be computed). Overlay analysis has only
+   * been validated in combination with diff-informed analysis, so we fall
+   * back to a non-overlay analysis in this case.
    */
-  PrDiffRangesNotComputed = "pr-diff-ranges-not-computed",
+  DiffInformedAnalysisNotEnabled = "diff-informed-analysis-not-enabled",
   /** 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. */