Add support for an explicit remote path prefix

[mbg]

This is an alternative to #4012 which addresses the same issue. The first few commits here are the same as there and increase test coverage and refactor a couple of functions.

The approach to resolving the issue here is different, however: instead of trying to find the file locally as in #4012 and always treat ambiguous paths as remote paths, we instead add support for a prefix that allows user to explicitly indicate that a configuration file path is supposed to refer to a remote file.

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.
• Code Quality - The changes impact analyses when analysis-kinds: code-quality.
• Other first-party - The changes impact other first-party analyses.

Environments:

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

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).
• End-to-end tests - I am depending on PR checks (i.e. tests in pr-checks).

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]

Warning

• Copilot's review of this pull request may be incomplete because some of the changed files are excluded by your Copilot content exclusion settings. See Excluding content from Copilot for details.

Pull request overview

Adds an explicit :: prefix to disambiguate remote CodeQL configuration paths.

Changes:

• Adds local/remote path prefix handling.
• Refactors remote address parsing and test helpers.
• Expands local and remote configuration tests.

Show a summary per file

File	Description
src/config/file.ts	Defines local and remote path prefixes.
src/config-utils.ts	Routes prefixed paths and loads configurations.
src/config-utils.test.ts	Tests local and remote path handling.
src/config/remote-file.ts	Extracts new-format address parsing.
src/testing-utils.ts	Exports a minimal assertion interface.
lib/entry-points.js	Generated artifact; excluded from review.

Review details

Files excluded by content exclusion policy (1)

• lib/entry-points.js

• Files reviewed: 5/6 changed files
• Comments generated: 4
• Review effort level: Medium

[henrymercer]

Bike shed about the prefix, but otherwise LGTM!

[henrymercer]

What about something like remote:? It's five additional characters but can't be confused with two : separator characters.

[mbg]

I have no strong feelings on :: and am happy to change it to something else, but I don't think that remote: would be a good choice because, if you have a repo in your organisation named remote, e.g. remote:codeql.yml would be a valid remote file address that instructs us to fetch codeql.yml from org/remote, and a remote: prefix would clash with that and cause us to truncate it to just codeql.yml. That's why I think the prefix should start with a character that's not allowed in repo or org names.

[henrymercer]

Good point, how about remote=org/repo@ref:path or remote(org/repo@ref:path)?

[mbg]

I have changed the prefix to remote= in 3492b7e

[Copilot]

Warning

• Copilot's review of this pull request may be incomplete because some of the changed files are excluded by your Copilot content exclusion settings. See Excluding content from Copilot for details.

Review details

Files excluded by content exclusion policy (1)

• lib/entry-points.js

• Files reviewed: 5/6 changed files
• Comments generated: 1
• Review effort level: Medium