feat(cli): add a configuration file option

Author: avivkeller

bin/commands/generate.mjs

@@ -1,25 +1,44 @@
-import { cpus } from 'node:os';
-
 import { Command, Option } from 'commander';
-import { coerce } from 'semver';
 
-import { NODE_CHANGELOG_URL, NODE_VERSION } from '../../src/constants.mjs';
 import { publicGenerators } from '../../src/generators/index.mjs';
 import createGenerator from '../../src/generators.mjs';
-import logger from '../../src/logger/index.mjs';
-import { parseTypeMap } from '../../src/parsers/json.mjs';
-import { parseChangelog, parseIndex } from '../../src/parsers/markdown.mjs';
-import { DEFAULT_TYPE_MAP } from '../../src/utils/parser/constants.mjs';
+import { setConfig } from '../../src/utils/configuration/index.mjs';
 import { errorWrap } from '../utils.mjs';
 
+const { runGenerators } = createGenerator();
+
+/**
+ * @typedef {Object} CLIOptions
+ * @property {string[]} input
+ * @property {string[]} target
+ * @property {string[]} ignore
+ * @property {string} output
+ * @property {number} threads
+ * @property {number} chunkSize
+ * @property {string} version
+ * @property {string} changelog
+ * @property {string} gitRef
+ * @property {string} index
+ * @property {boolean} minify
+ * @property {string} typeMap
+ */
+
 export default new Command('generate')
   .description('Generate API docs')
+  .addOption(new Option('--config-file <path>', 'Config file'))
+
+  // Options that need to be converted into a configuration
   .addOption(
     new Option(
       '-i, --input <patterns...>',
       'Input file patterns (glob)'
     ).makeOptionMandatory()
   )
+  .addOption(
+    new Option('-t, --target <generator...>', 'Target generator(s)')
+      .makeOptionMandatory()
+      .choices(Object.keys(publicGenerators))
+  )
   .addOption(
     new Option('--ignore <patterns...>', 'Ignore file patterns (glob)')
   )
@@ -29,63 +48,23 @@ export default new Command('generate')
       '-p, --threads <number>',
       'Number of threads to use (minimum: 1)'
     )
-      .default(cpus().length)
-      .argParser(parseInt)
   )
   .addOption(
     new Option(
       '--chunk-size <number>',
       'Number of items to process per worker thread (minimum: 1)'
     )
-      .default(10)
-      .argParser(parseInt)
-  )
-  .addOption(
-    new Option('-v, --version <semver>', 'Target Node.js version').default(
-      NODE_VERSION
-    )
-  )
-  .addOption(
-    new Option('-c, --changelog <url>', 'Changelog URL or path').default(
-      NODE_CHANGELOG_URL
-    )
-  )
-  .addOption(
-    new Option('--git-ref', 'Git ref URL').default(
-      'https://github.com/nodejs/node/tree/HEAD'
-    )
-  )
-  .addOption(
-    new Option('-t, --target <generator...>', 'Target generator(s)')
-      .makeOptionMandatory()
-      .choices(Object.keys(publicGenerators))
   )
+  .addOption(new Option('-v, --version <semver>', 'Target Node.js version'))
+  .addOption(new Option('-c, --changelog <url>', 'Changelog URL or path'))
+  .addOption(new Option('--git-ref', 'Git ref URL'))
   .addOption(new Option('--index <url>', 'index.md URL or path'))
-  .addOption(
-    new Option('--type-map <url>', 'Type map URL or path').default(
-      DEFAULT_TYPE_MAP
-    )
-  )
+  .addOption(new Option('--minify', 'Minify?'))
+  .addOption(new Option('--type-map <url>', 'Type map URL or path'))
+
   .action(
     errorWrap(async opts => {
-      logger.debug('Starting doc-kit', opts);
-
-      const { runGenerators } = createGenerator();
-
-      logger.debug('Starting generation', { targets: opts.target });
-
-      await runGenerators({
-        generators: opts.target,
-        input: opts.input,
-        ignore: opts.ignore,
-        output: opts.output,
-        version: coerce(opts.version),
-        releases: await parseChangelog(opts.changelog),
-        gitRef: opts.gitRef,
-        threads: Math.max(opts.threads, 1),
-        chunkSize: Math.max(opts.chunkSize, 1),
-        index: await parseIndex(opts.index),
-        typeMap: await parseTypeMap(opts.typeMap),
-      });
+      const config = await setConfig(opts);
+      await runGenerators(config);
     })
   );

