Diagnose duplicate representations of @AlternateRepresentation

If an  `@AlternateRepresentation` clashes with already available source languages, this will now be reported as diagnostics.

These diagnostics are performed in the final stage of registering a bundle, during the global analysis of the topic graph, where all nodes are available and all links will have been resolved. This is so that we have all the information we need for detecting duplicates.

The following cases are detected:
- if the symbol the alternate representation is being defined for (the "original" symbol) was already available in one of the languages the counterpart symbol is available in
- if the alternate representations have duplicate source languages in common, i.e. if counterpart1 is available in Objective-C and counterpart2 is **also** available in Objective-C.

Suggestions will be provided depending on context:
- which languages are duplicate
- all the languages the symbol is already available in will be available as part of the diagnostic explanation
- if the `@AlternateRepresentation` directive is a duplicate, a suggestion will be made to remove it, with a suitable replacement
- if the `@AlternateRepresentation` directive is a duplicate, a note pointing to the original directive will be added

Example diagnostics:
```
warning: An alternate representation for Swift already exists
This node is already available in Swift and Objective-C.
SynonymSample.docc/SymbolExtension2.md:4:5: An alternate representation for Swift has already been defined by an @AlternateRepresentation directive.
 --> SynonymSample.docc/SymbolExtension2.md:5:5-5:57
3 | @metadata {
4 |     @AlternateRepresentation(``Synonyms/Synonym-5zxmc``)
5 +     @AlternateRepresentation(``Synonyms/Synonym-5zxmc``)
  |     ╰─suggestion: Remove this alternate representation
6 | }
7 |
```

```
warning: This node already has a representation in Swift
This node is already available in Swift.
 --> SynonymSample.docc/SynonymExtension.md:5:5-5:56
3 | @metadata {
4 |     @AlternateRepresentation(``Synonyms/Synonym-1wqxt``)
5 +     @AlternateRepresentation(``Synonyms/OtherSynonym``)
  |     ╰─suggestion: Replace the counterpart link with a node which isn't available in Swift
6 | }
7 |
```

Author: anferbui

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -2835,6 +2835,9 @@ public class DocumentationContext {
             }
         }
 
+        // Run analysis to determine whether manually configured alternate representations are valid.
+        analyzeAlternateRepresentations()
+        
         // Run global ``TopicGraph`` global analysis.
         analyzeTopicGraph()
     }
@@ -3199,6 +3202,87 @@ extension DocumentationContext {
         }
         diagnosticEngine.emit(problems)
     }
