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 29, 2026 2:19am

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

PR Summary

Low Risk
CLI-only validation before generator execution; no changes to doc generation logic or security-sensitive paths.

Overview
Running doc-kit generate with no --target / --input and no usable --config-file used to crash deep in runGenerators (e.g. undefined.join). This PR validates the merged config right after setConfig via assertRunnableOptions, requiring both target and global.input, and fails fast with a clear message that points users to doc-kit generate --help.

The README generate section now states that --target or --config-file is required. Unit tests cover the new guard for missing target, missing input, and the happy path.

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

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

Codecov Report

❌ Patch coverage is 87.23404% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.00%. Comparing base (b5cf0a0) to head (83ee9e1).
⚠️ Report is 5 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    16453     +595     
  Branches     1411     1492      +81     
==========================================
+ Hits        13417    13986     +569     
- Misses       2431     2457      +26     
  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

`orama-db` Generator

File	Base	Head	Diff
`orama-db.json`	8.89 MB	8.89 MB	+1.07 KB (+0.01%)

`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 and 83ee9e1

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

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

Want fixes drafted automatically? Bugbot Autofix can create code changes for findings. A team admin can enable Autofix in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 83ee9e1. 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

Comment thread bin/commands/generate.mjs

Comment thread src/utils/configuration/index.mjs

assert on merged config

83ee9e1

vercel Bot deployed to Preview June 29, 2026 02:19 View deployment

cursor Bot reviewed Jun 29, 2026

View reviewed changes

Comment thread src/utils/configuration/index.mjs

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 5 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 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

cursor Bot left a comment

Uh oh!

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!

orama-db Generator

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 • 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!

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

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

`orama-db` Generator

`web` Generator

avivkeller Jun 24, 2026 •

edited

Loading

bmuenzenmeyer Jun 27, 2026 •

edited

Loading