Merge branch 'main' into enable-external-link-support-by-default

Author: d-ronnqvist

Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift

@@ -214,16 +214,12 @@ public class DocumentationContentRenderer {
         guard let symbol = node.semantic as? Symbol,
               let currentPlatforms = documentationContext.configuration.externalMetadata.currentPlatforms,
               !currentPlatforms.isEmpty,
-              let symbolAvailability = symbol.availability?.availability,
+              let symbolAvailability = symbol.availability?.availability.filter({ !$0.isUnconditionallyUnavailable }), // symbol that's unconditionally unavailable in all the platforms can't be in beta.
               !symbolAvailability.isEmpty // A symbol without availability items can't be in beta.
         else { return false }
 
         // Verify that if current platforms are in beta, they match the introduced version of the symbol
         for availability in symbolAvailability {
-            // If not available on this platform, skip to next platform.
-            guard !availability.isUnconditionallyUnavailable else {
-                continue
-            }
 
             // If the symbol doesn't have an introduced version for one of those platforms, we don't consider it "in beta".
             guard let introduced = availability.introducedVersion else {

Sources/SwiftDocC/Utility/FileManagerProtocol+FilesSequence.swift

@@ -16,21 +16,24 @@ extension FileManagerProtocol {
     ///   - startingPoint: The file or directory that's the top of the directory structure that the file manager traverses.
     ///   - options: Options for how the file manager enumerates the contents of directories. Defaults to `.skipsHiddenFiles`.
     /// - Returns: A sequence of the files in the directory structure.
-    package func recursiveFiles(startingPoint: URL, options: FileManager.DirectoryEnumerationOptions = .skipsHiddenFiles) -> some Sequence<URL> {
-        IteratorSequence(FilesIterator(fileManager: self, startingPoint: startingPoint, options: options))
+    package func recursiveFiles(startingPoint: URL, options: FileManager.DirectoryEnumerationOptions = .skipsHiddenFiles) -> IteratorSequence<_FilesIterator> {
+        IteratorSequence(_FilesIterator(fileManager: self, startingPoint: startingPoint, options: options))
     }
 }
 
+// FIXME: This should be private and `FileManagerProtocol.recursiveFiles(startingPoint:options:)` should return `some Sequence<ULR>`
+// but because of https://github.com/swiftlang/swift/issues/77955 it needs to be exposed as an explicit type to avoid a SIL Validation error in the Swift compiler.
+
 /// An iterator that traverses the directory structure and returns the files in breadth-first order.
-private struct FilesIterator<FileManager: FileManagerProtocol>: IteratorProtocol {
+package struct _FilesIterator: IteratorProtocol {
     /// The file manager that the iterator uses to traverse the directory structure.
-    var fileManager: FileManager
-    var options: Foundation.FileManager.DirectoryEnumerationOptions
+    private var fileManager: any FileManagerProtocol // This can't be a generic because of https://github.com/swiftlang/swift/issues/77955
+    private var options: FileManager.DirectoryEnumerationOptions
 
     private var foundFiles: [URL]
     private var foundDirectories: [URL]
 
-    init(fileManager: FileManager, startingPoint: URL, options: Foundation.FileManager.DirectoryEnumerationOptions) {
+    fileprivate init(fileManager: any FileManagerProtocol, startingPoint: URL, options: FileManager.DirectoryEnumerationOptions) {
         self.fileManager = fileManager
         self.options = options
 
@@ -44,7 +47,7 @@ private struct FilesIterator<FileManager: FileManagerProtocol>: IteratorProtocol
         }
     }
 
-    mutating func next() -> URL? {
+    package mutating func next() -> URL? {
         // If the iterator has already found some files, return those first
         if !foundFiles.isEmpty {
             return foundFiles.removeFirst()

Sources/docc/DocCDocumentation.docc/other-formatting-options.md

@@ -14,13 +14,15 @@ configuration. For those situations, use an aside.
 
 DocC supports the following types of asides:
 
-| Type | Usage |
-| ----- | ------ |
-| Note | General information that applies to some users. |
-| Important | Important information, such as a requirement. |
-| Warning | Critical information, like potential data loss or an irrecoverable state. |
-| Tip | Helpful information, such as shortcuts, suggestions, or hints. |
-| Experiment | Instructional information to reinforce a learning objective, or to encourage developers to try out different parts of your framework. |
+> Note: General information that applies to some users.
+
+> Important: Important information, such as a requirement.
+
+> Warning: Critical information, like potential data loss or an irrecoverable state.
+
+> Tip: Helpful information, such as shortcuts, suggestions, or hints.
+
+> Experiment: Instructional information to reinforce a learning objective, or to encourage developers to try out different parts of your framework.
 
 To create an aside, begin a new line with a greater-than symbol (`>`), add a space, 
 the type of the aside, a colon (`:`), and the content of the aside.

Tests/SwiftDocCTests/Benchmark/ExternalTopicsHashTests.swift

@@ -39,7 +39,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
 
     func testNoMetricAddedIfNoExternalTopicsAreResolved() throws {
         // Load bundle without using external resolvers
-        let (_, context) = try testBundleAndContext(named: "TestBundle")
+        let (_, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         XCTAssertTrue(context.externallyResolvedLinks.isEmpty)
 
         // Try adding external topics metrics
@@ -55,7 +55,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
 
         // Add external links and verify the checksum is always the same
         let hashes: [String] = try (0...10).map { _ -> MetricValue? in
-            let (_, _, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
+            let (_, _, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
             try """
             # ``SideKit/SideClass``
 
@@ -93,7 +93,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
 
         // Add external links and verify the checksum is always the same
         let hashes: [String] = try (0...10).map { _ -> MetricValue? in
-            let (_, _, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [externalResolver.bundleID: externalResolver], externalSymbolResolver: externalSymbolResolver) { url in
+            let (_, _, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [externalResolver.bundleID: externalResolver], externalSymbolResolver: externalSymbolResolver) { url in
             try """
             # ``SideKit/SideClass``
 
@@ -131,7 +131,7 @@ class ExternalTopicsGraphHashTests: XCTestCase {
         let externalResolver = self.externalResolver
 
         // Load a bundle with external links
-        let (_, _, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
+        let (_, _, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [externalResolver.bundleID: externalResolver]) { url in
         try """
         # ``SideKit/SideClass``
 

Tests/SwiftDocCTests/Benchmark/TopicGraphHashTests.swift

@@ -14,7 +14,7 @@ import XCTest
 class TopicGraphHashTests: XCTestCase {
     func testTopicGraphSameHash() throws {
         let hashes: [String] = try (0...10).map { _ -> MetricValue? in
-            let (_, context) = try testBundleAndContext(named: "TestBundle")
+            let (_, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
             let testBenchmark = Benchmark()
             benchmark(add: Benchmark.TopicGraphHash(context: context), benchmarkLog: testBenchmark)
             return testBenchmark.metrics[0].result
@@ -32,7 +32,7 @@ class TopicGraphHashTests: XCTestCase {
     func testTopicGraphChangedHash() throws {
         // Verify that the hash changes if we change the topic graph
         let initialHash: String
-        let (_, context) = try testBundleAndContext(named: "TestBundle")
+        let (_, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
 
         do {
             let testBenchmark = Benchmark()
@@ -88,7 +88,7 @@ class TopicGraphHashTests: XCTestCase {
             "/externally/resolved/path/to/article2": .success(.init(referencePath: "/externally/resolved/path/to/article2")),
         ]
 
-        let (_, bundle, context) = try testBundleAndContext(copying: "TestBundle", externalResolvers: [
+        let (_, bundle, context) = try testBundleAndContext(copying: "LegacyBundle_DoNotUseInNewTests", externalResolvers: [
             "com.external.testbundle" : resolver
         ]) { url in
             // Add external links to the MyKit Topics.

Tests/SwiftDocCTests/Checker/Checkers/NonInclusiveLanguageCheckerTests.swift

@@ -11,6 +11,7 @@
 import XCTest
 import Markdown
 @testable import SwiftDocC
+import SwiftDocCTestUtilities
 
 class NonInclusiveLanguageCheckerTests: XCTestCase {
 
@@ -167,9 +168,9 @@ func aBlackListedFunc() {
     }
 
     private let nonInclusiveContent = """
-    # ``SideKit``
+    # Some root page
     
-    SideKit module root symbol. And here is a ~~whitelist~~:
+    Some custom root page. And here is a ~~whitelist~~:
     
      - item one
      - item two
@@ -178,11 +179,12 @@ func aBlackListedFunc() {
 
     func testDisabledByDefault() throws {
         // Create a test bundle with some non-inclusive content.
-        let (_, _, context) = try testBundleAndContext(copying: "TestBundle", diagnosticEngine: .init(filterLevel: .error)) { url in
-            try self.nonInclusiveContent.write(to: url.appendingPathComponent("documentation").appendingPathComponent("sidekit.md"), atomically: true, encoding: .utf8)
-        }
+        let catalog = Folder(name: "unit-test.docc", content: [
+            TextFile(name: "Root.md", utf8Content: nonInclusiveContent)
+        ])
+        let (_, context) = try loadBundle(catalog: catalog)
 
-        XCTAssertEqual(context.problems.count, 0)
+        XCTAssertEqual(context.problems.count, 0) // Non-inclusive content is an info-level diagnostic, so it's filtered out.
     }
 
     func testEnablingTheChecker() throws {
@@ -196,9 +198,12 @@ func aBlackListedFunc() {
         ]
 
         for (severity, enabled) in expectations {
-            let (_, _, context) = try testBundleAndContext(copying: "TestBundle", diagnosticEngine: .init(filterLevel: severity)) { url in
-                try self.nonInclusiveContent.write(to: url.appendingPathComponent("documentation").appendingPathComponent("sidekit.md"), atomically: true, encoding: .utf8)
-            }
+            let catalog = Folder(name: "unit-test.docc", content: [
+                TextFile(name: "Root.md", utf8Content: nonInclusiveContent)
+            ])
+            var configuration = DocumentationContext.Configuration()
+            configuration.externalMetadata.diagnosticLevel = severity
+            let (_, context) = try loadBundle(catalog: catalog, diagnosticEngine: .init(filterLevel: severity), configuration: configuration)
 
             // Verify that checker diagnostics were emitted or not, depending on the diagnostic level set.
             XCTAssertEqual(context.problems.contains(where: { $0.diagnostic.identifier == "org.swift.docc.NonInclusiveLanguage" }), enabled)

Tests/SwiftDocCTests/Converter/DocumentationContextConverterTests.swift

@@ -14,7 +14,7 @@ import XCTest
 
 class DocumentationContextConverterTests: XCTestCase {
     func testRenderNodesAreIdentical() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
 
         // We'll use this to convert nodes ad-hoc
         let perNodeConverter = DocumentationNodeConverter(bundle: bundle, context: context)
@@ -41,7 +41,7 @@ class DocumentationContextConverterTests: XCTestCase {
     }
 
     func testSymbolLocationsAreOnlyIncludedWhenRequested() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let renderContext = RenderContext(documentationContext: context, bundle: bundle)
 
         let fillIntroducedSymbolNode = try XCTUnwrap(
@@ -71,7 +71,7 @@ class DocumentationContextConverterTests: XCTestCase {
     }
 
     func testSymbolAccessLevelsAreOnlyIncludedWhenRequested() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let renderContext = RenderContext(documentationContext: context, bundle: bundle)
 
         let fillIntroducedSymbolNode = try XCTUnwrap(

Tests/SwiftDocCTests/Converter/RenderContextTests.swift

@@ -14,7 +14,7 @@ import XCTest
 
 class RenderContextTests: XCTestCase {
     func testCreatesRenderReferences() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
 
         let renderContext = RenderContext(documentationContext: context, bundle: bundle)
 

Tests/SwiftDocCTests/Converter/TopicRenderReferenceEncoderTests.swift

@@ -158,7 +158,7 @@ class TopicRenderReferenceEncoderTests: XCTestCase {
     /// Verifies that when JSON encoder should sort keys, the custom render reference cache
     /// respects that setting and prints the referencs in alphabetical order.
     func testSortedReferences() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let converter = DocumentationNodeConverter(bundle: bundle, context: context)
 
         // Create a JSON encoder
@@ -218,7 +218,7 @@ class TopicRenderReferenceEncoderTests: XCTestCase {
 
     // Verifies that there is no extra comma at the end of the references list.
     func testRemovesLastReferencesListDelimiter() throws {
-        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let (bundle, context) = try testBundleAndContext(named: "LegacyBundle_DoNotUseInNewTests")
         let converter = DocumentationNodeConverter(bundle: bundle, context: context)
 
         // Create a JSON encoder

Tests/SwiftDocCTests/Diagnostics/DiagnosticConsoleWriterDefaultFormattingTest.swift

@@ -229,7 +229,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         let summary = "Test diagnostic summary"
         let explanation = "Test diagnostic explanation."
         let baseURL =  Bundle.module.url(
-            forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+            forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!
         let source = baseURL.appendingPathComponent("TestTutorial.tutorial")
         let range = SourceLocation(line: 44, column: 59, source: source)..<SourceLocation(line: 44, column: 138, source: source)
 
@@ -307,7 +307,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         let summary = "Test diagnostic summary"
         let explanation = "Test diagnostic explanation."
         let baseURL =  Bundle.module.url(
-            forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
+            forResource: "LegacyBundle_DoNotUseInNewTests", withExtension: "docc", subdirectory: "Test Bundles")!
         let source = baseURL.appendingPathComponent("TestTutorial.tutorial")
         let diagnosticRange = SourceLocation(line: 44, column: 59, source: source)..<SourceLocation(line: 44, column: 138, source: source)
         let diagnostic = Diagnostic(source: source, severity: .warning, range: diagnosticRange, identifier: identifier, summary: summary, explanation: explanation)