From 310d14832b13406bd53533e23899a211dd52dfcd Mon Sep 17 00:00:00 2001 From: Richard Lau Date: Tue, 11 Jun 2019 21:29:36 -0400 Subject: [PATCH 1/2] doc: add missing options allowed in NODE_OPTIONS Add missing options to the list of allowed options for the `NODE_OPTIONS` environment variable. Sort the list alphabetically. --- doc/api/cli.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 6aa66cba166039..07635690defd4c 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -969,14 +969,10 @@ In case an option value happens to contain a space (for example a path listed in ``` Node.js options that are allowed are: -- `--report-directory` -- `--report-filename` -- `--report-on-fatalerror` -- `--report-on-signal` -- `--report-signal` -- `--report-uncaught-exception` - `--enable-fips` +- `--es-module-specifier-resolution` - `--experimental-modules` +- `--experimental-policy` - `--experimental-repl-await` - `--experimental-report` - `--experimental-vm-modules` @@ -984,11 +980,13 @@ Node.js options that are allowed are: - `--force-fips` - `--frozen-intrinsics` - `--heapsnapshot-signal` +- `--http-parser` - `--icu-data-dir` -- `--inspect` +- `--input-type` - `--inspect-brk` -- `--inspect-port` +- `--inspect-port`, `--debug-port` - `--inspect-publish-uid` +- `--inspect` - `--loader` - `--max-http-header-size` - `--napi-modules` @@ -997,7 +995,16 @@ Node.js options that are allowed are: - `--no-warnings` - `--openssl-config` - `--pending-deprecation` +- `--preserve-symlinks-main` +- `--preserve-symlinks` +- `--prof-process` - `--redirect-warnings` +- `--report-directory` +- `--report-filename` +- `--report-on-fatalerror` +- `--report-on-signal` +- `--report-signal` +- `--report-uncaught-exception` - `--require`, `-r` - `--throw-deprecation` - `--title` @@ -1025,10 +1032,10 @@ Node.js options that are allowed are: V8 options that are allowed are: - `--abort-on-uncaught-exception` - `--max-old-space-size` -- `--perf-basic-prof` - `--perf-basic-prof-only-functions` -- `--perf-prof` +- `--perf-basic-prof` - `--perf-prof-unwinding-info` +- `--perf-prof` - `--stack-trace-limit` ### `NODE_PATH=path[:…]` From 6bfc84030b2a95035f6a27685ec37bfcfddbb9fa Mon Sep 17 00:00:00 2001 From: Richard Lau Date: Tue, 11 Jun 2019 14:17:15 -0400 Subject: [PATCH 2/2] 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. --- doc/api/cli.md | 4 + ...rocess-env-allowed-flags-are-documented.js | 84 +++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 test/parallel/test-process-env-allowed-flags-are-documented.js diff --git a/doc/api/cli.md b/doc/api/cli.md index 07635690defd4c..4bf6a9473a0350 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: + - `--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` + V8 options that are allowed are: + - `--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_PATH=path[:…]` ', + ''); +const v8OptionsLines = parseSection(cliText, + '', + ''); +// 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(' ')}`);