feat(cli): add progress bar to generation pipeline by shivxmsharma · Pull Request #680 · nodejs/doc-kit

shivxmsharma · 2026-03-15T17:24:24Z

Description

Adds a cli-progress progress bar to the generate command that tracks each target generator as it completes.

New src/utils/progressBar.mjs utility wraps cli-progress and writes to stderr to avoid conflicts with the existing logger (stdout)
Automatically disabled when stderr is not a TTY (CI environments, piped output)
New --no-progress flag to explicitly disable it

The bar starts after all generators are scheduled and increments once per target generator as its result collection finishes. The phase label shows the generator name:

  legacy-json [████████████████████████████████████████] 100% | 1/1

Validation

# Bar renders
node bin/cli.mjs generate -i "doc/api/*.md" -t legacy-json -o out -v 18.0.0

# Bar suppressed explicitly
node bin/cli.mjs generate -i "doc/api/*.md" -t legacy-json -o out -v 18.0.0 --no-progress

# Bar auto-suppressed in CI / piped output (stderr is not a TTY)
node bin/cli.mjs generate -i "doc/api/*.md" -t legacy-json -o out -v 18.0.0 2>/dev/null

All 312 existing tests pass.

Related Issues

Closes #58

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run npm run format to ensure the code follows the style guide.
I have run npm test to check if all tests are passing.

vercel · 2026-03-15T17:24:30Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Mar 21, 2026 10:18am

Copilot

Pull request overview

Adds an optional CLI progress bar to the generation pipeline so users can see per-target generator completion while running doc-kit generate.

Changes:

Introduces src/utils/progressBar.mjs, a small wrapper around cli-progress that renders to stderr and auto-disables when stderr isn’t a TTY.
Hooks the progress bar into src/generators.mjs so it starts after scheduling and increments once each target generator’s result collection finishes.
Adds --no-progress to the generate command and wires it into runGenerators, plus adds the cli-progress dependency.

Reviewed changes

Copilot reviewed 3 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/utils/progressBar.mjs	New utility to create a TTY-aware progress bar that writes to `stderr`.
src/generators.mjs	Starts/increments/stops the progress bar around target result collection.
bin/commands/generate.mjs	Adds `--no-progress` and passes `opts.progress` into the generator runner.
package.json	Adds `cli-progress` dependency.
package-lock.json	Locks `cli-progress` and its transitive dependencies.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

src/generators.mjs

avivkeller

cc @ovflowd given that the tooling is really fast, is a progress bar still needed?

avivkeller · 2026-03-15T18:47:10Z

