Ensure that bundle identifiers are valid URL host components

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)
+    }
+}

Tests/SwiftDocCTests/Infrastructure/DocumentationBundleIdentifierTests.swift

@@ -0,0 +1,59 @@
+/*
+ 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 XCTest
+@testable import SwiftDocC
+
+class DocumentationBundleIdentifierTests: XCTestCase {
+    private typealias Identifier = DocumentationBundle.Identifier
+
+    func testInitialization() {
+        let id = Identifier(rawValue: "com.example.test")
+        XCTAssertEqual(id.rawValue, "com.example.test")
+
+        let idWithSpace = Identifier(rawValue: "Package  Name")
+        XCTAssertEqual(idWithSpace.rawValue, "Package-Name", "The initializer transforms the value to a valid identifier")
+    }
+
+    func testExpressibleByStringLiteral() {
+        let id: Identifier = "com.example.test"
+        XCTAssertEqual(id.rawValue, "com.example.test")
+
+        let idWithSpace: Identifier = "Package  Name"
+        XCTAssertEqual(idWithSpace.rawValue, "Package-Name", "The initializer transforms the value to a valid identifier")
+    }
+
+    func testEquatable() {
+        XCTAssertEqual(Identifier(rawValue: "A"), "A")
+        XCTAssertNotEqual(Identifier(rawValue: "A"), "B")
+    }
+
+    func testComparable() {
+        XCTAssertLessThan(Identifier(rawValue: "B"), "C")
+        XCTAssertGreaterThan(Identifier(rawValue: "B"), "A")
+    }
+
+    func testCustomStringConvertible() {
+        XCTAssertEqual(Identifier(rawValue: "com.example.test").description, "com.example.test")
+        XCTAssertEqual(Identifier(rawValue: "Package  Name").description, "Package-Name")
+
+    }
+
+    func testEncodesAsPlainString() throws {
+        let id = Identifier(rawValue: "com.example.test")
+        let encoded = try String(data: JSONEncoder().encode(id), encoding: .utf8)
+        XCTAssertEqual(encoded, "\"com.example.test\"")
+    }
+
+    func testDecodingFromPlainString() throws {
+        let decoded = try JSONDecoder().decode(Identifier.self, from: Data("\"com.example.test\"".utf8))
+        XCTAssertEqual(decoded, "com.example.test")
+    }
+}