add the ability to set a subset of feature flags from Info.plist (#891)

rdar://126305435

Author: QuietMisdreavus

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -2012,7 +2012,36 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
      */
     private func register(_ bundle: DocumentationBundle) throws {
         try shouldContinueRegistration()
-        
+
+        let currentFeatureFlags: FeatureFlags?
+        if let bundleFlags = bundle.info.featureFlags {
+            currentFeatureFlags = FeatureFlags.current
+            FeatureFlags.current.loadFlagsFromBundle(bundleFlags)
+
+            for unknownFeatureFlag in bundleFlags.unknownFeatureFlags {
+                let suggestions = NearMiss.bestMatches(
+                    for: DocumentationBundle.Info.BundleFeatureFlags.CodingKeys.allCases.map({ $0.stringValue }),
+                    against: unknownFeatureFlag)
+                var summary: String = "Unknown feature flag in Info.plist: \(unknownFeatureFlag.singleQuoted)"
+                if !suggestions.isEmpty {
+                    summary += ". Possible suggestions: \(suggestions.map(\.singleQuoted).joined(separator: ", "))"
+                }
+                diagnosticEngine.emit(.init(diagnostic:
+                        .init(
+                            severity: .warning,
+                            identifier: "org.swift.docc.UnknownBundleFeatureFlag",
+                            summary: summary
+                        )))
+            }
+        } else {
+            currentFeatureFlags = nil
+        }
+        defer {
+            if let currentFeatureFlags = currentFeatureFlags {
+                FeatureFlags.current = currentFeatureFlags
+            }
+        }
+
         // Note: Each bundle is registered and processed separately.
         // Documents and symbols may both reference each other so the bundle is registered in 4 steps
 

Sources/SwiftDocC/Infrastructure/Workspace/DocumentationBundle+Info.swift

@@ -32,7 +32,10 @@ extension DocumentationBundle {
 
         /// The default kind for the various modules in the bundle.
         public var defaultModuleKind: String?
-        
+
+        /// The parsed feature flags that were set for this bundle.
+        internal var featureFlags: BundleFeatureFlags?
+
         /// The keys that must be present in an Info.plist file in order for doc compilation to proceed.
         static let requiredKeys: Set<CodingKeys> = [.displayName, .identifier]
 
@@ -43,7 +46,8 @@ extension DocumentationBundle {
             case defaultCodeListingLanguage = "CDDefaultCodeListingLanguage"
             case defaultAvailability = "CDAppleDefaultAvailability"
             case defaultModuleKind = "CDDefaultModuleKind"
-            
+            case featureFlags = "CDExperimentalFeatureFlags"
+
             var argumentName: String? {
                 switch self {
                 case .displayName:
@@ -56,7 +60,7 @@ extension DocumentationBundle {
                     return "--default-code-listing-language"
                 case .defaultModuleKind:
                     return "--fallback-default-module-kind"
-                case .defaultAvailability:
+                case .defaultAvailability, .featureFlags:
                     return nil
                 }
             }
@@ -231,6 +235,7 @@ extension DocumentationBundle {
             self.defaultCodeListingLanguage = try decodeOrFallbackIfPresent(String.self, with: .defaultCodeListingLanguage)
             self.defaultModuleKind = try decodeOrFallbackIfPresent(String.self, with: .defaultModuleKind)
             self.defaultAvailability = try decodeOrFallbackIfPresent(DefaultAvailability.self, with: .defaultAvailability)
+            self.featureFlags = try decodeOrFallbackIfPresent(BundleFeatureFlags.self, with: .featureFlags)
         }
 
         init(
@@ -239,14 +244,16 @@ extension DocumentationBundle {
             version: String? = nil,
             defaultCodeListingLanguage: String? = nil,
             defaultModuleKind: String? = nil,
-            defaultAvailability: DefaultAvailability? = nil
+            defaultAvailability: DefaultAvailability? = nil,
+            featureFlags: BundleFeatureFlags? = nil
         ) {
             self.displayName = displayName
             self.identifier = identifier
             self.version = version
             self.defaultCodeListingLanguage = defaultCodeListingLanguage
             self.defaultModuleKind = defaultModuleKind
             self.defaultAvailability = defaultAvailability
+            self.featureFlags = featureFlags
         }
     }
 }
@@ -295,6 +302,8 @@ extension BundleDiscoveryOptions {
                 value = fallbackDefaultAvailability
             case .defaultModuleKind:
                 value = fallbackDefaultModuleKind
+            case .featureFlags:
+                value = nil
             }
 
             guard let unwrappedValue = value else {

Sources/SwiftDocC/Infrastructure/Workspace/FeatureFlags+Info.swift

@@ -0,0 +1,84 @@
+/*
+ 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
+
+extension DocumentationBundle.Info {
+    /// A collection of feature flags that can be enabled from a bundle's Info.plist.
+    ///
+    /// This is a subset of flags from ``FeatureFlags`` that can influence how a documentation
+    /// bundle is written, and so can be considered a property of the documentation itself, rather
+    /// than as an experimental behavior that can be enabled for one-off builds.
+    ///
+    /// ```xml
+    /// <key>CDExperimentalFeatureFlags</key>
+    /// <dict>
+    ///     <key>ExperimentalOverloadedSymbolPresentation</key>
+    ///     <true/>
+    /// </dict>
+    /// ```
+    internal struct BundleFeatureFlags: Codable, Equatable {
+        // FIXME: Automatically expose all the feature flags from the global FeatureFlags struct
+
+        /// Whether or not experimental support for combining overloaded symbol pages is enabled.
+        ///
+        /// This feature flag corresponds to ``FeatureFlags/isExperimentalOverloadedSymbolPresentationEnabled``.
+        public var experimentalOverloadedSymbolPresentation: Bool?
+
+        public init(experimentalOverloadedSymbolPresentation: Bool? = nil) {
+            self.experimentalOverloadedSymbolPresentation = experimentalOverloadedSymbolPresentation
+            self.unknownFeatureFlags = []
+        }
+
+        /// A list of decoded feature flag keys that didn't match a known feature flag.
+        public let unknownFeatureFlags: [String]
+
+        enum CodingKeys: String, CodingKey, CaseIterable {
+            case experimentalOverloadedSymbolPresentation = "ExperimentalOverloadedSymbolPresentation"
+        }
+
+        struct AnyCodingKeys: CodingKey {
+            var stringValue: String
+
+            init?(stringValue: String) {
+                self.stringValue = stringValue
+            }
+
+            var intValue: Int? { nil }
+            init?(intValue: Int) {
+                return nil
+            }
+        }
+
+        public init(from decoder: any Decoder) throws {
+            let values = try decoder.container(keyedBy: AnyCodingKeys.self)
+            var unknownFeatureFlags: [String] = []
+
+            for flagName in values.allKeys {
+                if let codingKey = CodingKeys(stringValue: flagName.stringValue) {
+                    switch codingKey {
+                    case .experimentalOverloadedSymbolPresentation:
+                        self.experimentalOverloadedSymbolPresentation = try values.decode(Bool.self, forKey: flagName)
+                    }
+                } else {
+                    unknownFeatureFlags.append(flagName.stringValue)
+                }
+            }
+
+            self.unknownFeatureFlags = unknownFeatureFlags
+        }
+
+        public func encode(to encoder: any Encoder) throws {
+            var container = encoder.container(keyedBy: CodingKeys.self)
+
+            try container.encode(experimentalOverloadedSymbolPresentation, forKey: .experimentalOverloadedSymbolPresentation)
+        }
+    }
+}

Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC.md

@@ -54,5 +54,6 @@ Converting in-memory documentation into rendering nodes and persisting them on d
 ### Development
 
 - <doc:Features>
+- <doc:AddingFeatureFlags>
 
-<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/SwiftDocC/SwiftDocC.docc/SwiftDocC/AddingFeatureFlags.md

@@ -0,0 +1,40 @@
+# Adding Feature Flags
+
+Develop experimental features by adding feature flags.
+
+## Overview
+
+Make new features in Swift-DocC optional during active development by creating a command-line flag that
+enables the new behavior. Then set the new flag in the ``FeatureFlags``' ``FeatureFlags/current`` instance,
+making it available for the rest of the compilation process.
+
+### The FeatureFlags structure
+
+Feature flags are defined in the ``FeatureFlags`` structure. This type has a static
+``FeatureFlags/current`` property that contains a global instance of the flags that can be accessed
+throughout the compiler. When adding a flag property to this struct, give it a reasonable default
+value so that the default initializer can be used.
+
+### Feature flags on the command line
+
+Command-line feature flags live in the `Docc.Convert.FeatureFlagOptions` in `SwiftDocCUtilities`.
+This type implements the `ParsableArguments` protocol from Swift Argument Parser to create an option
+group for the `convert` and `preview` commands.
+
+These options are then handled in `ConvertAction.init(fromConvertCommand:)`, still in
+`SwiftDocCUtilities`, where they are written into the global feature flags ``FeatureFlags/current``
+instance, which can then be used during the compilation process.
+
+### Feature flags in Info.plist
+
+A subset of feature flags can affect how a documentation bundle is authored. For example, the
+experimental overloaded symbol presentation can affect how a bundle curates its symbols due to the 
+creation of overload group pages. These flags should also be added to the
+``DocumentationBundle/Info/BundleFeatureFlags`` type, so that they can be parsed out of a bundle's
+Info.plist.
+
+Feature flags that are loaded from an Info.plist file are saved into the global feature flags while
+the bundle is being registered. To ensure that your new feature flag is properly loaded, update the
+``FeatureFlags/loadFlagsFromBundle(_:)`` method to load your new field into the global flags.
+
+<!-- Copyright (c) 2024 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/SwiftDocC/Utility/FeatureFlags.swift

@@ -46,4 +46,11 @@ public struct FeatureFlags: Codable {
         additionalFlags: [String : Bool] = [:]
     ) {
     }
+
+    /// Set feature flags that were loaded from a bundle's Info.plist.
+    internal mutating func loadFlagsFromBundle(_ bundleFlags: DocumentationBundle.Info.BundleFeatureFlags) {
+        if let overloadsPresentation = bundleFlags.experimentalOverloadedSymbolPresentation {
+            self.isExperimentalOverloadedSymbolPresentationEnabled = overloadsPresentation
+        }
+    }
 }

Tests/SwiftDocCTests/Infrastructure/DocumentationBundleInfoTests.swift

@@ -414,4 +414,32 @@ class DocumentationBundleInfoTests: XCTestCase {
             )
         )
     }
+
+    func testFeatureFlags() throws {
+        let infoPlistWithFeatureFlags = """
+        <plist version="1.0">
+        <dict>
+            <key>CFBundleDisplayName</key>
+            <string>Info Plist Display Name</string>
+            <key>CFBundleIdentifier</key>
+            <string>com.info.Plist</string>
+            <key>CFBundleVersion</key>
+            <string>1.0.0</string>
+            <key>CDExperimentalFeatureFlags</key>
+            <dict>
+                <key>ExperimentalOverloadedSymbolPresentation</key>
+                <true/>
+            </dict>
+        </dict>
+        </plist>
+        """
+
+        let infoPlistWithFeatureFlagsData = Data(infoPlistWithFeatureFlags.utf8)
+        let info = try DocumentationBundle.Info(
+            from: infoPlistWithFeatureFlagsData,
+            bundleDiscoveryOptions: nil)
+
+        let featureFlags = try XCTUnwrap(info.featureFlags)
+        XCTAssertTrue(try XCTUnwrap(featureFlags.experimentalOverloadedSymbolPresentation))
+    }
 }

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -4613,7 +4613,54 @@ let expected = """
             }
         }
     }
-    
+
+    func testContextRecognizesOverloadsFromPlistFlag() throws {
+        let overloadableKindIDs = SymbolGraph.Symbol.KindIdentifier.allCases.filter { $0.isOverloadableKind }
+        // Generate a 4 symbols with the same name for every overloadable symbol kind
+        let symbols: [SymbolGraph.Symbol] = overloadableKindIDs.flatMap { [
+            makeSymbol(identifier: "first-\($0.identifier)-id", kind: $0),
+            makeSymbol(identifier: "second-\($0.identifier)-id", kind: $0),
+            makeSymbol(identifier: "third-\($0.identifier)-id", kind: $0),
+            makeSymbol(identifier: "fourth-\($0.identifier)-id", kind: $0),
+        ] }
+
+        let tempURL = try createTempFolder(content: [
+            Folder(name: "unit-test.docc", content: [
+                JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
+                    moduleName: "ModuleName",
+                    symbols: symbols
+                )),
+                DataFile(name: "Info.plist", data: Data("""
+                <plist version="1.0">
+                <dict>
+                    <key>CDExperimentalFeatureFlags</key>
+                    <dict>
+                        <key>ExperimentalOverloadedSymbolPresentation</key>
+                        <true/>
+                    </dict>
+                </dict>
+                </plist>
+                """.utf8))
+            ])
+        ])
+        let (_, bundle, context) = try loadBundle(from: tempURL)
+        let moduleReference = ResolvedTopicReference(bundleIdentifier: bundle.identifier, path: "/documentation/ModuleName", sourceLanguage: .swift)
+
+        for kindID in overloadableKindIDs {
+            switch context.resolve(.unresolved(.init(topicURL: .init(symbolPath: "SymbolName-\(kindID.identifier)"))), in: moduleReference, fromSymbolLink: true) {
+            case let .failure(_, errorMessage):
+                XCTFail("Could not resolve overload group page for \(kindID.identifier). Error message: \(errorMessage)")
+                continue
+            case let .success(overloadGroupReference):
+                let overloadGroupNode = try context.entity(with: overloadGroupReference)
+                let overloadGroupSymbol = try XCTUnwrap(overloadGroupNode.semantic as? Symbol)
+                let overloadGroupReferences = try XCTUnwrap(overloadGroupSymbol.overloadsVariants.firstValue)
+
+                XCTAssertEqual(overloadGroupReferences.displayIndex, 0)
+            }
+        }
+    }
+
     // The overload behavior doesn't apply to symbol kinds that don't support overloading
     func testContextDoesNotRecognizeNonOverloadableSymbolKinds() throws {
         enableFeatureFlag(\.isExperimentalOverloadedSymbolPresentationEnabled)
@@ -4651,6 +4698,60 @@ let expected = """
         }
     }
 
+    func testWarnsOnUnknownPlistFeatureFlag() throws {
+        let tempURL = try createTempFolder(content: [
+            Folder(name: "unit-test.docc", content: [
+                DataFile(name: "Info.plist", data: Data("""
+                <plist version="1.0">
+                <dict>
+                    <key>CDExperimentalFeatureFlags</key>
+                    <dict>
+                        <key>NonExistentFeature</key>
+                        <true/>
+                    </dict>
+                </dict>
+                </plist>
+                """.utf8))
+            ])
+        ])
+        let (_, _, context) = try loadBundle(from: tempURL)
+
+        let unknownFeatureFlagProblems = context.problems.filter({ $0.diagnostic.identifier == "org.swift.docc.UnknownBundleFeatureFlag" })
+        XCTAssertEqual(unknownFeatureFlagProblems.count, 1)
+        let problem = try XCTUnwrap(unknownFeatureFlagProblems.first)
+
+        XCTAssertEqual(problem.diagnostic.severity, .warning)
+        XCTAssertEqual(problem.diagnostic.summary, "Unknown feature flag in Info.plist: 'NonExistentFeature'")
+    }
+
+    func testUnknownFeatureFlagSuggestsOtherFlags() throws {
+        let tempURL = try createTempFolder(content: [
+            Folder(name: "unit-test.docc", content: [
+                DataFile(name: "Info.plist", data: Data("""
+                <plist version="1.0">
+                <dict>
+                    <key>CDExperimentalFeatureFlags</key>
+                    <dict>
+                        <key>ExperimenalOverloadedSymbolPresentation</key>
+                        <true/>
+                    </dict>
+                </dict>
+                </plist>
+                """.utf8))
+            ])
+        ])
+        let (_, _, context) = try loadBundle(from: tempURL)
+
+        let unknownFeatureFlagProblems = context.problems.filter({ $0.diagnostic.identifier == "org.swift.docc.UnknownBundleFeatureFlag" })
+        XCTAssertEqual(unknownFeatureFlagProblems.count, 1)
+        let problem = try XCTUnwrap(unknownFeatureFlagProblems.first)
+
+        XCTAssertEqual(problem.diagnostic.severity, .warning)
+        XCTAssertEqual(
+            problem.diagnostic.summary,
+            "Unknown feature flag in Info.plist: 'ExperimenalOverloadedSymbolPresentation'. Possible suggestions: 'ExperimentalOverloadedSymbolPresentation'")
+    }
+
     // A test helper that creates a symbol with a given identifier and kind.
     private func makeSymbol(
         name: String = "SymbolName",