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

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

* fix(configuration): add assertRunnableOptions to validate target or config file presence

* fix(generate): validate options after configuration is set

* assert on merged config

Author: bmuenzenmeyer

README.md

@@ -54,6 +54,10 @@ Commands:
 
 ### `generate`
 
+You must provide either `--target` (one or more generators to run) or
+`--config-file` (which supplies the targets). Running `generate` without either
+exits with an error pointing you to the help output.
+
 ```
 Usage: @node-core/doc-kit generate [options]
 

bin/commands/generate.mjs

@@ -2,7 +2,10 @@ import { Command, Option } from 'commander';
 
 import { publicGenerators } from '../../src/generators/index.mjs';
 import createGenerator from '../../src/generators.mjs';
-import { setConfig } from '../../src/utils/configuration/index.mjs';
+import {
+  assertRunnableOptions,
+  setConfig,
+} from '../../src/utils/configuration/index.mjs';
 import { errorWrap } from '../utils.mjs';
 
 const { runGenerators } = createGenerator();
@@ -62,6 +65,8 @@ export default new Command('generate')
   .action(
     errorWrap(async opts => {
       const config = await setConfig(opts);
+      assertRunnableOptions(config);
+
       await runGenerators(config);
     })
   );

src/utils/configuration/__tests__/index.test.mjs

@@ -33,6 +33,7 @@ mock.module('../../loaders.mjs', {
 });
 
 const {
+  assertRunnableOptions,
   loadConfigFile,
   createConfigFromCLIOptions,
   createRunConfiguration,
@@ -125,6 +126,28 @@ describe('config.mjs', () => {
     });
   });
 
+  describe('assertRunnableOptions', () => {
+    it('should throw when target is missing', () => {
+      assert.throws(
+        () => assertRunnableOptions({ global: { input: 'src/' } }),
+        /Both a `target` and an `input` must be provided/
+      );
+    });
+
+    it('should throw when input is missing', () => {
+      assert.throws(
+        () => assertRunnableOptions({ target: ['json'], global: {} }),
+        /Both a `target` and an `input` must be provided/
+      );
+    });
+
+    it('should not throw when both target and input are provided', () => {
+      assert.doesNotThrow(() =>
+        assertRunnableOptions({ target: ['json'], global: { input: 'src/' } })
+      );
+    });
+  });
+
   describe('createRunConfiguration', () => {
     it('should merge config sources in correct order', async () => {
       mockImportFromURL.mock.mockImplementationOnce(async () =>

src/utils/configuration/index.mjs

@@ -104,6 +104,24 @@ export const createConfigFromCLIOptions = options => ({
   chunkSize: options.chunkSize,
 });
 
+/**
+ * Asserts that the resolved configuration has everything needed to run:
+ * at least one generator `target` and an `input` to read source files from.
+ * These may come from CLI flags or a config file; by this point both sources
+ * have been merged, so we validate the result rather than the raw options.
+ *
+ * @param {import('./types').Configuration} config - The merged configuration
+ */
+export const assertRunnableOptions = config => {
+  if (!config.target || !config.global?.input) {
+    throw new Error(
+      'Both a `target` and an `input` must be provided, either via ' +
+        '`--target`/`--input` or a `--config-file`. ' +
+        'Run `doc-kit generate --help` for usage.'
+    );
+  }
+};
+
 /**
  * Creates a complete run configuration by merging config file, user options, and defaults.
  * Processes and validates configuration values including version coercion, changelog parsing,