Add a new show-executables package subcommand for all executables (#8005)

The `swift run` subcommand runs executables that come from a variety of
places. Typically, users
are expecting to be able to execute products and targets for their
package, iterating quickly with
their code changes. You can also run executable products from packages
that are part of the
dependency list. It turns out that all of the executable products of the
root package's transitive
closure are available.
    
Discovery of the available executables is limited to either direct
inspection of the Package.swift,
the `swift package describe`, and `swift package completion-tool
list-executables`. However, these
only work to find the executables of the current package, not in the
dependent packages. This has
real implications for a package maintainer since duplicate executable
names are forbidden among the
closure of the package's dependencies.
    
Provide the ability to show the complete list of available executables
from the package with a new
`swift package show-executables` subcommand. Qualify executables that
aren't in the current package
with their package of origin for traceability purposes. The list can be
formatted as JSON so that
this information can be used by third-party tools.

---------

Co-authored-by: Max Desiatov <[email protected]>

Author: cmcgee1024

Fixtures/Miscellaneous/ShowExecutables/app/Package.swift

@@ -0,0 +1,21 @@
+// swift-tools-version:5.10
+import PackageDescription
+
+let package = Package(
+    name: "Dealer",
+    products: [
+        .executable(
+            name: "dealer",
+            targets: ["Dealer"]
+        ),
+    ],
+    dependencies: [
+        .package(path: "../deck-of-playing-cards"),
+    ],
+    targets: [
+        .executableTarget(
+            name: "Dealer",
+            path: "./"
+        ),
+    ]
+)

Fixtures/Miscellaneous/ShowExecutables/app/main.swift

@@ -0,0 +1 @@
+print("I'm the dealer")

Fixtures/Miscellaneous/ShowExecutables/deck-of-playing-cards/Package.swift

@@ -0,0 +1,18 @@
+// swift-tools-version:5.10
+import PackageDescription
+
+let package = Package(
+    name: "deck-of-playing-cards",
+    products: [
+        .executable(
+            name: "deck",
+            targets: ["Deck"]
+        ),
+    ],
+    targets: [
+        .executableTarget(
+            name: "Deck",
+            path: "./"
+        ),
+    ]
+)

Fixtures/Miscellaneous/ShowExecutables/deck-of-playing-cards/main.swift

@@ -0,0 +1 @@
+print("I'm a deck of cards")

Sources/Commands/CMakeLists.txt

@@ -27,6 +27,7 @@ add_library(Commands
   PackageCommands/ResetCommands.swift
   PackageCommands/Resolve.swift
   PackageCommands/ShowDependencies.swift
+  PackageCommands/ShowExecutables.swift
   PackageCommands/SwiftPackageCommand.swift
   PackageCommands/ToolsVersionCommand.swift
   PackageCommands/Update.swift

Sources/Commands/PackageCommands/ShowExecutables.swift

@@ -0,0 +1,88 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2014-2024 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import ArgumentParser
+import Basics
+import CoreCommands
+import Foundation
+import Workspace
+
+struct ShowExecutables: AsyncSwiftCommand {
+    static let configuration = CommandConfiguration(
+        abstract: "List the available executables from this package.")
+
+    @OptionGroup(visibility: .hidden)
+    var globalOptions: GlobalOptions
+
+    @Option(help: "Set the output format.")
+    var format: ShowExecutablesMode = .flatlist
+
+    func run(_ swiftCommandState: SwiftCommandState) async throws {
+        let packageGraph = try await swiftCommandState.loadPackageGraph()
+        let rootPackages = packageGraph.rootPackages.map { $0.identity }
+
+        let executables = packageGraph.allProducts.filter({
+            $0.type == .executable || $0.type == .snippet
+        }).map { product -> Executable in
+            if !rootPackages.contains(product.packageIdentity) {
+                return Executable(package: product.packageIdentity.description, name: product.name)
+            } else {
+                return Executable(package: Optional<String>.none, name: product.name)
+            }
+        }.sorted(by: {$0.name < $1.name})
+
+        switch self.format {
+        case .flatlist:
+            for executable in executables {
+                if let package = executable.package {
+                    print("\(executable.name) (\(package))")
+                } else {
+                    print(executable.name)
+                }
+            }
+
+        case .json:
+            let encoder = JSONEncoder()
+            let data = try encoder.encode(executables)
+            if let output = String(data: data, encoding: .utf8) {
+                print(output)
+            }
+        }
+    }
+
+    struct Executable: Codable {
+        var package: String?
+        var name: String
+    }
+
+    enum ShowExecutablesMode: String, RawRepresentable, CustomStringConvertible, ExpressibleByArgument, CaseIterable {
+        case flatlist, json
+
+        public init?(rawValue: String) {
+            switch rawValue.lowercased() {
+            case "flatlist":
+                self = .flatlist
+            case "json":
+                self = .json
+            default:
+                return nil
+            }
+        }
+
+        public var description: String {
+            switch self {
+            case .flatlist: return "flatlist"
+            case .json: return "json"
+            }
+        }
+    }
+}

Sources/Commands/PackageCommands/SwiftPackageCommand.swift

@@ -62,6 +62,7 @@ public struct SwiftPackageCommand: AsyncParsableCommand {
             Fetch.self,
 
             ShowDependencies.self,
+            ShowExecutables.self,
             ToolsVersionCommand.self,
             ComputeChecksum.self,
             ArchiveSource.self,

Tests/CommandsTests/PackageCommandTests.swift

@@ -551,6 +551,41 @@ final class PackageCommandTests: CommandsTestCase {
         }
     }
 
+    func testShowExecutables() async throws {
+        try await fixture(name: "Miscellaneous/ShowExecutables") { fixturePath in
+            let packageRoot = fixturePath.appending("app")
+            let (textOutput, _) = try await SwiftPM.Package.execute(["show-executables", "--format=flatlist"], packagePath: packageRoot)
+            XCTAssert(textOutput.contains("dealer\n"))
+            XCTAssert(textOutput.contains("deck (deck-of-playing-cards)\n"))
+
+            let (jsonOutput, _) = try await SwiftPM.Package.execute(["show-executables", "--format=json"], packagePath: packageRoot)
+            let json = try JSON(bytes: ByteString(encodingAsUTF8: jsonOutput))
+            guard case let .array(contents) = json else { XCTFail("unexpected result"); return }
+
+            XCTAssertEqual(2, contents.count)
+
+            guard case let first = contents.first else { XCTFail("unexpected result"); return }
+            guard case let .dictionary(dealer) = first else { XCTFail("unexpected result"); return }
+            guard case let .string(dealerName)? = dealer["name"] else { XCTFail("unexpected result"); return }
+            XCTAssertEqual(dealerName, "dealer")
+            if case let .string(package)? = dealer["package"] {
+                XCTFail("unexpected package for dealer (should be unset): \(package)")
+                return
+            }
+
+            guard case let last = contents.last else { XCTFail("unexpected result"); return }
+            guard case let .dictionary(deck) = last else { XCTFail("unexpected result"); return }
+            guard case let .string(deckName)? = deck["name"] else { XCTFail("unexpected result"); return }
+            XCTAssertEqual(deckName, "deck")
+            if case let .string(package)? = deck["package"] {
+                XCTAssertEqual("deck-of-playing-cards", package)
+            } else {
+                XCTFail("missing package for deck")
+                return
+            }
+        }
+    }
+
     func testShowDependencies() async throws {
         try await fixture(name: "DependencyResolution/External/Complex") { fixturePath in
             let packageRoot = fixturePath.appending("app")