Make the symbol graph extraction requested by plugins more robust (#3993)

* Rework the SymbolGraphExtract so it's more suitable for being called in the context of plugins.

This includes parameterizing the output format and the output path, as well as the diagnostics that are printed, and applying the extractor to a target at a time and not always to all the targets in a package.  The original behavior for the `dump-symbol-graph` command is unmodified, but some of the specifics are hoisted into the DumpSymbolGraph command implementation rather than in the reusable SymbolGraphExtract type.

* Make the symbol graph generation more robust by using the refactored SymbolGraphExtract:

- only generate symbol graph information for the specified target
- use a unique symbol graph output directory for each package/target combination
- added a unit test to check these things.

* Skip the test in a bootstrap situation where we're using a Swift compiler that hasn't built the `swift-symbolgraph-extract` tool.  There is a `SWIFT_SYMBOLGRAPH_EXTRACT` env var that could be used to point it another binary, but on platforms other than macOS we don't have an existing Xcode or anything that would be guaranteed to contain this tool.  This test should still run on full builds and on self tests, where the tool is available.

rdar://87234110&86785765

Author: abertelrud

Sources/Commands/SwiftPackageTool.swift

@@ -531,7 +531,7 @@ extension SwiftPackageTool {
     struct DumpSymbolGraph: SwiftCommand {
         static let configuration = CommandConfiguration(
             abstract: "Dump Symbol Graph")
-        static let defaultMinimumAccessLevel = AccessLevel.public
+        static let defaultMinimumAccessLevel = SymbolGraphExtract.AccessLevel.public
 
         @OptionGroup(_hiddenFromHelp: true)
         var swiftOptions: SwiftToolOptions
@@ -542,7 +542,7 @@ extension SwiftPackageTool {
         @Flag(help: "Skip members inherited through classes or default implementations.")
         var skipSynthesizedMembers = false
 
-        @Option(help: "Include symbols with this access level or more. Possible values: \(AccessLevel.allValueStrings.joined(separator: " | "))")
+        @Option(help: "Include symbols with this access level or more. Possible values: \(SymbolGraphExtract.AccessLevel.allValueStrings.joined(separator: " | "))")
         var minimumAccessLevel = defaultMinimumAccessLevel
 
         @Flag(help: "Skip emitting doc comments for members inherited through classes or default implementations.")
@@ -552,23 +552,34 @@ extension SwiftPackageTool {
         var includeSPISymbols = false
 
         func run(_ swiftTool: SwiftTool) throws {
-            let symbolGraphExtract = try SymbolGraphExtract(
-                tool: swiftTool.getToolchain().getSymbolGraphExtract())
-
             // Build the current package.
             //
             // We turn build manifest caching off because we need the build plan.
             let buildOp = try swiftTool.createBuildOperation(cacheBuildManifest: false)
             try buildOp.build()
 
-            try symbolGraphExtract.dumpSymbolGraph(
-                buildPlan: buildOp.buildPlan!,
-                prettyPrint: prettyPrint,
-                skipSynthesisedMembers: skipSynthesizedMembers,
+            // Configure the symbol graph extractor.
+            let symbolGraphExtractor = try SymbolGraphExtract(
+                tool: swiftTool.getToolchain().getSymbolGraphExtract(),
+                skipSynthesizedMembers: skipSynthesizedMembers,
                 minimumAccessLevel: minimumAccessLevel,
                 skipInheritedDocs: skipInheritedDocs,
-                includeSPISymbols: includeSPISymbols
-            )
+                includeSPISymbols: includeSPISymbols)
+
+            // Run the tool once for every library and executable target in the root package.
+            let buildPlan = buildOp.buildPlan!
+            let symbolGraphDirectory = buildPlan.buildParameters.dataPath.appending(component: "symbolgraph")
+            let targets = buildPlan.graph.rootPackages.flatMap{ $0.targets }.filter{ $0.type == .library || $0.type == .executable }
+            for target in targets {
+                print("-- Emitting symbol graph for", target.name)
+                try symbolGraphExtractor.extractSymbolGraph(
+                    target: target,
+                    buildPlan: buildPlan,
+                    logLevel: swiftTool.logLevel,
+                    outputDirectory: symbolGraphDirectory)
+            }
+
+            print("Files written to", symbolGraphDirectory.pathString)
         }
     }
 
@@ -1217,37 +1228,58 @@ final class PluginDelegate: PluginInvocationDelegate {
     }
 
     private func createSymbolGraph(forTarget targetName: String, options: PluginInvocationSymbolGraphOptions) throws -> PluginInvocationSymbolGraphResult {
-        // Current implementation uses `SymbolGraphExtract()` but we can probably do better in the future.
-        let buildParameters = try swiftTool.buildParameters()
-        let buildOperation = try swiftTool.createBuildOperation(cacheBuildManifest: false)  // We only get a build plan if we don't cache
-        try buildOperation.build(subset: .target(targetName))
-        let symbolGraphExtract = try SymbolGraphExtract(tool: swiftTool.getToolchain().getSymbolGraphExtract())
-        let minimumAccessLevel: AccessLevel
+        // Current implementation uses `SymbolGraphExtract()` but in the future we should emit the symbol graph while building.
+
+        // Create a build operation for building the target., skipping the the cache because we need the build plan.
+        let buildOperation = try swiftTool.createBuildOperation(cacheBuildManifest: false)
+
+        // Find the target in the build operation's package graph; it's an error if we don't find it.
+        let packageGraph = try buildOperation.getPackageGraph()
+        guard let target = packageGraph.allTargets.first(where: { $0.name == targetName }) else {
+            throw StringError("could not find a target named “\(targetName)”")
+        }
+
+        // Build the target, if needed.
+        try buildOperation.build(subset: .target(target.name))
+
+        // Configure the symbol graph extractor.
+        var symbolGraphExtractor = try SymbolGraphExtract(tool: swiftTool.getToolchain().getSymbolGraphExtract())
+        symbolGraphExtractor.skipSynthesizedMembers = !options.includeSynthesized
         switch options.minimumAccessLevel {
         case .private:
-            minimumAccessLevel = .private
+            symbolGraphExtractor.minimumAccessLevel = .private
         case .fileprivate:
-            minimumAccessLevel = .fileprivate
+            symbolGraphExtractor.minimumAccessLevel = .fileprivate
         case .internal:
-            minimumAccessLevel = .internal
+            symbolGraphExtractor.minimumAccessLevel = .internal
         case .public:
-            minimumAccessLevel = .public
+            symbolGraphExtractor.minimumAccessLevel = .public
         case .open:
-            minimumAccessLevel = .open
+            symbolGraphExtractor.minimumAccessLevel = .open
         }
-        
-        // Extract the symbol graph.
-        try symbolGraphExtract.dumpSymbolGraph(
-            buildPlan: buildOperation.buildPlan!,
-            prettyPrint: false,
-            skipSynthesisedMembers: !options.includeSynthesized,
-            minimumAccessLevel: minimumAccessLevel,
-            skipInheritedDocs: true,
-            includeSPISymbols: options.includeSPI)
-        
+        symbolGraphExtractor.skipInheritedDocs = true
+        symbolGraphExtractor.includeSPISymbols = options.includeSPI
+
+        // Determine the output directory, and remove any old version if it already exists.
+        guard let buildPlan = buildOperation.buildPlan else {
+            throw StringError("could not get the build plan from the build operation")
+        }
+        guard let package = packageGraph.package(for: target) else {
+            throw StringError("could not determine the package for target “\(target.name)”")
+        }
+        let outputDir = buildPlan.buildParameters.dataPath.appending(components: "extracted-symbols", package.identity.description, target.name)
+        try localFileSystem.removeFileTree(outputDir)
+
+        // Run the symbol graph extractor on the target.
+        try symbolGraphExtractor.extractSymbolGraph(
+            target: target,
+            buildPlan: buildPlan,
+            outputRedirection: .collect,
+            logLevel: .warning,
+            outputDirectory: outputDir)
+
         // Return the results to the plugin.
-        return PluginInvocationSymbolGraphResult(
-            directoryPath: buildParameters.symbolGraph.pathString)
+        return PluginInvocationSymbolGraphResult(directoryPath: outputDir.pathString)
     }
 }
 

Sources/Commands/SymbolGraphExtract.swift

@@ -1,97 +1,88 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2014 - 2020 Apple Inc. and the Swift project authors
+ Copyright (c) 2014 - 2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See http://swift.org/LICENSE.txt for license information
  See http://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import Foundation
-
-import TSCBasic
-import TSCUtility
-
-import SPMBuildCore
+import ArgumentParser
+import Basics
 import Build
 import PackageGraph
 import PackageModel
-import SourceControl
-import Workspace
-import ArgumentParser
+import SPMBuildCore
+import TSCBasic
+import TSCUtility
 
 /// A wrapper for swift-symbolgraph-extract tool.
 public struct SymbolGraphExtract {
     let tool: AbsolutePath
-
-    init(tool: AbsolutePath) {
-        self.tool = tool
+    
+    var skipSynthesizedMembers = false
+    var minimumAccessLevel = AccessLevel.public
+    var skipInheritedDocs = false
+    var includeSPISymbols = false
+    var outputFormat = OutputFormat.json(pretty: false)
+
+    /// Access control levels.
+    public enum AccessLevel: String, RawRepresentable, CaseIterable, ExpressibleByArgument {
+        // The cases reflect those found in `include/swift/AST/AttrKind.h` of the swift compiler (at commit 03f55d7bb4204ca54841218eb7cc175ae798e3bd)
+        case `private`, `fileprivate`, `internal`, `public`, `open`
     }
 
-    public func dumpSymbolGraph(
+    /// Output format of the generated symbol graph.
+    public enum OutputFormat {
+        /// JSON format, optionally "pretty-printed" be more human-readable.
+        case json(pretty: Bool)
+    }
+    
+    /// Creates a symbol graph for `target` in `outputDirectory` using the build information from `buildPlan`. The `outputDirection` determines how the output from the tool subprocess is handled, and `verbosity` specifies how much console output to ask the tool to emit.
+    public func extractSymbolGraph(
+        target: ResolvedTarget,
         buildPlan: BuildPlan,
-        prettyPrint: Bool,
-        skipSynthesisedMembers: Bool,
-        minimumAccessLevel: AccessLevel,
-        skipInheritedDocs: Bool,
-        includeSPISymbols: Bool
+        outputRedirection: Process.OutputRedirection = .none,
+        logLevel: Basics.Diagnostic.Severity,
+        outputDirectory: AbsolutePath
     ) throws {
         let buildParameters = buildPlan.buildParameters
-        let symbolGraphDirectory = buildPlan.buildParameters.symbolGraph
-        try localFileSystem.createDirectory(symbolGraphDirectory, recursive: true)
-
-        // Run the tool for each target in the root package.
-        let targets = buildPlan.graph.rootPackages.flatMap{ $0.targets }.filter{ $0.type == .library || $0.type == .executable }
-        for target in targets {
-            var args = [String]()
-            args += ["-module-name", target.c99name]
-            args += try buildParameters.targetTripleArgs(for: target)
-
-            args += buildPlan.createAPIToolCommonArgs(includeLibrarySearchPaths: true)
-            args += ["-module-cache-path", buildParameters.moduleCache.pathString]
-
-            args += ["-output-dir", symbolGraphDirectory.pathString]
-
-            if prettyPrint { args.append("-pretty-print") }
-            if skipSynthesisedMembers { args.append("-skip-synthesized-members") }
-            if minimumAccessLevel != SwiftPackageTool.DumpSymbolGraph.defaultMinimumAccessLevel {
-                args += ["-minimum-access-level", minimumAccessLevel.rawValue]
+        try localFileSystem.createDirectory(outputDirectory, recursive: true)
+
+        // Construct arguments for extracting symbols for a single target.
+        var commandLine = [self.tool.pathString]
+        commandLine += ["-module-name", target.c99name]
+        commandLine += try buildParameters.targetTripleArgs(for: target)
+        commandLine += buildPlan.createAPIToolCommonArgs(includeLibrarySearchPaths: true)
+        commandLine += ["-module-cache-path", buildParameters.moduleCache.pathString]
+        if logLevel <= .info {
+            commandLine += ["-v"]
+        }
+        commandLine += ["-minimum-access-level", minimumAccessLevel.rawValue]
+        if skipSynthesizedMembers {
+            commandLine += ["-skip-synthesized-members"]
+        }
+        if skipInheritedDocs {
+            commandLine += ["-skip-inherited-docs"]
+        }
+        if includeSPISymbols {
+            commandLine += ["-include-spi-symbols"]
+        }
+        switch outputFormat {
+        case .json(let pretty):
+            if pretty {
+                commandLine += ["-pretty-print"]
             }
-            if skipInheritedDocs { args.append("-skip-inherited-docs") }
-            if includeSPISymbols { args.append("-include-spi-symbols") }
-
-            print("-- Emitting symbol graph for", target.name)
-            try runTool(args)
         }
-        print("Files written to", symbolGraphDirectory.pathString)
-    }
+        commandLine += ["-output-dir", outputDirectory.pathString]
 
-    func runTool(_ args: [String]) throws {
-        let arguments = [tool.pathString] + args
+        // Run the extraction.
         let process = Process(
-            arguments: arguments,
-            outputRedirection: .none,
-            verbose: verbosity != .concise
-        )
+            arguments: commandLine,
+            outputRedirection: outputRedirection,
+            verbose: logLevel <= .info)
         try process.launch()
         try process.waitUntilExit()
     }
 }
-
-/// Access control levels.
-public enum AccessLevel: String, RawRepresentable, CustomStringConvertible, CaseIterable {
-    // The cases reflect those found in `include/swift/AST/AttrKind.h` of the swift compiler (at commit 03f55d7bb4204ca54841218eb7cc175ae798e3bd)
-    case `private`, `fileprivate`, `internal`, `public`, `open`
-
-    public var description: String { rawValue }
-}
-
-extension AccessLevel: ExpressibleByArgument {}
-
-extension BuildParameters {
-    /// The directory containing artifacts generated by the symbolgraph-extract tool.
-    var symbolGraph: AbsolutePath {
-        dataPath.appending(component: "symbolgraph")
-    }
-}

Tests/CommandsTests/PackageToolTests.swift

@@ -1442,4 +1442,90 @@ final class PackageToolTests: CommandsTestCase {
             }
         }
     }
+
+    func testCommandPluginSymbolGraphCallbacks() throws {
+        // Depending on how the test is running, the `swift-symbolgraph-extract` tool might be unavailable.
+        try XCTSkipIf((try? UserToolchain.default.getSymbolGraphExtract()) == nil, "skipping test because the `swift-symbolgraph-extract` tools isn't available")
+        
+        try testWithTemporaryDirectory { tmpPath in
+            // Create a sample package with a library, and executable, and a plugin.
+            let packageDir = tmpPath.appending(components: "MyPackage")
+            try localFileSystem.writeFileContents(packageDir.appending(components: "Package.swift")) {
+                $0 <<< """
+                // swift-tools-version: 5.6
+                import PackageDescription
+                let package = Package(
+                    name: "MyPackage",
+                    targets: [
+                        .target(
+                            name: "MyLibrary"
+                        ),
+                        .executableTarget(
+                            name: "MyCommand",
+                            dependencies: ["MyLibrary"]
+                        ),
+                        .plugin(
+                            name: "MyPlugin",
+                            capability: .command(
+                                intent: .documentationGeneration()
+                            )
+                        ),
+                    ]
+                )
+                """
+            }
+            try localFileSystem.writeFileContents(packageDir.appending(components: "Sources", "MyLibrary", "library.swift")) {
+                $0 <<< """
+                public func GetGreeting() -> String { return "Hello" }
+                """
+            }
+            try localFileSystem.writeFileContents(packageDir.appending(components: "Sources", "MyCommand", "main.swift")) {
+                $0 <<< """
+                import MyLibrary
+                print("\\(GetGreeting()), World!")
+                """
+            }
+            try localFileSystem.writeFileContents(packageDir.appending(components: "Plugins", "MyPlugin", "plugin.swift")) {
+                $0 <<< """
+                import PackagePlugin
+                import Foundation
+
+                @main
+                struct MyCommandPlugin: CommandPlugin {
+                    func performCommand(
+                        context: PluginContext,
+                        targets: [Target],
+                        arguments: [String]
+                    ) throws {
+                        // Ask for and print out the symbol graph directory for each target.
+                        for target in targets {
+                            let symbolGraph = try packageManager.getSymbolGraph(for: target,
+                                options: .init(minimumAccessLevel: .public))
+                            print("\\(target.name): \\(symbolGraph.directoryPath)")
+                        }
+                    }
+                }
+                """
+            }
+
+            // Check that if we don't pass any target, we successfully get symbol graph information for all targets in the package, and at different paths.
+            do {
+                let result = try SwiftPMProduct.SwiftPackage.executeProcess(["generate-documentation"], packagePath: packageDir)
+                let output = try result.utf8Output() + result.utf8stderrOutput()
+                XCTAssertEqual(result.exitStatus, .terminated(code: 0), "output: \(output)")
+                XCTAssertMatch(output, .and(.contains("MyLibrary:"), .contains("mypackage/MyLibrary")))
+                XCTAssertMatch(output, .and(.contains("MyCommand:"), .contains("mypackage/MyCommand")))
+
+            }
+
+            // Check that if we pass a target, we successfully get symbol graph information for just the target we asked for.
+            do {
+                let result = try SwiftPMProduct.SwiftPackage.executeProcess(["--target", "MyLibrary", "generate-documentation"], packagePath: packageDir)
+                let output = try result.utf8Output() + result.utf8stderrOutput()
+                XCTAssertEqual(result.exitStatus, .terminated(code: 0), "output: \(output)")
+                XCTAssertMatch(output, .and(.contains("MyLibrary:"), .contains("mypackage/MyLibrary")))
+                XCTAssertNoMatch(output, .and(.contains("MyCommand:"), .contains("mypackage/MyCommand")))
+            }
+        }
+    }
 }