Merge branch 'main' into fix-closure-parameter-disambiguation-suggestion

# Conflicts:
#	Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

Author: d-ronnqvist

Package.resolved

@@ -131,8 +131,8 @@ public enum LinkCompletionTools {
                 node,
                 kind: symbol.kind,
                 hash: symbol.symbolIDHash,
-                parameterTypes: symbol.parameterTypes,
-                returnTypes: symbol.returnTypes
+                parameterTypes: symbol.parameterTypes?.map { $0.withoutWhitespace() },
+                returnTypes: symbol.returnTypes?.map { $0.withoutWhitespace() }
             )
         }
 
@@ -236,3 +236,9 @@ private extension PathHierarchy.PathComponent.Disambiguation {
         }
     }
 }
+
+private extension String {
+    func withoutWhitespace() -> String {
+        filter { !$0.isWhitespace }
+    }
+}

Sources/SwiftDocC/DocumentationService/Convert/Symbol Link Resolution/LinkCompletionTools.swift

@@ -2428,18 +2428,17 @@ public class DocumentationContext {
 
         // Crawl the rest of the symbols that haven't been crawled so far in hierarchy pre-order.
         allCuratedReferences = try crawlSymbolCuration(in: automaticallyCurated.map(\.symbol), bundle: bundle, initial: allCuratedReferences)
-
-        // Remove curation paths that have been created automatically above
-        // but we've found manual curation for in the second crawl pass.
-        removeUnneededAutomaticCuration(automaticallyCurated)
 
         // Automatically curate articles that haven't been manually curated
         // Article curation is only done automatically if there is only one root module
         if let rootNode = rootNodeForAutomaticCuration {
             let articleReferences = try autoCurateArticles(otherArticles, startingFrom: rootNode)
-            preResolveExternalLinks(references: articleReferences, localBundleID: bundle.id)
-            resolveLinks(curatedReferences: Set(articleReferences), bundle: bundle)
+            allCuratedReferences = try crawlSymbolCuration(in: articleReferences, bundle: bundle, initial: allCuratedReferences)
         }
+        
+        // Remove curation paths that have been created automatically above
+        // but we've found manual curation for in the second crawl pass.
+        removeUnneededAutomaticCuration(automaticallyCurated)
 
         // Remove any empty "Extended Symbol" pages whose children have been curated elsewhere.
         for module in rootModules {

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -136,6 +136,11 @@ extension PathHierarchy {
                     // For example: "[", "?", "<", "...", ",", "(", "->" etc. contribute to the type spellings like
                     // `[Name]`, `Name?`, "Name<T>", "Name...", "()", "(Name, Name)", "(Name)->Name" and more.
                     let utf8Spelling = fragment.spelling.utf8
+                    guard !utf8Spelling.elementsEqual(".Type".utf8) else {
+                        // Once exception to that is "Name.Type" which is different from just "Name" (and we don't want a trailing ".")
+                        accumulated.append(contentsOf: utf8Spelling)
+                        continue
+                    }
                     for index in utf8Spelling.indices {
                         let char = utf8Spelling[index]
                         switch char {

Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy+TypeSignature.swift

@@ -330,7 +330,7 @@ struct TopicGraph {
         }
 
         var result = ""
-        result.append("\(decorator) \(node[keyPath: keyPath])\r\n")
+        result.append("\(decorator) \(node[keyPath: keyPath])\n")
         if let childEdges = edges[node.reference]?.sorted(by: { $0.path < $1.path }) {
             for (index, childRef) in childEdges.enumerated() {
                 var decorator = decorator

Sources/SwiftDocC/Infrastructure/Topic Graph/TopicGraph.swift

@@ -15,7 +15,7 @@
                     "interfaceLanguages"
                 ],
                 "properties": {
-                    "identifier": {
+                    "schemaVersion": {
                         "$ref": "#/components/schemas/SchemaVersion"
                     },
                     "interfaceLanguages": {

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderIndex.spec.json

@@ -201,6 +201,90 @@ class DocumentationCuratorTests: XCTestCase {
         XCTAssertEqual(curationProblem.possibleSolutions.map(\.summary), ["Remove '- <doc:First>'"])
     }
 
+    func testCurationInUncuratedAPICollection() throws {
+        // Everything should behave the same when an API Collection is automatically curated as when it is explicitly curated
+        for shouldCurateAPICollection in [true, false] {
+            let assertionMessageDescription = "when the API collection is \(shouldCurateAPICollection ? "explicitly curated" : "auto-curated as an article under the module")."
+            
+            let catalog = Folder(name: "unit-test.docc", content: [
+                JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(moduleName: "ModuleName", symbols: [
+                    makeSymbol(id: "some-symbol-id", kind: .class, pathComponents: ["SomeClass"])
+                ])),
+                
+                TextFile(name: "ModuleName.md", utf8Content: """
+                # ``ModuleName``
+                
+                \(shouldCurateAPICollection ? "## Topics\n\n### Explicit curation\n\n- <doc:API-Collection>" : "")
+                """),
+                
+                TextFile(name: "API-Collection.md", utf8Content: """
+                # Some API collection
+                
+                Curate the only symbol
+                
+                ## Topics
+                    
+                - ``SomeClass``
+                - ``NotFound``
+                """),
+            ])
+            let (bundle, context) = try loadBundle(catalog: catalog)
+            XCTAssertEqual(
+                context.problems.map(\.diagnostic.summary),
+                [
+                    // There should only be a single problem about the unresolvable link in the API collection.
+                    "'NotFound' doesn't exist at '/unit-test/API-Collection'"
+                ],
+                "Unexpected problems: \(context.problems.map(\.diagnostic.summary).joined(separator: "\n")) \(assertionMessageDescription)"
+            )
+            
+            // Verify that the topic graph paths to the symbol (although not used for its breadcrumbs) doesn't have the automatic edge anymore.
+            let symbolReference = try XCTUnwrap(context.knownPages.first(where: { $0.lastPathComponent == "SomeClass" }))
+            XCTAssertEqual(
+                context.finitePaths(to: symbolReference).map { $0.map(\.path) },
+                [
+                    // The automatic default `["/documentation/ModuleName"]` curation _shouldn't_ be here.
+                    
+                    // The authored curation in the uncurated API collection
+                    ["/documentation/ModuleName", "/documentation/unit-test/API-Collection"],
+                ],
+                "Unexpected 'paths' to the symbol page \(assertionMessageDescription)"
+            )
+            
+            // Verify that the symbol page shouldn't auto-curate in its canonical location.
+            let symbolTopicNode = try XCTUnwrap(context.topicGraph.nodeWithReference(symbolReference))
+            XCTAssertFalse(symbolTopicNode.shouldAutoCurateInCanonicalLocation, "Symbol node is unexpectedly configured to auto-curate \(assertionMessageDescription)")
+            
+            // Verify that the topic graph doesn't have the automatic edge anymore.
+            XCTAssertEqual(context.dumpGraph(), """
+                 doc://unit-test/documentation/ModuleName
+                 ╰ doc://unit-test/documentation/unit-test/API-Collection
+                   ╰ doc://unit-test/documentation/ModuleName/SomeClass
+                
+                """,
+                "Unexpected topic graph \(assertionMessageDescription)"
+            )
+            
+            // Verify that the rendered top-level page doesn't have an automatic "Classes" topic section anymore.
+            let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+            let moduleReference = try XCTUnwrap(context.soleRootModuleReference)
+            let rootRenderNode = converter.convert(try context.entity(with: moduleReference))
+            
+            XCTAssertEqual(
+                rootRenderNode.topicSections.map(\.title),
+                [shouldCurateAPICollection ? "Explicit curation" : "Articles"],
+                "Unexpected rendered topic sections on the module page \(assertionMessageDescription)"
+            )
+            XCTAssertEqual(
+                rootRenderNode.topicSections.map(\.identifiers),
+                [
+                    ["doc://unit-test/documentation/unit-test/API-Collection"],
+                ],
+                "Unexpected rendered topic sections on the module page \(assertionMessageDescription)"
+            )
+        }
+    }
+    
     func testModuleUnderTechnologyRoot() throws {
         let (_, bundle, context) = try testBundleAndContext(copying: "SourceLocations") { url in
             try """

Tests/SwiftDocCTests/Infrastructure/DocumentationCuratorTests.swift

@@ -3889,6 +3889,42 @@ class PathHierarchyTests: XCTestCase {
             ])
         }
 
+        // The second overload refers to the metatype of the parameter
+        do {
+            func makeSignature(first: DeclToken...) -> SymbolGraph.Symbol.FunctionSignature {
+                .init(
+                    parameters: [.init(name: "first",  externalName: "with", declarationFragments: makeFragments(first),  children: []),],
+                    returns: makeFragments([voidType])
+                )
+            }
+            
+            let someGenericTypeID = "some-generic-type-id"
+            let catalog = Folder(name: "unit-test.docc", content: [
+                JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
+                    moduleName: "ModuleName",
+                    symbols: [
+                        makeSymbol(id: "function-overload-1", kind: .func, pathComponents: ["doSomething(with:)"], signature: makeSignature(
+                            // GenericName
+                            first: .typeIdentifier("GenericName", precise: someGenericTypeID)
+                        )),
+                        
+                        makeSymbol(id: "function-overload-2", kind: .func, pathComponents: ["doSomething(with:)"], signature: makeSignature(
+                            // GenericName.Type
+                            first: .typeIdentifier("GenericName", precise: someGenericTypeID), ".Type"
+                        )),
+                    ]
+                ))
+            ])
+            
+            let (_, context) = try loadBundle(catalog: catalog)
+            let tree = context.linkResolver.localResolver.pathHierarchy
+            
+            try assertPathCollision("ModuleName/doSomething(with:)", in: tree, collisions: [
+                (symbolID: "function-overload-1", disambiguation: "-(GenericName)"),      //  GenericName
+                (symbolID: "function-overload-2", disambiguation: "-(GenericName.Type)"), //  GenericName.Type
+            ])
+        }
+        
         // Second overload requires combination of two non-unique types to disambiguate
         do {
             //  String   Set<Int>  (Double)->Void

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

@@ -237,4 +237,25 @@ class LinkCompletionToolsTests: XCTestCase {
             "->_",        // The only overload that returns something
         ])
     }
+    
+    func testRemovesWhitespaceFromTypeSignatureDisambiguation() {
+        let overloads = [
+            // The caller included whitespace in these closure type spellings but the DocC disambiguation won't include this whitespace.
+            (parameters: ["(Int) -> Int"],  returns: []), // ((Int)  -> Int)  -> Void
+            (parameters: ["(Bool) -> ()"], returns: []),  // ((Bool) -> () )  -> Void
+        ].map {
+            LinkCompletionTools.SymbolInformation(
+                kind: "func",
+                symbolIDHash: "\($0)".stableHashString,
+                parameterTypes: $0.parameters,
+                returnTypes: $0.returns
+            )
+        }
+        
+        XCTAssertEqual(LinkCompletionTools.suggestedDisambiguation(forCollidingSymbols: overloads), [
+            // Both parameters require the only parameter type as disambiguation. The suggested disambiguation shouldn't contain extra whitespace.
+            "-((Int)->Int)",
+            "-((Bool)->())",
+        ])
+    }
 }