Add the plugin-side declarations for command plugins, per the pitch, and change the invocations to call them. Add a unit test that calls through to a command plugin and verifies the output received from it.

Author: abertelrud

Sources/PackagePlugin/Plugin.swift

@@ -64,6 +64,7 @@ extension Plugin {
         // that SwiftPM specified.
         let commands: [Command]
         switch input.pluginAction {
+            
         case .createBuildToolCommands(let target):
             // Check that the plugin implements the appropriate protocol for its
             // declared capability.
@@ -73,6 +74,20 @@ extension Plugin {
 
             // Ask the plugin to create build commands for the input target.
             commands = try plugin.createBuildCommands(context: context, target: target)
+            
+        case .performCommand(let targets, let arguments):
+            // Check that the plugin implements the appropriate protocol for its
+            // declared capability.
+            guard let plugin = plugin as? CommandPlugin else {
+                throw PluginDeserializationError.malformedInputJSON("Plugin declared with `command` capability but doesn't conform to `CommandPlugin` protocol")
+            }
+            
+            // Invoke the plugin.
+            try plugin.performCommand(context: context, targets: targets, arguments: arguments)
+
+            // For command plugin there are currently no return commands (any
+            // commands invoked by the plugin are invoked directly).
+            commands = []
         }
 
         // Construct the output structure to send to SwiftPM.

Sources/PackagePlugin/PluginInput.swift

@@ -20,6 +20,7 @@ struct PluginInput {
     let pluginAction: PluginAction
     enum PluginAction {
         case createBuildToolCommands(target: Target)
+        case performCommand(targets: [Target], arguments: [String])
     }
 
     internal init(from data: Data) throws {
@@ -41,6 +42,8 @@ struct PluginInput {
         switch input.pluginAction {
         case .createBuildToolCommands(let targetId):
             self.pluginAction = .createBuildToolCommands(target: try deserializer.target(for: targetId))
+        case .performCommand(let targetIds, let arguments):
+            self.pluginAction = .performCommand(targets: try targetIds.map{ try deserializer.target(for: $0) }, arguments: arguments)
         }
     }
 }
@@ -297,6 +300,7 @@ fileprivate struct WireInput: Decodable {
     /// the capabilities declared for the plugin.
     enum PluginAction: Decodable {
         case createBuildToolCommands(targetId: Target.Id)
+        case performCommand(targetIds: [Target.Id], arguments: [String])
     }
 
     /// A single absolute path in the wire structure, represented as a tuple

Sources/PackagePlugin/Protocols.swift

@@ -73,3 +73,22 @@ extension BuildToolPlugin {
             toolNamesToPaths: context.toolNamesToPaths))
     }
 }
+
+/// Defines functionality for all plugins that have a `customCommand` capability.
+public protocol CommandPlugin: Plugin {
+    /// Invoked by SwiftPM to perform the custom actions of the command.
+    func performCommand(
+        /// The context in which the plugin is invoked. This is the same for all
+        /// kinds of plugins, and provides access to the package graph, to cache
+        /// directories, etc.
+        context: PluginContext,
+        
+        /// The targets to which the command should be applied. If the invoker of
+        /// the command has not specified particular targets, this will be a list
+        /// of all the targets in the package to which the command is applied.
+        targets: [Target],
+        
+        /// Any literal arguments passed after the verb in the command invocation.
+        arguments: [String]
+    ) throws
+}

Sources/SPMBuildCore/PluginInvocation.swift

@@ -18,6 +18,144 @@ import TSCUtility
 
 public typealias Diagnostic = Basics.Diagnostic
 
+public enum PluginAction {
+    case createBuildToolCommands(target: ResolvedTarget)
+    case performCommand(targets: [ResolvedTarget], arguments: [String])
+}
+
+extension PluginTarget {
+    /// Invokes the plugin by compiling its source code (if needed) and then running it as a subprocess. The specified
+    /// plugin action determines which entry point is called in the subprocess, and the package and the tool mapping
+    /// determine the context that is available to the plugin.
+    ///
+    /// The working directory should be a path in the file system into which the plugin is allowed to write information
+    /// that persists between all invocations of a plugin for the same purpose. The exact meaning of "same" means here
+    /// depends on the particular plugin; for a build tool plugin, it might be the combination of the plugin and target
+    /// for which it is being invoked.
+    ///
+    /// Note that errors thrown by this function relate to problems actually invoking the plugin. Any diagnostics that
+    /// are emitted by the plugin are contained in the returned result structure.
+    ///
+    /// - Parameters:
+    ///   - action: The plugin action (i.e. entry point) to invoke, possibly containing parameters.
+    ///   - package: The root of the package graph to pass down to the plugin.
+    ///   - scriptRunner: Entity responsible for actually running the code of the plugin.
+    ///   - outputDirectory: A directory under which the plugin can write anything it wants to.
+    ///   - toolNamesToPaths: A mapping from name of tools available to the plugin to the corresponding absolute paths.
+    ///   - fileSystem: The file system to which all of the paths refers.
+    ///
+    /// - Returns: A PluginInvocationResult that contains the results of invoking the plugin.
+    public func invoke(
+        action: PluginAction,
+        package: ResolvedPackage,
+        buildEnvironment: BuildEnvironment,
+        scriptRunner: PluginScriptRunner,
+        outputDirectory: AbsolutePath,
+        toolNamesToPaths: [String: AbsolutePath],
+        observabilityScope: ObservabilityScope,
+        fileSystem: FileSystem
+    ) throws -> PluginInvocationResult {
+        // Create the plugin working directory if needed (but don't do anything with it if it already exists).
+        do {
+            try fileSystem.createDirectory(outputDirectory, recursive: true)
+        }
+        catch {
+            throw PluginEvaluationError.outputDirectoryCouldNotBeCreated(path: outputDirectory, underlyingError: error)
+        }
+
+        // Create the input context to send to the plugin.
+        // TODO: Some of this could probably be cached.
+        var serializer = PluginScriptRunnerInputSerializer(buildEnvironment: buildEnvironment)
+        let inputStruct = try serializer.makePluginScriptRunnerInput(
+            rootPackage: package,
+            pluginWorkDir: outputDirectory,
+            builtProductsDir: outputDirectory,  // FIXME — what is this parameter needed for?
+            toolNamesToPaths: toolNamesToPaths,
+            pluginAction: action)
+        
+        // Serialize the PluginEvaluationInput to JSON.
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.prettyPrinted, .sortedKeys, .withoutEscapingSlashes]
+        let inputJSON = try encoder.encode(inputStruct)
+        
+        // Call the plugin script runner to actually invoke the plugin.
+        // TODO: This should be asynchronous.
+        let (outputJSON, outputText) = try scriptRunner.runPluginScript(
+            sources: sources,
+            inputJSON: inputJSON,
+            pluginArguments: [],
+            toolsVersion: self.apiVersion,
+            writableDirectories: [outputDirectory],
+            observabilityScope: observabilityScope,
+            fileSystem: fileSystem)
+
+        // Deserialize the JSON to an PluginScriptRunnerOutput.
+        let outputStruct: PluginScriptRunnerOutput
+        do {
+            let decoder = JSONDecoder()
+            outputStruct = try decoder.decode(PluginScriptRunnerOutput.self, from: outputJSON)
+        }
+        catch {
+            throw PluginEvaluationError.decodingPluginOutputFailed(json: outputJSON, underlyingError: error)
+        }
+
+        // Generate emittable Diagnostics from the plugin output.
+        let diagnostics: [Diagnostic] = try outputStruct.diagnostics.map { diag in
+            let metadata: ObservabilityMetadata? = try diag.file.map {
+                var metadata = ObservabilityMetadata()
+                metadata.fileLocation = try .init(.init(validating: $0), line: diag.line)
+                return metadata
+            }
+
+            switch diag.severity {
+            case .error:
+                return .error(diag.message, metadata: metadata)
+            case .warning:
+                return .warning(diag.message, metadata: metadata)
+            case .remark:
+                return .info(diag.message, metadata: metadata)
+            }
+        }
+
+        // FIXME: Validate the plugin output structure here, e.g. paths, etc.
+        
+        // Generate commands from the plugin output. This is where we translate from the transport JSON to our
+        // internal form. We deal with BuildCommands and PrebuildCommands separately.
+        // FIXME: This feels a bit too specific to have here.
+        // FIXME: Also there is too much repetition here, need to unify it.
+        let buildCommands = outputStruct.buildCommands.map { cmd in
+            PluginInvocationResult.BuildCommand(
+                configuration: .init(
+                    displayName: cmd.displayName,
+                    executable: cmd.executable,
+                    arguments: cmd.arguments,
+                    environment: cmd.environment,
+                    workingDirectory: cmd.workingDirectory.map{ AbsolutePath($0) }),
+                inputFiles: cmd.inputFiles.map{ AbsolutePath($0) },
+                outputFiles: cmd.outputFiles.map{ AbsolutePath($0) })
+        }
+        let prebuildCommands = outputStruct.prebuildCommands.map { cmd in
+            PluginInvocationResult.PrebuildCommand(
+                configuration: .init(
+                    displayName: cmd.displayName,
+                    executable: cmd.executable,
+                    arguments: cmd.arguments,
+                    environment: cmd.environment,
+                    workingDirectory: cmd.workingDirectory.map{ AbsolutePath($0) }),
+                outputFilesDirectory: AbsolutePath(cmd.outputFilesDirectory))
+        }
+
+        // Create and return an evaluation result for the invocation.
+        return PluginInvocationResult(
+            plugin: self,
+            diagnostics: diagnostics,
+            textOutput: String(decoding: outputText, as: UTF8.self),
+            buildCommands: buildCommands,
+            prebuildCommands: prebuildCommands)
+    }
+}
+
+
 extension PackageGraph {
 
     /// Traverses the graph of reachable targets in a package graph, and applies plugins to targets as needed. Each
@@ -93,85 +231,20 @@ extension PackageGraph {
                     }
                 })
 
