build: make test-addons dependency-free

`make test-addons` used to depend on a markdown parser and then
doc-kit to extract C++ addon examples from addons.md by guessing
the file contents based on headings. This is hacky and brittle.
The introduction of doc-kit also means tests intended for verifying
the binary like `make test-only` now need to support doc-building
toolchains e.g. minifier, highlighter, and indirect dependencies
that rely on prebuilt-addon/wasm, which defeats the purpose
and makes it harder to run for experimental platforms.

This patch adds explicit
`<!-- addon-verify-file dir/filename -->` markers in addons.md to
locate extractable code blocks, avoiding fragile heuristics based on
heading text or code block order and eliminating the dependency
with simpler parsing.

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: joyeecheung

Makefile

@@ -388,17 +388,15 @@ DOC_KIT ?= tools/doc/node_modules/@nodejs/doc-kit/bin/cli.mjs
 
 node_use_openssl_and_icu = $(call available-node,"-p" \
 			 "process.versions.openssl != undefined && process.versions.icu != undefined")
-test/addons/.docbuildstamp: $(DOCBUILDSTAMP_PREREQS) tools/doc/node_modules
+test/addons/.docbuildstamp: $(DOCBUILDSTAMP_PREREQS) tools/doc/addon-verify.mjs
 	@if [ "$(shell $(node_use_openssl_and_icu))" != "true" ]; then \
 		echo "Skipping .docbuildstamp (no crypto and/or no ICU)"; \
 	else \
 		$(RM) -r test/addons/??_*/; \
 		$(call available-node, \
-			$(DOC_KIT) generate \
-			-t addon-verify \
-			-i doc/api/addons.md \
-			-o test/addons/ \
-			--type-map doc/type-map.json \
+			tools/doc/addon-verify.mjs \
+			--input doc/api/addons.md \
+			--output test/addons/ \
 		) \
 		[ $$? -eq 0 ] && touch $@; \
 	fi

doc/api/addons.md

@@ -280,6 +280,8 @@ such as any libuv handles registered by the addon.
 
 The following `addon.cc` uses `AddEnvironmentCleanupHook`:
 
+<!-- addon-verify-file worker_support/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -328,6 +330,8 @@ NODE_MODULE_INIT(/* exports, module, context */) {
 
 Test in JavaScript by running:
 
+<!-- addon-verify-file worker_support/test.js -->
+
 ```js
 // test.js
 require('./build/Release/addon');
@@ -526,6 +530,8 @@ code.
 The following example illustrates how to read function arguments passed from
 JavaScript and how to return a result:
 
+<!-- addon-verify-file function_arguments/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -585,6 +591,8 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
 
 Once compiled, the example addon can be required and used from within Node.js:
 
+<!-- addon-verify-file function_arguments/test.js -->
+
 ```js
 // test.js
 const addon = require('./build/Release/addon');
@@ -598,6 +606,8 @@ It is common practice within addons to pass JavaScript functions to a C++
 function and execute them from there. The following example illustrates how
 to invoke such callbacks:
 
+<!-- addon-verify-file callbacks/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -641,6 +651,8 @@ property of `exports`.
 
 To test it, run the following JavaScript:
 
+<!-- addon-verify-file callbacks/test.js -->
+
 ```js
 // test.js
 const addon = require('./build/Release/addon');
@@ -659,6 +671,8 @@ Addons can create and return new objects from within a C++ function as
 illustrated in the following example. An object is created and returned with a
 property `msg` that echoes the string passed to `createObject()`:
 
+<!-- addon-verify-file object_factory/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -698,6 +712,8 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
 
 To test it in JavaScript:
 
+<!-- addon-verify-file object_factory/test.js -->
+
 ```js
 // test.js
 const addon = require('./build/Release/addon');
@@ -713,6 +729,8 @@ console.log(obj1.msg, obj2.msg);
 Another common scenario is creating JavaScript functions that wrap C++
 functions and returning those back to JavaScript:
 
+<!-- addon-verify-file function_factory/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -760,6 +778,8 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, Init)
 
 To test:
 
+<!-- addon-verify-file function_factory/test.js -->
+
 ```js
 // test.js
 const addon = require('./build/Release/addon');
@@ -774,6 +794,8 @@ console.log(fn());
 It is also possible to wrap C++ objects/classes in a way that allows new
 instances to be created using the JavaScript `new` operator:
 
+<!-- addon-verify-file wrapping_c_objects/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -795,6 +817,8 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)
 
 Then, in `myobject.h`, the wrapper class inherits from `node::ObjectWrap`:
 
+<!-- addon-verify-file wrapping_c_objects/myobject.h -->
+
 ```cpp
 // myobject.h
 #ifndef MYOBJECT_H
@@ -828,6 +852,8 @@ In `myobject.cc`, implement the various methods that are to be exposed.
 In the following code, the method `plusOne()` is exposed by adding it to the
 constructor's prototype:
 
+<!-- addon-verify-file wrapping_c_objects/myobject.cc -->
+
 ```cpp
 // myobject.cc
 #include "myobject.h"
@@ -931,6 +957,8 @@ To build this example, the `myobject.cc` file must be added to the
 
 Test it with:
 
+<!-- addon-verify-file wrapping_c_objects/test.js -->
+
 ```js
 // test.js
 const addon = require('./build/Release/addon');
@@ -968,6 +996,8 @@ const obj = addon.createObject();
 
 First, the `createObject()` method is implemented in `addon.cc`:
 
+<!-- addon-verify-file factory_of_wrapped_objects/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -1001,6 +1031,8 @@ In `myobject.h`, the static method `NewInstance()` is added to handle
 instantiating the object. This method takes the place of using `new` in
 JavaScript:
 
