[6.1] Add @AlternateRepresentation directive (#1155)

Fixes rdar://109417745.

* Add `@AlternateRepresentation` directive

Adds a new child directive to `@Metadata` which can be used in a symbol extension file by specifying the link to another symbol:
```swift
@metadata {
  @AlternateRepresentation(``MyClass/property``)
}
```

External links are also supported, as long as they're quoted:
```swift
@metadata {
  @AlternateRepresentation("doc://com.example/documentation/MyClass/property")
}
```

The intent of this directive is to define an alternate language representation for the current symbol, such that both symbols are considered to be alternate representations of the same symbol.

Ideally two symbols which are equivalent would have the same USR and be resolved as the same symbol by the compiler, but this is not always the case. For the cases in which it is not feasible to change the source code to have them as one symbol, the `@AlternateRepresentation` directive can be used to manually link them as variants of each other.

Discussion:
----------

A mutable topic reference type was chosen as the type for parsing&storing the link
so that it can be parsed as an unresolved link at the directive parsing stage,
and then later be updated to a resolved link at a later stage when the documentation context is resolving all links.

A parsing failure diagnostic is returned if the link is invalid in any way:
```
AlternateRepresentation expects an argument for an unnamed parameter that's convertible to 'TopicReference'
 --> SynonymSample.docc/Symbol.md:4:31-4:37
2 |
3 | @metadata {
4 +     @AlternateRepresentation("doc://")
5 | }
6 |

```

This commit adds the directive itself, but doesn't hook it up to other parts of SwiftDocC. Subsequent commits will add:
- link resolution
- rendering logic

Alternatives considered:
-----------------------
Considered other names such as `@Synonym`, `@Counterpart`, `@AlternativeDeclaration` and `@VariantOf`.
In the end disqualified these as being confusing, and chose `@AlternateRepresentation` for being the one which strikes the best balance between readable and closeness to the technical term for this concept.

* Resolve topic references in `@AlternateRepresentation`

Adds logic in `DocumentationContext` which will resolve the references inside the alternate representation directive.

The same logic is used as for resolving all other links.
This is done outside the usual ReferenceResolver visit of the semantic object, because `Symbol` objects don't have access to the node metadata, where the unresolved link resides.

If the link cannot be resolved, the usual diagnostic is emitted:
```
warning: 'MissingSymbol' doesn't exist at '/Synonyms'
 --> SynonymSample.docc/SymbolExtension2.md:4:19-4:32
2 |
3 | @metadata {
4 +     @AlternateRepresentation(``Synonyms/MissingSymbol``)
5 | }
```

* 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 |
```

* Emit diagnostics for non-symbol pages

The `@AlternateRepresentation` directive is not expected for non-symbol pages, and we now emit diagnostics for this case.

For example, if an `@AlternateDeclaration` directive is added to an article, the resulting diagnostic will be:
```
warning: Custom alternate representations are not supported for page kind 'Article'
Alternate representations are only supported for symbols.
 --> ./SynonymSample.docc/Article.md:4:5-4:57
2 |
3 | @metadata {
4 +     @AlternateRepresentation(``Synonyms/Synonym-5zxmc``)
  |     ╰─suggestion: Remove this alternate representation
5 | }
```

And if a custom alternate declaration to an article is specified, the resulting dia
gnostic will be:
```
warning: Page kind 'Article' is not allowed as a custom alternate language representation
Symbols can only specify other symbols as custom language representations.
 --> ./SynonymSample.docc/Synonym-1wqxt.md:5:5-5:44
3 | @metadata {
4 |     @AlternateRepresentation(``Synonyms/Synonym-5zxmc``)
5 +     @AlternateRepresentation("doc:Article")
  |     ╰─suggestion: Remove this alternate representation
6 | }
```

* Render alternate representations as node variants

When rendering the variants of a node, use the topic references from the `@AlternateRepresentation` directives to populate more variants.

There is no need to report diagnostics as they would have been reported during bundle registration.
Link resolution would have already been performed at that point.

Unresolved topic references are ignored, but all resolved references are added as variants.
If there are multiple symbols per variant, Swift-DocC-Render prefers the first one that was added, which will always be the current node's symbol.

There should be no breakage and change of behaviour for anyone not using `@AlternateRepresentation`, and the current symbol's variants will always be preferred over any other.

* Add `AlternateRepresentation` to Metadata article (#1128)

The metadata article curates a list of its child directives, with relevant topic titles.

This adds `AlternateRepresentation` to that list, in the same section as `SupportedLanguage` as they both deal with language representations.

Author: anferbui

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -618,6 +618,19 @@ public class DocumentationContext {
                 resolver.visit(documentationNode.semantic)
             }
 
+            // Also resolve the node's alternate representations. This isn't part of the node's 'semantic' value (resolved above).
+            if let alternateRepresentations = documentationNode.metadata?.alternateRepresentations {
+                for alternateRepresentation in alternateRepresentations {
+                    let resolutionResult = resolver.resolve(
+                        alternateRepresentation.reference,
+                        in: bundle.rootReference,
+                        range: alternateRepresentation.originalMarkup.range,
+                        severity: .warning
+                    )
+                    alternateRepresentation.reference = .resolved(resolutionResult)
+                }
+            }
+
             let problems: [Problem]
             if documentationNode.semantic is Article {
                 // Diagnostics for articles have correct source ranges and don't need to be modified.
@@ -2822,6 +2835,9 @@ public class DocumentationContext {
             }
         }
 
+        // Run analysis to determine whether manually configured alternate representations are valid.
+        analyzeAlternateRepresentations()
+        
         // Run global ``TopicGraph`` global analysis.
         analyzeTopicGraph()
     }
@@ -3186,6 +3202,118 @@ 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 alternateRepresentations {
+                // Check if the entity is not a symbol, as only symbols are allowed to specify custom alternate representations
+                guard entity.symbol != nil else {
+                    problems.append(Problem(
+                        diagnostic: Diagnostic(
+                            source: alternateRepresentation.originalMarkup.range?.source,
+                            severity: .warning,
+                            range: alternateRepresentation.originalMarkup.range,
+                            identifier: "org.swift.docc.AlternateRepresentation.UnsupportedPageKind",
+                            summary: "Custom alternate representations are not supported for page kind \(entity.kind.name.singleQuoted)",
+                            explanation: "Alternate representations are only supported for symbols."
+                        ),
+                        possibleSolutions: removeAlternateRepresentationSolution(alternateRepresentation)
+                    ))
+                    continue
+                }
+
+                guard case .resolved(.success(let alternateRepresentationReference)) = alternateRepresentation.reference,
+                      let alternateRepresentationEntity = try? self.entity(with: alternateRepresentationReference) else {
+                    continue
+                }
+                
+                // Check if the resolved entity is not a symbol, as only symbols are allowed as custom alternate representations
+                guard alternateRepresentationEntity.symbol != nil else {
+                    problems.append(Problem(
+                        diagnostic: Diagnostic(
+                            source: alternateRepresentation.originalMarkup.range?.source,
+                            severity: .warning,
+                            range: alternateRepresentation.originalMarkup.range,
+                            identifier: "org.swift.docc.AlternateRepresentation.UnsupportedPageKind",
+                            summary: "Page kind \(alternateRepresentationEntity.kind.name.singleQuoted) is not allowed as a custom alternate language representation",
+                            explanation: "Symbols can only specify other symbols as custom language representations."
+                        ),
+                        possibleSolutions: removeAlternateRepresentationSolution(alternateRepresentation)
+                    ))
+                    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 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: removeAlternateRepresentationSolution(alternateRepresentation)
+                    ))
+                }
+                
+                // 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 {

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -1852,23 +1852,45 @@ public struct RenderNodeTranslator: SemanticVisitor {
     private func variants(for documentationNode: DocumentationNode) -> [RenderNode.Variant] {
         let generator = PresentationURLGenerator(context: context, baseURL: bundle.baseURL)
 
-        return documentationNode.availableSourceLanguages
-            .sorted(by: { language1, language2 in
+        var allVariants: [SourceLanguage: ResolvedTopicReference] = documentationNode.availableSourceLanguages.reduce(into: [:]) { partialResult, language in
+            partialResult[language] = identifier
+        }
+        
+        // Apply alternate representations
+        if let alternateRepresentations = documentationNode.metadata?.alternateRepresentations {
+            for alternateRepresentation in alternateRepresentations {
+                // Only alternate representations which were able to be resolved to a reference should be included as an alternate representation.
+                // Unresolved alternate representations can be ignored, as they would have been reported during link resolution.
+                guard case .resolved(.success(let alternateRepresentationReference)) = alternateRepresentation.reference else {
+                    continue
+                }
+
+                // Add the language representations of the alternate symbol as additional variants for the current symbol.
+                // Symbols can only specify custom alternate language representations for languages that the documented symbol doesn't already have a representation for.
+                // If the current symbol and its custom alternate representation share language representations, the custom language representation is ignored.
+                allVariants.merge(
+                    alternateRepresentationReference.sourceLanguages.map { ($0, alternateRepresentationReference) }
+                ) { existing, _ in existing }
+            }
+        }
+        
+        return allVariants
+            .sorted(by: { variant1, variant2 in
                 // Emit Swift first, then alphabetically.
-                switch (language1, language2) {
+                switch (variant1.key, variant2.key) {
                 case (.swift, _): return true
                 case (_, .swift): return false
-                default: return language1.id < language2.id
-                }
-            })
-            .map { sourceLanguage in
-                RenderNode.Variant(
-                    traits: [.interfaceLanguage(sourceLanguage.id)],
-                    paths: [
-                        generator.presentationURLForReference(identifier).path
-                    ]
-                )
+                default: return variant1.key.id < variant2.key.id
             }
+        })
+        .map { sourceLanguage, reference in
+            RenderNode.Variant(
+                traits: [.interfaceLanguage(sourceLanguage.id)],
+                paths: [
+                    generator.presentationURLForReference(reference).path
+                ]
+            )
+        }
     }
 
     private mutating func convertFragments(_ fragments: [SymbolGraph.Symbol.DeclarationFragments.Fragment]) -> [DeclarationRenderSection.Token] {

Sources/SwiftDocC/Semantics/Metadata/AlternateRepresentation.swift

@@ -0,0 +1,89 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import Markdown
+
+
+/// A directive that configures an alternate language representation of a symbol.
+///
+/// An API that can be called from more than one source language has more than one language representation.
+///
+/// Whenever possible, prefer to define alternative language representations for a symbol by using in-source annotations
+/// such as the `@objc` and `@_objcImplementation` attributes in Swift,
+/// or the `NS_SWIFT_NAME` macro in Objective C.
+///
+/// If your source language doesn’t have a mechanism for specifying alternate representations or if your intended alternate representation isn't compatible with those attributes,
+/// you can use the `@AlternateRepresentation` directive to specify another symbol that should be considered an alternate representation of the documented symbol.
+///
+/// ```md
+/// @Metadata {
+///     @AlternateRepresentation(MyApp/MyClass/property)
+/// }
+/// ```
+/// If you prefer, you can wrap the symbol link in a set of double backticks (\`\`), or use any other supported syntax for linking to symbols.
+/// For more information about linking to symbols, see <doc:linking-to-symbols-and-other-content>.
+///
+/// This provides a hint to the renderer as to the alternate language representations for the current symbol.
+/// The renderer may use this hint to provide a link to these alternate symbols.
+/// For example, Swift-DocC-Render shows a toggle between supported languages, where switching to a different language representation will redirect to the documentation for the configured alternate symbol.
+///
+/// ### Special considerations
+///
+/// Links containing a colon (`:`) must be wrapped in quotes:
+/// ```md
+/// @Metadata {
+///     @AlternateRepresentation("doc://com.example/documentation/MyClass/property")
+///     @AlternateRepresentation("MyClass/myFunc(_:_:)")
+/// }
+/// ```
+///
+/// The `@AlternateRepresentation` directive only specifies an alternate language representation in one direction.
+/// To define a two-way relationship, add an `@AlternateRepresentation` directive, linking to this symbol, to the other symbol as well.
+///
+/// You can only configure custom alternate language representations for languages that the documented symbol doesn't already have a language representation for,
+/// either from in-source annotations or from a previous `@AlternateRepresentation` directive.
+public final class AlternateRepresentation: Semantic, AutomaticDirectiveConvertible {
+    public static let introducedVersion = "6.1"
+            
+    // Directive parameter definition
+
+    /// A link to another symbol that should be considered an alternate language representation of the current symbol.
+    ///
+    /// If you prefer, you can wrap the symbol link in a set of double backticks (\`\`).
+    @DirectiveArgumentWrapped(
+        name: .unnamed,
+        parseArgument: { _, argumentValue in
+            // Allow authoring of links with leading and trailing "``"s
+            var argumentValue = argumentValue
+            if argumentValue.hasPrefix("``"), argumentValue.hasSuffix("``") {
+                argumentValue = String(argumentValue.dropFirst(2).dropLast(2))
+            }
+            guard let url = ValidatedURL(parsingAuthoredLink: argumentValue), !url.components.path.isEmpty else {
+                return nil
+            }
+            return .unresolved(UnresolvedTopicReference(topicURL: url))
+        }
+    )
+    public internal(set) var reference: TopicReference
+
+    static var keyPaths: [String : AnyKeyPath] = [
+        "reference" : \AlternateRepresentation._reference
+    ]
+
+    // Boiler-plate required by conformance to AutomaticDirectiveConvertible
+    
+    public var originalMarkup: Markdown.BlockDirective
+
+    @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible")
+    init(originalMarkup: Markdown.BlockDirective) {
+        self.originalMarkup = originalMarkup
+    }
+}

Sources/SwiftDocC/Semantics/Metadata/Metadata.swift

@@ -19,6 +19,7 @@ import Markdown
 /// 
 /// ### Child Directives
 ///
+/// - ``AlternateRepresentation``
 /// - ``DocumentationExtension``
 /// - ``TechnologyRoot``
 /// - ``DisplayName``
@@ -77,6 +78,9 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
 
     @ChildDirective
     var redirects: [Redirect]? = nil
+    
+    @ChildDirective(requirements: .zeroOrMore)
+    var alternateRepresentations: [AlternateRepresentation]
 
     static var keyPaths: [String : AnyKeyPath] = [
         "documentationOptions"  : \Metadata._documentationOptions,
@@ -91,6 +95,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
         "_pageColor"            : \Metadata.__pageColor,
         "titleHeading"          : \Metadata._titleHeading,
         "redirects"             : \Metadata._redirects,
+        "alternateRepresentations"  : \Metadata._alternateRepresentations,
     ]
 
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
@@ -100,7 +105,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
 
     func validate(source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> Bool {
         // Check that something is configured in the metadata block
-        if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil && pageColor == nil && titleHeading == nil && redirects == nil {
+        if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil && pageColor == nil && titleHeading == nil && redirects == nil && alternateRepresentations.isEmpty {
             let diagnostic = Diagnostic(
                 source: source,
                 severity: .information,

Sources/SwiftDocC/Utility/MarkupExtensions/BlockDirectiveExtensions.swift

@@ -41,6 +41,7 @@ extension BlockDirective {
         Metadata.directiveName,
         Metadata.Availability.directiveName,
         Metadata.PageKind.directiveName,
+        AlternateRepresentation.directiveName,
         MultipleChoice.directiveName,
         Options.directiveName,
         PageColor.directiveName,