tools,doc: list the stability status of each API

Fixes: #23723

PR-URL: #36223
Reviewed-By: Joyee Cheung <[email protected]>
Reviewed-By: Gireesh Punathil <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Myles Borins <[email protected]>
Reviewed-By: Franziska Hinkelmann <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>

Makefile

@@ -696,7 +696,7 @@ doc-only: tools/doc/node_modules \
 	@if [ "$(shell $(node_use_openssl))" != "true" ]; then \
 		echo "Skipping doc-only (no crypto)"; \
 	else \
-		$(MAKE) out/doc/api/all.html out/doc/api/all.json; \
+		$(MAKE) out/doc/api/all.html out/doc/api/all.json out/doc/api/stability; \
 	fi
 
 .PHONY: doc
@@ -749,6 +749,10 @@ out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \
 out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.js | out/doc/api
 	$(call available-node, tools/doc/alljson.js)
 
+.PHONY: out/doc/api/stability
+out/doc/api/stability: out/doc/api/all.json tools/doc/stability.js | out/doc/api
+	$(call available-node, tools/doc/stability.js)
+
 .PHONY: docopen
 docopen: out/doc/api/all.html
 	@$(PYTHON) -mwebbrowser file://$(abspath $<)

doc/api/documentation.md

@@ -43,6 +43,9 @@ Bugs or behavior changes may surprise users when Experimental API
 modifications occur. To avoid surprises, use of an Experimental feature may need
 a command-line flag. Experimental features may also emit a [warning][].
 
+## Stability overview
+<!-- STABILITY_OVERVIEW_SLOT -->
+
 ## JSON output
 <!-- YAML
 added: v0.6.12

doc/api_assets/style.css

@@ -263,6 +263,10 @@ ol.version-picker li:last-child a {
   background-color: var(--green2);
 }
 
+.module_stability {
+  vertical-align: middle;
+}
+
 .api_metadata {
   font-size: .85rem;
   margin-bottom: 1rem;

tools/doc/alljson.js

@@ -43,6 +43,9 @@ for (const link of toc.match(/<a.*?>/g)) {
 
   for (const property in data) {
     if (results.hasOwnProperty(property)) {
+      data[property].forEach((mod) => {
+        mod.source = data.source;
+      });
       results[property].push(...data[property]);
     }
   }

tools/doc/stability.js

@@ -0,0 +1,111 @@
+'use strict';
+
+// Build stability table to documentation.html/json/md by generated all.json
+
+const fs = require('fs');
+const path = require('path');
+const unified = require('unified');
+const raw = require('rehype-raw');
+const markdown = require('remark-parse');
+const htmlStringify = require('rehype-stringify');
+const gfm = require('remark-gfm');
+const remark2rehype = require('remark-rehype');
+const visit = require('unist-util-visit');
+
+const source = `${__dirname}/../../out/doc/api`;
+const data = require(path.join(source, 'all.json'));
+const mark = '<!-- STABILITY_OVERVIEW_SLOT -->';
+
+const output = {
+  json: path.join(source, 'stability.json'),
+  docHTML: path.join(source, 'documentation.html'),
+  docJSON: path.join(source, 'documentation.json'),
+  docMarkdown: path.join(source, 'documentation.md'),
+};
+
+function collectStability(data) {
+  const stability = [];
+
+  for (const mod of data.modules) {
+    if (mod.displayName && mod.stability >= 0) {
+      const link = mod.source.replace('doc/api/', '').replace('.md', '.html');
+      // const link = re.exec(toc)[1]
+      stability.push({
+        api: mod.name,
+        link: link,
+        stability: mod.stability,
+        stabilityText: `(${mod.stability}) ${mod.stabilityText}`,
+      });
+    }
+  }
+
+  stability.sort((a, b) => a.api.localeCompare(b.api));
+  return stability;
+}
+
+function createMarkdownTable(data) {
+  const md = ['| API | Stability |', '| --- | --------- |'];
+
+  for (const mod of data) {
+    md.push(`| [${mod.api}](${mod.link}) | ${mod.stabilityText} |`);
+  }
+
+  return md.join('\n');
+}
+
+function createHTML(md) {
+  const file = unified()
+    .use(markdown)
+    .use(gfm)
+    .use(remark2rehype, { allowDangerousHtml: true })
+    .use(raw)
+    .use(htmlStringify)
+    .use(processStability)
+    .processSync(md);
+
+  return file.contents.trim();
+}
+
+function processStability() {
+  return (tree) => {
+    visit(tree, { type: 'element', tagName: 'tr' }, (node) => {
+      const [api, stability] = node.children;
+      if (api.tagName !== 'td') {
+        return;
+      }
+
+      api.properties.class = 'module_stability';
+
+      const level = stability.children[0].value[1];
+      stability.properties.class = `api_stability api_stability_${level}`;
+    });
+  };
+}
+
+function updateStabilityMark(file, value, mark) {
+  const fd = fs.openSync(file, 'r+');
+  const content = fs.readFileSync(fd);
+
+  // Find the position of the `mark`.
+  const index = content.indexOf(mark);
+
+  // Overwrite the mark with `value` parameter.
+  const offset = fs.writeSync(fd, value, index, 'utf-8');
+
+  // Re-write the end of the file after `value`.
+  fs.writeSync(fd, content, index + mark.length, undefined, index + offset);
+  fs.closeSync(fd);
+}
+
+const stability = collectStability(data);
+
+// add markdown
+const markdownTable = createMarkdownTable(stability);
+updateStabilityMark(output.docMarkdown, markdownTable, mark);
+
+// add html table
+const html = createHTML(markdownTable);
+updateStabilityMark(output.docHTML, html, mark);
+
+// add json output
+updateStabilityMark(output.docJSON, JSON.stringify(html), JSON.stringify(mark));