address review comments with strategy from swiftlang#28

Author: theMomax

Plugins/SharedPackagePluginExtensions/PackageManager+getSymbolGraphsForDocC.swift

@@ -39,13 +39,26 @@ extension PackageManager {
         context: PluginContext,
         verbose: Bool,
         snippetExtractor: SnippetExtractor?,
-        arguments: Arguments
+        customSymbolGraphOptions: [PluginFlag]
     ) throws -> DocCSymbolGraphResult {
         // First generate the primary symbol graphs containing information about the
         // symbols defined in the target itself.
 
         var symbolGraphOptions = target.defaultSymbolGraphOptions(in: context.package)
-        symbolGraphOptions.override(with: arguments)
+
+        // Modify the symbol graph options with the custom ones
+        for customSymbolGraphOption in customSymbolGraphOptions {
+            switch customSymbolGraphOption {
+            case .extendedTypes:
+#if swift(>=5.8)
+                symbolGraphOptions.emitExtensionBlocks = true
+#else
+                print("warning: detected '--include-extended-types' option, which is incompatible with your swift version (required: 5.8)")
+#endif
+            default:
+                fatalError("error: unknown PluginFlag (\(customSymbolGraphOption.parsedValues.joined(separator: ", "))) detected in symbol graph generation - please create an issue at https://github.com/apple/swift-docc-plugin")
+         }
+        }
 
         if verbose {
             print("symbol graph options: '\(symbolGraphOptions)'")

Plugins/SharedPackagePluginExtensions/SymbolGraphOptions+override.swift

@@ -36,7 +36,7 @@ extension SwiftSourceModuleTarget {
 
 #if swift(<5.8)
 private extension PackageManager.SymbolGraphOptions {
-    /// A copatibility layer for lower Swift versions which discards unknown parameters.
+    /// A compatibility layer for lower Swift versions which discards unknown parameters.
     init(minimumAccessLevel: PackagePlugin.PackageManager.SymbolGraphOptions.AccessLevel = .public,
          includeSynthesized: Bool = false,
          includeSPI: Bool = false,

Plugins/SharedPackagePluginExtensions/Target+defaultSymbolGraphOptions.swift

@@ -71,7 +71,7 @@ import PackagePlugin
                 context: context,
                 verbose: verbose,
                 snippetExtractor: snippetExtractor,
-                arguments: parsedArguments.dumpSymbolGraphArguments()
+                customSymbolGraphOptions: parsedArguments.symbolGraphArguments
             )
 
             if try FileManager.default.contentsOfDirectory(atPath: symbolGraphs.targetSymbolGraphsDirectory.path).isEmpty {

Plugins/Swift-DocC Convert/SwiftDocCConvert.swift

@@ -84,7 +84,7 @@ import PackagePlugin
             context: context,
             verbose: verbose,
             snippetExtractor: snippetExtractor,
-            arguments: parsedArguments.dumpSymbolGraphArguments()
+            customSymbolGraphOptions: parsedArguments.symbolGraphArguments
         )
 
         if try FileManager.default.contentsOfDirectory(atPath: symbolGraphs.targetSymbolGraphsDirectory.path).isEmpty {

Plugins/Swift-DocC Preview/SwiftDocCPreview.swift

@@ -47,6 +47,9 @@ public enum HelpInformation {
             PluginFlag.disableIndex,
         ]
 
+        // stops 'not mutated' warning for Swift 5.7 and lower
+        supportedPluginFlags += []
+        
 #if swift(>=5.8)
         supportedPluginFlags += [PluginFlag.extendedTypes]
 #endif

Sources/SwiftDocCPluginUtilities/HelpInformation.swift

@@ -19,21 +19,6 @@ public struct ParsedArguments {
         return arguments.contains("--help") || arguments.contains("-h")
     }
 
-    /// Returns the arguments that could be passed to `swift package dump-symbol-graph`.
-    ///
-    /// In practice, however we won't invoke the `dump-symbol-graph` command via the command line,
-    /// but via the `PackagePlugin` API. Thus, these arguments have to be parsed later on and converted to
-    /// `PackageManager.SymbolGraphOptions`.
-    public func dumpSymbolGraphArguments() -> Arguments {
-        var dumpSymbolGraphArguments = arguments.filter(for: .dumpSymbolGraph)
-        
-        for argumentsTransformer in Self.argumentsTransformers {
-            dumpSymbolGraphArguments = argumentsTransformer.transform(dumpSymbolGraphArguments)
-        }
-        
-        return dumpSymbolGraphArguments
-    }
-    
     /// Returns the arguments that should be passed to `docc` to invoke the given plugin action.
     ///
     /// Merges the arguments provided upon initialization of the parsed arguments that are relevant
@@ -168,8 +153,19 @@ public struct ParsedArguments {
     /// Creates a new set of parsed arguments with the given arguments.
     public init(_ arguments: [String]) {
         self.arguments = arguments
+        
+        let symbolGraphArguments = arguments.filter(for: .dumpSymbolGraph)
+        
+        self.symbolGraphArguments = ParsedArguments.ArgumentConsumer.dumpSymbolGraph.flags.filter { option in
+            option.parsedValues.contains(where: symbolGraphArguments.contains)
+        }
     }
 
+    // Build array with plugin flags that modify the symbol graph generation,
+    // filtering from the available custom symbol graph options those
+    // that correspond to the received flags
+    var symbolGraphArguments: [PluginFlag]
+    
     /// The command-line options required by the `docc` tool.
     private static let requiredOptions: [CommandLineOption] = [
         .fallbackDisplayName,
@@ -199,16 +195,16 @@ private extension ParsedArguments {
 
         /// Returns the flags applicable to an `ArgumentConsumer`.
         ///
-        /// If `flags` is `nil`, this `ArgumentConsumer` is assumed to
+        /// If `flags.isEmpty` is `true`, this `ArgumentConsumer` is assumed to
         /// consume all flags not consumed by any of the other `ArgumentConsumer`s.
-        var flags: [PluginFlag]? {
+        var flags: [PluginFlag] {
             switch self {
             case .dumpSymbolGraph:
                 return [
                     PluginFlag.extendedTypes
                 ]
             case .docc:
-                return nil
+                return []
             }
         }
     }
@@ -217,14 +213,22 @@ private extension ParsedArguments {
 private extension Arguments {
     /// Returns the subset of arguments which are applicable to the given `consumer`.
     func filter(for consumer: ParsedArguments.ArgumentConsumer) -> Arguments {
-        if let flagsToInclude = consumer.flags {
+        if !consumer.flags.isEmpty {
+            // If the consumer can provide a complete list of valid flags,
+            // we only include elements that are included in one of these flags'
+            // `parsedValues`, i.e. if one of these flags can be applied to the
+            // element.
+            let flagsToInclude = consumer.flags
             return self.filter { argument in
                 flagsToInclude.contains(where: { flag in
                     flag.parsedValues.contains(argument)
                 })
             }
         } else {
-            let flagsToExclude = ParsedArguments.ArgumentConsumer.allCases.compactMap(\.flags).flatMap { $0 }
+            // If the consumer cannot provide a complete list of valid flags, (which
+            // should only happen for the `.docc` case) we return all elements
+            // that are not applicable to any of the other `ArgumentConsumer`s.
+            let flagsToExclude = ParsedArguments.ArgumentConsumer.allCases.flatMap(\.flags)
             return self.filter { argument in
                 !flagsToExclude.contains(where: { flag in
                     flag.parsedValues.contains(argument)

Sources/SwiftDocCPluginUtilities/ParsedArguments.swift

@@ -24,6 +24,6 @@ extension PluginFlag {
         description: """
             Allows documenting symbols that a target adds to its dependencies.
             """,
-        argumentTransformation: { $0 + ["--emit-extension-block-symbols"] }
+        argumentTransformation: { $0 }
     )
 }

Sources/SwiftDocCPluginUtilities/PluginFlags/ExtendedTypesFlag.swift

@@ -0,0 +1,13 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2022 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
+
+extension PluginFlag: Equatable {
+    static func ==(lhs: PluginFlag, rhs: PluginFlag) -> Bool {
+        return lhs.parsedValues == rhs.parsedValues
+    }
+}

Sources/SwiftDocCPluginUtilities/PluginFlags/PluginFlag+Equatable.swift

@@ -456,19 +456,18 @@ final class ParsedArgumentsTests: XCTestCase {
         )
 
         XCTAssertFalse(doccArguments.contains("--include-extended-types"))
-        XCTAssertFalse(doccArguments.contains("--emit-extension-block-symbols"))
     }
 
     func testDumpSymbolGraphArguments() {
         let dumpSymbolGraphArguments = ParsedArguments(["--include-extended-types"])
 
-        XCTAssertEqual(dumpSymbolGraphArguments.dumpSymbolGraphArguments(), ["--emit-extension-block-symbols"])
+        XCTAssertEqual(dumpSymbolGraphArguments.symbolGraphArguments, [.extendedTypes])
     }
 
     func testDumpSymbolGraphArgumentsWithDocCArguments() {
         let dumpSymbolGraphArguments = ParsedArguments(["--fallback-default-module-kind", "Executable"])
 
 
-        XCTAssertTrue(dumpSymbolGraphArguments.dumpSymbolGraphArguments().isEmpty)
+        XCTAssertEqual(dumpSymbolGraphArguments.symbolGraphArguments, [])
     }
 }

Tests/SwiftDocCPluginUtilitiesTests/ParsedArgumentsTests.swift

@@ -16,7 +16,7 @@ final class ExtendedTypesFlagTests: XCTestCase {
             PluginFlag.extendedTypes.transform(
                 ["--include-extended-types", "--other-flag"]
             ),
-            ["--other-flag", "--emit-extension-block-symbols"]
+            ["--other-flag"]
         )
     }