apple/swift-argument-parser

This system is the Swift Argument Parser library, a framework for building command-line tools in Swift. It provides core capabilities for defining and parsing command-line arguments, flags, and subcommands, while supporting asynchronous execution. The system also includes features for generating shell completions, structured help documentation, and manual pages, along with tooling to introspect and serialize command metadata for external integration.

21 changes.

The project introduced asynchronous command execution via AsyncParsableCommand and expanded configuration options, while refactoring the internal parsing engine for better performance and error handling. Concurrently, the entire test suite was migrated from XCTest to the Swift Testing framework, and shell completion generation was added for Bash, Zsh, and Fish.

17 changes.

This period focused on expanding the project's tooling ecosystem by introducing utilities for generating Unix manual pages, DocC reference documentation, and changelog author lists. It also involved modernizing example commands to use Swift 5.10+ syntax and adding comprehensive snapshot tests to ensure the reliability of shell completions and documentation generation outputs.

A new Swift Package Manager plugin named GenerateDoccReference has been added to the project. This plugin generates DocC reference documentation, outputting to a directory named after the target with a .docc extension. It is implemented alongside the existing GenerateManual plugin, which continues to generate manual pages to a work directory, allowing users to choose between generating reference documentation or man pages via the respective plugins.

Plugins/GenerateManual · high confidence

A new command-line tool, \generate-manual\, has been added to the \Tools/generate-manual\ directory. This tool generates Unix manual pages for Swift Argument Parser-based tools by invoking them with the \--experimental-dump-help\ flag to capture tool information. Users can specify the target tool, output directory (or stdout), manual section, creation date, and authors. It supports generating either a single combined manual or separate pages for each subcommand via the \--multi-page\ flag.

Tools/generate-manual, Tools/generate-manual/Extensions · high confidence

A new command-line tool, \generate-docc-reference\, has been added to the \Tools\ directory. It accepts a Swift tool executable as input, runs it with the \--experimental-dump-help\ flag to retrieve command metadata, and generates a Markdown reference file. Users can choose between DocC-flavored and GitHub-flavored Markdown output styles, and the resulting documentation is saved to a specified directory or printed to standard output.

Tools/generate-docc-reference · high confidence

Two new executable shell scripts have been added to the Scripts directory to assist with development workflows. The new environment.sh script collects system details (Swift, Unix, macOS, and Xcode versions) and copies them to the clipboard for bug reports, while format.sh runs swift format in parallel to format and lint all Swift source files in the project.

Scripts · high confidence

Users can now define asynchronous command-line tools by conforming to the new AsyncParsableCommand protocol, which provides async main() and asyncParse() entry points. The CommandConfiguration struct has been expanded to support subcommand grouping via CommandGroup, command aliases, custom usage strings, help banners, and version flags. Additionally, the library now includes validators to ensure argument names are unique, coding keys are present, and positional arguments are correctly ordered, while error messages can be customized via \_errorPrefix.

Sources/ArgumentParser/Parsable Types · high confidence

The \Tools/generate-manual/DSL\ area now provides a structured, type-safe DSL for generating manual pages. This includes core components for building the document structure (such as \Document\, \Synopsis\, \Name\, and \Authors\), specialized renderers for single-page and multi-page descriptions, and an underlying \MDoc\ serialization layer that converts the abstract syntax tree into standard mdoc format.

Tools/generate-manual/DSL · high confidence

Adds the ArgumentParserToolInfo library, which provides a structured serialization format (ToolInfoV0) for command-line tool metadata. This enables external tools to programmatically inspect command structures, including commands, arguments, aliases, and completion kinds, via a standardized dump-help output.

Sources/ArgumentParserToolInfo · high confidence

A new command-line utility, \changelog-authors\, has been added to the project to help generate author information for changelogs. This tool queries the GitHub API to identify contributors between two release tags (or from a specific tag to the current head) and outputs a formatted list of author links along with their corresponding reference definitions, streamlining the process of crediting contributors in release notes.

Tools/changelog-authors · high confidence

Added a new example command in Examples/color that showcases how to provide descriptions for CaseEnumerable @Option values. The Color.swift file implements a ParsableCommand with two color options, demonstrating the use of the description property on ColorOptions enum cases to provide help text for users.

Examples/color · high confidence

Added a new \count-lines\ example command that counts lines in a file or standard input. The command supports an optional file path argument (defaulting to stdin), an optional prefix filter to count only lines starting with a specific string, and a verbose flag to include filename and prefix details in the output. It utilizes Swift's async/await capabilities via \AsyncParsableCommand\ and is available on macOS 12+, iOS 15+, visionOS 1+, tvOS 15+, and watchOS 8+.

Examples/count-lines · high confidence

Added a new example command, DefaultAsFlag, that illustrates how the defaultAsFlag attribute allows options to function as both flags and value-taking options. The example covers string, integer, and boolean types, as well as options with custom transforms, providing users with a concrete reference for implementing this feature in their own commands.

Examples/default-as-flag · high confidence

