From 5ee6ecd979e39badc3988e8abd56f44dd8393534 Mon Sep 17 00:00:00 2001
From: Richard Lau <riclau@uk.ibm.com>
Date: Tue, 11 Jun 2019 14:17:15 -0400
Subject: [PATCH] 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: https://github.com/nodejs/node/pull/28179
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
---
 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 8b3b697918cec2..fe790a43bb2f91 100644
--- a/doc/api/cli.md
+++ b/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,8 +1041,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`
@@ -1049,6 +1052,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 00000000000000..bb203d94d370d8
--- /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(' ')}`);