diff options
| -rw-r--r-- | doc/api/cli.md | 4 | ||||
| -rw-r--r-- | test/parallel/test-process-env-allowed-flags-are-documented.js | 84 |
2 files changed, 88 insertions, 0 deletions
diff --git a/doc/api/cli.md b/doc/api/cli.md index 07635690de..4bf6a9473a 100644 --- a/doc/api/cli.md +++ b/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,8 +1029,10 @@ 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` @@ -1037,6 +1040,7 @@ V8 options that are allowed are: - `--perf-prof-unwinding-info` - `--perf-prof` - `--stack-trace-limit` +<!-- node-options-v8 end --> ### `NODE_PATH=path[:…]` <!-- YAML diff --git a/test/parallel/test-process-env-allowed-flags-are-documented.js b/test/parallel/test-process-env-allowed-flags-are-documented.js new file mode 100644 index 0000000000..bb203d94d3 --- /dev/null +++ b/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(' ')}`); |