+        
+    func analyzeAlternateRepresentations() {
+        var problems = [Problem]()
+
+        func listSourceLanguages(_ sourceLanguages: Set<SourceLanguage>) -> String {
+            sourceLanguages.sorted(by: { language1, language2 in
+                // Emit Swift first, then alphabetically.
+                switch (language1, language2) {
+                case (.swift, _): return true
+                case (_, .swift): return false
+                default: return language1.id < language2.id
+                }
+            }).map(\.name).list(finalConjunction: .and)
+        }
+        func removeAlternateRepresentationSolution(_ alternateRepresentation: AlternateRepresentation) -> [Solution] {
+            [Solution(
+                summary: "Remove this alternate representation",
+                replacements: alternateRepresentation.originalMarkup.range.map { [Replacement(range: $0, replacement: "")] } ?? [])]
+        }
+
+        for reference in knownPages {
+            guard let entity = try? self.entity(with: reference), let alternateRepresentations = entity.metadata?.alternateRepresentations else { continue }
+            
+            var sourceLanguageToReference: [SourceLanguage: AlternateRepresentation] = [:]
+            for alternateRepresentation in entity.metadata?.alternateRepresentations ?? [] {
+                guard case .resolved(.success(let alternateRepresentationReference)) = alternateRepresentation.reference,
+                      let alternateRepresentationEntity = try? self.entity(with: alternateRepresentationReference) else {
+                    continue
+                }
+                
+                // Check if the documented symbol already has alternate representations from in-source annotations.
+                let duplicateSourceLanguages = alternateRepresentationEntity.availableSourceLanguages.intersection(entity.availableSourceLanguages)
+                if !duplicateSourceLanguages.isEmpty {
+                    problems.append(Problem(
+                        diagnostic: Diagnostic(
+                            source: alternateRepresentation.originalMarkup.range?.source,
+                            severity: .warning,
+                            range: alternateRepresentation.originalMarkup.range,
+                            identifier: "org.swift.docc.AlternateRepresentation.DuplicateLanguageDefinition",
+                            summary: "\(entity.name.plainText.singleQuoted) already has a representation in \(listSourceLanguages(duplicateSourceLanguages))",
+                            explanation: "Symbols can only specify custom alternate language representations for languages that the documented symbol doesn't already have a representation for."
+                        ),
+                        possibleSolutions: [Solution(summary: "Replace this alternate language representation with a symbol which isn't available in \(listSourceLanguages(entity.availableSourceLanguages))", replacements: [])]
+                    ))
+                }
+                
+                let duplicateAlternateLanguages = Set(sourceLanguageToReference.keys).intersection(alternateRepresentationEntity.availableSourceLanguages)
+                if !duplicateAlternateLanguages.isEmpty {
+                    let replacements = alternateRepresentation.originalMarkup.range.flatMap { [Replacement(range: $0, replacement: "")] } ?? []
+                    let notes: [DiagnosticNote] = duplicateAlternateLanguages.compactMap { duplicateAlternateLanguage in
+                        guard let alreadyExistingRepresentation = sourceLanguageToReference[duplicateAlternateLanguage],
+                              let range = alreadyExistingRepresentation.originalMarkup.range,
+                              let source = range.source else {
+                            return nil
+                        }
+                        
+                        return DiagnosticNote(source: source, range: range, message: "This directive already specifies an alternate \(duplicateAlternateLanguage.name) representation.")
+                    }
+                    problems.append(Problem(
+                        diagnostic: Diagnostic(
+                            source: alternateRepresentation.originalMarkup.range?.source,
+                            severity: .warning,
+                            range: alternateRepresentation.originalMarkup.range,
+                            identifier: "org.swift.docc.AlternateRepresentation.DuplicateLanguageDefinition",
+                            summary: "A custom alternate language representation for \(listSourceLanguages(duplicateAlternateLanguages)) has already been specified",
+                            explanation: "Only one custom alternate language representation can be specified per language.",
+                            notes: notes
+                        ),
+                        possibleSolutions: [Solution(summary: "Remove this alternate representation", replacements: replacements)]
+                    ))
+                }
+                
+                // Update mapping from source language to alternate declaration, for diagnostic purposes
+                for alreadySeenLanguage in alternateRepresentationEntity.availableSourceLanguages {
+                    sourceLanguageToReference[alreadySeenLanguage] = alternateRepresentation
+                }
+            }
+        }
+        
+        diagnosticEngine.emit(problems)
+    }
 }
 
 extension GraphCollector.GraphKind {

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -5433,7 +5433,78 @@ let expected = """
         let problem = try XCTUnwrap(context.problems.first)
         XCTAssertEqual(problem.diagnostic.severity, .warning)
         XCTAssertEqual(problem.diagnostic.summary, "Can't resolve 'MissingSymbol'")
-    }    
+    }
+        
+    func testDiagnosesAlternateDeclarations() throws {
+        let (_, context) = try loadBundle(catalog: Folder(
+            name: "unit-test.docc",
+            content: [
+                TextFile(name: "Symbol.md", utf8Content: """
+                # ``Symbol``
+                @Metadata {
+                    @AlternateRepresentation(``CounterpartSymbol``)
+                    @AlternateRepresentation(``OtherCounterpartSymbol``)
+                }
+                A symbol extension file defining an alternate representation which overlaps source languages with another one.
+                """),
+                TextFile(name: "SwiftSymbol.md", utf8Content: """
+                # ``SwiftSymbol``
+                @Metadata {
+                    @AlternateRepresentation(``Symbol``)
+                }
+                A symbol extension file defining an alternate representation which overlaps source languages with the current node.
+                """),
+                JSONFile(
+                    name: "unit-test.swift.symbols.json",
+                    content: makeSymbolGraph(
+                        moduleName: "unit-test",
+                        symbols: [
+                            makeSymbol(id: "symbol-id", kind: .class, pathComponents: ["Symbol"]),
+                            makeSymbol(id: "other-symbol-id", kind: .class, pathComponents: ["SwiftSymbol"]),
+                        ]
+                    )
+                ),
+                JSONFile(
+                    name: "unit-test.occ.symbols.json",
+                    content: makeSymbolGraph(
+                        moduleName: "unit-test",
+                        symbols: [
+                            makeSymbol(id: "counterpart-symbol-id", language: .objectiveC, kind: .class, pathComponents: ["CounterpartSymbol"]),
+                            makeSymbol(id: "other-counterpart-symbol-id", language: .objectiveC, kind: .class, pathComponents: ["OtherCounterpartSymbol"]),
+                        ]
+                    )
+                ),
+            ]
+        ))
+
+        let alternateRepresentationProblems = context.problems.sorted(by: \.diagnostic.summary)
+        XCTAssertEqual(alternateRepresentationProblems.count, 2)
+        
+        // Verify a problem is reported for trying to define an alternate representation for a language the symbol already supports
+        var problem = try XCTUnwrap(alternateRepresentationProblems.first)
+        XCTAssertEqual(problem.diagnostic.severity, .warning)
+        XCTAssertEqual(problem.diagnostic.summary, "'SwiftSymbol' already has a representation in Swift")
+        XCTAssertEqual(problem.diagnostic.explanation, "Symbols can only specify custom alternate language representations for languages that the documented symbol doesn't already have a representation for.")
+        XCTAssertEqual(problem.possibleSolutions.count, 1)
+    
+        // Verify solutions provide context, but no replacements
+        var solution = try XCTUnwrap(problem.possibleSolutions.first)
+        XCTAssertEqual(solution.summary, "Replace this alternate language representation with a symbol which isn't available in Swift")
+        XCTAssertEqual(solution.replacements.count, 0)
+
+        // Verify a problem is reported for having alternate representations with duplicate source languages
+        problem = try XCTUnwrap(alternateRepresentationProblems[1])
+        XCTAssertEqual(problem.diagnostic.severity, .warning)
+        XCTAssertEqual(problem.diagnostic.summary, "A custom alternate language representation for Objective-C has already been specified")
+        XCTAssertEqual(problem.diagnostic.explanation, "Only one custom alternate language representation can be specified per language.")
+        XCTAssertEqual(problem.possibleSolutions.count, 1)
+                
+        // Verify solutions provide context and suggest to remove the duplicate directive
+        solution = try XCTUnwrap(problem.possibleSolutions.first)
+        XCTAssertEqual(solution.summary, "Remove this alternate representation")
+        XCTAssertEqual(solution.replacements.count, 1)
+        XCTAssertEqual(solution.replacements.first?.replacement, "")
+    }
 }
 
 func assertEqualDumps(_ lhs: String, _ rhs: String, file: StaticString = #file, line: UInt = #line) {