tools,doc: list the stability status of each API

Fixes: #23723
PR-URL: #36223
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>

Author: Lxxyx

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(constpropertyindata){
 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
+
+constfs=require('fs');
+constpath=require('path');
+constunified=require('unified');
+constraw=require('rehype-raw');
+constmarkdown=require('remark-parse');
+consthtmlStringify=require('rehype-stringify');
+constgfm=require('remark-gfm');
+constremark2rehype=require('remark-rehype');
+constvisit=require('unist-util-visit');
+
+constsource=`${__dirname}/../../out/doc/api`;
+constdata=require(path.join(source,'all.json'));
+constmark='<!-- STABILITY_OVERVIEW_SLOT -->';
+
+constoutput={
+json: path.join(source,'stability.json'),
+docHTML: path.join(source,'documentation.html'),
+docJSON: path.join(source,'documentation.json'),
+docMarkdown: path.join(source,'documentation.md'),
+};
+
+functioncollectStability(data){
+conststability=[];
+
+for(constmodofdata.modules){
+if(mod.displayName&&mod.stability>=0){
+constlink=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));
+returnstability;
+}
+
+functioncreateMarkdownTable(data){
+constmd=['| API | Stability |','| --- | --------- |'];
+
+for(constmodofdata){
+md.push(`| [${mod.api}](${mod.link}) | ${mod.stabilityText} |`);
+}
+
+returnmd.join('\n');
+}
+
+functioncreateHTML(md){
+constfile=unified()
+.use(markdown)
+.use(gfm)
+.use(remark2rehype,{allowDangerousHtml: true})
+.use(raw)
+.use(htmlStringify)
+.use(processStability)
+.processSync(md);
+
+returnfile.contents.trim();
+}
+
+functionprocessStability(){
+return(tree)=>{
+visit(tree,{type: 'element',tagName: 'tr'},(node)=>{
+const[api,stability]=node.children;
+if(api.tagName!=='td'){
+return;
+}
+
+api.properties.class='module_stability';
+
+constlevel=stability.children[0].value[1];
+stability.properties.class=`api_stability api_stability_${level}`;
+});
+};
+}
+
+functionupdateStabilityMark(file,value,mark){
+constfd=fs.openSync(file,'r+');
+constcontent=fs.readFileSync(fd);
+
+// Find the position of the `mark`.
+constindex=content.indexOf(mark);
+
+// Overwrite the mark with `value` parameter.
+constoffset=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);
+}
+
+conststability=collectStability(data);
+
+// add markdown
+constmarkdownTable=createMarkdownTable(stability);
+updateStabilityMark(output.docMarkdown,markdownTable,mark);
+
+// add html table
+consthtml=createHTML(markdownTable);
+updateStabilityMark(output.docHTML,html,mark);
+
+// add json output
+updateStabilityMark(output.docJSON,JSON.stringify(html),JSON.stringify(mark));