chore: provide ref from string

bin/cli.mjs

@@ -4,17 +4,18 @@ import { resolve } from 'node:path';
 import { argv, exit } from 'node:process';
 
 import { Command, Option } from 'commander';
+import parseGitUrl from 'git-url-parse';
 
 import { coerce } from 'semver';
 import { DOC_NODE_CHANGELOG_URL, DOC_NODE_VERSION } from '../src/constants.mjs';
 import createGenerator from '../src/generators.mjs';
 import generators from '../src/generators/index.mjs';
-import createMarkdownLoader from '../src/loaders/markdown.mjs';
-import createMarkdownParser from '../src/parsers/markdown.mjs';
-import createNodeReleases from '../src/releases.mjs';
 import createLinter from '../src/linter/index.mjs';
 import reporters from '../src/linter/reporters/index.mjs';
 import rules from '../src/linter/rules/index.mjs';
+import createMarkdownLoader from '../src/loaders/markdown.mjs';
+import createMarkdownParser from '../src/parsers/markdown.mjs';
+import createNodeReleases from '../src/releases.mjs';
 
 const availableGenerators = Object.keys(generators);
 
@@ -68,7 +69,9 @@ program
     new Option('--lint-dry-run', 'Run linter in dry-run mode').default(false)
   )
   .addOption(
-    new Option('--use-git', 'Run git commands when needed').default(false)
+    new Option('--git-ref', 'The current Node.js git ref').default(
+      'https://github.com/nodejs/node/tree/HEAD'
+    )
   )
   .addOption(
     new Option('-r, --reporter [reporter]', 'Specify the linter reporter')
@@ -104,7 +107,7 @@ const {
   changelog,
   disableRule,
   lintDryRun,
-  useGit,
+  gitRef,
   reporter,
 } = program.opts();
 
@@ -113,6 +116,8 @@ const linter = createLinter(lintDryRun, disableRule);
 const { loadFiles } = createMarkdownLoader();
 const { parseApiDocs } = createMarkdownParser();
 
+const parsedGitRef = parseGitUrl(gitRef);
+
 const apiDocFiles = await loadFiles(input, ignore);
 
 const parsedApiDocs = await parseApiDocs(apiDocFiles);
@@ -125,21 +130,21 @@ const { getAllMajors } = createNodeReleases(changelog);
 // Runs the Linter on the parsed API docs
 linter.lintAll(parsedApiDocs);
 
-if (target && output) {
+if (target) {
   await runGenerators({
     // A list of target modes for the API docs parser
     generators: target,
     // Resolved `input` to be used
     input: input,
     // Resolved `output` path to be used
-    output: resolve(output),
+    output: output && resolve(output),
     // Resolved SemVer of current Node.js version
     version: coerce(version),
     // A list of all Node.js major versions with LTS status
     releases: await getAllMajors(),
-    // If it should run git commands when needed
-    // (should only be used within a git repo)
-    useGit,
+    // The current Node.js's git ref to be used within API
+    // doc generation. This is used only to stamp some files.
+    gitRef: parsedGitRef,
   });
 }
 

package.json

@@ -41,6 +41,7 @@
     "commander": "^13.1.0",
     "dedent": "^1.5.3",
     "estree-util-visit": "^2.0.0",
+    "git-url-parse": "^16.0.1",
     "github-slugger": "^2.0.0",
     "hast-util-to-string": "^3.0.1",
     "hastscript": "^9.0.1",

src/constants.mjs

@@ -7,9 +7,6 @@ export const DOC_NODE_VERSION = process.version;
 export const DOC_NODE_CHANGELOG_URL =
   'https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md';
 
-// The base URL for the Node.js runtime GitHub repository
-export const DOC_NODE_REPO_URL = 'https://github.com/nodejs/node';
-
 // This is the Node.js Base URL for viewing a file within GitHub UI
 export const DOC_NODE_BLOB_BASE_URL =
   'https://github.com/nodejs/node/blob/HEAD/';

src/generators/api-links/index.mjs

@@ -1,15 +1,10 @@
 'use strict';
 
-import { basename, dirname, join } from 'node:path';
+import { basename, join } from 'node:path';
 import { writeFile } from 'node:fs/promises';
-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';
-import { DOC_NODE_REPO_URL } from '../../constants.mjs';
 
 /**
  * This generator is responsible for mapping publicly accessible functions in
@@ -41,58 +36,39 @@ export default {
    * @param {Input} input
    * @param {Partial<GeneratorOptions>} options
    */
-  async generate(input, { output, useGit }) {
+  async generate(input, { output, gitRef }) {
     /**
      * @type Record<string, string>
      */
     const definitions = {};
 
-    /**
-     * @type {string}
-     */
-    let baseGithubLink;
-
-    if (input.length > 0) {
-      const repositoryDirectory = dirname(input[0].path);
-
-      const repository = useGit
-        ? getBaseGitHubUrl(repositoryDirectory)
-        : DOC_NODE_REPO_URL;
-
-      const tag = useGit ? getCurrentGitHash(repositoryDirectory) : 'HEAD';
-
-      baseGithubLink = `${repository}/blob/${tag}`;
-    }
+    const gitBaseUrl = `https://${gitRef.host}/${gitRef.full_name}/blob/${gitRef.commit ?? 'HEAD'}`;
 
     input.forEach(program => {
       /**
        * Mapping of definitions to their line number
+       *
        * @type {Record<string, number>}
        * @example { 'someclass.foo': 10 }
        */
       const nameToLineNumberMap = {};
 
       // `http.js` -> `http`
-      const programBasename = basename(program.path, '.js');
+      const baseName = basename(program.path, '.js');
 
-      const exports = extractExports(
-        program,
-        programBasename,
-        nameToLineNumberMap
-      );
+      const exports = extractExports(program, baseName, nameToLineNumberMap);
 
-      findDefinitions(program, programBasename, nameToLineNumberMap, exports);
+      findDefinitions(program, baseName, nameToLineNumberMap, exports);
 
       checkIndirectReferences(program, exports, nameToLineNumberMap);
 
-      const githubLink =
-        `${baseGithubLink}/lib/${programBasename}.js`.replaceAll('\\', '/');
+      const fullGitUrl = `${gitBaseUrl}/lib/${baseName}.js`;
 
       // Add the exports we found in this program to our output
       Object.keys(nameToLineNumberMap).forEach(key => {
         const lineNumber = nameToLineNumberMap[key];
 
-        definitions[key] = `${githubLink}#L${lineNumber}`;
+        definitions[key] = `${fullGitUrl}#L${lineNumber}`;
       });
     });
 

src/generators/types.d.ts

@@ -1,6 +1,7 @@
+import type { GitUrl } from 'git-url-parse';
 import type { SemVer } from 'semver';
-import type availableGenerators from './index.mjs';
 import type { ApiDocReleaseEntry } from '../types';
+import type availableGenerators from './index.mjs';
 
 declare global {
   // All available generators as an inferable type, to allow Generator interfaces
@@ -31,8 +32,8 @@ declare global {
     // A list of all Node.js major versions and their respective release information
     releases: Array<ApiDocReleaseEntry>;
 
-    // Wether to use `git` commands while running the generator
-    useGit: boolean;
+    // The current Node.js's git ref to be used within the API doc generation
+    gitRef: GitUrl;
   }
 
   export interface GeneratorMetadata<I extends any, O extends any> {