yargs 17.7.3

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/yargs@17.7.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/yargs@17.7.3

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:f7d66ec09ac0a6b3ef14b5e978a4945944dc94c50ad575a8a03633025ecde7b4","contract":["yargs parses command line options with types, aliases, defaults, and descriptions","yargs enforces option requirements with demandOption and choices validation","yargs supports command routing with positional arguments and handler execution","yargs supports type coercion and custom validation via coerce and check","yargs provides parseSync and parse to synchronously or asynchronously extract parsed arguments"],"goal":"verify pkg:npm/yargs@17.7.3","kind":"HOW","packages":["pkg:npm/yargs@17.7.3"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/yargs@17.7.3"],"schemaVersion":1,"subject":"pkg:npm/yargs@17.7.3","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-yargs",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-yargs",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "yargs": "17.7.3"
      }
    },
    "node_modules/ansi-regex": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/ansi-styles": {
      "version": "4.3.0",
      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
      "license": "MIT",
      "dependencies": {
        "color-convert": "^2.0.1"
      },
      "engines": {
        "node": ">=8"
      },
      "funding": {
        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
      }
    },
    "node_modules/cliui": {
      "version": "8.0.1",
      "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
      "license": "ISC",
      "dependencies": {
        "string-width": "^4.2.0",
        "strip-ansi": "^6.0.1",
        "wrap-ansi": "^7.0.0"
      },
      "engines": {
        "node": ">=12"
      }
    },
    "node_modules/color-convert": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
      "license": "MIT",
      "dependencies": {
        "color-name": "~1.1.4"
      },
      "engines": {
        "node": ">=7.0.0"
      }
    },
    "node_modules/color-name": {
      "version": "1.1.4",
      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
      "license": "MIT"
    },
    "node_modules/emoji-regex": {
      "version": "8.0.0",
      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
      "license": "MIT"
    },
    "node_modules/escalade": {
      "version": "3.2.0",
      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
      "license": "MIT",
      "engines": {
        "node": ">=6"
      }
    },
    "node_modules/get-caller-file": {
      "version": "2.0.5",
      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
      "license": "ISC",
      "engines": {
        "node": "6.* || 8.* || >= 10.*"
      }
    },
    "node_modules/is-fullwidth-code-point": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
      "license": "MIT",
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/require-directory": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/string-width": {
      "version": "4.2.3",
      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
      "license": "MIT",
      "dependencies": {
        "emoji-regex": "^8.0.0",
        "is-fullwidth-code-point": "^3.0.0",
        "strip-ansi": "^6.0.1"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/strip-ansi": {
      "version": "6.0.1",
      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
      "license": "MIT",
      "dependencies": {
        "ansi-regex": "^5.0.1"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/wrap-ansi": {
      "version": "7.0.0",
      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
      "license": "MIT",
      "dependencies": {
        "ansi-styles": "^4.0.0",
        "string-width": "^4.1.0",
        "strip-ansi": "^6.0.0"
      },
      "engines": {
        "node": ">=10"
      },
      "funding": {
        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
      }
    },
    "node_modules/y18n": {
      "version": "5.0.8",
      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
      "license": "ISC",
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/yargs": {
      "version": "17.7.3",
      "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.3.tgz",
      "integrity": "sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==",
      "license": "MIT",
      "dependencies": {
        "cliui": "^8.0.1",
        "escalade": "^3.1.1",
        "get-caller-file": "^2.0.5",
        "require-directory": "^2.1.1",
        "string-width": "^4.2.3",
        "y18n": "^5.0.5",
        "yargs-parser": "^21.1.1"
      },
      "engines": {
        "node": ">=12"
      }
    },
    "node_modules/yargs-parser": {
      "version": "21.1.1",
      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
      "license": "ISC",
      "engines": {
        "node": ">=12"
      }
    }
  }
}

{
  "name": "sample-yargs",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification sample for yargs",
  "main": "src/index.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "yargs": "17.7.3"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/yargs@17.7.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/yargs@17.7.3"
  ]
}

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

function createParser(args) {
  return yargs(args)
    .exitProcess(false)
    .showHelpOnFail(false)
    .fail((msg, err) => {
      throw err || new Error(msg);
    });
}

function parseCliOptions(args) {
  return createParser(args)
    .option('port', {
      alias: 'p',
      type: 'number',
      default: 8080,
      describe: 'Port number to listen on'
    })
    .option('host', {
      alias: 'h',
      type: 'string',
      default: 'localhost',
      describe: 'Hostname to bind to'
    })
    .option('verbose', {
      alias: 'v',
      type: 'boolean',
      default: false,
      describe: 'Enable verbose logging'
    })
    .parseSync();
}

function parseWithCommands(args) {
  let executedCommand = null;
  let commandArgs = null;

  const parser = createParser(args)
    .command(
      'serve <dir>',
      'Start a file server',
      (y) => {
        return y.positional('dir', {
          type: 'string',
          describe: 'Directory to serve'
        }).option('port', {
          alias: 'p',
          type: 'number',
          default: 3000
        });
      },
      (argv) => {
        executedCommand = 'serve';
        commandArgs = argv;
      }
    )
    .command(
      'build [entry]',
      'Build project assets',
      (y) => {
        return y.positional('entry', {
          type: 'string',
          default: 'index.js'
        }).option('minify', {
          type: 'boolean',
          default: false
        });
      },
      (argv) => {
        executedCommand = 'build';
        commandArgs = argv;
      }
    );

  const argv = parser.parseSync();
  return { argv, executedCommand, commandArgs };
}

