Initial plan

.github/workflows/codescanning-config-cli.yml

@@ -6,6 +6,13 @@ env:
   # Diff informed queries add an additional query filter which is not yet
   # taken into account by these tests.
   CODEQL_ACTION_DIFF_INFORMED_QUERIES: false
+  # Specify overlay enablement manually to ensure stability around the exclude-from-incremental
+  # query filter. Here we only enable for the default code scanning suite.
+  CODEQL_ACTION_OVERLAY_ANALYSIS: true
+  CODEQL_ACTION_OVERLAY_ANALYSIS_JAVASCRIPT: false
+  CODEQL_ACTION_OVERLAY_ANALYSIS_CODE_SCANNING_JAVASCRIPT: true
+  CODEQL_ACTION_OVERLAY_ANALYSIS_STATUS_CHECK: false
+  CODEQL_ACTION_OVERLAY_ANALYSIS_SKIP_RESOURCE_CHECKS: true
 
 on:
   push:
@@ -72,13 +79,33 @@ jobs:
       with:
         version: ${{ matrix.version }}
 
-    - name: Empty file
+    # On PRs, overlay analysis may change the config that is passed to the CLI.
+    # Therefore, we have two variants of the following test, one for PRs and one for other events.
+    - name: Empty file (non-PR)
+      if: github.event_name != 'pull_request'
       uses: ./../action/.github/actions/check-codescanning-config
       with:
         expected-config-file-contents: "{}"
         languages: javascript
         tools: ${{ steps.prepare-test.outputs.tools-url }}
 
+    - name: Empty file (PR)
+      if: github.event_name == 'pull_request'
+      uses: ./../action/.github/actions/check-codescanning-config
+      with:
+        expected-config-file-contents: |
+          {
+            "query-filters": [
+              {
+                "exclude": {
+                  "tags": "exclude-from-incremental"
+                }
+              }
+            ]
+          }
+        languages: javascript
+        tools: ${{ steps.prepare-test.outputs.tools-url }}
+
     - name: Packs from input
       if: success() || failure()
       uses: ./../action/.github/actions/check-codescanning-config

CHANGELOG.md

@@ -4,7 +4,7 @@ See the [releases page](https://github.com/github/codeql-action/releases) for th
 
 ## [UNRELEASED]
 
-- 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)
+No user facing changes.
 
 ## 4.35.3 - 01 May 2026
 

package-lock.json

@@ -410,6 +410,15 @@
         "undici": "^6.23.0"
       }
     },
+    "node_modules/@actions/github/node_modules/undici": {
+      "version": "6.23.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.23.0.tgz",
+      "integrity": "sha512-VfQPToRA5FZs/qJxLIinmU59u0r7LXqoJkCzinq3ckNJp3vKEh7jTWN589YQ5+aoAC/TGRLyJLCPKcLQbM8r9g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
     "node_modules/@actions/glob": {
       "version": "0.5.1",
       "resolved": "https://registry.npmjs.org/@actions/glob/-/glob-0.5.1.tgz",
@@ -430,6 +439,15 @@
         "undici": "^6.23.0"
       }
     },
+    "node_modules/@actions/http-client/node_modules/undici": {
+      "version": "6.23.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-6.23.0.tgz",
+      "integrity": "sha512-VfQPToRA5FZs/qJxLIinmU59u0r7LXqoJkCzinq3ckNJp3vKEh7jTWN589YQ5+aoAC/TGRLyJLCPKcLQbM8r9g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
     "node_modules/@actions/io": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/@actions/io/-/io-2.0.0.tgz",
@@ -1476,6 +1494,14 @@
         "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
       }
     },
+    "node_modules/@fastify/busboy": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@fastify/busboy/-/busboy-2.1.1.tgz",
+      "integrity": "sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==",
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/@github/browserslist-config": {
       "version": "1.0.0",
       "dev": true,
@@ -9828,12 +9854,14 @@
       }
     },
     "node_modules/undici": {
-      "version": "6.24.1",
-      "resolved": "https://registry.npmjs.org/undici/-/undici-6.24.1.tgz",
-      "integrity": "sha512-sC+b0tB1whOCzbtlx20fx3WgCXwkW627p4EA9uM+/tNNPkSS+eSEld6pAs9nDv7WbY1UUljBMYPtu9BCOrCWKA==",
-      "license": "MIT",
+      "version": "5.29.0",
+      "resolved": "https://registry.npmjs.org/undici/-/undici-5.29.0.tgz",
+      "integrity": "sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==",
+      "dependencies": {
+        "@fastify/busboy": "^2.0.0"
+      },
       "engines": {
-        "node": ">=18.17"
+        "node": ">=14.0"
       }
     },
     "node_modules/undici-types": {

package.json

@@ -90,7 +90,6 @@
       "semver": ">=6.3.1"
     },
     "brace-expansion@2.0.1": "2.0.2",
