Break down overlay disabled reason

[henrymercer]

Break down the two most common categories to help us better understand why overlay isn't run.

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, Code Quality, ...).

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?

• 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?

• Rollback - Change can only be disabled by rolling back the release or releasing a new version with a fix.

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 PR refines overlay-analysis disablement reporting by splitting previously broad disablement categories into more specific OverlayDisabledReason values, primarily to improve telemetry and diagnostics around why overlay analysis doesn’t run.

Changes:

• Expand OverlayDisabledReason to distinguish disk vs memory resource failures and feature-enablement sub-cases.
• Refactor overlay enablement/resource checks to return a specific disablement reason (or undefined when enabled).
• Update unit tests to expect the new disablement reasons.

Reviewed changes

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

File	Description
src/overlay/diagnostics.ts	Extends OverlayDisabledReason with more granular reason values used for telemetry.
src/config-utils.ts	Refactors overlay enablement/resource-check logic to return specific disablement reasons.
src/config-utils.test.ts	Updates overlay mode tests to assert the new disablement reasons.
lib/init-action.js	Generated output reflecting the TypeScript changes (not reviewed).

[mbg]

Thanks for working on this -- getting a more detailed reason for why overlay is disabled is useful!

That said, I am not overly fond of some of the details of the changes here, sorry! See my comments for the details.

[mbg]

Thanks for iterating on the feedback! This looks better to me now, although the diff for b371ccd is a bit horrible to review -- it would have been good to commit some of those changes more incrementally.

Just some minor comments left which aren't blocking, so I am happy to approve!

[mbg]

Minor: Since this is used at least a couple of times in this file now, extract it into a type definition type OverlayEnabledResult = { enabled: true } | { enabled: false; reason: OverlayDisabledReason }.

We have similar-ish patterns elsewhere, so we could also move it to util as something like type EnablementResult<T> = { enabled: true } | { enabled: false; reason: T }, but this doesn't have to be done here.

Perhaps add helper definitions along the lines of const enabled = { enabled: true } and function disabled<T>(reason: T) { return { enabled: false; reason }; }

[henrymercer]

I've decided to refactor this into a Result, since there's no need to repeat overlayDatabaseMode: OverlayDatabaseMode.None and useOverlayDatabaseCaching: false.