clap-ts 0.3.0 → 0.4.0

package/src/__tests__/validation.test.ts

@@ -0,0 +1,267 @@
+/**
+ * Validation tests - tests for constraint enforcement after parsing.
+ */
+
+import { describe, test, expect } from 'bun:test';
+import { parseArgs } from '../parser.js';
+import { validate } from '../validation.js';
+import type { CommandDef, ArgsDef } from '../types.js';
+
+/** Helper to create a CommandDef from ArgsDef for testing. */
+function cmd(args: ArgsDef): CommandDef {
+  return { meta: { name: 'test' }, args };
+}
+
+/** Parse and validate in one step. */
+function parseAndValidate(rawArgs: string[], command: CommandDef): void {
+  const result = parseArgs(rawArgs, command);
+  validate(result, command);
+}
+
+// ---- Required Args Missing ----
+
+describe('required args missing', () => {
+  test('throws when required arg is not provided', () => {
+    const command = cmd({ port: { type: 'number', required: true } });
+    expect(() => parseAndValidate([], command)).toThrow('required arguments were not provided');
+  });
+
+  test('required arg with default does not throw', () => {
+    const command = cmd({ port: { type: 'number', required: true, default: 3000 } });
+    expect(() => parseAndValidate([], command)).not.toThrow();
+  });
+
+  test('required positional throws', () => {
+    const command = cmd({
+      file: { type: 'positional', valueName: 'FILE', required: true },
+    });
+    expect(() => parseAndValidate([], command)).toThrow('required arguments were not provided');
+  });
+
+  test('required arg provided does not throw', () => {
+    const command = cmd({ port: { type: 'number', required: true } });
+    expect(() => parseAndValidate(['--port', '3003'], command)).not.toThrow();
+  });
+});
+
+// ---- conflictsWith Violation ----
+
+describe('conflictsWith violation', () => {
+  test('throws when conflicting args are both provided', () => {
+    const command = cmd({
+      json: { type: 'boolean', conflictsWith: ['csv'] },
+      csv: { type: 'boolean' },
+    });
+    expect(() => parseAndValidate(['--json', '--csv'], command)).toThrow('cannot be used with');
+  });
+
+  test('does not throw when only one is provided', () => {
+    const command = cmd({
+      json: { type: 'boolean', conflictsWith: ['csv'] },
+      csv: { type: 'boolean' },
+    });
+    expect(() => parseAndValidate(['--json'], command)).not.toThrow();
+  });
+
+  test('does not throw when neither is provided', () => {
+    const command = cmd({
+      json: { type: 'boolean', conflictsWith: ['csv'] },
+      csv: { type: 'boolean' },
+    });
+    expect(() => parseAndValidate([], command)).not.toThrow();
+  });
+});
+
+// ---- requires Violation ----
+
+describe('requires violation', () => {
+  test('throws when required companion is missing', () => {
+    const command = cmd({
+      'tls-cert': { type: 'string', long: 'tls-cert', requires: ['tls'] },
+      tls: { type: 'boolean' },
+    });
+    expect(() => parseAndValidate(['--tls-cert', './cert.pem'], command)).toThrow(
+      'required arguments were not provided',
+    );
+  });
+
+  test('does not throw when companion is present', () => {
+    const command = cmd({
+      'tls-cert': { type: 'string', long: 'tls-cert', requires: ['tls'] },
+      tls: { type: 'boolean' },
+    });
+    expect(() => parseAndValidate(['--tls-cert', './cert.pem', '--tls'], command)).not.toThrow();
+  });
+
+  test('does not throw when the arg itself is not provided', () => {
+    const command = cmd({
+      'tls-cert': { type: 'string', long: 'tls-cert', requires: ['tls'] },
+      tls: { type: 'boolean' },
+    });
+    expect(() => parseAndValidate([], command)).not.toThrow();
+  });
+});
+
+// ---- valueParser Enum Violation ----
+
+describe('valueParser enum violation', () => {
+  test('throws on invalid enum value', () => {
+    const command = cmd({
+      env: { type: 'string', valueParser: ['dev', 'staging', 'prod'] },
+    });
+    expect(() => parseAndValidate(['--env', 'invalid'], command)).toThrow(
+      "invalid value 'invalid'",
+    );
+  });
+
+  test('error message includes possible values', () => {
+    const command = cmd({
+      env: { type: 'string', valueParser: ['dev', 'staging', 'prod'] },
+    });
+    try {
+      parseAndValidate(['--env', 'invalid'], command);
+      expect.unreachable('should have thrown');
+    } catch (error) {
+      expect((error as Error).message).toContain('possible values: dev, staging, prod');
+    }
+  });
+
+  test('valid enum value passes', () => {
+    const command = cmd({
+      env: { type: 'string', valueParser: ['dev', 'staging', 'prod'] },
+    });
+    expect(() => parseAndValidate(['--env', 'dev'], command)).not.toThrow();
+  });
+});
+
+// ---- Typo Suggestions (Levenshtein) ----
+
+describe('typo suggestions', () => {
+  test('suggests close match for typo', () => {
+    const command = cmd({
+      verbose: { type: 'boolean' },
+    });
+    const result = parseArgs(['--verbos'], command);
+    try {
+      validate(result, command);
+      expect.unreachable('should have thrown');
+    } catch (error) {
+      const msg = (error as Error).message;
+      expect(msg).toContain("unexpected argument '--verbos' found");
+      expect(msg).toContain('tip: a similar argument exists');
+      expect(msg).toContain('verbose');
+    }
+  });
+
+  test('no suggestion when distance is too large', () => {
+    const command = cmd({
+      verbose: { type: 'boolean' },
+    });
+    const result = parseArgs(['--xyzzy'], command);
+    try {
+      validate(result, command);
+      expect.unreachable('should have thrown');
+    } catch (error) {
+      const msg = (error as Error).message;
+      expect(msg).toContain("unexpected argument '--xyzzy' found");
+      expect(msg).not.toContain('tip');
+    }
+  });
+});
+
+// ---- numArgs Validation ----
+
+describe('numArgs validation', () => {
+  test('respects min constraint', () => {
+    const command = cmd({
+      files: {
+        type: 'string',
+        action: 'append',
+        numArgs: { min: 2, max: 10 },
+      },
+    });
+    expect(() => parseAndValidate(['--files', 'a.txt'], command)).toThrow(
+      'requires at least 2 values',
+    );
+  });
+});
+
+describe('exclusive', () => {
+  test('exclusive arg cannot be used with any other', () => {
+    const command = cmd({
+      init: { type: 'boolean', long: 'init', exclusive: true },
+      verbose: { type: 'boolean', long: 'verbose' },
+    });
+    expect(() => parseAndValidate(['--init', '--verbose'], command)).toThrow(
+      /cannot be used with/,
+    );
+  });
+
+  test('exclusive arg alone is fine', () => {
+    const command = cmd({
+      init: { type: 'boolean', long: 'init', exclusive: true },
+      verbose: { type: 'boolean', long: 'verbose' },
+    });
+    expect(() => parseAndValidate(['--init'], command)).not.toThrow();
+  });
+});
+
+describe('requiredUnlessPresent', () => {
+  test('not required when alternative is present', () => {
+    const command = cmd({
+      file: { type: 'string', long: 'file', required: true, requiredUnlessPresent: 'stdin' },
+      stdin: { type: 'boolean', long: 'stdin' },
+    });
+    expect(() => parseAndValidate(['--stdin'], command)).not.toThrow();
+  });
+
+  test('required when alternative is absent', () => {
+    const command = cmd({
+      file: { type: 'string', long: 'file', required: true, requiredUnlessPresent: 'stdin' },
+      stdin: { type: 'boolean', long: 'stdin' },
+    });
+    expect(() => parseAndValidate([], command)).toThrow('required arguments');
+  });
+
+  test('works with array of alternatives', () => {
+    const command = cmd({
+      file: {
+        type: 'string',
+        long: 'file',
+        required: true,
+        requiredUnlessPresent: ['stdin', 'generate'],
+      },
+      stdin: { type: 'boolean', long: 'stdin' },
+      generate: { type: 'boolean', long: 'generate' },
+    });
+    expect(() => parseAndValidate(['--generate'], command)).not.toThrow();
+  });
+});
+
+describe('requiredIfEq', () => {
+  test('required when condition met', () => {
+    const command = cmd({
+      format: { type: 'string', long: 'format' },
+      output: { type: 'string', long: 'output', requiredIfEq: ['format', 'file'] },
+    });
+    expect(() => parseAndValidate(['--format', 'file'], command)).toThrow('required arguments');
+  });
+
+  test('not required when condition not met', () => {
+    const command = cmd({
+      format: { type: 'string', long: 'format' },
+      output: { type: 'string', long: 'output', requiredIfEq: ['format', 'file'] },
+    });
+    expect(() => parseAndValidate(['--format', 'stdout'], command)).not.toThrow();
+  });
+
+  test('passes when arg is provided', () => {
+    const command = cmd({
+      format: { type: 'string', long: 'format' },
+      output: { type: 'string', long: 'output', requiredIfEq: ['format', 'file'] },
+    });
+    expect(() =>
+      parseAndValidate(['--format', 'file', '--output', '/tmp/out'], command),
+    ).not.toThrow();
+  });
+});