-    "glob": "^11.1.0",
-    "undici": "^6.24.0"
+    "glob": "^11.1.0"
   }
 }

src/api-client.ts

@@ -128,8 +128,6 @@ export async function getGitHubVersionFromApi(
 
   // Doesn't strictly have to be the meta endpoint as we're only
   // using the response headers which are available on every request.
-  //
-  // See https://docs.github.com/en/rest/meta/meta#get-github-meta-information.
   // eslint-disable-next-line @typescript-eslint/no-unsafe-call
   const response = await apiClient.rest.meta.get();
 
@@ -166,9 +164,6 @@ export async function getGitHubVersion(): Promise<GitHubVersion> {
 
 /**
  * Get the path of the currently executing workflow relative to the repository root.
- *
- * See https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run
- * and https://docs.github.com/en/rest/actions/workflows#get-a-workflow.
  */
 export async function getWorkflowRelativePath(): Promise<string> {
   const repo_nwo = getRepositoryNwo();
@@ -257,13 +252,9 @@ export interface ActionsCacheItem {
   size_in_bytes?: number;
 }
 
-/**
- * List all Actions cache entries starting with the provided key prefix and matching the provided ref.
- *
- * See https://docs.github.com/en/rest/actions/cache#list-github-actions-caches-for-a-repository.
- */
+/** List all Actions cache entries matching the provided key and ref. */
 export async function listActionsCaches(
-  keyPrefix: string,
+  key: string,
   ref?: string,
 ): Promise<ActionsCacheItem[]> {
   const repositoryNwo = getRepositoryNwo();
@@ -273,17 +264,13 @@ export async function listActionsCaches(
     {
       owner: repositoryNwo.owner,
       repo: repositoryNwo.repo,
-      key: keyPrefix,
+      key,
       ref,
     },
   );
 }
 
-/**
- * Delete an Actions cache item by its ID.
- *
- * See https://docs.github.com/en/rest/actions/cache#delete-a-github-actions-cache-for-a-repository-using-a-cache-id.
- */
+/** Delete an Actions cache item by its ID. */
 export async function deleteActionsCache(id: number) {
   const repositoryNwo = getRepositoryNwo();
 
@@ -294,11 +281,7 @@ export async function deleteActionsCache(id: number) {
   });
 }
 
-/**
- * Retrieve all custom repository properties.
- *
- * See https://docs.github.com/en/rest/repos/custom-properties#get-all-custom-property-values-for-a-repository.
- */
+/** Retrieve all custom repository properties. */
 export async function getRepositoryProperties(repositoryNwo: RepositoryNwo) {
   return getApiClient().request("GET /repos/:owner/:repo/properties/values", {
     owner: repositoryNwo.owner,

src/config-utils.test.ts

@@ -21,7 +21,6 @@ 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";
@@ -2201,87 +2200,3 @@ test.serial(
     });
   },
 );
-
-test("applyIncrementalAnalysisSettings: no-op when mode is not Overlay and diff ranges are unavailable", async (t) => {
-  const config = createTestConfig({});
-  config.overlayDatabaseMode = OverlayDatabaseMode.None;
-  const codeql = createStubCodeQL({});
-  const logger = getRunnerLogger(true);
-
-  await configUtils.applyIncrementalAnalysisSettings(
-    config,
-    false,
-    codeql,
-    logger,
-  );
-
-  t.is(config.overlayDatabaseMode, OverlayDatabaseMode.None);
-  t.deepEqual(config.extraQueryExclusions, []);
-});
-
-test("applyIncrementalAnalysisSettings: keeps overlay mode and adds exclusions when diff ranges are available", async (t) => {
-  const config = createTestConfig({
-    overlayDatabaseMode: OverlayDatabaseMode.Overlay,
-  });
-  const codeql = createStubCodeQL({});
-  const logger = getRunnerLogger(true);
-
-  await configUtils.applyIncrementalAnalysisSettings(
-    config,
-    true,
-    codeql,
-    logger,
-  );
-
-  t.is(config.overlayDatabaseMode, OverlayDatabaseMode.Overlay);
-  t.deepEqual(config.extraQueryExclusions, [
-    { exclude: { tags: "exclude-from-incremental" } },
-  ]);
-});
-
-test("applyIncrementalAnalysisSettings: disables overlay analysis when diff ranges are unavailable", async (t) => {
-  const config = createTestConfig({
-    overlayDatabaseMode: OverlayDatabaseMode.Overlay,
-  });
-  config.useOverlayDatabaseCaching = true;
-  const codeql = createStubCodeQL({});
-  const logger = getRunnerLogger(true);
-  const addDiagnosticsStub = sinon
-    .stub(overlayDiagnostics, "addOverlayDisablementDiagnostics")
-    .resolves();
-
-  await configUtils.applyIncrementalAnalysisSettings(
-    config,
-    false,
-    codeql,
-    logger,
-  );
-
-  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) => {
-  const config = createTestConfig({});
-  config.overlayDatabaseMode = OverlayDatabaseMode.None;
-  const codeql = createStubCodeQL({});
-  const logger = getRunnerLogger(true);
-
-  await configUtils.applyIncrementalAnalysisSettings(
-    config,
-    true,
-    codeql,
-    logger,
-  );
-
-  t.is(config.overlayDatabaseMode, OverlayDatabaseMode.None);
-  t.deepEqual(config.extraQueryExclusions, [
-    { exclude: { tags: "exclude-from-incremental" } },
-  ]);
-});

src/config-utils.ts

@@ -31,7 +31,7 @@ import {
   addNoLanguageDiagnostic,
   makeTelemetryDiagnostic,
 } from "./diagnostics";
-import { prepareDiffInformedAnalysis } from "./diff-informed-analysis-utils";
+import { shouldPerformDiffInformedAnalysis } from "./diff-informed-analysis-utils";
 import { EnvVar } from "./environment";
 import * as errorMessages from "./error-messages";
 import { Feature, FeatureEnablement } from "./feature-flags";
@@ -1076,48 +1076,6 @@ function hasQueryCustomisation(userConfig: UserConfig): boolean {
   );
 }
 
-/**
- * Finalize the incremental-analysis configuration for this run.
- *
- * Overlay analysis has only been validated in combination with diff-informed
- * analysis, so if `Overlay` mode was selected for a pull request but the diff
- * ranges could not be computed, fall back to a full non-overlay analysis.
- *
- * Query exclusions for incremental-only queries are then applied whenever the
- * diff ranges are available — which, after the fallback above, is exactly the
- * set of runs where any kind of incremental analysis (overlay or
- * diff-informed) is in effect.
- */
-export async function applyIncrementalAnalysisSettings(
-  config: Config,
-  hasDiffRanges: boolean,
-  codeql: CodeQL,
-  logger: Logger,
-): Promise<void> {
-  if (
-    config.overlayDatabaseMode === OverlayDatabaseMode.Overlay &&
-    !hasDiffRanges
-  ) {
-    logger.info(
-      `Reverting overlay database mode to ${OverlayDatabaseMode.None} ` +
-        "because the PR diff ranges could not be computed.",
-    );
-    config.overlayDatabaseMode = OverlayDatabaseMode.None;
-    config.useOverlayDatabaseCaching = false;
-    await addOverlayDisablementDiagnostics(
-      config,
-      codeql,
-      OverlayDisabledReason.DiffInformedAnalysisNotEnabled,
-    );
-  }
-
-  if (hasDiffRanges) {
-    config.extraQueryExclusions.push({
-      exclude: { tags: "exclude-from-incremental" },
-    });
-  }
-}
-
 /**
  * Load and return the config.
  *
@@ -1272,18 +1230,18 @@ export async function initConfig(
     );
   }
 
-  const hasDiffRanges = await prepareDiffInformedAnalysis(
-    inputs.codeql,
-    inputs.features,
-    logger,
-  );
-
-  await applyIncrementalAnalysisSettings(
-    config,
-    hasDiffRanges,
-    inputs.codeql,
-    logger,
-  );
+  if (
+    config.overlayDatabaseMode === OverlayDatabaseMode.Overlay ||
+    (await shouldPerformDiffInformedAnalysis(
+      inputs.codeql,
+      inputs.features,
+      logger,
+    ))
+  ) {
+    config.extraQueryExclusions.push({
+      exclude: { tags: "exclude-from-incremental" },
+    });
+  }
 
   if (await isTrapCachingEnabled(features, config.overlayDatabaseMode)) {
     const { trapCaches, trapCacheDownloadTime } = await downloadCacheWithTime(

src/diff-informed-analysis-utils.test.ts

@@ -5,16 +5,14 @@ import * as actionsUtil from "./actions-util";
 import type { PullRequestBranches } from "./actions-util";
 import * as apiClient from "./api-client";
 import {
-  getDiffInformedAnalysisBranches,
-  prepareDiffInformedAnalysis,
+  shouldPerformDiffInformedAnalysis,
   exportedForTesting,
 } from "./diff-informed-analysis-utils";
-import { Feature, FeatureEnablement, initFeatures } from "./feature-flags";
+import { Feature, initFeatures } from "./feature-flags";
 import { getRunnerLogger } from "./logging";
 import { parseRepositoryNwo } from "./repository";
 import {
   setupTests,
-  createFeatures,
   mockCodeQLVersion,
   mockFeatureFlagApiEndpoint,
   setupActionsVars,
@@ -82,13 +80,13 @@ const testShouldPerformDiffInformedAnalysis = test.macro({
         .stub(actionsUtil, "getPullRequestBranches")
         .returns(testCase.pullRequestBranches);
 
-      const branches = await getDiffInformedAnalysisBranches(
+      const result = await shouldPerformDiffInformedAnalysis(
         codeql,
         features,
         logger,
       );
 
-      t.is(branches !== undefined, expectedResult);
+      t.is(result, expectedResult);
 
       delete process.env.CODEQL_ACTION_DIFF_INFORMED_QUERIES;
 
@@ -96,7 +94,7 @@ const testShouldPerformDiffInformedAnalysis = test.macro({
       getPullRequestBranchesStub.restore();
     });
   },
-  title: (_, title) => `getDiffInformedAnalysisBranches: ${title}`,
+  title: (_, title) => `shouldPerformDiffInformedAnalysis: ${title}`,
 });
 
 test.serial(
@@ -189,135 +187,6 @@ test.serial(
   false,
 );
 
-test.serial(
-  "prepareDiffInformedAnalysis: returns false when not a pull request",
-  async (t) => {
-    await withTmpDir(async (tmpDir) => {
-      setupActionsVars(tmpDir, tmpDir);
-      const logger = getRunnerLogger(true);
-      const codeql = mockCodeQLVersion("2.21.0");
-      const features = createFeatures([Feature.DiffInformedQueries]);
-
-      sinon.stub(actionsUtil, "getPullRequestBranches").returns(undefined);
-      sinon
-        .stub(apiClient, "getGitHubVersion")
-        .resolves({ type: GitHubVariant.DOTCOM });
-
-      const result = await prepareDiffInformedAnalysis(
-        codeql,
-        features,
-        logger,
-      );
-
-      t.false(result);
-    });
-  },
-);
-
-test.serial(
-  "prepareDiffInformedAnalysis: returns false when applicability check throws",
-  async (t) => {
-    await withTmpDir(async (tmpDir) => {
-      setupActionsVars(tmpDir, tmpDir);
-      const logger = getRunnerLogger(true);
-      const codeql = mockCodeQLVersion("2.21.0");
-      // A features implementation whose getValue rejects, simulating an
-      // unexpected failure when determining whether diff-informed analysis
-      // should run.
-      const features: FeatureEnablement = {
-        getDefaultCliVersion: async () => {
-          throw new Error("not implemented");
-        },
-        getValue: async () => {
-          throw new Error("feature flag lookup failed");
-        },
-      };
-
-      const result = await prepareDiffInformedAnalysis(
-        codeql,
-        features,
-        logger,
-      );
-
-      t.false(result);
-    });
-  },
-);
-
-test.serial(
-  "prepareDiffInformedAnalysis: returns true when the diff is fetched successfully",
-  async (t) => {
-    await withTmpDir(async (tmpDir) => {
-      setupActionsVars(tmpDir, tmpDir);
-      const logger = getRunnerLogger(true);
-      const codeql = mockCodeQLVersion("2.21.0");
-      const features = createFeatures([Feature.DiffInformedQueries]);
-
-      sinon
-        .stub(actionsUtil, "getPullRequestBranches")
-        .returns({ base: "main", head: "feature" });
-      sinon
-        .stub(apiClient, "getGitHubVersion")
-        .resolves({ type: GitHubVariant.DOTCOM });
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-      sinon.stub(apiClient, "getApiClient").returns({
-        rest: {
-          repos: {
-            compareCommitsWithBasehead: sinon
-              .stub()
-              .resolves({ data: { files: [] } }),
-          },
-        },
-      } as any);
-
-      const result = await prepareDiffInformedAnalysis(
-        codeql,
-        features,
-        logger,
-      );
-
-      t.true(result);
-    });
-  },
-);
-
-test.serial(
-  "prepareDiffInformedAnalysis: returns false when the diff API call fails",
-  async (t) => {
-    await withTmpDir(async (tmpDir) => {
-      setupActionsVars(tmpDir, tmpDir);
-      const logger = getRunnerLogger(true);
-      const codeql = mockCodeQLVersion("2.21.0");
-      const features = createFeatures([Feature.DiffInformedQueries]);
-
-      sinon
-        .stub(actionsUtil, "getPullRequestBranches")
-        .returns({ base: "main", head: "feature" });
-      sinon
-        .stub(apiClient, "getGitHubVersion")
-        .resolves({ type: GitHubVariant.DOTCOM });
-      const notFoundError: any = new Error("Not Found");
-      notFoundError.status = 404;
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
-      sinon.stub(apiClient, "getApiClient").returns({
-        rest: {
-          repos: {
-            compareCommitsWithBasehead: sinon.stub().rejects(notFoundError),
-          },
-        },
-      } as any);
-
-      const result = await prepareDiffInformedAnalysis(
-        codeql,
-        features,
-        logger,
-      );
-
-      t.false(result);
-    });
-  },
-);
-
 function runGetDiffRanges(changes: number, patch: string[] | undefined): any {
   return exportedForTesting.getDiffRanges(
     {

src/diff-informed-analysis-utils.ts

@@ -5,9 +5,9 @@ import type { PullRequestBranches } from "./actions-util";
 import { getApiClient, getGitHubVersion } from "./api-client";
 import type { CodeQL } from "./codeql";
 import { Feature, FeatureEnablement } from "./feature-flags";
-import { Logger, withGroupAsync } from "./logging";
+import { Logger } from "./logging";
 import { getRepositoryNwoFromEnv } from "./repository";
-import { getErrorMessage, GitHubVariant, satisfiesGHESVersion } from "./util";
+import { GitHubVariant, satisfiesGHESVersion } from "./util";
 
 /**
  * This interface is an abbreviated version of the file diff object returned by
@@ -21,6 +21,20 @@ interface FileDiff {
   patch?: string | undefined;
 }
 
+/**
+ * Check if the action should perform diff-informed analysis.
+ */
+export async function shouldPerformDiffInformedAnalysis(
+  codeql: CodeQL,
+  features: FeatureEnablement,
+  logger: Logger,
+): Promise<boolean> {
+  return (
+    (await getDiffInformedAnalysisBranches(codeql, features, logger)) !==
+    undefined
+  );
+}
+
 /**
  * Get the branches to use for diff-informed analysis.
  *
@@ -55,46 +69,6 @@ export async function getDiffInformedAnalysisBranches(
   return branches;
 }
 
-/**
- * Prepares the diff ranges needed for diff-informed analysis for the current
- * run.
- *
- * @returns `true` if the diff ranges were successfully computed and persisted
- *   and are therefore available for use, `false` otherwise.
- */
-export async function prepareDiffInformedAnalysis(
-  codeql: CodeQL,
-  features: FeatureEnablement,
-  logger: Logger,
-): Promise<boolean> {
-  let branches: PullRequestBranches | undefined;
-  try {
-    branches = await getDiffInformedAnalysisBranches(codeql, features, logger);
-  } catch (e) {
-    // If we cannot determine whether diff-informed analysis applies (for
-    // example, because a feature-flag lookup failed), treat it as not
-    // applicable rather than triggering the overlay fallback.
-    logger.warning(
-      `Failed to determine branch information for diff-informed analysis: ${getErrorMessage(e)}`,
-    );
-    return false;
-  }
-  if (!branches) {
-    return false;
-  }
-
-  return await withGroupAsync("Computing PR diff ranges", async () => {
-    try {
-      return await computeAndPersistDiffRanges(branches, logger);
-    } catch (e) {
-      logger.warning(
-        `Failed to compute diff-informed analysis ranges: ${getErrorMessage(e)}`,
-      );
-      return false;
-    }
-  });
-}
-
 export interface DiffThunkRange {
   /** Relative path from the repository root, using forward slashes as separators. */
   path: string;
@@ -177,33 +151,6 @@ export async function getPullRequestEditedDiffRanges(
   return results;
 }
 
-/**
- * Compute and persist the diff ranges for a pull request. This fetches the
- * diff from the GitHub API and writes it to the diff ranges JSON file so that
- * CodeQL can use it for diff-informed analysis.
- *
- * @param branches The base and head branches of the pull request, as returned
- *   by `getDiffInformedAnalysisBranches`.
- * @param logger
- * @returns `true` if the diff ranges were successfully computed and persisted,
- *   otherwise `false`.
- */
-export async function computeAndPersistDiffRanges(
-  branches: PullRequestBranches,
-  logger: Logger,
-): Promise<boolean> {
-  const ranges = await getPullRequestEditedDiffRanges(branches, logger);
-  if (ranges === undefined) {
-    return false;
-  }
-  writeDiffRangesJsonFile(logger, ranges);
-  const distinctFiles = new Set(ranges.map((r) => r.path)).size;
-  logger.info(
-    `Persisted ${ranges.length} diff range(s) across ${distinctFiles} file(s).`,
-  );
-  return true;
-}
-
 async function getFileDiffsWithBasehead(
   branches: PullRequestBranches,
   logger: Logger,

src/init-action.ts

@@ -37,6 +37,11 @@ import {
   makeDiagnostic,
   makeTelemetryDiagnostic,
 } from "./diagnostics";
+import {
+  getDiffInformedAnalysisBranches,
+  getPullRequestEditedDiffRanges,
+  writeDiffRangesJsonFile,
+} from "./diff-informed-analysis-utils";
 import { EnvVar } from "./environment";
 import { Feature, FeatureEnablement, initFeatures } from "./feature-flags";
 import {
@@ -422,6 +427,7 @@ async function run(startedAt: Date) {
     }
 
     await checkInstallPython311(config.languages, codeql);
+    await computeAndPersistDiffRanges(codeql, features, logger);
   } catch (unwrappedError) {
     const error = wrapError(unwrappedError);
     core.setFailed(error.message);
@@ -817,6 +823,42 @@ async function loadRepositoryProperties(
   }
 }
 
+/**
+ * Compute and persist diff ranges when diff-informed analysis is enabled
+ * (feature flag + PR context). This writes the standard pr-diff-range.json
+ * file for later reuse in the analyze step. Failures are logged but non-fatal.
+ */
+async function computeAndPersistDiffRanges(
+  codeql: CodeQL,
+  features: FeatureEnablement,
+  logger: Logger,
+): Promise<void> {
+  await withGroupAsync("Computing PR diff ranges", async () => {
+    try {
+      const branches = await getDiffInformedAnalysisBranches(
+        codeql,
+        features,
+        logger,
+      );
+      if (!branches) {
+        return;
+      }
+      const ranges = await getPullRequestEditedDiffRanges(branches, logger);
+      if (ranges === undefined) {
+        return;
+      }
+      writeDiffRangesJsonFile(logger, ranges);
+      const distinctFiles = new Set(ranges.map((r) => r.path)).size;
+      logger.info(
+        `Persisted ${ranges.length} diff range(s) across ${distinctFiles} file(s).`,
+      );
+    } catch (e) {
+      logger.warning(
+        `Failed to compute and persist PR diff ranges: ${getErrorMessage(e)}`,
+      );
+    }
+  });
+}
 async function recordZstdAvailability(
   config: configUtils.Config,
   zstdAvailability: ZstdAvailability,

src/overlay/caching.test.ts

@@ -7,7 +7,7 @@ import * as sinon from "sinon";
 
 import * as actionsUtil from "../actions-util";
 import * as apiClient from "../api-client";
-import type { ResolveDatabaseOutput } from "../codeql";
+import { ResolveDatabaseOutput } from "../codeql";
 import * as gitUtils from "../git-utils";
 import { BuiltInLanguage } from "../languages";
 import { getRunnerLogger } from "../logging";
@@ -23,7 +23,6 @@ import {
   downloadOverlayBaseDatabaseFromCache,
   getCacheRestoreKeyPrefix,
   getCacheSaveKey,
-  getCodeQlVersionsForOverlayBaseDatabases,
 } from "./caching";
 import { OverlayDatabaseMode } from "./overlay-database-mode";
 
@@ -286,134 +285,3 @@ test.serial("overlay-base database cache keys remain stable", async (t) => {
     `Expected save key "${saveKey}" to start with restore key prefix "${restoreKeyPrefix}"`,
   );
 });
-
-test.serial(
-  "getCodeQlVersionsForOverlayBaseDatabases returns unique versions sorted latest first",
-  async (t) => {
-    const logger = getRunnerLogger(true);
-
-    sinon.stub(apiClient, "getAutomationID").resolves("test-automation-id/");
-    sinon.stub(apiClient, "listActionsCaches").resolves([
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-javascript_python-2.23.0-abc123-1-1",
-      },
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-javascript_python-2.24.1-def456-2-1",
-      },
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-javascript_python-2.23.0-ghi789-3-1",
-      },
-    ]);
-
-    const result = await getCodeQlVersionsForOverlayBaseDatabases(
-      ["javascript", "python"],
-      logger,
-    );
-    t.deepEqual(result, ["2.24.1", "2.23.0"]);
-  },
-);
-
-test.serial(
-  "getCodeQlVersionsForOverlayBaseDatabases returns empty list when no caches exist",
-  async (t) => {
-    const logger = getRunnerLogger(true);
-
-    sinon.stub(apiClient, "getAutomationID").resolves("test-automation-id/");
-    sinon.stub(apiClient, "listActionsCaches").resolves([]);
-
-    const result = await getCodeQlVersionsForOverlayBaseDatabases(
-      ["python"],
-      logger,
-    );
-    t.deepEqual(result, []);
-  },
-);
-
-test.serial(
-  "getCodeQlVersionsForOverlayBaseDatabases returns empty list when cache keys are unparseable",
-  async (t) => {
-    const logger = getRunnerLogger(true);
-
-    sinon.stub(apiClient, "getAutomationID").resolves("test-automation-id/");
-    sinon.stub(apiClient, "listActionsCaches").resolves([
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-python-malformed",
-      },
-      { key: undefined },
-    ]);
-
-    const result = await getCodeQlVersionsForOverlayBaseDatabases(
-      ["python"],
-      logger,
-    );
-    t.deepEqual(result, []);
-  },
-);
-
-test.serial(
-  "getCodeQlVersionsForOverlayBaseDatabases returns the single version when only one cache exists",
-  async (t) => {
-    const logger = getRunnerLogger(true);
-
-    sinon.stub(apiClient, "getAutomationID").resolves("test-automation-id/");
-    sinon.stub(apiClient, "listActionsCaches").resolves([
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-cpp-2.25.0-abc123-1-1",
-      },
-    ]);
-
-    const result = await getCodeQlVersionsForOverlayBaseDatabases(
-      ["cpp"],
-      logger,
-    );
-    t.deepEqual(result, ["2.25.0"]);
-  },
-);
-
-test.serial(
-  "getCodeQlVersionsForOverlayBaseDatabases resolves language aliases",
-  async (t) => {
-    const logger = getRunnerLogger(true);
-    // The alias `c++` should be resolved to "cpp" and match cache entries keyed with "cpp"
-
-    sinon.stub(apiClient, "getAutomationID").resolves("test-automation-id/");
-    sinon.stub(apiClient, "listActionsCaches").resolves([
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-cpp-2.25.0-abc123-1-1",
-      },
-    ]);
-
-    const result = await getCodeQlVersionsForOverlayBaseDatabases(
-      ["c++"],
-      logger,
-    );
-    t.deepEqual(result, ["2.25.0"]);
-  },
-);
-
-test.serial(
-  "getCodeQlVersionsForOverlayBaseDatabases ignores nightly versions with build metadata",
-  async (t) => {
-    const logger = getRunnerLogger(true);
-
-    sinon.stub(apiClient, "getAutomationID").resolves("test-automation-id/");
-    sinon.stub(apiClient, "listActionsCaches").resolves([
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-python-2.25.0-abc123-1-1",
-      },
-      {
-        // Nightly release with semver build metadata; should be ignored.
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-python-2.26.0+202604211234-def456-2-1",
-      },
-      {
-        key: "codeql-overlay-base-database-1-c5666c509a2d9895-python-2.24.0-ghi789-3-1",
-      },
-    ]);
-
-    const result = await getCodeQlVersionsForOverlayBaseDatabases(
-      ["python"],
-      logger,
-    );
-    t.deepEqual(result, ["2.25.0", "2.24.0"]);
-  },
-);

