tools: update doctool dependencies, migrate to ESM

- Migrated to ESM because some dependencies now require it. - Did not update `highlight.js` to v11 because it has many breaking changes. - Used non-deprecated `highlight.js` API. Refs: highlightjs/highlight.js#2277Fixes: #38938 Co-authored-by: Antoine du Hamel <[email protected]> PR-URL: #38966 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Richard Lau <[email protected]> Reviewed-By: Anto Aravinth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

Author: targos

Makefile

@@ -338,7 +338,7 @@ test-valgrind: all
 test-check-deopts: all
 $(PYTHON) tools/test.py $(PARALLEL_ARGS) --mode=$(BUILDTYPE_LOWER) --check-deopts parallel sequential
 
-DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.js doc/api/addons.md
+DOCBUILDSTAMP_PREREQS = tools/doc/addon-verify.mjs doc/api/addons.md
 
 ifeq ($(OSTYPE),aix)
 DOCBUILDSTAMP_PREREQS := $(DOCBUILDSTAMP_PREREQS) out/$(BUILDTYPE)/node.exp
@@ -589,12 +589,12 @@ test-doc: doc-only lint-md ## Builds, lints, and verifies the docs.
 else\
 $(PYTHON) tools/test.py $(PARALLEL_ARGS) doctool;\
 fi
-$(NODE) tools/doc/checkLinks.js.
+$(NODE) tools/doc/checkLinks.mjs.
 
 .PHONY: test-doc-ci
 test-doc-ci: doc-only
 $(PYTHON) tools/test.py --shell $(NODE)$(TEST_CI_ARGS)$(PARALLEL_ARGS) doctool
-$(NODE) tools/doc/checkLinks.js.
+$(NODE) tools/doc/checkLinks.mjs.
 
 test-known-issues: all
 $(PYTHON) tools/test.py $(PARALLEL_ARGS) known_issues
@@ -736,33 +736,33 @@ run-npm-ci = $(PWD)/$(NPM) ci
 
 LINK_DATA = out/doc/apilinks.json
 VERSIONS_DATA = out/previous-doc-versions.json
-gen-api = tools/doc/generate.js --node-version=$(FULLVERSION)\
+gen-api = tools/doc/generate.mjs --node-version=$(FULLVERSION)\
  --apilinks=$(LINK_DATA)$< --output-directory=out/doc/api \
  --versions-file=$(VERSIONS_DATA)
