Sanitize CLI (#409)

* reduce the amount of hidden directories Unidoc requires, split the CompileCommand into two subcommands

* make PackageBuild use the shared cache again, when running in slave mode

* i can’t seem to stop self-sabotaging

* update macOS package build script

Author: tayloraswift

.github/workflows/docs.yml renamed to .github/workflows/Docs.yml

@@ -19,8 +19,8 @@ jobs:
             -   name: Install Swift
                 uses: tayloraswift/swift-install-action@master
                 with:
-                    swift-prefix: "swift-6.0.1-release/ubuntu2404/swift-6.0.1-RELEASE"
-                    swift-id: "swift-6.0.1-RELEASE-ubuntu24.04"
+                    swift-prefix: "swift-6.0.3-release/ubuntu2404/swift-6.0.3-RELEASE"
+                    swift-id: "swift-6.0.3-RELEASE-ubuntu24.04"
 
             #   This installs an older version of Unidoc, not the one we are testing.
             #   We use `--static-swift-stdlib` so it doesn’t matter if the Unidoc binary was
@@ -34,9 +34,9 @@ jobs:
             -   name: Build documentation
                 run: |
                     unidoc compile -I .. \
-                    --swift-toolchain $SWIFT_INSTALLATION \
-                    --ci fail-on-errors \
-                    --package-name swift-unidoc
+                        --ci fail-on-errors \
+                        --package-name swift-unidoc \
+                        --swift-toolchain $SWIFT_INSTALLATION
 
     macos:
         runs-on: macos-15
@@ -54,5 +54,5 @@ jobs:
             -   name: Build documentation
                 run: |
                     unidoc compile -I .. \
-                    --ci fail-on-errors \
-                    --package-name swift-unidoc
+                        --ci fail-on-errors \
+                        --package-name swift-unidoc

.gitignore

@@ -16,6 +16,7 @@
 /Assets/secrets/
 /Assets/icons/*.jpg
 
+/TestModules/Determinism/*.json
 /TestModules/SymbolGraphs/*.json
 /TestModules/*.json
 /TestPackages/*.bson

README.md

@@ -3,7 +3,7 @@
 <strong><em><code>unidoc</code></em></strong>
 
 [![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/Test.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/Test.yml)
-[![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/docs.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/docs.yml)
+[![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/Docs.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/Docs.yml)
 [![ci build status](https://github.com/tayloraswift/swift-unidoc/actions/workflows/Deploy.yml/badge.svg)](https://github.com/tayloraswift/swift-unidoc/actions/workflows/Deploy.yml)
 
 </div>

Scripts/Linux/GeneratePackageSymbolGraphs

@@ -3,53 +3,37 @@ set -e
 
 swift --version
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/apple/swift-atomics.git \
-    -t 1.2.0 \
-    -n swift-atomics \
+ssgc slave https://github.com/apple/swift-atomics.git 1.2.0 \
+    -u $SWIFT_INSTALLATION \
     -o TestPackages/swift-atomics.bson
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/apple/swift-nio.git \
-    -t 2.75.0 \
-    -n swift-nio \
+ssgc slave https://github.com/apple/swift-nio.git 2.75.0 \
+    -u $SWIFT_INSTALLATION \
     -o TestPackages/swift-nio.bson
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/apple/swift-nio-ssl.git \
-    -t 2.29.0 \
-    -n swift-nio-ssl \
+ssgc slave https://github.com/apple/swift-nio-ssl.git 2.29.0 \
+    -u $SWIFT_INSTALLATION \
     -o TestPackages/swift-nio-ssl.bson
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/apple/swift-async-dns-resolver.git \
-    -t 0.1.2 \
-    -n swift-async-dns-resolver \
+ssgc slave https://github.com/apple/swift-async-dns-resolver.git 0.1.2 \
+    -u $SWIFT_INSTALLATION \
     -o TestPackages/swift-async-dns-resolver.bson
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/swiftlang/swift-syntax.git \
-    -t 600.0.1 \
-    -n swift-syntax \
+ssgc slave https://github.com/swiftlang/swift-syntax.git 600.0.1 \
+    -u $SWIFT_INSTALLATION \
     -o TestPackages/swift-syntax.bson
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/pointfreeco/swift-snapshot-testing.git \
-    -t 1.17.5 \
-    -n swift-snapshot-testing \
+ssgc slave https://github.com/pointfreeco/swift-snapshot-testing.git 1.17.5 \
+    -u $SWIFT_INSTALLATION \
     -o TestPackages/swift-snapshot-testing.bson
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/swiftlang/indexstore-db.git \
-    -t swift-6.0-RELEASE \
-    -n indexstore-db \
+ssgc slave https://github.com/swiftlang/indexstore-db.git swift-6.0-RELEASE \
+    -u $SWIFT_INSTALLATION \
     -o TestPackages/indexstore-db.bson \
     --Xcxx -I$SWIFT_INSTALLATION/lib/swift \
     --Xcxx -I$SWIFT_INSTALLATION/lib/swift/Block
 
-ssgc -u $SWIFT_INSTALLATION \
-    -r https://github.com/swiftlang/swift-book.git \
-    -t swift-5.10-fcs \
+ssgc slave https://github.com/swiftlang/swift-book.git swift-5.10-fcs \
+    -u $SWIFT_INSTALLATION \
     -b book \
-    -n swift-book \
     -o TestPackages/swift-book.bson

Scripts/Linux/GenerateTestSymbolGraphs

@@ -41,13 +41,13 @@ do
     done
 done
 
-.build/release/ssgc -u $SWIFT_INSTALLATION \
+.build/release/ssgc build -u $SWIFT_INSTALLATION \
     -n swift \
     -o TestPackages/swift.bson
 
 for PACKAGE in swift-test swift-malibu swift-snippets swift-exportation cross-module-articles
 do
-    .build/release/ssgc -u $SWIFT_INSTALLATION \
+    .build/release/ssgc build -u $SWIFT_INSTALLATION \
         -p TestPackages/$PACKAGE \
         -o TestPackages/$PACKAGE.bson
 done

Scripts/macOS/GeneratePackageSymbolGraphs

@@ -3,51 +3,27 @@ set -e
 
 swift --version
 
-ssgc \
-    -r https://github.com/apple/swift-atomics.git \
-    -t 1.2.0 \
-    -n swift-atomics \
+ssgc slave https://github.com/apple/swift-atomics.git 1.2.0 \
     -o TestPackages/swift-atomics.bson
 
-ssgc \
-    -r https://github.com/apple/swift-nio.git \
-    -t 2.75.0 \
-    -n swift-nio \
+ssgc slave https://github.com/apple/swift-nio.git 2.75.0 \
     -o TestPackages/swift-nio.bson
 
-ssgc \
-    -r https://github.com/apple/swift-nio-ssl.git \
-    -t 2.29.0 \
-    -n swift-nio-ssl \
+ssgc slave https://github.com/apple/swift-nio-ssl.git 2.29.0 \
     -o TestPackages/swift-nio-ssl.bson
 
-ssgc \
-    -r https://github.com/apple/swift-async-dns-resolver.git \
-    -t 0.1.2 \
-    -n swift-async-dns-resolver \
+ssgc slave https://github.com/apple/swift-async-dns-resolver.git 0.1.2 \
     -o TestPackages/swift-async-dns-resolver.bson
 
-ssgc \
-    -r https://github.com/swiftlang/swift-syntax.git \
-    -t 600.0.1 \
-    -n swift-syntax \
+ssgc slave https://github.com/swiftlang/swift-syntax.git 600.0.1 \
     -o TestPackages/swift-syntax.bson
 
-ssgc \
-    -r https://github.com/pointfreeco/swift-snapshot-testing.git \
-    -t 1.17.5 \
-    -n swift-snapshot-testing \
+ssgc slave https://github.com/pointfreeco/swift-snapshot-testing.git 1.17.5 \
     -o TestPackages/swift-snapshot-testing.bson
 
-ssgc \
-    -r https://github.com/swiftlang/indexstore-db.git \
-    -t swift-6.0-RELEASE \
-    -n indexstore-db \
+ssgc slave https://github.com/swiftlang/indexstore-db.git swift-6.0-RELEASE \
     -o TestPackages/indexstore-db.bson
 
-ssgc \
-    -r https://github.com/swiftlang/swift-book.git \
-    -t swift-5.10-fcs \
+ssgc slave https://github.com/swiftlang/swift-book.git swift-5.10-fcs \
     -b book \
-    -n swift-book \
     -o TestPackages/swift-book.bson

Sources/SymbolGraphBuilder/Builds/SSGC.DocumentationBuild.swift

@@ -5,10 +5,33 @@ extension SSGC
 {
     protocol DocumentationBuild
     {
-        mutating
         func compile(updating status:SSGC.StatusStream?,
-            cache:FilePath.Directory,
             with swift:Toolchain,
             clean:Bool) throws -> (SymbolGraphMetadata, any DocumentationSources)
     }
 }
+extension SSGC.DocumentationBuild
+{
+    func build(
+        toolchain swift:SSGC.Toolchain,
+        define defines:[String] = [],
+        status:SSGC.StatusStream? = nil,
+        logger:SSGC.Logger = .default(),
+        clean:Bool) throws -> SymbolGraphObject<Void>
+    {
+        /// TODO: support values?
+        let definitions:[String: Void] = defines.reduce(into: [:]) { $0[$1] = () }
+
+        let metadata:SymbolGraphMetadata
+        let package:any SSGC.DocumentationSources
+
+        (metadata, package) = try self.compile(updating: status, with: swift, clean: clean)
+
+        let documentation:SymbolGraph = try package.link(
+            definitions: definitions,
+            logger: logger,
+            with: swift)
+
+        return .init(metadata: metadata, graph: documentation)
+    }
+}

Sources/SymbolGraphBuilder/Builds/SSGC.PackageBuild.swift

@@ -15,6 +15,7 @@ extension SSGC
         let id:ID
 
         let scratch:PackageBuildDirectory
+        let cache:FilePath.Directory?
 
         /// Additional flags to pass to the Swift compiler.
         var flags:Flags
@@ -26,12 +27,14 @@ extension SSGC
         private
         init(id:ID,
             scratch:PackageBuildDirectory,
+            cache:FilePath.Directory?,
             flags:Flags,
             root:FilePath.Directory,
             type:ProjectType)
         {
             self.id = id
             self.scratch = scratch
+            self.cache = cache
             self.flags = flags
             self.root = root
             self.type = type
@@ -81,8 +84,8 @@ extension SSGC.PackageBuild
     ///         The type of project to build.
     ///     -   flags:
     ///         Additional flags to pass to the Swift compiler.
-    public static
-    func local(project location:FilePath.Directory,
+    public
+    static func local(project location:FilePath.Directory,
         using scratchName:FilePath.Component = ".build.ssgc",
         as type:SSGC.ProjectType = .package,
         flags:Flags = .init()) -> Self
@@ -103,6 +106,7 @@ extension SSGC.PackageBuild
 
         return .init(id: .unversioned(.init(last.string)),
             scratch: scratch,
+            cache: nil,
             flags: flags,
             root: location,
             type: type)
@@ -124,8 +128,8 @@ extension SSGC.PackageBuild
     ///         The type of project to build.
     ///     -   workspace:
     ///         The directory in which this function will create folders.
-    public static
-    func remote(project projectName:Symbol.Package,
+    public
+    static func remote(project projectName:Symbol.Package,
         from repository:String,
         at refName:String,
         as type:SSGC.ProjectType = .package,
@@ -153,6 +157,7 @@ extension SSGC.PackageBuild
 
         return .init(id: .versioned(pin, ref: refName, date: checkout.date),
             scratch: scratch,
+            cache: workspace.cache,
             flags: flags,
             root: checkout.location,
             type: type)
@@ -162,22 +167,16 @@ extension SSGC.PackageBuild
 extension SSGC.PackageBuild:SSGC.DocumentationBuild
 {
     func compile(updating status:SSGC.StatusStream?,
-        cache:FilePath.Directory,
         with toolchain:SSGC.Toolchain,
         clean:Bool = true) throws -> (SymbolGraphMetadata, any SSGC.DocumentationSources)
     {
         switch self.type
         {
         case .package:
-            try self.compileSwiftPM(updating: status,
-                cache: cache,
-                with: toolchain,
-                clean: clean)
+            try self.compileSwiftPM(updating: status, with: toolchain, clean: clean)
 
         case .book:
-            try self.compileBook(updating: status,
-                cache: cache,
-                with: toolchain)
+            try self.compileBook(updating: status, with: toolchain)
         }
     }
 }
@@ -186,7 +185,6 @@ extension SSGC.PackageBuild
 {
     @_spi(testable) public
     func compileBook(updating status:SSGC.StatusStream? = nil,
-        cache _:FilePath.Directory,
         with toolchain:SSGC.Toolchain) throws -> (SymbolGraphMetadata, SSGC.BookSources)
     {
         switch self.id
@@ -232,7 +230,6 @@ extension SSGC.PackageBuild
 
     @_spi(testable) public
     func compileSwiftPM(updating status:SSGC.StatusStream? = nil,
-        cache _:FilePath.Directory,
         with toolchain:SSGC.Toolchain,
         clean:Bool = true) throws -> (SymbolGraphMetadata, SSGC.PackageSources)
     {
@@ -324,7 +321,7 @@ extension SSGC.PackageBuild
 
         //  Dump the standard library’s symbols, unless they’re already cached.
         let symbolsCached:FilePath.Directory = try toolchain.dump(stdlib: stdlib,
-            cache: artifacts)
+            cache: self.cache ?? artifacts)
 
         let symbols:FilePath.Directory = artifacts / "symbols"
         try symbols.create(clean: false)