Positional commands are not working as excpected

[ChiefORZ]

Hello,

we just came across following issue and we did not manage to find a solution of what we are doing wrong - maybe somebody can help us:

const yargs = require('yargs/yargs');

describe('use-version', () => {
  it('positional command with builder object should be parsed', async () => {
    const parser = yargs(['use-version', 'latest', '--dry-run'])
      .command([
        {
          command: 'use-version <version>',
          describe:
            'Use a specific npm tagged version throughout the current project (e.g. canary, latest, workspace)',
          builder: {
            version: {
              describe: 'The npm tag to update to',
              type: 'string',
              // choices: ['canary', 'latest', 'workspace'],
            },
          },
          handler: (args) => args,
        },
      ])
      .help();
    expect(parser.argv.version).toBe('latest');
  });

  it('positional command with builder function should be parsed', async () => {
    const parser = yargs(['use-version', 'latest', '--dry-run'])
      .command([
        {
          command: 'use-version <version>',
          describe:
            'Use a specific npm tagged version throughout the current project (e.g. canary, latest, workspace)',
          builder: (instance) => {
            instance.positional('version', {
              describe: 'The npm tag to update to',
              type: 'string',
              // choices: ['canary', 'latest', 'workspace'],
            });
          },
          handler: (args) => args,
        },
      ])
      .help();
    expect(parser.argv.version).toBe('latest');
  });
});

The positional command version should be parsed in both szenarios, but it gets parsed as false... and the _ array of the results does not dontain "latest" anymore...

{
  "_": [ "use-version" ],
  "dry-run": true,
  "dryRun": true,
  "version": false
}

For explanation, we are using a a commands/index.js where we import all commands - thats why we use the command([]) notation as mentioned in https://github.com/yargs/yargs/blob/master/docs/advanced.md#providing-a-command-module

// commands/index.js
import * as csv from './csv';
import * as pdf from './pdf';

export const commands = [csv, pdf];

// index.js
import { commands } from './commands'

yargs(hideBin(process.argv))
    .command(commands)
    .parse();

[jly36963]

I believe the issue is with using "version".
I made a PR to help address this.
I think the solution is to disable version with yargs.version(false) if using "version" as an option.
yargs uses version internally, and it causes conflicts unless disabled.

I added a unit test titled "does not emit warning if version is disabled" in that PR. Hopefully that can be used as an example of how to make "version" work.

[ChiefORZ]

Yeah, that was actually the issue.

One more note on this side - i did not get the warning even though i was testing this with the latest version 17.1.1. Could it be that the warning is only ommited, when version is defined as an option field, and not when it is defined as an positional parameter? https://github.com/yargs/yargs/blob/master/lib/yargs-factory.ts#L911 i think this block needs to be executed in the positional method as well ;)

[jly36963]

Yeah, I will need to make sure that both positionals and options trigger this warning (and add the missing unit tests for those cases)

[jly36963]

@ChiefORZ
Hey, sorry for the delay -- I've been pretty busy.

It looks like my PR was merged and then released in yargs 17.2.0 -- that's why it wasn't working for you. Try the latest version and you should see the warning.

The warning will be emitted if version is used either as an option or positional argument.

I tested this locally and the expected warning was emitted:

yargs()
  .command(
    "cmd1 <version>",
    "cmd1 desc",
    (yargs) =>
      yargs.positional("version", {
        describe: "version description",
        type: "string",
      }),
    (argv) => {
      console.log({ argv });
    }
  )
  .parse("cmd1 0.25.10");

Warning: "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