feat(docs): document the batch status data type

integrations/validate-data-type-anchors.ts

@@ -1,9 +1,19 @@
 import type { AstroIntegration } from 'astro';
+import rawApiSchema from '../public/api-schemas.json';
 import rawConfigSchema from '../public/mergify-configuration-schema.json';
 import { missingDataTypeAnchors } from '../src/util/dataTypeAnchors';
 
+// Both synced schemas can carry the engine's `x-has-data-type` marker: the
+// configuration schema for types you write in `.mergify.yml`, the OpenAPI spec
+// for types the API only reports (a batch status, say). Both arrive by the same
+// bot sync, so both need the same gate.
+const SCHEMAS: { file: string; schema: unknown }[] = [
+  { file: 'public/mergify-configuration-schema.json', schema: rawConfigSchema },
+  { file: 'public/api-schemas.json', schema: rawApiSchema },
+];
+
 /**
- * Fail the build when the config schema flags a documented data type whose
+ * Fail the build when a synced schema flags a documented data type whose
  * derived anchor (slugified `title`) has no matching heading on the
  * data-types page. This is the enforcement point that actually guards the
  * drift path: schema syncs land as direct bot pushes to main (no PR, so no
@@ -16,14 +26,18 @@ export function validateDataTypeAnchors(): AstroIntegration {
     name: 'validate-data-type-anchors',
     hooks: {
       'astro:build:start': () => {
-        const missing = missingDataTypeAnchors(rawConfigSchema);
-        if (missing.length > 0) {
+        const problems = SCHEMAS.flatMap(({ file, schema }) => {
+          const missing = missingDataTypeAnchors(schema);
+          return missing.length > 0 ? [`${file}: ${missing.join(', ')}`] : [];
+        });
+
+        if (problems.length > 0) {
           throw new Error(
-            `Documented data type(s) in public/mergify-configuration-schema.json have no ` +
-              `matching heading anchor on src/content/docs/configuration/data-types.mdx: ` +
-              `${missing.join(', ')}. A marked node's slugified title must equal the anchor ` +
-              `of its section heading (add the missing section, or fix the title next to the ` +
-              `engine's DocsDataType annotation).`
+            `Documented data type(s) in a synced schema have no matching heading anchor on ` +
+              `src/content/docs/configuration/data-types.mdx — ${problems.join('; ')}. ` +
+              `A marked node's slugified title must equal the anchor of its section heading ` +
+              `(add the missing section, or fix the title next to the engine's DocsDataType ` +
+              `annotation).`
           );
         }
       },

package.json

@@ -102,6 +102,7 @@
     "rehype-autolink-headings": "^7.1.0",
     "rehype-format": "^5.0.1",
     "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
     "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-lint": "^10.0.1",