`swift package plugin` argument processing is confusingly sensitive to argument order

[euanh]

Is it reproducible with SwiftPM command-line tools: swift build, swift test, swift package etc?

• Confirmed reproduction steps with SwiftPM CLI. The description text must include reproduction steps with either of command-line SwiftPM commands, swift build, swift test, swift package etc.

Description

Possibly the same as #8418.

The plugin subcommand is optional, but some of the arguments in a typical plugin command are handled by swift, some by the package subcommand and others by the plugin sub-subcommand. Although these flags have unique names, the order they are presented on the command line must match the order of the subcommands. Specifying a flag for package after specifying one for plugin is an error. This can be very confusing for users.

Expected behavior

Order of swift package arguments should not be significant, unless specifically documented in the help.
Error messages should explain argument order more helpfully.

Actual behavior

Order of arguments is significant. Changing the order, or adding a new argument in the wrong place, can cause a command which currently works to fail with an error.

Steps to reproduce

-Xswiftc is handled by swift package; --allow-network-connections is handled by swift package plugin, but writing plugin is optional so the argument list appears to be one unbroken list. Many users will be surprised to find that the ordering of such an argument list is significant.

bash-5.1# swift package init --type executable
bash-5.1# swift package -Xswiftc -static-stdlib --allow-network-connections all build-container-image --repository localhost:5555/example
Building for debugging...
...

Swapping -Xswiftc and --allow-network-connections makes this fail:

bash-5.1# swift package --allow-network-connections all -Xswiftc -static-stdlib build-container-image --repository localhost:5555/example
error: Unknown option '-Xswiftc'
Usage: swift package default-command [--allow-writing-to-package-directory] [--allow-writing-to-directory <allow-writing-to-directory> ...] [--allow-network-connections <allow-network-connections>] [--package <package>] [<remaining> ...]
  See 'package default-command -help' for more information.

Swift Package Manager version/commit hash

6.0.3

Swift & OS version (output of swift --version ; uname -a)

Swift version 6.0.3 (swift-6.0.3-RELEASE)
Target: aarch64-unknown-linux-gnu

Linux 0527dce5b4de 6.1.68 #1 SMP Fri Nov 22 18:05:17 UTC 2024 aarch64 aarch64 aarch64 GNU/Linux

[euanh]

A similar example on macOS. This command succeeds:

% swift package --swift-sdk swift-6.0.3-RELEASE_static-linux-0.0.1 build-container-image --repository localhost:5555/example        
Plugin ‘ContainerImageBuilder’ wants permission to allow all network connections on all ports.
Stated reason: “This command publishes images to container registries over the network”.
Allow this plugin to allow all network connections on all ports? (yes/no) yes
warning: multiple Swift SDKs match ID `swift-6.0.3-RELEASE_static-linux-0.0.1` and host triple arm64-apple-macosx15.0, selected one at /Users/euanh/Library/org.swift.swiftpm/swift-sdks/swift-6.0.3-RELEASE_static-linux-0.0.1.artifactbundle/swift-6.0.3-RELEASE_static-linux-0.0.1/swift-linux-musl
Building for debugging...
...
localhost:5555/example@sha256:43049cb4ace2b1837fbf681f878b106a3090ba92e174a8bf045f58758e755a6c

Adding the --allow-network-connections all flag (understood by the implicit plugin subcommand) in the wrong place makes it fail:

% swift package --allow-network-connections all --swift-sdk swift-6.0.3-RELEASE_static-linux-0.0.1 build-container-image --repository localhost:5555/example
error: Unknown option '--swift-sdk'
Usage: swift package default-command [--allow-writing-to-package-directory] [--allow-writing-to-directory <allow-writing-to-directory> ...] [--allow-network-connections <allow-network-connections>] [--package <package>] [<remaining> ...]
  See 'package default-command -help' for more information.

It needs to go after the SDK flag:

% swift package --swift-sdk swift-6.0.3-RELEASE_static-linux-0.0.1 --allow-network-connections all build-container-image --repository localhost:5555/example
0.0.1.artifactbundle/swift-6.0.3-RELEASE_static-linux-0.0.1/swift-linux-musl
Building for debugging...
...