feat(cli): add progress bar to generation pipeline

Author: shivxmsharma

bin/commands/generate.mjs

@@ -58,10 +58,11 @@ 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 => {
       const config = await setConfig(opts);
-      await runGenerators(config);
+      await runGenerators(config, opts.progress);
     })
   );

package-lock.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",

package.json

@@ -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,10 +93,11 @@ 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
+   * @param {boolean} [showProgress=true] - Whether to render the progress bar
    * @returns {Promise<unknown[]>} Results of all requested generators
    */
-  const runGenerators = async configuration => {
+  const runGenerators = async (configuration, showProgress = true) => {
     const { target: generators, threads } = configuration;
 
     generatorsLogger.debug(`Starting pipeline`, {
@@ -111,6 +113,9 @@ const createGenerator = () => {
       await scheduleGenerator(name, configuration);
     }
 
+    const progress = createProgressBar({ enabled: showProgress });
+    progress.start(generators.length);
+
     // Start all collections in parallel (don't await sequentially)
     const resultPromises = generators.map(async name => {
       let result = await cachedGenerators[name];
@@ -119,12 +124,14 @@ const createGenerator = () => {
         result = await streamingCache.getOrCollect(name, result);
       }
 
+      progress.increment(name);
       return result;
     });
 
     const results = await Promise.all(resultPromises);
 
     await pool.destroy();
+    progress.stop();
 
     return results;
   };

src/generators.mjs

@@ -0,0 +1,46 @@
+'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 {{ start: (total: number) => void, increment: (phase: string) => void, stop: () => void }}
+ */
+const createProgressBar = ({ enabled = true } = {}) => {
+  if (!enabled || !process.stderr.isTTY) {
+    return {
+      /** @returns {void} */
+      start: () => {},
+      /** @returns {void} */
+      increment: () => {},
+      /** @returns {void} */
+      stop: () => {},
+    };
+  }
+
+  const bar = new SingleBar(
+    {
+      stream: process.stderr,
+      format: '  {phase} [{bar}] {percentage}% | {value}/{total}',
+      hideCursor: true,
+      clearOnComplete: false,
+    },
+    Presets.shades_grey
+  );
+
+  return {
+    /** @param {number} total */
+    start: total => bar.start(total, 0, { phase: 'Starting...' }),
+    /** @param {string} phase */
+    increment: phase => bar.increment({ phase }),
+    /** @returns {void} */
+    stop: () => bar.stop(),
+  };
+};
+
+export default createProgressBar;