Add warning for symbols with @TechnologyRoot pages

When documentation contains symbols (from symbol graphs) and also has
@TechnologyRoot pages, emit a warning about the unsupported setup with
multiple roots in the documentation hierarchy.

The solution suggests removing the @TechnologyRoot directive so pages
are treated as articles under the module instead.

Author: agisilaos

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -2429,6 +2429,39 @@ public class DocumentationContext {
             return node.reference
         }
 
+        // Warn when the documentation contains both symbols (modules) and @TechnologyRoot pages
+        // This is an unsupported setup that creates multiple roots in the documentation hierarchy
+        if !rootModules.isEmpty && !rootPageArticles.isEmpty {
+            let problems = rootPageArticles.map { rootPageArticle -> Problem in
+                let diagnostic = Diagnostic(
+                    source: rootPageArticle.source,
+                    severity: .warning,
+                    range: rootPageArticle.value.metadata?.technologyRoot?.originalMarkup.range,
+                    identifier: "org.swift.docc.TechnologyRootWithSymbols",
+                    summary: "Documentation contains both symbols and articles with @TechnologyRoot directives",
+                    explanation: """
+                    When documentation contains symbols (from symbol graph files), @TechnologyRoot directives create an unsupported setup with multiple roots in the documentation hierarchy.
+                    Remove the @TechnologyRoot directive so that this page is treated as an article under the module.
+                    """
+                )
+                
+                guard let range = rootPageArticle.value.metadata?.technologyRoot?.originalMarkup.range else {
+                    return Problem(diagnostic: diagnostic)
+                }
+                
+                let solution = Solution(
+                    summary: "Remove the \(TechnologyRoot.directiveName.singleQuoted) directive",
+                    replacements: [
+                        Replacement(range: range, replacement: "")
+                    ]
+                )
+                
+                return Problem(diagnostic: diagnostic, possibleSolutions: [solution])
+            }
+            
+            diagnosticEngine.emit(problems)
+        }
+        
         // Articles that will be automatically curated can be resolved but they need to be pre registered before resolving links.
         let rootNodeForAutomaticCuration = soleRootModuleReference.flatMap(topicGraph.nodeWithReference(_:))
         if configuration.convertServiceConfiguration.allowsRegisteringArticlesWithoutTechnologyRoot || rootNodeForAutomaticCuration != nil {

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContext+RootPageTests.swift

@@ -218,6 +218,50 @@ class DocumentationContext_RootPageTests: XCTestCase {
         }
     }
 
+    func testWarnsAboutSymbolsWithTechnologyRootPages() async throws {
+        // Test the third case: documentation contains symbols (has a module) and also has @TechnologyRoot pages
+        let (_, context) = try await loadBundle(catalog:
+            Folder(name: "symbols-with-root.docc", content: [
+                // Symbol graph with a module
+                JSONFile(name: "MyModule.symbols.json", content: makeSymbolGraph(moduleName: "MyModule")),
+                
+                // Article with @TechnologyRoot directive
+                TextFile(name: "GettingStarted.md", utf8Content: """
+                # Getting Started
+                @Metadata {
+                   @TechnologyRoot
+                }
+                Learn how to use MyModule.
+                """),
+                
+                // Another article with @TechnologyRoot directive
+                TextFile(name: "Overview.md", utf8Content: """
+                # Overview
+                @Metadata {
+                   @TechnologyRoot
+                }
+                Overview of the technology.
+                """),
+            ])
+        )
+        
+        // Verify that we emit warnings for @TechnologyRoot directives when symbols are present
+        let symbolsWithRootProblems = context.problems.filter { $0.diagnostic.identifier == "org.swift.docc.TechnologyRootWithSymbols" }
+        XCTAssertEqual(symbolsWithRootProblems.count, 2, "Should emit warnings for both @TechnologyRoot directives when symbols are present")
+        
+        // Verify the warnings are associated with the correct files
+        let problemSources = symbolsWithRootProblems.compactMap { $0.diagnostic.source?.lastPathComponent }.sorted()
+        XCTAssertEqual(problemSources, ["GettingStarted.md", "Overview.md"])
+        
+        // Verify each warning has a solution to remove the TechnologyRoot directive
+        for problem in symbolsWithRootProblems {
+            XCTAssertEqual(problem.possibleSolutions.count, 1)
+            let solution = try XCTUnwrap(problem.possibleSolutions.first)
+            XCTAssertEqual(solution.summary, "Remove the 'TechnologyRoot' directive")
+            XCTAssertEqual(solution.replacements.count, 1)
+        }
+    }
+    
     func testWarnsAboutMultipleMainModules() async throws {
         // Create a bundle with multiple symbol graphs for different modules
         let (_, context) = try await loadBundle(catalog: