feat(args): support a multiple modifier for arguments

[LandonSchropp]

Closes #258.

Adds an optional multiple?: boolean modifier to argument definitions. Combined with the existing required?: boolean, it covers the full cardinality matrix (both default to false, so the change is additive and non-breaking). It applies to string, enum, and positional args: repeated flags collect into an array and a multiple positional is variadic. Type inference flips to T[] accordingly, and usage output marks the repeatability.

See #258 for the full rationale, cardinality matrix, and examples.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds multiple support for repeatable string and enum options and variadic positional arguments, including typed array results, validation, required handling, usage rendering, documentation, and test coverage.

Changes

Multiple argument support

Layer / File(s)	Summary
Argument contracts and raw parsing src/types.ts, src/_parser.ts, test/parser.test.ts	Argument definitions and parsed types support multiple, while raw parsing collects repeated values with alias-aware handling and recursive coercion.
Argument validation and assignment src/args.ts, test/args.test.ts	Multiple options and positionals are assigned as arrays, enum values are validated, required cardinality is enforced, and variadic positionals must be last.
Usage rendering and documentation src/usage.ts, test/usage.test.ts, README.md	Usage output marks repeatable arguments with ..., and documentation describes multiple-value behavior and cardinality.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant parseArgs
  participant parseRawArgs
  participant Usage
  CLI->>parseArgs: provide argument definitions and argv
  parseArgs->>parseRawArgs: configure and parse multiple options
  parseRawArgs-->>parseArgs: return collected arrays
  parseArgs-->>CLI: return validated parsed arguments
  CLI->>Usage: render command usage
  Usage-->>CLI: show repeatable and variadic markers

Loading

Possibly related PRs

• unjs/citty#198: Shares the usage rendering and value-hint pipeline updated for repeatable argument notation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Implements the requested multiple modifier for flags and positionals, including arrays, final-only variadics, required handling, typing, and help output.
Out of Scope Changes check	✅ Passed	Changes stay within the multiple feature scope; the README and tests support the new parsing, typing, and usage behavior.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding a multiple modifier for arguments.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}