Fix error when writing multiple index.html files to the same location

Addresses a regression where `docc convert` would throw an error
when writing multiple `index.html` files to the same location on disk.

This can occur if docc is writing to an output directory that already contains
built documentation or because when docc is given bad input such that multiple
documentation pages have the same path on the filesystem.

Resolves rdar://94311195

Author: ethan-kusters

Sources/SwiftDocCUtilities/Action/Actions/Convert/JSONEncodingRenderNodeWriter.swift

@@ -116,6 +116,16 @@ class JSONEncodingRenderNodeWriter {
             attributes: nil
         )
 
-        try fileManager.copyItem(at: indexHTML, to: htmlTargetFileURL)
+        do {
+            try fileManager.copyItem(at: indexHTML, to: htmlTargetFileURL)
+        } catch let error as NSError where error.code == NSFileWriteFileExistsError {
+            // We already have an 'index.html' file at this path. This could be because
+            // we're writing to an output directory that already contains built documentation
+            // or because we we're given bad input such that multiple documentation pages
+            // have the same path on the filesystem. Either way, we don't want this to error out
+            // so just remove the destination item and try the copy operation again.
+            try fileManager.removeItem(at: htmlTargetFileURL)
+            try fileManager.copyItem(at: indexHTML, to: htmlTargetFileURL)
+        }
     }
 }

Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift

@@ -12,6 +12,7 @@ import XCTest
 import Foundation
 @testable import SwiftDocC
 @testable import SwiftDocCUtilities
+import SymbolKit
 import Markdown
 import SwiftDocCTestUtilities
 
@@ -2361,7 +2362,75 @@ class ConvertActionTests: XCTestCase {
         var action = try ConvertAction(fromConvertCommand: convertCommand)
         _ = try action.perform(logHandle: .none)
     }
+    
+    func emitEmptySymbolGraph(moduleName: String, destination: URL) throws {
+        let symbolGraph = SymbolGraph(
+            metadata: .init(
+                formatVersion: .init(major: 0, minor: 0, patch: 1),
+                generator: "unit-test"
+            ),
+            module: .init(
+                name: moduleName,
+                platform: .init()
+            ),
+            symbols: [],
+            relationships: []
+        )
+        
+        // Create a unique subfolder to place the symbol graph in
+        // in case we're emitting multiple symbol graphs with the same filename.
+        let uniqueSubfolder = destination.appendingPathComponent(
+            ProcessInfo.processInfo.globallyUniqueString
+        )
+        try FileManager.default.createDirectory(
+            at: uniqueSubfolder,
+            withIntermediateDirectories: false
+        )
+        
+        try JSONEncoder().encode(symbolGraph).write(
+            to: uniqueSubfolder
+                .appendingPathComponent(moduleName, isDirectory: false)
+                .appendingPathExtension("symbols.json")
+        )
+    }
 
+    // Tests that when `docc convert` is given input that produces multiple pages at the same path
+    // on disk it does not throw an error when attempting to transform it for static hosting. (94311195)
+    func testConvertDocCCatalogThatProducesMultipleDocumentationPagesAtTheSamePathDoesNotThrowError() throws {
+        let temporaryDirectory = try createTemporaryDirectory()
+        
+        let catalogURL = try Folder(
+            name: "unit-test.docc",
+            content: [
+                InfoPlist(displayName: "TestBundle", identifier: "com.test.example"),
+            ]
+        ).write(inside: temporaryDirectory)
+        try emitEmptySymbolGraph(moduleName: "docc", destination: catalogURL)
+        try emitEmptySymbolGraph(moduleName: "DocC", destination: catalogURL)
+        
+        let htmlTemplateDirectory = try Folder.emptyHTMLTemplateDirectory.write(
+            inside: temporaryDirectory
+        )
+        
+        let targetDirectory = temporaryDirectory.appendingPathComponent("target.doccarchive", isDirectory: true)
+        let dataProvider = try LocalFileSystemDataProvider(rootURL: catalogURL)
+        
+        var action = try ConvertAction(
+            documentationBundleURL: catalogURL,
+            outOfProcessResolver: nil,
+            analyze: false,
+            targetDirectory: targetDirectory,
+            htmlTemplateDirectory: htmlTemplateDirectory,
+            emitDigest: false,
+            currentPlatforms: nil,
+            dataProvider: dataProvider,
+            fileManager: FileManager.default,
+            temporaryDirectory: createTemporaryDirectory(),
+            transformForStaticHosting: true
+        )
+        
+        XCTAssertNoThrow(try action.performAndHandleResult())
+    }
     func testConvertWithCustomTemplates() throws {
         let info = InfoPlist(displayName: "TestConvertWithCustomTemplates", identifier: "com.test.example")
         let index = TextFile(name: "index.html", utf8Content: """