The library now generates shell completion scripts for Bash, Zsh, and Fish. This adds the \CompletionShell\ enum (with \.bash\, \.zsh\, and \.fish\ cases) and the \CompletionsGenerator\ struct, which produces the necessary shell functions and \complete\/\compdef\ directives based on the command's argument definitions. The implementation includes specific generators for each shell (\BashCompletionsGenerator\, \ZshCompletionsGenerator\, \FishCompletionsGenerator\) and handles escaping, option filtering, and custom completion calls appropriate for each environment.

Sources/ArgumentParser/Completions · high confidence

The TestHelpers module, which previously provided utility functions and extensions for testing Swift Argument Parser commands (such as AssertParse, AssertErrorMessage, and AssertExecuteCommand), has been removed from the codebase.

Sources/TestHelpers · high confidence

The example application now uses standard Swift default property initialization (e.g., \var times = 1\) instead of the previous \@Option(default: ...)\ syntax. This change simplifies the code by leveraging Swift's native default value capabilities for optional properties and flags, while also updating the verbose flag to use explicit short and long names (\-v --verbose\).

Examples/roll · high confidence

The build system now supports installing libraries to standard directories via new export configuration files (ArgumentParserConfig.cmake.in and CMakeLists.txt in cmake/modules). Additionally, Swift support has been expanded to include Apple Silicon (aarch64/arm64), RISC-V 64-bit, and other architectures through the updated SwiftSupport.cmake module, which handles host architecture detection and module triple installation.

cmake · high confidence

The ArgumentParserTestHelpers module now provides new testing utilities built on the Swift Testing framework, including \TestableSwiftTestingParsableArguments\, \TestableSwiftTestingParsableCommand\, and corresponding assertion functions like \expectErrorMessage\ and \expectParse\. The previous XCTest-based helpers (e.g., \TestableParsableArguments\, \AssertErrorMessage\) are now deprecated with migration messages directing users to the new Swift Testing equivalents. Additionally, a \requiresProcessExecution\ trait is introduced to skip tests on platforms where subprocess execution is unsupported.

Sources/ArgumentParserTestHelpers · high confidence

The ArgumentParser library now includes a new concurrency-safe Mutex implementation for cross-platform locking, a new Foundation abstraction layer that prefers FoundationEssentials, and several utility extensions. String handling has been updated to use StringProtocol for wrapping, with a simplified and more efficient snake-case conversion algorithm and a new edit-distance calculation for suggestions. Additionally, the command tree initialization now explicitly prevents recursive subcommands and aliases that match the command name, and collection extensions have been refactored for better reusability.

Sources/ArgumentParser/Utilities · high confidence

The help system in Sources/ArgumentParser/Usage has been significantly refactored to improve output quality and add new programmatic capabilities. A new \DumpHelpGenerator\ has been introduced to produce structured JSON output via a \--dump-help\ flag, enabling external tooling to inspect command definitions. Help display behavior has changed: the \HelpCommand\ now supports a \--help-hidden\ flag to reveal private arguments, respects terminal dimensions via \COLUMNS\/\LINES\ environment variables, and ignores extra help flags passed alongside the help subcommand. Error messages have been enhanced to include usage context and help abstracts when validation fails, and the \HelpGenerator\ now supports titled option groups and better formatting for enumerated option values. Additionally, usage synopsis generation has been optimized to handle commands with many options by filtering optional arguments when necessary.

Sources/ArgumentParser/Usage · high confidence

The Math example has been updated to use modern Swift syntax, including the @main entry point, let bindings for immutable configurations, and explicit default values for arguments and flags. It now exposes a version number (1.0.0) for automatic --version support and adds an alias (mul) for the Multiply subcommand. Additionally, the run methods for subcommands are now marked mutating to align with current ArgumentParser requirements.

Examples/math · high confidence

This update introduces the @ParentCommand property wrapper, allowing child commands to access the state of their parent command without duplicating arguments in help screens. It also refines help display control by replacing the boolean shouldDisplay flag with a three-level ArgumentVisibility enum (default, hidden, private) on ArgumentHelp and OptionGroup, and adds an ArgumentDiscussion type to support richer, enumerated descriptions for ExpressibleByArgument types in help output.

Sources/ArgumentParser/Parsable Properties · high confidence

The plugin implementation has been restructured to extract common generation logic into a new shared module (Plugins/GenerateCommon). This change introduces a \GeneratePlugin\ protocol and helper extensions that standardize how plugins build the package, locate executable artifacts, and spawn the generation tool, ensuring consistent behavior across different plugin commands.

Plugins/GenerateCommon · high confidence

The argument parsing engine has been refactored to improve performance and error reporting. The internal \ArgumentSet\ storage is now a flat array, replacing the previous nested structure, which simplifies iteration and improves parsing speed. \InputKey\ handling has been updated to preserve leading underscores in coding keys, ensuring accurate field mapping for nested option groups. The \ArgumentDecoder\ now distinguishes between values provided via command-line arguments and those derived from property defaults using a new \DecodedArguments\ structure and \InputOrigin.defaultValue\ tracking, preventing incorrect overwrites of default values. Additionally, the parser now provides more specific error messages for unknown options and handles built-in flags like \--help\ and \--version\ with greater precision, including support for hidden visibility levels.

