fixup!

Author: avivkeller

test/doctool/test-manpage-envvars.mjs

@@ -0,0 +1,96 @@
+import '../common/index.mjs';
+import assert from 'node:assert';
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { resolve, join } from 'node:path';
+
+// This test checks that all the environment variables defined in the public CLI documentation (doc/api/cli.md)
+// are also documented in the manpage file (doc/node.1) and vice-versa (that all the environment variables
+// in the manpage are present in the CLI documentation)
+
+const rootDir = resolve(import.meta.dirname, '..', '..');
+
+const cliMdEnvVarNames = await collectCliMdEnvVarNames();
+const manpageEnvVarNames = await collectManPageEnvVarNames();
+
+assert(cliMdEnvVarNames.size > 0,
+       'Unexpectedly not even a single env variable was detected when scanning the `doc/api/cli.md` file'
+);
+
+assert(manpageEnvVarNames.size > 0,
+       'Unexpectedly not even a single env variable was detected when scanning the `doc/node.1` file'
+);
+
+for (const envVarName of cliMdEnvVarNames) {
+  if (!manpageEnvVarNames.has(envVarName)) {
+    assert.fail(`The "${envVarName}" environment variable (present in \`doc/api/cli.md\`) is missing from the \`doc/node.1\` file`);
+  }
+  manpageEnvVarNames.delete(envVarName);
+}
+
+if (manpageEnvVarNames.size > 0) {
+  assert.fail(`The following env variables are present in the \`doc/node.1\` file but not in the \`doc/api/cli.md\` file: ${
+    [...manpageEnvVarNames].map((name) => `"${name}"`).join(', ')
+  }`);
+}
+
+async function collectManPageEnvVarNames() {
+  const manPagePath = join(rootDir, 'out', 'doc', 'node.1');
+  const fileStream = createReadStream(manPagePath);
+
+  const rl = createInterface({
+    input: fileStream,
+  });
+
+  const envVarNames = new Set();
+
+  for await (const line of rl) {
+    const match = line.match(/^\.It Ev (?<envName>[^ ]*)/);
+    if (match) {
+      envVarNames.add(match.groups.envName);
+    }
+  }
+
+  return envVarNames;
+}
+
+async function collectCliMdEnvVarNames() {
+  const cliMdPath = join(rootDir, 'doc', 'api', 'cli.md');
+  const fileStream = createReadStream(cliMdPath);
+
+  let insideEnvVariablesSection = false;
+
+  const rl = createInterface({
+    input: fileStream,
+  });
+
+  const envVariableRE = /^### `(?<varName>[^`]*?)(?:=[^`]+)?`$/;
+
+  const envVarNames = new Set();
+
+  for await (const line of rl) {
+    if (line.startsWith('## ')) {
+      if (insideEnvVariablesSection) {
+        // We were in the environment variables section and we're now exiting it,
+        // so there is no need to keep checking the remaining lines,
+        // we might as well close the stream and return
+        fileStream.close();
+        return envVarNames;
+      }
+
+      // We've just entered the options section
+      insideEnvVariablesSection = line === '## Environment variables';
+      continue;
+    }
+
+    if (insideEnvVariablesSection) {
+      const match = line.match(envVariableRE);
+      if (match) {
+        const { varName } = match.groups;
+        envVarNames.add(varName);
+      }
+    }
+  }
+
+  return envVarNames;
+}

test/doctool/test-manpage-options.mjs

@@ -0,0 +1,88 @@
+import '../common/index.mjs';
+import assert from 'node:assert';
+import { createReadStream, readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { resolve, join } from 'node:path';
+
+// This test checks that all the CLI flags defined in the public CLI documentation (doc/api/cli.md)
+// are also documented in the manpage file (doc/node.1)
+// Note: the opposite (that all variables in doc/node.1 are documented in the CLI documentation)
+//       is covered in the test-cli-node-options-docs.js file
+
+const rootDir = resolve(import.meta.dirname, '..', '..');
+
+const cliMdPath = join(rootDir, 'doc', 'api', 'cli.md');
+const cliMdContentsStream = createReadStream(cliMdPath);
+
+const manPagePath = join(rootDir, 'out', 'doc', 'node.1');
+const manPageContents = readFileSync(manPagePath, { encoding: 'utf8' });
+
+let insideOptionsSection = false;
+
+const rl = createInterface({
+  input: cliMdContentsStream,
+});
+
+const isOptionLineRegex = /^###(?: `[^`]*`,?)*$/;
+
+for await (const line of rl) {
+  if (line.startsWith('## ')) {
+    if (insideOptionsSection) {
+      // We were in the options section and we're now exiting it,
+      // so there is no need to keep checking the remaining lines,
+      // we might as well close the stream and exit the loop
+      cliMdContentsStream.close();
+      break;
+    }
+
+    // We've just entered the options section
+    insideOptionsSection = line === '## Options';
+    continue;
+  }
+
+  if (insideOptionsSection && isOptionLineRegex.test(line)) {
+    const flagNames = extractFlagNames(line);
+    const flagMatcher = new RegExp(`^\\.It ${flagNames.map((f) => `Fl ${f}.*`).join(', ')}$`, 'm');
+
+    if (!manPageContents.match(flagMatcher)) {
+      assert.fail(
+        `The following flag${
+          flagNames.length === 1 ? '' : 's'
+        } (present in \`doc/api/cli.md\`) ${flagNames.length === 1 ? 'is' : 'are'} missing in the \`doc/node.1\` file: ${
+          flagNames.map((flag) => `"-${flag}"`).join(', ')
+        }`
+      );
+    }
+  }
+}
+
+/**
+ * Function that given a string containing backtick enclosed cli flags
+ * separated by `, ` returns the name of flags present in the string
+ * e.g. `extractFlagNames('`-x`, `--print "script"`')` === `['x', 'print']`
+ * @param {string} str target string
+ * @returns {string[]} the name of the detected flags
+ */
+function extractFlagNames(str) {
+  const match = str.match(/`[^`]*?`/g);
+  if (!match) {
+    return [];
+  }
+  return match.map((flag) => {
+    // Remove the backticks, and leading dash from the flag
+    flag = flag.slice(2, -1);
+
+    // If the flag contains parameters make sure to remove those
+    const nameDelimiters = ['=', ' ', '['];
+    const nameCutOffIdx = Math.min(...nameDelimiters.map((d) => {
+      const idx = flag.indexOf(d);
+      if (idx > 0) {
+        return idx;
+      }
+      return flag.length;
+    }));
+    flag = flag.slice(0, nameCutOffIdx);
+
+    return flag;
+  });
+}