test: check stability block position in API markdown

Author: Renegade334

doc/api/buffer.md

@@ -3491,13 +3491,13 @@ changes:
                  calculations with them.
 -->
 
+> Stability: 0 - Deprecated: Use [`buf.subarray`][] instead.
+
 * `start` {integer} Where the new `Buffer` will start. **Default:** `0`.
 * `end` {integer} Where the new `Buffer` will end (not inclusive).
   **Default:** [`buf.length`][].
 * Returns: {Buffer}
 
-> Stability: 0 - Deprecated: Use [`buf.subarray`][] instead.
-
 Returns a new `Buffer` that references the same memory as the original, but
 offset and cropped by the `start` and `end` indexes.
 

test/doctool/test-stability-block-position.mjs

@@ -0,0 +1,48 @@
+import '../common/index.mjs';
+
+import fs from 'fs';
+import assert from 'assert';
+
+import {
+  remarkParse,
+  unified,
+} from '../../tools/doc/deps.mjs';
+
+const ignore = ['deprecations.md', 'documentation.md'];
+
+const docURL = new URL('../../doc/api/', import.meta.url);
+const docList = fs.readdirSync(docURL).filter((filename) => !ignore.includes(filename));
+
+for (const file of docList) {
+  const fileURL = new URL(file, docURL);
+  const tree = unified()
+    .use(remarkParse)
+    .parse(fs.readFileSync(fileURL));
+
+  for (let i = 0; i < tree.children.length; i++) {
+    const { [i]: node, [i - 1]: previousNode } = tree.children;
+    if (node.type !== 'blockquote' || !node.children.length) continue;
+
+    const paragraph = node.children[0];
+    if (paragraph.type !== 'paragraph' || !paragraph.children.length) continue;
+
+    const text = paragraph.children[0];
+    if (text.type !== 'text' || !text.value.match(/^Stability: \d/)) continue;
+
+    // Check that previous node type is one of:
+    // * 'heading'
+    // * 'html' (YAML block)
+    // * 'paragraph' with a leading 'strong' node (pseudo-heading, eg. assert.equal)
+    try {
+      assert(previousNode.type === 'heading' || previousNode.type === 'html' ||
+                 (previousNode.type === 'paragraph' && previousNode.children[0]?.type === 'strong'),
+             'Stability block must be the first content element under heading');
+    } catch (error) {
+      const { line, column } = node.position.start;
+      error.stack = error.stack.split('\n')
+                      .toSpliced(1, 0, `    at ${fileURL}:${line}:${column}`)
+                      .join('\n');
+      throw error;
+    }
+  }
+}