From 75f4b788f6bc4e68f3202b984f232ade64056ff8 Mon Sep 17 00:00:00 2001
From: tpoisseau <theotime.poisseau@gmail.com>
Date: Thu, 24 Oct 2019 12:14:45 +0200
Subject: [PATCH 1/2] tools: doc: improve async workflow of generate.js

Use fs.promises for read and write file
Use unified().process wich is async instead processSync
html and json are write in parallel
errors are logged and exit process with `1` code

Fixes: https://github.com/nodejs/node/issues/30090
---
 tools/doc/generate.js  | 89 +++++++++++++++++++++++++++---------------
 tools/doc/package.json |  2 +-
 2 files changed, 58 insertions(+), 33 deletions(-)

diff --git a/tools/doc/generate.js b/tools/doc/generate.js
index 7be5f3f73fc26a..ff826415e44a09 100644
--- a/tools/doc/generate.js
+++ b/tools/doc/generate.js
@@ -21,7 +21,7 @@
 
 'use strict';
 
-const fs = require('fs');
+const { promises: fs } = require('fs');
 const path = require('path');
 const unified = require('unified');
 const markdown = require('remark-parse');
@@ -41,36 +41,35 @@ let nodeVersion = null;
 let outputDir = null;
 let apilinks = {};
 
-args.forEach((arg) => {
-  if (!arg.startsWith('--')) {
-    filename = arg;
-  } else if (arg.startsWith('--node-version=')) {
-    nodeVersion = arg.replace(/^--node-version=/, '');
-  } else if (arg.startsWith('--output-directory=')) {
-    outputDir = arg.replace(/^--output-directory=/, '');
-  } else if (arg.startsWith('--apilinks=')) {
-    const linkFile = arg.replace(/^--apilinks=/, '');
-    const data = fs.readFileSync(linkFile, 'utf8');
-    if (!data.trim()) {
-      throw new Error(`${linkFile} is empty`);
+async function main() {
+  for (const arg of args) {
+    if (!arg.startsWith('--')) {
+      filename = arg;
+    } else if (arg.startsWith('--node-version=')) {
+      nodeVersion = arg.replace(/^--node-version=/, '');
+    } else if (arg.startsWith('--output-directory=')) {
+      outputDir = arg.replace(/^--output-directory=/, '');
+    } else if (arg.startsWith('--apilinks=')) {
+      const linkFile = arg.replace(/^--apilinks=/, '');
+      const data = await fs.readFile(linkFile, 'utf8');
+      if (!data.trim()) {
+        throw new Error(`${linkFile} is empty`);
+      }
+      apilinks = JSON.parse(data);
     }
-    apilinks = JSON.parse(data);
   }
-});
 
-nodeVersion = nodeVersion || process.version;
-
-if (!filename) {
-  throw new Error('No input file specified');
-} else if (!outputDir) {
-  throw new Error('No output directory specified');
-}
+  nodeVersion = nodeVersion || process.version;
 
+  if (!filename) {
+    throw new Error('No input file specified');
+  } else if (!outputDir) {
+    throw new Error('No output directory specified');
+  }
 
-fs.readFile(filename, 'utf8', async (er, input) => {
-  if (er) throw er;
+  const input = await fs.readFile(filename, 'utf8');
 
-  const content = unified()
+  const content = await unified()
     .use(markdown)
     .use(html.preprocessText)
     .use(json.jsonAPI, { filename })
@@ -80,14 +79,40 @@ fs.readFile(filename, 'utf8', async (er, input) => {
     .use(remark2rehype, { allowDangerousHTML: true })
     .use(raw)
     .use(htmlStringify)
-    .processSync(input);
-
-  const basename = path.basename(filename, '.md');
+    .process(input);
 
   const myHtml = await html.toHTML({ input, content, filename, nodeVersion });
+  const basename = path.basename(filename, '.md');
   const htmlTarget = path.join(outputDir, `${basename}.html`);
-  fs.writeFileSync(htmlTarget, myHtml);
-
   const jsonTarget = path.join(outputDir, `${basename}.json`);
-  fs.writeFileSync(jsonTarget, JSON.stringify(content.json, null, 2));
-});
+
+  return Promise.allSettled([
+    fs.writeFile(htmlTarget, myHtml),
+    fs.writeFile(jsonTarget, JSON.stringify(content.json, null, 2)),
+  ]);
+}
+
+main()
+  .then((tasks) => {
+    // Filter tasks rejected
+    const errors = tasks.filter(({ status }) => status === 'rejected')
+      .map(({ reason }) => reason);
+
+    // Log errors
+    for (const error of errors) {
+      console.error(error);
+    }
+
+    // Exit process with code 1 if some errors
+    if (errors.length > 0) {
+      return process.exit(1);
+    }
+
+    // Else with code 1
+    process.exit(0);
+  })
+  .catch((error) => {
+    console.error(error);
+
+    process.exit(1);
+  });
diff --git a/tools/doc/package.json b/tools/doc/package.json
index 1d2953b023b06d..11f6c76c911a59 100644
--- a/tools/doc/package.json
+++ b/tools/doc/package.json
@@ -4,7 +4,7 @@
   "description": "Internal tool for generating Node.js API docs",
   "version": "0.0.0",
   "engines": {
-    "node": ">=6"
+    "node": ">=12.10.0"
   },
   "dependencies": {
     "rehype-raw": "^2.0.0",

From c1cbd68237af859e10600c07d2a4aaefbd1e1cc2 Mon Sep 17 00:00:00 2001
From: tpoisseau <theotime.poisseau@gmail.com>
Date: Thu, 24 Oct 2019 13:42:54 +0200
Subject: [PATCH 2/2] Apply suggestions from code review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Michaël Zasso <targos@protonmail.com>
---
 tools/doc/generate.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/doc/generate.js b/tools/doc/generate.js
index ff826415e44a09..cd85d5365791ba 100644
--- a/tools/doc/generate.js
+++ b/tools/doc/generate.js
@@ -94,7 +94,7 @@ async function main() {
 
 main()
   .then((tasks) => {
-    // Filter tasks rejected
+    // Filter rejected tasks
     const errors = tasks.filter(({ status }) => status === 'rejected')
       .map(({ reason }) => reason);
 
@@ -108,7 +108,7 @@ main()
       return process.exit(1);
     }
 
-    // Else with code 1
+    // Else with code 0
     process.exit(0);
   })
   .catch((error) => {