Core Parser Configuration

/**
 * Creates a new yargs parser instance
 * @param processArgs - Arguments to parse (default: [])
 * @param cwd - Current working directory  
 * @param parentRequire - Parent require function
 * @returns YargsInstance for method chaining
 */
function yargs(processArgs?: string | string[], cwd?: string, parentRequire?: Function): YargsInstance;

import yargs from 'yargs';
import { hideBin } from 'yargs/helpers';

// Parse process.argv (most common)
const argv1 = yargs(hideBin(process.argv)).parse();

// Parse custom arguments
const argv2 = yargs(['--port', '3000', '--verbose']).parse();

// Parse with custom working directory
const argv3 = yargs(hideBin(process.argv), '/custom/path').parse();

/**
 * Set custom script name (overrides automatic detection)
 * @param scriptName - Custom script name to display
 * @returns YargsInstance for chaining
 */
scriptName(scriptName: string): YargsInstance;

yargs()
  .scriptName('my-tool')
  .help()
  .parse();
// Help will show "my-tool [options]" instead of auto-detected name

/**
 * Configure parser behavior with advanced options
 * @param config - Parser configuration object
 * @returns YargsInstance for chaining
 */
parserConfiguration(config: Configuration): YargsInstance;

yargs()
  .parserConfiguration({
    'duplicate-arguments-array': false,
    'flatten-duplicate-arrays': true,
    'populate--': true,
    'set-placeholder-key': true,
    'halt-at-non-option': false,
    'strip-aliased': false,
    'strip-dashed': false,
    'boolean-negation': true,
    'camel-case-expansion': true,
    'deep-merge-config': false,
    'sort-commands': false
  })
  .parse();

/**
 * Get current terminal width
 * @returns Terminal width in columns or null
 */
terminalWidth(): number | null;

/**
 * Set wrap width for help text formatting
 * @param cols - Number of columns to wrap at, or null for no wrapping
 * @returns YargsInstance for chaining
 */
wrap(cols: number | null): YargsInstance;

const width = yargs().terminalWidth();
console.log(`Terminal width: ${width}`);

// Force wrap at 80 columns
yargs()
  .wrap(80)
  .help()
  .parse();

// Disable wrapping
yargs()
  .wrap(null)
  .help()
  .parse();

/**
 * Control whether yargs calls process.exit() on completion
 * @param enabled - Whether to exit process (default: true)
 * @returns YargsInstance for chaining
 */
exitProcess(enabled?: boolean): YargsInstance;

/**
 * Get current exit process setting
 * @returns Whether yargs will exit the process
 */
getExitProcess(): boolean;

// Disable process exit (useful for testing)
yargs()
  .exitProcess(false)
  .help()
  .parse();

// Check current setting
const willExit = yargs().getExitProcess();

/**
 * Load configuration from package.json
 * @param key - Key in package.json to read config from
 * @param rootPath - Root path for package.json search
 * @returns YargsInstance for chaining
 */
pkgConf(key: string, rootPath?: string): YargsInstance;

// Load config from package.json "myapp" field
yargs()
  .pkgConf('myapp')
  .parse();

// package.json:
// {
//   "myapp": {
//     "port": 3000,
//     "verbose": true
//   }
// }

/**
 * Parser configuration options
 */
interface Configuration {
  /** Create array for duplicate arguments */
  'duplicate-arguments-array'?: boolean;
  /** Flatten duplicate arrays */
  'flatten-duplicate-arrays'?: boolean;
  /** Populate -- with remaining args */
  'populate--'?: boolean;
  /** Set placeholder key for missing options */
  'set-placeholder-key'?: boolean;
  /** Stop parsing at first non-option */
  'halt-at-non-option'?: boolean;
  /** Remove aliased keys from result */
  'strip-aliased'?: boolean;
  /** Remove dashed keys from result */
  'strip-dashed'?: boolean;
  /** Enable --no-flag negation */
  'boolean-negation'?: boolean;
  /** Convert kebab-case to camelCase */
  'camel-case-expansion'?: boolean;
  /** Deep merge config objects */
  'deep-merge-config'?: boolean;
  /** Sort commands in help */
  'sort-commands'?: boolean;
  /** Parse positional numbers */
  'parse-positional-numbers'?: boolean;
}