-gen-apilink = tools/doc/apilinks.js$(LINK_DATA)$(wildcard lib/*.js)
+gen-apilink = tools/doc/apilinks.mjs$(LINK_DATA)$(wildcard lib/*.js)
 
-$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js | out/doc
+$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.mjs | out/doc
 $(call available-node, $(gen-apilink))
 
 # Regenerate previous versions data if the current version changes
-$(VERSIONS_DATA): CHANGELOG.md src/node_version.h tools/doc/versions.js
-$(call available-node, tools/doc/versions.js$@)
+$(VERSIONS_DATA): CHANGELOG.md src/node_version.h tools/doc/versions.mjs
+$(call available-node, tools/doc/versions.mjs$@)
 
-out/doc/api/%.jsonout/doc/api/%.html: doc/api/%.md tools/doc/generate.js\
- tools/doc/markdown.js tools/doc/html.js tools/doc/json.js\
- tools/doc/apilinks.js$(VERSIONS_DATA)|$(LINK_DATA) out/doc/api
+out/doc/api/%.jsonout/doc/api/%.html: doc/api/%.md tools/doc/generate.mjs\
+ tools/doc/markdown.mjs tools/doc/html.mjs tools/doc/json.mjs\
+ tools/doc/apilinks.mjs$(VERSIONS_DATA)|$(LINK_DATA) out/doc/api
 $(call available-node, $(gen-api))
 
-out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js\
- tools/doc/apilinks.js| out/doc/api
-$(call available-node, tools/doc/allhtml.js)
+out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.mjs\
+ tools/doc/apilinks.mjs| out/doc/api
+$(call available-node, tools/doc/allhtml.mjs)
 
-out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.js | out/doc/api
-$(call available-node, tools/doc/alljson.js)
+out/doc/api/all.json: $(apidocs_json) tools/doc/alljson.mjs | out/doc/api
+$(call available-node, tools/doc/alljson.mjs)
 
 .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)
+out/doc/api/stability: out/doc/api/all.json tools/doc/stability.mjs | out/doc/api
+$(call available-node, tools/doc/stability.mjs)
 
 .PHONY: docopen
 docopen: out/doc/api/all.html

doc/api/index.md

@@ -1,6 +1,6 @@
 <!--
  NB(chrisdickinson): if you move this file, be sure to update
- tools/doc/html.js to point at the new location.
+ tools/doc/html.mjs to point at the new location.
 -->
 
 <!--introduced_in=v0.10.0-->

test/common/index.mjs

@@ -30,6 +30,7 @@ const{
  allowGlobals,
  mustCall,
  mustCallAtLeast,
+ mustSucceed,
  hasMultiLocalhost,
  skipIfDumbTerminal,
  skipIfEslintMissing,
@@ -75,6 +76,7 @@ export{
 allowGlobals,
 mustCall,
 mustCallAtLeast,
+mustSucceed,
 hasMultiLocalhost,
 skipIfDumbTerminal,
 skipIfEslintMissing,

test/doctool/test-apilinks.js test/doctool/test-apilinks.mjstest/doctool/test-apilinks.js renamed to test/doctool/test-apilinks.mjs

@@ -1,14 +1,15 @@
-'use strict';
-
-require('../common');
-constfixtures=require('../common/fixtures');
-consttmpdir=require('../common/tmpdir');
-constfs=require('fs');
-constassert=require('assert');
-constpath=require('path');
-const{ execFileSync }=require('child_process');
-
-constscript=path.join(__dirname,'..','..','tools','doc','apilinks.js');
+import'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
+importtmpdirfrom'../common/tmpdir.js';
+
+importassertfrom'assert';
+import{execFileSync}from'child_process';
+importfsfrom'fs';
+importpathfrom'path';
+import{fileURLToPath}from'url';
+
+constscript=fileURLToPath(
+newURL('../../tools/doc/apilinks.mjs',import.meta.url));
 constapilinks=fixtures.path('apilinks');
 
 tmpdir.refresh();

test/doctool/test-doctool-html.js test/doctool/test-doctool-html.mjstest/doctool/test-doctool-html.js renamed to test/doctool/test-doctool-html.mjs

@@ -1,22 +1,14 @@
-'use strict';
+import'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 
-constcommon=require('../common');
-// The doctool currently uses js-yaml from the tool/node_modules/eslint/ tree.
-try{
-require('../../tools/node_modules/eslint/node_modules/js-yaml');
-}catch{
-common.skip('missing js-yaml (eslint not present)');
-}
+importassertfrom'assert';
+import{readFileSync}from'fs';
+import{createRequire}from'module';
 
-constassert=require('assert');
-const{ readFileSync }=require('fs');
-constfixtures=require('../common/fixtures');
-const{ replaceLinks }=require('../../tools/doc/markdown.js');
-consthtml=require('../../tools/doc/html.js');
-constpath=require('path');
+import*ashtmlfrom'../../tools/doc/html.mjs';
+import{replaceLinks}from'../../tools/doc/markdown.mjs';
 
-module.paths.unshift(
-path.join(__dirname,'..','..','tools','doc','node_modules'));
+constrequire=createRequire(newURL('../../tools/doc/',import.meta.url));
 constunified=require('unified');
 constmarkdown=require('remark-parse');
 constremark2rehype=require('remark-rehype');

test/doctool/test-doctool-json.js test/doctool/test-doctool-json.mjstest/doctool/test-doctool-json.js renamed to test/doctool/test-doctool-json.mjs

@@ -1,21 +1,13 @@
-'use strict';
+import*ascommonfrom'../common/index.mjs';
+import*asfixturesfrom'../common/fixtures.mjs';
 
-constcommon=require('../common');
-// The doctool currently uses js-yaml from the tool/node_modules/eslint/ tree.
-try{
-require('../../tools/node_modules/eslint/node_modules/js-yaml');
-}catch{
-common.skip('missing js-yaml (eslint not present)');
-}
+importassertfrom'assert';
+importfsfrom'fs';
+import{createRequire}from'module';
 
-constassert=require('assert');
-constfs=require('fs');
-constpath=require('path');
-constfixtures=require('../common/fixtures');
-constjson=require('../../tools/doc/json.js');
+import*asjsonfrom'../../tools/doc/json.mjs';
 
-module.paths.unshift(
-path.join(__dirname,'..','..','tools','doc','node_modules'));
+constrequire=createRequire(newURL('../../tools/doc/',import.meta.url));
 constunified=require('unified');
 constmarkdown=require('remark-parse');
 

test/doctool/test-doctool-versions.js test/doctool/test-doctool-versions.mjstest/doctool/test-doctool-versions.js renamed to test/doctool/test-doctool-versions.mjs

@@ -1,15 +1,16 @@
-'use strict';
+import'../common/index.mjs';
+importtmpdirfrom'../common/tmpdir.js';
 
-require('../common');
-constassert=require('assert');
-const{ spawnSync }=require('child_process');
-constfs=require('fs');
-constpath=require('path');
-consttmpdir=require('../common/tmpdir');
-constutil=require('util');
+importassertfrom'assert';
+import{spawnSync}from'child_process';
+importfsfrom'fs';
+importpathfrom'path';
+import{fileURLToPath}from'url';
+importutilfrom'util';
 
 constdebuglog=util.debuglog('test');
-constversionsTool=path.resolve(__dirname,'../../tools/doc/versions.js');
+constversionsTool=fileURLToPath(
+newURL('../../tools/doc/versions.mjs',import.meta.url));
 
 // At the time of writing these are the minimum expected versions.
 // New versions of Node.js do not have to be explicitly added here.

…ol/test-local-md-file-reference-regex.js …l/test-local-md-file-reference-regex.mjstest/doctool/test-local-md-file-reference-regex.js renamed to test/doctool/test-local-md-file-reference-regex.mjs test/doctool/test-local-md-file-reference-regex.js renamed to test/doctool/test-local-md-file-reference-regex.mjs

@@ -1,9 +1,8 @@
-'use strict';
+import'../common/index.mjs';
 
-require('../common');
-constassert=require('assert');
+importassertfrom'assert';
 
-const{ referenceToLocalMdFile }=require('../../tools/doc/markdown.js');
+import{referenceToLocalMdFile}from'../../tools/doc/markdown.mjs';
 
 {
 constshouldBeSpotted=[

test/doctool/test-make-doc.js test/doctool/test-make-doc.mjstest/doctool/test-make-doc.js renamed to test/doctool/test-make-doc.mjs

@@ -1,20 +1,20 @@
-'use strict';
-constcommon=require('../common');
+import*ascommonfrom'../common/index.mjs';
+
+importassertfrom'assert';
+importfsfrom'fs';
+importpathfrom'path';
+
 if(common.isWindows){
 common.skip('`make doc` does not run on Windows');
 }
 
 // This tests that `make doc` generates the documentation properly.
 // Note that for this test to pass, `make doc` must be run first.
 
-constassert=require('assert');
-constfs=require('fs');
-constpath=require('path');
-
-constapiPath=path.resolve(__dirname,'..','..','out','doc','api');
-constmdPath=path.resolve(__dirname,'..','..','doc','api');
-constallMD=fs.readdirSync(mdPath);
-constallDocs=fs.readdirSync(apiPath);
+constapiURL=newURL('../../out/doc/api/',import.meta.url);
+constmdURL=newURL('../../doc/api/',import.meta.url);
+constallMD=fs.readdirSync(mdURL);
+constallDocs=fs.readdirSync(apiURL);
 assert.ok(allDocs.includes('index.html'));
 
 constactualDocs=allDocs.filter(
@@ -33,7 +33,7 @@ for (const name of actualDocs){
 );
 }
 
-consttoc=fs.readFileSync(path.resolve(apiPath,'index.html'),'utf8');
+consttoc=fs.readFileSync(newURL('./index.html',apiURL),'utf8');
 constre=/href="([^/]+\.html)"/;
 constglobalRe=newRegExp(re,'g');
 constlinks=toc.match(globalRe);
@@ -56,8 +56,9 @@ for (const actualDoc of actualDocs){
 assert.ok(
 expectedDocs.includes(actualDoc),`${actualDoc} does not match TOC`);
 
-assert.ok(
-fs.statSync(path.join(apiPath,actualDoc)).size!==0,
+assert.notStrictEqual(
+fs.statSync(newURL(`./${actualDoc}`,apiURL)).size,
+0,
 `${actualDoc} is empty`
 );
 }

tools/doc/README.md

@@ -78,7 +78,7 @@ added: v0.10.0
 
 * Returns:{SomeClass | null} The next `SomeClass` in line.
 
-`SomeClass` must be registered in `tools/doc/type-parser.js`
+`SomeClass` must be registered in `tools/doc/type-parser.mjs`
 to be properly parsed in `{type}` fields.
 
 ### SomeClass.someProperty