function parseWithValidation(args) {
  return createParser(args)
    .option('format', {
      type: 'string',
      choices: ['json', 'yaml', 'text'],
      demandOption: true
    })
    .option('count', {
      type: 'number',
      coerce: (val) => {
        const num = Number(val);
        if (isNaN(num) || num <= 0) {
          throw new Error('count must be a positive integer');
        }
        return num;
      }
    })
    .check((argv) => {
      if (argv.format === 'yaml' && argv.count > 100) {
        throw new Error('YAML format is limited to count <= 100');
      }
      return true;
    })
    .parseSync();
}

module.exports = {
  createParser,
  parseCliOptions,
  parseWithCommands,
  parseWithValidation
};

const assert = require('node:assert');
const yargs = require('yargs/yargs');
const {
  createParser,
  parseCliOptions,
  parseWithCommands,
  parseWithValidation
} = require('../src/index.js');

// 1. yargs parses command line options with types, aliases, defaults, and descriptions
{
  const defaultRes = parseCliOptions([]);
  assert.strictEqual(defaultRes.port, 8080, 'port should default to 8080');
  assert.strictEqual(defaultRes.host, 'localhost', 'host should default to localhost');
  assert.strictEqual(defaultRes.verbose, false, 'verbose should default to false');

  const customRes = parseCliOptions(['-p', '9000', '--host', '127.0.0.1', '-v']);
  assert.strictEqual(customRes.port, 9000, 'port should be parsed from alias -p');
  assert.strictEqual(customRes.p, 9000, 'alias p should match port value');
  assert.strictEqual(customRes.host, '127.0.0.1', 'host should be parsed from flag');
  assert.strictEqual(customRes.verbose, true, 'verbose should be true from alias -v');
  assert.strictEqual(customRes.v, true, 'alias v should match verbose value');
}

// 2. yargs enforces option requirements with demandOption and choices validation
{
  assert.throws(
    () => parseWithValidation([]),
    (err) => err.message.includes('Missing required argument: format'),
    'should fail when demanded option format is missing'
  );

  assert.throws(
    () => parseWithValidation(['--format', 'xml']),
    (err) => err.message.includes('Invalid values') && err.message.includes('format'),
    'should fail when value is not in allowed choices'
  );

  const validRes = parseWithValidation(['--format', 'json']);
  assert.strictEqual(validRes.format, 'json', 'valid format option should parse correctly');
}

// 3. yargs supports command routing with positional arguments and handler execution
{
  const serveRes = parseWithCommands(['serve', './public', '--port', '4000']);
  assert.strictEqual(serveRes.executedCommand, 'serve', 'serve command handler should have executed');
  assert.strictEqual(serveRes.commandArgs.dir, './public', 'positional argument dir should match');
  assert.strictEqual(serveRes.commandArgs.port, 4000, 'command option port should be 4000');

  const buildRes = parseWithCommands(['build', '--minify']);
  assert.strictEqual(buildRes.executedCommand, 'build', 'build command handler should have executed');
  assert.strictEqual(buildRes.commandArgs.entry, 'index.js', 'default positional entry should be index.js');
  assert.strictEqual(buildRes.commandArgs.minify, true, 'minify flag should be true');
}

// 4. yargs supports type coercion and custom validation via coerce and check
{
  assert.throws(
    () => parseWithValidation(['--format', 'json', '--count', '-5']),
    (err) => err.message.includes('count must be a positive integer'),
    'coerce should reject negative numbers'
  );

  assert.throws(
    () => parseWithValidation(['--format', 'yaml', '--count', '150']),
    (err) => err.message.includes('YAML format is limited to count <= 100'),
    'custom check should reject count > 100 for yaml format'
  );

  const validCustom = parseWithValidation(['--format', 'yaml', '--count', '42']);
  assert.strictEqual(validCustom.count, 42, 'count should be coerced to integer 42');
  assert.strictEqual(validCustom.format, 'yaml', 'format should be yaml');
}

// 5. yargs provides parseSync and parse to synchronously or asynchronously extract parsed arguments
{
  const syncArgv = createParser(['--debug', 'true'])
    .option('debug', { type: 'boolean' })
    .parseSync();
  assert.strictEqual(syncArgv.debug, true, 'parseSync should synchronously return argv');

  let asyncResult = null;
  createParser(['--timeout', '500'])
    .option('timeout', { type: 'number' })
    .parse(['--timeout', '500'], (err, argv, output) => {
      assert.strictEqual(err, null, 'parse callback error should be null');
      asyncResult = argv;
    });
  assert.notStrictEqual(asyncResult, null, 'asyncResult should be populated');
  assert.strictEqual(asyncResult.timeout, 500, 'parsed timeout should be 500');
}

console.log('All yargs contract tests passed successfully.');