feat(amplify-xcode): generate JSON schema (#1080)

* amplify-xcode: generate JSON schema

* Delete old CLICommandGenerateBindings.swift

* feat: fix typo in command name

* feat(amplify-xcode): apply suggestions from code review (spacing nit)

Co-authored-by: Tim Schmelter <[email protected]>

* feat(amplify-xcode): address PR comments

* feat(amplify-xcode): add docs, rename CLICommandEncodable

* feat(amplify-xcode): re-generate xcodeproj file

* feat(amplify-xcode): re-run swiftformat

* feat(amplify-xcode): generate-schema generates schema of itself

* feat(amplify-xcode): add docs around schema generations

* feat(amplify-xcode): add param label to clarify usage of parameters ref

* feat(amplify-xcode): address PR comments

Co-authored-by: Tim Schmelter <[email protected]>

Author: diegocstn

AmplifyTools/AmplifyXcode/AmplifyXcode.xcodeproj/project.pbxproj

@@ -26,43 +26,25 @@
       buildConfiguration = "Debug"
       selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
       selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
-      shouldUseLaunchSchemeArgsEnv = "YES"
-      codeCoverageEnabled = "YES"
-      onlyGenerateCoverageForSpecifiedTargets = "YES">
-      <CodeCoverageTargets>
-         <BuildableReference
-            BuildableIdentifier = "primary"
-            BlueprintIdentifier = "AmplifyXcode::AmplifyXcodeCore"
-            BuildableName = "AmplifyXcodeCore.framework"
-            BlueprintName = "AmplifyXcodeCore"
-            ReferencedContainer = "container:AmplifyXcode.xcodeproj">
-         </BuildableReference>
-         <BuildableReference
-            BuildableIdentifier = "primary"
-            BlueprintIdentifier = "AmplifyXcode::AmplifyXcode"
-            BuildableName = "AmplifyXcode"
-            BlueprintName = "AmplifyXcode"
-            ReferencedContainer = "container:AmplifyXcode.xcodeproj">
-         </BuildableReference>
-      </CodeCoverageTargets>
+      shouldUseLaunchSchemeArgsEnv = "YES">
       <Testables>
          <TestableReference
             skipped = "NO">
             <BuildableReference
                BuildableIdentifier = "primary"
-               BlueprintIdentifier = "AmplifyXcode::AmplifyXcodeTests"
-               BuildableName = "AmplifyXcodeTests.xctest"
-               BlueprintName = "AmplifyXcodeTests"
+               BlueprintIdentifier = "AmplifyXcode::AmplifyXcodeCoreTests"
+               BuildableName = "AmplifyXcodeCoreTests.xctest"
+               BlueprintName = "AmplifyXcodeCoreTests"
                ReferencedContainer = "container:AmplifyXcode.xcodeproj">
             </BuildableReference>
          </TestableReference>
          <TestableReference
             skipped = "NO">
             <BuildableReference
                BuildableIdentifier = "primary"
-               BlueprintIdentifier = "AmplifyXcode::AmplifyXcodeCoreTests"
-               BuildableName = "AmplifyXcodeCoreTests.xctest"
-               BlueprintName = "AmplifyXcodeCoreTests"
+               BlueprintIdentifier = "AmplifyXcode::AmplifyXcodeTests"
+               BuildableName = "AmplifyXcodeTests.xctest"
+               BlueprintName = "AmplifyXcodeTests"
                ReferencedContainer = "container:AmplifyXcode.xcodeproj">
             </BuildableReference>
          </TestableReference>

AmplifyTools/AmplifyXcode/AmplifyXcode.xcodeproj/xcshareddata/xcschemes/AmplifyXcode.xcscheme

@@ -18,5 +18,9 @@ import AmplifyXcodeCore
 struct AmplifyXcode: ParsableCommand {
     static let configuration = CommandConfiguration(
         abstract: "Amplify Xcode CLI",
-        subcommands: [CLICommandImportConfig.self, CLICommandImportModels.self])
+        subcommands: [
+            CLICommandImportConfig.self,
+            CLICommandImportModels.self,
+            CLICommandGenerateJSONSchema.self
+        ])
 }

AmplifyTools/AmplifyXcode/Sources/AmplifyXcode/CLI.swift

