Make Resolved* in PackageGraph value types (#7160)

Depends on #7161.
Unblocks macros cross-compilation fix in #7118.

### Motivation:

Value types are easier to reason about as they prevent "spooky action at
a distance" bugs, and can be easily made `Equatable`, `Hashable`, and most important of all `Sendable`.

### Modifications:

Converted `ResolvedTarget`, `ResolvedProduct`, and `ResolvedPackage`
from `final class`es to `struct`s.

Renamed `underlyingTarget`, `underlyingProduct`, and `underlyingPackage`
to just `underlying` to avoid tautological patterns like `target.underlyingTarget`.

### Result:

It's easier to apply changes in `PackageGraph`. Also, in my benchmarks
done locally this makes package graph resolution consistently ~5% faster
when resolving the package graph of SwiftPM's own `Package.swift`.

#### `main` branch:

```
╒══════════════════════════════════╤═════════╤═════════╤═════════╤═════════╤═════════╤═════════╤═════════╤═════════╕
│ Metric                           │      p0 │     p25 │     p50 │     p75 │     p90 │     p99 │    p100 │ Samples │
╞══════════════════════════════════╪═════════╪═════════╪═════════╪═════════╪═════════╪═════════╪═════════╪═════════╡
│ Time (system CPU) (ms)           │       7 │       8 │      11 │      14 │      15 │      18 │      18 │      25 │
├──────────────────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ Time (total CPU) (ms)            │      12 │      13 │      16 │      19 │      20 │      23 │      23 │      25 │
├──────────────────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ Time (user CPU) (μs)             │    4688 │    4857 │    4890 │    4956 │    5107 │    5347 │    5347 │      25 │
├──────────────────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ Time (wall clock) (ms)           │     390 │     397 │     402 │     409 │     414 │     420 │     420 │      25 │
╘══════════════════════════════════╧═════════╧═════════╧═════════╧═════════╧═════════╧═════════╧═════════╧═════════╛
```

#### This PR's branch:

```
╒══════════════════════════════════╤═════════╤═════════╤═════════╤═════════╤═════════╤═════════╤═════════╤═════════╕
│ Metric                           │      p0 │     p25 │     p50 │     p75 │     p90 │     p99 │    p100 │ Samples │
╞══════════════════════════════════╪═════════╪═════════╪═════════╪═════════╪═════════╪═════════╪═════════╪═════════╡
│ Time (system CPU) (ms)           │       6 │       8 │      10 │      13 │      16 │      17 │      17 │      26 │
├──────────────────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ Time (total CPU) (ms)            │      11 │      13 │      15 │      18 │      20 │      21 │      21 │      26 │
├──────────────────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ Time (user CPU) (μs)             │    4476 │    4567 │    4648 │    4796 │    4931 │    4998 │    4998 │      26 │
├──────────────────────────────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ Time (wall clock) (ms)           │     375 │     379 │     384 │     391 │     394 │     398 │     398 │      26 │
╘══════════════════════════════════╧═════════╧═════════╧═════════╧═════════╧═════════╧═════════╧═════════╧═════════╛
```

### Future directions:

I'm unable to fully remove `Resolved*Builder` classes yet, as they rely on `Target` being a reference type and module aliasing relying on side effects of modifying instances of `Target`. In turn, `Target` is a class hierarchy, which we should convert to multiple value types that use composition in the future. In the meantime this also prevents us from making it, and all types that contain it, `Sendable`.

Author: MaxDesiatov

Sources/Build/BuildDescription/ClangTargetBuildDescription.swift

@@ -13,7 +13,7 @@
 import Basics
 import PackageLoading
 import PackageModel
-import class PackageGraph.ResolvedTarget
+import struct PackageGraph.ResolvedTarget
 import struct SPMBuildCore.BuildParameters
 import struct SPMBuildCore.BuildToolPluginInvocationResult
 import struct SPMBuildCore.PrebuildCommandResult
@@ -26,9 +26,7 @@ public final class ClangTargetBuildDescription {
     public let target: ResolvedTarget
 
     /// The underlying clang target.
-    public var clangTarget: ClangTarget {
-        target.underlyingTarget as! ClangTarget
-    }
+    public let clangTarget: ClangTarget
 
     /// The tools version of the package that declared the target.  This can
     /// can be used to conditionalize semantically significant changes in how
@@ -45,7 +43,7 @@ public final class ClangTargetBuildDescription {
 
     /// The list of all resource files in the target, including the derived ones.
     public var resources: [Resource] {
-        self.target.underlyingTarget.resources + self.pluginDerivedResources
+        self.target.underlying.resources + self.pluginDerivedResources
     }
 
     /// Path to the bundle generated for this module (if any).
@@ -54,7 +52,7 @@ public final class ClangTargetBuildDescription {
             return .none
         }
 
-        if let bundleName = target.underlyingTarget.potentialBundleName {
+        if let bundleName = target.underlying.potentialBundleName {
             return self.buildParameters.bundlePath(named: bundleName)
         } else {
             return .none
@@ -119,10 +117,11 @@ public final class ClangTargetBuildDescription {
         fileSystem: FileSystem,
         observabilityScope: ObservabilityScope
     ) throws {
-        guard target.underlyingTarget is ClangTarget else {
+        guard let clangTarget = target.underlying as? ClangTarget else {
             throw InternalError("underlying target type mismatch \(target)")
         }
 
+        self.clangTarget = clangTarget
         self.fileSystem = fileSystem
         self.target = target
         self.toolsVersion = toolsVersion

Sources/Build/BuildDescription/PluginDescription.swift

@@ -50,7 +50,7 @@ public final class PluginDescription: Codable {
         testDiscoveryTarget: Bool = false,
         fileSystem: FileSystem
     ) throws {
-        guard target.underlyingTarget is PluginTarget else {
+        guard target.underlying is PluginTarget else {
             throw InternalError("underlying target type mismatch \(target)")
         }
 

Sources/Build/BuildDescription/ProductBuildDescription.swift

@@ -236,7 +236,7 @@ public final class ProductBuildDescription: SPMBuildCore.ProductBuildDescription
             // Support for linking tests against executables is conditional on the tools
             // version of the package that defines the executable product.
             let executableTarget = try product.executableTarget
-            if let target = executableTarget.underlyingTarget as? SwiftTarget, 
+            if let target = executableTarget.underlying as? SwiftTarget, 
                 self.toolsVersion >= .v5_5,
                 self.buildParameters.driverParameters.canRenameEntrypointFunctionName,
                 target.supportsTestableExecutablesFeature

Sources/Build/BuildDescription/SharedTargetBuildDescription.swift

@@ -53,7 +53,7 @@ struct SharedTargetBuildDescription {
             additionalFileRules: additionalFileRules,
             defaultLocalization: target.defaultLocalization,
             targetName: target.name,
-            targetPath: target.underlyingTarget.path,
+            targetPath: target.underlying.path,
             observabilityScope: observabilityScope
         )
         let pluginDerivedResources = derivedResources

Sources/Build/BuildDescription/SwiftTargetBuildDescription.swift

@@ -33,6 +33,8 @@ public final class SwiftTargetBuildDescription {
     /// The target described by this target.
     public let target: ResolvedTarget
 
+    private let swiftTarget: SwiftTarget
+
     /// The tools version of the package that declared the target.  This can
     /// can be used to conditionalize semantically significant changes in how
     /// a target is built.
@@ -57,7 +59,7 @@ public final class SwiftTargetBuildDescription {
 
     /// Path to the bundle generated for this module (if any).
     var bundlePath: AbsolutePath? {
-        if let bundleName = target.underlyingTarget.potentialBundleName, needsResourceBundle {
+        if let bundleName = target.underlying.potentialBundleName, needsResourceBundle {
             return self.buildParameters.bundlePath(named: bundleName)
         } else {
             return .none
@@ -83,7 +85,7 @@ public final class SwiftTargetBuildDescription {
 
     /// The list of all resource files in the target, including the derived ones.
     public var resources: [Resource] {
-        self.target.underlyingTarget.resources + self.pluginDerivedResources
+        self.target.underlying.resources + self.pluginDerivedResources
     }
 
     /// The objects in this target, containing either machine code or bitcode
@@ -139,7 +141,7 @@ public final class SwiftTargetBuildDescription {
 
     /// The swift version for this target.
     var swiftVersion: SwiftLanguageVersion {
-        (self.target.underlyingTarget as! SwiftTarget).swiftVersion
+        self.swiftTarget.swiftVersion
     }
 
     /// Describes the purpose of a test target, including any special roles such as containing a list of discovered
@@ -257,10 +259,11 @@ public final class SwiftTargetBuildDescription {
         fileSystem: FileSystem,
         observabilityScope: ObservabilityScope
     ) throws {
-        guard target.underlyingTarget is SwiftTarget else {
+        guard let swiftTarget = target.underlying as? SwiftTarget else {
             throw InternalError("underlying target type mismatch \(target)")
         }
 
+        self.swiftTarget = swiftTarget
         self.package = package
         self.target = target
         self.toolsVersion = toolsVersion
@@ -514,7 +517,7 @@ public final class SwiftTargetBuildDescription {
         // when we link the executable, we will ask the linker to rename the entry point
         // symbol to just `_main` again (or if the linker doesn't support it, we'll
         // generate a source containing a redirect).
-        if (self.target.underlyingTarget as? SwiftTarget)?.supportsTestableExecutablesFeature == true
+        if (self.target.underlying as? SwiftTarget)?.supportsTestableExecutablesFeature == true
             && !self.isTestTarget && self.toolsVersion >= .v5_5
         {
             // We only do this if the linker supports it, as indicated by whether we

Sources/Build/BuildDescription/TargetBuildDescription.swift

@@ -11,10 +11,10 @@
 //===----------------------------------------------------------------------===//
 
 import Basics
-import struct SPMBuildCore.BuildParameters
-import class PackageGraph.ResolvedTarget
+import struct PackageGraph.ResolvedTarget
 import struct PackageModel.Resource
 import struct SPMBuildCore.BuildToolPluginInvocationResult
+import struct SPMBuildCore.BuildParameters
 
 public enum BuildDescriptionError: Swift.Error {
     case requestedFileNotPartOfTarget(targetName: String, requestedFilePath: AbsolutePath)

Sources/Build/BuildManifest/LLBuildManifestBuilder+Clang.swift

@@ -13,7 +13,7 @@
 import struct LLBuildManifest.Node
 import struct Basics.AbsolutePath
 import struct Basics.InternalError
-import class PackageGraph.ResolvedTarget
+import struct PackageGraph.ResolvedTarget
 import PackageModel
 
 extension LLBuildManifestBuilder {

Sources/Build/BuildManifest/LLBuildManifestBuilder+Swift.swift

@@ -17,7 +17,7 @@ import struct Basics.TSCAbsolutePath
 import struct LLBuildManifest.Node
 import struct LLBuildManifest.LLBuildManifest
 import struct SPMBuildCore.BuildParameters
-import class PackageGraph.ResolvedTarget
+import struct PackageGraph.ResolvedTarget
 import protocol TSCBasic.FileSystem
 import enum TSCBasic.ProcessEnv
 import func TSCBasic.topologicalSort
@@ -212,8 +212,8 @@ extension LLBuildManifestBuilder {
                 // product into its constituent targets.
                 continue
             }
-            guard target.underlyingTarget.type != .systemModule,
-                  target.underlyingTarget.type != .binary
+            guard target.underlying.type != .systemModule,
+                  target.underlying.type != .binary
             else {
                 // Much like non-Swift targets, system modules will consist of a modulemap
                 // somewhere in the filesystem, with the path to that module being either
@@ -416,11 +416,11 @@ extension LLBuildManifestBuilder {
 
         func addStaticTargetInputs(_ target: ResolvedTarget) throws {
             // Ignore C Modules.
-            if target.underlyingTarget is SystemLibraryTarget { return }
+            if target.underlying is SystemLibraryTarget { return }
             // Ignore Binary Modules.
-            if target.underlyingTarget is BinaryTarget { return }
+            if target.underlying is BinaryTarget { return }
             // Ignore Plugin Targets.
-            if target.underlyingTarget is PluginTarget { return }
+            if target.underlying is PluginTarget { return }
 
             // Depend on the binary for executable targets.
             if target.type == .executable {

Sources/Build/BuildOperation.swift

@@ -511,7 +511,7 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
         for package in graph.rootPackages where package.manifest.toolsVersion >= .v5_3 {
             for target in package.targets {
                 // Get the set of unhandled files in targets.
-                var unhandledFiles = Set(target.underlyingTarget.others)
+                var unhandledFiles = Set(target.underlying.others)
                 if unhandledFiles.isEmpty { continue }
 
                 // Subtract out any that were inputs to any commands generated by plugins.

Sources/Build/BuildPlan/BuildPlan+Clang.swift

@@ -21,7 +21,7 @@ extension BuildPlan {
         let dependencies = try clangTarget.target.recursiveDependencies(satisfying: clangTarget.buildEnvironment)
 
         for case .target(let dependency, _) in dependencies {
-            switch dependency.underlyingTarget {
+            switch dependency.underlying {
             case is SwiftTarget:
                 if case let .swift(dependencyTargetDescription)? = targetMap[dependency] {
                     if let moduleMap = dependencyTargetDescription.moduleMap {

Sources/Build/BuildPlan/BuildPlan+Product.swift

@@ -13,8 +13,8 @@
 import struct Basics.AbsolutePath
 import struct Basics.Triple
 import struct Basics.InternalError
-import class PackageGraph.ResolvedProduct
-import class PackageGraph.ResolvedTarget
+import struct PackageGraph.ResolvedProduct
+import struct PackageGraph.ResolvedTarget
 import class PackageModel.BinaryTarget
 import class PackageModel.ClangTarget
 import class PackageModel.Target
@@ -32,7 +32,7 @@ extension BuildPlan {
 
         // Add flags for system targets.
         for systemModule in dependencies.systemModules {
-            guard case let target as SystemLibraryTarget = systemModule.underlyingTarget else {
+            guard case let target as SystemLibraryTarget = systemModule.underlying else {
                 throw InternalError("This should not be possible.")
             }
             // Add pkgConfig libs arguments.
@@ -53,7 +53,7 @@ extension BuildPlan {
         // Link C++ if needed.
         // Note: This will come from build settings in future.
         for target in dependencies.staticTargets {
-            if case let target as ClangTarget = target.underlyingTarget, target.isCXX {
+            if case let target as ClangTarget = target.underlying, target.isCXX {
                 let triple = buildProduct.buildParameters.triple
                 if triple.isDarwin() {
                     buildProduct.additionalFlags += ["-lc++"]
@@ -67,7 +67,7 @@ extension BuildPlan {
         }
 
         for target in dependencies.staticTargets {
-            switch target.underlyingTarget {
+            switch target.underlying {
             case is SwiftTarget:
                 // Swift targets are guaranteed to have a corresponding Swift description.
                 guard case .swift(let description) = targetMap[target] else {
@@ -131,7 +131,7 @@ extension BuildPlan {
         // For test targets, we need to consider the first level of transitive dependencies since the first level is always test targets.
         let topLevelDependencies: [PackageModel.Target]
         if product.type == .test {
-            topLevelDependencies = product.targets.flatMap { $0.underlyingTarget.dependencies }.compactMap {
+            topLevelDependencies = product.targets.flatMap { $0.underlying.dependencies }.compactMap {
                 switch $0 {
                 case .product:
                     return nil
@@ -149,7 +149,7 @@ extension BuildPlan {
             switch dependency {
             // Include all the dependencies of a target.
             case .target(let target, _):
-                let isTopLevel = topLevelDependencies.contains(target.underlyingTarget) || product.targets.contains(target)
+                let isTopLevel = topLevelDependencies.contains(target.underlying) || product.targets.contains(target)
                 let topLevelIsMacro = isTopLevel && product.type == .macro
                 let topLevelIsPlugin = isTopLevel && product.type == .plugin
                 let topLevelIsTest = isTopLevel && product.type == .test
@@ -200,9 +200,9 @@ extension BuildPlan {
                 case .executable, .snippet, .macro:
                     if product.targets.contains(target) {
                         staticTargets.append(target)
-                    } else if product.type == .test && (target.underlyingTarget as? SwiftTarget)?.supportsTestableExecutablesFeature == true {
+                    } else if product.type == .test && (target.underlying as? SwiftTarget)?.supportsTestableExecutablesFeature == true {
                         // Only "top-level" targets should really be considered here, not transitive ones.
-                        let isTopLevel = topLevelDependencies.contains(target.underlyingTarget) || product.targets.contains(target)
+                        let isTopLevel = topLevelDependencies.contains(target.underlying) || product.targets.contains(target)
                         if let toolsVersion = graph.package(for: product)?.manifest.toolsVersion, toolsVersion >= .v5_5, isTopLevel {
                             staticTargets.append(target)
                         }
@@ -220,7 +220,7 @@ extension BuildPlan {
                     systemModules.append(target)
                 // Add binary to binary paths set.
                 case .binary:
-                    guard let binaryTarget = target.underlyingTarget as? BinaryTarget else {
+                    guard let binaryTarget = target.underlying as? BinaryTarget else {
                         throw InternalError("invalid binary target '\(target.name)'")
                     }
                     switch binaryTarget.kind {

Sources/Build/BuildPlan/BuildPlan+Swift.swift

@@ -21,7 +21,7 @@ extension BuildPlan {
         // depends on.
         let environment = swiftTarget.buildParameters.buildEnvironment
         for case .target(let dependency, _) in try swiftTarget.target.recursiveDependencies(satisfying: environment) {
-            switch dependency.underlyingTarget {
+            switch dependency.underlying {
             case let underlyingTarget as ClangTarget where underlyingTarget.type == .library:
                 guard case let .clang(target)? = targetMap[dependency] else {
                     throw InternalError("unexpected clang target \(underlyingTarget)")