Cache first failure building an overlay base DB to avoid repeated failures

[henrymercer]

When overlay analysis (improved incremental analysis) fails on a runner — typically due to insufficient disk space — this PR records that failure in the Actions cache so that subsequent runs will skip overlay analysis automatically until something changes (e.g. a larger runner is provisioned or a new CodeQL version is released).

See the backlinked internal issue for more information.

I recommend reviewing the first commit separately from the rest as this moves the overlay utilities into their own directory.

Risk assessment

For internal use only. Please select the risk level of this change:

• Low risk: Changes are fully under feature flags, or have been fully tested and validated in pre-production environments and are highly observable, or are documentation or test only.

Which use cases does this change impact?

Workflow types:

• Advanced setup - Impacts users who have custom CodeQL workflows.
• Managed - Impacts users with dynamic workflows (Default Setup, CCR, ...).

Products:

• Code Scanning - The changes impact analyses when analysis-kinds: code-scanning.

Environments:

• Dotcom - Impacts CodeQL workflows on github.com and/or GitHub Enterprise Cloud with Data Residency.

How did/will you validate this change?

• Test repository - This change will be tested on a test repository before merging.
• Unit tests - I am depending on unit test coverage (i.e. tests in .test.ts files).

If something goes wrong after this change is released, what are the mitigation and rollback strategies?

• Feature flags - All new or changed code paths can be fully disabled with corresponding feature flags.

How will you know if something goes wrong after this change is released?

• Telemetry - I rely on existing telemetry or have made changes to the telemetry.
  • Dashboards - I will watch relevant dashboards for issues after the release. Consider whether this requires this change to be released at a particular time rather than as part of a regular release.
  • Alerts - New or existing monitors will trip if something goes wrong with this change.

Are there any special considerations for merging or releasing this change?

• No special considerations - This change can be merged at any time.

Merge / deployment checklist

• Confirm this change is backwards compatible with existing workflows.
• Consider adding a changelog entry for this change.
• Confirm the readme and docs have been updated if necessary.

[Copilot]

Pull request overview

This pull request implements a caching mechanism to avoid repeated failures when overlay analysis (improved incremental analysis) fails on a runner due to insufficient resources, typically disk space. The PR introduces a status tracking system that records failures in the Actions cache, allowing subsequent runs to skip overlay analysis automatically until conditions change (e.g., runner upgrade or new CodeQL version).

Changes:

• Added a new src/overlay/status.ts module to track and persist overlay analysis failures via Actions cache
• Modified src/init-action-post-helper.ts to record failures when overlay base database builds are unsuccessful
• Updated src/config-utils.ts to check cached status and skip overlay analysis when previous failures are detected
• Added two new feature flags: OverlayAnalysisStatusCheck and OverlayAnalysisStatusSave
• Modified bundleDb function signature to accept an includeDiagnostics parameter
• Reorganized overlay-related imports from overlay-database-utils to overlay module structure

Reviewed changes

Copilot reviewed 29 out of 31 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/overlay/status.ts	New module implementing status persistence using Actions cache with timeout handling
src/overlay/status.test.ts	Comprehensive unit tests for the new status tracking functionality
src/init-action-post-helper.ts	Integration to save failure status after unsuccessful overlay-base builds
src/init-action-post-helper.test.ts	Tests verifying status saving under different conditions (failure, success, disabled)
src/config-utils.ts	Integration to check cached status and skip overlay analysis when indicated
src/config-utils.test.ts	Tests for skipping overlay analysis based on cached status
src/feature-flags.ts	Added two new feature flags for status check and save operations
src/util.ts	Modified bundleDb signature to accept includeDiagnostics parameter
src/database-upload.ts	Updated bundleDb call to pass includeDiagnostics: false
src/debug-artifacts.ts	Updated bundleDb call to pass includeDiagnostics: true
src/doc-url.ts	Added new documentation URL for deleting Actions cache entries
src/testing-utils.ts	Updated import path from overlay-database-utils to overlay
src/status-report.ts	Updated import path from overlay-database-utils to overlay
src/overlay/index.ts	Updated import paths to use relative paths from parent directory
src/overlay/index.test.ts	Updated imports to match new module structure
src/init-action.ts	Updated import path from overlay-database-utils to overlay
src/analyze.ts	Updated import path from overlay-database-utils to overlay
src/analyze-action.ts	Updated import path from overlay-database-utils to overlay
src/codeql.ts	Updated databaseBundle signature to include includeDiagnostics parameter
lib/*	Generated JavaScript files reflecting all TypeScript changes