chore: self review and code review

Author: ovflowd

src/generators.mjs

@@ -37,21 +37,15 @@ const createGenerator = input => {
    *
    * @param {GeneratorOptions} options The options for the generator runtime
    */
-  const runGenerators = async ({
-    generators,
-    threads,
-    chunkSize,
-    ...extra
-  }) => {
+  const runGenerators = async options => {
+    const { generators, threads } = options;
+
     // WorkerPool for running full generators in worker threads
     const generatorPool = new WorkerPool('./generator-worker.mjs', threads);
 
     // WorkerPool for chunk-level parallelization within generators
     const chunkPool = new WorkerPool('./chunk-worker.mjs', threads);
 
-    // Options including threading config
-    const threadingOptions = { threads, chunkSize };
-
     // Note that this method is blocking, and will only execute one generator per-time
     // but it ensures all dependencies are resolved, and that multiple bottom-level generators
     // can reuse the already parsed content from the top-level/dependency generators
@@ -61,34 +55,21 @@ const createGenerator = input => {
       // If the generator dependency has not yet been resolved, we resolve
       // the dependency first before running the current generator
       if (dependsOn && dependsOn in cachedGenerators === false) {
-        await runGenerators({
-          ...extra,
-          ...threadingOptions,
-          generators: [dependsOn],
-        });
+        await runGenerators({ ...options, generators: [dependsOn] });
       }
 
       // Ensures that the dependency output gets resolved before we run the current
       // generator with its dependency output as the input
       const input = await cachedGenerators[dependsOn];
 
       // Create a ParallelWorker for this generator to use for item-level parallelization
-      const worker = createParallelWorker(generatorName, chunkPool, {
-        ...extra,
-        ...threadingOptions,
-      });
-
-      // Generator options with worker instance
-      const generatorOptions = { ...extra, ...threadingOptions, worker };
-
-      // Worker options for the worker thread
-      const workerOptions = { ...extra, ...threadingOptions };
+      const worker = createParallelWorker(generatorName, chunkPool, options);
 
       // Adds the current generator execution Promise to the cache
       cachedGenerators[generatorName] =
         threads < 2
-          ? generate(input, generatorOptions) // Run in main thread
-          : generatorPool.run({ generatorName, input, options: workerOptions }); // Offload to worker thread
+          ? generate(input, { ...options, worker })
+          : generatorPool.run({ generatorName, input, options });
     }
 
     // Returns the value of the last generator of the current pipeline

src/generators/ast-js/index.mjs

@@ -24,15 +24,12 @@ export default {
 
   /**
    * Process a chunk of JavaScript files in a worker thread.
-   * Called by chunk-worker.mjs for parallel processing.
-   *
-   * @param {unknown} _ - Unused (we use options.input instead)
-   * @param {number[]} itemIndices - Indices of source files to process
+   * @param {unknown} _
+   * @param {number[]} itemIndices
    * @param {Partial<GeneratorOptions>} options
    */
   async processChunk(_, itemIndices, { input }) {
     const { loadFiles } = createJsLoader();
-
     const sourceFiles = loadFiles(input ?? []);
 
     const { parseJsSource } = createJsParser();
@@ -57,8 +54,6 @@ export default {
     const sourceFiles = loadFiles(input ?? []);
 
     // Parse the Javascript sources into ASTs in parallel using worker threads
-    // Note: We pass sourceFiles as items but _ (empty) as fullInput since
-    // processChunk reloads files from options.input
     return worker.map(sourceFiles, _, { input });
   },
 };

src/generators/jsx-ast/index.mjs

@@ -1,10 +1,7 @@
+import { OVERRIDDEN_POSITIONS } from './constants.mjs';
 import { buildSideBarProps } from './utils/buildBarProps.mjs';
 import buildContent from './utils/buildContent.mjs';
-import {
-  buildDocPages,
-  getSortedHeadNodes,
-  groupNodesByModule,
-} from '../../utils/generators.mjs';
+import { groupNodesByModule } from '../../utils/generators.mjs';
 import { getRemarkRecma } from '../../utils/remark.mjs';
 
 /**
@@ -13,6 +10,34 @@ import { getRemarkRecma } from '../../utils/remark.mjs';
  * @typedef {Array<ApiDocMetadataEntry>} Input
  * @type {GeneratorMetadata<Input, string>}
  */
+
+/**
+ * Sorts entries by OVERRIDDEN_POSITIONS and then heading name.
+ * @param {Array<ApiDocMetadataEntry>} entries
+ */
+const getSortedHeadNodes = entries => {
+  return entries
+    .filter(node => node.heading.depth === 1)
+    .sort((a, b) => {
+      const ai = OVERRIDDEN_POSITIONS.indexOf(a.api);
+      const bi = OVERRIDDEN_POSITIONS.indexOf(b.api);
+
+      if (ai !== -1 && bi !== -1) {
+        return ai - bi;
+      }
+
+      if (ai !== -1) {
+        return -1;
+      }
+
+      if (bi !== -1) {
+        return 1;
+      }
+
+      return a.heading.data.name.localeCompare(b.heading.data.name);
+    });
+};
+
 export default {
   name: 'jsx-ast',
   version: '1.0.0',
@@ -26,36 +51,45 @@ export default {
    * @param {Partial<GeneratorOptions>} options
    */
   async processChunk(fullInput, itemIndices, { index, releases, version }) {
-    const processor = getRemarkRecma();
+    const remarkRecma = getRemarkRecma();
     const groupedModules = groupNodesByModule(fullInput);
     const headNodes = getSortedHeadNodes(fullInput);
-    const docPages = buildDocPages(headNodes, index);
 
-    return Promise.all(
-      itemIndices.map(async idx => {
-        const entry = headNodes[idx];
+    const docPages = index
+      ? index.map(({ section, api }) => [section, `${api}.html`])
+      : headNodes.map(node => [node.heading.data.name, `${node.api}.html`]);
 
-        const sideBarProps = buildSideBarProps(
-          entry,
-          releases,
-          version,
-          docPages
-        );
+    const results = [];
 
-        return buildContent(
+    for (const idx of itemIndices) {
+      const entry = headNodes[idx];
+
+      const sideBarProps = buildSideBarProps(
+        entry,
+        releases,
+        version,
+        docPages
+      );
+
+      results.push(
+        await buildContent(
           groupedModules.get(entry.api),
           entry,
           sideBarProps,
-          processor
-        );
-      })
-    );
+          remarkRecma
+        )
+      );
+    }
+
+    return results;
   },
 
   /**
    * Generates a JSX AST
+   *
    * @param {Input} entries
    * @param {Partial<GeneratorOptions>} options
+   * @returns {Promise<Array<string>>} Array of generated content
    */
   async generate(entries, { index, releases, version, worker }) {
     const headNodes = getSortedHeadNodes(entries);