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

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

src/generators.mjs

@@ -6,6 +6,7 @@ import logger from './logger/index.mjs';
 import createWorkerPool from './threading/index.mjs';
 import createParallelWorker from './threading/parallel.mjs';
 import { isAsyncIterable } from './utils/misc.mjs';
+import createProgressBar from './utils/progressBar.mjs';
 
 const generatorsLogger = logger.child('generators');
 
@@ -89,7 +90,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 => {
@@ -115,13 +116,23 @@ 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). Consuming
     // through the shared path lets the final read also trigger eviction.
     const results = await Promise.all(
-      generators.map(name => cache.consume(name))
+      generators.map(async name => {
+        const result = await cache.consume(name);
+
+        progress.increment({ phase: name });
+
+        return result;
+      })
     );
 
     await pool.destroy();
+    progress.stop();
 
     return results;
   };

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

@@ -41,6 +41,7 @@ export const getDefaultConfig = lazy(() =>
       // See also https://github.com/nodejs/node/pull/60591
       threads: process.arch === 'riscv64' ? 1 : cpus().length,
       chunkSize: 10,
+      progress: true,
     })
   )
 );
@@ -102,6 +103,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,9 @@ export type Configuration = {
 
   // Number of items to process per worker thread
   chunkSize: number;
+
+  // Whether or not the progress bar is enabled
+  progress: boolean;
 } & {
   [K in keyof AllGenerators]: GlobalConfiguration &
     AllGenerators[K]['defaultConfiguration'];

src/utils/progressBar.mjs

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