tools: Include links to source code in documentation

Parse source code using acorn; extracting exports.  When producing
documentation, match exports to headers.  When a match is found, add a [src]
link.

This first commit handles simple exported classes and functions, and does so
without requiring any changes to the source code or markdown.  Subsequent
commits will attempt to match more headers, and some of these changes are
likely to require changes to the source code and/or markdown.

PR-URL: https://github.com/nodejs/node/pull/22405
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

2 files changed, 40 insertions, 1 deletions

diff --git a/test/doctool/test-apilinks.js b/test/doctool/test-apilinks.js
new file mode 100644
index 0000000000..e53c81a08a
--- /dev/null
+++ b/test/doctool/test-apilinks.js
@@ -0,0 +1,39 @@
+'use strict';
+
+require('../common');
+const fixtures = require('../common/fixtures');
+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');
+fs.readdirSync(apilinks).forEach((fixture) => {
+  if (!fixture.endsWith('.js')) return;
+  const file = path.join(apilinks, fixture);
+
+  const expectedContent = fs.readFileSync(file + 'on', 'utf8');
+
+  const output = execFileSync(
+    process.execPath,
+    [script, file],
+    { encoding: 'utf-8' }
+  );
+
+  const expectedLinks = JSON.parse(expectedContent);
+  const actualLinks = JSON.parse(output);
+
+  for (const [k, v] of Object.entries(expectedLinks)) {
+    assert.ok(k in actualLinks, `link not found: ${k}`);
+    assert.ok(actualLinks[k].endsWith('/' + v),
+              `link ${actualLinks[k]} expected to end with ${v}`);
+    delete actualLinks[k];
+  }
+
+  assert.strictEqual(
+    Object.keys(actualLinks).length, 0,
+    `unexpected links returned ${JSON.stringify(actualLinks)}`
+  );
+});
diff --git a/test/doctool/test-doctool-html.js b/test/doctool/test-doctool-html.js
index 8c05ea6a0b..2fcb8315af 100644
--- a/test/doctool/test-doctool-html.js
+++ b/test/doctool/test-doctool-html.js
@@ -28,7 +28,7 @@ function toHTML({ input, filename, nodeVersion, analytics }, cb) {
     .use(html.firstHeader)
     .use(html.preprocessText)
     .use(html.preprocessElements, { filename })
-    .use(html.buildToc, { filename })
+    .use(html.buildToc, { filename, apilinks: {} })
     .use(remark2rehype, { allowDangerousHTML: true })
     .use(raw)
     .use(htmlStringify)