Merge branch 'main' into add-extended-types-flag

theMomax · web-flow · commit 04aed7c386a1 · 2022-12-21T11:56:44.000+01:00
diff --git a/IntegrationTests/Tests/DocCArchiveIndexGenerationTests.swift b/IntegrationTests/Tests/DocCArchiveIndexGenerationTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class DocCArchiveIndexGenerationTests: XCTestCase {
+final class DocCArchiveIndexGenerationTests: ConcurrencyRequiringTestCase {
     func testGenerateDocumentationWithIndexingEnabled() throws {
         let result = try swiftPackage(
             "generate-documentation",
diff --git a/IntegrationTests/Tests/Fixtures/PackageWithSnippets/Package.swift b/IntegrationTests/Tests/Fixtures/PackageWithSnippets/Package.swift
@@ -13,6 +13,9 @@ import PackageDescription
 
 let package = Package(
     name: "PackageWithSnippets",
+    products: [
+        .library(name: "Library", targets: ["Library"])
+    ],
     targets: [
         .target(name: "Library"),
     ]
diff --git a/IntegrationTests/Tests/MixedTargetsTests.swift b/IntegrationTests/Tests/MixedTargetsTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class MixedTargetsTests: XCTestCase {
+final class MixedTargetsTests: ConcurrencyRequiringTestCase {
     func testGenerateDocumentationForSpecificTarget() throws {
         let result = try swiftPackage(
             "generate-documentation", "--target", "Executable",
diff --git a/IntegrationTests/Tests/SingleExecutableTargetTests.swift b/IntegrationTests/Tests/SingleExecutableTargetTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class SingleExecutableTargetTests: XCTestCase {
+final class SingleExecutableTargetTests: ConcurrencyRequiringTestCase {
     func testGenerateDocumentation() throws {
         let result = try swiftPackage(
             "generate-documentation",
diff --git a/IntegrationTests/Tests/SingleLibraryTargetTests.swift b/IntegrationTests/Tests/SingleLibraryTargetTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class SingleLibraryTargetTests: XCTestCase {
+final class SingleLibraryTargetTests: ConcurrencyRequiringTestCase {
     func testGenerateDocumentation() throws {
         let result = try swiftPackage(
             "generate-documentation",
diff --git a/IntegrationTests/Tests/SingleTestTargetTests.swift b/IntegrationTests/Tests/SingleTestTargetTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class SingleTestTargetTests: XCTestCase {
+final class SingleTestTargetTests: ConcurrencyRequiringTestCase {
     func testDoesNotGenerateDocumentation() throws {
         let result = try swiftPackage(
             "generate-documentation",
diff --git a/IntegrationTests/Tests/SnippetDocumentationGenerationTests.swift b/IntegrationTests/Tests/SnippetDocumentationGenerationTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class SnippetDocumentationGenerationTests: XCTestCase {
+final class SnippetDocumentationGenerationTests: ConcurrencyRequiringTestCase {
     func testGenerateDocumentationForPackageWithSnippets() throws {
         let result = try swiftPackage(
             "generate-documentation",
diff --git a/IntegrationTests/Tests/SwiftDocCPreviewTests.swift b/IntegrationTests/Tests/SwiftDocCPreviewTests.swift
@@ -9,7 +9,7 @@
 import Foundation
 import XCTest
 
-final class SwiftDocCPreview: XCTestCase {
+final class SwiftDocCPreview: ConcurrencyRequiringTestCase {
     func testRunPreviewServerOnSamePortRepeatedly() throws {
         // Because only a single server can bind to a given port at a time,
         // this test ensures that the preview server running in the `docc`
diff --git a/IntegrationTests/Tests/SwiftPMSandboxTests.swift b/IntegrationTests/Tests/SwiftPMSandboxTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class SwiftPMSandboxTests: XCTestCase {
+final class SwiftPMSandboxTests: ConcurrencyRequiringTestCase {
     func testEnableAdditionalSandboxedDirectories() throws {
         let outputDirectory = try temporaryDirectory()
         
diff --git a/IntegrationTests/Tests/TargetWithDocCCatalogTests.swift b/IntegrationTests/Tests/TargetWithDocCCatalogTests.swift
@@ -8,7 +8,7 @@
 
 import XCTest
 
-final class TargetWithDocCCatalogTests: XCTestCase {
+final class TargetWithDocCCatalogTests: ConcurrencyRequiringTestCase {
     func testGenerateDocumentation() throws {
         let result = try swiftPackage(
             "generate-documentation",
diff --git a/IntegrationTests/Tests/Utility/ConcurrencyRequiringTestCase.swift b/IntegrationTests/Tests/Utility/ConcurrencyRequiringTestCase.swift
@@ -0,0 +1,87 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+
+import Foundation
+import XCTest
+
+/// A test case that requires the host toolchain to support Swift concurrency in order
+/// to pass.
+///
+/// All SwiftPM command plugins depend on Swift concurrency so we don't expect to be able
+/// to run any integration test that actually invokes the Swift-DocC Plugin without
+/// the Swift concurrency libraries.
+class ConcurrencyRequiringTestCase: XCTestCase {
+    override func setUpWithError() throws {
+        try XCTSkipUnless(
+            supportsSwiftConcurrency(),
+            "The current SDK and/or OS do not support Swift concurrency."
+        )
+    }
+    
+    private static var _supportsSwiftConcurrency: Bool?
+    
+    // Adapted from https://github.com/apple/swift-package-manager/blob/dd7e9cc6/Sources/SPMTestSupport/Toolchain.swift#L55
+    private func supportsSwiftConcurrency() throws -> Bool {
+#if os(macOS)
+        if #available(macOS 12.0, *) {
+            // On macOS 12 and later, concurrency is assumed to work.
+            return true
+        } else {
+            if let _supportsSwiftConcurrency = Self._supportsSwiftConcurrency {
+                return _supportsSwiftConcurrency
+            }
+            
+            let temporaryDirectory = try temporaryDirectory()
+            
+            // On macOS 11 and earlier, we don't know if concurrency actually works because not all
+            // SDKs and toolchains have the right bits.  We could examine the SDK and the various
+            // libraries, but the most accurate test is to just try to compile and run a snippet of
+            // code that requires async/await support.  It doesn't have to actually do anything,
+            // it's enough that all the libraries can be found (but because the library reference
+            // is weak we do need the linkage reference to `_swift_task_create` and the like).
+            do {
+                let inputPath = temporaryDirectory.appendingPathComponent("foo.swift")
+                
+                try """
+                public func foo() async {}
+                
+                Task { await foo() }
+                """.write(to: inputPath, atomically: true, encoding: .utf8)
+                
+                let outputPath = temporaryDirectory.appendingPathComponent("foo")
+                let process = Process()
+                process.executableURL = try swiftExecutableURL
+                    .deletingLastPathComponent()
+                    .appendingPathComponent("swiftc")
+                
+                process.arguments = [inputPath.path, "-o", outputPath.path]
+                
+                try process.run()
+                process.waitUntilExit()
+                guard process.terminationStatus == EXIT_SUCCESS else {
+                    Self._supportsSwiftConcurrency = false
+                    return false
+                }
+            } catch {
+                // On any failure we assume false.
+                Self._supportsSwiftConcurrency = false
+                return false
+            }
+            // If we get this far we could compile and run a trivial executable that uses
+            // libConcurrency, so we can say that this toolchain supports concurrency on this host.
+            Self._supportsSwiftConcurrency = true
+            return true
+        }
+#else
+        // On other platforms, concurrency is assumed to work since with new enough versions
+        // of the toolchain.
+        return true
+#endif
+    }
+}
+
diff --git a/IntegrationTests/Tests/Utility/XCTestCase+swiftPackage.swift b/IntegrationTests/Tests/Utility/XCTestCase+swiftPackage.swift
@@ -110,7 +110,7 @@ extension XCTestCase {
         }
     }
     
-    private var swiftExecutableURL: URL {
+    var swiftExecutableURL: URL {
         get throws {
             let whichProcess = Process.shell("which swift")
             
diff --git a/Package.swift b/Package.swift
@@ -56,6 +56,7 @@ let package = Package(
             dependencies: [
                 "Snippets",
                 "SwiftDocCPluginUtilities",
+                "snippet-extract",
             ],
             resources: [
                 .copy("Test Fixtures"),
diff --git a/Sources/SwiftDocCPluginUtilities/Snippets/SnippetExtractor.swift b/Sources/SwiftDocCPluginUtilities/Snippets/SnippetExtractor.swift
@@ -15,7 +15,7 @@ public class SnippetExtractor {
     
     enum SymbolGraphExtractionResult {
         case packageDoesNotProduceSnippets
-        case packageContainsSnippets(symbolGraphDirectory: URL)
+        case packageContainsSnippets(symbolGraphFile: URL)
     }
     
     private let snippetTool: URL
@@ -65,6 +65,27 @@ public class SnippetExtractor {
     var _fileExists: (_ path: String) -> Bool = { path in
         return FileManager.default.fileExists(atPath: path)
     }
+
+    /// Returns all of the `.swift` files under a directory recursively.
+    ///
+    /// Provided for testing.
+    var _findSnippetFilesInDirectory: (_ directory: URL) -> [String] = { directory -> [String] in
+        guard let snippetEnumerator = FileManager.default.enumerator(at: directory,
+                                                                     includingPropertiesForKeys: nil,
+                                                                     options: [.skipsHiddenFiles]) else {
+            return []
+
+        }
+        var snippetInputFiles = [String]()
+        for case let potentialSnippetURL as URL in snippetEnumerator {
+            guard potentialSnippetURL.pathExtension.lowercased() == "swift" else {
+                continue
+            }
+            snippetInputFiles.append(potentialSnippetURL.path)
+        }
+
+        return snippetInputFiles
+    }
     
     /// Generate snippets for the given package.
     ///
@@ -79,16 +100,15 @@ public class SnippetExtractor {
     ///     The snippet extractor will look for a `Snippets` subdirectory
     ///     within this directory.
     ///
-    /// - Returns: A URL for the directory containing the generated snippets or nil if
-    ///   no snippets were produced.
+    /// - Returns: A URL for the output file of the generated snippets symbol graph JSON file.
     public func generateSnippets(
         for packageIdentifier: PackageIdentifier,
         packageDisplayName: String,
         packageDirectory: URL
     ) throws -> URL? {
         switch snippetSymbolGraphExtractionResults[packageIdentifier] {
-        case .packageContainsSnippets(symbolGraphDirectory: let symbolGraphDirectory):
-            return symbolGraphDirectory
+        case .packageContainsSnippets(symbolGraphFile: let symbolGraphFile):
+            return symbolGraphFile
         case .packageDoesNotProduceSnippets:
             return nil
         case .none:
@@ -100,26 +120,34 @@ public class SnippetExtractor {
             snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
             return nil
         }
+
+        let snippetInputFiles = _findSnippetFilesInDirectory(snippetsDirectory)
+
+        guard !snippetInputFiles.isEmpty else {
+            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
+            return nil
+        }
         
         let outputDirectory = snippetsOutputDirectory(
             in: workingDirectory,
             packageIdentifier: packageIdentifier,
             packageDisplayName: packageDisplayName
         )
+
+        let outputFile = outputDirectory.appendingPathComponent("\(packageDisplayName)-snippets.symbols.json")
         
         let process = Process()
         process.executableURL = snippetTool
         process.arguments = [
-            snippetsDirectory.path,
-            outputDirectory.path,
-            packageDisplayName,
-        ]
-        
+            "--output", outputFile.path,
+            "--module-name", packageDisplayName,
+        ] + snippetInputFiles
+
         try _runProcess(process)
         
-        if _fileExists(outputDirectory.path) {
-            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageContainsSnippets(symbolGraphDirectory: outputDirectory)
-            return outputDirectory
+        if _fileExists(outputFile.path) {
+            snippetSymbolGraphExtractionResults[packageIdentifier] = .packageContainsSnippets(symbolGraphFile: outputFile)
+            return outputFile
         } else {
             snippetSymbolGraphExtractionResults[packageIdentifier] = .packageDoesNotProduceSnippets
             return nil
diff --git a/Sources/snippet-extract/SnippetBuildCommand.swift b/Sources/snippet-extract/SnippetBuildCommand.swift
diff --git a/Sources/snippet-extract/Utility/SymbolGraph+Snippet.swift b/Sources/snippet-extract/Utility/SymbolGraph+Snippet.swift
diff --git a/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetExtractTests.swift b/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetExtractTests.swift
diff --git a/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetSymbolTests.swift b/Tests/SwiftDocCPluginUtilitiesTests/Snippets/SnippetSymbolTests.swift

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,9 @@ import PackageDescription`
`13`	`13`
`14`	`14`	`let package = Package(`
`15`	`15`	`name: "PackageWithSnippets",`
	`16`	`+ products: [`
	`17`	`+ .library(name: "Library", targets: ["Library"])`
	`18`	`+ ],`
`16`	`19`	`targets: [`
`17`	`20`	`.target(name: "Library"),`
`18`	`21`	`]`
Original file line number	Diff line number	Diff line change
`@@ -110,7 +110,7 @@ extension XCTestCase {`
`110`	`110`	`}`
`111`	`111`	`}`
`112`	`112`
`113`		`- private var swiftExecutableURL: URL {`
	`113`	`+ var swiftExecutableURL: URL {`
`114`	`114`	`get throws {`
`115`	`115`	`let whichProcess = Process.shell("which swift")`
`116`	`116`