-                // Give each invocation of a plugin a separate output directory.
+                // Assign a plugin working directory based on the package, target, and plugin.
                 let pluginOutputDir = outputDir.appending(components: package.identity.description, target.name, pluginTarget.name)
-                do {
-                    try fileSystem.createDirectory(pluginOutputDir, recursive: true)
-                }
-                catch {
-                    throw PluginEvaluationError.outputDirectoryCouldNotBeCreated(path: pluginOutputDir, underlyingError: error)
-                }
 
-                // Create the input context to pass when applying the plugin to the target.
-                var serializer = PluginScriptRunnerInputSerializer(buildEnvironment: buildEnvironment)
-                let pluginInput = try serializer.makePluginScriptRunnerInput(
-                    rootPackage: package,
-                    pluginWorkDir: pluginOutputDir,
-                    builtProductsDir: builtToolsDir,
+                // Invoke the plugin.
+                let result = try pluginTarget.invoke(
+                    action: .createBuildToolCommands(target: target),
+                    package: package,
+                    buildEnvironment: buildEnvironment,
+                    scriptRunner: pluginScriptRunner,
+                    outputDirectory: pluginOutputDir,
                     toolNamesToPaths: toolNamesToPaths,
-                    pluginAction: .createBuildToolCommands(target: target))
-                
-                // Run the plugin in the context of the target. The details of this are left to the plugin runner.
-                // TODO: This should be asynchronous.
-                let (pluginOutput, emittedText) = try runPluginScript(
-                    sources: pluginTarget.sources,
-                    input: pluginInput,
-                    toolsVersion: package.manifest.toolsVersion,
-                    writableDirectories: [pluginOutputDir],
-                    pluginScriptRunner: pluginScriptRunner,
                     observabilityScope: observabilityScope,
-                    fileSystem: fileSystem
-                )
-
-                // Generate emittable Diagnostics from the plugin output.
-                let diagnostics: [Diagnostic] = try pluginOutput.diagnostics.map { diag in
-                    let metadata: ObservabilityMetadata? = try diag.file.map {
-                        var metadata = ObservabilityMetadata()
-                        metadata.fileLocation = try .init(.init(validating: $0), line: diag.line)
-                        return metadata
-                    }
-
-                    switch diag.severity {
-                    case .error:
-                        return .error(diag.message, metadata: metadata)
-                    case .warning:
-                        return .warning(diag.message, metadata: metadata)
-                    case .remark:
-                        return .info(diag.message, metadata: metadata)
-                    }
-                }
-
-                // Extract any emitted text output (received from the stdout/stderr of the plugin invocation).
-                let textOutput = String(decoding: emittedText, as: UTF8.self)
-
-                // FIXME: Validate the plugin output structure here, e.g. paths, etc.
-
-                // Generate commands from the plugin output. This is where we translate from the transport JSON to our
-                // internal form. We deal with BuildCommands and PrebuildCommands separately.
-                let buildCommands = pluginOutput.buildCommands.map { cmd in
-                    PluginInvocationResult.BuildCommand(
-                        configuration: .init(
-                            displayName: cmd.displayName,
-                            executable: cmd.executable,
-                            arguments: cmd.arguments,
-                            environment: cmd.environment,
-                            workingDirectory: cmd.workingDirectory.map{ AbsolutePath($0) }),
-                        inputFiles: cmd.inputFiles.map{ AbsolutePath($0) },
-                        outputFiles: cmd.outputFiles.map{ AbsolutePath($0) })
-                }
-                let prebuildCommands = pluginOutput.prebuildCommands.map { cmd in
-                    PluginInvocationResult.PrebuildCommand(
-                        configuration: .init(
-                            displayName: cmd.displayName,
-                            executable: cmd.executable,
-                            arguments: cmd.arguments,
-                            environment: cmd.environment,
-                            workingDirectory: cmd.workingDirectory.map{ AbsolutePath($0) }),
-                        outputFilesDirectory: AbsolutePath(cmd.outputFilesDirectory))
-                }
-
-                // Create an evaluation result from the usage of the plugin by the target.
-                pluginResults.append(PluginInvocationResult(plugin: pluginTarget, diagnostics: diagnostics, textOutput: textOutput, buildCommands: buildCommands, prebuildCommands: prebuildCommands))
+                    fileSystem: fileSystem)
+                pluginResults.append(result)
             }
 
             // Associate the list of results with the target. The list will have one entry for each plugin used by the target.
