fix(generate): show help output when no arguments or config are provided by bmuenzenmeyer · Pull Request #853 · nodejs/doc-kit

bmuenzenmeyer · 2026-06-24T14:01:00Z

Description

When using doc-kit, i tried npx doc-kit generate only to get the reported error. We can do better.

Made with assistance by Claude Code Sonnet - verified manually.

We don't have any test coverage of this file, which I retained that pattern.

Validation

Before

npm run run generate

> @node-core/doc-kit@1.3.10 run
> node bin/cli.mjs generate

[14:02:51.573] ERROR: Cannot read properties of undefined (reading 'join')
TypeError: Cannot read properties of undefined (reading 'join')
    at runGenerators (file:///Users/brian/Documents/doc-kit/src/generators.mjs:99:30)
    at file:///Users/brian/Documents/doc-kit/bin/commands/generate.mjs:65:13
    at process.processTicksAndRejections (node:internal/process/task_queues:103:5)
    at async Command.<anonymous> (file:///Users/brian/Documents/doc-kit/bin/u

After

npm run run generate   

> @node-core/doc-kit@1.3.10 run
> node bin/cli.mjs generate

Usage: @node-core/doc-kit generate [options]

Generate API docs

Options:
  --config-file <path>         Config file
  -i, --input <patterns...>    Input file patterns (glob)
  -t, --target <generator...>  Target generator(s) (choices: "json-simple", "legacy-html", "legacy-html-all", "man-page",
                               "legacy-json", "legacy-json-all", "addon-verify", "api-links", "orama-db", "llms-txt",
                               "sitemap", "web")
  --ignore <patterns...>       Ignore file patterns (glob)
  -o, --output <directory>     The output directory
  -p, --threads <number>       Number of threads to use (minimum: 1)
  --chunk-size <number>        Number of items to process per worker thread (minimum: 1)
  -v, --version <semver>       Target Node.js version
  -c, --changelog <url>        Changelog URL or path
  --git-ref                    Git ref URL
  --index <url>                index.md URL or path
  --minify                     Minify?
  --type-map <url>             Type map URL or path
  -h, --help                   display help for command

Related Issues

closes #852

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format & node --run lint.
I've covered new added functionality with unit tests if necessary.

vercel · 2026-06-24T14:01:06Z

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

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Jun 27, 2026 3:28am

cursor · 2026-06-24T14:01:10Z

PR Summary

Low Risk
CLI-only guard before generators run; no changes to doc generation or config merging behavior when valid options are provided.

Overview
Running doc-kit generate with no --target and no --config-file used to fail deep in runGenerators with a TypeError on generators.join. The CLI now validates inputs immediately after setConfig via assertRunnableOptions, which throws a clear message telling users to pass --target or --config-file and to run doc-kit generate --help.

Unit tests cover the throw and the two allowed cases. The README generate section documents the requirement.

^{Reviewed by Cursor Bugbot for commit 19da3ae. Bugbot is set up for automated code reviews on this repo. Configure here.}

codecov · 2026-06-24T14:01:57Z

Codecov Report

❌ Patch coverage is 85.36585% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.00%. Comparing base (b5cf0a0) to head (19da3ae).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
bin/commands/generate.mjs	0.00%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #853      +/-   ##
==========================================
+ Coverage   84.60%   85.00%   +0.39%     
==========================================
  Files         176      179       +3     
  Lines       15858    16444     +586     
  Branches     1411     1490      +79     
==========================================
+ Hits        13417    13978     +561     
- Misses       2431     2456      +25     
  Partials       10       10

☔ View full report in Codecov by Harness.
📢 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.

github-actions · 2026-06-24T14:03:22Z

`web` Generator

File	Base	Head	Diff
`all.html`	19.89 MB	19.84 MB	-49.70 KB (-0.24%)
`all.js`	20.31 MB	20.28 MB	-25.87 KB (-0.12%)
`fs.html`	1.47 MB	1.47 MB	-7.09 KB (-0.47%)
`buffer.html`	911.50 KB	906.26 KB	-5.24 KB (-0.57%)
`crypto.html`	1.10 MB	1.10 MB	-4.59 KB (-0.41%)
`fs.js`	1.27 MB	1.27 MB	-3.79 KB (-0.29%)
`buffer.js`	1.08 MB	1.08 MB	-2.61 KB (-0.24%)
`crypto.js`	1.22 MB	1.22 MB	-2.34 KB (-0.19%)
`test.html`	808.97 KB	806.86 KB	-2.11 KB (-0.26%)
`http.html`	756.24 KB	754.18 KB	-2.06 KB (-0.27%)
`net.html`	412.36 KB	410.31 KB	-2.05 KB (-0.50%)
`util.html`	697.58 KB	695.74 KB	-1.84 KB (-0.26%)
`zlib.html`	347.02 KB	345.26 KB	-1.76 KB (-0.51%)
`webcrypto.html`	551.61 KB	550.03 KB	-1.58 KB (-0.29%)
`stream.html`	860.83 KB	859.48 KB	-1.35 KB (-0.16%)
`dgram.html`	209.44 KB	208.12 KB	-1.32 KB (-0.63%)
`dns.html`	299.13 KB	297.83 KB	-1.30 KB (-0.44%)
`process.html`	687.95 KB	686.65 KB	-1.30 KB (-0.19%)
`sqlite.html`	289.79 KB	288.59 KB	-1.20 KB (-0.41%)
`net.js`	294.67 KB	293.49 KB	-1.18 KB (-0.40%)
`stream_iter.html`	368.25 KB	367.10 KB	-1.15 KB (-0.31%)
`http.js`	687.23 KB	686.12 KB	-1.12 KB (-0.16%)
`test.js`	921.62 KB	920.58 KB	-1.05 KB (-0.11%)
`tls.html`	379.50 KB	378.47 KB	-1.03 KB (-0.27%)
`util.js`	745.90 KB	744.92 KB	-995.00 B (-0.13%)
`assert.html`	330.42 KB	329.45 KB	-990.00 B (-0.29%)
`events.html`	455.61 KB	454.72 KB	-904.00 B (-0.19%)
`zlib.js`	359.52 KB	358.65 KB	-892.00 B (-0.24%)
`perf_hooks.html`	382.20 KB	381.37 KB	-852.00 B (-0.22%)
`console.html`	145.43 KB	144.61 KB	-845.00 B (-0.57%)
`webcrypto.js`	423.06 KB	422.27 KB	-802.00 B (-0.19%)
`stream.js`	854.40 KB	853.64 KB	-773.00 B (-0.09%)
`process.js`	695.92 KB	695.18 KB	-753.00 B (-0.11%)
`dgram.js`	179.27 KB	178.55 KB	-736.00 B (-0.40%)
`vm.html`	371.29 KB	370.59 KB	-718.00 B (-0.19%)
`https.html`	151.10 KB	150.40 KB	-712.00 B (-0.46%)
`url.html`	348.62 KB	347.95 KB	-679.00 B (-0.19%)
`ffi.html`	132.79 KB	132.13 KB	-676.00 B (-0.50%)
`dns.js`	261.77 KB	261.12 KB	-660.00 B (-0.25%)
`tls.js`	312.25 KB	311.64 KB	-626.00 B (-0.20%)
`sqlite.js`	254.82 KB	254.22 KB	-608.00 B (-0.23%)
`stream_iter.js`	456.16 KB	455.59 KB	-581.00 B (-0.12%)
`quic.html`	728.12 KB	727.59 KB	-542.00 B (-0.07%)
`worker_threads.html`	373.28 KB	372.76 KB	-538.00 B (-0.14%)
`child_process.html`	380.16 KB	379.65 KB	-530.00 B (-0.14%)
`v8.html`	342.55 KB	342.05 KB	-516.00 B (-0.15%)
`assert.js`	448.95 KB	448.47 KB	-488.00 B (-0.11%)
`timers.html`	133.96 KB	133.51 KB	-460.00 B (-0.34%)
`https.js`	155.41 KB	154.98 KB	-447.00 B (-0.28%)
`events.js`	539.11 KB	538.68 KB	-445.00 B (-0.08%)
`globals.html`	230.84 KB	230.41 KB	-442.00 B (-0.19%)
`console.js`	99.13 KB	98.70 KB	-436.00 B (-0.43%)
`perf_hooks.js`	353.78 KB	353.37 KB	-419.00 B (-0.12%)
`readline.html`	252.63 KB	252.26 KB	-386.00 B (-0.15%)
`vm.js`	432.13 KB	431.79 KB	-352.00 B (-0.08%)
`async_context.html`	188.03 KB	187.70 KB	-342.00 B (-0.18%)
`ffi.js`	97.13 KB	96.81 KB	-331.00 B (-0.33%)
`module.html`	328.80 KB	328.52 KB	-294.00 B (-0.09%)
`url.js`	331.00 KB	330.73 KB	-275.00 B (-0.08%)
`http2.html`	779.11 KB	778.85 KB	-264.00 B (-0.03%)
`quic.js`	442.59 KB	442.33 KB	-264.00 B (-0.06%)
`worker_threads.js`	394.12 KB	393.86 KB	-262.00 B (-0.06%)
`child_process.js`	455.00 KB	454.75 KB	-258.00 B (-0.06%)
`v8.js`	345.20 KB	344.95 KB	-251.00 B (-0.07%)
`tty.html`	95.85 KB	95.61 KB	-246.00 B (-0.25%)
`inspector.html`	172.05 KB	171.82 KB	-240.00 B (-0.14%)
`path.html`	139.72 KB	139.50 KB	-226.00 B (-0.16%)
`timers.js`	93.30 KB	93.08 KB	-223.00 B (-0.23%)
`globals.js`	122.78 KB	122.57 KB	-214.00 B (-0.17%)
`cluster.html`	196.76 KB	196.55 KB	-210.00 B (-0.10%)
`dtls.html`	147.37 KB	147.17 KB	-200.00 B (-0.13%)
`readline.js`	217.31 KB	217.13 KB	-186.00 B (-0.08%)
`async_context.js`	213.43 KB	213.27 KB	-164.00 B (-0.08%)
`querystring.html`	64.31 KB	64.17 KB	-144.00 B (-0.22%)
`module.js`	331.70 KB	331.56 KB	-140.00 B (-0.04%)
`repl.html`	183.83 KB	183.69 KB	-140.00 B (-0.07%)
`os.html`	145.11 KB	144.97 KB	-138.00 B (-0.09%)
`http2.js`	803.03 KB	802.91 KB	-125.00 B (-0.02%)
`domain.html`	105.56 KB	105.45 KB	-118.00 B (-0.11%)
`tty.js`	43.05 KB	42.93 KB	-116.00 B (-0.26%)
`vfs.html`	81.86 KB	81.75 KB	-116.00 B (-0.14%)
`inspector.js`	114.89 KB	114.78 KB	-113.00 B (-0.10%)
`wasi.html`	69.83 KB	69.72 KB	-108.00 B (-0.15%)
`path.js`	91.92 KB	91.81 KB	-106.00 B (-0.11%)
`errors.html`	483.71 KB	483.61 KB	-104.00 B (-0.02%)
`punycode.html`	63.68 KB	63.58 KB	-104.00 B (-0.16%)
`cluster.js`	188.56 KB	188.47 KB	-98.00 B (-0.05%)
`dtls.js`	82.81 KB	82.72 KB	-93.00 B (-0.11%)
`single-executable-applications.html`	107.45 KB	107.37 KB	-84.00 B (-0.08%)
`querystring.js`	26.14 KB	26.07 KB	-65.00 B (-0.24%)
`repl.js`	205.07 KB	205.01 KB	-63.00 B (-0.03%)
`os.js`	103.20 KB	103.14 KB	-62.00 B (-0.06%)
`string_decoder.html`	55.85 KB	55.79 KB	-60.00 B (-0.10%)
`domain.js`	85.64 KB	85.59 KB	-52.00 B (-0.06%)
`vfs.js`	43.09 KB	43.04 KB	-51.00 B (-0.12%)
`wasi.js`	37.79 KB	37.74 KB	-47.00 B (-0.12%)
`errors.js`	362.34 KB	362.30 KB	-45.00 B (-0.01%)
`punycode.js`	23.41 KB	23.36 KB	-45.00 B (-0.19%)
`async_hooks.html`	160.17 KB	160.13 KB	-38.00 B (-0.02%)
`single-executable-applications.js`	80.17 KB	80.14 KB	-35.00 B (-0.04%)
`string_decoder.js`	26.63 KB	26.61 KB	-23.00 B (-0.08%)
`esm.html`	156.17 KB	156.15 KB	-22.00 B (-0.01%)
`tracing.html`	84.62 KB	84.59 KB	-22.00 B (-0.03%)
`webstreams.html`	358.17 KB	358.15 KB	-20.00 B (-0.01%)
`modules.html`	180.77 KB	180.75 KB	-16.00 B (-0.01%)
`async_hooks.js`	191.51 KB	191.50 KB	-12.00 B (-0.01%)
`addons.js`	305.26 KB	305.26 KB	+7.00 B (+0.00%)
`cli.js`	314.94 KB	314.95 KB	+7.00 B (+0.00%)
`debugger.js`	88.91 KB	88.91 KB	+7.00 B (+0.01%)
`deprecations.js`	294.99 KB	295.00 KB	+7.00 B (+0.00%)
`diagnostics_channel.js`	303.25 KB	303.26 KB	+7.00 B (+0.00%)
`documentation.js`	4.84 KB	4.85 KB	+7.00 B (+0.14%)
`embedding.js`	33.39 KB	33.40 KB	+7.00 B (+0.02%)
`environment_variables.js`	11.70 KB	11.70 KB	+7.00 B (+0.06%)
`intl.js`	32.41 KB	32.42 KB	+7.00 B (+0.02%)
`n-api.js`	711.14 KB	711.15 KB	+7.00 B (+0.00%)
`packages.js`	145.83 KB	145.84 KB	+7.00 B (+0.00%)
`permissions.js`	34.79 KB	34.79 KB	+7.00 B (+0.02%)
`report.js`	184.70 KB	184.71 KB	+7.00 B (+0.00%)
`synopsis.js`	11.39 KB	11.40 KB	+7.00 B (+0.06%)
`typescript.js`	21.57 KB	21.57 KB	+7.00 B (+0.03%)
`esm.js`	131.90 KB	131.90 KB	-4.00 B (-0.00%)
`tracing.js`	72.75 KB	72.74 KB	-4.00 B (-0.01%)
`webstreams.js`	280.37 KB	280.36 KB	-3.00 B (-0.00%)
`modules.js`	146.23 KB	146.23 KB	-1.00 B (-0.00%)

avivkeller · 2026-06-24T14:55:09Z

+      // Running `generate` with no arguments or config has nothing to do, so
+      // show the help output instead of failing later with an opaque error.
+      if (Object.keys(opts).length === 0) {
+        command.help();
+      }


Shouldn't we just make certain arguments required instead?

i.e., --target OR --config-file MUST be provided.

resolved via 1ef7ca1

… command

…onfig file presence

avivkeller · 2026-06-24T19:30:17Z

+      assertRunnableOptions(opts);
+
      const config = await setConfig(opts);


swap these statements and call assertRunnableOptions on the config, checking that target and input is passed

addressed via 19da3ae

cursor

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 19da3ae. Configure here.}

cursor · 2026-06-27T03:29:01Z

  .action(
    errorWrap(async opts => {
      const config = await setConfig(opts);
+      assertRunnableOptions(config);


configFile check wrong object

Medium Severity

assertRunnableOptions is run on the merged configuration from setConfig, but it still treats configFile as if it were CLI options. Merged configs never carry configFile, so that branch never applies in the generate command. Users who only pass --config-file can get an error implying they omitted it even when they did not.

Additional Locations (1)

src/utils/configuration/index.mjs#L112-L119

^{Reviewed by Cursor Bugbot for commit 19da3ae. Configure here.}

cursor · 2026-06-27T03:29:01Z

+      'Either `--target` or `--config-file` must be provided. ' +
+        'Run `doc-kit generate --help` for usage.'
+    );
+  }


Runnable guard skips input

Medium Severity

The new assertRunnableOptions gate only checks target and configFile, not input. After merge, a run can pass validation with generators set but no global.input, then fail later in the pipeline when generators call methods like flatMap on undefined input.

Additional Locations (1)

bin/commands/generate.mjs#L67-L68

^{Reviewed by Cursor Bugbot for commit 19da3ae. Configure here.}

fix(generate): show help output when no arguments or config are provided

42a47e6

bmuenzenmeyer requested a review from a team as a code owner June 24, 2026 14:01

avivkeller reviewed Jun 24, 2026

View reviewed changes

fix(generate): enforce target or config file requirement for generate…

1ef7ca1

… command

bmuenzenmeyer requested a review from avivkeller June 24, 2026 18:46

cursor Bot reviewed Jun 24, 2026

View reviewed changes

Comment thread src/utils/configuration/index.mjs

vercel Bot deployed to Preview June 24, 2026 18:48 View deployment

fix(configuration): add assertRunnableOptions to validate target or c…

40d5928

…onfig file presence

vercel Bot deployed to Preview June 24, 2026 19:16 View deployment

avivkeller reviewed Jun 24, 2026

View reviewed changes

fix(generate): validate options after configuration is set

19da3ae

vercel Bot deployed to Preview June 27, 2026 03:28 View deployment

cursor Bot reviewed Jun 27, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(generate): show help output when no arguments or config are provided#853

fix(generate): show help output when no arguments or config are provided#853
bmuenzenmeyer wants to merge 4 commits into
mainfrom
generate-help

bmuenzenmeyer commented Jun 24, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

cursor Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

codecov Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 24, 2026 •

edited

Loading

Uh oh!

avivkeller Jun 24, 2026 •

edited

Loading

Uh oh!

bmuenzenmeyer Jun 24, 2026

Uh oh!

Uh oh!

avivkeller Jun 24, 2026

Uh oh!

bmuenzenmeyer Jun 27, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Jun 27, 2026

Uh oh!

cursor Bot Jun 27, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		assertRunnableOptions(opts);

		const config = await setConfig(opts);

Uh oh!

Conversation

bmuenzenmeyer commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Related Issues

Check List

Uh oh!

vercel Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Summary

Uh oh!

codecov Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jun 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

web Generator

Uh oh!

avivkeller Jun 24, 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!

bmuenzenmeyer Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

avivkeller Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

bmuenzenmeyer Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jun 27, 2026

Choose a reason for hiding this comment

configFile check wrong object

Uh oh!

cursor Bot Jun 27, 2026

Choose a reason for hiding this comment

Runnable guard skips input

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bmuenzenmeyer commented Jun 24, 2026 •

edited

Loading

vercel Bot commented Jun 24, 2026 •

edited

Loading

cursor Bot commented Jun 24, 2026 •

edited

Loading

codecov Bot commented Jun 24, 2026 •

edited

Loading

github-actions Bot commented Jun 24, 2026 •

edited

Loading

`web` Generator

avivkeller Jun 24, 2026 •

edited

Loading