src/overlay/caching.ts

@@ -1,20 +1,18 @@
 import * as fs from "fs";
 
 import * as actionsCache from "@actions/cache";
-import * as semver from "semver";
 
 import {
   getRequiredInput,
   getWorkflowRunAttempt,
   getWorkflowRunID,
 } from "../actions-util";
-import { getAutomationID, listActionsCaches } from "../api-client";
+import { getAutomationID } from "../api-client";
 import { createCacheKeyHash } from "../caching-utils";
 import { type CodeQL } from "../codeql";
 import { type Config } from "../config-utils";
 import { getCommitOid } from "../git-utils";
-import { type Language, parseBuiltInLanguage } from "../languages";
-import { type Logger, withGroupAsync } from "../logging";
+import { Logger, withGroupAsync } from "../logging";
 import {
   CleanupLevel,
   getBaseDatabaseOidsFilePath,
@@ -406,17 +404,7 @@ export async function getCacheRestoreKeyPrefix(
   config: Config,
   codeQlVersion: string,
 ): Promise<string> {
-  return `${await getCacheKeyPrefixBase(config.languages)}${codeQlVersion}-`;
-}
-
-/**
- * Computes the cache key prefix for overlay-base databases, excluding the
- * CodeQL version.
- */
-async function getCacheKeyPrefixBase(
-  parsedLanguages: Language[],
-): Promise<string> {
-  const languagesComponent = [...parsedLanguages].sort().join("_");
+  const languages = [...config.languages].sort().join("_");
 
   const cacheKeyComponents = {
     automationID: await getAutomationID(),
@@ -424,97 +412,17 @@ async function getCacheKeyPrefixBase(
   };
   const componentsHash = createCacheKeyHash(cacheKeyComponents);
 
+  // For a cached overlay-base database to be considered compatible for overlay
+  // analysis, all components in the cache restore key must match:
+  //
   // CACHE_PREFIX: distinguishes overlay-base databases from other cache objects
   // CACHE_VERSION: cache format version
   // componentsHash: hash of additional components (see above for details)
-  // languagesComponent: the languages included in the overlay-base database
+  // languages: the languages included in the overlay-base database
+  // codeQlVersion: CodeQL bundle version
   //
-  // Technically we can also include languages in the componentsHash, but
-  // including them explicitly in the cache key makes it easier to debug and
-  // understand the cache key structure.
-  return `${CACHE_PREFIX}-${CACHE_VERSION}-${componentsHash}-${languagesComponent}-`;
-}
-
-/**
- * Searches the GitHub Actions cache for overlay-base databases matching the given languages, and
- * returns all stable CodeQL versions found across matching cache entries.
- *
- * Note that we do not guarantee that the cache entry for these versions of CodeQL will still be
- * present by the time we attempt to restore the cache. We could achieve that with a download retry
- * loop, but we expect that if there is sufficient Actions cache contention that an overlay-base
- * cache entry for a particular CodeQL version is evicted before we can use it, then it is likely
- * that the same thing will happen to other overlay-base cache entries, and therefore we will not be
- * able to use overlay.
- *
- * @returns Unique stable CodeQL versions found in cached overlay-base databases, sorted from latest to
- * earliest, or undefined if one of the languages is not a built-in language.
- */
-export async function getCodeQlVersionsForOverlayBaseDatabases(
-  rawLanguages: string[],
-  logger: Logger,
-): Promise<string[] | undefined> {
-  const languages = rawLanguages.map(parseBuiltInLanguage);
-  if (languages.includes(undefined)) {
-    logger.warning(
-      "One or more provided languages are not recognized as built-in languages. " +
-        "Skipping searching for overlay-base databases in cache.",
-    );
-    return undefined;
-  }
-  const cacheKeyPrefix = await getCacheKeyPrefixBase(
-    languages.filter((l) => l !== undefined),
-  );
-
-  logger.debug(
-    `Searching for overlay-base databases in Actions cache with ` +
-      `prefix ${cacheKeyPrefix}`,
-  );
-
-  const caches = await listActionsCaches(cacheKeyPrefix);
-
-  if (caches.length === 0) {
-    logger.info("No overlay-base databases found in Actions cache.");
-    return [];
-  }
-
-  logger.info(
-    `Found ${caches.length} overlay-base ` +
-      `${caches.length === 1 ? "database" : "databases"} in the Actions cache.`,
-  );
-
-  // Parse CodeQL versions from cache keys, matching only stable releases.
-  //
-  // After the prefix, the remaining key format starts with `${codeQlVersion}-`. Nightlies will have
-  // a suffix like `+202604201548` that will break the match.
-  //
-  // Caveat: this relies on the fact that we haven't released any CodeQL bundles with the
-  // `x.y.z-<pre-release>` semver format which does not interact well with the current overlay base
-  // DB cache key format.
-  const versionRegex = /^([\d.]+)-/;
-  const versionSet = new Set<string>();
-
-  for (const cache of caches) {
-    if (!cache.key) continue;
-    const suffix = cache.key.substring(cacheKeyPrefix.length);
-    const match = suffix.match(versionRegex);
-    if (match && semver.valid(match[1])) {
-      versionSet.add(match[1]);
-    }
-  }
-
-  if (versionSet.size === 0) {
-    logger.info(
-      "Could not parse any CodeQL versions from overlay-base database " +
-        "cache keys.",
-    );
-    return [];
-  }
-
-  const versions = [...versionSet].sort(semver.rcompare);
-
-  logger.info(
-    `Found overlay databases for the following CodeQL versions in the Actions cache: ${versions.join(", ")}`,
-  );
-
-  return versions;
+  // Technically we can also include languages and codeQlVersion in the
+  // componentsHash, but including them explicitly in the cache key makes it
+  // easier to debug and understand the cache key structure.
+  return `${CACHE_PREFIX}-${CACHE_VERSION}-${componentsHash}-${languages}-${codeQlVersion}-`;
 }

src/overlay/diagnostics.ts

@@ -39,15 +39,6 @@ export enum OverlayDisabledReason {
   NotPullRequestOrDefaultBranch = "not-pull-request-or-default-branch",
   /** The top-level overlay analysis feature flag is not enabled. */
   OverallFeatureNotEnabled = "overall-feature-not-enabled",
-  /**
-   * 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.
-   */
-  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. */