From 272484b8b2a340d901f263a99119c194bad35234 Mon Sep 17 00:00:00 2001 From: Aras Abbasi Date: Thu, 7 Mar 2024 19:00:11 +0100 Subject: [PATCH] doc: test for cli options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR-URL: https://github.com/nodejs/node/pull/51623 Reviewed-By: Matteo Collina Reviewed-By: Vinícius Lourenço Claro Cardoso --- doc/api/cli.md | 43 +++++++ doc/contributing/internal-api.md | 14 +++ doc/node.1 | 3 - src/node_options.cc | 2 +- test/parallel/test-cli-node-options-docs.js | 129 ++++++++++++++++++++ 5 files changed, 187 insertions(+), 4 deletions(-) create mode 100644 test/parallel/test-cli-node-options-docs.js diff --git a/doc/api/cli.md b/doc/api/cli.md index 0b8eb7b0cb2308..82cbd12d8c97e0 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -2832,11 +2832,15 @@ V8 options that are allowed are: + + `--perf-basic-prof-only-functions`, `--perf-basic-prof`, `--perf-prof-unwinding-info`, and `--perf-prof` are only available on Linux. `--enable-etw-stack-walking` is only available on Windows. + + ### `NODE_PATH=path[:…]` + +### `--abort-on-uncaught-exception` + +### `--disallow-code-generation-from-strings` + +### `--enable-etw-stack-walking` + +### `--harmony-shadow-realm` + +### `--huge-max-old-generation-size` + +### `--jitless` + +### `--interpreted-frames-native-stack` + +### `--prof` + +### `--perf-basic-prof` + +### `--perf-basic-prof-only-functions` + +### `--perf-prof` + +### `--perf-prof-unwinding-info` + ### `--max-old-space-size=SIZE` (in megabytes) Sets the max memory size of V8's old memory section. As memory @@ -3174,6 +3204,19 @@ for MiB in 16 32 64 128; do done ``` +### `--security-revert` + +### `--stack-trace-limit=limit` + +The maximum number of stack frames to collect in an error's stack trace. +Setting it to 0 disables stack trace collection. The default value is 10. + +```bash +node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 +``` + + + [#42511]: https://github.com/nodejs/node/issues/42511 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/ [CommonJS]: modules.md diff --git a/doc/contributing/internal-api.md b/doc/contributing/internal-api.md index 2631978e1af01c..e4120f44fc6a8c 100644 --- a/doc/contributing/internal-api.md +++ b/doc/contributing/internal-api.md @@ -8,6 +8,12 @@ rules. The core developers may remove these flags in any version of Node.js. ### Flags +#### `--debug-arraybuffer-allocations` + +#### `--expose-internals` + +Allows to require the `internal/*` modules. + #### `--inspect-brk-node[=[host:]port]` (.*)/s)[1]; +const v8OptionsText = cliText.match(/(.*)/s)[1]; + +const manPage = path.join(rootDir, 'doc', 'node.1'); +const manPageText = fs.readFileSync(manPage, { encoding: 'utf8' }); + +// Documented in /doc/api/deprecations.md +const deprecated = [ + '--debug', + '--debug-brk', +]; + + +const manPagesOptions = new Set(); + +for (const [, envVar] of manPageText.matchAll(/\.It Fl (-[a-zA-Z0-9._-]+)/g)) { + manPagesOptions.add(envVar); +} + +for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { + let hasTrueAsDefaultValue = false; + let isInNodeOption = false; + let isV8Option = false; + let isNoOp = false; + + if (config.includes('NoOp{}')) { + isNoOp = true; + } + + if (config.includes('kAllowedInEnvvar')) { + isInNodeOption = true; + } + if (config.includes('kDisallowedInEnvvar')) { + isInNodeOption = false; + } + + if (config.includes('V8Option{}')) { + isV8Option = true; + } + + if (/^\s*true\s*$/.test(config.split(',').pop())) { + hasTrueAsDefaultValue = true; + } + + if ( + envVar.startsWith('[') || + deprecated.includes(envVar) || + isNoOp + ) { + // assert(!manPagesOptions.has(envVar.slice(1)), `Option ${envVar} should not be documented`) + manPagesOptions.delete(envVar.slice(1)); + continue; + } + + // Internal API options are documented in /doc/contributing/internal-api.md + if (new RegExp(`####.*\`${envVar}[[=\\s\\b\`]`).test(internalApiText) === true) { + manPagesOptions.delete(envVar.slice(1)); + continue; + } + + // CLI options + if (!isV8Option && !hasTrueAsDefaultValue) { + if (new RegExp(`###.*\`${envVar}[[=\\s\\b\`]`).test(cliText) === false) { + assert(false, `Should have option ${envVar} documented`); + } else { + manPagesOptions.delete(envVar.slice(1)); + } + } + + if (!hasTrueAsDefaultValue && new RegExp(`###.*\`--no${envVar.slice(1)}[[=\\s\\b\`]`).test(cliText) === true) { + assert(false, `Should not have option --no${envVar.slice(1)} documented`); + } + + if (!isV8Option && hasTrueAsDefaultValue) { + if (new RegExp(`###.*\`--no${envVar.slice(1)}[[=\\s\\b\`]`).test(cliText) === false) { + assert(false, `Should have option --no${envVar.slice(1)} documented`); + } else { + manPagesOptions.delete(`-no${envVar.slice(1)}`); + } + } + + // NODE_OPTIONS + if (isInNodeOption && !hasTrueAsDefaultValue && new RegExp(`\`${envVar}\``).test(nodeOptionsText) === false) { + assert(false, `Should have option ${envVar} in NODE_OPTIONS documented`); + } + + if (isInNodeOption && hasTrueAsDefaultValue && new RegExp(`\`--no${envVar.slice(1)}`).test(cliText) === false) { + assert(false, `Should have option --no${envVar.slice(1)} in NODE_OPTIONS documented`); + } + + if (!hasTrueAsDefaultValue && new RegExp(`\`--no${envVar.slice(1)}`).test(cliText) === true) { + assert(false, `Should not have option --no${envVar.slice(1)} in NODE_OPTIONS documented`); + } + + // V8 options + if (isV8Option) { + if (new RegExp(`###.*\`${envVar}[[=\\s\\b\`]`).test(v8OptionsText) === false) { + assert(false, `Should have option ${envVar} in V8 options documented`); + } else { + manPagesOptions.delete(envVar.slice(1)); + } + } +} + +// add alias handling +manPagesOptions.delete('-trace-events-enabled'); + +assert.strictEqual(manPagesOptions.size, 0, `Man page options not documented: ${[...manPagesOptions]}`);