fix: prevent version name collision

lib/yargs-factory.ts

@@ -904,6 +904,21 @@ export class YargsInstance {
         opt = {};
       }
 
+      // Prevent version name collision
+      // Addresses: https://github.com/yargs/yargs/issues/1979
+      if (this.#versionOpt && (key === 'version' || opt?.alias === 'version')) {
+        throw new YError(
+          [
+            '"version" is a reserved word.',
+            'Please do one of the following:',
+            '- Disable version with `yargs.version(false)` if using "version" as an option',
+            '- Use the built-in `yargs.version` method instead (if applicable)',
+            '- Use a different option key',
+            'https://yargs.js.org/docs/#api-reference-version',
+          ].join('\n')
+        );
+      }
+
       this.#options.key[key] = true; // track manually set keys.
 
       if (opt.alias) this.alias(key, opt.alias);

test/usage.cjs

@@ -5,6 +5,7 @@
 const checkUsage = require('./helpers/utils.cjs').checkOutput;
 const chalk = require('chalk');
 const yargs = require('../index.cjs');
+const expect = require('chai').expect;
 const {YError} = require('../build/index.cjs');
 
 const should = require('chai').should();
@@ -1570,6 +1571,47 @@ describe('usage tests', () => {
       r.logs[0].should.eql('1.0.2');
     });
 
+    // Addresses: https://github.com/yargs/yargs/issues/1979
+    describe('when an option or alias "version" is set', () => {
+      it('fails unless version is disabled', done => {
+        yargs
+          .command('cmd1', 'cmd desc', yargs =>
+            yargs.option('v', {
+              alias: 'version',
+              describe: 'version desc',
+              type: 'string',
+            })
+          )
+          .fail(msg => {
+            msg.should.match(/reserved word/);
+            return done();
+          })
+          .wrap(null)
+          .parse('cmd1 --version 0.25.10');
+      });
+
+      it('works if version is disabled', () => {
+        yargs
+          .command(
+            'cmd1',
+            'cmd1 desc',
+            yargs =>
+              yargs.version(false).option('version', {
+                alias: 'v',
+                describe: 'version desc',
+                type: 'string',
+              }),
+            argv => {
+              argv.version.should.equal('0.25.10');
+            }
+          )
+          .fail(() => {
+            expect.fail();
+          })
+          .parse('cmd1 --version 0.25.10');
+      });
+    });
+
     describe('when exitProcess is false', () => {
       it('should not validate arguments (required argument)', () => {
         const r = checkUsage(() =>