Merge branch 'main' into remove-long-disabled-integration-test

# Conflicts:
#	Tests/SwiftDocCUtilitiesTests/PreviewActionIntegrationTests.swift

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticEngine.swift

@@ -27,11 +27,7 @@ public final class DiagnosticEngine {
     /// 
     /// This filter level is inclusive, i.e. if a level of ``DiagnosticSeverity/information`` is specified,
     /// diagnostics with a severity up to and including `.information` will be printed.
-    public var filterLevel: DiagnosticSeverity {
-        didSet {
-            self.filter = { $0.diagnostic.severity.rawValue <= self.filterLevel.rawValue }
-        }
-    }
+    public var filterLevel: DiagnosticSeverity
 
     /// Returns a Boolean value indicating whether the engine contains a consumer that satisfies the given predicate.
     /// - Parameter predicate: A closure that takes one of the engine's consumers as its argument and returns a Boolean value that indicates whether the passed consumer represents a match.
@@ -46,7 +42,9 @@ public final class DiagnosticEngine {
     private let treatWarningsAsErrors: Bool
 
     /// Determines which problems should be emitted.
-    private var filter: (Problem) -> Bool
+    private func shouldEmit(_ problem: Problem) -> Bool {
+        problem.diagnostic.severity.rawValue <= filterLevel.rawValue
+    }
 
     /// A convenience accessor for retrieving all of the diagnostics this engine currently holds.
     public var problems: [Problem] {
@@ -57,7 +55,6 @@ public final class DiagnosticEngine {
     public init(filterLevel: DiagnosticSeverity = .warning, treatWarningsAsErrors: Bool = false) {
         self.filterLevel = filterLevel
         self.treatWarningsAsErrors = treatWarningsAsErrors
-        self.filter = { $0.diagnostic.severity.rawValue <= filterLevel.rawValue }
     }
 
     /// Removes all of the encountered diagnostics from this engine.
@@ -85,7 +82,7 @@ public final class DiagnosticEngine {
             }
             return problem
         }
-        let filteredProblems = mappedProblems.filter(filter)
+        let filteredProblems = mappedProblems.filter(shouldEmit)
         guard !filteredProblems.isEmpty else { return }
 
         if filteredProblems.containsErrors {

Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift

@@ -128,8 +128,8 @@ public struct DocumentationBundle {
         self.themeSettings = themeSettings
         self.rootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: "/", sourceLanguage: .swift)
         self.documentationRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.documentationFolder, sourceLanguage: .swift)
-        self.tutorialsRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)
-        self.technologyTutorialsRootReference = tutorialsRootReference.appendingPath(urlReadablePath(info.displayName))
+        self.tutorialTableOfContentsContainer = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)
+        self.tutorialsContainerReference = tutorialTableOfContentsContainer.appendingPath(urlReadablePath(info.displayName))
         self.articlesDocumentationRootReference = documentationRootReference.appendingPath(urlReadablePath(info.displayName))
     }
 
@@ -154,12 +154,22 @@ public struct DocumentationBundle {
     /// Default path to resolve symbol links.
     public private(set) var documentationRootReference: ResolvedTopicReference
 
-    /// Default path to resolve technology links.
-    public var tutorialsRootReference: ResolvedTopicReference
+    @available(*, deprecated, renamed: "tutorialTableOfContentsContainer", message: "Use 'tutorialTableOfContentsContainer' instead. This deprecated API will be removed after 6.2 is released")
+    public var tutorialsRootReference: ResolvedTopicReference {
+        tutorialTableOfContentsContainer
+    }
+
+    /// Default path to resolve tutorial table-of-contents links.
+    public var tutorialTableOfContentsContainer: ResolvedTopicReference
+
+    @available(*, deprecated, renamed: "tutorialsContainerReference", message: "Use 'tutorialsContainerReference' instead. This deprecated API will be removed after 6.2 is released")
+    public var technologyTutorialsRootReference: ResolvedTopicReference {
+        tutorialsContainerReference
+    }
+
+    /// Default path to resolve tutorial links.
+    public var tutorialsContainerReference: ResolvedTopicReference
 
-    /// Default path to resolve tutorials.
-    public var technologyTutorialsRootReference: ResolvedTopicReference
-    
     /// Default path to resolve articles.
     public var articlesDocumentationRootReference: ResolvedTopicReference
 }