+<!-- addon-verify-file factory_of_wrapped_objects/myobject.h -->
+
 ```cpp
 // myobject.h
 #ifndef MYOBJECT_H
@@ -1033,6 +1065,8 @@ class MyObject : public node::ObjectWrap {
 
 The implementation in `myobject.cc` is similar to the previous example:
 
+<!-- addon-verify-file factory_of_wrapped_objects/myobject.cc -->
+
 ```cpp
 // myobject.cc
 #include <node.h>
@@ -1147,6 +1181,8 @@ Once again, to build this example, the `myobject.cc` file must be added to the
 
 Test it with:
 
+<!-- addon-verify-file factory_of_wrapped_objects/test.js -->
+
 ```js
 // test.js
 const createObject = require('./build/Release/addon');
@@ -1175,6 +1211,8 @@ wrapped objects around by unwrapping them with the Node.js helper function
 `node::ObjectWrap::Unwrap`. The following examples shows a function `add()`
 that can take two `MyObject` objects as input arguments:
 
+<!-- addon-verify-file passing_wrapped_objects_around/addon.cc -->
+
 ```cpp
 // addon.cc
 #include <node.h>
@@ -1224,6 +1262,8 @@ NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)
 In `myobject.h`, a new public method is added to allow access to private values
 after unwrapping the object.
 
+<!-- addon-verify-file passing_wrapped_objects_around/myobject.h -->
+
 ```cpp
 // myobject.h
 #ifndef MYOBJECT_H
@@ -1256,6 +1296,8 @@ class MyObject : public node::ObjectWrap {
 
 The implementation of `myobject.cc` remains similar to the previous version:
 
+<!-- addon-verify-file passing_wrapped_objects_around/myobject.cc -->
+
 ```cpp
 // myobject.cc
 #include <node.h>
@@ -1340,6 +1382,8 @@ void MyObject::NewInstance(const FunctionCallbackInfo<Value>& args) {
 
 Test it with:
 
+<!-- addon-verify-file passing_wrapped_objects_around/test.js -->
+
 ```js
 // test.js
 const addon = require('./build/Release/addon');

tools/doc/addon-verify.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+// Extracts C++ addon examples from doc/api/addons.md into numbered test
+// directories under test/addons/.
+//
+// Each code block to extract is preceded by a marker in the markdown:
+//
+//   <!-- addon-verify-file worker_support/addon.cc -->
+//   ```cpp
+//   #include <node.h>
+//   ...
+//   ```
+//
+// This produces test/addons/01_worker_support/addon.cc.
+// Sections are numbered in order of first appearance.
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+const { values } = parseArgs({
+  options: {
+    input: { type: 'string' },
+    output: { type: 'string' },
+  },
+});
+
+if (!values.input || !values.output) {
+  console.error('Usage: addon-verify.mjs --input <file> --output <dir>');
+  process.exit(1);
+}
+
+const src = await open(values.input, 'r');
+
+const MARKER_RE = /^<!--\s*addon-verify-file\s+(\S+?)\/(\S+)\s*-->$/;
+
+const entries = [];
+let nextBlockIsAddonVerifyFile = false;
+let expectedClosingFenceMarker;
+for await (const line of src.readLines()) {
+  if (expectedClosingFenceMarker) {
+    // We're inside a Addon snippet
+    if (line === expectedClosingFenceMarker) {
+      // End of the snippet
+      expectedClosingFenceMarker = null;
+      continue;
+    }
+
+    entries.at(-1).content += `${line}\n`;
+  }
+  if (nextBlockIsAddonVerifyFile) {
+    if (line) {
+      expectedClosingFenceMarker = line.replace(/\w/g, '');
+      nextBlockIsAddonVerifyFile = false;
+    }
+    continue;
+  }
+  const match = MARKER_RE.exec(line);
+  if (match) {
+    nextBlockIsAddonVerifyFile = true;
+    const [, dir, name] = match;
+    entries.push({ dir, name, content: '' });
+  }
+}
+
+// Collect files grouped by section directory name.
+const sections = Map.groupBy(entries, (e) => e.dir);
+
+let idx = 0;
+for (const [name, files] of sections) {
+  const dirName = `${String(++idx).padStart(2, '0')}_${name}`;
+  const dir = join(values.output, dirName);
+  mkdirSync(dir, { recursive: true });
+
+  for (const file of files) {
+    let content = file.content;
+    if (file.name === 'test.js') {
+      content =
+        "'use strict';\n" +
+        "const common = require('../../common');\n" +
+        content.replace(
+          "'./build/Release/addon'",
+          // eslint-disable-next-line no-template-curly-in-string
+          '`./build/${common.buildType}/addon`',
+        );
+    }
+    writeFileSync(join(dir, file.name), content);
+  }
+
+  // Generate binding.gyp
+  const names = files.map((f) => f.name);
+  writeFileSync(join(dir, 'binding.gyp'), JSON.stringify({
+    targets: [{
+      target_name: 'addon',
+      sources: names,
+      includes: ['../common.gypi'],
+    }],
+  }));
+
+  console.log(`Generated ${dirName} with files: ${names.join(', ')}`);
+}

vcbuild.bat

@@ -670,7 +670,7 @@ for /d %%F in (test\addons\??_*) do (
   rd /s /q %%F
 )
 :: generate
-%doc_kit_exe% generate -t addon-verify -i "file://%~dp0doc\api\addons.md" -o "file://%~dp0test\addons" --type-map "file://%~dp0doc\type-map.json"
+"%node_exe%" tools\doc\addon-verify.mjs --input "%~dp0doc\api\addons.md" --output "%~dp0test\addons"
 if %errorlevel% neq 0 exit /b %errorlevel%
 :: building addons
 setlocal