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>

Makefile

@@ -647,16 +647,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/%.json out/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');
 const fixtures = require('../common/fixtures');
+const tmpdir = require('../common/tmpdir');
 const fs = require('fs');
 const assert = require('assert');
 const path = require('path');
 const { execFileSync } = require('child_process');
 
 const script = path.join(__dirname, '..', '..', 'tools', 'doc', 'apilinks.js');
-
 const apilinks = fixtures.path('apilinks');
+
+tmpdir.refresh();
+
 fs.readdirSync(apilinks).forEach((fixture) => {
   if (!fixture.endsWith('.js')) return;
-  const file = path.join(apilinks, fixture);
-
-  const expectedContent = fs.readFileSync(file + 'on', 'utf8');
+  const input = path.join(apilinks, fixture);
 
-  const output = execFileSync(
+  const expectedContent = fs.readFileSync(`${input}on`, 'utf8');
+  const outputPath = path.join(tmpdir.path, `${fixture}on`);
+  execFileSync(
     process.execPath,
-    [script, file],
+    [script, outputPath, input],
     { encoding: 'utf-8' }
   );
 
   const expectedLinks = JSON.parse(expectedContent);
-  const actualLinks = JSON.parse(output);
+  const actualLinks = JSON.parse(fs.readFileSync(outputPath));
 
   for (const [k, v] of Object.entries(expectedLinks)) {
     assert.ok(k in actualLinks, `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.
 const definition = {};
-process.argv.slice(2).forEach((file) => {
+const output = process.argv[2];
+const inputs = process.argv.slice(3);
+inputs.forEach((file) => {
   const basename = 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) {
   } else if (arg.startsWith('--output-directory=')) {
     outputDir = arg.replace(/^--output-directory=/, '');
   } else if (arg.startsWith('--apilinks=')) {
-    apilinks = JSON.parse(
-      fs.readFileSync(arg.replace(/^--apilinks=/, ''), 'utf8')
-    );
+    const linkFile = arg.replace(/^--apilinks=/, '');
+    const data = fs.readFileSync(linkFile, 'utf8');
+    if (!data.trim()) {
+      throw new Error(`${linkFile} is empty`);
+    }
+    apilinks = JSON.parse(data);
   }
 });