simplify Unidoc’s CLI by adding a direct --project-path argument that defaults to current working directory

Author: tayloraswift

Package.resolved

@@ -102,8 +102,9 @@ let package:Package = .init(
         .package(url: "https://github.com/tayloraswift/swift-png", .upToNextMinor(
             from: "4.4.3")),
 
-        .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(
-            from: "1.5.0")),
+        // .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(
+        //     from: "1.5.0")),
+        .package(url: "https://github.com/apple/swift-argument-parser", branch: "main"),
         .package(url: "https://github.com/apple/swift-atomics", .upToNextMinor(
             from: "1.2.0")),
         .package(url: "https://github.com/apple/swift-collections", .upToNextMinor(

Package.swift

@@ -31,7 +31,9 @@ extension SSGC
 
         @Option(
             name: [.customLong("search-path"), .customShort("I")],
-            help: "Where to look for a SwiftPM package to build, if building locally",
+            help: """
+            DEPRECATED: Where to look for a SwiftPM package to build, if building locally
+            """,
             completion: .directory)
         var search:FilePath.Directory? = nil
 
@@ -67,13 +69,19 @@ extension SSGC
             help: "Run in CI mode under the specified validation level")
         var ci:ValidationBehavior? = nil
 
+        @Option(
+            name: [.customLong("project-path"), .customShort("p")],
+            help: "Path to a local project to build",
+            completion: .directory)
+        var projectPath:FilePath.Directory?
+
         @Option(
             name: [.customLong("package-name"), .customShort("n")],
             help: """
                 The symbolic name of the project to build — \
                 this is not the name specified in the `Package.swift` manifest!
                 """)
-        var project:String
+        var project:String?
 
         @Option(
             name: [.customLong("project-type"), .customShort("b")],
@@ -240,10 +248,11 @@ extension SSGC.Compile
 
         let object:SymbolGraphObject<Void>
 
-        if  let repo:String = self.repo,
+        if  let project:String = self.project,
+            let repo:String = self.repo,
             let ref:String = self.ref
         {
-            let symbol:Symbol.Package = .init(self.project)
+            let symbol:Symbol.Package = .init(project)
 
             defer
             {
@@ -277,10 +286,39 @@ extension SSGC.Compile
                 logger: logger,
                 clean: self.cleanArtifacts)
         }
-        else if
-            let search:FilePath.Directory = self.search
+        else if case "swift"? = self.project
+        {
+            object = try workspace.build(some: SSGC.StandardLibraryBuild.swift,
+                toolchain: toolchain,
+                status: status,
+                logger: logger,
+                clean: self.cleanArtifacts)
+        }
+        else
         {
-            let build:SSGC.PackageBuild = .local(project: search / self.project,
+            let computedPath:FilePath.Directory
+
+            if  let projectPath:FilePath.Directory = self.projectPath
+            {
+                computedPath = projectPath
+            }
+            else if  
+                let search:FilePath.Directory = self.search, 
+                let name:String = self.project
+            {
+                print("""
+                    Warning: '--search-path' is deprecated, use '--project-path' with the 
+                    full path to the project root instead
+                    """)
+
+                computedPath = search / name
+            }
+            else
+            {
+                throw SSGC.ProjectPathRequiredError.init()
+            }
+
+            let build:SSGC.PackageBuild = .local(project: computedPath,
                 using: ".build.ssgc",
                 as: self.type)
 
@@ -298,18 +336,6 @@ extension SSGC.Compile
                 logger: logger,
                 clean: self.cleanArtifacts)
         }
-        else if self.project == "swift"
-        {
-            object = try workspace.build(some: SSGC.StandardLibraryBuild.swift,
-                toolchain: toolchain,
-                status: status,
-                logger: logger,
-                clean: self.cleanArtifacts)
-        }
-        else
-        {
-            throw SSGC.SearchPathRequiredError.init()
-        }
 
         let output:FilePath = self.output ?? workspace.location / "docs.bson"
         try output.open(.writeOnly,

Sources/SymbolGraphBuilder/SSGC.Compile.swift

@@ -0,0 +1,6 @@
+extension SSGC
+{
+    struct ProjectPathRequiredError:Error
+    {
+    }
+}

Sources/SymbolGraphBuilder/SSGC.ProjectPathRequiredError.swift

@@ -279,13 +279,13 @@ extension Unidoc.Client<HTTP.Client2>
     }
 
     public
-    func buildAndUpload(local name:String,
-        search:FilePath.Directory?,
+    func buildAndUpload(local:FilePath.Directory?,
+        name:String?,
         type:SSGC.ProjectType,
         with toolchain:Unidoc.Toolchain) async throws
     {
-        let object:SymbolGraphObject<Void> = try await self.build(local: name,
-            search: search,
+        let object:SymbolGraphObject<Void> = try await self.build(local: local,
+            name: name,
             type: type,
             with: toolchain)
 
@@ -301,13 +301,13 @@ extension Unidoc.Client<HTTP.Client2>
 extension Unidoc.Client<HTTP.Client1>
 {
     public
-    func buildAndUpload(local name:String,
-        search:FilePath.Directory?,
+    func buildAndUpload(local:FilePath.Directory?,
+        name:String?,
         type:SSGC.ProjectType,
         with toolchain:Unidoc.Toolchain) async throws
     {
-        let object:SymbolGraphObject<Void> = try await self.build(local: name,
-            search: search,
+        let object:SymbolGraphObject<Void> = try await self.build(local: local,
+            name: name,
             type: type,
             with: toolchain)
 
@@ -318,13 +318,13 @@ extension Unidoc.Client<HTTP.Client1>
             http://\(self.http.remote):\(self.port)/tags/\(object.metadata.package.id)
             """)
     }
-}
+} 
 extension Unidoc.Client
 {
     /// Name is case-sensitive, so it is not modeled as a ``Symbol.Package``.
     private
-    func build(local name:String,
-        search:FilePath.Directory?,
+    func build(local:FilePath.Directory?,
+        name:String?,
         type:SSGC.ProjectType,
         with toolchain:Unidoc.Toolchain) async throws -> SymbolGraphObject<Void>
     {
@@ -334,7 +334,6 @@ extension Unidoc.Client
         var arguments:[String] = [
             "compile",
 
-            "--package-name", "\(name)",
             "--project-type", "\(type)",
             "--workspace", "\(workspace.location)",
             "--output", "\(docs)",
@@ -354,10 +353,15 @@ extension Unidoc.Client
             arguments.append("--sdk")
             arguments.append("\(sdk)")
         }
-        if  let search:FilePath.Directory
+        if  let local:FilePath.Directory 
+        {
+            arguments.append("--project-path")
+            arguments.append("\(local)")
+        }
+        if  let name:String
         {
-            arguments.append("--search-path")
-            arguments.append("\(search)")
+            arguments.append("--package-name")
+            arguments.append("\(name)")
         }
 
         let ssgc:SystemProcess = try .init(command: self.executablePath, arguments: arguments)

Sources/SymbolGraphBuilder/SSGC.SearchPathRequiredError.swift

@@ -10,7 +10,14 @@ extension Main
     struct Local
     {
         @Argument
-        var project:String
+        var project:String?
+
+        @Option(
+            name: [.customLong("project-path"), .customShort("i")],
+            help: "The path to the project to build",
+            completion: .directory)
+        var projectPath:FilePath.Directory = "."
+
 
         @Option(
             name: [.customLong("host"), .customShort("h")],
@@ -35,7 +42,7 @@ extension Main
 
         @Option(
             name: [.customLong("input"), .customShort("I")],
-            help: "The path to a directory containing the project to build",
+            help: "DEPRECATED: The path to a directory containing the project to build",
             completion: .directory)
         var input:FilePath.Directory?
 
@@ -78,8 +85,8 @@ extension Main.Local:AsyncParsableCommand
 
         print("Connecting to \(self.host):\(self.port)...")
 
-        try await unidoc.buildAndUpload(local: self.project,
-            search: self.input,
+        try await unidoc.buildAndUpload(local: self.projectPath,
+            name: self.project,
             type: self.book ? .book : .package,
             with: toolchain)
     }