chore: code review

Author: ovflowd

bin/cli.mjs

@@ -6,7 +6,8 @@ import { Command, Option } from 'commander';
 
 import commands from './commands/index.mjs';
 import { errorWrap } from './utils.mjs';
-import logger, { LogLevel } from '../src/logger/index.mjs';
+import { LogLevel } from '../src/logger/constants.mjs';
+import logger from '../src/logger/index.mjs';
 
 const logLevelOption = new Option('--log-level <level>', 'Log level')
   .choices(Object.keys(LogLevel))

bin/commands/generate.mjs

@@ -7,28 +7,14 @@ 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 { loadFromURL } from '../../src/utils/parser.mjs';
 
 const availableGenerators = Object.keys(publicGenerators);
 
 /**
- * @typedef {{
- * input: Array<string> | string;
- * ignore?: Array<string> | string;
- * target: Array<keyof publicGenerators>;
- * version: string;
- * changelog: string;
- * typeMap: string;
- * gitRef?: string;
- * threads?: number;
- * chunkSize?: number;
- * }} Options
- */
-
-/**
- * @type {import('../utils.mjs').Command}
+ * @type {import('./types').Command}
  */
 export default {
   description: 'Generate API docs',
@@ -60,7 +46,7 @@ export default {
     },
     threads: {
       flags: ['-p', '--threads <number>'],
-      desc: 'Number of worker threads to use (minimum: 2)',
+      desc: 'Number of threads to use (minimum: 1)',
       prompt: {
         type: 'text',
         message: 'How many threads to allow',
@@ -134,7 +120,20 @@ export default {
       },
     },
   },
+
   /**
+   * @typedef {Object} Options
+   * @property {Array<string>|string} input - Specifies the glob/path for input files.
+   * @property {Array<string>|string} [ignore] - Specifies the glob/path for ignoring files.
+   * @property {Array<keyof AvailableGenerators>} target - Specifies the generator target mode.
+   * @property {string} version - Specifies the target Node.js version.
+   * @property {string} changelog - Specifies the path to the Node.js CHANGELOG.md file.
+   * @property {string} typeMap - Specifies the path to the Node.js Type Map.
+   * @property {string} index - Specifies the path to the index document.
+   * @property {string} [gitRef] - Git ref/commit URL.
+   * @property {number} [threads] - Number of threads to allow.
+   * @property {number} [chunkSize] - Number of items to process per worker thread.
+   *
    * Handles the action for generating API docs
    * @param {Options} opts - The options to generate API docs.
    * @returns {Promise<void>}
@@ -144,25 +143,19 @@ export default {
 
     const { runGenerators } = createGenerator();
 
-    const releases = await parseChangelog(opts.changelog);
-
-    const typeMap = JSON.parse(await loadFromURL(opts.typeMap));
-
-    const index = opts.index && (await parseIndex(opts.index));
-
     logger.debug('Starting generation', { targets: opts.target });
 
     await runGenerators({
       generators: opts.target,
       input: opts.input,
       output: opts.output && resolve(opts.output),
       version: coerce(opts.version),
-      releases,
+      releases: await parseChangelog(opts.changelog),
       gitRef: opts.gitRef,
-      threads: Math.max(parseInt(opts.threads, 10), 2),
-      chunkSize: parseInt(opts.chunkSize, 10),
-      index,
-      typeMap,
+      threads: Math.max(parseInt(opts.threads, 10), 1),
+      chunkSize: Math.max(parseInt(opts.chunkSize, 10), 1),
+      index: await parseIndex(opts.index),
+      typeMap: await parseTypeMap(opts.typeMap),
     });
   },
 };

bin/commands/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Represents a command-line option for the CLI.
+ */
+export interface Option {
+  flags: string[];
+  desc: string;
+  prompt?: {
+    type: 'text' | 'confirm' | 'select' | 'multiselect';
+    message: string;
+    variadic?: boolean;
+    required?: boolean;
+    initialValue?: boolean;
+    options?: { label: string; value: string }[];
+  };
+}
+
+/**
+ * Represents a command-line subcommand
+ */
+export interface Command {
+  options: { [key: string]: Option };
+  name: string;
+  description: string;
+  action: Function;
+}

src/generators/ast-js/index.mjs

@@ -18,8 +18,9 @@ const { parseJsSource } = createJsParser();
  * so we're only parsing the Javascript sources when we need to.
  *
  * @typedef {unknown} Input
+ * @typedef {Array<JsProgram>} Output
  *
- * @type {GeneratorMetadata<Input, Array<JsProgram>>}
+ * @type {GeneratorMetadata<Input, Output>}
  */
 export default {
   name: 'ast-js',
@@ -34,22 +35,32 @@ export default {
    *
    * @param {string[]} inputSlice - Sliced input paths for this chunk
    * @param {number[]} itemIndices - Indices into the sliced array
-   * @returns {Promise<object[]>} Parsed JS AST objects for each file
+   * @returns {Promise<Output>} Parsed JS AST objects for each file
    */
   async processChunk(inputSlice, itemIndices) {
     const filePaths = itemIndices.map(idx => inputSlice[idx]);
 
-    const vfiles = await Promise.all(loadFiles(filePaths));
+    const vfilesPromises = loadFiles(filePaths);
 
-    return Promise.all(vfiles.map(parseJsSource));
+    const results = [];
+
+    for (const vfilePromise of vfilesPromises) {
+      const vfile = await vfilePromise;
+
+      const parsed = await parseJsSource(vfile);
+
+      results.push(parsed);
+    }
+
+    return results;
   },
 
   /**
    * Generates a JavaScript AST from the input files.
    *
    * @param {Input} _ - Unused (files loaded from input paths)
    * @param {Partial<GeneratorOptions>} options
-   * @returns {AsyncGenerator<Array<object>>}
+   * @returns {AsyncGenerator<Output>}
    */
   async *generate(_, { input = [], worker }) {
     const source = globSync(input).filter(path => extname(path) === '.js');

src/generators/ast/index.mjs

@@ -16,8 +16,9 @@ const remarkProcessor = getRemark();
  * It parallelizes the parsing across worker threads for better performance.
  *
  * @typedef {undefined} Input
+ * @typedef {Array<ParserOutput<import('mdast').Root>>} Output
  *
- * @type {GeneratorMetadata<Input, Array<ParserOutput<import('mdast').Root>>>}
+ * @type {GeneratorMetadata<Input, Output>}
  */
 export default {
   name: 'ast',
@@ -32,28 +33,33 @@ export default {
    *
    * @param {string[]} inputSlice - Sliced input paths for this chunk
    * @param {number[]} itemIndices - Indices into the sliced array
-   * @returns {Promise<Array<ParserOutput<import('mdast').Root>>>}
+   * @returns {Promise<Output>}
    */
   async processChunk(inputSlice, itemIndices) {
     const filePaths = itemIndices.map(idx => inputSlice[idx]);
 
-    const vfiles = await Promise.all(loadFiles(filePaths));
+    const vfilesPromises = loadFiles(filePaths);
 
-    return vfiles.map(vfile => {
-      const tree = remarkProcessor.parse(vfile);
+    const results = [];
 
-      const minimalVfile = { stem: vfile.stem, basename: vfile.basename };
+    for (const vfilePromise of vfilesPromises) {
+      const vfile = await vfilePromise;
 
-      return { file: minimalVfile, tree };
-    });
+      results.push({
+        tree: remarkProcessor.parse(vfile),
+        file: { stem: vfile.stem, basename: vfile.basename },
+      });
+    }
+
+    return results;
   },
 
   /**
    * Generates AST trees from markdown input files.
    *
    * @param {Input} _ - Unused (top-level generator)
    * @param {Partial<GeneratorOptions>} options
-   * @returns {AsyncGenerator<Array<ParserOutput<import('mdast').Root>>>}
+   * @returns {AsyncGenerator<Output>}
    */
   async *generate(_, { input = [], worker }) {
     const files = globSync(input).filter(path => extname(path) === '.md');

src/generators/jsx-ast/index.mjs

@@ -10,7 +10,9 @@ const remarkRecma = getRemarkRecma();
  * Generator for converting MDAST to JSX AST.
  *
  * @typedef {Array<ApiDocMetadataEntry>} Input
- * @type {GeneratorMetadata<Input, string>}
+ * @typedef {Array<import('./utils/buildContent.mjs').JSXContent>} Output
+ *
+ * @type {GeneratorMetadata<Input, Output>}
  */
 export default {
   name: 'jsx-ast',
@@ -30,11 +32,8 @@ export default {
    *
    * @param {Array<{head: ApiDocMetadataEntry, entries: Array<ApiDocMetadataEntry>}>} slicedInput - Pre-sliced module data
    * @param {number[]} itemIndices - Indices of items to process
-   * @param {object} options - Serializable options
-   * @param {Array<[string, string]>} options.docPages - Pre-computed doc pages for sidebar
-   * @param {Array<ApiDocReleaseEntry>} options.releases - Release information
-   * @param {import('semver').SemVer} options.version - Target Node.js version
-   * @returns {Promise<Array<import('estree-jsx').Program>>} JSX AST programs for each module
+   * @param {{ docPages: Array<[string, string]>, releases: Array<ApiDocReleaseEntry>, version: import('semver').SemVer }} options - Serializable options
+   * @returns {Promise<Output>} JSX AST programs for each module
    */
   async processChunk(
     slicedInput,
@@ -66,7 +65,6 @@ export default {
    *
    * @param {Input} input
    * @param {Partial<GeneratorOptions>} options
-   * @returns {AsyncGenerator<Array<string>>}
    */
   async *generate(input, { index, releases, version, worker }) {
     const groupedModules = groupNodesByModule(input);

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

@@ -10,23 +10,13 @@ import { replaceTemplateValues } from '../legacy-html/utils/replaceTemplateValue
 import tableOfContents from '../legacy-html/utils/tableOfContents.mjs';
 
 /**
- * @typedef {{
- * api: string;
- * added: string;
- * section: string;
- * version: string;
- * toc: string;
- * nav: string;
- * content: string;
- * }} TemplateValues
- *
  * This generator generates the legacy HTML pages of the legacy API docs
  * for retro-compatibility and while we are implementing the new 'react' and 'html' generators.
  *
  * This generator is a top-level generator, and it takes the raw AST tree of the API doc files
  * and generates the HTML files to the specified output directory from the configuration settings
  *
- * @typedef {Array<TemplateValues>} Input
+ * @typedef {Array<import('../legacy-html/types').TemplateValues>} Input
  *
  * @type {GeneratorMetadata<Input, string>}
  */

src/generators/legacy-html/index.mjs

@@ -22,15 +22,6 @@ const getHeading = name => ({ data: { depth: 1, name } });
 const remarkRehypeProcessor = getRemarkRehypeWithShiki();
 
 /**
- * @typedef {{
- * api: string;
- * added: string;
- * section: string;
- * version: string;
- * toc: string;
- * nav: string;
- * content: string;
- * }} TemplateValues
  *
  * This generator generates the legacy HTML pages of the legacy API docs
  * for retro-compatibility and while we are implementing the new 'react' and 'html' generators.
@@ -39,8 +30,9 @@ const remarkRehypeProcessor = getRemarkRehypeWithShiki();
  * and generates the HTML files to the specified output directory from the configuration settings
  *
  * @typedef {Array<ApiDocMetadataEntry>} Input
+ * @typedef {Array<import('./types').TemplateValues>} Output
  *
- * @type {GeneratorMetadata<Input, Array<TemplateValues>>}
+ * @type {GeneratorMetadata<Input, Output>}
  */
 export default {
   name: 'legacy-html',
@@ -59,10 +51,10 @@ export default {
    * Each item is pre-grouped {head, nodes, headNodes} - no need to
    * recompute groupNodesByModule for every chunk.
    *
-   * @param {Array<{head: ApiDocMetadataEntry, nodes: ApiDocMetadataEntry[], headNodes: ApiDocMetadataEntry[]}>} slicedInput - Pre-sliced module data
+   * @param {Array<{ head: ApiDocMetadataEntry, nodes: Array<ApiDocMetadataEntry>, headNodes: Array<ApiDocMetadataEntry> }> } slicedInput - Pre-sliced module data
    * @param {number[]} itemIndices - Indices into the sliced array
-   * @param {{version: SemVer, parsedSideNav: string}} deps - Dependencies passed from generate()
-   * @returns {Promise<TemplateValues[]>} Template objects for each processed module
+   * @param {{ version: SemVer, parsedSideNav: string }} deps - Dependencies passed from generate()
+   * @returns {Promise<Output>} Template objects for each processed module
    */
   async processChunk(slicedInput, itemIndices, { version, parsedSideNav }) {
     const results = [];
@@ -110,7 +102,7 @@ export default {
    * Generates the legacy version of the API docs in HTML
    * @param {Input} input
    * @param {Partial<GeneratorOptions>} options
-   * @returns {AsyncGenerator<Array<TemplateValues>>}
+   * @returns {AsyncGenerator<Output>}
    */
   async *generate(input, { index, releases, version, output, worker }) {
     const baseDir = import.meta.dirname;
@@ -134,19 +126,6 @@ export default {
       })
     );
 
-    // Create sliced input: each item contains head + its module's entries + headNodes reference
-    // This avoids sending all ~4900 entries to every worker and recomputing groupings
-    const slicedInput = headNodes.map(head => ({
-      head,
-      nodes: groupedModules.get(head.api),
-      headNodes,
-    }));
-
-    const deps = {
-      version,
-      parsedSideNav: String(parsedSideNav),
-    };
-
     if (output) {
       // Define the source folder for API docs assets
       const srcAssets = join(baseDir, 'assets');
@@ -161,12 +140,18 @@ export default {
       await safeCopy(srcAssets, assetsFolder);
     }
 
+    // Create sliced input: each item contains head + its module's entries + headNodes reference
+    // This avoids sending all ~4900 entries to every worker and recomputing groupings
+    const entries = headNodes.map(head => ({
+      head,
+      nodes: groupedModules.get(head.api),
+      headNodes,
+    }));
+
+    const deps = { version, parsedSideNav: String(parsedSideNav) };
+
     // Stream chunks as they complete - HTML files are written immediately
-    for await (const chunkResult of worker.stream(
-      slicedInput,
-      slicedInput,
-      deps
-    )) {
+    for await (const chunkResult of worker.stream(entries, entries, deps)) {
       // Write files for this chunk in the generate method (main thread)
       if (output) {
         for (const template of chunkResult) {

src/generators/legacy-html/types.d.ts

@@ -0,0 +1,9 @@
+export interface TemplateValues {
+  api: string;
+  added: string;
+  section: string;
+  version: string;
+  toc: string;
+  nav: string;
+  content: string;
+}