Deterministic behaviour when a catalog has colliding filename (#286)

Whenever there are two or more files with same name for a type in a catalog only one is picked up randomly and rest gets Diagnostics information that its content is being dropped. The change addresses the issue by adding a sort to the url of the document, so that the behavior is deterministic, i.e the order in which a file is picked, as well as the rest who's content is ignored when there is colliding filenames within a catalog. 

rdar: //81691423

Author: binamaniar

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -823,7 +823,10 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             throw error
         }
 
-        for analyzedDocument in analyzedDocuments {
+        // to preserve the order of documents by url
+        let analyzedDocumentsSorted = analyzedDocuments.sorted(by: \.0.absoluteString)
+
+        for analyzedDocument in analyzedDocumentsSorted {
             // Store the references we encounter to ensure they're unique. The file name is currently the only part of the URL considered for the topic reference, so collisions may occur.
             let (url, analyzed) = analyzedDocument
 

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -644,15 +644,30 @@ class DocumentationContextTests: XCTestCase {
 
     func testDetectsReferenceCollision() throws {
         let (_, context) = try testBundleAndContext(named: "TestBundleWithDupe")
-        
-        XCTAssert(
-            context.problems.contains { problem in
-                problem.diagnostic.identifier == "org.swift.docc.DuplicateReference"
-                    && problem.diagnostic.localizedSummary == "Redeclaration of 'TestTutorial.tutorial'; this file will be skipped"
-            }
-        )
+
+        let problemWithDuplicate = context.problems.filter { $0.diagnostic.identifier == "org.swift.docc.DuplicateReference" }
+
+        XCTAssertEqual(problemWithDuplicate.count, 1)
+
+        let localizedSummary = try XCTUnwrap(problemWithDuplicate.first?.diagnostic.localizedSummary)
+        XCTAssertEqual(localizedSummary, "Redeclaration of 'TestTutorial.tutorial'; this file will be skipped")
+
     }
 
+    func testDetectsMultipleMDfilesWithSameName() throws {
+        let (_, context) = try testBundleAndContext(named: "TestBundleWithDupMD")
+
+        let problemWithDuplicateReference = context.problems.filter { $0.diagnostic.identifier == "org.swift.docc.DuplicateReference" }
+
+        XCTAssertEqual(problemWithDuplicateReference.count, 2)
+
+        let localizedSummary = try XCTUnwrap(problemWithDuplicateReference.first?.diagnostic.localizedSummary)
+        XCTAssertEqual(localizedSummary, "Redeclaration of \'overview.md\'; this file will be skipped")
+
+        let localizedSummarySecond = try XCTUnwrap(problemWithDuplicateReference[1].diagnostic.localizedSummary)
+        XCTAssertEqual(localizedSummarySecond, "Redeclaration of \'overview.md\'; this file will be skipped")
+    }
+
     func testGraphChecks() throws {
         let workspace = DocumentationWorkspace()
         let context = try DocumentationContext(dataProvider: workspace)

Tests/SwiftDocCTests/Test Bundles/TestBundleWithDupMD.docc/Info.plist

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleName</key>
+	<string>TestBundleWithDupMD</string>
+	<key>CFBundleDisplayName</key>
+	<string>Test Bundle</string>
+	<key>CFBundleIdentifier</key>
+	<string>org.swift.docc.example</string>
+	<key>CFBundleIconFile</key>
+	<string>DocumentationIcon</string>
+	<key>CFBundleIconName</key>
+	<string>DocumentationIcon</string>
+	<key>CFBundlePackageType</key>
+	<string>DOCS</string>
+	<key>CFBundleSignature</key>
+	<string>????</string>
+	<key>CFBundleVersion</key>
+	<string>0.1.0</string>
+	<key>CFBundleShortVersionString</key>
+	<string>0.1.0</string>
+</dict>
+</plist>

Tests/SwiftDocCTests/Test Bundles/TestBundleWithDupMD.docc/documentation/overview.md

@@ -0,0 +1,9 @@
+# Getting Started with Capybara
+
+Create a capybara and assign personality traits and abilities.
+
+## Overview at documentation level
+
+Capybara are complex creatures that require careful creation and a suitable habitat. After creating a capybara, you're responsible for feeding them, providing fulfilling activities, and giving them opportunities to exercise and rest.
+
+<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Test Bundles/TestBundleWithDupMD.docc/documentation1/overview.md

@@ -0,0 +1,9 @@
+# Getting Started with Monkeys
+
+Create a monkey and assign personality traits and abilities.
+
+## Overview at documentation1
+
+Monekys are complex creatures that require careful creation and a suitable habitat. After creating a sloth, you're responsible for feeding them, providing fulfilling activities, and giving them opportunities to exercise and rest. 
+
+<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Test Bundles/TestBundleWithDupMD.docc/overview.md

@@ -0,0 +1,9 @@
+# Getting Started with Monkeys
+
+Create a monkey and assign personality traits and abilities.
+
+## Overview at parent level
+
+Monkeys are complex creatures that require careful creation and a suitable habitat. After creating a sloth, you're responsible for feeding them, providing fulfilling activities, and giving them opportunities to exercise and rest. 
+
+<!-- Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved. -->