feat: use git only when requested

Author: ovflowd

README.md

@@ -36,10 +36,16 @@ CLI tool to generate API documentation of a Node.js project.
 
 Options:
   -i, --input [patterns...]  Specify input file patterns using glob syntax
-  --ignore [patterns...]     Specify files to be ignored from the input using glob syntax
+  --ignore [patterns...]     Specify which input files to ignore using glob syntax
   -o, --output <path>        Specify the relative or absolute output directory
-  -v, --version <semver>     Specify the target version of Node.js, semver compliant (default: "v22.6.0")
-  -c, --changelog <url>      Specify the path (file: or https://) to the CHANGELOG.md file (default: "https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md")
-  -t, --target [mode...]     Set the processing target modes (choices: "json-simple", "legacy-html", "legacy-html-all", "man-page", "legacy-json", "legacy-json-all", "addon-verify", "api-links", "orama-db")
+  -v, --version <semver>     Specify the target version of Node.js, semver compliant (default: "v22.11.0")
+  -c, --changelog <url>      Specify the path (file: or https://) to the CHANGELOG.md file (default:
+                             "https://raw.githubusercontent.com/nodejs/node/HEAD/CHANGELOG.md")
+  -t, --target [mode...]     Set the processing target modes (choices: "json-simple", "legacy-html", "legacy-html-all",
+                             "man-page", "legacy-json", "legacy-json-all", "addon-verify", "api-links", "orama-db")
+  --disable-rule [rule...]   Disable a specific linter rule (choices: "invalid-change-version",
+                             "missing-change-version", "missing-introduced-in", default: [])
+  --lint-dry-run             Run linter in dry-run mode (default: false)
+  -r, --reporter [reporter]  Specify the linter reporter (choices: "console", "github", default: "console")
   -h, --help                 display help for command
 ```

bin/cli.mjs

@@ -67,6 +67,9 @@ program
   .addOption(
     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)
+  )
   .addOption(
     new Option('-r, --reporter [reporter]', 'Specify the linter reporter')
       .choices(Object.keys(reporters))
@@ -85,6 +88,7 @@ program
  * @property {string} changelog Specifies the path to the Node.js CHANGELOG.md file.
  * @property {string[]} disableRule Specifies the linter rules to disable.
  * @property {boolean} lintDryRun Specifies whether the linter should run in dry-run mode.
+ * @property {boolean} useGit Specifies whether the parser should execute optional git commands. (Should only be used within a git repo)
  * @property {keyof reporters} reporter Specifies the linter reporter.
  *
  * @name ProgramOptions
@@ -100,6 +104,7 @@ const {
   changelog,
   disableRule,
   lintDryRun,
+  useGit,
   reporter,
 } = program.opts();
 
@@ -117,6 +122,7 @@ const { runGenerators } = createGenerator(parsedApiDocs);
 // Retrieves Node.js release metadata from a given Node.js version and CHANGELOG.md file
 const { getAllMajors } = createNodeReleases(changelog);
 
+// Runs the Linter on the parsed API docs
 linter.lintAll(parsedApiDocs);
 
 if (target && output) {
@@ -131,9 +137,13 @@ if (target && output) {
     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,
   });
 }
 
+// Reports Lint Content
 linter.report(reporter);
 
 exit(Number(linter.hasError()));

src/constants.mjs

@@ -7,6 +7,9 @@ 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.mjs

@@ -13,8 +13,8 @@ const availableGenerators = {
 };
 
 /**
- * @typedef {{ ast: import('./generators/types.d.ts').GeneratorMetadata<ApiDocMetadataEntry, ApiDocMetadataEntry>}} AstGenerator The AST "generator" is a facade for the AST tree and it isn't really a generator
- * @typedef {import('./generators/types.d.ts').AvailableGenerators & AstGenerator} AllGenerators A complete set of the available generators, including the AST one
+ * @typedef {{ ast: GeneratorMetadata<ApiDocMetadataEntry, ApiDocMetadataEntry>}} AstGenerator The AST "generator" is a facade for the AST tree and it isn't really a generator
+ * @typedef {AvailableGenerators & AstGenerator} AllGenerators A complete set of the available generators, including the AST one
  * @param markdownInput
  * @param jsInput
  *
@@ -41,14 +41,12 @@ const createGenerator = markdownInput => {
    *
    * @type {{ [K in keyof AllGenerators]: ReturnType<AllGenerators[K]['generate']> }}
    */
-  const cachedGenerators = {
-    ast: Promise.resolve(markdownInput),
-  };
+  const cachedGenerators = { ast: Promise.resolve(markdownInput) };
 
   /**
    * Runs the Generator engine with the provided top-level input and the given generator options
    *
-   * @param {import('./generators/types.d.ts').GeneratorOptions} options The options for the generator runtime
+   * @param {GeneratorOptions} options The options for the generator runtime
    */
   const runGenerators = async ({ generators, ...extra }) => {
     // Note that this method is blocking, and will only execute one generator per-time

src/generators/addon-verify/index.mjs

@@ -20,7 +20,7 @@ import {
  *
  * @typedef {Array<ApiDocMetadataEntry>} Input
  *
- * @type {import('../types.d.ts').GeneratorMetadata<Input, string>}
+ * @type {GeneratorMetadata<Input, string>}
  */
 export default {
   name: 'addon-verify',

src/generators/api-links/index.mjs

@@ -9,6 +9,7 @@ import {
 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
@@ -20,7 +21,7 @@ import { checkIndirectReferences } from './utils/checkIndirectReferences.mjs';
  *
  * @typedef {Array<JsProgram>} Input
  *
- * @type {import('../types.d.ts').GeneratorMetadata<Input, Record<string, string>>}
+ * @type {GeneratorMetadata<Input, Record<string, string>>}
  */
 export default {
   name: 'api-links',
@@ -40,7 +41,7 @@ export default {
    * @param {Input} input
    * @param {Partial<GeneratorOptions>} options
    */
-  async generate(input, { output }) {
+  async generate(input, { output, useGit }) {
     /**
      * @type Record<string, string>
      */
@@ -54,9 +55,11 @@ export default {
     if (input.length > 0) {
       const repositoryDirectory = dirname(input[0].path);
 
-      const repository = getBaseGitHubUrl(repositoryDirectory);
+      const repository = useGit
+        ? getBaseGitHubUrl(repositoryDirectory)
+        : DOC_NODE_REPO_URL;
 
-      const tag = getCurrentGitHash(repositoryDirectory);
+      const tag = useGit ? getCurrentGitHash(repositoryDirectory) : 'HEAD';
 
       baseGithubLink = `${repository}/blob/${tag}`;
     }

src/generators/ast-js/index.mjs

@@ -11,7 +11,7 @@ import createJsParser from '../../parsers/javascript.mjs';
  *
  * @typedef {unknown} Input
  *
- * @type {import('../types.d.ts').GeneratorMetadata<Input, Array<JsProgram>>}
+ * @type {GeneratorMetadata<Input, Array<JsProgram>>}
  */
 export default {
   name: 'ast-js',

src/generators/json-simple/index.mjs

@@ -17,7 +17,7 @@ import { getRemark } from '../../utils/remark.mjs';
  *
  * @typedef {Array<ApiDocMetadataEntry>} Input
  *
- * @type {import('../types.d.ts').GeneratorMetadata<Input, string>}
+ * @type {GeneratorMetadata<Input, string>}
  */
 export default {
   name: 'json-simple',

src/generators/legacy-html-all/index.mjs

@@ -29,7 +29,7 @@ import { getRemarkRehype } from '../../utils/remark.mjs';
  *
  * @typedef {Array<TemplateValues>} Input
  *
- * @type {import('../types.d.ts').GeneratorMetadata<Input, string>}
+ * @type {GeneratorMetadata<Input, string>}
  */
 export default {
   name: 'legacy-html-all',

src/generators/legacy-html/index.mjs

@@ -31,7 +31,7 @@ import { getRemarkRehype } from '../../utils/remark.mjs';
  *
  * @typedef {Array<ApiDocMetadataEntry>} Input
  *
- * @type {import('../types.d.ts').GeneratorMetadata<Input, Array<TemplateValues>>}
+ * @type {GeneratorMetadata<Input, Array<TemplateValues>>}
  */
 export default {
   name: 'legacy-html',