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: #28179 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>

Author: richardlau

doc/api/cli.md

@@ -980,6 +980,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`
@@ -1040,15 +1041,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';
+
+constcommon=require('../common');
+
+constassert=require('assert');
+constfs=require('fs');
+constpath=require('path');
+
+constrootDir=path.resolve(__dirname,'..','..');
+constcliMd=path.join(rootDir,'doc','api','cli.md');
+constcliText=fs.readFileSync(cliMd,{encoding: 'utf8'});
+
+constparseSection=(text,startMarker,endMarker)=>{
+constregExp=newRegExp(`${startMarker}\r?\n([^]*)\r?\n${endMarker}`);
+constmatch=text.match(regExp);
+assert(match,
+`Unable to locate text between '${startMarker}' and '${endMarker}'.`);
+returnmatch[1].split(/\r?\n/);
+};
+
+constnodeOptionsLines=parseSection(cliText,
+'<!-- node-options-node start -->',
+'<!-- node-options-node end -->');
+constv8OptionsLines=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());
+
+constdocumented=newSet();
+for(constlineof[...nodeOptionsLines, ...v8OptionsLines]){
+for(constmatchofline.matchAll(/`(-[^`]+)`/g)){
+constoption=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.
+constconditionalOpts=[
+{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);
+}
+});
+});
+
+constdifference=(setA,setB)=>{
+returnnewSet([...setA].filter((x)=>!setB.has(x)));
+};
+
+constoverdocumented=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');
+constundocumented=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(' ')}`);