Convert symbol graph dictionary structures

Add base support for dictionary and dictionaryKey structures. These
model JSON request/responses for example.

rdar://101407961

Co-Authored-By: Peter Wilson <[email protected]>

Author: franklinsch

Package.resolved

@@ -99,6 +99,7 @@ extension DocumentationCoverageOptions {
         internal static let typeProperty =                KindFilterOptions(rawValue: BitFlagRepresentation.typeProperty.bitMask)
         internal static let typeSubscript =               KindFilterOptions(rawValue: BitFlagRepresentation.typeSubscript.bitMask)
         internal static let globalVariable =              KindFilterOptions(rawValue: BitFlagRepresentation.globalVariable.bitMask)
+        internal static let dictionary =                  KindFilterOptions(rawValue: BitFlagRepresentation.dictionary.bitMask)
 
         /// Mask with all valid/used bit flags set to 1.
         internal static let allSingleBitOptions: [KindFilterOptions] = {
@@ -172,6 +173,7 @@ extension DocumentationCoverageOptions.KindFilterOptions {
         case typeProperty
         case typeSubscript
         case globalVariable
+        case dictionary
 
         /// Parses given `String` to corresponding `BitFlagRepresentation` if possible. Returns `nil` if the given string does not specify a representable value.
         public init?(string: String) {
@@ -225,6 +227,8 @@ extension DocumentationCoverageOptions.KindFilterOptions {
                 self = .typeSubscript
             case .globalVariable: // 20
                 self = .globalVariable
+            case .dictionary: // 21
+                self = .dictionary
             default:
                 return nil
             }
@@ -275,6 +279,8 @@ extension DocumentationCoverageOptions.KindFilterOptions {
             return 1 << 19
             case .globalVariable:
                 return 1 << 20
+            case .dictionary:
+                return 1 << 21
             }
         }
 
@@ -327,8 +333,10 @@ extension DocumentationCoverageOptions.KindFilterOptions {
                 return .typeProperty
             case .typeSubscript: // 19
                 return .typeSubscript
-            case .globalVariable:
+            case .globalVariable: // 20
                 return .globalVariable
+            case .dictionary: // 21
+                return .dictionary
             }
         }
 
@@ -376,6 +384,8 @@ extension DocumentationCoverageOptions.KindFilterOptions {
                 return "type-subscript"
             case .globalVariable: // 20
                 return "global-variable"
+            case .dictionary: // 21
+                return "dictionary"
             }
         }
         /// A  dictionary where keys are all valid argument strings and values are corresponding instances of ``BitFlagRepresentation``.
@@ -421,6 +431,8 @@ extension DocumentationCoverageOptions.KindFilterOptions {
                 "type-subscript": .typeSubscript,
                 // 20
                 "global-variable": .globalVariable,
+                // 21
+                "dictionary": .dictionary,
             ]
 
         }

Sources/SwiftDocC/Coverage/DocumentationCoverageOptions.swift

@@ -302,8 +302,10 @@ extension RenderAttribute {
         case .default(let value): return value
         case .maximum(let value): return value
         case .maximumExclusive(let value): return value
+        case .maximumLength(let value): return value
         case .minimum(let value): return value
         case .minimumExclusive(let value): return value
+        case .minimumLength(let value): return value
         case .allowedValues(let values): return values.joined(separator: " ")
         case .allowedTypes(let values): return values.map { return $0.map { $0.text }.joined() }.joined(separator: " ")
         }

Sources/SwiftDocC/Indexing/RenderSection+TextIndexing.swift