package/src/argfile.ts

@@ -0,0 +1,188 @@
+/**
+ * Response files and stdin, the `@file` convention git, gcc and java use for
+ * command lines too long to type or to pass through the shell's ARG_MAX.
+ *
+ * ```ts
+ * import { expandArgFiles, readStdin } from 'clap-ts/argfile';
+ *
+ * await runMain(main, { argv: expandArgFiles() });
+ * ```
+ *
+ * clap has no equivalent, so the shape here follows gcc: one argument per line,
+ * `#` comments and blank lines skipped, quoted runs kept together, and a
+ * literal `@` escaped as `@@`.
+ */
+
+import { readFileSync } from 'node:fs';
+import { getRawArgs } from './parser.js';
+
+export interface ArgFileOptions {
+  /** Prefix marking a response file (default '@'). */
+  readonly prefix?: string;
+  /** How deep a response file may reference another (default 5). */
+  readonly maxDepth?: number;
+  /** Read a file's text. Defaults to reading UTF-8 from disk. */
+  readonly read?: (path: string) => string;
+}
+
+/**
+ * Split response-file text into arguments.
+ *
+ * Whitespace separates, `#` at the start of a line comments the rest of it out,
+ * and single or double quotes group a run containing spaces. A backslash
+ * escapes the next character inside or outside quotes.
+ */
+export function parseArgFile(text: string): string[] {
+  const args: string[] = [];
+  let current = '';
+  let quote: '"' | "'" | undefined;
+  let hasToken = false;
+
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+
+    if (ch === '\\' && i + 1 < text.length) {
+      current += text[i + 1]!;
+      hasToken = true;
+      i++;
+      continue;
+    }
+
+    if (quote !== undefined) {
+      if (ch === quote) {
+        quote = undefined;
+      } else {
+        current += ch;
+      }
+      continue;
+    }
+
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      hasToken = true;
+      continue;
+    }
+
+    // A comment runs to the end of its line, and only starts a token boundary.
+    if (ch === '#' && !hasToken) {
+      while (i < text.length && text[i] !== '\n') {
+        i++;
+      }
+      continue;
+    }
+
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+      if (hasToken) {
+        args.push(current);
+        current = '';
+        hasToken = false;
+      }
+      continue;
+    }
+
+    current += ch;
+    hasToken = true;
+  }
+
+  if (quote !== undefined) {
+    throw new Error(`unterminated ${quote === '"' ? 'double' : 'single'} quote in response file`);
+  }
+  if (hasToken) {
+    args.push(current);
+  }
+  return args;
+}
+
+/**
+ * Replace every `@file` in argv with that file's arguments.
+ *
+ * Reads `process.argv` when given nothing. A response file may reference
+ * another up to `maxDepth`; `@@` is a literal argument starting with `@`, and
+ * everything after a bare `--` is left alone.
+ */
+export function expandArgFiles(
+  argv: readonly string[] = getRawArgs(),
+  opts?: ArgFileOptions,
+): string[] {
+  const prefix = opts?.prefix ?? '@';
+  const maxDepth = opts?.maxDepth ?? 5;
+  const read = opts?.read ?? ((path: string) => readFileSync(path, 'utf8'));
+
+  const expand = (tokens: readonly string[], depth: number): string[] => {
+    const out: string[] = [];
+    let escaped = false;
+
+    for (const token of tokens) {
+      if (escaped || !token.startsWith(prefix) || token.length === prefix.length) {
+        out.push(token);
+        if (token === '--') {
+          escaped = true;
+        }
+        continue;
+      }
+
+      // `@@file` means a literal argument that happens to start with `@`.
+      if (token.startsWith(prefix + prefix)) {
+        out.push(token.slice(prefix.length));
+        continue;
+      }
+
+      if (depth >= maxDepth) {
+        throw new Error(`response files nested more than ${String(maxDepth)} deep at '${token}'`);
+      }
+
+      const path = token.slice(prefix.length);
+      let text: string;
+      try {
+        text = read(path);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`cannot read response file '${path}': ${message}`);
+      }
+      out.push(...expand(parseArgFile(text), depth + 1));
+    }
+
+    return out;
+  };
+
+  return expand(argv, 0);
+}
+
+/**
+ * Read all of stdin as text, for the `-` convention meaning "read from stdin".
+ *
+ * Resolves to undefined when stdin is a terminal, so an interactive run does
+ * not hang waiting for input that is never coming.
+ */
+export async function readStdin(): Promise<string | undefined> {
+  if (process.stdin.isTTY === true) {
+    return undefined;
+  }
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+/**
+ * Resolve a path argument, reading stdin when it is `-`.
+ *
+ * ```ts
+ * const source = await readPathOrStdin(args.input);
+ * ```
+ */
+export async function readPathOrStdin(
+  path: string,
+  opts?: { readonly read?: (path: string) => string },
+): Promise<string> {
+  if (path === '-') {
+    const text = await readStdin();
+    if (text === undefined) {
+      throw new Error('reading from stdin was requested but stdin is a terminal');
+    }
+    return text;
+  }
+  const read = opts?.read ?? ((p: string) => readFileSync(p, 'utf8'));
+  return read(path);
+}