feat(docs): accept the namespaced documented-data-type marker by kozlek · Pull Request #12301 · Mergifyio/docs

kozlek · 2026-08-04T08:50:20Z

The engine is renaming its documented-data-type flag from
x-has-data-type to x-mergify-has-data-type, matching the namespacing
already used for x-mergify-enum. An unprefixed x- key is a claim on a
name nobody owns, which is how x-enum-descriptions ended up meaning a
positional array of strings to openapi-generator and a map to us.

Read both spellings. Schema syncs land as direct pushes to main, so the
docs repo cannot assume the two sides move together: whichever order the
repos merge in, a synced schema can carry either key, and a reader that
knew only one would take the anchor gate offline without failing
anything. The fallback can go once no synced schema publishes the old
key.

Only isDataType reads the flag directly — the anchor collector, both
config tables and the build gate all go through it — so accepting both is
one predicate, not a sweep.

This lands before the schemas that carry the new key, so the gate never
sees a marker it cannot read.

Part of MRGFY-8330

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

Depends-On: #12304

kozlek · 2026-08-04T08:50:26Z

This pull request is part of a Mergify stack:

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

mergify · 2026-08-04T08:50:36Z

Merge Protections

🔴 3 of 7 protections blocking · waiting on 👀 reviews and ⛓️ dependency

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

🔴 ⛓️ Depends-On Requirements

Waiting for

depends-on=Mergifyio/docs#12293 [⛓️ refactor(docs): read documented enum values through one shared reader #12293 [stack]]
depends-on=Mergifyio/docs#12304 [⛓️ fix(docs): sanitize the HTML the schema-driven tables inject #12304 [stack]]

This rule is failing.

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

depends-on=Mergifyio/docs#12293 [⛓️ refactor(docs): read documented enum values through one shared reader #12293 [stack]]
depends-on=Mergifyio/docs#12304 [⛓️ fix(docs): sanitize the HTML the schema-driven tables inject #12304 [stack]]

🔴 👀 Review Requirements

Waiting for

#approved-reviews-by >= 2

This rule is failing.

🔴 🔎 Reviews

Waiting for

#review-requested = 0

This rule is failing.

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

Show 4 satisfied protections

🟢 🤖 Continuous Integration

🟢 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 · 2026-08-04T17:10:18Z

Revision history

#	Type	Changes	Date
1	initial	`f390aeb`	2026-08-04 17:09 UTC
2	rebase	`f390aeb → 40c537b` (rebase only)	2026-08-04 17:09 UTC
3	rebase	`40c537b → 979f038` (rebase only)	2026-08-05 13:05 UTC

Copilot

🟢 Ready to approve

The implementation is minimal, backward-compatible, and covered by targeted unit tests for both marker spellings.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Pull request overview

Updates the docs-site schema utilities to recognize the engine’s renamed “documented data type” marker (x-has-data-type → x-mergify-has-data-type) while remaining backward-compatible during the schema sync transition, so build-time anchor validation continues to work regardless of merge order between repos.

Changes:

Teach isDataType to accept both the new namespaced marker and the legacy marker.
Expand unit tests to cover both marker spellings and ensure non-boolean values are rejected.
Update collectDataTypeTitles test fixtures/documentation to reflect the namespaced key.

File summaries

File	Description
src/util/dataType.ts	Accepts both marker spellings via a small key list and checks them through `isDataType`.
src/util/dataType.test.ts	Adds coverage for namespaced vs legacy marker behavior and updates schema fixtures accordingly.

Review details

Files reviewed: 2/2 changed files
Comments generated: 0
Review effort level: Lite

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

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> Change-Id: Ie539de06bf3391eb4390333810cda6e8f131b1e6

`renderMarkdown` output goes straight into `dangerouslySetInnerHTML` in six tables, and it did not filter URL protocols: `remark-rehype` emits an `<a>` for any link target whatever its scheme, so a `javascript:` link in a synced description would have rendered as a live link. Raw HTML was never a way in — `remark-rehype` runs without `allowDangerousHtml`, so it is discarded before becoming a node — which makes URL filtering the whole of what `rehype-sanitize` adds here. It sits after `rehype-raw` so that if a caller ever does enable `allowDangerousHtml`, the embedded markup is parsed and then sanitized rather than passed through opaque. Every input today is first-party: descriptions generated by our own engine and delivered by our own sync bot. So this is defence in depth rather than a live exposure — but "the input is trustworthy" is a property of the six current callers, not of the function, and the output lands somewhere that makes the distinction expensive to get wrong later. The tests separate the two guarantees on purpose. Asserting all four cases together would have been misleading: three of them pass with the sanitizer removed, because they test the markdown pipeline discarding raw HTML rather than anything the sanitizer does. Only the URL-protocol cases fail if it goes. Output is unchanged across every description the two schemas publish. Part of MRGFY-8330 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Change-Id: Ice1642f855d6698b65a034e398affbce16f822a6

