Include manually curated non-symbol nodes in the Topics section regardless of the source language of the symbol (#757)

sofiaromorales · franklinsch · d-ronnqvist · web-flow · commit 7cdca7fd6a21 · 2023-12-07T13:39:09.000+01:00
If the node to which the reference belongs is a non symbol node, render the topic in the topic section independently of the source language of the curation.

By default, Articles and other non-symbol nodes have the source language set to 'Swift.' Prior to this fix, when curating an Article within a symbol with ObjC availability, the curated article was being omitted from the Topics section. With this fix, we check whether it's an article and maintain the curation, regardless of whether we're linking to a node with a different source language.

rdar://118461894

* Added multiple tests to validate that the correct filter behaviour happens when linking to external articles with the link resolver.
* Refactored tests to validate filtering functionality for all available language variants.

---------

Co-authored-by: Franklin Schrans &lt;fschrans@apple.com&gt;
Co-authored-by: David Rönnqvist &lt;david.ronnqvist@gmail.com&gt;
diff --git a/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift b/Sources/SwiftDocC/Infrastructure/DocumentationContext.swift
@@ -2547,25 +2547,46 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         throw ContextError.notFound(reference.url)
     }
     
-    /// Returns the set of languages the entity corresponding to the given reference is available in.
-    ///
-    /// - Precondition: The entity associated with the given reference must be registered in the context.
-    public func sourceLanguages(for reference: ResolvedTopicReference) -> Set<SourceLanguage> {
+    private func knownEntityValue<Result>(
+        reference: ResolvedTopicReference,
+        valueInLocalEntity: (DocumentationNode) -> Result,
+        valueInExternalEntity: (LinkResolver.ExternalEntity) -> Result
+    ) -> Result {
         do {
             // Look up the entity without its fragment. The documentation context does not keep track of page sections
             // as nodes, and page sections are considered to be available in the same languages as the page they're
             // defined in.
             let referenceWithoutFragment = reference.withFragment(nil)
-            return try entity(with: referenceWithoutFragment).availableSourceLanguages
+            return try valueInLocalEntity(entity(with: referenceWithoutFragment))
         } catch ContextError.notFound {
             if let externalEntity = externalCache[reference] {
-                return externalEntity.sourceLanguages
+                return valueInExternalEntity(externalEntity)
             }
             preconditionFailure("Reference does not have an associated documentation node.")
         } catch {
-            fatalError("Unexpected error when retrieving source languages: \(error)")
+            fatalError("Unexpected error when retrieving entity: \(error)")
         }
     }
+    
+    /// Returns the set of languages the entity corresponding to the given reference is available in.
+    ///
+    /// - Precondition: The entity associated with the given reference must be registered in the context.
+    public func sourceLanguages(for reference: ResolvedTopicReference) -> Set<SourceLanguage> {
+        knownEntityValue(
+            reference: reference,
+            valueInLocalEntity: \.availableSourceLanguages,
+            valueInExternalEntity: \.sourceLanguages
+        )
+    }
+    
+    /// Returns whether the given reference corresponds to a symbol.
+    func isSymbol(reference: ResolvedTopicReference) -> Bool {
+        knownEntityValue(
+            reference: reference,
+            valueInLocalEntity: { node in node.kind.isSymbol },
+            valueInExternalEntity: { entity in entity.topicRenderReference.kind == .symbol }
+        )
+    }
 
     // MARK: - Relationship queries
     
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift
@@ -1048,6 +1048,13 @@ public struct RenderNodeTranslator: SemanticVisitor {
                     return true
                 }
                 
+                guard context.isSymbol(reference: reference) else {
+                    // If the reference corresponds to any kind except Symbol
+                    // (e.g., Article, Tutorial, SampleCode...), allow the topic
+                    // to appear independently of the source language it belongs to.
+                    return true
+                }
+                
                 let referenceSourceLanguageIDs = Set(context.sourceLanguages(for: reference).map(\.id))
                 
                 let availableSourceLanguageTraits = Set(availableTraits.compactMap(\.interfaceLanguage))
@@ -1491,7 +1498,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
             
             var sections = [TaskGroupRenderSection]()
             if let topics = topics, !topics.taskGroups.isEmpty {
-                // Allowed traits should be all traits except the reverse of the objc/swift pairing
+                // Allowed symbol traits should be all traits except the reverse of the objc/swift pairing
                 sections.append(
                     contentsOf: renderGroups(
                         topics,
diff --git a/Tests/SwiftDocCTests/Infrastructure/ExternalReferenceResolverTests.swift b/Tests/SwiftDocCTests/Infrastructure/ExternalReferenceResolverTests.swift
@@ -912,4 +912,97 @@ Document @1:1-1:35
         let finalURL = urlGenerator.presentationURLForReference(linkReference)
         XCTAssertEqual(finalURL.absoluteString, "https://example.com/example/externally/resolved/path#67890")
     }
+    
+    func testExternalArticlesAreIncludedInAllVariantsTopicsSection() throws {
+        let externalResolver = TestMultiResultExternalReferenceResolver()
+        externalResolver.bundleIdentifier = "com.test.external"
+        
+        externalResolver.entitiesToReturn["/path/to/external/swiftArticle"] = .success(
+            .init(
+                    referencePath: "/path/to/external/swiftArticle",
+                    title: "SwiftArticle",
+                    kind: .article,
+                    language: .swift
+                )
+        )
+        
+        externalResolver.entitiesToReturn["/path/to/external/objCArticle"] = .success(
+            .init(
+                    referencePath: "/path/to/external/objCArticle",
+                    title: "ObjCArticle",
+                    kind: .article,
+                    language: .objectiveC
+                )
+        )
+        
+        externalResolver.entitiesToReturn["/path/to/external/swiftSymbol"] = .success(
+            .init(
+                referencePath: "/path/to/external/swiftSymbol",
+                title: "SwiftSymbol",
+                kind: .class,
+                language: .swift
+            )
+        )
+                
+        externalResolver.entitiesToReturn["/path/to/external/objCSymbol"] = .success(
+            .init(
+                referencePath: "/path/to/external/objCSymbol",
+                title: "ObjCSymbol",
+                kind: .class,
+                language: .objectiveC
+            )
+        )
+        
+        let (_, bundle, context) = try testBundleAndContext(
+            copying: "MixedLanguageFramework",
+            externalResolvers: [externalResolver.bundleIdentifier: externalResolver]
+        ) { url in
+            let mixedLanguageFrameworkExtension = """
+                # ``MixedLanguageFramework``
+                
+                This symbol has a Swift and Objective-C variant.
+
+                ## Topics
+                
+                ### External Reference
+
+                - <doc://com.test.external/path/to/external/swiftArticle>
+                - <doc://com.test.external/path/to/external/swiftSymbol>
+                - <doc://com.test.external/path/to/external/objCArticle>
+                - <doc://com.test.external/path/to/external/objCSymbol>
+                """
+            try mixedLanguageFrameworkExtension.write(to: url.appendingPathComponent("/MixedLanguageFramework.md"), atomically: true, encoding: .utf8)
+        }
+        let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+        let mixedLanguageFrameworkReference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/MixedLanguageFramework",
+            sourceLanguage: .swift
+        )
+        let node = try context.entity(with: mixedLanguageFrameworkReference)
+        let fileURL = try XCTUnwrap(context.documentURL(for: node.reference))
+        let renderNode = try converter.convert(node, at: fileURL)
+        // Topic identifiers in the Swift variant of the `MixedLanguageFramework` symbol
+        let swiftTopicIDs = renderNode.topicSections.flatMap(\.identifiers)
+        
+        let data = try renderNode.encodeToJSON()
+        let variantRenderNode = try RenderNodeVariantOverridesApplier()
+            .applyVariantOverrides(in: data, for: [.interfaceLanguage("occ")])
+        let objCRenderNode = try RenderJSONDecoder.makeDecoder().decode(RenderNode.self, from: variantRenderNode)
+        // Topic identifiers in the ObjC variant of the `MixedLanguageFramework` symbol
+        let objCTopicIDs = objCRenderNode.topicSections.flatMap(\.identifiers)
+        
+        // Verify that external articles are included in the Topics section of both symbol
+        // variants regardless of their perceived language.
+        XCTAssertTrue(swiftTopicIDs.contains("doc://com.test.external/path/to/external/swiftArticle"))
+        XCTAssertTrue(swiftTopicIDs.contains("doc://com.test.external/path/to/external/objCArticle"))
+        XCTAssertTrue(objCTopicIDs.contains("doc://com.test.external/path/to/external/swiftArticle"))
+        XCTAssertTrue(objCTopicIDs.contains("doc://com.test.external/path/to/external/objCArticle"))
+        // Verify that external language specific symbols are dropped from the Topics section in the
+        // variants for languages where the symbol isn't available.
+        XCTAssertFalse(swiftTopicIDs.contains("doc://com.test.external/path/to/external/objCSymbol"))
+        XCTAssertTrue(swiftTopicIDs.contains("doc://com.test.external/path/to/external/swiftSymbol"))
+        XCTAssertTrue(objCTopicIDs.contains("doc://com.test.external/path/to/external/objCSymbol"))
+        XCTAssertFalse(objCTopicIDs.contains("doc://com.test.external/path/to/external/swiftSymbol"))
+    }
 }
diff --git a/Tests/SwiftDocCTests/Model/SemaToRenderNodeMultiLanguageTests.swift b/Tests/SwiftDocCTests/Model/SemaToRenderNodeMultiLanguageTests.swift
@@ -888,6 +888,88 @@ class SemaToRenderNodeMixedLanguageTests: XCTestCase {
         )
     }
     
