refactor(docs): read documented enum values through one shared reader

[kozlek]

The engine is changing how it publishes per-value documentation for a
schema's choice set, moving from an x-enum-descriptions map to a
positional x-mergify-enum array that also carries a display title and a
deprecation flag. Schema syncs land as direct pushes to main, so the docs
repo cannot assume both sides move together.

Introduce readEnumChoices, which tolerates every shape a synced schema
can be in during that migration: values as a flat enum, a const, or
the anyOf of branches a composed Literal produces, with the node — or
any single branch of it — either inline or behind a $ref. Hoisting
repeated enums into shared components is what removes the duplicated
blocks from the published schema, and a reader that followed only the
property node would silently render an empty table once that happens.

Three things the shape change makes possible that the map could not, and
which are handled explicitly because each fails silently:

• Metadata can sit on the referring node as a $ref sibling rather than
  on the target, which is how pydantic publishes an annotation for a
  hoisted type. Both are consulted, nearest first.
• A positional array can fall out of alignment with enum in a way a
  keyed map never could. A length mismatch is treated as unusable rather
  than shifting every description onto the wrong value.
• The two shapes can coexist on one node mid-migration, so they are
  merged rather than treated as alternatives.

Ref resolution uses the jsonpointer the sibling readers already use:
hand-decoding each segment raises URIError on a pointer containing a
stray %, which would break the never-throws contract this reader
depends on to degrade instead of failing the build.

The dequeue reason table moves onto it here; the batch status table is
written against it from the start in a later commit. Rendered output is
unchanged.

Part of MRGFY-8330

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com

Depends-On: #12299

[kozlek]

This pull request is part of a Mergify stack:

#	Pull Request	Link
1	fix(docs): show accepted values for API parameters typed by a shared enum	#12299
2	refactor(docs): read documented enum values through one shared reader	#12293	👈
3	fix(docs): sanitize the HTML the schema-driven tables inject	#12304
4	feat(docs): switch to the namespaced documented-data-type marker	#12319
5	feat(docs): document the batch status data type	#12263

[mergify]

Merge Protections

🔴 2 of 7 protections blocking · waiting on 👀 reviews

	Protection	Waiting on
🔴	👀 Review Requirements	👀 reviews
🔴	🔎 Reviews	👀 reviews
🟢	⛓️ Depends-On Requirements	—
🟢	🤖 Continuous Integration	—
🟢	Enforce conventional commit	—
🟢	📕 PR description	—
🟢	🚦 Auto-queue	—

🔴 👀 Review Requirements

Waiting for

• #approved-reviews-by >= 2

This rule is failing.

• any of:
  • #approved-reviews-by >= 2
  • author = dependabot[bot]
  • all of:
    • author = mergify-ci-bot
    • -head ~= ^docs-agent/

🔴 🔎 Reviews

Waiting for

• #review-requested = 0

This rule is failing.

• #review-requested = 0
• #changes-requested-reviews-by = 0
• #review-threads-unresolved = 0

---

Show 5 satisfied protections

🟢 ⛓️ Depends-On Requirements

Requirement based on the presence of Depends-On in the body of the pull request

• depends-on=Mergifyio/docs#12299 [⛓️ fix(docs): show accepted values for API parameters typed by a shared enum #12299 [stack]]

🟢 🤖 Continuous Integration

• all of:
  • check-success = build
  • check-success = lint
  • check-success = test
  • any of:
    • check-success = test-broken-links
    • label = ignore-broken-links
  • any of:
    • check-success=Cloudflare Pages
    • -head-repo-full-name~=^Mergifyio/

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 📕 PR description

• body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

[kozlek]

Revision history

#	Type	Changes	Reason	Date
1	initial	b56a1a0		2026-08-03 19:22 UTC
2	rebase	b56a1a0 → 810fd13 (rebase only)		2026-08-03 19:22 UTC
3	content	810fd13 → 3cf3096		2026-08-04 07:58 UTC
4	content	3cf3096 → 3c3d836		2026-08-04 17:09 UTC
5	content	3c3d836 → f747840		2026-08-05 13:05 UTC
6	rebase	f747840 → 4b1ec1f (rebase only)		2026-08-05 13:52 UTC
7	rebase	4b1ec1f → b5e84ba (rebase only)		2026-08-05 14:00 UTC

[Copilot]

Pull request overview

This PR introduces a shared, schema-shape-tolerant reader for “choice sets” (enums + per-value documentation) to keep docs rendering stable across an engine-side schema migration from x-enum-descriptions to x-mergify-enum, including cases where enums are hoisted behind $ref.

Changes:

• Added readEnumChoices (and supporting $ref resolution/metadata collection) to handle enum, const, and anyOf/oneOf choice shapes across both metadata formats.
• Added Vitest coverage to pin expected behavior for migration edge cases (ref siblings, hoisted enums, misaligned positional metadata, etc.).
• Refactored QueueDequeueReasons to use the shared reader rather than bespoke enum/description extraction.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/util/enumChoices.ts	New shared enum-choice reader with $ref resolution and merged legacy/target metadata handling.
src/util/enumChoices.test.ts	New unit tests covering multiple schema shapes and migration failure modes.
src/components/Tables/QueueDequeueReasons.tsx	Switched dequeue reason table generation to readEnumChoices for migration-safe rendering.

---

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