Fix wrong role assigned to technology-root articles (#744)

Fix the role of the Technology Root of Single Article-Only or Article-Only catalogs without any manual curation at the technology root. (closes #743).

Previously, the article role was assigned to the technology root instead of the collection role in the corresponding JSON file of the documentation archive.

* Added tests to validate the correct assignment of roles for this type of case.

rdar://116419389

Author: sofiaromorales

Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift

@@ -141,9 +141,9 @@ public class DocumentationContentRenderer {
         default: break
         }
 
-        if article.topics?.taskGroups.isEmpty == false {
+        let isTechnologyRoot = article.metadata?.technologyRoot != nil
+        if article.topics?.taskGroups.isEmpty == false || isTechnologyRoot {
             // The documentation includes a "Topics" section, it's a collection or a group
-            let isTechnologyRoot = article.metadata?.technologyRoot != nil
             return role(for: (isTechnologyRoot) ? .collection : .collectionGroup)
         } else {
             // The documentation is a plain article

Tests/SwiftDocCTests/Rendering/PageKindTests.swift

@@ -14,11 +14,12 @@ import XCTest
 @testable import SwiftDocC
 
 class PageKindTests: XCTestCase {
-    func testPageKindSampleCode() throws {
-        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
+    
+    private func generateRenderNodeFromBundle(bundleName: String, resolvedTopicPath: String) throws -> RenderNode {
+        let (bundle, context) = try testBundleAndContext(named: bundleName)
         let reference = ResolvedTopicReference(
             bundleIdentifier: bundle.identifier,
-            path: "/documentation/SampleBundle/MyLocalSample",
+            path: resolvedTopicPath,
             sourceLanguage: .swift
         )
         let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
@@ -28,70 +29,43 @@ class PageKindTests: XCTestCase {
             identifier: reference,
             source: nil
         )
-        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
-
+        return try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
+    }
+    
+    func testPageKindSampleCode() throws {
+        let renderNode = try generateRenderNodeFromBundle(
+            bundleName: "SampleBundle",
+            resolvedTopicPath: "/documentation/SampleBundle/MyLocalSample"
+        )
         XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.sampleCode.rawValue)
         XCTAssertEqual(renderNode.metadata.roleHeading, Metadata.PageKind.Kind.sampleCode.titleHeading)
     }
 
     func testPageKindArticle() throws {
-        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
-        let reference = ResolvedTopicReference(
-            bundleIdentifier: bundle.identifier,
-            path: "/documentation/SampleBundle/MySample",
-            sourceLanguage: .swift
+        let renderNode = try generateRenderNodeFromBundle(
+            bundleName: "SampleBundle",
+            resolvedTopicPath: "/documentation/SampleBundle/MySample"
         )
-        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
-        var translator = RenderNodeTranslator(
-            context: context,
-            bundle: bundle,
-            identifier: reference,
-            source: nil
-        )
-        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
 
         XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.article.rawValue)
         XCTAssertEqual(renderNode.metadata.roleHeading, Metadata.PageKind.Kind.article.titleHeading)
     }
 
     func testPageKindDefault() throws {
-        let (bundle, context) = try testBundleAndContext(named: "AvailabilityBundle")
-        let reference = ResolvedTopicReference(
-            bundleIdentifier: bundle.identifier,
-            path: "/documentation/AvailabilityBundle/ComplexAvailable",
-            sourceLanguage: .swift
+        let renderNode = try generateRenderNodeFromBundle(
+            bundleName: "AvailabilityBundle",
+            resolvedTopicPath: "/documentation/AvailabilityBundle/ComplexAvailable"
         )
-        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
-        var translator = RenderNodeTranslator(
-            context: context,
-            bundle: bundle,
-            identifier: reference,
-            source: nil
-        )
-        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
-
         XCTAssertEqual(renderNode.metadata.role, "article")
         XCTAssertEqual(renderNode.metadata.roleHeading, "Article")
     }
 
     func testPageKindReference() throws {
-        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
-        let reference = ResolvedTopicReference(
-            bundleIdentifier: bundle.identifier,
-            path: "/documentation/SomeSample",
-            sourceLanguage: .swift
-        )
-        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
-        var translator = RenderNodeTranslator(
-            context: context,
-            bundle: bundle,
-            identifier: reference,
-            source: nil
+        let renderNode = try generateRenderNodeFromBundle(
+            bundleName: "SampleBundle",
+            resolvedTopicPath: "/documentation/SomeSample"
         )
-        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
-
         let sampleReference = try XCTUnwrap(renderNode.references["doc://org.swift.docc.sample/documentation/SampleBundle/MyLocalSample"] as? TopicRenderReference)
-
         XCTAssertEqual(sampleReference.role, RenderMetadata.Role.sampleCode.rawValue)
     }
 
@@ -118,4 +92,24 @@ class PageKindTests: XCTestCase {
             XCTAssert(problems.isEmpty)
         }
     }
+    
+    // Verify that we assign the `Collection` role to the root article of a
+    // documentation catalog that contains only one article.
+    func testRoleForSingleArticleCatalog() throws {
+        let renderNode = try generateRenderNodeFromBundle(
+            bundleName: "BundleWithSingleArticle",
+            resolvedTopicPath: "/documentation/Article"
+        )
+        XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.collection.rawValue)
+    }
+    
+    // Verify we assign the `Collection` role to the root article of an article-only
+    // documentation catalog that doesn't include manual curation
+    func testRoleForArticleOnlyCatalogWithNoCuration() throws {
+        let renderNode = try generateRenderNodeFromBundle(
+            bundleName: "BundleWithArticlesNoCurated",
+            resolvedTopicPath: "/documentation/Article"
+        )
+        XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.collection.rawValue)
+    }
 }

Tests/SwiftDocCTests/Test Bundles/BundleWithArticlesNoCurated.docc/Article.md

@@ -0,0 +1,13 @@
+# Article
+
+@Metadata {
+  @TechnologyRoot
+}
+
+Add a single sentence or sentence fragment, which DocC uses as the page’s abstract or summary.
+
+## Overview
+
+Add one or more paragraphs that introduce your content overview.
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Test Bundles/BundleWithArticlesNoCurated.docc/Essentials/getting_started.md

@@ -0,0 +1,7 @@
+# Getting Started 
+
+Summary
+
+Overview
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Test Bundles/BundleWithArticlesNoCurated.docc/Essentials/more_information.md

@@ -0,0 +1,7 @@
+# More Information 
+
+Summary
+
+Overview
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Tests/SwiftDocCTests/Test Bundles/BundleWithSingleArticle.docc/Article.md

@@ -0,0 +1,13 @@
+# Article
+
+@Metadata {
+  @TechnologyRoot
+}
+
+This is an article.
+
+## Overview
+
+Overview
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->