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)