feat(cli): add progress bar to generation pipeline

bin/commands/generate.mjs

@@ -21,6 +21,7 @@ const { runGenerators } = createGenerator();
  * @property {string} index
  * @property {boolean} minify
  * @property {string} typeMap
+ * @property {boolean} progress
  */
 
 export default new Command('generate')
@@ -58,6 +59,7 @@ export default new Command('generate')
   .addOption(new Option('--index <url>', 'index.md URL or path'))
   .addOption(new Option('--minify', 'Minify?'))
   .addOption(new Option('--type-map <url>', 'Type map URL or path'))
+  .addOption(new Option('--no-progress', 'Disable the progress bar'))
 
   .action(
     errorWrap(async opts => {

package.json

@@ -52,6 +52,7 @@
     "@rollup/plugin-virtual": "^3.0.2",
     "@swc/html-wasm": "^1.15.18",
     "acorn": "^8.16.0",
+    "cli-progress": "^3.12.0",
     "commander": "^14.0.3",
     "dedent": "^1.7.1",
     "estree-util-to-js": "^2.0.0",

src/generators.mjs

@@ -5,6 +5,7 @@ import logger from './logger/index.mjs';
 import { isAsyncGenerator, createStreamingCache } from './streaming.mjs';
 import createWorkerPool from './threading/index.mjs';
 import createParallelWorker from './threading/parallel.mjs';
+import createProgressBar from './utils/progressBar.mjs';
 
 const generatorsLogger = logger.child('generators');
 
@@ -92,7 +93,7 @@ const createGenerator = () => {
   /**
    * Runs all requested generators with their dependencies.
    *
-   * @param {import('./utils/configuration/types').Configuration} options - Runtime options
+   * @param {import('./utils/configuration/types').Configuration} configuration - Runtime options
    * @returns {Promise<unknown[]>} Results of all requested generators
    */
   const runGenerators = async configuration => {
@@ -111,6 +112,9 @@ const createGenerator = () => {
       await scheduleGenerator(name, configuration);
     }
 
+    const progress = createProgressBar({ enabled: configuration.progress });
+    progress?.start(generators.length, 0, { phase: 'Starting...' });
+
     // Start all collections in parallel (don't await sequentially)
     const resultPromises = generators.map(async name => {
       let result = await cachedGenerators[name];
@@ -119,14 +123,17 @@ const createGenerator = () => {
         result = await streamingCache.getOrCollect(name, result);
       }
 
+      progress?.increment({ phase: name });
       return result;
     });
 
-    const results = await Promise.all(resultPromises);
-
-    await pool.destroy();
-
-    return results;
+    try {
+      const results = await Promise.all(resultPromises);
+      return results;
+    } finally {
+      await pool.destroy();
+      progress?.stop();
+    }
   };
 
   return { runGenerators };

src/utils/configuration/__tests__/index.test.mjs

@@ -93,6 +93,7 @@ describe('config.mjs', () => {
         target: 'json',
         threads: 4,
         chunkSize: 5,
+        progress: true,
       };
 
       const config = createConfigFromCLIOptions(options);
@@ -112,6 +113,7 @@ describe('config.mjs', () => {
         target: 'json',
         threads: 4,
         chunkSize: 5,
+        progress: true,
       });
     });
 

src/utils/configuration/index.mjs

@@ -35,6 +35,7 @@ export const getDefaultConfig = lazy(() =>
 
       threads: cpus().length,
       chunkSize: 10,
+      progress: true,
     })
   )
 );
@@ -96,6 +97,7 @@ export const createConfigFromCLIOptions = options => ({
   target: options.target,
   threads: options.threads,
   chunkSize: options.chunkSize,
+  progress: options.progress,
 });
 
 /**

src/utils/configuration/types.d.ts

@@ -15,6 +15,7 @@ export type Configuration = {
 
   // Number of items to process per worker thread
   chunkSize: number;
+  progress: boolean;
 } & {
   [K in keyof AllGenerators]: GlobalConfiguration &
     AllGenerators[K]['defaultConfiguration'];

src/utils/progressBar.mjs

@@ -0,0 +1,30 @@
+'use strict';
+
+import { SingleBar, Presets } from 'cli-progress';
+
+/**
+ * Creates a progress bar for the generation pipeline.
+ * Writes to stderr to avoid conflicts with the logger (stdout).
+ * Returns a no-op object if disabled or if stderr is not a TTY (e.g. CI).
+ *
+ * @param {object} [options]
+ * @param {boolean} [options.enabled=true] Whether to render the progress bar
+ * @returns {SingleBar | null}
+ */
+const createProgressBar = ({ enabled = true } = {}) => {
+  if (!enabled || !process.stderr.isTTY) {
+    return null;
+  }
+
+  return new SingleBar(
+    {
+      stream: process.stderr,
+      format: '  {phase} [{bar}] {percentage}% | {value}/{total}',
+      hideCursor: true,
+      clearOnComplete: false,
+    },
+    Presets.shades_grey
+  );
+};
+
+export default createProgressBar;