@@ -0,0 +1,14 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+struct AnyCLICommandEncodable: Encodable {
+    let name: String
+    let abstract: String
+    let parameters: Set<CLICommandParameter>
+}

AmplifyTools/AmplifyXcode/Sources/AmplifyXcode/CLIAnyCommandEncodable.swift

@@ -0,0 +1,41 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+import ArgumentParser
+
+protocol CLICommandInitializable {
+    init()
+}
+
+private enum CLICommandCodingKeys: String, CodingKey {
+    case commandName
+    case abstract
+    case parameters
+}
+
+protocol CLICommand: Encodable, CLICommandInitializable {
+    static var commandName: String { get }
+    static var abstract: String { get }
+    static var parameters: Set<CLICommandParameter> { get }
+}
+
+extension CLICommand {
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CLICommandCodingKeys.self)
+        try container.encode(Self.commandName, forKey: .commandName)
+        try container.encode(Self.abstract, forKey: .abstract)
+        try container.encode(Self.parameters, forKey: .parameters)
+    }
+}
+
+// MARK: - ParsableCommand + CLICommandEncodable
+
+extension CLICommand where Self: ParsableCommand {
+    static var commandName: String { Self.configuration.commandName! }
+    static var abstract: String { Self.configuration.abstract }
+}

AmplifyTools/AmplifyXcode/Sources/AmplifyXcode/CLICommand.swift

@@ -0,0 +1,54 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+import AmplifyXcodeCore
+import ArgumentParser
+
+/// Encodable representation of the `amplify-xcode` CLI.
+/// In order to get the necessary information to produce a representation of each commands,
+/// we instantiate them to have their params property wrappers initialized and therefore registered
+/// as `CLICommandParameter`s.
+private struct CLISchema: Encodable {
+    let abstract = "Auto generated JSON representation of amplify-xcode CLI"
+    var commands: [AnyCLICommandEncodable] = []
+
+    init() {
+        for command in AmplifyXcode.configuration.subcommands {
+            guard let command = command as? CLICommand.Type else {
+                continue
+            }
+            _ = command.init()
+            commands.append(AnyCLICommandEncodable(name: command.commandName,
+                                                   abstract: command.abstract,
+                                                   parameters: command.parameters))
+        }
+    }
+}
+
+struct CLICommandGenerateJSONSchema: ParsableCommand, CommandExecutable, CLICommand {
+    static var parameters = Set<CLICommandParameter>()
+    static let configuration = CommandConfiguration(
+        commandName: "generate-schema",
+        abstract: "Generates a JSON description of the CLI and its commands"
+    )
+
+    @Option(name: "output-path", help: "Path to save the output of generated schema file", updating: &parameters)
+    private var outputPath: String
+
+    var environment: AmplifyCommandEnvironment {
+        CommandEnvironment(basePath: outputPath, fileManager: FileManager.default)
+    }
+
+    func run() throws {
+        let schema = try JSONEncoder().encode(CLISchema())
+        let schemaFileName = "amplify-xcode.json"
+        let fullPath = try environment.createFile(atPath: schemaFileName,
+                                                  content: String(data: schema, encoding: .utf8)!)
+        print("Schema generated at: \(fullPath)")
+    }
+}

AmplifyTools/AmplifyXcode/Sources/AmplifyXcode/CLICommandGenerateJSONSchema.swift

@@ -10,13 +10,14 @@ import ArgumentParser
 import AmplifyXcodeCore
 
 /// CLI command invoking `CommandImportConfig`.
