mark several FileSystem APIs as disfavored overloads (#418)

motivation: help the transition off of TSC Path and FileSystem

changes:
* mark several FileSystem APIs that return AbsolutePath as disfavored overloads
* deprecate Product which is really a SwiftPM construct

Author: tomerd

Sources/TSCBasic/FileSystem.swift

@@ -148,6 +148,7 @@ public enum FileMode: Sendable {
 /// - Note: All of these APIs are synchronous and can block.
 public protocol FileSystem: Sendable {
     /// Check whether the given path exists and is accessible.
+    @_disfavoredOverload
     func exists(_ path: AbsolutePath, followSymlink: Bool) -> Bool
 
     /// Check whether the given path is accessible and a directory.
@@ -183,6 +184,7 @@ public protocol FileSystem: Sendable {
     /// The current working directory can be empty if e.g. the directory became
     /// unavailable while the current process was still working in it.
     /// This follows the POSIX `getcwd(3)` semantics.
+    @_disfavoredOverload
     var currentWorkingDirectory: AbsolutePath? { get }
 
     /// Change the current working directory.
@@ -191,12 +193,15 @@ public protocol FileSystem: Sendable {
     func changeCurrentWorkingDirectory(to path: AbsolutePath) throws
 
     /// Get the home directory of current user
+    @_disfavoredOverload
     var homeDirectory: AbsolutePath { get throws }
 
     /// Get the caches directory of current user
+    @_disfavoredOverload
     var cachesDirectory: AbsolutePath? { get }
 
     /// Get the temp directory
+    @_disfavoredOverload
     var tempDirectory: AbsolutePath { get throws }
 
     /// Create the given directory.
@@ -259,6 +264,7 @@ public protocol FileSystem: Sendable {
 /// methods).
 public extension FileSystem {
     /// exists override with default value.
+    @_disfavoredOverload
     func exists(_ path: AbsolutePath) -> Bool {
         return exists(path, followSymlink: true)
     }
@@ -275,6 +281,7 @@ public extension FileSystem {
 
     // Unless the file system type provides an override for this method, throw
     // if `atomically` is `true`, otherwise fall back to whatever implementation already exists.
+    @_disfavoredOverload
     func writeFileContents(_ path: AbsolutePath, bytes: ByteString, atomically: Bool) throws {
         guard !atomically else {
             throw FileSystemError(.unsupported, path)
@@ -283,6 +290,7 @@ public extension FileSystem {
     }
 
     /// Write to a file from a stream producer.
+    @_disfavoredOverload
     func writeFileContents(_ path: AbsolutePath, body: (WritableByteStream) -> Void) throws {
         let contents = BufferedOutputByteStream()
         body(contents)

Sources/TSCTestSupport/Product.swift

@@ -18,6 +18,7 @@ import TSCUtility
 import class Foundation.Bundle
 #endif
 
+@available(*, deprecated, message: "moved to SwiftPM")
 public enum SwiftPMProductError: Swift.Error {
     case packagePathNotFound
     case executionFailure(error: Swift.Error, output: String, stderr: String)
@@ -26,10 +27,12 @@ public enum SwiftPMProductError: Swift.Error {
 /// Defines the executables used by SwiftPM.
 /// Contains path to the currently built executable and
 /// helper method to execute them.
+@available(*, deprecated, message: "moved to SwiftPM")
 public protocol Product {
     var exec: RelativePath { get }
 }
 
+@available(*, deprecated, message: "moved to SwiftPM")
 extension Product {
     /// Path to currently built binary.
     public var path: AbsolutePath {