Sources/ArgumentParser/Parsing · high confidence

The Repeat example has been refactored to provide a better default user experience: the optional \count\ argument now defaults to 2 instead of using the maximum integer value, preventing the previous behavior of endless printing when no count is specified. Additionally, the command now uses the \@main\ attribute for its entry point, simplifying the code structure by removing the explicit \Repeat.main()\ call.

Examples/repeat · high confidence

This update introduces the release notes for version 1.8.0, which adds a \helpBanner\ to \CommandConfiguration\, allows \@Option\ defaults to be specified as flags via \defaultAsFlag:\, enables \async\/\await\ for custom completions in \AsyncParsableCommand\, and simplifies name declarations with \ExpressibleByStringLiteral\ conformance. It also raises the minimum supported Swift version to 6.0. The entry includes new project configuration files (\.editorconfig\, \.swift-format\, \.spi.yml\) and updates the README to reflect the new \@main\ attribute requirement, updated example paths, and the new minimum version requirements.

(repo-wide) · high confidence

Add snapshot tests for Docc and Markdown reference generation; Added end-to-end tests for Swift Argument Parser using Swift Testing; Added snapshot tests for manual page generation; Added test snapshots for shell completions and help dump output; Added tests for ArgumentParser command definitions and options; Added tests for ToolInfoV0 JSON decoding; Initial import of end-to-end tests for Swift Argument Parser; Migrate ArgumentParser unit tests to Swift Testing; Migrate ArgumentParserPackageManagerTests to Swift Testing; Migrate example tests to Swift Testing; Removed MathExampleTests; Removed legacy unit test suite for ArgumentParser; Snapshot tests for shell completion scripts.

A dependency / build maintenance change in (dependencies) — 22 commits (4 fixs), 1 file.

(dependencies) · medium confidence · unverified

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 63 → 61 (-2.4)
• Rubric changed (rubric-2026.09.11 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 91 → 90 (-1.1)
• Architecture 58 → 86 (+27.8)
• Maturity 58 → 54 (-3.6)
• Readiness 69 → 52 (-16.3)
• Security 80 → 80 (+0.0)

• Documentation: no installation or build instructions (README.md)
• Documentation: no licence statement (README.md)
• Documentation: no usage examples (README.md)
• Duplicated block (9 lines × 4) (Sources/ArgumentParser/Parsable Properties/Argument.swift)
• Duplicated block (9 lines × 4) (Sources/ArgumentParser/Parsable Properties/Argument.swift)
• Duplicated block (9 lines × 6) (Sources/ArgumentParser/Parsable Properties/Argument.swift)
• Off-boarding risk: anonymized user #1

• CommandInfoV0.completionFunctions (cognitive 16) (Sources/ArgumentParserToolInfo/ToolInfo.swift)
• Duplicated block (10–11 lines × 3) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (11 lines × 2) (Sources/ArgumentParser/Usage/HelpGenerator.swift)
• Duplicated block (12 lines × 2) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (13 lines × 2) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (15–22 lines × 3) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (17–19 lines × 2) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (20 lines × 2) (Tools/generate-manual/DSL/MultiPageDescription.swift)
• Duplicated block (21 lines × 2) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (26–27 lines × 3) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (6 lines × 2) (Sources/ArgumentParserTestHelpers/TestHelpers.swift)
• Duplicated block (8 lines × 5) (Sources/ArgumentParser/Parsable Properties/Argument.swift)
• Duplicated block (9 lines × 2) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (9 lines × 2) (Sources/ArgumentParserTestHelpers/TestHelpers+SwiftTesting.swift)
• Duplicated block (9 lines × 2) (Tools/generate-docc-reference/GenerateDoccReference.swift)
• Duplicated block (9 lines × 4) (Sources/ArgumentParser/Parsable Properties/Argument.swift)
• Duplicated block (9 lines × 4) (Sources/ArgumentParser/Parsable Properties/Argument.swift)
• Duplicated block (9 lines × 6) (Sources/ArgumentParser/Parsable Properties/Argument.swift)
• Low cohesion: StringProtocol (LCOM4 6) (Sources/ArgumentParser/Utilities/StringExtensions.swift)
• Low coverage: Sources/ArgumentParser/Parsable Types/AsyncParsableCommand.swift (Sources/ArgumentParser/Parsable Types/AsyncParsableCommand.swift)
• …and 22 more

• 4 commits — 3 feature/other, 1 fixes

• Sources/ArgumentParser — 2 commits
• (root) — 1 commit
• Sources/ArgumentParserTestHelpers — 1 commit

• fix: Fix --opt= silently consuming the next positional token (#961)
• change: Call validate() only once when parsing via ParsableArguments.parse(_:) (#970)
• change: Migrate subcommand end-to-end validation test to Swift Testing (#964)
• change: Replace CODE_OF_CONDUCT with the org-wide version (#978)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

apple/swift-argument-parser was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.