False positive warning when curating symbol with special character (s…

…wiftlang#642)

* Fix false-positive warning for curated symbols with special characters

rdar://111227479

* Remove redundant symbol index modification

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -658,9 +658,12 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
         for result in results.sync({ $0 }) {
             documentationCache[result.reference] = result.node
-            if let preciseIdentifier = result.node.symbol?.identifier.precise {
-                symbolIndex[preciseIdentifier] = result.reference
-            }
+            assert(
+                // If this is a symbol, verify that the reference exist in the in the symbolIndex
+                result.node.symbol.map { symbolIndex[$0.identifier.precise] == result.reference }
+                ?? true, // Nothing to check for non-symbols
+                "Previous versions updated the symbolIndex here. This assert verifies that that's no longer necessary."
+            )
             diagnosticEngine.emit(result.problems)
         }
     }
@@ -2378,6 +2381,15 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             bundle: bundle
         )
 
+        // After the resolving links in tutorial content all the local references are known and can be added to the referenceIndex for fast lookup.
+        referenceIndex.reserveCapacity(knownIdentifiers.count + nodeAnchorSections.count)
+        for reference in knownIdentifiers {
+            referenceIndex[reference.absoluteString] = reference
+        }
+        for reference in nodeAnchorSections.keys {
+            referenceIndex[reference.absoluteString] = reference
+        }
+
         try shouldContinueRegistration()
         var allCuratedReferences: Set<ResolvedTopicReference>
         if LinkResolutionMigrationConfiguration.shouldUseHierarchyBasedLinkResolver {
@@ -2433,22 +2445,14 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
         // Sixth - fetch external entities and merge them in the context
         mergeExternalEntities(withReferences: Array(externallyResolvedSymbols))
+        for case .success(let reference) in externallyResolvedLinks.values {
+            referenceIndex[reference.absoluteString] = reference
+        }
 
         // Seventh, the complete topic graph—with all nodes and all edges added—is analyzed.
         topicGraphGlobalAnalysis()
 
         preResolveModuleNames()
-
-        referenceIndex.reserveCapacity(knownIdentifiers.count + nodeAnchorSections.count)
-        for reference in knownIdentifiers {
-            referenceIndex[reference.absoluteString] = reference
-        }
-        for case .success(let reference) in externallyResolvedLinks.values {
-            referenceIndex[reference.absoluteString] = reference
-        }
-        for reference in nodeAnchorSections.keys {
-            referenceIndex[reference.absoluteString] = reference
-        }
     }
 
     /// Given a list of topics that have been automatically curated, checks if a topic has been additionally manually curated

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -1667,6 +1667,28 @@ let expected = """
         XCTAssertEqual(node.kind, .unknown)
     }
 
+    func testCuratingSymbolsWithSpecialCharacters() throws {
+        try XCTSkipUnless(LinkResolutionMigrationConfiguration.shouldUseHierarchyBasedLinkResolver)
+
+        let (_, _, context) = try testBundleAndContext(copying: "InheritedOperators") { root in
+            try """
+            # ``Operators/MyNumber``
+            
+            A documentation extension that curates symbosl with characters not allowed in a resolved reference URL.
+
+            ## Topics
+
+            - ``<(_:_:)``
+            - ``>(_:_:)``
+            - ``<=(_:_:)``
+            - ``>=(_:_:)``
+            """.write(to: root.appendingPathComponent("doc-extension.md"), atomically: true, encoding: .utf8)
+        }
+
+        let unresolvedTopicProblems = context.problems.filter({ $0.diagnostic.identifier == "org.swift.docc.unresolvedTopicReference" })
+        XCTAssertEqual(unresolvedTopicProblems.map(\.diagnostic.summary), [], "All links should resolve without warnings")
+    }
+
     func testSpecialCharactersInLinks() throws {
         try XCTSkipUnless(LinkResolutionMigrationConfiguration.shouldUseHierarchyBasedLinkResolver)