Overlay: check query packs for compatibility #2993

cklin · 2025-07-25T21:32:59Z

This PR updates the init action to prevent overlay analysis (or overlay-base database construction) when one of the query packs involved does not support overlay analysis with the installed CodeQL CLI.

@alexet Please review the aspects concerning interaction with the CodeQL bundle
@mbg Please review all other aspects of the change

Merge / deployment checklist

Confirm this change is backwards compatible with existing workflows.
Confirm the readme has been updated if necessary.
Confirm the changelog has been updated if necessary.

Copilot

Pull Request Overview

This PR adds compatibility checking for query packs with overlay analysis in the CodeQL Action, preventing overlay analysis when query packs don't support the feature. The overlay minimum version is also updated from 2.20.5 to 2.22.2.

Implements pack compatibility checking that validates overlay version requirements
Refactors database initialization to support re-initialization when incompatible packs are found
Updates minimum CodeQL version for overlay support and adds comprehensive test coverage

Reviewed Changes

Copilot reviewed 14 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/testing-utils.ts	Adds overlayVersion parameter to makeVersionInfo utility for testing
src/overlay-database-utils.ts	Updates minimum CodeQL version for overlay support from 2.20.5 to 2.22.2
src/init.ts	Refactors database initialization and adds pack compatibility checking logic
src/init.test.ts	Adds comprehensive tests for pack compatibility checking functionality
src/init-action.ts	Integrates pack compatibility checking into the main initialization flow
src/config-utils.test.ts	Updates test to use new minimum overlay version constant
src/codeql.ts	Adds resolvePacks method interface and implementation
lib/*	Generated JavaScript files mirroring the TypeScript changes

Comments suppressed due to low confidence (1)

src/init.test.ts:146

The type name PackInfo conflicts with the interface PackInfo exported from src/codeql.ts. Consider renaming this test-specific type to avoid confusion, such as TestPackInfo or MockPackInfo.

type PackInfo = {
  kind: "query" | "library";
  packinfoContents?: string;
};

src/init.test.ts

Copilot · 2025-07-29T19:20:52Z

src/init.ts

+      return true;
+    }
+
+    const packInfoPath = path.join(path.dirname(packInfo.path), ".packinfo");


The hard-coded .packinfo filename is used multiple times in this function. Consider extracting it as a constant (e.g., PACK_INFO_FILENAME) to improve maintainability and reduce the risk of typos.

Suggested change

const packInfoPath = path.join(path.dirname(packInfo.path), ".packinfo");

const packInfoPath = path.join(path.dirname(packInfo.path), PACK_INFO_FILENAME);

Copilot · 2025-07-29T19:20:52Z

src/init.ts

+
+    const packInfoFileContents = JSON.parse(
+      fs.readFileSync(packInfoPath, "utf8"),
+    );


JSON parsing errors should be caught and provide more descriptive error messages. The current catch block at line 225 doesn't distinguish between file system errors and JSON parsing errors, which could make debugging more difficult.

alexet

It doesn't feel to me that resolve packs is quite the right command (although it looks like it will work).It feels like we should run resolve queries with --format startingpacks to find the query packs we care about, and then just use those.

But I am also not fully sure of all the subtleties of either choice.

cklin · 2025-07-31T16:06:10Z

It doesn't feel to me that resolve packs is quite the right command (although it looks like it will work).It feels like we should run resolve queries with --format startingpacks to find the query packs we care about, and then just use those.

But I am also not fully sure of all the subtleties of either choice.

Thanks for the suggestion!

When I first looked into the problem, I considered this approach but was unable to get it to work. While codeql resolve queries with --format startingpacks can map queries to their containing query packs, there does not seem to be a way to get the list of queries that would be used in the analysis and feed that into codeql resolve queries. I could see that codeql database init already computes that information (though a deep-plumbing subcommand) for internal use, but no easy way to obtain that information from outside the CodeQL CLI. Re-interpreting the Code Scanning config file in the action seems like a lot of work for relatively little gain.

Prompted by your suggestion, I looked again. This time I noticed that codeql database init actually generates config-queries.qls suite file with the list of queries, so all I need to do is to feed that suite file into codeql resolve queries, and I can get the list of query packs to check for overlay compatibility.

(There is the slight complication that codeql resolve queries --format startingpacks would also return query packs that have not been compiled. I will have to make the action ignore those query packs when checking for overlay compatibility.)

This commit inlines runInit(), so that it is easier to repeat the runDatabaseInitCluster() call when needed.

cklin · 2025-07-31T20:38:00Z

It doesn't feel to me that resolve packs is quite the right command (although it looks like it will work).It feels like we should run resolve queries with --format startingpacks to find the query packs we care about, and then just use those.

I updated the PR to use this approach to identify the query packs to check for overlay compatibility. Related changes:

I removed the commit that adds resolvePacks() to the CodeQL interface
Instead, there is now a commit to add resolveQueriesStartingPacks()
To avoid confusion, I removed the unused resolveQueries() from CodeQL
While I am at it, I also removed the unused packDownload() from CodeQL

The other commits remain the same as before. PTAL.

cklin force-pushed the cklin/overlay-pack-check branch 4 times, most recently from 230fc32 to d0d4112 Compare July 29, 2025 18:58

cklin marked this pull request as ready for review July 29, 2025 19:20

Copilot AI review requested due to automatic review settings July 29, 2025 19:20

cklin requested a review from a team as a code owner July 29, 2025 19:20

cklin requested review from mbg and alexet July 29, 2025 19:20

Copilot AI reviewed Jul 29, 2025

View reviewed changes

alexet reviewed Jul 31, 2025

View reviewed changes

cklin marked this pull request as draft July 31, 2025 16:06

cklin added 11 commits July 31, 2025 11:27

Update CODEQL_OVERLAY_MINIMUM_VERSION

25b4e2f

VersionInfo: add overlayVersion field

cb19286

Remove resolveQueries()

30383e4

Remove packDownload()

1570bf1

Add resolveQueriesStartingPacks()

9a9af90

Add checkPacksForOverlayCompatibility()

abfb9f4

Extract runDatabaseInitCluster()

94afc7d

Inline runInit()

b72635c

This commit inlines runInit(), so that it is easier to repeat the runDatabaseInitCluster() call when needed.

init-action: check packs for overlay compatibility

4e500d9

init-action: inhibit non-empty dbLocation warning when restarting

7066904

build: refresh js files

f1a0360

cklin force-pushed the cklin/overlay-pack-check branch from d0d4112 to f1a0360 Compare July 31, 2025 18:31

cklin marked this pull request as ready for review July 31, 2025 20:38

cklin requested a review from alexet July 31, 2025 20:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Overlay: check query packs for compatibility #2993

Overlay: check query packs for compatibility #2993

cklin commented Jul 25, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Copilot AI Jul 29, 2025

Uh oh!

Copilot AI Jul 29, 2025

Uh oh!

alexet left a comment

Uh oh!

cklin commented Jul 31, 2025

Uh oh!

cklin commented Jul 31, 2025

Uh oh!

Uh oh!

	const packInfoPath = path.join(path.dirname(packInfo.path), ".packinfo");
	const packInfoPath = path.join(path.dirname(packInfo.path), PACK_INFO_FILENAME);

Overlay: check query packs for compatibility #2993

Are you sure you want to change the base?

Overlay: check query packs for compatibility #2993

Conversation

cklin commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge / deployment checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jul 29, 2025

Choose a reason for hiding this comment

Uh oh!

alexet left a comment

Choose a reason for hiding this comment

Uh oh!

cklin commented Jul 31, 2025

Uh oh!

cklin commented Jul 31, 2025

Uh oh!

Uh oh!

cklin commented Jul 25, 2025 •

edited

Loading