Include search path for Swift Testing's macro plugin from toolchain if present (#8670)

This modifies the logic for determining compiler flags for locating
Swift Testing content such that it will always include a search path for
Swift Testing's macro plugin at its newer, testing-specific location in
the toolchain, if that directory exists.

### Motivation:

Swift Testing installs a macro plugin library named `TestingMacros` into
the official Swift toolchains for several platforms. By convention, most
Swift macro plugins are installed into the toolchain's
`usr/lib/swift/host/plugins` directory. However, testing libraries are
somewhat special in the sense that they should generally only be
available for use in "non-product" targets, i.e. targets which are not
intended for distribution and only intended for use in qualifying the
main product targets which _will_ be distributed.

For that reason, in Darwin toolchains, Swift Testing's plugin is
installed into a different location than for other platforms:
`usr/lib/swift/host/plugins/testing` (note the final `testing/`
directory) — see the [CMake
rules](https://github.com/swiftlang/swift-testing/blob/72afbb418542654781a6b7853479c7e70a862b6f/Sources/TestingMacros/CMakeLists.txt#L67-L75)
where that is controlled. Over time, we'd like to move the macro plugin
on other platforms to that location for consistency, because the current
_inconsistent_ install path has caused friction for users if they
attempt to form search paths to the plugin on their own — see
swiftlang/swift-testing#1039. So this PR paves
the way for Swift Testing to begin to relocate its plugin by ensuring
that _if_ this distinct plugin directory exists in a toolchain, it will
be preferred.

### Modifications:

- Modify logic in `UserToolchain.swift` to begin passing `-plugin-path`
whenever the relevant, testing-specific plugin path exists in a
toolchain.
- Add a new test which validates this, by simulating the scenario of
_not_ having a custom toolchain and validating the expected flags are
passed. (This most closely matches the current scenario today of using
the toolchain included in Xcode, and in that toolchain the plugin is
already installed into the `testing/`-suffixed path.)

rdar://151319768

Author: stmontgomery

Sources/PackageModel/UserToolchain.swift

@@ -636,26 +636,28 @@ public final class UserToolchain: Toolchain {
         )
 
         if triple.isMacOSX, let swiftTestingPath {
-            // swift-testing in CommandLineTools, needs extra frameworks search path
+            // Swift Testing is a framework (e.g. from CommandLineTools) so use -F.
             if swiftTestingPath.extension == "framework" {
                 swiftCompilerFlags += ["-F", swiftTestingPath.pathString]
-            }
 
-            // Otherwise we must have a custom toolchain, add overrides to find its swift-testing ahead of any in the
-            // SDK. We expect the library to be in `lib/swift/macosx/testing` and the plugin in
-            // `lib/swift/host/plugins/testing`
-            if let pluginsPath = try? AbsolutePath(
-                validating: "../../host/plugins/testing",
-                relativeTo: swiftTestingPath
-            ) {
+            // Otherwise Swift Testing is assumed to be a swiftmodule + library, so use -I and -L.
+            } else {
                 swiftCompilerFlags += [
                     "-I", swiftTestingPath.pathString,
                     "-L", swiftTestingPath.pathString,
-                    "-plugin-path", pluginsPath.pathString,
                 ]
             }
         }
 
+        // Specify the plugin path for Swift Testing's macro plugin if such a
+        // path exists in this toolchain.
+        if let swiftTestingPluginPath = Self.deriveSwiftTestingPluginPath(
+            derivedSwiftCompiler: swiftCompilers.compile,
+            fileSystem: fileSystem
+        ) {
+            swiftCompilerFlags += ["-plugin-path", swiftTestingPluginPath.pathString]
+        }
+
         swiftCompilerFlags += try Self.deriveSwiftCFlags(
             triple: triple,
             swiftSDK: swiftSDK,
@@ -1037,6 +1039,35 @@ public final class UserToolchain: Toolchain {
         return nil
     }
 
+    /// Derive the plugin path needed to locate the Swift Testing macro plugin,
+    /// if such a path exists in the toolchain of the specified compiler.
+    ///
+    /// - Parameters:
+    ///   - derivedSwiftCompiler: The derived path of the Swift compiler to use
+    ///       when deriving the Swift Testing plugin path.
+    ///   - fileSystem: The file system instance to use when validating the path
+    ///       to return.
+    ///
+    /// - Returns: A path to the directory containing Swift Testing's macro
+    ///     plugin, or `nil` if the path does not exist or cannot be determined.
+    ///
+    /// The path returned is a directory containing a library, suitable for
+    /// passing to a client compiler via the `-plugin-path` flag.
+    private static func deriveSwiftTestingPluginPath(
+        derivedSwiftCompiler: Basics.AbsolutePath,
+        fileSystem: any FileSystem
+    ) -> AbsolutePath? {
+        guard let toolchainLibDir = try? toolchainLibDir(swiftCompilerPath: derivedSwiftCompiler) else {
+            return nil
+        }
+
+        if let pluginsPath = try? AbsolutePath(validating: "swift/host/plugins/testing", relativeTo: toolchainLibDir), fileSystem.exists(pluginsPath) {
+            return pluginsPath
+        }
+
+        return nil
+    }
+
     public var sdkRootPath: AbsolutePath? {
         configuration.sdkRootPath
     }

Tests/BuildTests/BuildPlanTests.swift

@@ -4998,6 +4998,122 @@ class BuildPlanTestCase: BuildSystemProviderTestCase {
         ])
     }
 