@@ -200,6 +273,7 @@ extension PackageGraph {
         let (outputJSON, stdoutText) = try pluginScriptRunner.runPluginScript(
             sources: sources,
             inputJSON: inputJSON,
+            pluginArguments: [],
             toolsVersion: toolsVersion,
             writableDirectories: writableDirectories,
             observabilityScope: observabilityScope,
@@ -341,6 +415,7 @@ public protocol PluginScriptRunner {
     func runPluginScript(
         sources: Sources,
         inputJSON: Data,
+        pluginArguments: [String],
         toolsVersion: ToolsVersion,
         writableDirectories: [AbsolutePath],
         observabilityScope: ObservabilityScope,
@@ -380,6 +455,7 @@ struct PluginScriptRunnerInput: Codable {
     /// the capabilities declared for the plugin.
     enum PluginAction: Codable {
         case createBuildToolCommands(targetId: Target.Id)
+        case performCommand(targetIds: [Target.Id], arguments: [String])
     }
 
     /// A single absolute path in the wire structure, represented as a tuple
@@ -551,13 +627,6 @@ struct PluginScriptRunnerInputSerializer {
     var packages: [PluginScriptRunnerInput.Package] = []
     var packagesToIds: [ResolvedPackage: PluginScriptRunnerInput.Package.Id] = [:]
 
-    /// The action that SwiftPM wants to invoke on the plugin.
-    enum PluginAction {
-        case createBuildToolCommands(target: ResolvedTarget)
-    }
-    
-    /// Constructs the codable, serialized input to the plugin, based on a
-    /// plugin action, a package subgraph, and other parameters.
     mutating func makePluginScriptRunnerInput(
         rootPackage: ResolvedPackage,
         pluginWorkDir: AbsolutePath,
@@ -573,8 +642,10 @@ struct PluginScriptRunnerInputSerializer {
         switch pluginAction {
         case .createBuildToolCommands(let target):
             serializedPluginAction = .createBuildToolCommands(targetId: try serialize(target: target)!)
+        case .performCommand(let targets, let arguments):
+            serializedPluginAction = .performCommand(targetIds: try targets.compactMap { try serialize(target: $0) }, arguments: arguments)
         }
-        let input = PluginScriptRunnerInput(
+        return PluginScriptRunnerInput(
             paths: paths,
             targets: targets,
             products: products,
@@ -584,7 +655,6 @@ struct PluginScriptRunnerInputSerializer {
             builtProductsDirId: builtProductsDirId,
             toolNamesToPathIds: toolNamesToPathIds,
             pluginAction: serializedPluginAction)
-        return input
     }
 
     /// Adds a path to the serialized structure, if it isn't already there.