Skip to content

Commit a5bccc2

Browse files
joyeecheungMylesBorins
authored andcommitted
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>
1 parent 4561e2c commit a5bccc2

File tree

4 files changed

+25
-17
lines changed

4 files changed

+25
-17
lines changed

Makefile

+5-5
Original file line numberDiff line numberDiff line change
@@ -692,16 +692,16 @@ out/doc/api/assets/%: doc/api_assets/% out/doc/api/assets
692692

693693
run-npm-ci = $(PWD)/$(NPM) ci
694694

695+
LINK_DATA = out/doc/apilinks.json
695696
gen-api = tools/doc/generate.js --node-version=$(FULLVERSION) \
696-
--apilinks=out/apilinks.json $< --output-directory=out/doc/api
697-
gen-apilink = tools/doc/apilinks.js $(wildcard lib/*.js) > $@
697+
--apilinks=$(LINK_DATA) $< --output-directory=out/doc/api
698+
gen-apilink = tools/doc/apilinks.js $(LINK_DATA) $(wildcard lib/*.js)
698699

699-
out/apilinks.json: $(wildcard lib/*.js) tools/doc/apilinks.js
700+
$(LINK_DATA): $(wildcard lib/*.js) tools/doc/apilinks.js
700701
$(call available-node, $(gen-apilink))
701702

702703
out/doc/api/%.json out/doc/api/%.html: doc/api/%.md tools/doc/generate.js \
703-
tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js | \
704-
out/apilinks.json
704+
tools/doc/html.js tools/doc/json.js tools/doc/apilinks.js | $(LINK_DATA)
705705
$(call available-node, $(gen-api))
706706

707707
out/doc/api/all.html: $(apidocs_html) tools/doc/allhtml.js \

test/doctool/test-apilinks.js

+10-7
Original file line numberDiff line numberDiff line change
@@ -2,28 +2,31 @@
22

33
require('../common');
44
const fixtures = require('../common/fixtures');
5+
const tmpdir = require('../common/tmpdir');
56
const fs = require('fs');
67
const assert = require('assert');
78
const path = require('path');
89
const { execFileSync } = require('child_process');
910

1011
const script = path.join(__dirname, '..', '..', 'tools', 'doc', 'apilinks.js');
11-
1212
const apilinks = fixtures.path('apilinks');
13+
14+
tmpdir.refresh();
15+
1316
fs.readdirSync(apilinks).forEach((fixture) => {
1417
if (!fixture.endsWith('.js')) return;
15-
const file = path.join(apilinks, fixture);
16-
17-
const expectedContent = fs.readFileSync(file + 'on', 'utf8');
18+
const input = path.join(apilinks, fixture);
1819

19-
const output = execFileSync(
20+
const expectedContent = fs.readFileSync(`${input}on`, 'utf8');
21+
const outputPath = path.join(tmpdir.path, `${fixture}on`);
22+
execFileSync(
2023
process.execPath,
21-
[script, file],
24+
[script, outputPath, input],
2225
{ encoding: 'utf-8' }
2326
);
2427

2528
const expectedLinks = JSON.parse(expectedContent);
26-
const actualLinks = JSON.parse(output);
29+
const actualLinks = JSON.parse(fs.readFileSync(outputPath));
2730

2831
for (const [k, v] of Object.entries(expectedLinks)) {
2932
assert.ok(k in actualLinks, `link not found: ${k}`);

tools/doc/apilinks.js

+4-2
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@ const tag = execSync(`git describe --contains ${hash}`).split('\n')[0] || hash;
4747

4848
// Extract definitions from each file specified.
4949
const definition = {};
50-
process.argv.slice(2).forEach((file) => {
50+
const output = process.argv[2];
51+
const inputs = process.argv.slice(3);
52+
inputs.forEach((file) => {
5153
const basename = path.basename(file, '.js');
5254

5355
// Parse source.
@@ -206,4 +208,4 @@ process.argv.slice(2).forEach((file) => {
206208
}
207209
});
208210

209-
console.log(JSON.stringify(definition, null, 2));
211+
fs.writeFileSync(output, JSON.stringify(definition, null, 2), 'utf8');

tools/doc/generate.js

+6-3
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,12 @@ args.forEach(function(arg) {
4949
} else if (arg.startsWith('--output-directory=')) {
5050
outputDir = arg.replace(/^--output-directory=/, '');
5151
} else if (arg.startsWith('--apilinks=')) {
52-
apilinks = JSON.parse(
53-
fs.readFileSync(arg.replace(/^--apilinks=/, ''), 'utf8')
54-
);
52+
const linkFile = arg.replace(/^--apilinks=/, '');
53+
const data = fs.readFileSync(linkFile, 'utf8');
54+
if (!data.trim()) {
55+
throw new Error(`${linkFile} is empty`);
56+
}
57+
apilinks = JSON.parse(data);
5558
}
5659
});
5760

0 commit comments

Comments
 (0)