[Build] BuildPlan: Add a way to traverse module dependencies

This method is going to be very useful for planning various
build descriptions because they currently rely on a modules
graph + description lookup into the build plan which is not
great because it means that modules graph has to know about
module destinations.

Author: xedin

Sources/Build/BuildPlan/BuildPlan.swift

@@ -706,6 +706,20 @@ public class BuildPlan: SPMBuildCore.BuildPlan {
         }
         return inputs
     }
+
+    public func description(
+        for product: ResolvedProduct,
+        context: BuildParameters.Destination
+    ) -> ProductBuildDescription? {
+        return self.productMap[product.id]
+    }
+
+    public func description(
+        for module: ResolvedModule,
+        context: BuildParameters.Destination
+    ) -> ModuleBuildDescription? {
+        return self.targetMap[module.id]
+    }
 }
 
 extension BuildPlan {
@@ -1117,6 +1131,59 @@ extension BuildPlan {
             }
         }
     }
+
+    package func traverseDependencies(
+        of description: ModuleBuildDescription,
+        onProduct: (ResolvedProduct, BuildParameters.Destination, ProductBuildDescription?) -> Void,
+        onModule: (ResolvedModule, BuildParameters.Destination, ModuleBuildDescription?) -> Void
+    ) {
+        func successors(
+            for product: ResolvedProduct,
+            destination: Destination
+        ) -> [TraversalNode] {
+            product.modules.map { module in
+                TraversalNode(module: module, context: destination)
+            }
+        }
+
+        func successors(
+            for module: ResolvedModule,
+            destination: Destination
+        ) -> [TraversalNode] {
+            module
+                .dependencies(satisfying: description.buildParameters.buildEnvironment)
+                .reduce(into: [TraversalNode]()) { partial, dependency in
+                    switch dependency {
+                    case .product(let product, _):
+                        partial.append(.init(product: product, context: destination))
+                    case .module(let module, _):
+                        partial.append(.init(module: module, context: destination))
+                    }
+                }
+        }
+
+        depthFirstSearch(successors(for: description.module, destination: description.destination)) {
+            switch $0 {
+            case .module(let module, let destination):
+                successors(for: module, destination: destination)
+            case .product(let product, let destination):
+                successors(for: product, destination: destination)
+            case .package:
+                []
+            }
+        } onNext: { module, _, _ in
+            switch module {
+            case .package:
+                break
+
+            case .product(let product, let destination):
+                onProduct(product, destination, self.description(for: product, context: destination))
+
+            case .module(let module, let destination):
+                onModule(module, destination, self.description(for: module, context: destination))
+            }
+        }
+    }
 }
 
 extension Basics.Diagnostic {

Tests/BuildTests/BuildPlanTraversalTests.swift

@@ -143,4 +143,47 @@ final class BuildPlanTraversalTests: XCTestCase {
         XCTAssertEqual(self.getUniqueOccurrences(in: results, for: "SwiftSyntax", destination: .host), [2, 3, 4, 5, 6])
         XCTAssertEqual(self.getUniqueOccurrences(in: results, for: "HAL"), [1, 2, 3])
     }
+
+    func testRecursiveDependencyTraversal() async throws {
+        let destinationTriple = Triple.arm64Linux
+        let toolsTriple = Triple.x86_64MacOS
+
+        let (graph, fs, scope) = try macrosPackageGraph()
+        let plan = try await BuildPlan(
+            destinationBuildParameters: mockBuildParameters(
+                destination: .target,
+                triple: destinationTriple
+            ),
+            toolsBuildParameters: mockBuildParameters(
+                destination: .host,
+                triple: toolsTriple
+            ),
+            graph: graph,
+            fileSystem: fs,
+            observabilityScope: scope
+        )
+
+        let mmioModule = try XCTUnwrap(plan.description(for: graph.module(for: "MMIO")!, context: .target))
+
+        var moduleDependencies: [(ResolvedModule, Dest, Build.ModuleBuildDescription?)] = []
+        plan.traverseDependencies(of: mmioModule) { product, destination, description in
+            XCTAssertEqual(product.name, "SwiftSyntax")
+            XCTAssertEqual(destination, .host)
+            XCTAssertNil(description)
+        } onModule: { module, destination, description in
+            moduleDependencies.append((module, destination, description))
+        }
+
+        XCTAssertEqual(moduleDependencies.count, 2)
+
+        // The ordering is guaranteed by the traversal
+
+        XCTAssertEqual(moduleDependencies[0].0.name, "MMIOMacros")
+        XCTAssertEqual(moduleDependencies[1].0.name, "SwiftSyntax")
+
+        for index in 0 ..< moduleDependencies.count {
+            XCTAssertEqual(moduleDependencies[index].1, .host)
+            XCTAssertNotNil(moduleDependencies[index].2)
+        }
+    }
 }