bin/commands/generate.mjs

    errorWrap(async opts => {
      const config = await setConfig(opts);
-      await runGenerators(config);
+      await runGenerators(config, opts.progress);


The progress bar should be a part of global config

Should I wait for @ovflowd's response or make the possible changes to this?

IMO progress bar should be disabled/enabled behind cli arg since it's related to cli.

src/utils/progressBar.mjs

vercel · 2026-03-15T19:27:41Z

Deployment failed with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

AugustinMauroy

LGMT ! and IMO it's still a good thing to have progress bar

codecov · 2026-03-15T21:18:59Z

Codecov Report

❌ Patch coverage is 9.09091% with 40 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.63%. Comparing base (38c58bc) to head (b74b39e).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
src/utils/progressBar.mjs	0.00%	31 Missing ⚠️
src/generators.mjs	0.00%	7 Missing ⚠️
bin/commands/generate.mjs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #680      +/-   ##
==========================================
+ Coverage   74.74%   75.63%   +0.89%     
==========================================
  Files         146      150       +4     
  Lines       13255    13725     +470     
  Branches      960     1040      +80     
==========================================
+ Hits         9907    10381     +474     
+ Misses       3342     3338       -4     
  Partials        6        6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

ovflowd · 2026-03-18T13:47:48Z

cc @ovflowd given that the tooling is really fast, is a progress bar still needed?

I think a progress bar/visual indicator is good regardless. Allows us to see on what it is working. I'd argue it should be behind a feature flag such as --progress if we make it opt-in or --no-progress if we make it opt-out. I'd argue opt-out by default would be ideal, so we can disable it on CI.

It is a cool gimmick, but also genuinely brings "status" to what doc-kit is doing atm... Regardless of it being fast. What if I throw 20K md files on it?

shivxmsharma · 2026-03-19T06:31:49Z

Hey @ovflowd, the current implementation already does this — --no-progress makes it opt-out (enabled by default), and it also auto-disables in CI via a process.stderr.isTTY check, so no flag is even needed there.

@avivkeller the progress flag is now part of the global Configuration object as well. Let me know if there's anything else to address!

src/utils/configuration/types.d.ts

src/generators.mjs

Co-authored-by: Aviv Keller <me@aviv.sh>

shivxmsharma · 2026-03-19T13:12:06Z

@avivkeller Committed the suggested changes!

ovflowd · 2026-03-20T17:07:53Z

src/utils/progressBar.mjs

+    return null;
+  }
+
+  return new SingleBar(


OOC, why this package versus other packages?

Went with cli-progress mainly because of its large user base (~4M weekly downloads) and the simple API. It does exactly what we need without any extra bloat.

ovflowd · 2026-03-20T17:08:21Z

src/generators.mjs

-    await pool.destroy();
-
-    return results;
+    try {


Please revert this change 🙇

Done, reverted! 👍

ovflowd · 2026-03-20T17:09:42Z

src/generators.mjs

        result = await streamingCache.getOrCollect(name, result);
      }

+      progress?.increment({ phase: name });


Why progress?.?

ovflowd · 2026-03-20T17:09:45Z

src/generators.mjs

    }

+    const progress = createProgressBar({ enabled: configuration.progress });
+    progress?.start(generators.length, 0, { phase: 'Starting...' });


Why progress?.?

If the user disabled the progress bar, it'll be undefined

Ehh, I'd argue that

if (!enabled || !process.stderr.isTTY) {
return null;
}

Shouldn't be inside createProgressBar, what's the point of calling createProgressBar just to return null? Id recommend instead of not creating the instance, simply making a mock stream.

so:

import { PassThrough } from 'node:stream'; // ... stream: shouldEnable ? process.stdout : new PassThrough();

Great suggestion, done! Now using a PassThrough stream when disabled instead of returning null. Much cleaner.

ovflowd · 2026-03-20T17:22:05Z

package.json

    "@rollup/plugin-virtual": "^3.0.2",
    "@swc/html-wasm": "^1.15.18",
    "acorn": "^8.16.0",
+    "cli-progress": "^3.12.0",


Last release was 3y ago, although I'm fine with not having releases that often, any particular reason why this package instead of others?

It seems stable and mature — no breaking changes or open security issues. The last release is just because there's nothing to fix. Open to switching if you have a preference though!

ovflowd

This implementation of a ProgrressBar only provides Progress per generator, in the future we'd probably want to expose the Progress Bar as an Progress API to each generator so they can have more granular control.

…tional chaining

shivxmsharma · 2026-03-21T10:24:03Z

This implementation of a ProgrressBar only provides Progress per generator, in the future we'd probably want to expose the Progress Bar as an Progress API to each generator so they can have more granular control.

Agreed, that would be a nice follow-up. Happy to work on that in a separate PR!

shivxmsharma requested a review from a team as a code owner March 15, 2026 17:24

Copilot AI review requested due to automatic review settings March 15, 2026 17:24

Copilot started reviewing on behalf of shivxmsharma March 15, 2026 17:24 View session

vercel bot deployed to Preview March 15, 2026 17:25 View deployment

Copilot AI reviewed Mar 15, 2026

View reviewed changes

src/generators.mjs Show resolved Hide resolved

shivxmsharma force-pushed the feat/cli-progress-bar branch from ca20ac3 to 4f07217 Compare March 15, 2026 17:32

vercel bot deployed to Preview March 15, 2026 17:33 View deployment

avivkeller requested changes Mar 15, 2026

View reviewed changes

feat(cli): add progress bar to generation pipeline

57a244e

shivxmsharma force-pushed the feat/cli-progress-bar branch from 4f07217 to 57a244e Compare March 15, 2026 19:27

AugustinMauroy approved these changes Mar 15, 2026

View reviewed changes

avivkeller approved these changes Mar 19, 2026

View reviewed changes

src/utils/configuration/types.d.ts Show resolved Hide resolved

src/generators.mjs Outdated Show resolved Hide resolved

Update src/utils/configuration/types.d.ts

806c0bf

Co-authored-by: Aviv Keller <me@aviv.sh>

vercel bot deployed to Preview March 19, 2026 11:56 View deployment

Update src/generators.mjs

87b8843

Co-authored-by: Aviv Keller <me@aviv.sh>

vercel bot deployed to Preview March 19, 2026 11:58 View deployment

ovflowd reviewed Mar 20, 2026

View reviewed changes

refactor: address review feedback - use PassThrough stream, remove op…

b74b39e

…tional chaining

vercel bot deployed to Preview March 21, 2026 10:18 View deployment

Conversation

shivxmsharma commented Mar 15, 2026

Description

Validation

Related Issues

Check List

Uh oh!

vercel bot commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vercel bot commented Mar 15, 2026

Uh oh!

AugustinMauroy left a comment

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

ovflowd commented Mar 18, 2026

Uh oh!

shivxmsharma commented Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

shivxmsharma commented Mar 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 20, 2026 • edited by AugustinMauroy Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ovflowd Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ovflowd left a comment

Choose a reason for hiding this comment

Uh oh!

shivxmsharma commented Mar 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

vercel bot commented Mar 15, 2026 •

edited

Loading

codecov bot commented Mar 15, 2026 •

edited

Loading

ovflowd Mar 20, 2026 •

edited by AugustinMauroy

Loading

ovflowd Mar 20, 2026 •

edited

Loading