fix(docs): show accepted values for API parameters typed by a shared enum

[kozlek]

Deduplicating repeated enums in the OpenAPI spec hoists them into shared
components, so a query parameter's schema becomes a $ref instead of an
inline enum. getTypeLabel returned the component name for any $ref,
which is right for an object — the schema tree below expands it — but
wrong for an enum: parameters are rendered from that label alone, with no
tree underneath and no enum among their constraints.

Fifteen public parameters were affected. /api/activity-log's
event_type listed all 44 accepted values and would have shown
EventType[]; source on the quarantines endpoint would have shown
QuarantineSource instead of "manual" | "auto". The components
themselves are not rendered anywhere on the site, so the values would
have been published nowhere at all.

Resolve the reference when it targets an enum and keep the name
otherwise.

Part of MRGFY-8330

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

[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

🟢 All 6 merge protections satisfied — ready to merge.

Show 6 satisfied protections

🟢 🤖 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/

🟢 👀 Review Requirements

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

🟢 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)(?:\(.+\))?!?:

🟢 🔎 Reviews

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

🟢 📕 PR description

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

🟢 🚦 Auto-queue

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

[mergify]

A predecessor in this stack was just merged, but I couldn't auto-rebase this PR: there's a conflict that needs manual resolution.

Conflict in: src/util/enumChoices.test.ts (replayed onto c73d0756).

Resolve with mergify stack sync && mergify stack push.

[kozlek]

Revision history

#	Type	Changes	Reason	Date
1	initial	80eb05a		2026-08-04 17:09 UTC
2	rebase	80eb05a → 85e5029 (rebase only)		2026-08-04 17:09 UTC
3	content	4e7d3df → 7b64b97		2026-08-05 13:05 UTC
4	rebase	7b64b97 → c3af39d (rebase only)		2026-08-05 13:52 UTC
5	rebase	c3af39d → 2be5cc3 (rebase only)		2026-08-05 14:00 UTC

[Copilot]

Pull request overview

Fixes docs rendering regressions caused by OpenAPI enum deduplication (inline enum → $ref to shared components) by correctly resolving referenced enums when rendering API parameter types, and by centralizing enum-choice extraction/metadata handling across both the OpenAPI spec and the configuration schema.

Changes:

• Add a resilient readEnumChoices() / $ref resolver to read enum values + per-value docs across multiple engine-published shapes.
• Update API reference type labeling to expand $ref’d enums (so accepted values remain visible for parameters).
• Document “Batch Status” as a data type and extend the build-time anchor gate to validate both synced schemas (config + OpenAPI); harden markdown-to-HTML rendering with sanitization.

Reviewed changes

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

Show a summary per file

File	Description
src/util/enumChoices.ts	Adds enum choice reader that resolves $ref, flattens unions, and merges legacy/new per-value documentation shapes.
src/util/enumChoices.test.ts	Pins expected behavior across synthetic cases and the real synced schemas to prevent silent regressions.
src/util/dataType.ts	Accepts both x-mergify-has-data-type and legacy x-has-data-type markers during migration.
src/util/dataType.test.ts	Extends tests for both marker spellings and validates anchors against both synced schemas.
src/content/docs/merge-queue/monitoring.mdx	Cross-references the new Batch Status data type from monitoring docs.
src/content/docs/merge-queue/batches.mdx	Cross-references the new Batch Status data type from batch failure resolution docs.
src/content/docs/configuration/data-types.mdx	Adds “Batch Status” section and renders its codes table from the OpenAPI spec.
src/components/Tables/utils.ts	Sanitizes rendered markdown before injecting into DOM via dangerouslySetInnerHTML.
src/components/Tables/utils.test.ts	Adds security-focused tests for protocol filtering and raw HTML handling.
src/components/Tables/QueueDequeueReasons.tsx	Switches to readEnumChoices() for values + documentation rather than custom enum-shape parsing.
src/components/Tables/BatchStatusCodes.tsx	New table component that renders batch status codes/descriptions from the OpenAPI schema.
src/components/ApiReference/openapi.ts	Resolves $ref’d enums for parameter type labels instead of showing the component name.
public/mergify-configuration-schema.json	Synced schema update: emits x-mergify-enum positional metadata for dequeue reasons and reshapes enum values.
public/api-schemas.json	Synced spec update: hoists repeated enums into shared components and adds Batch Status metadata.
package.json	Adds rehype-sanitize dependency.
pnpm-lock.yaml	Locks rehype-sanitize and transitive deps.
integrations/validate-data-type-anchors.ts	Extends anchor validation gate to run against both synced schemas.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

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

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-08-05 16:29 UTC · Rule: default · triggered by merge protections
• ✅ Checks passed · on draft merge queue: checking main (1bed144) and #12299 together #12322
• ✅ Merged — 2026-08-06 07:04 UTC · at 2be5cc3dfea506970dfe9723fa43cc95bbc6bec9 · squash

This pull request spent 14 hours 35 minutes 17 seconds in the queue, including 2 minutes 16 seconds running CI.

Required conditions to merge

• github-review-approved [🛡 GitHub repository ruleset rule Require pull request for default branch]
  • fix(docs): show accepted values for API parameters typed by a shared enum #12299
• schedule=Mon-Fri 09:00-17:30[Europe/Paris]
• all of [🛡 Merge Protections rule Enforce conventional commit]:
  • title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:
    • fix(docs): show accepted values for API parameters typed by a shared enum #12299
• all of [🛡 Merge Protections rule 👀 Review Requirements]:
  • any of:
    • #approved-reviews-by >= 2
      • fix(docs): show accepted values for API parameters typed by a shared enum #12299
    • author = dependabot[bot]
      • fix(docs): show accepted values for API parameters typed by a shared enum #12299
    • all of:
      • author = mergify-ci-bot
        • fix(docs): show accepted values for API parameters typed by a shared enum #12299
      • -head ~= ^docs-agent/
        • fix(docs): show accepted values for API parameters typed by a shared enum #12299
• all of [🛡 Merge Protections rule 📕 PR description]:
  • body ~= (?ms:.{48,})
    • fix(docs): show accepted values for API parameters typed by a shared enum #12299
• all of [🛡 Merge Protections rule 🔎 Reviews]:
  • #changes-requested-reviews-by = 0
    • fix(docs): show accepted values for API parameters typed by a shared enum #12299
  • #review-requested = 0
    • fix(docs): show accepted values for API parameters typed by a shared enum #12299
  • #review-threads-unresolved = 0
    • fix(docs): show accepted values for API parameters typed by a shared enum #12299
• all of [🛡 Merge Protections rule 🤖 Continuous Integration]:
  • all of:
    • check-success = build
    • check-success = lint
    • check-success = test
    • any of:
      • check-success = test-broken-links
      • label = ignore-broken-links
        • fix(docs): show accepted values for API parameters typed by a shared enum #12299
    • any of:
      • check-success=Cloudflare Pages
      • -head-repo-full-name~=^Mergifyio/
        • fix(docs): show accepted values for API parameters typed by a shared enum #12299