review

Author: flakey5

bin/cli.mjs

@@ -68,18 +68,14 @@ program
  */
 const { input, output, target = [], version, changelog } = program.opts();
 
-const { loadFiles, loadJsFiles } = createLoader();
+const { loadMarkdownFiles, loadJsFiles } = createLoader();
 const { parseApiDocs, parseJsSources } = createParser();
 
-const apiDocFiles = loadFiles(input);
+const apiDocFiles = loadMarkdownFiles(input);
 
 const parsedApiDocs = await parseApiDocs(apiDocFiles);
 
-const sourceFiles = loadJsFiles(
-  parsedApiDocs
-    .map(({ source_link_local }) => source_link_local)
-    .filter(path => path?.endsWith('.js'))
-);
+const sourceFiles = loadJsFiles(input);
 
 const parsedJsFiles = await parseJsSources(sourceFiles);
 

package-lock.json

@@ -31,6 +31,8 @@
   "dependencies": {
     "acorn": "^8.14.0",
     "commander": "^13.0.0",
+    "estree-util-visit": "^2.0.0",
+    "gitconfiglocal": "^2.1.0",
     "github-slugger": "^2.0.0",
     "glob": "^11.0.0",
     "hast-util-to-string": "^3.0.1",

package.json

@@ -0,0 +1,4 @@
+'use strict';
+
+// Checks if a string is a valid name for a constructor in JavaScript
+export const CONSTRUCTOR_EXPRESSION = /^[A-Z]/;

src/generators/api-links/constants.mjs

@@ -2,9 +2,13 @@
 
 import { basename, dirname, join } from 'node:path';
 import { writeFile } from 'node:fs/promises';
-import { getGitRepository, getGitTag } from '../../utils/git.mjs';
+import {
+  getBaseGitHubUrl,
+  getCurrentGitHash,
+} from './utils/getBaseGitHubUrl.mjs';
 import { extractExports } from './utils/extractExports.mjs';
 import { findDefinitions } from './utils/findDefinitions.mjs';
+import { checkIndirectReferences } from './utils/checkIndirectReferences.mjs';
 
 /**
  * This generator is responsible for mapping publicly accessible functions in
@@ -36,7 +40,7 @@ export default {
    */
   async generate(input, { output }) {
     /**
-     * @type {Record<string, string>}
+     * @type Record<string, string>
      */
     const definitions = {};
 
@@ -45,14 +49,25 @@ export default {
      */
     let baseGithubLink;
 
+    if (input.length > 0) {
+      const repositoryDirectory = dirname(input[0].path);
+
+      const repository = getBaseGitHubUrl(repositoryDirectory);
+
+      const tag = getCurrentGitHash(repositoryDirectory);
+
+      baseGithubLink = `${repository}/blob/${tag}`;
+    }
+
     input.forEach(program => {
       /**
        * Mapping of definitions to their line number
        * @type {Record<string, number>}
-       * @example { 'someclass.foo', 10 }
+       * @example { 'someclass.foo': 10 }
        */
       const nameToLineNumberMap = {};
 
+      // `http.js` -> `http`
       const programBasename = basename(program.path, '.js');
 
       const exports = extractExports(
@@ -63,19 +78,12 @@ export default {
 
       findDefinitions(program, programBasename, nameToLineNumberMap, exports);
 
-      if (!baseGithubLink) {
-        const directory = dirname(program.path);
-
-        const repository = getGitRepository(directory);
-
-        const tag = getGitTag(directory);
-
-        baseGithubLink = `https://github.com/${repository}/blob/${tag}`;
-      }
+      checkIndirectReferences(program, exports, nameToLineNumberMap);
 
       const githubLink =
         `${baseGithubLink}/lib/${programBasename}.js`.replaceAll('\\', '/');
 
+      // Add the exports we found in this program to our output
       Object.keys(nameToLineNumberMap).forEach(key => {
         const lineNumber = nameToLineNumberMap[key];
 

src/generators/api-links/index.mjs

@@ -1,4 +1,5 @@
 export interface ProgramExports {
   ctors: Array<string>;
   identifiers: Array<string>;
+  indirects: Record<string, string>;
 }

src/generators/api-links/types.d.ts

@@ -0,0 +1,25 @@
+import { visit } from 'estree-util-visit';
+
+/**
+ *
+ * @param program
+ * @param {import('../types.d.ts').ProgramExports} exports
+ * @param {Record<string, number>} nameToLineNumberMap
+ */
+export function checkIndirectReferences(program, exports, nameToLineNumberMap) {
+  if (Object.keys(exports.indirects).length === 0) {
+    return;
+  }
+
+  visit(program, node => {
+    if (!node.loc || node.type !== 'FunctionDeclaration') {
+      return;
+    }
+
+    const name = node.id.name;
+
+    if (name in exports.indirects) {
+      nameToLineNumberMap[exports.indirects[name]] = node.loc.start.line;
+    }
+  });
+}