eslint.config.mjs

@@ -77,7 +77,6 @@ export default defineConfig([
           },
         },
       ],
-      'jsdoc/require-param': 'error',
     },
   },
   // Override rules for test files to disable JSDoc rules

src/constants.mjs

@@ -12,8 +12,6 @@ const generatorsLogger = logger.child('generators');
  * Creates a generator orchestration system that manages the execution of
  * documentation generators in dependency order, with support for parallel
  * processing and streaming results.
- *
- * @returns {{ runGenerators: (options: GeneratorOptions) => Promise<unknown[]> }}
  */
 const createGenerator = () => {
   /** @type {{ [key: string]: Promise<unknown> | AsyncGenerator }} */
@@ -48,9 +46,9 @@ const createGenerator = () => {
    * Schedules a generator and its dependencies for execution.
    *
    * @param {string} generatorName - Generator to schedule
-   * @param {GeneratorOptions} options - Runtime options
+   * @param {import('./utils/configuration/types').Configuration} configuration - Runtime options
    */
-  const scheduleGenerator = (generatorName, options) => {
+  const scheduleGenerator = (generatorName, configuration) => {
     if (generatorName in cachedGenerators) {
       return;
     }
@@ -59,7 +57,7 @@ const createGenerator = () => {
 
     // Schedule dependency first
     if (dependsOn && !(dependsOn in cachedGenerators)) {
-      scheduleGenerator(dependsOn, options);
+      scheduleGenerator(dependsOn, configuration);
     }
 
     generatorsLogger.debug(`Scheduling "${generatorName}"`, {
@@ -75,10 +73,10 @@ const createGenerator = () => {
 
       // Create parallel worker for streaming generators
       const worker = processChunk
-        ? createParallelWorker(generatorName, pool, options)
+        ? createParallelWorker(generatorName, pool, configuration)
         : null;
 
-      const result = await generate(dependencyInput, { ...options, worker });
+      const result = await generate(dependencyInput, worker);
 
       // For streaming generators, "Completed" is logged when collection finishes
       // (in streamingCache.getOrCollect), not here when the generator returns
@@ -93,11 +91,11 @@ const createGenerator = () => {
   /**
    * Runs all requested generators with their dependencies.
    *
-   * @param {GeneratorOptions} options - Runtime options
+   * @param {import('./utils/configuration/types').Configuration} options - Runtime options
    * @returns {Promise<unknown[]>} Results of all requested generators
    */
-  const runGenerators = async options => {
-    const { generators, threads } = options;
+  const runGenerators = async configuration => {
+    const { target: generators, threads } = configuration;
 
     generatorsLogger.debug(`Starting pipeline`, {
       generators: generators.join(', '),
@@ -109,7 +107,7 @@ const createGenerator = () => {
 
     // Schedule all generators
     for (const name of generators) {
-      scheduleGenerator(name, options);
+      scheduleGenerator(name, configuration);
     }
 
     // Start all collections in parallel (don't await sequentially)

src/generators.mjs

@@ -12,15 +12,14 @@ import {
   isBuildableSection,
   normalizeSectionName,
 } from './utils/section.mjs';
+import getConfig from '../../utils/configuration/index.mjs';
 
 /**
  * This generator generates a file list from code blocks extracted from
  * `doc/api/addons.md` to facilitate C++ compilation and JavaScript runtime
  * validations.
  *
- * @typedef {Array<ApiDocMetadataEntry>} Input
- *
- * @type {GeneratorMetadata<Input, string>}
+ * @type {import('./types').Generator}
  */
 export default {
   name: 'addon-verify',
@@ -34,11 +33,10 @@ export default {
 
   /**
    * Generates a file list from code blocks.
-   *
-   * @param {Input} input
-   * @param {Partial<GeneratorOptions>} options
    */
-  async generate(input, { output }) {
+  async generate(input) {
+    const { 'addon-verify': config } = getConfig();
+
     const sectionsCodeBlocks = input.reduce((addons, node) => {
       const sectionName = node.heading.data.name;
 
@@ -72,19 +70,19 @@ export default {
         .flatMap(async ([sectionName, codeBlocks], index) => {
           const files = generateFileList(codeBlocks);
 
-          if (output) {
+          if (config.output) {
             const normalizedSectionName = normalizeSectionName(sectionName);
 
             const folderName = generateSectionFolderName(
               normalizedSectionName,
               index
             );
 
-            await mkdir(join(output, folderName), { recursive: true });
+            await mkdir(join(config.output, folderName), { recursive: true });
 
             for (const file of files) {
               await writeFile(
-                join(output, folderName, file.name),
+                join(config.output, folderName, file.name),
                 file.content
               );
             }

src/generators/addon-verify/index.mjs

@@ -0,0 +1,4 @@
+export type Generator = GeneratorMetadata<
+  {},
+  Generate<Array<ApiDocMetadataEntry>, Promise<Record<string, string>>>
+>;

src/generators/addon-verify/types.d.ts

@@ -6,6 +6,11 @@ import { basename, join } from 'node:path';
 import { checkIndirectReferences } from './utils/checkIndirectReferences.mjs';
 import { extractExports } from './utils/extractExports.mjs';
 import { findDefinitions } from './utils/findDefinitions.mjs';
+import getConfig from '../../utils/configuration/index.mjs';
+import {
+  GITHUB_BLOB_URL,
+  populate,
+} from '../../utils/configuration/templates.mjs';
 
 /**
  * This generator is responsible for mapping publicly accessible functions in
@@ -15,9 +20,7 @@ import { findDefinitions } from './utils/findDefinitions.mjs';
  * source files. It outputs a `apilinks.json` file into the specified output
  * directory.
  *
- * @typedef {Array<JsProgram>} Input
- *
- * @type {GeneratorMetadata<Input, Record<string, string>>}
+ * @type {import('./types').Generator}
  */
 export default {
   name: 'api-links',
@@ -33,11 +36,9 @@ export default {
 
   /**
    * Generates the `apilinks.json` file.
-   *
-   * @param {Input} input
-   * @param {Partial<GeneratorOptions>} options
    */
-  async generate(input, { output, gitRef }) {
+  async generate(input) {
+    const { 'api-links': config } = getConfig();
     /**
      * @type Record<string, string>
      */
@@ -61,7 +62,7 @@ export default {
 
       checkIndirectReferences(program, exports, nameToLineNumberMap);
 
-      const fullGitUrl = `${gitRef}/lib/${baseName}.js`;
+      const fullGitUrl = `${populate(GITHUB_BLOB_URL)}/lib/${baseName}.js`;
 
       // Add the exports we found in this program to our output
       Object.keys(nameToLineNumberMap).forEach(key => {
@@ -71,10 +72,15 @@ export default {
       });
     });
 
-    if (output) {
-      const out = join(output, 'apilinks.json');
+    if (config.output) {
+      const out = join(config.output, 'apilinks.json');
 
-      await writeFile(out, JSON.stringify(definitions));
+      await writeFile(
+        out,
+        config.minify
+          ? JSON.stringify(definitions)
+          : JSON.stringify(definitions, null, 2)
+      );
     }
 
     return definitions;

src/generators/api-links/index.mjs

@@ -3,3 +3,8 @@ export interface ProgramExports {
   identifiers: Array<string>;
   indirects: Record<string, string>;
 }
+
+export type Generator = GeneratorMetadata<
+  {},
+  Generate<undefined, Promise<Record<string, string>>>
+>;