The engine is renaming its documented-data-type flag from `x-has-data-type` to `x-mergify-has-data-type`, matching the namespacing already used for `x-mergify-enum`. An unprefixed `x-` key is a claim on a name nobody owns, which is how `x-enum-descriptions` ended up meaning a positional array of strings to openapi-generator and a map to us. Read both spellings. Schema syncs land as direct pushes to main, so the docs repo cannot assume the two sides move together: whichever order the repos merge in, a synced schema can carry either key, and a reader that knew only one would take the anchor gate offline without failing anything. The fallback can go once no synced schema publishes the old key. Only `isDataType` reads the flag directly — the anchor collector, both config tables and the build gate all go through it — so accepting both is one predicate, not a sweep. This lands before the schemas that carry the new key, so the gate never sees a marker it cannot read. Part of MRGFY-8330 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Change-Id: I203218c96b6b12aa53cb7121722f0870a909598f

mergify Bot had a problem deploying to Mergify Merge Protections August 4, 2026 08:50 Failure

This was referenced Aug 4, 2026

feat(docs): document the batch status data type #12263

Open

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

Open

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

Open

kozlek mentioned this pull request Aug 4, 2026

test(docs): make the renderMarkdown security tests actually load-bearing #12300

Closed

mergify Bot requested a review from a team August 4, 2026 08:52

kozlek changed the base branch from devs/kozlek/devs/kozlek/batch-status-data-type/make-rendermarkdown-security-tests-actually-load--63b59daf to main August 4, 2026 17:09

kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/accept-namespaced-documented-data-type-marker--203218c9 branch from f390aeb to 40c537b Compare August 4, 2026 17:10

Copilot AI lite review requested due to automatic review settings August 4, 2026 17:10

kozlek changed the base branch from main to devs/kozlek/devs/kozlek/batch-status-data-type/sanitize-html-schema-driven-tables-inject--ce1642f8 August 4, 2026 17:10

kozlek mentioned this pull request Aug 4, 2026

fix(docs): sanitize the HTML the schema-driven tables inject #12304

Open

mergify Bot had a problem deploying to Mergify Merge Protections August 4, 2026 17:10 Failure

Copilot AI approved these changes Aug 4, 2026

View reviewed changes

kozlek and others added 3 commits August 5, 2026 15:04

kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/sanitize-html-schema-driven-tables-inject--ce1642f8 branch from 4455148 to 87b0bd3 Compare August 5, 2026 13:05

kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/accept-namespaced-documented-data-type-marker--203218c9 branch from 40c537b to 979f038 Compare August 5, 2026 13:05

mergify Bot had a problem deploying to Mergify Merge Protections August 5, 2026 13:05 Failure

kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/sanitize-html-schema-driven-tables-inject--ce1642f8 branch from 87b0bd3 to 08912d8 Compare August 5, 2026 13:52

kozlek closed this Aug 5, 2026

kozlek deleted the devs/kozlek/devs/kozlek/batch-status-data-type/accept-namespaced-documented-data-type-marker--203218c9 branch August 5, 2026 13:52

Navigation Menu

Uh oh!

feat(docs): accept the namespaced documented-data-type marker - #12301

kozlek commented Aug 4, 2026 •

edited

Loading

Uh oh!

kozlek commented Aug 4, 2026 •

edited

Loading

Uh oh!

mergify Bot commented Aug 4, 2026 •

edited

Loading

🟢 🤖 Continuous Integration

🟢 Enforce conventional commit

🟢 📕 PR description

🟢 🚦 Auto-queue

Uh oh!

kozlek commented Aug 4, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

kozlek commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kozlek commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mergify Bot commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Protections

🔴 ⛓️ Depends-On Requirements

🔴 👀 Review Requirements

🔴 🔎 Reviews

🟢 🤖 Continuous Integration

🟢 Enforce conventional commit

🟢 📕 PR description

🟢 🚦 Auto-queue

Uh oh!

kozlek commented Aug 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Revision history

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Ready to approve

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

kozlek commented Aug 4, 2026 •

edited

Loading

kozlek commented Aug 4, 2026 •

edited

Loading

mergify Bot commented Aug 4, 2026 •

edited

Loading

kozlek commented Aug 4, 2026 •

edited

Loading