fix: prevent version name collision

[jly36963]

Addresses: #1979 and #1864

Problem

"version" can be passed as a key to yargs.option(), but this messes up parsing.
The yargs.version() method already occupies that namespace.

This code

yargs.command(
  "cmd1",
  "cmd1 desc",
  (yargs) =>
    yargs.option("version", {
      alias: "v",
      describe: "version desc",
      type: "string",
    }),
  (argv) => {
    console.log({ argv });
  }
).parse('cmd1 --version 0.25.10')

produces this result:

{
  argv: {
    _: [ 'cmd1', '0.25.10' ],
    version: false,
    v: false,
    '$0': 'my-script.js'
  }
}

Solution

I added a check in yargs.option that will throw an error emit a warning if an option (or its alias) is "version", unless they disabled version with yargs.version(false).

[bcoe]

I think throwing an error is too heavy handed, as it would break a lot of applications. Here's what I would do:

1. emit a custom warning with a similar message to this, using the approach described here. We should make sure that we don't show it more than once, using the approach outlined in the docs.
2. I think we should turn off our own handling of .version() if someone configures it themselves, which the warning message can draw attention to.

What I'm not sure of, is whether we should call this a breaking change.

[jly36963]

Questions

• Would emitting a warning be sufficient? It would keep this from becoming a breaking change.
• I left process.emitWarning as a noop in the deno shim. Is there a deno equivalent that I can use instead?
• I left type and deduplicationID separate, so that process.emitWarning can be called without a type, but still prevent duplicate warnings. Does that make sense?
• I didn't know what values to use for type/deduplicationID -- can I get your suggestions?

[bcoe]

see comments.

[bcoe]

This seems like a really solid work to me 👍 , thank you. I'm sure we'll get additional usage out of emitWarning.

My only concern is if a major project, e.g., mocha, starts emitting on this warning, and we get a ton of users complaining on yargs.

I'm comfortable with shipping this, and keeping an eye on issues opened against yargs.