Support undefined, number, and object in JSON module

[mario-campos]

Summary

This pull request introduces several additions to the JSON schema-validation utilities:

• Renamed the optional validator to optionalOrNull to clarify that schema fields may be optional and accept null as a valid value, in addition to undefined.
• Redefined the optional validator so that it only accepts undefined (not null), making its behavior more precise and distinct from optionalOrNull.
• Added new built-in validators for number and object types.
• Added an isNumber type guard function for type checking.

This PR is a prerequisite for #3950.

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.

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?

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

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

This PR extends the internal JSON schema-validation helpers to better distinguish “optional” vs “optional-or-null” fields, and to add first-class validators for number and object. It also updates start-proxy configuration schemas to use the new optionalOrNull semantics and adjusts unit tests accordingly.

Changes:

• Introduces isNumber, plus json.number and json.object validators.
• Renames the old “optional (undefined or null)” behavior to optionalOrNull and redefines optional to mean “undefined-only”.
• Updates start-proxy schemas and unit tests to reflect the new optional semantics.

Show a summary per file

File	Description
src/start-proxy/types.ts	Switches relevant schema fields from optional to optionalOrNull for backwards-compatible null acceptance.
src/json/index.ts	Adds number/object validators and splits optional handling into optionalOrNull vs optional.
src/json/index.test.ts	Updates/expands tests to cover the new optional semantics (optionalOrNull vs optional).
lib/entry-points.js	Generated output (content excluded from review per policy).

Review details

Files excluded by content exclusion policy (1)

• lib/entry-points.js

• Files reviewed: 3/4 changed files
• Comments generated: 3
• Review effort level: Low

[mbg]

For top-level objects, we'd call validateSchema on them along with the relevant schema. Adding this object validator to schemas seems a bit simplistic. Is the intention here to say "I want to accept an arbitrary object"? If so, then it might be better off as being named any or similar, rather than object. If not, then perhaps this should be parameterised over a schema:

Suggested change

	export const object = {
	validate: isObject<any>,
	required: true,
	} as const satisfies Validator<UnvalidatedObject<any>>;
	export const object = <S extends Schema>(schema: S) => ...;

[mario-campos]

Here's the use-case:

json.validateSchema(
  {
    version: json.string,
    features: json.optional(json.object),
    overlayVersion: json.optional(json.number),
  },
  x,
);

where features here refers to VersionInfo.features.

[mbg]

OK, so there is a schema for features (a mapping of strings to booleans) that could be expressed if we wanted to. I think it's better for us to leave the conversation about the schema validation for the CLI output to the other PR, but the relevant flow chart for my comment was:

• If you just want to validate arbitrary objects, rename it to any or similar instead of object.
• If not, change object to validate a specific object schema.