Sources/SwiftDocC/Infrastructure/DocumentationContext+Breadcrumbs.swift

@@ -13,8 +13,8 @@ extension DocumentationContext {
     struct PathOptions: OptionSet {
         let rawValue: Int
 
-        /// Prefer a technology as the canonical path over a shorter path.
-        static let preferTechnologyRoot = PathOptions(rawValue: 1 << 0)
+        /// Prefer a tutorial table-of-contents page as the canonical path over a shorter path.
+        static let preferTutorialTableOfContentsRoot = PathOptions(rawValue: 1 << 0)
     }
 
     /// Finds all finite (acyclic) paths, also called "breadcrumbs", to the given reference in the topic graph.
@@ -38,9 +38,9 @@ extension DocumentationContext {
             // To match the caller's expectations we remove the starting point and then flip the paths.
             .map { $0.dropFirst().reversed() }
             .sorted { (lhs, rhs) -> Bool in
-                // Order a path rooted in a technology as the canonical one.
-                if options.contains(.preferTechnologyRoot), let first = lhs.first {
-                    return try! entity(with: first).semantic is Technology
+                // Order a path rooted in a tutorial table-of-contents as the canonical one.
+                if options.contains(.preferTutorialTableOfContentsRoot), let first = lhs.first {
+                    return try! entity(with: first).semantic is TutorialTableOfContents
                 }
 
                 return breadcrumbsAreInIncreasingOrder(lhs, rhs)

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -136,10 +136,15 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// The set of all manually curated references if `shouldStoreManuallyCuratedReferences` was true at the time of processing and has remained `true` since.. Nil if curation has not been processed yet.
     public private(set) var manuallyCuratedReferences: Set<ResolvedTopicReference>?
 
-    /// The root technology nodes of the Topic Graph.
+    @available(*, deprecated, renamed: "tutorialTableOfContentsReferences", message: "Use 'tutorialTableOfContentsReferences' This deprecated API will be removed after 6.2 is released")
     public var rootTechnologies: [ResolvedTopicReference] {
+        tutorialTableOfContentsReferences
+    }
+
+    /// The tutorial table-of-contents nodes in the topic graph.
+    public var tutorialTableOfContentsReferences: [ResolvedTopicReference] {
         return topicGraph.nodes.values.compactMap { node in
-            guard node.kind == .technology && parents(of: node.reference).isEmpty else {
+            guard node.kind == .tutorialTableOfContents && parents(of: node.reference).isEmpty else {
                 return nil
             }
             return node.reference
@@ -606,65 +611,65 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// up in the context, not from the arrays that was passed as arguments.
     ///
     /// - Parameters:
-    ///   - technologies: The list of temporary 'technology' pages.
+    ///   - tutorialTableOfContentsResults: The list of temporary 'tutorial table-of-contents' pages.
     ///   - tutorials: The list of temporary 'tutorial' pages.
     ///   - tutorialArticles: The list of temporary 'tutorialArticle' pages.
     ///   - bundle: The bundle to resolve links against.
-    private func resolveLinks(technologies: [SemanticResult<Technology>],
-                              tutorials: [SemanticResult<Tutorial>],
-                              tutorialArticles: [SemanticResult<TutorialArticle>],
-                              bundle: DocumentationBundle) {
-        
+    private func resolveLinks(
+        tutorialTableOfContents tutorialTableOfContentsResults: [SemanticResult<TutorialTableOfContents>],
+        tutorials: [SemanticResult<Tutorial>],
+        tutorialArticles: [SemanticResult<TutorialArticle>],
+        bundle: DocumentationBundle
+    ) {
         let sourceLanguages = soleRootModuleReference.map { self.sourceLanguages(for: $0) } ?? [.swift]
 
-        // Technologies
-        
-        for technologyResult in technologies {
+        // Tutorial table-of-contents
+
+        for tableOfContentsResult in tutorialTableOfContentsResults {
             autoreleasepool {
-                let url = technologyResult.source
-                let unresolvedTechnology = technologyResult.value
+                let url = tableOfContentsResult.source
                 var resolver = ReferenceResolver(context: self, bundle: bundle)
-                let technology = resolver.visit(unresolvedTechnology) as! Technology
+                let tableOfContents = resolver.visit(tableOfContentsResult.value) as! TutorialTableOfContents
                 diagnosticEngine.emit(resolver.problems)
 
                 // Add to document map
-                documentLocationMap[url] = technologyResult.topicGraphNode.reference
-                
-                let technologyReference = technologyResult.topicGraphNode.reference.withSourceLanguages(sourceLanguages)
+                documentLocationMap[url] = tableOfContentsResult.topicGraphNode.reference
 
-                let technologyNode = DocumentationNode(
-                    reference: technologyReference,
-                    kind: .technology,
+                let tableOfContentsReference = tableOfContentsResult.topicGraphNode.reference.withSourceLanguages(sourceLanguages)
+
+                let tutorialTableOfContentsNode = DocumentationNode(
+                    reference: tableOfContentsReference,
+                    kind: .tutorialTableOfContents,
                     sourceLanguage: Self.defaultLanguage(in: sourceLanguages),
                     availableSourceLanguages: sourceLanguages,
-                    name: .conceptual(title: technology.intro.title),
-                    markup: technology.originalMarkup,
-                    semantic: technology
+                    name: .conceptual(title: tableOfContents.intro.title),
+                    markup: tableOfContents.originalMarkup,
+                    semantic: tableOfContents
                 )
-                documentationCache[technologyReference] = technologyNode
+                documentationCache[tableOfContentsReference] = tutorialTableOfContentsNode
 
-                // Update the reference in the topic graph with the technology's available languages.
+                // Update the reference in the topic graph with the table-of-contents page's available languages.
                 topicGraph.updateReference(
-                    technologyResult.topicGraphNode.reference,
-                    newReference: technologyReference
+                    tableOfContentsResult.topicGraphNode.reference,
+                    newReference: tableOfContentsReference
                 )
 
                 let anonymousVolumeName = "$volume"
 
-                for volume in technology.volumes {
+                for volume in tableOfContents.volumes {
                     // Graph node: Volume
-                    let volumeReference = technologyNode.reference.appendingPath(volume.name ?? anonymousVolumeName)
+                    let volumeReference = tutorialTableOfContentsNode.reference.appendingPath(volume.name ?? anonymousVolumeName)
                     let volumeNode = TopicGraph.Node(reference: volumeReference, kind: .volume, source: .file(url: url), title: volume.name ?? anonymousVolumeName)
                     topicGraph.addNode(volumeNode)
 
-                    // Graph edge: Technology -> Volume
-                    topicGraph.addEdge(from: technologyResult.topicGraphNode, to: volumeNode)
+                    // Graph edge: Tutorial table-of-contents -> Volume
+                    topicGraph.addEdge(from: tableOfContentsResult.topicGraphNode, to: volumeNode)
 
                     for chapter in volume.chapters {
                         // Graph node: Module
                         let baseNodeReference: ResolvedTopicReference
                         if volume.name == nil {
-                            baseNodeReference = technologyNode.reference
+                            baseNodeReference = tutorialTableOfContentsNode.reference
                         } else {
                             baseNodeReference = volumeNode.reference
                         }
@@ -761,15 +766,15 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     }
 
     private func registerDocuments(from bundle: DocumentationBundle) throws -> (
-        technologies: [SemanticResult<Technology>],
+        tutorialTableOfContentsResults: [SemanticResult<TutorialTableOfContents>],
         tutorials: [SemanticResult<Tutorial>],
         tutorialArticles: [SemanticResult<TutorialArticle>],
         articles: [SemanticResult<Article>],
         documentationExtensions: [SemanticResult<Article>]
     ) {
         // First, try to understand the basic structure of the document by
         // analyzing it and putting references in as "unresolved".
-        var technologies = [SemanticResult<Technology>]()
+        var tutorialTableOfContentsResults = [SemanticResult<TutorialTableOfContents>]()
         var tutorials = [SemanticResult<Tutorial>]()
         var tutorialArticles = [SemanticResult<TutorialArticle>]()
         var articles = [SemanticResult<Article>]()
@@ -857,11 +862,11 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
              Add all topic graph nodes up front before resolution starts, because
              there may be circular linking.
              */
-            if let technology = analyzed as? Technology {
-                let topicGraphNode = TopicGraph.Node(reference: reference, kind: .technology, source: .file(url: url), title: technology.intro.title)
+            if let tableOfContents = analyzed as? TutorialTableOfContents {
+                let topicGraphNode = TopicGraph.Node(reference: reference, kind: .tutorialTableOfContents, source: .file(url: url), title: tableOfContents.intro.title)
                 topicGraph.addNode(topicGraphNode)
-                let result = SemanticResult(value: technology, source: url, topicGraphNode: topicGraphNode)
-                technologies.append(result)
+                let result = SemanticResult(value: tableOfContents, source: url, topicGraphNode: topicGraphNode)
+                tutorialTableOfContentsResults.append(result)
             } else if let tutorial = analyzed as? Tutorial {
                 let topicGraphNode = TopicGraph.Node(reference: reference, kind: .tutorial, source: .file(url: url), title: tutorial.title ?? "")
                 topicGraph.addNode(topicGraphNode)
@@ -920,7 +925,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             }
         }
 
-        return (technologies, tutorials, tutorialArticles, articles, documentationExtensions)
+        return (tutorialTableOfContentsResults, tutorials, tutorialArticles, articles, documentationExtensions)
     }
 
     private func insertLandmarks(_ landmarks: some Sequence<Landmark>, from topicGraphNode: TopicGraph.Node, source url: URL) {
@@ -1331,6 +1336,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     }
 
     private func shouldContinueRegistration() throws {
+        try Task.checkCancellation()
         guard isRegistrationEnabled.sync({ $0 }) else {
             throw ContextError.registrationDisabled
         }
@@ -1773,6 +1779,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     ///
     /// When given `false` the context will try to cancel as quick as possible
     /// any ongoing bundle registrations.
+    @available(*, deprecated, message: "This deprecated API will be removed after 6.2 is released")
     public func setRegistrationEnabled(_ value: Bool) {
         isRegistrationEnabled.sync({ $0 = value })
     }
@@ -2098,7 +2105,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         //       symbols or attempt to resolve links/references since the topic graph may not contain all documents
         //       or all symbols yet.
         var result: (
-            technologies: [SemanticResult<Technology>],
+            tutorialTableOfContentsResults: [SemanticResult<TutorialTableOfContents>],
             tutorials: [SemanticResult<Tutorial>],
             tutorialArticles: [SemanticResult<TutorialArticle>],
             articles: [SemanticResult<Article>],
@@ -2137,7 +2144,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         }
 
         // All discovery went well, process the inputs.
-        let (technologies, tutorials, tutorialArticles, allArticles, documentationExtensions) = result
+        let (tutorialTableOfContentsResults, tutorials, tutorialArticles, allArticles, documentationExtensions) = result
         var (otherArticles, rootPageArticles) = splitArticles(allArticles)
 
         let globalOptions = (allArticles + documentationExtensions).compactMap { article in
@@ -2185,8 +2192,8 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         for article in tutorialArticles {
             hierarchyBasedResolver.addTutorialArticle(article)
         }
-        for technology in technologies {
-            hierarchyBasedResolver.addTechnology(technology)
+        for tutorialTableOfContents in tutorialTableOfContentsResults {
+            hierarchyBasedResolver.addTutorialTableOfContents(tutorialTableOfContents)
         }
 
         registerRootPages(from: rootPageArticles, in: bundle)
@@ -2221,13 +2228,13 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
         // Third, any processing that relies on resolving other content is done, mainly resolving links.
         preResolveExternalLinks(semanticObjects:
-            technologies.map(referencedSemanticObject) +
+            tutorialTableOfContentsResults.map(referencedSemanticObject) +
             tutorials.map(referencedSemanticObject) +
             tutorialArticles.map(referencedSemanticObject),
             localBundleID: bundle.identifier)
 
         resolveLinks(
-            technologies: technologies,
+            tutorialTableOfContents: tutorialTableOfContentsResults,
             tutorials: tutorials,
             tutorialArticles: tutorialArticles,
             bundle: bundle
@@ -2913,8 +2920,8 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 extension DocumentationContext {
 
     /// The nodes that are allowed to be roots in the topic graph.
-    static var allowedRootNodeKinds: [DocumentationNode.Kind] = [.technology, .module]
-    
+    static var allowedRootNodeKinds: [DocumentationNode.Kind] = [.tutorialTableOfContents, .module]
+
     func analyzeTopicGraph() {
         // Find all nodes that are loose in the graph and have no parent but aren't supposed to
         let unexpectedRoots = topicGraph.nodes.values.filter { node in