From e15c5dab79c49351ce3705ce8b10881ef5e1f8f1 Mon Sep 17 00:00:00 2001 From: Antoine du Hamel Date: Wed, 27 Nov 2024 16:26:34 +0100 Subject: [PATCH] test: ensure `cli.md` is in alphabetical order Co-authored-by: RedYetiDev PR-URL: https://github.com/nodejs/node/pull/56025 Reviewed-By: Luigi Pinca --- doc/api/cli.md | 269 ++++++++++---------- test/parallel/test-cli-node-options-docs.js | 15 ++ 2 files changed, 144 insertions(+), 140 deletions(-) diff --git a/doc/api/cli.md b/doc/api/cli.md index 8126e662725630..552d00ef07a404 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -549,6 +549,18 @@ Affects the default output directory of: * [`--heap-prof-dir`][] * [`--redirect-warnings`][] +### `--disable-proto=mode` + + + +Disable the `Object.prototype.__proto__` property. If `mode` is `delete`, the +property is removed entirely. If `mode` is `throw`, accesses to the +property throw an exception with the code `ERR_PROTO_ACCESS`. + ### `--disable-warning=code-or-type` > Stability: 1.1 - Active development @@ -641,18 +653,6 @@ users can at least run WebAssembly (with less optimal performance) when the virtual memory address space available to their Node.js process is lower than what the V8 WebAssembly memory cage needs. -### `--disable-proto=mode` - - - -Disable the `Object.prototype.__proto__` property. If `mode` is `delete`, the -property is removed entirely. If `mode` is `throw`, accesses to the -property throw an exception with the code `ERR_PROTO_ACCESS`. - ### `--disallow-code-generation-from-strings` - -> Stability: 1 - Experimental. This flag is inherited from V8 and is subject to -> change upstream. - -This flag will expose the gc extension from V8. - -```js -if (globalThis.gc) { - globalThis.gc(); -} -``` - ### `--dns-result-order=order` + +Behavior is the same as [`--env-file`][], but an error is not thrown if the file +does not exist. + ### `--env-file=config` > Stability: 1.1 - Active development @@ -850,15 +842,6 @@ export USERNAME="nodejs" # will result in `nodejs` as the value. If you want to load environment variables from a file that may not exist, you can use the [`--env-file-if-exists`][] flag instead. -### `--env-file-if-exists=config` - - - -Behavior is the same as [`--env-file`][], but an error is not thrown if the file -does not exist. - ### `-e`, `--eval "script"` - -> Stability: 1.0 - Early development - -Enables the transformation of TypeScript-only syntax into JavaScript code. -Implies `--experimental-strip-types` and `--enable-source-maps`. - ### `--experimental-eventsource` + +If the ES module being `require()`'d contains top-level `await`, this flag +allows Node.js to evaluate the module, try to locate the +top-level awaits, and print their location to help users find them. + ### `--experimental-require-module` + +> Stability: 1.0 - Early development + +Enables the transformation of TypeScript-only syntax into JavaScript code. +Implies `--experimental-strip-types` and `--enable-source-maps`. + ### `--experimental-vm-modules` + +> Stability: 1 - Experimental. This flag is inherited from V8 and is subject to +> change upstream. + +This flag will expose the gc extension from V8. + +```js +if (globalThis.gc) { + globalThis.gc(); +} +``` + ### `--force-context-aware` - -Activate inspector on `host:port`. Default is `127.0.0.1:9229`. If port `0` is -specified, a random available port will be used. - -V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug -and profile Node.js instances. The tools attach to Node.js instances via a -tcp port and communicate using the [Chrome DevTools Protocol][]. -See [V8 Inspector integration for Node.js][] for further explanation on Node.js debugger. - - - - - -#### Warning: binding inspector to a public IP:port combination is insecure - -Binding the inspector to a public IP (including `0.0.0.0`) with an open port is -insecure, as it allows external hosts to connect to the inspector and perform -a [remote code execution][] attack. - -If specifying a host, make sure that either: - -* The host is not accessible from public networks. -* A firewall disallows unwanted connections on the port. - -**More specifically, `--inspect=0.0.0.0` is insecure if the port (`9229` by -default) is not firewall-protected.** - -See the [debugging security implications][] section for more information. - ### `--inspect-brk[=[host:]port]` + +Activate inspector on `host:port`. Default is `127.0.0.1:9229`. If port `0` is +specified, a random available port will be used. + +V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug +and profile Node.js instances. The tools attach to Node.js instances via a +tcp port and communicate using the [Chrome DevTools Protocol][]. +See [V8 Inspector integration for Node.js][] for further explanation on Node.js debugger. + + + + + +#### Warning: binding inspector to a public IP:port combination is insecure + +Binding the inspector to a public IP (including `0.0.0.0`) with an open port is +insecure, as it allows external hosts to connect to the inspector and perform +a [remote code execution][] attack. + +If specifying a host, make sure that either: + +* The host is not accessible from public networks. +* A firewall disallows unwanted connections on the port. + +**More specifically, `--inspect=0.0.0.0` is insecure if the port (`9229` by +default) is not firewall-protected.** + +See the [debugging security implications][] section for more information. + ### `-i`, `--interactive` - -Disable exposition of [Fetch API][] on the global scope. - ### `--no-experimental-detect-module` + +Disable exposition of [Fetch API][] on the global scope. + ### `--no-experimental-global-customevent` - -If the ES module being `require()`'d contains top-level `await`, this flag -allows Node.js to evaluate the module, try to locate the -top-level awaits, and print their location to help users find them. - ### `--prof` Exclude `header.networkInterfaces` from the diagnostic report. By default @@ -2073,15 +2071,6 @@ Enables report to be generated when the process exits due to an uncaught exception. Useful when inspecting the JavaScript stack in conjunction with native stack and other runtime environment data. -### `--report-exclude-network` - - - -Exclude `header.networkInterfaces` from the diagnostic report. By default -this is not set and the network interfaces are included. - ### `-r`, `--require module` + +When using `--secure-heap`, the `--secure-heap-min` flag specifies the +minimum allocation from the secure heap. The minimum value is `2`. +The maximum value is the lesser of `--secure-heap` or `2147483647`. +The value given must be a power of two. + ### `--secure-heap=n` - -When using `--secure-heap`, the `--secure-heap-min` flag specifies the -minimum allocation from the secure heap. The minimum value is `2`. -The maximum value is the lesser of `--secure-heap` or `2147483647`. -The value given must be a power of two. - ### `--snapshot-blob=path` @@ -3606,6 +3585,16 @@ for MiB in 16 32 64 128; do done ``` +### `--perf-basic-prof` + +### `--perf-basic-prof-only-functions` + +### `--perf-prof` + +### `--perf-prof-unwinding-info` + +### `--prof` + ### `--security-revert` ### `--stack-trace-limit=limit` diff --git a/test/parallel/test-cli-node-options-docs.js b/test/parallel/test-cli-node-options-docs.js index ef82489d044171..8bcb69cdcba0f3 100644 --- a/test/parallel/test-cli-node-options-docs.js +++ b/test/parallel/test-cli-node-options-docs.js @@ -123,6 +123,21 @@ for (const [, envVar, config] of nodeOptionsCC.matchAll(addOptionRE)) { } } +{ + const sections = /^## (.+)$/mg; + const cliOptionPattern = /^### (?:`-\w.*`, )?`([^`]+)`/mg; + let match; + let previousIndex = 0; + do { + const sectionTitle = match?.[1]; + match = sections.exec(cliText); + const filteredCLIText = cliText.slice(previousIndex, match?.index); + const options = Array.from(filteredCLIText.matchAll(cliOptionPattern), (match) => match[1]); + assert.deepStrictEqual(options, options.toSorted(), `doc/api/cli.md ${sectionTitle} subsections are not in alphabetical order`); + previousIndex = match?.index; + } while (match); +} + // add alias handling manPagesOptions.delete('-trace-events-enabled');