Extract getTopLevelVariants for testable top-level oneOf rendering

[superhighfives]

What

Extracts getTopLevelVariants (and the SchemaVariant type) from SchemaDisplay.astro into src/util/model-schema.ts, alongside detectApiModes, and adds unit tests that lock in correct rendering of titled top-level oneOf model schemas.

Behavior is unchanged — this is a behavior-preserving refactor plus tests. No rendering or detection logic is modified, and no catalog-models data is touched.

Why

The AI Gateway catalog API will start emitting a faithful top-level oneOf for variable-schema models (multi-format models like the GPT-5 and Gemini families) — see ai-gateway-infra MR !462. Each request-format branch carries a human-readable title (e.g. "Chat Completions" / "Responses").

The docs already render this shape correctly: detectApiModes does not hijack it (no requests/binary signals → single mode → falls through), and SchemaDisplay's getTopLevelVariants surfaces the titled branches into the variant selector. This PR proves that behavior with tests and makes the gate unit-testable, so the rendering is protected for whenever the data lands.

Tests

New src/util/model-schema.node.test.ts (10 tests):

• detectApiModes returns undefined for the titled request-format oneOf (no API-mode hijack), input and output.
• detectApiModes still correctly splits genuine Workers AI sync/batch and sync/streaming schemas (refactor doesn't weaken real behavior).
• getTopLevelVariants surfaces the "Chat Completions" / "Responses" titles for both sides; returns null for flat / untitled / single-branch schemas.

Local: vitest Node project 10/10 new + no regressions; astro check 0 errors; eslint 0 errors on touched files.

Sequencing

Safe to merge independently — behavior-preserving. The actual catalog-models/*.json data refresh (which makes the variant selector appear on real model pages) is a separate change, gated on !462 being deployed and promoted to production.

Refs AIG-1175.

[cloudflare-docs-bot]

Review

✅ No style-guide issues found in commit de66363.

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
*.astro	@cloudflare/content-engineering, @kodster28
*.ts	@cloudflare/content-engineering, @kodster28

[Copilot]

Pull request overview

This PR extracts the top-level oneOf/anyOf variant-tab detection (getTopLevelVariants + SchemaVariant) out of SchemaDisplay.astro into the shared src/util/model-schema.ts, and adds Node Vitest coverage to lock in the intended behavior for titled top-level oneOf model schemas (request-format branches like “Chat Completions” vs “Responses”). This supports upcoming AI Gateway catalog schema shapes while preserving current rendering behavior.

Changes:

• Moved getTopLevelVariants and SchemaVariant from SchemaDisplay.astro into src/util/model-schema.ts (alongside detectApiModes).
• Updated SchemaDisplay.astro to import and use the extracted utility.
• Added src/util/model-schema.node.test.ts with coverage for both the “no API-mode hijack” case and genuine Workers AI mode-splitting cases.

Reviewed changes

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

File	Description
src/util/model-schema.ts	Adds exported SchemaVariant and getTopLevelVariants utility for top-level titled oneOf/anyOf variant selection.
src/util/model-schema.node.test.ts	Introduces unit tests covering request-format top-level oneOf behavior and ensuring detectApiModes still splits real sync/batch and sync/streaming shapes.
src/components/models/SchemaDisplay.astro	Replaces in-file helper/type with an import from ~/util/model-schema and keeps rendering logic unchanged.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ask-bonk]

Clean behavior-preserving refactor. No issues found.

Summary: Extracts getTopLevelVariants and the SchemaVariant type from SchemaDisplay.astro into src/util/model-schema.ts, adds 10 unit tests locking in correct rendering of titled top-level oneOf schemas. pnpm run check and pnpm vitest run both pass cleanly.

Labels applied: docs engine, engineering

[ask-bonk]

Done. Here's what I found:

Labels applied: docs engine, engineering

PR assessment: This is a clean, behavior-preserving refactor. No issues found.

• getTopLevelVariants and the SchemaVariant type are cleanly extracted from SchemaDisplay.astro into src/util/model-schema.ts
• Import path ~/util/model-schema resolves correctly via the existing ~/* → src/* path alias
• New test file src/util/model-schema.node.test.ts has solid coverage: both detectApiModes boundaries (refusing to hijack titled request-format oneOf, while still splitting genuine sync/batch/streaming schemas) and getTopLevelVariants edge cases (titled branches, flat schemas, untitled branches, single-branch oneOf)
• pnpm run check, lint, and the new Vitest suite all pass with zero errors

Action taken: Approved PR #31226 with a summary review comment.

github run

[github-actions]

Preview URL: https://de663634.preview.developers.cloudflare.com
Preview Branch URL: https://aig-1175-docs-oneof-schema-variants.preview.developers.cloudflare.com