-struct CLICommandImportConfig: ParsableCommand, CommandExecutable, CLICommandReportable {
+struct CLICommandImportConfig: ParsableCommand, CommandExecutable, CLICommandReportable, CLICommand {
+    static var parameters = Set<CLICommandParameter>()
     static let configuration = CommandConfiguration(
         commandName: "import-config",
         abstract: CommandImportConfig.description
     )
 
-    @Option(name: .shortAndLong, help: "Project base path")
+    @Option(name: "path", help: "Project base path", updating: &parameters)
     private var path: String = Process().currentDirectoryPath
 
     var environment: AmplifyCommandEnvironment {

AmplifyTools/AmplifyXcode/Sources/AmplifyXcode/CLICommandImportConfig.swift

@@ -10,13 +10,14 @@ import ArgumentParser
 import AmplifyXcodeCore
 
 /// CLI command invoking `CommandImportModels`.
-struct CLICommandImportModels: ParsableCommand, CommandExecutable, CLICommandReportable {
+struct CLICommandImportModels: ParsableCommand, CommandExecutable, CLICommandReportable, CLICommand {
+    static var parameters = Set<CLICommandParameter>()
     static let configuration = CommandConfiguration(
         commandName: "import-models",
         abstract: CommandImportModels.description
     )
 
-    @Option(name: .shortAndLong, help: "Project base path")
+    @Option(name: "path", help: "Project base path", updating: &parameters)
     private var path: String = Process().currentDirectoryPath
 
     var environment: AmplifyCommandEnvironment {

AmplifyTools/AmplifyXcode/Sources/AmplifyXcode/CLICommandImportModels.swift

@@ -0,0 +1,55 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+
+/// Encodable representation of a CLI command parameter.
+/// Commands parameters (options, flags, arguments) are declared as properties on the command type
+/// and annotated with `@propertyWrapper`s `@Option`, `@Flag` and `@Argument` provided by `ArgumentParser`.
+/// `ArgumentParser` derives parameters names from property names (i.e.,  an`outputPath` option becomes `--output-path`)
+/// making thus impossible to reliably generate a JSON representation of a command and its parameters.
+/// Therefore we use the following enum to keep track of each parameter and their attributes (name, type and help text).
+enum CLICommandParameter: Hashable {
+    case option(name: String, type: String, help: String)
+    case argument(name: String, type: String, help: String)
+    case flag(name: String, type: String, help: String)
+
+    var kind: String {
+        switch self {
+        case .option:
+            return "option"
+        case .argument:
+            return "argument"
+        case .flag:
+            return "flag"
+        }
+    }
+}
+
+// MARK: - CLICommandEncodableParameter + Encodable
+
+extension CLICommandParameter: Encodable {
+    private enum CodingKeys: CodingKey {
+        case kind
+        case name
+        case type
+        case help
+    }
+
+    func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        switch self {
+        case .option(let name, let type, let help),
+             .argument(let name, let type, let help),
+             .flag(let name, let type, let help):
+            try container.encode(name, forKey: .name)
+            try container.encode(type, forKey: .type)
+            try container.encode(help, forKey: .help)
+            try container.encode(kind, forKey: .kind)
+        }
+    }
+}

AmplifyTools/AmplifyXcode/Sources/AmplifyXcode/CLICommandParameter.swift

@@ -0,0 +1,48 @@
+//
+// Copyright Amazon.com Inc. or its affiliates.
+// All Rights Reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+
+import Foundation
+import ArgumentParser
+
+/// The following extensions on ArgumentParser commands parameters property wrappers
+/// help us providing a hook to generate a JSON representation of a CLI command.
+/// As for now `@PropertyWrappers` APIs to access enclosing type are still "private", so the passed
+/// `parameters` allows the property to reference an external type.
+/// `Argument` has been left out on purpose as we'd rather use options and flags for clarity of use.
+/// Also by providing these extra initializers we make parameter name explicit.
+extension Option where Value: ExpressibleByArgument {
+    init(wrappedValue: Value, name: String, help: String, updating parameters: inout Set<CLICommandParameter>) {
+        self.init(
+            wrappedValue: wrappedValue,
+            name: .customLong(name),
+            parsing: .next,
+            completion: nil,
+            help: ArgumentHelp(help)
+          )
+        let type = String(describing: Value.self)
+        parameters.insert(.option(name: name, type: type, help: help))
+    }
+
+    init(name: String, help: String, updating parameters: inout Set<CLICommandParameter>) {
+        self.init(
+            name: .customLong(name),
+            parsing: .next,
+            help: ArgumentHelp(help),
+            completion: nil
+          )
+        let type = String(describing: Value.self)
+        parameters.insert(.option(name: name, type: type, help: help))
+    }
+}
+
+extension Flag where Value == Bool {
+    init(wrappedValue: Value, name: String, help: String, updating parameters: inout Set<CLICommandParameter>) {
+        self.init(wrappedValue: wrappedValue, name: .customLong(name), help: ArgumentHelp(help))
+        let type = String(describing: Value.self)
+        parameters.insert(.flag(name: name, type: type, help: help))
+    }
+}