Emit variants if any root module is a symbol kind (#1333)

* Extract helper in `RenderNodeTranslatorTests`

One of the test methods in `RenderNodeTranslatorTests` was duplicated
multiple times. It has been extracted out of the tests and deduplicated.

* Emit variants if any root module is a symbol

When the render node translator visits articles, it emits variants for
each language that the article is supported in. This step is skipped if
an article-only catalog is being built, since it would otherwise lead to
a redundant "Swift" language marker being rendered in the page. However,
if a catalog contains more than one module, i.e. an article-only
collection and a different module's symbol graph in the same catalog,
then the variants are not emitted despite the possibility of the page
being available in more than one language. This commit changes the
boolean check to skip emitting variants only if all root modules are
article-only. It does not affect the behaviour when building a correctly
configured catalog that contains a sole root module.

rdar://163926698

Author: snprajwal

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -632,9 +632,8 @@ public struct RenderNodeTranslator: SemanticVisitor {
         // Emit variants only if we're not compiling an article-only catalog to prevent renderers from
         // advertising the page as "Swift", which is the language DocC assigns to pages in article only catalogs.
         // (github.com/swiftlang/swift-docc/issues/240).
-        if let topLevelModule = context.soleRootModuleReference,
-           try! context.entity(with: topLevelModule).kind.isSymbol
-        {
+        let isArticleOnlyCatalog = context.rootModules.allSatisfy { !context.isSymbol(reference: $0) }
+        if !isArticleOnlyCatalog {
             node.variants = variants(for: documentationNode)
         }
 

Tests/SwiftDocCTests/Indexing/NavigatorIndexTests.swift

@@ -15,7 +15,7 @@ import SwiftDocCTestUtilities
 typealias Node = NavigatorTree.Node
 typealias PageType = NavigatorIndex.PageType
 
-let testBundleIdentifier = "org.swift.docc.example"
+private let testBundleIdentifier = "org.swift.docc.example"
 
 class NavigatorIndexingTests: XCTestCase {
 

Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift

@@ -1334,31 +1334,22 @@ class RenderNodeTranslatorTests: XCTestCase {
                 ),
             ]
         )
-        let (bundle, context) = try await loadBundle(catalog: catalog)
+        let (_, context) = try await loadBundle(catalog: catalog)
 
-        func renderNodeArticleFromReferencePath(
-            referencePath: String
-        ) throws -> RenderNode {
-            let reference = ResolvedTopicReference(bundleID: bundle.id, path: referencePath, sourceLanguage: .swift)
-            let symbol = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
-            var translator = RenderNodeTranslator(context: context, identifier: reference)
-            return try XCTUnwrap(translator.visitArticle(symbol) as? RenderNode)
-        }
-        
         // Assert that articles that curates any symbol gets 'API Collection' assigned as the eyebrow title.
-        var renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/APICollection")
+        var renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/APICollection")
         XCTAssertEqual(renderNode.metadata.roleHeading, "API Collection")
         // Assert that articles that curates only other articles don't get any value assigned as the eyebrow title.
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/Collection")
+        renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/Collection")
         XCTAssertEqual(renderNode.metadata.roleHeading, nil)
         // Assert that articles that don't curate anything else get 'Article' assigned as the eyebrow title.
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/Article")
+        renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/Article")
         XCTAssertEqual(renderNode.metadata.roleHeading, "Article")
         // Assert that articles that have a custom title heading the eyebrow title assigned properly.
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/CustomRole")
+        renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/CustomRole")
         XCTAssertEqual(renderNode.metadata.roleHeading, "Custom Role")
         // Assert that articles that have a custom page kind the eyebrow title assigned properly.
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/SampleCode")
+        renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/SampleCode")
         XCTAssertEqual(renderNode.metadata.roleHeading, "Sample Code")
     }
 
@@ -1426,35 +1417,26 @@ class RenderNodeTranslatorTests: XCTestCase {
                 ),
             ]
         )
-        let (bundle, context) = try await loadBundle(catalog: catalog)
-
-        func renderNodeArticleFromReferencePath(
-            referencePath: String
-        ) throws -> RenderNode {
-            let reference = ResolvedTopicReference(bundleID: bundle.id, path: referencePath, sourceLanguage: .swift)
-            let symbol = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
-            var translator = RenderNodeTranslator(context: context, identifier: reference)
-            return try XCTUnwrap(translator.visitArticle(symbol) as? RenderNode)
-        }
+        let (_, context) = try await loadBundle(catalog: catalog)
 
         // Assert that API collections disabling automatic title headings don't get any value assigned as the eyebrow title,
         // but that the node's role itself is unaffected.
