Ensure that bundle identifiers are valid URL host components (#1069)

* Add bundle identifier type that ensures a valid URL host component

rdar://135335645

* Use new Identifier type in `DocumentationBundle/Info`

* Update code to not use deprecated `Info/identifier` property

* Use new Identifier type in `DocumentationBundle`

* Update code to not use deprecated `identifier` property

* Use new Identifier type in `[Unresolved|Resolved]TopicReference`

* Update code to not use deprecated topic reference `bundleIdentifier` property

* Deprecate `BundleIdentifier` in favor of `DocumentationBundle/Identifier`

* Use new Identifier type in `BuildMetadata`

* Use new Identifier type in `AssetReference`

* Use new Identifier type in `ResourceReference`

* Use new Identifier type in `ConvertServiceFallbackResolver`

* Use new Identifier type in `SerializableLinkResolutionInformation`

* Use new Identifier type in `ConvertAction/Indexer`

* Prefer `bundleID` over `id` for types that scoped inside bundle

* Use `bundleID` instead of `id` for property names outside the bundle

* Use "bundle id" in local variable in fallback resolver

Author: d-ronnqvist

Sources/SwiftDocC/DocumentationService/Convert/ConvertService.swift

@@ -128,7 +128,7 @@ public struct ConvertService: DocumentationService {
 
             if let linkResolvingServer {
                 let resolver = try OutOfProcessReferenceResolver(
-                    bundleIdentifier: request.bundleInfo.identifier,
+                    bundleID: request.bundleInfo.id,
                     server: linkResolvingServer,
                     convertRequestIdentifier: messageIdentifier
                 )
@@ -267,7 +267,7 @@ public struct ConvertService: DocumentationService {
             .compactMap { (value, isDocumentationExtensionContent) -> (ResolvedTopicReference, RenderReferenceStore.TopicContent)? in
                 let (topicReference, article) = value
 
-                guard let bundle = context.bundle, bundle.identifier == topicReference.bundleIdentifier else { return nil }
+                guard let bundle = context.bundle, bundle.id == topicReference.bundleID else { return nil }
                 let renderer = DocumentationContentRenderer(documentationContext: context, bundle: bundle)
 
                 let documentationNodeKind: DocumentationNode.Kind = isDocumentationExtensionContent ? .unknownSymbol : .article

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

@@ -26,7 +26,7 @@ protocol ConvertServiceFallbackResolver {
     /// The bundle identifier for the fallback resolver.
     ///
     /// The fallback resolver will only resolve links with this bundle identifier.
-    var bundleIdentifier: String { get }
+    var bundleID: DocumentationBundle.Identifier { get }
 
     // MARK: References
 

Sources/SwiftDocC/Indexing/Navigator/NavigatorIndex.swift

@@ -438,7 +438,7 @@ extension ResolvedTopicReference {
         let normalizedPath = NodeURLGenerator.fileSafeReferencePath(self, lowercased: true)
 
         return NavigatorIndex.Identifier(
-            bundleIdentifier: bundleIdentifier.lowercased(),
+            bundleIdentifier: bundleID.rawValue.lowercased(),
             path: "/" + normalizedPath,
             fragment: fragment,
             languageIdentifier: languageIdentifier

Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift

@@ -346,12 +346,24 @@ fileprivate extension NSRegularExpression {
 public struct AssetReference: Hashable, Codable {
     /// The name of the asset.
     public var assetName: String
+    @available(*, deprecated, renamed: "bundleID", message: "Use 'bundleID' instead. This deprecated API will be removed after 6.2 is released")
+    public var bundleIdentifier: String {
+        bundleID.rawValue
+    }
+    
     /// The identifier of the bundle the asset is apart of.
-    public var bundleIdentifier: String
+    public let bundleID: DocumentationBundle.Identifier
 
     /// Creates a reference from a given asset name and the bundle it is apart of.
-    public init(assetName: String, bundleIdentifier: String) {
+    public init(assetName: String, bundleID: DocumentationBundle.Identifier) {
         self.assetName = assetName
-        self.bundleIdentifier = bundleIdentifier
+        self.bundleID = bundleID
+    }
+    @available(*, deprecated, renamed: "init(assetName:bundleID:)", message: "Use 'init(assetName:bundleID:)' instead. This deprecated API will be removed after 6.2 is released")
+    public init(assetName: String, bundleIdentifier: String) {
+        self.init(
+            assetName: assetName,
+            bundleID: .init(rawValue: bundleIdentifier)
+        )
     }
 }

Sources/SwiftDocC/Infrastructure/Context/Deprecated/DocumentationContext+Deprecated.swift

@@ -18,8 +18,19 @@ extension DocumentationContext {
 
     @available(*, deprecated, renamed: "configuration.externalDocumentationConfiguration.sources", message: "Use 'configuration.externalDocumentationConfiguration.sources' instead. This deprecated API will be removed after Swift 6.2 is released.")
     public var externalDocumentationSources: [BundleIdentifier: ExternalDocumentationSource] {
-        get { configuration.externalDocumentationConfiguration.sources }
-        set { configuration.externalDocumentationConfiguration.sources = newValue }
+        get {
+            var result = [BundleIdentifier: ExternalDocumentationSource]()
+            for (key, value) in configuration.externalDocumentationConfiguration.sources {
+                result[key.rawValue] = value
+            }
+            return result
+        }
+        set {
+            configuration.externalDocumentationConfiguration.sources.removeAll()
+            for (key, value) in newValue {
+                configuration.externalDocumentationConfiguration.sources[.init(rawValue: key)] = value
+            }
+        }
     }
 
     @available(*, deprecated, renamed: "configuration.externalDocumentationConfiguration.globalSymbolResolver", message: "Use 'configuration.externalDocumentationConfiguration.globalSymbolResolver' instead. This deprecated API will be removed after Swift 6.2 is released.")

Sources/SwiftDocC/Infrastructure/Context/DocumentationContext+Configuration.swift

@@ -76,7 +76,7 @@ extension DocumentationContext {
         /// A collection of configuration related to external sources of documentation.
         public struct ExternalDocumentationConfiguration {
             /// The lookup of external documentation sources by their bundle identifiers.
-            public var sources: [BundleIdentifier: ExternalDocumentationSource] = [:]
+            public var sources: [DocumentationBundle.Identifier: ExternalDocumentationSource] = [:]
             /// A type that resolves all symbols that are referenced in symbol graph files but can't be found in any of the locally available symbol graph files.
             public var globalSymbolResolver: GlobalExternalSymbolResolver?
             /// A list of URLs to documentation archives that the local documentation depends on.

Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift

@@ -161,7 +161,7 @@ package enum ConvertActionConverter {
 
         if FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled {
             do {
-                let serializableLinkInformation = try context.linkResolver.localResolver.prepareForSerialization(bundleID: bundle.identifier)
+                let serializableLinkInformation = try context.linkResolver.localResolver.prepareForSerialization(bundleID: bundle.id)
                 try outputConsumer.consume(linkResolutionInformation: serializableLinkInformation)
 
                 if !emitDigest {
@@ -191,7 +191,7 @@ package enum ConvertActionConverter {
             break
         }
 
-        try outputConsumer.consume(buildMetadata: BuildMetadata(bundleDisplayName: bundle.displayName, bundleIdentifier: bundle.identifier))
+        try outputConsumer.consume(buildMetadata: BuildMetadata(bundleDisplayName: bundle.displayName, bundleID: bundle.id))
 
         // Log the finalized topic graph checksum.
         benchmark(add: Benchmark.TopicGraphHash(context: context))

Sources/SwiftDocC/Infrastructure/DocumentationBundle+Identifier.swift

@@ -0,0 +1,67 @@
+/*
+ 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
+
+extension DocumentationBundle {
+    /// A stable and locally unique identifier for a collection of documentation inputs.
+    public struct Identifier: RawRepresentable {
+        public let rawValue: String
+        
+        public init(rawValue: String) {
+            // To ensure that the identifier can be used as a valid "host" component of a resolved topic reference's url,
+            // replace any consecutive sequence of unsupported characters with a "-".
+            self.rawValue = rawValue
+                .components(separatedBy: Self.charactersToReplace)
+                .filter { !$0.isEmpty }
+                .joined(separator: "-")
+        }
+        
+        private static let charactersToReplace = CharacterSet.urlHostAllowed.inverted
+    }
+}
+
+extension DocumentationBundle.Identifier: Hashable {}
+extension DocumentationBundle.Identifier: Sendable {}
+
+// Support creating an identifier from a string literal.
+extension DocumentationBundle.Identifier: ExpressibleByStringLiteral {
+    public init(stringLiteral value: StringLiteralType) {
+        self.init(rawValue: value)
+    }
+}
+
+// Sort identifiers based on their raw string value.
+extension DocumentationBundle.Identifier: Comparable {
+    public static func < (lhs: Self, rhs: Self) -> Bool {
+        lhs.rawValue < rhs.rawValue
+    }
+}
+
+// Print as a single string value
+extension DocumentationBundle.Identifier: CustomStringConvertible {
+    public var description: String {
+        rawValue
+    }
+}
+
+// Encode and decode the identifier as a single string value.
+extension DocumentationBundle.Identifier: Codable {
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        let rawValue = try container.decode(String.self)
+        self.init(rawValue: rawValue)
+    }
+    
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        try container.encode(rawValue)
+    }
+}

Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift

@@ -57,11 +57,14 @@ public struct DocumentationBundle {
         info.displayName
     }
 
-    /// A identifier for this unit of documentation
-    ///
-    /// The string is typically in reverse DNS format using only the Roman alphabet in upper and lower case (A–Z, a–z), the dot (“.”), and the hyphen (“-”).
+    @available(*, deprecated, renamed: "id", message: "Use 'id' instead. This deprecated API will be removed after 6.2 is released")
     public var identifier: String {
-        info.identifier
+        id.rawValue
+    }
+    
+    /// The documentation bundle's stable and locally unique identifier.
+    public var id: DocumentationBundle.Identifier {
+        info.id
     }
 
     /**
@@ -107,7 +110,6 @@ public struct DocumentationBundle {
 
     /// A custom JSON settings file used to theme renderer output.
     public let themeSettings: URL?
-    
     /// A URL prefix to be appended to the relative presentation URL.
     ///
     /// This is used when a built documentation is hosted in a known location.
@@ -142,9 +144,9 @@ public struct DocumentationBundle {
         self.customHeader = customHeader
         self.customFooter = customFooter
         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.tutorialTableOfContentsContainer = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)
+        self.rootReference = ResolvedTopicReference(bundleID: info.id, path: "/", sourceLanguage: .swift)
+        self.documentationRootReference = ResolvedTopicReference(bundleID: info.id, path: NodeURLGenerator.Path.documentationFolder, sourceLanguage: .swift)
+        self.tutorialTableOfContentsContainer = ResolvedTopicReference(bundleID: info.id, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)
         self.tutorialsContainerReference = tutorialTableOfContentsContainer.appendingPath(urlReadablePath(info.displayName))
         self.articlesDocumentationRootReference = documentationRootReference.appendingPath(urlReadablePath(info.displayName))
     }