Option Definition

/**
 * Define a command-line option
 * @param key - Option name or configuration object
 * @param opt - Option configuration
 * @returns YargsInstance for chaining
 */
option(key: string | Dictionary<OptionDefinition>, opt?: OptionDefinition): YargsInstance;

/**
 * Alias for option()
 */
options(key: string | Dictionary<OptionDefinition>, opt?: OptionDefinition): YargsInstance;

// Single option
yargs()
  .option('port', {
    alias: 'p',
    type: 'number',
    default: 3000,
    description: 'Port to bind on'
  })
  .parse();

// Multiple options object
yargs()
  .options({
    port: {
      alias: 'p',
      type: 'number',
      default: 3000,
      description: 'Port to bind on'
    },
    verbose: {
      alias: 'v',
      type: 'boolean',
      description: 'Enable verbose logging'
    }
  })
  .parse();

/**
 * Define option aliases
 * @param key - Option name, array of names, or alias map
 * @param value - Alias name(s) for the option
 * @returns YargsInstance for chaining
 */
alias(key: string | string[] | Dictionary<string | string[]>, value?: string | string[]): YargsInstance;

// Single alias
yargs()
  .option('verbose')
  .alias('verbose', 'v')
  .parse();

// Multiple aliases
yargs()
  .option('output')
  .alias('output', ['o', 'out'])
  .parse();

// Alias object
yargs()
  .alias({
    verbose: 'v',
    output: ['o', 'out'],
    help: 'h'
  })
  .parse();

/**
 * Mark options as arrays
 * @param keys - Option name(s) to treat as arrays
 * @returns YargsInstance for chaining
 */
array(keys: string | string[]): YargsInstance;

/**
 * Mark options as booleans
 * @param keys - Option name(s) to treat as booleans
 * @returns YargsInstance for chaining
 */
boolean(keys: string | string[]): YargsInstance;

/**
 * Mark options as numbers
 * @param keys - Option name(s) to treat as numbers
 * @returns YargsInstance for chaining
 */
number(keys: string | string[]): YargsInstance;

/**
 * Mark options as strings
 * @param keys - Option name(s) to treat as strings
 * @returns YargsInstance for chaining
 */
string(keys: string | string[]): YargsInstance;

/**
 * Mark options as counters (increment on each use)
 * @param keys - Option name(s) to treat as counters
 * @returns YargsInstance for chaining
 */
count(keys: string | string[]): YargsInstance;

yargs()
  .option('files', { description: 'Input files' })
  .array('files')                    // --files a.txt b.txt c.txt
  .option('verbose', { description: 'Verbose output' })
  .boolean('verbose')                // --verbose or --no-verbose
  .option('port', { description: 'Port number' })
  .number('port')                    // --port 3000
  .option('name', { description: 'Project name' })
  .string('name')                    // --name "My Project"
  .option('debug', { description: 'Debug level' })
  .count('debug')                    // -d -d -d or -ddd
  .parse();

/**
 * Set default values for options
 * @param key - Option name, array, or defaults object
 * @param value - Default value
 * @param defaultDescription - Description of default value
 * @returns YargsInstance for chaining
 */
default(key: string | string[] | Dictionary<any>, value?: any, defaultDescription?: string): YargsInstance;

/**
 * Alias for default()
 */
defaults(key: string | string[] | Dictionary<any>, value?: any, defaultDescription?: string): YargsInstance;

// Single default
yargs()
  .option('port')
  .default('port', 3000)
  .parse();

// Default with description
yargs()
  .option('config')
  .default('config', './config.json', 'default configuration file')
  .parse();

// Multiple defaults
yargs()
  .defaults({
    port: 3000,
    host: 'localhost',
    verbose: false
  })
  .parse();

// Function defaults (evaluated at parse time)
yargs()
  .default('timestamp', () => Date.now())
  .parse();

/**
 * Add descriptions for options
 * @param keys - Option name, array, or description map
 * @param description - Description text
 * @returns YargsInstance for chaining
 */
describe(keys: string | string[] | Dictionary<string>, description?: string): YargsInstance;

// Single description
yargs()
  .option('port')
  .describe('port', 'Port to bind the server on')
  .parse();