-        var renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/APICollection")
+        var renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/APICollection")
         XCTAssertEqual(renderNode.metadata.roleHeading, nil)
         XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.collectionGroup.rawValue)
         // Assert that articles disabling automatic title headings don't get any value assigned as the eyebrow title,
         // but that the node's role itself is unaffected.
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/Article")
+        renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/Article")
         XCTAssertEqual(renderNode.metadata.roleHeading, nil)
         XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.article.rawValue)
         // Assert that articles that have a custom title heading have the eyebrow title assigned properly,
         // even when automatic title headings are disabled.
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/CustomRole")
+        renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/CustomRole")
         XCTAssertEqual(renderNode.metadata.roleHeading, "Custom Role")
         XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.article.rawValue)
         // Assert that articles that have a custom page kind have the eyebrow title assigned properly,
         // even when automatic title headings are disabled.
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/SampleCode")
+        renderNode = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/unit-test/SampleCode")
         XCTAssertEqual(renderNode.metadata.roleHeading, "Sample Code")
     }
 
@@ -1544,7 +1526,7 @@ class RenderNodeTranslatorTests: XCTestCase {
             ]
         ))
 
-        func renderNodeArticleFromReferencePath(
+        func renderNodeSymbolFromReferencePath(
             referencePath: String
         ) throws -> RenderNode {
             let reference = ResolvedTopicReference(bundleID: context.inputs.id, path: referencePath, sourceLanguage: .swift)
@@ -1554,25 +1536,69 @@ class RenderNodeTranslatorTests: XCTestCase {
         }
 
         // Assert that CounterpartSymbol's source languages have been added as source languages of Symbol
-        var renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/Symbol")
+        var renderNode = try renderNodeSymbolFromReferencePath(referencePath: "/documentation/unit-test/Symbol")
         XCTAssertEqual(renderNode.variants?.count, 2)
         XCTAssertEqual(renderNode.variants, [
             .init(traits: [.interfaceLanguage("swift")], paths: ["/documentation/unit-test/symbol"]),
             .init(traits: [.interfaceLanguage("occ")], paths: ["/documentation/unit-test/counterpartsymbol"])
         ])
 
         // Assert that alternate representations which can't be resolved are ignored
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/OtherSymbol")
+        renderNode = try renderNodeSymbolFromReferencePath(referencePath: "/documentation/unit-test/OtherSymbol")
         XCTAssertEqual(renderNode.variants?.count, 1)
         XCTAssertEqual(renderNode.variants, [
             .init(traits: [.interfaceLanguage("swift")], paths: ["/documentation/unit-test/othersymbol"]),
         ])
 
         // Assert that duplicate alternate representations are not added as variants
-        renderNode = try renderNodeArticleFromReferencePath(referencePath: "/documentation/unit-test/MultipleSwiftVariantsSymbol")
+        renderNode = try renderNodeSymbolFromReferencePath(referencePath: "/documentation/unit-test/MultipleSwiftVariantsSymbol")
         XCTAssertEqual(renderNode.variants?.count, 1)
         XCTAssertEqual(renderNode.variants, [
             .init(traits: [.interfaceLanguage("swift")], paths: ["/documentation/unit-test/multipleswiftvariantssymbol"]),
         ])
     }
+
+    // Tests if variants are emitted in catalogs with more than one root module.
+    func testEmitVariantsInCatalogWithMultipleModules() async throws {
+        let (_, context) = try await loadBundle(catalog: Folder(
+            name: "UnitTest.docc",
+            content: [
+                TextFile(name: "UnitTest.md", utf8Content: """
+                # Unit test
+
+                @Metadata {
+                  @TechnologyRoot
+                  @SupportedLanguage(swift)
+                  @SupportedLanguage(occ)
+                }
+
+                This is an article in a catalog containing a module different from the article-only collection.
+                """),
+                // The correct way to configure a catalog is to have a single
+                // root module. If multiple modules are present, it is not
+                // possible to determine which module an article is supposed to
+                // be registered with. This test includes another module to
+                // verify if the variants are correctly emitted when there is
+                // no sole root module.
+                JSONFile(name: "foo.symbols.json", content: makeSymbolGraph(moduleName: "foo")),
+            ]
+        ))
+
+        let article = try renderNodeArticleFromReferencePath(context: context, referencePath: "/documentation/UnitTest")
+        XCTAssertEqual(article.variants?.count, 2)
+        XCTAssertEqual(article.variants, [
+            .init(traits: [.interfaceLanguage("swift")], paths: ["/documentation/unittest"]),
+            .init(traits: [.interfaceLanguage("occ")], paths: ["/documentation/unittest"])
+        ])
+    }
+
+    private func renderNodeArticleFromReferencePath(
+        context: DocumentationContext,
+        referencePath: String
+    ) throws -> RenderNode {
+        let reference = ResolvedTopicReference(bundleID: context.inputs.id, path: referencePath, sourceLanguage: .swift)
+        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
+        var translator = RenderNodeTranslator(context: context, identifier: reference)
+        return try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
+    }
 }