+    func testArticlesAreIncludedInAllVariantsTopicsSection() throws {
+        let outputConsumer = try renderNodeConsumer(
+            for: "MixedLanguageFramework",
+            configureBundle: { bundleURL in
+                try """
+                # ObjCArticle
+
+                @Metadata {
+                    @SupportedLanguage(objc)
+                }
+
+                This article has Objective-C as the source language.
+                
+                ## Topics
+                """.write(to: bundleURL.appendingPathComponent("ObjCArticle.md"), atomically: true, encoding: .utf8)
+                try """
+                # SwiftArticle
+                
+                @Metadata {
+                    @SupportedLanguage(swift)
+                }
+
+                This article has Swift as the source language.
+                """.write(to: bundleURL.appendingPathComponent("SwiftArticle.md"), atomically: true, encoding: .utf8)
+                try """
+                # ``MixedLanguageFramework``
+                
+                This symbol has a Swift and Objective-C variant.
+
+                ## Topics
+                
+                - <doc:ObjCArticle>
+                - <doc:SwiftArticle>
+                - ``_MixedLanguageFrameworkVersionNumber``
+                - ``SwiftOnlyStruct``
+                
+                """.write(to: bundleURL.appendingPathComponent("MixedLanguageFramework.md"), atomically: true, encoding: .utf8)
+            }
+        )
+        assertIsAvailableInLanguages(
+            try outputConsumer.renderNode(
+                withTitle: "ObjCArticle"
+            ),
+            languages: ["occ"],
+            defaultLanguage: .objectiveC
+        )
+        assertIsAvailableInLanguages(
+            try outputConsumer.renderNode(
+                withTitle: "_MixedLanguageFrameworkVersionNumber"
+            ),
+            languages: ["occ"],
+            defaultLanguage: .objectiveC
+        )
+        
+        let renderNode = try outputConsumer.renderNode(withIdentifier: "MixedLanguageFramework")
+        
+        // Topic identifiers in the Swift variant of the `MixedLanguageFramework` symbol
+        let swiftTopicIDs = renderNode.topicSections.flatMap(\.identifiers)
+
+        let data = try renderNode.encodeToJSON()
+        let variantRenderNode = try RenderNodeVariantOverridesApplier()
+            .applyVariantOverrides(in: data, for: [.interfaceLanguage("occ")])
+        let objCRenderNode = try RenderJSONDecoder.makeDecoder().decode(RenderNode.self, from: variantRenderNode)
+        // Topic identifiers in the ObjC variant of the `MixedLanguageFramework` symbol
+        let objCTopicIDs = objCRenderNode.topicSections.flatMap(\.identifiers)
+
+
+        // Verify that articles are included in the Topics section of both symbol
+        // variants regardless of their perceived language.
+        XCTAssertTrue(swiftTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/ObjCArticle"))
+        XCTAssertTrue(swiftTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/SwiftArticle"))
+        XCTAssertTrue(objCTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/SwiftArticle"))
+        XCTAssertTrue(objCTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/ObjCArticle"))
+        
+        // Verify that language specific symbols are dropped from the Topics section in the
+        // variants for languages where the symbol isn't available.
+        XCTAssertTrue(swiftTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/SwiftOnlyStruct"))
+        XCTAssertFalse(swiftTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/_MixedLanguageFrameworkVersionNumber"))
+        XCTAssertTrue(objCTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/_MixedLanguageFrameworkVersionNumber"))
+        XCTAssertFalse(objCTopicIDs.contains("doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/SwiftOnlyStruct"))
+    }
+    
     func renderNodeApplyingObjectiveCVariantOverrides(to renderNode: RenderNode) throws -> RenderNode {
         return try renderNodeApplying(variant: "occ", to: renderNode)
     }
