Add native response file support

Add native response file support in Swift Argument Parser for all
`ParsableCommand` and `AsyncParsableCommand` commands.

Since the nested response files are supported, also include an
experiemental command line argument that provides source location
support.

Fixes: #846

Author: bkhouri

CHANGELOG.md

@@ -6,6 +6,11 @@ Add new items at the end of the relevant section under **Unreleased**.
 
 ## [Unreleased]
 
+### Additions
+
+- Added source-location tracking for arguments expanded from response files. When at least one `@file` reference is present in the input, parser error messages now include a multi-line `at <file>:<line>` / `included from <file>:<line>` block that pinpoints the offending argument and its full include chain. For pure command-line invocations (no `@file`), error messages are unchanged.
+- Added the experimental `--experimental-dump-arguments-source-location` option. When present, the parser fully parses the command line and then prints every parsed argument together with its value and source location (file:line for response-file args, `argv[N]` for command-line args), organized as a subcommand tree. Accepts `=text` (default) or `=json`.
+
 ---
 
 ## [1.8.2] - 2026-06-04

README.md

@@ -68,6 +68,25 @@ OPTIONS:
   -h, --help              Show help for this command.
 ```
 
+## Response Files
+
+Swift Argument Parser automatically supports response files, which let you store command-line arguments in text files. This is especially useful for commands with many arguments or for reusable configurations:
+
+```bash
+# Store arguments in a file
+$ echo "--count 5 --include-counter hello" > args.txt
+
+# Use the response file with @filename syntax
+$ repeat @args.txt
+1: hello
+2: hello
+3: hello
+4: hello
+5: hello
+```
+
+Response files support multiple formats, comments, quoted arguments, and can even reference other response files. No code changes are required - this feature works automatically with any `ParsableCommand`. See the [Response Files documentation](https://swiftpackageindex.com/apple/swift-argument-parser/documentation/argumentparser/responsefiles) for complete details.
+
 ## Documentation
 
 For guides, articles, and API documentation see the

Sources/ArgumentParser/CMakeLists.txt

@@ -33,12 +33,14 @@ add_library(ArgumentParser
   Parsing/Parsed.swift
   Parsing/ParsedValues.swift
   Parsing/ParserError.swift
+  Parsing/ResponseFileExpander.swift
   Parsing/SplitArguments.swift
 
   Usage/DumpHelpGenerator.swift
   Usage/HelpCommand.swift
   Usage/HelpGenerator.swift
   Usage/MessageInfo.swift
+  Usage/SourceLocationDumpGenerator.swift
   Usage/UsageGenerator.swift
 
   Utilities/CollectionExtensions.swift

Sources/ArgumentParser/Documentation.docc/ArgumentParser.md

@@ -10,7 +10,7 @@ Begin by declaring a type that defines
 the information that you need to collect from the command line.
 Decorate each stored property with one of `ArgumentParser`'s property wrappers,
 declare conformance to ``ParsableCommand``,
-and implement your command's logic in its `run()` method. 
+and implement your command's logic in its `run()` method.
 For `async` renditions of `run`, declare ``AsyncParsableCommand`` conformance instead.
 
 ```swift
@@ -33,7 +33,7 @@ struct Repeat: ParsableCommand {
 }
 ```
 
-When a user executes your command, 
+When a user executes your command,
 the `ArgumentParser` library parses the command-line arguments,
 instantiates your command type,
 and then either calls your `run()` method or exits with a useful message.
@@ -58,6 +58,7 @@ and then either calls your `run()` method or exits with a useful message.
 ### Arguments, Options, and Flags
 
 - <doc:DeclaringArguments>
+- <doc:ResponseFiles>
 - ``Argument``
 - ``Option``
 - ``Flag``

Sources/ArgumentParser/Documentation.docc/Articles/ExperimentalFeatures.md

@@ -13,6 +13,7 @@ If you have any feedback on experimental features, please [open a GitHub issue][
 | Name | Description | related PRs | Version |
 | ------------- | ------------- | ------------- | ------------- |
 | `--experimental-dump-help`  | Dumps command/argument/help information as JSON | [#310][] [#335][] | 0.5.0 or newer |
+| `--experimental-dump-arguments-source-location`  | Dumps the parsed argument tree with each value's source location (file:line for response-file args, `argv[N]` for command-line args). Accepts `=text` (default) or `=json`. | — | 1.9.0 or newer |
 
 [#310]: https://github.com/apple/swift-argument-parser/pull/310
 [#335]: https://github.com/apple/swift-argument-parser/pull/335