Add back the "intent" enum for command plugins, as described in the revised pitch document

Author: abertelrud

Sources/Commands/Describe.swift

@@ -142,33 +142,56 @@ struct DescribedPackage: Encodable {
     /// Represents a plugin capability for the sole purpose of generating a description.
     struct DescribedPluginCapability: Encodable {
         let type: String
-        let verb: String?
-        let description: String?
+        let intent: PluginCommandIntent?
         let permissions: [PluginPermission]?
 
         init(from capability: PluginCapability, in package: Package) {
             switch capability {
             case .buildTool:
                 self.type = "buildTool"
-                self.verb = nil
-                self.description = nil
+                self.intent = nil
                 self.permissions = nil
-            case .command(let verb, let description, let permissions):
+            case .command(let intent, let permissions):
                 self.type = "command"
-                self.verb = verb
-                self.description = description
-                self.permissions = permissions.map{
-                    switch $0 {
-                    case .packageWritability(let reason):
-                        return PluginPermission(type: "packageWritability", reason: reason)
-                    }
-                }
+                self.intent = .init(from: intent)
+                self.permissions = permissions.map{ .init(from: $0) }
             }
         }
 
+        struct PluginCommandIntent: Encodable {
+            let type: String
+            let verb: String?
+            let description: String?
+            
+            init(from intent: PackageModel.PluginCommandIntent) {
+                switch intent {
+                case .documentationGeneration:
+                    self.type = "documentationGeneration"
+                    self.verb = nil
+                    self.description = nil
+                case .sourceCodeFormatting:
+                    self.type = "sourceCodeFormatting"
+                    self.verb = nil
+                    self.description = nil
+                case .custom(let verb, let description):
+                    self.type = "documentationGeneration"
+                    self.verb = verb
+                    self.description = description
+                }
+            }
+        }
+
         struct PluginPermission: Encodable {
             let type: String
             let reason: String
+            
+            init(from permission: PackageModel.PluginPermission) {
+                switch permission {
+                case .packageWritability(let reason):
+                    self.type = "packageWritability"
+                    self.reason = reason
+                }
+            }
         }
     }
 

Sources/PackageDescription/PackageDescriptionSerialization.swift

@@ -224,7 +224,7 @@ extension SystemPackageProvider: Encodable {
 
 extension Target.PluginCapability: Encodable {
     private enum CodingKeys: CodingKey {
-        case type, verb, description, permissions
+        case type, intent, permissions
     }
 
     private enum Capability: String, Encodable {
@@ -236,11 +236,34 @@ extension Target.PluginCapability: Encodable {
         switch self {
         case ._buildTool:
             try container.encode(Capability.buildTool, forKey: .type)
-        case ._command(let verb, let description, let permissions):
+        case ._command(let intent, let permissions):
             try container.encode(Capability.command, forKey: .type)
+            try container.encode(intent, forKey: .intent)
+            try container.encode(permissions, forKey: .permissions)
+        }
+    }
+}
+
+extension PluginCommandIntent: Encodable {
+    private enum CodingKeys: CodingKey {
+        case type, verb, description
+    }
+
+    private enum IntentType: String, Encodable {
+        case documentationGeneration, sourceCodeFormatting, custom
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        switch self {
+        case .documentationGeneration:
+            try container.encode(IntentType.documentationGeneration, forKey: .type)
+        case .sourceCodeFormatting:
+            try container.encode(IntentType.sourceCodeFormatting, forKey: .type)
+        case .custom(let verb, let description):
+            try container.encode(IntentType.custom, forKey: .type)
             try container.encode(verb, forKey: .verb)
             try container.encode(description, forKey: .description)
-            try container.encode(permissions, forKey: .permissions)
         }
     }
 }

Sources/PackageDescription/Target.swift

@@ -131,7 +131,7 @@ public final class Target {
     /// this enum will be extended as new plugin capabilities are added.
     public enum PluginCapability {
         case _buildTool
-        case _command(verb: String, description: String, permissions: [PluginPermission])
+        case _command(intent: PluginCommandIntent, permissions: [PluginPermission])
     }
 
     /// The target's C build settings.
@@ -1020,22 +1020,36 @@ extension Target.PluginCapability {
     /// using the SwiftPM CLI (`swift package <verb>`), or in an IDE that supports
     /// Swift Packages.
     public static func command(
-        /// The `swift package` CLI verb through which the plugin can be invoked.
-        verb: String,
-        
-        /// A description of the functionality of the custom command, suitable for
-        /// showing in help text output.
-        description: String,
-        
+        /// The semantic intent of the plugin (either one of the predefined intents,
+        /// or a custom intent).
+        intent: PluginCommandIntent,
+
         /// Any permissions needed by the command plugin. This affects what the
         /// sandbox in which the plugin is run allows. Some permissions may require
         /// approval by the user.
         permissions: [PluginPermission] = []
     ) -> Target.PluginCapability {
-        return ._command(verb: verb, description: description, permissions: permissions)
+        return ._command(intent: intent, permissions: permissions)
     }
 }
 
+public enum PluginCommandIntent {
+    /// The intent of the command is to generate documentation, either by parsing the
+    /// package contents directly or by using the build system support for generating
+    /// symbol graphs. Invoked by a `generate-documentation` verb to `swift package`.
+    case documentationGeneration
+    
+    /// The intent of the command is to modify the source code in the package based
+    /// on a set of rules. Invoked by a `format-source-code` verb to `swift package`.
+    case sourceCodeFormatting
+
+    /// Any future enum cases should use @available()
+
+    /// An intent that doesn't fit into any of the other categories, with a custom
+    /// verb through which it can be invoked.
+    case custom(verb: String, description: String)
+}
+
 public enum PluginPermission {
     /// The custom command plugin requests permission to modify the files inside the
     /// package directory. The `reason` string is shown to the user at the time of

Sources/PackageLoading/ManifestJSONParser.swift

@@ -597,10 +597,27 @@ extension TargetDescription.PluginCapability {
         case "buildTool":
             self = .buildTool
         case "command":
+            let intent = try TargetDescription.PluginCommandIntent(v4: json.getJSON("intent"))
+            let permissions = try json.getArray("permissions").map(TargetDescription.PluginPermission.init(v4:))
+            self = .command(intent: intent, permissions: permissions)
+        default:
+            throw InternalError("invalid type \(type)")
+        }
+    }
+}
+
+extension TargetDescription.PluginCommandIntent {
+    fileprivate init(v4 json: JSON) throws {
+        let type = try json.get(String.self, forKey: "type")
+        switch type {
+        case "documentationGeneration":
+            self = .documentationGeneration
+        case "sourceCodeFormatting":
+            self = .sourceCodeFormatting
+        case "custom":
             let verb = try json.get(String.self, forKey: "verb")
             let description = try json.get(String.self, forKey: "description")
-            let permissions = try json.getArray("permissions").map(TargetDescription.PluginPermission.init(v4:))
-            self = .command(verb: verb, description: description, permissions: permissions)
+            self = .custom(verb: verb, description: description)
         default:
             throw InternalError("invalid type \(type)")
         }

Sources/PackageModel/Manifest/TargetDescription.swift

@@ -110,9 +110,15 @@ public struct TargetDescription: Equatable, Codable {
     /// Represents the declared capability of a package plugin.
     public enum PluginCapability: Equatable {
         case buildTool
-        case command(verb: String, description: String, permissions: [PluginPermission])
+        case command(intent: PluginCommandIntent, permissions: [PluginPermission])
     }
 
+    public enum PluginCommandIntent: Equatable, Codable {
+        case documentationGeneration
+        case sourceCodeFormatting
+        case custom(verb: String, description: String)
+    }
+
     public enum PluginPermission: Equatable, Codable {
         case packageWritability(reason: String)
     }
@@ -272,11 +278,10 @@ extension TargetDescription.PluginCapability: Codable {
         switch self {
         case .buildTool:
             try container.encodeNil(forKey: .buildTool)
-        case .command(let a1, let a2, let a3):
+        case .command(let a1, let a2):
             var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .command)
             try unkeyedContainer.encode(a1)
             try unkeyedContainer.encode(a2)
-            try unkeyedContainer.encode(a3)
         }
     }
 
@@ -290,10 +295,9 @@ extension TargetDescription.PluginCapability: Codable {
             self = .buildTool
         case .command:
             var unkeyedValues = try values.nestedUnkeyedContainer(forKey: key)
-            let a1 = try unkeyedValues.decode(String.self)
-            let a2 = try unkeyedValues.decode(String.self)
-            let a3 = try unkeyedValues.decode([TargetDescription.PluginPermission].self)
-            self = .command(verb: a1, description: a2, permissions: a3)
+            let a1 = try unkeyedValues.decode(TargetDescription.PluginCommandIntent.self)
+            let a2 = try unkeyedValues.decode([TargetDescription.PluginPermission].self)
+            self = .command(intent: a1, permissions: a2)
         }
     }
 }

Sources/PackageModel/ManifestSourceGeneration.swift

@@ -415,17 +415,32 @@ fileprivate extension SourceCodeFragment {
         switch capability {
         case .buildTool:
             self.init(enum: "buildTool", subnodes: [])
-        case .command(let verb, let description, let permissions):
+        case .command(let intent, let permissions):
             var params: [SourceCodeFragment] = []
-            params.append(SourceCodeFragment(key: "verb", string: verb))
-            params.append(SourceCodeFragment(key: "description", string: description))
+            params.append(SourceCodeFragment(key: "intent", subnode: .init(from: intent)))
             if !permissions.isEmpty {
                 params.append(SourceCodeFragment(key: "permissions", subnodes: permissions.map{ .init(from: $0) }))
             }
             self.init(enum: "command", subnodes: params)
         }
     }
 
+    /// Instantiates a SourceCodeFragment to represent a single plugin command intent.
+    init(from intent: TargetDescription.PluginCommandIntent) {
+        switch intent {
+        case .documentationGeneration:
+            self.init(enum: "documentationGeneration")
+        case .sourceCodeFormatting:
+            self.init(enum: "sourceCodeFormatting")
+        case .custom(let verb, let description):
+            let params = [
+                SourceCodeFragment(key: "verb", string: verb),
+                SourceCodeFragment(key: "description", string: description)
+            ]
+            self.init(enum: "packageWritability", subnodes: params)
+        }
+    }
+
     /// Instantiates a SourceCodeFragment to represent a single plugin permission.
     init(from permission: TargetDescription.PluginPermission) {
         switch permission {

Sources/PackageModel/Target.swift

@@ -664,7 +664,7 @@ public final class PluginTarget: Target {
 
 public enum PluginCapability: Hashable, Codable {
     case buildTool
-    case command(verb: String, description: String, permissions: [PluginPermission])
+    case command(intent: PluginCommandIntent, permissions: [PluginPermission])
 
     private enum CodingKeys: String, CodingKey {
         case buildTool, command
@@ -675,11 +675,10 @@ public enum PluginCapability: Hashable, Codable {
         switch self {
         case .buildTool:
             try container.encodeNil(forKey: .buildTool)
-        case .command(let a1, let a2, let a3):
+        case .command(let a1, let a2):
             var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .command)
             try unkeyedContainer.encode(a1)
             try unkeyedContainer.encode(a2)
-            try unkeyedContainer.encode(a3)
         }
     }
 
@@ -693,19 +692,35 @@ public enum PluginCapability: Hashable, Codable {
             self = .buildTool
         case .command:
             var unkeyedValues = try values.nestedUnkeyedContainer(forKey: key)
-            let a1 = try unkeyedValues.decode(String.self)
-            let a2 = try unkeyedValues.decode(String.self)
-            let a3 = try unkeyedValues.decode([PluginPermission].self)
-            self = .command(verb: a1, description: a2, permissions: a3)
+            let a1 = try unkeyedValues.decode(PluginCommandIntent.self)
+            let a2 = try unkeyedValues.decode([PluginPermission].self)
+            self = .command(intent: a1, permissions: a2)
         }
     }
 
     public init(from desc: TargetDescription.PluginCapability) {
         switch desc {
         case .buildTool:
             self = .buildTool
-        case .command(let verb, let description, let permissions):
-            self = .command(verb: verb, description: description, permissions: permissions.map{ .init(from: $0) })
+        case .command(let intent, let permissions):
+            self = .command(intent: .init(from: intent), permissions: permissions.map{ .init(from: $0) })
+        }
+    }
+}
+
+public enum PluginCommandIntent: Hashable, Codable {
+    case documentationGeneration
+    case sourceCodeFormatting
+    case custom(verb: String, description: String)
+
+    public init(from desc: TargetDescription.PluginCommandIntent) {
+        switch desc {
+        case .documentationGeneration:
+            self = .documentationGeneration
+        case .sourceCodeFormatting:
+            self = .sourceCodeFormatting
+        case .custom(let verb, let description):
+            self = .custom(verb: verb, description: description)
         }
     }
 }

Tests/FunctionalTests/PluginTests.swift

@@ -167,9 +167,8 @@ class PluginTests: XCTestCase {
                         .plugin(
                             name: "MyPlugin",
                             capability: .command(
-                                verb: "mycmd",
-                                description: "What is mycmd anyway?",
-                                permissions: [ .packageWritability(reason: "YOLO") ]
+                                intent: .custom(verb: "mycmd", description: "What is mycmd anyway?"),
+                                permissions: [.packageWritability(reason: "YOLO")]
                             )
                         ),
                     ]

Tests/PackageLoadingTests/PD_5_6_LoadingTests.swift

@@ -117,7 +117,7 @@ class PackageDescription5_6LoadingTests: PackageDescriptionLoadingTests {
         XCTAssertNoDiagnostics(observability.diagnostics)
 
         XCTAssertEqual(manifest.targets[0].type, .plugin)
-        XCTAssertEqual(manifest.targets[0].pluginCapability, .command(verb: "mycmd", description: "helpful description of mycmd", permissions: [.packageWritability(reason: "YOLO")]))
+        XCTAssertEqual(manifest.targets[0].pluginCapability, .command(intent: .custom(verb: "mycmd", description: "helpful description of mycmd"), permissions: [.packageWritability(reason: "YOLO")]))
     }
 
     func testPluginTargetCustomization() throws {