React to wrong library usage

Readme.md

@@ -546,6 +546,8 @@ subcommand is specified ([example](./examples/defaultCommand.js)).
 
 You can add alternative names for a command with `.alias()`. ([example](./examples/alias.js))
 
+Commands added with `.command()` automatically inherit settings for which inheritance is meaningful from the parent command, but only upon the subcommand creation. The setting changes made after calling `.command()` are not inherited.
+
 For safety, `.addCommand()` does not automatically copy the inherited settings from the parent command. There is a helper routine `.copyInheritedSettings()` for copying the settings when they are wanted.
 
 ### Command-arguments

lib/command.js

@@ -12,6 +12,8 @@ const { suggestSimilar } = require('./suggestSimilar');
 
 // @ts-check
 
+const PRODUCTION = process.env.NODE_ENV === 'production';
+
 class Command extends EventEmitter {
   /**
    * Initialize a new `Command`.
@@ -77,6 +79,9 @@ class Command extends EventEmitter {
     this._helpCommandnameAndArgs = 'help [command]';
     this._helpCommandDescription = 'display help for command';
     this._helpConfiguration = {};
+
+    /** @type {boolean | undefined} */
+    this._asyncParsing = undefined;
   }
 
   /**
@@ -265,6 +270,10 @@ class Command extends EventEmitter {
       throw new Error(`Command passed to .addCommand() must have a name
 - specify the name in Command constructor or using .name()`);
     }
+    if (cmd.parent) {
+      throw new Error(`'${cmd._name}' cannot be added using .addCommand()
+- it already has a parent command`);
+    }
 
     opts = opts || {};
     if (opts.isDefault) this._defaultCommandName = cmd._name;
@@ -887,6 +896,28 @@ Expecting one of '${allowedValues.join("', '")}'`);
     return userArgs;
   }
 
+  /**
+   * @param {boolean} async
+   * @param {Function} userArgsCallback
+   * @param {string[]} [argv]
+   * @param {Object} [parseOptions]
+   * @param {string} [parseOptions.from]
+   * @return {Command|Promise}
+   * @api private
+   */
+
+  _parseSubroutine(async, userArgsCallback, argv, parseOptions) {
+    this._asyncParsing = async;
+    const methodName = async ? 'parseAsync' : 'parse';
+    if (!PRODUCTION && this.parent) {
+      console.warn(`Called .${methodName}() on subcommand '${this._name}'.
+Call on top-level command instead`);
+    }
+
+    const userArgs = this._prepareUserArgs(argv, parseOptions);
+    return userArgsCallback(userArgs);
+  }
+
   /**
    * Parse `argv`, setting options and invoking commands when defined.
    *
@@ -905,10 +936,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   parse(argv, parseOptions) {
-    const userArgs = this._prepareUserArgs(argv, parseOptions);
-    this._parseCommand([], userArgs);
-
-    return this;
+    return this._parseSubroutine(false, (userArgs) => {
+      this._parseCommand([], userArgs);
+      return this;
+    }, argv, parseOptions);
   }
 
   /**
@@ -931,10 +962,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   async parseAsync(argv, parseOptions) {
-    const userArgs = this._prepareUserArgs(argv, parseOptions);
-    await this._parseCommand([], userArgs);
-
-    return this;
+    return this._parseSubroutine(true, async(userArgs) => {
+      await this._parseCommand([], userArgs);
+      return this;
+    }, argv, parseOptions);
   }
 
   /**
@@ -1071,6 +1102,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
   _dispatchSubcommand(commandName, operands, unknown) {
     const subCommand = this._findCommand(commandName);
     if (!subCommand) this.help({ error: true });
+    subCommand._asyncParsing = this._asyncParsing;
 
     let hookResult;
     hookResult = this._chainOrCallSubCommandHook(hookResult, subCommand, 'preSubcommand');
@@ -1189,12 +1221,18 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   _chainOrCall(promise, fn) {
     // thenable
-    if (promise && promise.then && typeof promise.then === 'function') {
+    if (isThenable(promise)) {
       // already have a promise, chain callback
       return promise.then(() => fn());
     }
+
     // callback might return a promise
-    return fn();
+    const result = fn();
+    if (!PRODUCTION && !this._asyncParsing && isThenable(result)) {
+      console.warn(`.parse() is incompatible with async hooks and actions.
+Use .parseAsync() instead.`);
+    }
+    return result;
   }
 
   /**
@@ -2193,4 +2231,14 @@ function getCommandAndParents(startCommand) {
   return result;
 }
 
+/**
+ * @param {*} value
+ * @returns {boolean}
+ * @api private
+ */
+
+function isThenable(value) {
+  return typeof value?.then === 'function';
+}
+
 exports.Command = Command;