// Multiple descriptions
yargs()
  .describe({
    port: 'Port to bind the server on',
    verbose: 'Enable verbose logging',
    config: 'Path to configuration file'
  })
  .parse();

/**
 * Restrict option values to specific choices
 * @param key - Option name, array, or choices map
 * @param value - Array of valid choices
 * @returns YargsInstance for chaining
 */
choices(key: string | string[] | Dictionary<string | string[]>, value?: string | string[]): YargsInstance;

// Single choice restriction
yargs()
  .option('env')
  .choices('env', ['development', 'staging', 'production'])
  .parse();

// Multiple choice restrictions
yargs()
  .choices({
    env: ['development', 'staging', 'production'],
    log: ['error', 'warn', 'info', 'debug']
  })
  .parse();

/**
 * Transform option values using coercion functions
 * @param keys - Option name(s) or coercion map
 * @param value - Coercion function
 * @returns YargsInstance for chaining
 */
coerce(keys: string | string[] | Dictionary<CoerceCallback>, value?: CoerceCallback): YargsInstance;

// Single coercion
yargs()
  .option('date')
  .coerce('date', (arg) => new Date(arg))
  .parse();

// Multiple coercions
yargs()
  .coerce({
    port: (arg) => parseInt(arg, 10),
    tags: (arg) => Array.isArray(arg) ? arg : [arg],
    config: (arg) => JSON.parse(require('fs').readFileSync(arg, 'utf8'))
  })
  .parse();

// Array coercion
yargs()
  .option('files')
  .array('files')
  .coerce('files', (files) => files.map(f => path.resolve(f)))
  .parse();

/**
 * Specify number of arguments an option expects
 * @param key - Option name or nargs map
 * @param value - Number of arguments
 * @returns YargsInstance for chaining
 */
nargs(key: string | string[] | Dictionary<number>, value?: number): YargsInstance;

/**
 * Require options to have arguments
 * @param keys - Option name(s) that require arguments
 * @returns YargsInstance for chaining
 */
requiresArg(keys: string | string[] | Dictionary): YargsInstance;

/**
 * Normalize file paths
 * @param keys - Option name(s) to normalize as paths
 * @returns YargsInstance for chaining
 */
normalize(keys: string | string[]): YargsInstance;

/**
 * Hide options from help text
 * @param key - Option name to hide
 * @returns YargsInstance for chaining
 */
hide(key: string): YargsInstance;

/**
 * Skip validation for specific options
 * @param keys - Option name(s) to skip validation for
 * @returns YargsInstance for chaining
 */
skipValidation(keys: string | string[]): YargsInstance;

yargs()
  .option('coords', { description: 'X and Y coordinates' })
  .nargs('coords', 2)               // --coords 10 20
  
  .option('output', { description: 'Output file' })
  .requiresArg('output')            // --output requires a value
  
  .option('input', { description: 'Input file path' })
  .normalize('input')               // Normalizes file paths
  
  .option('secret', { description: 'API secret' })
  .hide('secret')                   // Hidden from help
  
  .option('raw', { description: 'Skip validation' })
  .skipValidation('raw')            // Skip validation for this option
  .parse();

/**
 * Option definition configuration
 */
interface OptionDefinition {
  alias?: string | string[];
  array?: boolean;
  boolean?: boolean;
  choices?: string | string[];
  coerce?: (arg: any) => any;
  config?: boolean;
  configParser?: (configPath: string) => object;
  conflicts?: string | string[];
  count?: boolean;
  default?: any;
  defaultDescription?: string;
  deprecate?: string | boolean;
  deprecated?: string | boolean;
  desc?: string;
  describe?: string;
  description?: string;
  demand?: string | true;
  demandOption?: string | true;
  global?: boolean;
  group?: string;
  hidden?: boolean;
  implies?: string | number | (string | number)[];
  nargs?: number;
  normalize?: boolean;
  number?: boolean;
  require?: string | true;
  required?: string | true;
  requiresArg?: boolean;
  skipValidation?: boolean;
  string?: boolean;
  type?: 'array' | 'boolean' | 'count' | 'number' | 'string';
}

/**
 * Coercion callback function
 */
type CoerceCallback = (arg: any) => any;

/**
 * Dictionary type for option maps
 */
type Dictionary<T = any> = { [key: string]: T };