@@ -239,6 +239,7 @@ extension CoverageDataEntry {
             switch documentationNodeKind {
             case .class,
                 .structure,
+                .dictionary,
                 .enumeration,
                 .protocol,
                 .typeAlias,
@@ -277,6 +278,7 @@ extension CoverageDataEntry {
     enum KindSpecificData: Equatable, Codable {
         case `class`(memberStats: [InstanceMemberType: RatioStatistic])
         case structure(memberStats: [InstanceMemberType: RatioStatistic])
+        case dictionary
         case enumeration(memberStats: [InstanceMemberType: RatioStatistic])
         case `protocol`(memberStats: [InstanceMemberType: RatioStatistic])
         case typeAlias
@@ -444,6 +446,7 @@ extension CoverageDataEntry.KindSpecificData {
     internal enum Discriminant: String, Codable {
         case `class`
         case structure
+        case dictionary
         case enumeration
         case `protocol`
         case `operator`
@@ -477,6 +480,7 @@ extension CoverageDataEntry.KindSpecificData {
                 return CoverageDataEntry.KindSpecificData.`operator`(parameterStats:)
             case .class,
                  .`structure`,
+                 .dictionary,
                  .enumeration,
                 .protocol,
                 .typeAlias,
@@ -509,6 +513,7 @@ extension CoverageDataEntry.KindSpecificData {
                 return CoverageDataEntry.KindSpecificData.class(memberStats:)
             case .instanceMethod,
                  .initializer,
+                 .dictionary,
                 .typeAlias,
                 .instanceProperty,
                 .enumerationCase,
@@ -533,6 +538,8 @@ extension CoverageDataEntry.KindSpecificData {
             return .class
         case .structure:
             return .`structure`
+        case .dictionary:
+            return .dictionary
         case .enumeration:
             return .enumeration
         case .protocol:
@@ -625,6 +632,8 @@ extension CoverageDataEntry.KindSpecificData {
             )
             self = try discriminant.associatedMemberStatisticsInitializer()(associatedValue)
 
+        case .dictionary:
+            self = .dictionary
         case .typeAlias:
             self = .typeAlias
         case .instanceProperty:
@@ -657,6 +666,7 @@ extension CoverageDataEntry.KindSpecificData {
             try container.encode(stats, forKey: .associatedValue)
 
         case .typeAlias,
+             .dictionary,
              .instanceProperty,
              .variable,
              .framework,

Sources/SwiftDocC/Infrastructure/CoverageDataEntry.swift

@@ -1446,6 +1446,8 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             for (selector, relationships) in combinedRelationships {
                 // Build relationships in the completed graph
                 buildRelationships(relationships, selector: selector, bundle: bundle, engine: diagnosticEngine)
+                // Merge dictionary keys into target dictionaries
+                populateDictionaryKeys(from: relationships, selector: selector)
             }
 
             // Index references
@@ -1535,6 +1537,42 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         }
     }
 
+    /// Identifies all the dictionary keys and records them in the appropriate target dictionaries.
+    private func populateDictionaryKeys(
+        from relationships: Set<SymbolGraph.Relationship>,
+        selector: UnifiedSymbolGraph.Selector
+    ) {
+        var keysByTarget = [String:[DictionaryKey]]()
+        
+        for edge in relationships {
+            if edge.kind == .memberOf || edge.kind == .optionalMemberOf {
+                if let source = symbolIndex[edge.source], let target = symbolIndex[edge.target], let keySymbol = source.symbol,
+                        source.kind == .dictionaryKey && target.kind == .dictionary {
+                    let dictionaryKey = DictionaryKey(name: keySymbol.title, contents: [], symbol: keySymbol, required: (edge.kind == .memberOf))
+                    if keysByTarget[edge.target] == nil {
+                        keysByTarget[edge.target] = [dictionaryKey]
+                    } else {
+                        keysByTarget[edge.target]?.append(dictionaryKey)
+                    }
+                }
+            }
+        }
+        
+        // Merge in all the dictionary keys for each target into their section variants.
+        keysByTarget.forEach { targetIdentifier, keys in
+            let target = symbolIndex[targetIdentifier]
+            if let semantic = target?.semantic as? Symbol {
+                let keys = keys.sorted { $0.name < $1.name }
+                let trait = DocumentationDataVariantsTrait(for: selector)
+                if semantic.dictionaryKeysSectionVariants[trait] == nil {
+                    semantic.dictionaryKeysSectionVariants[trait] = DictionaryKeysSection(dictionaryKeys: keys)
+                } else {
+                    semantic.dictionaryKeysSectionVariants[trait]?.mergeDictionaryKeys(keys)
+                }
+            }
+        }
+    }
+    
     /// Look up and add symbols that are _referenced_ in the symbol graph but don't exist in the symbol graph, using an `externalSymbolResolver` (if not `nil`).
     func resolveExternalSymbols(
         in symbols: [String: UnifiedSymbolGraph.Symbol],

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -13,6 +13,7 @@ import SymbolKit
 extension SymbolGraph.Symbol.KindIdentifier {
     /// The kinds of symbols that should not generate pages in the documentation hierarchy.
     static let noPageKinds: [SymbolGraph.Symbol.KindIdentifier] = [
+        .dictionaryKey,
         .module,
         .snippet,
         .snippetGroup

Sources/SwiftDocC/Infrastructure/Extensions/KindIdentifier+Curation.swift

@@ -52,6 +52,10 @@ extension ExternalSymbolResolver {
             symbolKind = .protocol
         case .structure:
             symbolKind = .struct
+        case .dictionary:
+            symbolKind = .dictionary
+        case .dictionaryKey:
+            symbolKind = .dictionaryKey
         case .instanceSubscript:
             symbolKind = .subscript
         case .typeMethod:

Sources/SwiftDocC/Infrastructure/External Data/ExternalSymbolResolver+SymbolKind.swift

@@ -982,6 +982,7 @@ extension OutOfProcessReferenceResolver {
             seeAlsoVariants: .empty,
             returnsSectionVariants: .empty,
             parametersSectionVariants: .empty,
+            dictionaryKeysSectionVariants: .empty,
             redirectsVariants: .empty
         )
     }

Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift

@@ -188,7 +188,7 @@ enum GeneratedDocumentationTopics {
             semantic: Article(markup: nil, metadata: nil, redirects: nil, options: [:])
         )
 
-        let collectionTaskGroups = try AutomaticCuration.topics(for: temporaryCollectionNode, withTrait: nil, context: context)
+        let collectionTaskGroups = try AutomaticCuration.topics(for: temporaryCollectionNode, withTraits: [], context: context)
             .map { taskGroup in
                 AutomaticTaskGroupSection(
                     // Force-unwrapping the title since automatically-generated task groups always have a title.

Sources/SwiftDocC/Infrastructure/Symbol Graph/GeneratedDocumentationTopics.swift

@@ -47,7 +47,7 @@ public struct AutomaticCuration {
     /// - Returns: An array of title and references list tuples.
     static func topics(
         for node: DocumentationNode,
-        withTrait variantsTrait: DocumentationDataVariantsTrait?,
+        withTraits variantsTraits: Set<DocumentationDataVariantsTrait>,
         context: DocumentationContext
     ) throws -> [TaskGroup] {
         // Get any default implementation relationships for this symbol
@@ -87,8 +87,12 @@ public struct AutomaticCuration {
                 //
                 // Otherwise, we'll fall back to the first kind variant.
                 let childSymbolKindIdentifier: SymbolGraph.Symbol.KindIdentifier?
-                if let variantsTrait = variantsTrait {
-                    childSymbolKindIdentifier = childSymbol.kindVariants[variantsTrait]?.identifier
+                if variantsTraits.count > 0 {
+                    if let matchingTrait = variantsTraits.first(where: { childSymbol.kindVariants[$0] != nil }) {
+                        childSymbolKindIdentifier = childSymbol.kindVariants[matchingTrait]?.identifier
+                    } else {
+                        childSymbolKindIdentifier = nil
+                    }
                 } else {
                     childSymbolKindIdentifier = childSymbol.kindVariants.firstValue?.identifier
                 }
@@ -117,7 +121,7 @@ public struct AutomaticCuration {
     ///   `nil` if the method can't find any relevant links to automatically generate a See Also content.
     static func seeAlso(
         for node: DocumentationNode,
-        withTrait variantsTrait: DocumentationDataVariantsTrait,
+        withTraits variantsTraits: Set<DocumentationDataVariantsTrait>,
         context: DocumentationContext,
         bundle: DocumentationBundle,
         renderContext: RenderContext?,
@@ -142,11 +146,11 @@ public struct AutomaticCuration {
                 // Don't include the current node.
                 .filter { $0 != node.reference }
 
-                // Filter out nodes that aren't available in the given trait.
+                // Filter out nodes that aren't available in any of the given traits.
                 .filter { reference in
-                    try context.entity(with: reference)
+                    try !context.entity(with: reference)
                         .availableVariantTraits
-                        .contains(variantsTrait)
+                        .isDisjoint(with: variantsTraits)
                 }
         }
 
@@ -192,6 +196,7 @@ extension AutomaticCuration {
             case .`deinit`: return "Deinitializers"
             case .`enum`: return "Enumerations"
             case .`case`: return "Enumeration Cases"
+            case .dictionary: return "Dictionaries"
             case .extension: return "Extensions"
             case .`func`: return "Functions"
             case .`operator`: return "Operators"
@@ -227,6 +232,7 @@ extension AutomaticCuration {
         .`class`,
         .`protocol`,
         .`struct`,
+        .`dictionary`,
         .`var`,
         .`func`,
         .`operator`,