Treat external content as pre-rendered

Sources/SwiftDocC/Benchmark/Metrics/ExternalTopicsHash.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -11,19 +11,18 @@
 import Foundation
 
 extension Benchmark {
-    /// A hash metric produced off the externally resolved links and symbols.
+    /// A hash metric produced off the externally resolved links.
     ///
-    /// Use this metric to verify that your code changes
-    /// did not affect external resolving.
+    /// Use this metric to verify that your code changes did not affect external link resolution.
     public class ExternalTopicsHash: BenchmarkMetric {
         public static let identifier = "external-topics-hash"
         public static let displayName = "External Topics Checksum"
 
-        /// Creates a new metric and stores the checksum of the given documentation context external topics.
-        /// - Parameter context: A documentation context.
+        /// Creates a new metric that stores the checksum of the successfully externally resolved links.
+        /// - Parameter context: A documentation context that the external links were resolved in.
         public init(context: DocumentationContext) {
             // If there are no externally resolved topics return quickly.
-            guard !context.externallyResolvedLinks.isEmpty || !context.externallyResolvedSymbols.isEmpty else {
+            guard !context.externallyResolvedLinks.isEmpty else {
                 return
             }
 
@@ -37,7 +36,6 @@ extension Benchmark {
                     return nil
                 }
             }).sorted().joined()
-                + context.externallyResolvedSymbols.map({ $0.absoluteString }).sorted().joined()
 
             result = .checksum(Checksum.md5(of: Data(sourceString.utf8)))
         }

Sources/SwiftDocC/DocumentationService/Convert/ConvertService.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -155,7 +155,6 @@ public struct ConvertService: DocumentationService {
 
             // Enable support for generating documentation for standalone articles and tutorials.
             context.allowsRegisteringArticlesWithoutTechnologyRoot = true
-            context.allowsRegisteringUncuratedTutorials = true
             context.considerDocumentationExtensionsThatDoNotMatchSymbolsAsResolved = true
 
             context.configureSymbolGraph = { symbolGraph in
@@ -173,9 +172,8 @@ public struct ConvertService: DocumentationService {
                     convertRequestIdentifier: messageIdentifier
                 )
 
-                context.fallbackReferenceResolvers[request.bundleInfo.identifier] = resolver
-                context.fallbackAssetResolvers[request.bundleInfo.identifier] = resolver
-                context.externalSymbolResolver = resolver
+                context.convertServiceFallbackResolver = resolver
+                context.globalExternalSymbolResolver = resolver
             }
 
             var converter = try self.converter ?? DocumentationConverter(

Sources/SwiftDocC/DocumentationService/Convert/Fallback Link Resolution/ConvertServiceFallbackResolver.swift

@@ -0,0 +1,44 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 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
+
+/// A resolver that attempts to resolve local references that wasn't included in the catalog or symbol input.
+///
+/// The ``ConvertService`` builds documentation for a single page at a time. If this page's content contains references to other local symbols, pages, or
+/// assets that aren't included in the original ``ConvertRequest``, this fallback resolver resolves those references.
+///
+/// The ``ConvertService`` only renders the one page that it provided inputs for. Because of this, the content that this fallback resolver returns is considered
+/// "external" content, even if it represents pages that would be "local" if the full project was built together.
+protocol ConvertServiceFallbackResolver {
+
+    // MARK: References
+
+    /// Attempts to resolve an unresolved reference for a page that couldn't be resolved locally.
+    ///
+    /// - Parameter reference: The unresolved local reference.
+    /// - Returns: The resolved reference, or information about why the resolver failed to resolve the reference.
+    func resolve(_ reference: TopicReference) -> TopicReferenceResolutionResult
+
+    /// Returns a  Creates a new documentation node with the documentation content for the external reference, if the given reference was
+    /// resolved by this resolver.
+    ///
+    /// - Parameter reference: The local reference that this resolver may have previously resolved.
+    /// - Returns: A node with the documentation content for the referenced topic, or `nil` if the reference wasn't previously resolved by this resolver.
+    func entityIfPreviouslyResolved(with reference: ResolvedTopicReference) -> LinkResolver.ExternalEntity?
+
+    // MARK:  Assets
+
+    /// Attempts to resolve an asset that couldn't be resolved locally.
+    ///
+    /// - Parameter assetName: The name of the local asset to resolve.
+    /// - Returns: The local asset with the given name if found; otherwise `nil`.
+    func resolve(assetNamed assetName: String) -> DataAsset?
+}

Sources/SwiftDocC/Infrastructure/ContentCache.swift

@@ -0,0 +1,93 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 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
+*/
+
+extension DocumentationContext {
+    /// A cache for symbol and page content.
+    struct ContentCache<Value> {
+        private var storage = [ResolvedTopicReference: Value]()
+        private var symbolIndex = [String: ResolvedTopicReference]()
+
+        /// Accesses the value for a given reference.
+        /// - Parameter reference: The reference to find in the cache.
+        subscript(reference: ResolvedTopicReference) -> Value? {
+            // Avoid copying the values if possible
+            _read { yield storage[reference] }
+            _modify { yield &storage[reference] }
+        }
+
+        /// Adds a value to the cache for a given reference _and_ symbol ID.
+        /// - Parameters:
+        ///   - value: The value to add to the cache.
+        ///   - reference: The reference associated with that value.
+        ///   - symbolID: The symbol ID associated with that value.
+        mutating func add(value: Value, reference: ResolvedTopicReference, symbolID: String) {
+            symbolIndex[symbolID] = reference
+            storage[reference] = value
+        }
+
+        /// Accesses the reference for a given symbol ID.
+        /// - Parameter symbolID: The symbol ID to find in the cache.
+        func reference(symbolID: String) -> ResolvedTopicReference? {
+            symbolIndex[symbolID]
+        }
+
+        /// Accesses the value for a given symbol ID.
+        /// - Parameter symbolID: The symbol ID to find in the cache.
+        subscript(symbolID: String) -> Value? {
+            // Avoid copying the values if possible
+            _read { yield symbolIndex[symbolID].map { storage[$0]! } }
+        }
+
+        /// Reserves enough space to store the specified number of values.
+        mutating func reserveCapacity(_ minimumCapacity: Int, reserveSymbolIDCapacity: Bool) {
+            storage.reserveCapacity(minimumCapacity)
+            if reserveSymbolIDCapacity {
+                symbolIndex.reserveCapacity(minimumCapacity)
+            }
+        }
+
+        /// Returns a list of all the references in the cache.
+        var references: [ResolvedTopicReference] {
+            return Array(storage.keys)
+        }
+
+        /// Returns a list of all the references in the cache.
+        var symbolReferences: [ResolvedTopicReference] {
+            return Array(symbolIndex.values)
+        }
+    }
+}
+
+// Support iterating over the cached values.
+extension DocumentationContext.ContentCache: Collection {
+    typealias Wrapped = [ResolvedTopicReference: Value]
+    typealias Index = Wrapped.Index
+    typealias Element = Wrapped.Element
+
+    func makeIterator() -> Wrapped.Iterator {
+        storage.makeIterator()
+    }
+
+    var startIndex: Wrapped.Index {
+        storage.startIndex
+    }
+
+    var endIndex: Wrapped.Index {
+        storage.endIndex
+    }
+
+    func index(after i: Wrapped.Index) -> Wrapped.Index {
+        storage.index(after: i)
+    }
+
+    subscript(position: Wrapped.Index) -> Wrapped.Element {
+        _read { yield storage[position] }
+    }
+}

Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -371,7 +371,7 @@ extension CoverageDataEntry {
                 )
                 let total = children.count
                 let documented = children.filter {
-                    (context.nodeWithSymbolIdentifier($0.reference.description)?.semantic as? Symbol)?.abstractSection != nil
+                    (context.documentationCache[$0.reference.description]?.semantic as? Symbol)?.abstractSection != nil
                 }.count
 
                 if total == 0 {