Skip to content

Commit 4b4aaf9

Browse files
test: add tests to ensure that node.1 is kept in sync with cli.md
add tests to make sure that the content of the doc/node.1 file is kept in snyc with the content of the doc/api/cli.md file (to make sure that when a flag or environment variable is added or removed to one, the same change is also applied to the other) PR-URL: #58878 Reviewed-By: Chemi Atlow <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 16035b4 commit 4b4aaf9

File tree

2 files changed

+273
-0
lines changed

2 files changed

+273
-0
lines changed
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
import '../common/index.mjs';
2+
import assert from 'node:assert';
3+
import { createReadStream } from 'node:fs';
4+
import { createInterface } from 'node:readline';
5+
import { resolve, join } from 'node:path';
6+
7+
// This test checks that all the environment variables defined in the public CLI documentation (doc/api/cli.md)
8+
// are also documented in the manpage file (doc/node.1) and vice-versa (that all the environment variables
9+
// in the manpage are present in the CLI documentation)
10+
11+
const rootDir = resolve(import.meta.dirname, '..', '..');
12+
13+
const cliMdEnvVarNames = await collectCliMdEnvVarNames();
14+
const manpageEnvVarNames = await collectManPageEnvVarNames();
15+
16+
assert(cliMdEnvVarNames.size > 0,
17+
'Unexpectedly not even a single env variable was detected when scanning the `doc/api/cli.md` file'
18+
);
19+
20+
assert(manpageEnvVarNames.size > 0,
21+
'Unexpectedly not even a single env variable was detected when scanning the `doc/node.1` file'
22+
);
23+
24+
// TODO(dario-piotrowicz): add the missing env variables to the manpage and remove this set
25+
// (refs: https://github.com/nodejs/node/issues/58894)
26+
const knownEnvVariablesMissingFromManPage = new Set([
27+
'NODE_COMPILE_CACHE',
28+
'NODE_DISABLE_COMPILE_CACHE',
29+
'NODE_PENDING_PIPE_INSTANCES',
30+
'NODE_TEST_CONTEXT',
31+
'NODE_USE_ENV_PROXY',
32+
]);
33+
34+
for (const envVarName of cliMdEnvVarNames) {
35+
if (!manpageEnvVarNames.has(envVarName) && !knownEnvVariablesMissingFromManPage.has(envVarName)) {
36+
assert.fail(`The "${envVarName}" environment variable (present in \`doc/api/cli.md\`) is missing from the \`doc/node.1\` file`);
37+
}
38+
manpageEnvVarNames.delete(envVarName);
39+
}
40+
41+
if (manpageEnvVarNames.size > 0) {
42+
assert.fail(`The following env variables are present in the \`doc/node.1\` file but not in the \`doc/api/cli.md\` file: ${
43+
[...manpageEnvVarNames].map((name) => `"${name}"`).join(', ')
44+
}`);
45+
}
46+
47+
async function collectManPageEnvVarNames() {
48+
const manPagePath = join(rootDir, 'doc', 'node.1');
49+
const fileStream = createReadStream(manPagePath);
50+
51+
const rl = createInterface({
52+
input: fileStream,
53+
});
54+
55+
const envVarNames = new Set();
56+
57+
for await (const line of rl) {
58+
const match = line.match(/^\.It Ev (?<envName>[^ ]*)/);
59+
if (match) {
60+
envVarNames.add(match.groups.envName);
61+
}
62+
}
63+
64+
return envVarNames;
65+
}
66+
67+
async function collectCliMdEnvVarNames() {
68+
const cliMdPath = join(rootDir, 'doc', 'api', 'cli.md');
69+
const fileStream = createReadStream(cliMdPath);
70+
71+
let insideEnvVariablesSection = false;
72+
73+
const rl = createInterface({
74+
input: fileStream,
75+
});
76+
77+
const envVariableRE = /^### `(?<varName>[^`]*?)(?:=[^`]+)?`$/;
78+
79+
const envVarNames = new Set();
80+
81+
for await (const line of rl) {
82+
if (line.startsWith('## ')) {
83+
if (insideEnvVariablesSection) {
84+
// We were in the environment variables section and we're now exiting it,
85+
// so there is no need to keep checking the remaining lines,
86+
// we might as well close the stream and return
87+
fileStream.close();
88+
return envVarNames;
89+
}
90+
91+
// We've just entered the options section
92+
insideEnvVariablesSection = line === '## Environment variables';
93+
continue;
94+
}
95+
96+
if (insideEnvVariablesSection) {
97+
const match = line.match(envVariableRE);
98+
if (match) {
99+
const { varName } = match.groups;
100+
envVarNames.add(varName);
101+
}
102+
}
103+
}
104+
105+
return envVarNames;
106+
}
Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
import '../common/index.mjs';
2+
import assert from 'node:assert';
3+
import { createReadStream, readFileSync } from 'node:fs';
4+
import { createInterface } from 'node:readline';
5+
import { resolve, join } from 'node:path';
6+
import { EOL } from 'node:os';
7+
8+
// This test checks that all the CLI flags defined in the public CLI documentation (doc/api/cli.md)
9+
// are also documented in the manpage file (doc/node.1)
10+
// Note: the opposite (that all variables in doc/node.1 are documented in the CLI documentation)
11+
// is covered in the test-cli-node-options-docs.js file
12+
13+
const rootDir = resolve(import.meta.dirname, '..', '..');
14+
15+
const cliMdPath = join(rootDir, 'doc', 'api', 'cli.md');
16+
const cliMdContentsStream = createReadStream(cliMdPath);
17+
18+
const manPagePath = join(rootDir, 'doc', 'node.1');
19+
const manPageContents = readFileSync(manPagePath, { encoding: 'utf8' });
20+
21+
// TODO(dario-piotrowicz): add the missing flags to the node.1 and remove this set
22+
// (refs: https://github.com/nodejs/node/issues/58895)
23+
const knownFlagsMissingFromManPage = new Set([
24+
'build-snapshot',
25+
'build-snapshot-config',
26+
'disable-sigusr1',
27+
'disable-warning',
28+
'dns-result-order',
29+
'enable-network-family-autoselection',
30+
'env-file-if-exists',
31+
'env-file',
32+
'experimental-network-inspection',
33+
'experimental-print-required-tla',
34+
'experimental-require-module',
35+
'experimental-sea-config',
36+
'experimental-worker-inspection',
37+
'expose-gc',
38+
'force-node-api-uncaught-exceptions-policy',
39+
'import',
40+
'network-family-autoselection-attempt-timeout',
41+
'no-async-context-frame',
42+
'no-experimental-detect-module',
43+
'no-experimental-global-navigator',
44+
'no-experimental-require-module',
45+
'no-network-family-autoselection',
46+
'openssl-legacy-provider',
47+
'openssl-shared-config',
48+
'report-dir',
49+
'report-directory',
50+
'report-exclude-env',
51+
'report-exclude-network',
52+
'run',
53+
'snapshot-blob',
54+
'trace-env',
55+
'trace-env-js-stack',
56+
'trace-env-native-stack',
57+
'trace-require-module',
58+
'use-system-ca',
59+
'watch-preserve-output',
60+
]);
61+
62+
const optionsEncountered = { dash: 0, dashDash: 0, named: 0 };
63+
let insideOptionsSection = false;
64+
65+
const rl = createInterface({
66+
input: cliMdContentsStream,
67+
});
68+
69+
const isOptionLineRegex = /^###(?: `[^`]*`,?)*$/;
70+
71+
for await (const line of rl) {
72+
if (line.startsWith('## ')) {
73+
if (insideOptionsSection) {
74+
// We were in the options section and we're now exiting it,
75+
// so there is no need to keep checking the remaining lines,
76+
// we might as well close the stream and exit the loop
77+
cliMdContentsStream.close();
78+
break;
79+
}
80+
81+
// We've just entered the options section
82+
insideOptionsSection = line === '## Options';
83+
continue;
84+
}
85+
86+
if (insideOptionsSection && isOptionLineRegex.test(line)) {
87+
if (line === '### `-`') {
88+
if (!manPageContents.includes(`${EOL}.It Sy -${EOL}`)) {
89+
throw new Error(`The \`-\` flag is missing in the \`doc/node.1\` file`);
90+
}
91+
optionsEncountered.dash++;
92+
continue;
93+
}
94+
95+
if (line === '### `--`') {
96+
if (!manPageContents.includes(`${EOL}.It Fl -${EOL}`)) {
97+
throw new Error(`The \`--\` flag is missing in the \`doc/node.1\` file`);
98+
}
99+
optionsEncountered.dashDash++;
100+
continue;
101+
}
102+
103+
const flagNames = extractFlagNames(line);
104+
105+
optionsEncountered.named += flagNames.length;
106+
107+
const manLine = `.It ${flagNames
108+
.map((flag) => `Fl ${flag.length > 1 ? '-' : ''}${flag}`)
109+
.join(' , ')}`;
110+
111+
if (
112+
// Note: we don't check the full line (note the EOL only at the beginning) because
113+
// options can have arguments and we do want to ignore those
114+
!manPageContents.includes(`${EOL}${manLine}`) &&
115+
!flagNames.every((flag) => knownFlagsMissingFromManPage.has(flag))) {
116+
assert.fail(
117+
`The following flag${
118+
flagNames.length === 1 ? '' : 's'
119+
} (present in \`doc/api/cli.md\`) ${flagNames.length === 1 ? 'is' : 'are'} missing in the \`doc/node.1\` file: ${
120+
flagNames.map((flag) => `"${flag}"`).join(', ')
121+
}`
122+
);
123+
}
124+
}
125+
}
126+
127+
assert.strictEqual(optionsEncountered.dash, 1);
128+
129+
assert.strictEqual(optionsEncountered.dashDash, 1);
130+
131+
assert(optionsEncountered.named > 0,
132+
'Unexpectedly not even a single cli flag/option was detected when scanning the `doc/cli.md` file'
133+
);
134+
135+
/**
136+
* Function that given a string containing backtick enclosed cli flags
137+
* separated by `, ` returns the name of flags present in the string
138+
* e.g. `extractFlagNames('`-x`, `--print "script"`')` === `['x', 'print']`
139+
* @param {string} str target string
140+
* @returns {string[]} the name of the detected flags
141+
*/
142+
function extractFlagNames(str) {
143+
const match = str.match(/`[^`]*?`/g);
144+
if (!match) {
145+
return [];
146+
}
147+
return match.map((flag) => {
148+
// Remove the backticks from the flag
149+
flag = flag.slice(1, -1);
150+
151+
// Remove the dash or dashes
152+
flag = flag.replace(/^--?/, '');
153+
154+
// If the flag contains parameters make sure to remove those
155+
const nameDelimiters = ['=', ' ', '['];
156+
const nameCutOffIdx = Math.min(...nameDelimiters.map((d) => {
157+
const idx = flag.indexOf(d);
158+
if (idx > 0) {
159+
return idx;
160+
}
161+
return flag.length;
162+
}));
163+
flag = flag.slice(0, nameCutOffIdx);
164+
165+
return flag;
166+
});
167+
}

0 commit comments

Comments
 (0)