+    func testSwiftTestingFlagsOnMacOSWithoutCustomToolchain() async throws {
+        #if !os(macOS)
+        // This is testing swift-testing in a toolchain which is macOS only feature.
+        try XCTSkipIf(true, "test is only supported on macOS")
+        #endif
+
+        let fs = InMemoryFileSystem(
+            emptyFiles:
+            "/fake/path/lib/swift/host/plugins/testing/libTestingMacros.dylib",
+            "/Pkg/Sources/Lib/main.swift",
+            "/Pkg/Tests/LibTest/test.swift"
+        )
+        try fs.createMockToolchain()
+
+        let userSwiftSDK = SwiftSDK(
+            hostTriple: .x86_64MacOS,
+            targetTriple: .x86_64MacOS,
+            toolset: .init(
+                knownTools: [
+                    .cCompiler: .init(extraCLIOptions: []),
+                    .swiftCompiler: .init(extraCLIOptions: []),
+                ],
+                rootPaths: ["/fake/path/to"]
+            ),
+            pathsConfiguration: .init(
+                sdkRootPath: "/fake/sdk",
+                swiftResourcesPath: "/fake/lib/swift",
+                swiftStaticResourcesPath: "/fake/lib/swift_static"
+            )
+        )
+
+        let env = Environment.mockEnvironment
+        let mockToolchain = try UserToolchain(
+            swiftSDK: userSwiftSDK,
+            environment: env,
+            searchStrategy: .custom(
+                searchPaths: getEnvSearchPaths(
+                    pathString: env[.path],
+                    currentWorkingDirectory: fs.currentWorkingDirectory
+                ),
+                useXcrun: true
+            ),
+            fileSystem: fs
+        )
+
+        XCTAssertEqual(
+            mockToolchain.extraFlags.swiftCompilerFlags,
+            [
+                "-plugin-path", "/fake/path/lib/swift/host/plugins/testing",
+                "-sdk", "/fake/sdk",
+            ]
+        )
+        XCTAssertNoMatch(mockToolchain.extraFlags.linkerFlags, ["-rpath"])
+        XCTAssertNoMatch(mockToolchain.extraFlags.swiftCompilerFlags, [
+            "-I", "/fake/path/lib/swift/macosx/testing",
+            "-L", "/fake/path/lib/swift/macosx/testing",
+        ])
+
+        let observability = ObservabilitySystem.makeForTesting()
+        let graph = try loadModulesGraph(
+            fileSystem: fs,
+            manifests: [
+                Manifest.createRootManifest(
+                    displayName: "Pkg",
+                    path: "/Pkg",
+                    targets: [
+                        TargetDescription(name: "Lib", dependencies: []),
+                        TargetDescription(
+                            name: "LibTest",
+                            dependencies: ["Lib"],
+                            type: .test
+                        ),
+                    ]
+                ),
+            ],
+            observabilityScope: observability.topScope
+        )
+        XCTAssertNoDiagnostics(observability.diagnostics)
+
+        let result = try await BuildPlanResult(plan: mockBuildPlan(
+            toolchain: mockToolchain,
+            graph: graph,
+            commonFlags: .init(),
+            fileSystem: fs,
+            observabilityScope: observability.topScope
+        ))
+        result.checkProductsCount(2)
+        result.checkTargetsCount(3)
+
+        let testProductLinkArgs = try result.buildProduct(for: "Lib").linkArguments()
+        XCTAssertNoMatch(testProductLinkArgs, [
+            "-I", "/fake/path/lib/swift/macosx/testing",
+            "-L", "/fake/path/lib/swift/macosx/testing",
+        ])
+
+        let libModuleArgs = try result.moduleBuildDescription(for: "Lib").swift().compileArguments()
+        XCTAssertMatch(libModuleArgs, [
+            "-plugin-path", "/fake/path/lib/swift/host/plugins/testing",
+        ])
+        XCTAssertNoMatch(libModuleArgs, ["-Xlinker"])
+        XCTAssertNoMatch(libModuleArgs, [
+            "-I", "/fake/path/lib/swift/macosx/testing",
+            "-L", "/fake/path/lib/swift/macosx/testing",
+        ])
+
+        let testModuleArgs = try result.moduleBuildDescription(for: "LibTest").swift().compileArguments()
+        XCTAssertMatch(testModuleArgs, [
+            "-plugin-path", "/fake/path/lib/swift/host/plugins/testing",
+        ])
+        XCTAssertNoMatch(testModuleArgs, ["-Xlinker"])
+        XCTAssertNoMatch(testModuleArgs, [
+            "-I", "/fake/path/lib/swift/macosx/testing",
+            "-L", "/fake/path/lib/swift/macosx/testing",
+        ])
+    }
+
     func testSwiftTestingFlagsOnMacOSWithCustomToolchain() async throws {
         #if !os(macOS)
         // This is testing swift-testing in a toolchain which is macOS only feature.
@@ -5007,7 +5123,7 @@ class BuildPlanTestCase: BuildSystemProviderTestCase {
         let fs = InMemoryFileSystem(
             emptyFiles:
             "/fake/path/lib/swift/macosx/testing/Testing.swiftmodule",
-            "/fake/path/lib/swift/host/plugins/testing/libTesting.dylib",
+            "/fake/path/lib/swift/host/plugins/testing/libTestingMacros.dylib",
             "/Pkg/Sources/Lib/main.swift",
             "/Pkg/Tests/LibTest/test.swift"
         )