build,tools: check freshness of doc addons

Add a `--check` flag to `tools/doc/addon-verify.js` and use that in the
`make test` target to determine if the generated files in `test/addons`
are fresh or stale.

PR-URL: #17407
Reviewed-By: Richard Lau <riclau@uk.ibm.com>

Makefile

@@ -225,7 +225,7 @@ v8:
 
 .PHONY: test
 # This does not run tests of third-party libraries inside deps.
-test: all build-addons	## Runs default tests, linters, and builds docs.
+test: all check-doc-addons build-addons	## Runs default tests, linters, and builds docs.
 	$(MAKE) -s doc-only
 	$(MAKE) -s lint
 	$(MAKE) -s cctest
@@ -234,6 +234,10 @@ test: all build-addons	## Runs default tests, linters, and builds docs.
 		$(CI_NATIVE_SUITES) \
 		$(CI_DOC)
 
+.PHONY: check-doc-addons
+check-doc-addons: $(NODE)
+	$(NODE) tools/doc/addon-verify.js --check
+
 .PHONY: test-only
 test-only: all build-addons	## For a quick test, does not run linter or build docs.
 	$(MAKE) cctest

tools/doc/addon-verify.js

@@ -10,6 +10,9 @@ const rootDir = path.resolve(__dirname, '..', '..');
 const doc = path.resolve(rootDir, 'doc', 'api', 'addons.md');
 const verifyDir = path.resolve(rootDir, 'test', 'addons');
 
+const changed = [];
+const checkOnly = process.argv.includes('--check');
+
 let id = 0;
 let currentHeader;
 
@@ -76,12 +79,6 @@ for (const header in addons) {
     })
   });
 
-  try {
-    fs.mkdirSync(dir);
-  } catch (e) {
-    strictEqual(e.code, 'EEXIST');
-  }
-
   for (const file of files) {
     let content;
     try {
@@ -91,13 +88,29 @@ for (const header in addons) {
     }
 
     // Only update when file content has changed to prevent unneeded rebuilds.
-    if (content !== file.content) {
-      fs.writeFileSync(file.path, file.content);
-      console.log('wrote', file.path);
+    if (content === file.content) continue;
+    changed.push(file);
+
+    if (checkOnly) continue;
+
+    try {
+      fs.mkdirSync(dir);
+    } catch (e) {
+      strictEqual(e.code, 'EEXIST');
     }
+
+    fs.writeFileSync(file.path, file.content);
+    console.log('wrote', file.path);
   }
 }
 
+if (checkOnly && changed.length > 0) {
+  console.error('The following files are out of date:');
+  for (const { path } of changed) console.error('  ', path);
+  console.error('Run `node tools/doc/addon-verify.js` to update.');
+  process.exit(1);
+}
+
 function boilerplate(name, content) {
   return `'use strict';
 const common = require('../../common');