doc,test: test documentation consistency for NODE_OPTIONS

Add a test that checks that the documented allowed options for the
`NODE_OPTIONS` environment variable are consistent with the actually
allowed options.

PR-URL: nodejs#28179
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

doc/api/cli.md

@@ -969,6 +969,7 @@ In case an option value happens to contain a space (for example a path listed in
 ```
 
 Node.js options that are allowed are:
+<!-- node-options-node start -->
 - `--enable-fips`
 - `--es-module-specifier-resolution`
 - `--experimental-modules`
@@ -1028,15 +1029,18 @@ Node.js options that are allowed are:
 - `--use-openssl-ca`
 - `--v8-pool-size`
 - `--zero-fill-buffers`
+<!-- node-options-node end -->
 
 V8 options that are allowed are:
+<!-- node-options-v8 start -->
 - `--abort-on-uncaught-exception`
 - `--max-old-space-size`
 - `--perf-basic-prof-only-functions`
 - `--perf-basic-prof`
 - `--perf-prof-unwinding-info`
 - `--perf-prof`
 - `--stack-trace-limit`
+<!-- node-options-v8 end -->
 
 ### `NODE_PATH=path[:…]`
 <!-- YAML

test/parallel/test-process-env-allowed-flags-are-documented.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const common = require('../common');
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const rootDir = path.resolve(__dirname, '..', '..');
+const cliMd = path.join(rootDir, 'doc', 'api', 'cli.md');
+const cliText = fs.readFileSync(cliMd, { encoding: 'utf8' });
+
+const parseSection = (text, startMarker, endMarker) => {
+  const regExp = new RegExp(`${startMarker}\r?\n([^]*)\r?\n${endMarker}`);
+  const match = text.match(regExp);
+  assert(match,
+         `Unable to locate text between '${startMarker}' and '${endMarker}'.`);
+  return match[1].split(/\r?\n/);
+};
+
+const nodeOptionsLines = parseSection(cliText,
+                                      '<!-- node-options-node start -->',
+                                      '<!-- node-options-node end -->');
+const v8OptionsLines = parseSection(cliText,
+                                    '<!-- node-options-v8 start -->',
+                                    '<!-- node-options-v8 end -->');
+// Check the options are documented in alphabetical order.
+assert.deepStrictEqual(nodeOptionsLines, [...nodeOptionsLines].sort());
+assert.deepStrictEqual(v8OptionsLines, [...v8OptionsLines].sort());
+
+const documented = new Set();
+for (const line of [...nodeOptionsLines, ...v8OptionsLines]) {
+  for (const match of line.matchAll(/`(-[^`]+)`/g)) {
+    const option = match[1];
+    assert(!documented.has(option),
+           `Option '${option}' was documented more than once as an ` +
+           `allowed option for NODE_OPTIONS in ${cliMd}.`);
+    documented.add(option);
+  }
+}
+
+// Filter out options that are conditionally present.
+const conditionalOpts = [
+  { include: common.hasCrypto,
+    filter: (opt) => {
+      return ['--openssl-config', '--tls-cipher-list', '--use-bundled-ca',
+              '--use-openssl-ca' ].includes(opt);
+    } },
+  { include: common.hasFipsCrypto,
+    filter: (opt) => opt.includes('-fips') },
+  { include: common.hasIntl,
+    filter: (opt) => opt === '--icu-data-dir' },
+  { include: process.features.inspector,
+    filter: (opt) => opt.startsWith('--inspect') || opt === '--debug-port' },
+  { include: process.config.variables.node_report,
+    filter: (opt) => opt.includes('-report') },
+];
+documented.forEach((opt) => {
+  conditionalOpts.forEach(({ include, filter }) => {
+    if (!include && filter(opt)) {
+      documented.delete(opt);
+    }
+  });
+});
+
+const difference = (setA, setB) => {
+  return new Set([...setA].filter((x) => !setB.has(x)));
+};
+
+const overdocumented = difference(documented,
+                                  process.allowedNodeEnvironmentFlags);
+assert.strictEqual(overdocumented.size, 0,
+                   'The following options are documented as allowed in ' +
+                   `NODE_OPTIONS in ${cliMd}: ` +
+                   `${[...overdocumented].join(' ')} ` +
+                   'but are not in process.allowedNodeEnvironmentFlags');
+const undocumented = difference(process.allowedNodeEnvironmentFlags,
+                                documented);
+// Remove intentionally undocumented options.
+assert(undocumented.delete('--debug-arraybuffer-allocations'));
+assert(undocumented.delete('--experimental-worker'));
+assert.strictEqual(undocumented.size, 0,
+                   'The following options are not documented as allowed in ' +
+                   `NODE_OPTIONS in ${cliMd}: ${[...undocumented].join(' ')}`);