Support qualifiers for ambiguous plugin commands (#6920)

* Support qualifiers for ambiguous plugin commands

This adds a `--package` option to the plugin command which will limit the set of available plugins to those inside a package with the given identity.

The identity is not validated in any way, it will just be applied as a filter on all relevant packages. The option does apply to `--list` as well which seems a bit odd but a consequence of making listing an option rather than a command.

rdar://99887952

* Test

Author: neonichu

Fixtures/Miscellaneous/Plugins/AmbiguousCommands/Dependencies/A/Package.swift

@@ -0,0 +1,21 @@
+// swift-tools-version: 5.9
+
+import PackageDescription
+
+let package = Package(
+    name: "A",
+    products: [
+        .plugin(
+            name: "A",
+            targets: ["A"]),
+    ],
+    targets: [
+        .plugin(
+            name: "A",
+            capability: .command(intent: .custom(
+                verb: "A",
+                description: "prints hello"
+            ))
+        ),
+    ]
+)

Fixtures/Miscellaneous/Plugins/AmbiguousCommands/Dependencies/A/Plugins/A.swift

@@ -0,0 +1,9 @@
+import PackagePlugin
+
+@main
+struct A: CommandPlugin {
+    func performCommand(context: PluginContext, arguments: [String]) async throws {
+        print("Hello A!")
+    }
+}
+

Fixtures/Miscellaneous/Plugins/AmbiguousCommands/Dependencies/B/Package.swift

@@ -0,0 +1,21 @@
+// swift-tools-version: 5.9
+
+import PackageDescription
+
+let package = Package(
+    name: "B",
+    products: [
+        .plugin(
+            name: "B",
+            targets: ["B"]),
+    ],
+    targets: [
+        .plugin(
+            name: "B",
+            capability: .command(intent: .custom(
+                verb: "A",
+                description: "prints hello"
+            ))
+        ),
+    ]
+)

Fixtures/Miscellaneous/Plugins/AmbiguousCommands/Dependencies/B/Plugins/B.swift

@@ -0,0 +1,8 @@
+import PackagePlugin
+
+@main
+struct B: CommandPlugin {
+    func performCommand(context: PluginContext, arguments: [String]) async throws {
+        print("Hello B!")
+    }
+}

Fixtures/Miscellaneous/Plugins/AmbiguousCommands/Package.swift

@@ -0,0 +1,15 @@
+// swift-tools-version: 5.9
+
+import PackageDescription
+
+let package = Package(
+    name: "AmbiguousCommands",
+    dependencies: [
+        .package(path: "Dependencies/A"),
+        .package(path: "Dependencies/B"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "AmbiguousCommands"),
+    ]
+)

Fixtures/Miscellaneous/Plugins/AmbiguousCommands/Sources/main.swift

@@ -0,0 +1 @@
+print("Hello, world!")

Sources/Commands/PackageTools/PluginCommand.swift

@@ -57,6 +57,12 @@ struct PluginCommand: SwiftCommand {
 
         @Option(name: .customLong("allow-network-connections"))
         var allowNetworkConnections: NetworkPermission = .none
+
+        @Option(
+            name: .customLong("package"),
+            help: "Limit available plugins to a single package with the given identity"
+        )
+        var packageIdentity: String? = nil
     }
 
     @OptionGroup()
@@ -80,7 +86,7 @@ struct PluginCommand: SwiftCommand {
         // List the available plugins, if asked to.
         if self.listCommands {
             let packageGraph = try swiftTool.loadPackageGraph()
-            let allPlugins = PluginCommand.availableCommandPlugins(in: packageGraph)
+            let allPlugins = PluginCommand.availableCommandPlugins(in: packageGraph, limitedTo: self.pluginOptions.packageIdentity)
             for plugin in allPlugins.sorted(by: { $0.name < $1.name }) {
                 guard case .command(let intent, _) = plugin.capability else { continue }
                 var line = "‘\(intent.invocationVerb)’ (plugin ‘\(plugin.name)’"
@@ -113,7 +119,7 @@ struct PluginCommand: SwiftCommand {
         let packageGraph = try swiftTool.loadPackageGraph()
 
         swiftTool.observabilityScope.emit(info: "Finding plugin for command ‘\(command)’")
-        let matchingPlugins = PluginCommand.findPlugins(matching: command, in: packageGraph)
+        let matchingPlugins = PluginCommand.findPlugins(matching: command, in: packageGraph, limitedTo: options.packageIdentity)
 
         // Complain if we didn't find exactly one.
         if matchingPlugins.isEmpty {
@@ -298,12 +304,12 @@ struct PluginCommand: SwiftCommand {
         // TODO: We should also emit a final line of output regarding the result.
     }
 
-    static func availableCommandPlugins(in graph: PackageGraph) -> [PluginTarget] {
+    static func availableCommandPlugins(in graph: PackageGraph, limitedTo packageIdentity: String?) -> [PluginTarget] {
         // All targets from plugin products of direct dependencies are "available".
-        let directDependencyPackages = graph.rootPackages.flatMap { $0.dependencies }
+        let directDependencyPackages = graph.rootPackages.flatMap { $0.dependencies }.filter { $0.matching(identity: packageIdentity) }
         let directDependencyPluginTargets = directDependencyPackages.flatMap { $0.products.filter { $0.type == .plugin } }.flatMap { $0.targets }
         // As well as any plugin targets in root packages.
-        let rootPackageTargets = graph.rootPackages.flatMap { $0.targets }
+        let rootPackageTargets = graph.rootPackages.filter { $0.matching(identity: packageIdentity) }.flatMap { $0.targets }
         return (directDependencyPluginTargets + rootPackageTargets).compactMap { $0.underlyingTarget as? PluginTarget }.filter {
             switch $0.capability {
             case .buildTool: return false
@@ -312,9 +318,9 @@ struct PluginCommand: SwiftCommand {
         }
     }
 
-    static func findPlugins(matching verb: String, in graph: PackageGraph) -> [PluginTarget] {
+    static func findPlugins(matching verb: String, in graph: PackageGraph, limitedTo packageIdentity: String?) -> [PluginTarget] {
         // Find and return the command plugins that match the command.
-        Self.availableCommandPlugins(in: graph).filter {
+        Self.availableCommandPlugins(in: graph, limitedTo: packageIdentity).filter {
             // Filter out any non-command plugins and any whose verb is different.
             guard case .command(let intent, _) = $0.capability else { return false }
             return verb == intent.invocationVerb
@@ -386,3 +392,13 @@ extension SandboxNetworkPermission {
         }
     }
 }
+
+extension ResolvedPackage {
+    fileprivate func matching(identity: String?) -> Bool {
+        if let identity {
+            return self.identity == .plain(identity)
+        } else {
+            return true
+        }
+    }
+}

Sources/Commands/PackageTools/SwiftPackageTool.swift

@@ -126,7 +126,7 @@ extension PluginCommand.PluginOptions {
     func merged(with other: Self) -> Self {
         // validate against developer mistake
         assert(
-            Mirror(reflecting: self).children.count == 3,
+            Mirror(reflecting: self).children.count == 4,
             "Property added to PluginOptions without updating merged(with:)!"
         )
         // actual merge
@@ -137,6 +137,9 @@ extension PluginCommand.PluginOptions {
         if other.allowNetworkConnections != .none {
             merged.allowNetworkConnections = other.allowNetworkConnections
         }
+        if other.packageIdentity != nil {
+            merged.packageIdentity = other.packageIdentity
+        }
         return merged
     }
 }

Tests/CommandsTests/PackageToolTests.swift

@@ -1842,6 +1842,16 @@ final class PackageToolTests: CommandsTestCase {
         }
     }
 
+    func testAmbiguousCommandPlugin() throws {
+        // Only run the test if the environment in which we're running actually supports Swift concurrency (which the plugin APIs require).
+        try XCTSkipIf(!UserToolchain.default.supportsSwiftConcurrency(), "skipping because test environment doesn't support concurrency")
+
+        try fixture(name: "Miscellaneous/Plugins/AmbiguousCommands") { fixturePath in
+            let (stdout, _) = try SwiftPM.Package.execute(["plugin", "--package", "A", "A"], packagePath: fixturePath)
+            XCTAssertMatch(stdout, .contains("Hello A!"))
+        }
+    }
+
     func testCommandPluginNetworkingPermissions(permissionsManifestFragment: String, permissionError: String, reason: String, remedy: [String]) throws {
         // Only run the test if the environment in which we're running actually supports Swift concurrency (which the plugin APIs require).
         try XCTSkipIf(!UserToolchain.default.supportsSwiftConcurrency(), "skipping because test environment doesn't support concurrency")