tools: make apilinks building more robust

1. Move the apilinks.json file into out/doc so it gets cleaned when
running `make docclean`
2. When the apilinks.json generated is empty, throw a specific error
so it's easier to understand what's wrong
3. Write to a file passed through CLI arguments instead writing to
stdout in apilinks.js so the build process is more robust in
the case of a bad binary
PR-URL: #25019
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: joyeecheung

Makefile

@@ -692,16 +692,16 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets
 
 run-npm-ci = $(PWD)/$(NPM) ci
 
+LINK_DATA = out/doc/apilinks.json
 gen-api = tools/doc/generate.js --node-version=$(FULLVERSION)\
- --apilinks=out/apilinks.json$< --output-directory=out/doc/api
-gen-apilink = tools/doc/apilinks.js $(wildcard lib/*.js) > $@
+ --apilinks=$(LINK_DATA)$< --output-directory=out/doc/api
+gen-apilink = tools/doc/apilinks.js $(LINK_DATA)$(wildcard lib/*.js)
 
-out/apilinks.json: $(wildcard lib/*.js) tools/doc/apilinks.js
+$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js
 $(call available-node, $(gen-apilink))
 
 out/doc/api/%.jsonout/doc/api/%.html: doc/api/%.md tools/doc/generate.js \
-	tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js |\
-	out/apilinks.json
+	tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js |$(LINK_DATA)
 $(call available-node, $(gen-api))
 
 out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \

test/doctool/test-apilinks.js

@@ -2,28 +2,31 @@
 
 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');
-
 constapilinks=fixtures.path('apilinks');
+
+tmpdir.refresh();
+
 fs.readdirSync(apilinks).forEach((fixture)=>{
 if(!fixture.endsWith('.js'))return;
-constfile=path.join(apilinks,fixture);
-
-constexpectedContent=fs.readFileSync(file+'on','utf8');
+constinput=path.join(apilinks,fixture);
 
-constoutput=execFileSync(
+constexpectedContent=fs.readFileSync(`${input}on`,'utf8');
+constoutputPath=path.join(tmpdir.path,`${fixture}on`);
+execFileSync(
 process.execPath,
-[script,file],
+[script,outputPath,input],
 {encoding: 'utf-8'}
 );
 
 constexpectedLinks=JSON.parse(expectedContent);
-constactualLinks=JSON.parse(output);
+constactualLinks=JSON.parse(fs.readFileSync(outputPath));
 
 for(const[k,v]ofObject.entries(expectedLinks)){
 assert.ok(kinactualLinks,`link not found: ${k}`);

tools/doc/apilinks.js

@@ -47,7 +47,9 @@ const tag = execSync(`git describe --contains ${hash}`).split('\n')[0] || hash;
 
 // Extract definitions from each file specified.
 constdefinition={};
-process.argv.slice(2).forEach((file)=>{
+constoutput=process.argv[2];
+constinputs=process.argv.slice(3);
+inputs.forEach((file)=>{
 constbasename=path.basename(file,'.js');
 
 // Parse source.
@@ -206,4 +208,4 @@ process.argv.slice(2).forEach((file) => {
 }
 });
 
-console.log(JSON.stringify(definition,null,2));
+fs.writeFileSync(output,JSON.stringify(definition,null,2),'utf8');

tools/doc/generate.js

@@ -49,9 +49,12 @@ args.forEach(function(arg) {
 }elseif(arg.startsWith('--output-directory=')){
 outputDir=arg.replace(/^--output-directory=/,'');
 }elseif(arg.startsWith('--apilinks=')){
-apilinks=JSON.parse(
-fs.readFileSync(arg.replace(/^--apilinks=/,''),'utf8')
-);
+constlinkFile=arg.replace(/^--apilinks=/,'');
+constdata=fs.readFileSync(linkFile,'utf8');
+if(!data.trim()){
+thrownewError(`${linkFile} is empty`);
+}
+apilinks=JSON.parse(data);
 }
 });