Add new providedLibrary package reference kind

This kind of reference is going to be returned by package
resolution if it detects that a provided library version
matches all of the constraints.

This makes it easier to handle provided libraries post-resolution
instead of eliding them completely.

Author: xedin

Sources/Build/BuildPlan/BuildPlan.swift

@@ -740,7 +740,7 @@ extension ResolvedPackage {
         switch self.underlying.manifest.packageKind {
         case .registry, .remoteSourceControl, .localSourceControl:
             return true
-        case .root, .fileSystem:
+        case .root, .fileSystem, .providedLibrary:
             return false
         }
     }

Sources/PackageGraph/ModulesGraph.swift

@@ -358,7 +358,8 @@ extension PackageGraphError: CustomStringConvertible {
                 switch $0.manifest.packageKind {
                 case .root(let path),
                         .fileSystem(let path),
-                        .localSourceControl(let path):
+                        .localSourceControl(let path),
+                        .providedLibrary(let path):
                     description += " (at '\(path)')"
                 case .remoteSourceControl(let url):
                     description += " (from '\(url)')"

Sources/PackageGraph/Resolution/PubGrub/PubGrubDependencyResolver.swift

@@ -897,7 +897,7 @@ extension PackageRequirement {
 extension PackageReference {
     public func matchingPrebuiltLibrary(in availableLibraries: [LibraryMetadata]) -> LibraryMetadata? {
         switch self.kind {
-        case .fileSystem, .localSourceControl, .root:
+        case .fileSystem, .localSourceControl, .root, .providedLibrary:
             return nil // can never match a prebuilt library
         case .registry(let identity):
             if let registryIdentity = identity.registry {

Sources/PackageLoading/ManifestJSONParser.swift

@@ -83,7 +83,7 @@ enum ManifestJSONParser {
         case .localSourceControl(let _packagePath):
             // we have a more accurate path than the virtual one
             packagePath = _packagePath
-        case .root(let _packagePath), .fileSystem(let _packagePath):
+        case .root(let _packagePath), .fileSystem(let _packagePath), .providedLibrary(let _packagePath):
             // we dont have a more accurate path, and they should be the same
             // asserting (debug only) to make sure refactoring is correct 11/2023
             assert(packagePath == _packagePath, "expecting package path '\(packagePath)' to be the same as '\(_packagePath)'")

Sources/PackageModel/IdentityResolver.swift

@@ -46,6 +46,8 @@ public struct DefaultIdentityResolver: IdentityResolver {
             return try self.resolveIdentity(for: url)
         case .registry(let identity):
             return identity
+        case .providedLibrary(let path):
+            return try self.resolveIdentity(for: path)
         }
     }
 

Sources/PackageModel/PackageReference.swift

@@ -34,6 +34,9 @@ public struct PackageReference {
         /// A package from  a registry.
         case registry(PackageIdentity)
 
+        /// A prebuilt library provided by a toolchain
+        case providedLibrary(AbsolutePath)
+
         // FIXME: we should not need this once we migrate off URLs
         //@available(*, deprecated)
         public var locationString: String {
@@ -49,6 +52,8 @@ public struct PackageReference {
             case .registry(let identity):
                 // FIXME: this is a placeholder
                 return identity.description
+            case .providedLibrary(let path):
+                return path.pathString
             }
         }
 
@@ -70,6 +75,8 @@ public struct PackageReference {
                 return "remoteSourceControl \(url)"
             case .registry(let identity):
                 return "registry \(identity)"
+            case .providedLibrary(let path):
+                return "library \(path)"
             }
         }
 
@@ -124,6 +131,8 @@ public struct PackageReference {
         case .registry(let identity):
             // FIXME: this is a placeholder
             self.deprecatedName = name ?? identity.description
+        case .providedLibrary(let path):
+            self.deprecatedName = name ?? PackageIdentityParser.computeDefaultName(fromPath: path)
         }
     }
 
@@ -151,6 +160,10 @@ public struct PackageReference {
     public static func registry(identity: PackageIdentity) -> PackageReference {
         PackageReference(identity: identity, kind: .registry(identity))
     }
+
+    public static func library(identity: PackageIdentity, path: AbsolutePath) -> PackageReference {
+        PackageReference(identity: identity, kind: .providedLibrary(path))
+    }
 }
 
 extension PackageReference: Equatable {
@@ -203,7 +216,7 @@ extension PackageReference: CustomStringConvertible {
 
 extension PackageReference.Kind: Encodable {
     private enum CodingKeys: String, CodingKey {
-        case root, fileSystem, localSourceControl, remoteSourceControl, registry
+        case root, fileSystem, localSourceControl, remoteSourceControl, registry, providedLibrary
     }
 
     public func encode(to encoder: Encoder) throws {
@@ -224,6 +237,9 @@ extension PackageReference.Kind: Encodable {
         case .registry:
             var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .registry)
             try unkeyedContainer.encode(self.isRoot)
+        case .providedLibrary(let path):
+            var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .providedLibrary)
+            try unkeyedContainer.encode(path)
         }
     }
 }

Sources/SPMBuildCore/Plugins/PluginContextSerializer.swift

@@ -240,6 +240,8 @@ internal struct PluginContextSerializer {
                 return .repository(url: url.absoluteString, displayVersion: String(describing: package.manifest.version), scmRevision: String(describing: package.manifest.revision))
             case .registry(let identity):
                 return .registry(identity: identity.description, displayVersion: String(describing: package.manifest.version))
+            case .providedLibrary(_):
+                throw InternalError("provided libraries are not supported in plugin context")
             }
         }
 

Sources/SPMTestSupport/MockManifestLoader.swift

@@ -109,6 +109,9 @@ extension ManifestLoader {
             packageIdentity = identity
             // FIXME: placeholder
             packageLocation = identity.description
+        case .providedLibrary(let path):
+            packageIdentity = try identityResolver.resolveIdentity(for: path)
+            packageLocation = path.pathString
         }
         return try await self.load(
             manifestPath: manifestPath,
@@ -156,6 +159,9 @@ extension ManifestLoader {
             packageIdentity = identity
             // FIXME: placeholder
             packageLocation = identity.description
+        case .providedLibrary(let path):
+            packageIdentity = try identityResolver.resolveIdentity(for: path)
+            packageLocation = path.pathString
         }
         return try await self.load(
             packagePath: packagePath,

Sources/SPMTestSupport/MockWorkspace.swift

@@ -1041,6 +1041,8 @@ extension PackageReference.Kind {
             return "remoteSourceControl"
         case .registry:
             return "registry"
+        case .providedLibrary:
+            return "library"
         }
     }
 }

Sources/Workspace/CMakeLists.txt

@@ -15,6 +15,7 @@ add_library(Workspace
   ManagedArtifact.swift
   ManagedDependency.swift
   PackageContainer/FileSystemPackageContainer.swift
+  PackageContainer/ProvidedLibraryPackageContainer.swift
   PackageContainer/RegistryPackageContainer.swift
   PackageContainer/SourceControlPackageContainer.swift
   ResolvedFileWatcher.swift

Sources/Workspace/Diagnostics.swift

@@ -185,7 +185,7 @@ extension Basics.Diagnostic {
                 return "'\(identity.description)'"
             case .remoteSourceControl(let url):
                 return "'\($0.identity)' from \(url)"
-            case .localSourceControl(let path), .fileSystem(let path), .root(let path):
+            case .localSourceControl(let path), .fileSystem(let path), .root(let path), .providedLibrary(let path):
                 return "'\($0.identity)' at \(path)"
             }
         }

Sources/Workspace/PackageContainer/ProvidedLibraryPackageContainer.swift

@@ -0,0 +1,74 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2014-2024 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Basics
+import Dispatch
+import PackageGraph
+import PackageLoading
+import PackageModel
+
+import struct TSCUtility.Version
+
+public struct ProvidedLibraryPackageContainer: PackageContainer {
+    public let package: PackageReference
+
+    /// Observability scope to emit diagnostics
+    private let observabilityScope: ObservabilityScope
+
+    public init(
+        package: PackageReference,
+        observabilityScope: ObservabilityScope
+    ) throws {
+        switch package.kind {
+        case .providedLibrary:
+            break
+        default:
+            throw InternalError("invalid package type \(package.kind)")
+        }
+        self.package = package
+        self.observabilityScope = observabilityScope.makeChildScope(
+            description: "ProvidedLibraryPackageContainer",
+            metadata: package.diagnosticsMetadata)
+    }
+
+    public func isToolsVersionCompatible(at version: Version) -> Bool {
+        true
+    }
+
+    public func toolsVersion(for version: Version) throws -> ToolsVersion {
+        .v6_0
+    }
+
+    public func toolsVersionsAppropriateVersionsDescending() throws -> [Version] {
+        return try versionsDescending()
+    }
+
+    public func versionsAscending() throws -> [Version] {
+        [] // TODO
+    }
+
+    public func getDependencies(at version: Version, productFilter: ProductFilter) throws -> [PackageContainerConstraint] {
+        []
+    }
+
+    public func getDependencies(at revision: String, productFilter: ProductFilter) throws -> [PackageContainerConstraint] {
+        []
+    }
+
+    public func getUnversionedDependencies(productFilter: ProductFilter) throws -> [PackageContainerConstraint] {
+        []
+    }
+
+    public func loadPackageReference(at boundVersion: BoundVersion) throws -> PackageReference {
+        package
+    }
+}

Sources/Workspace/Workspace+PackageContainer.swift

@@ -93,6 +93,14 @@ extension Workspace: PackageContainerProvider {
                 queue.async {
                     completion(.success(container))
                 }
+
+            case .providedLibrary:
+                let container = try ProvidedLibraryPackageContainer(
+                    package: package,
+                    observabilityScope: observabilityScope)
+                queue.async {
+                    completion(.success(container))
+                }
             }
         } catch {
             queue.async {

Sources/Workspace/Workspace+State.swift

@@ -440,6 +440,9 @@ extension WorkspaceStateStorage {
                     self.kind = .registry
                     // FIXME: placeholder
                     self.location = self.identity.description
+                case .providedLibrary(let path):
+                    self.kind = .providedLibrary
+                    self.location = path.pathString
                 }
                 self.name = reference.deprecatedName
             }
@@ -450,6 +453,7 @@ extension WorkspaceStateStorage {
                 case localSourceControl
                 case remoteSourceControl
                 case registry
+                case providedLibrary
             }
         }
     }
@@ -492,6 +496,8 @@ extension PackageModel.PackageReference {
             kind = .remoteSourceControl(SourceControlURL(reference.location))
         case .registry:
             kind = .registry(identity)
+        case .providedLibrary:
+            kind = try .providedLibrary(.init(validating: reference.location))
         }
 
         self.init(
@@ -766,6 +772,9 @@ extension WorkspaceStateStorage {
                     self.kind = .registry
                     // FIXME: placeholder
                     self.location = self.identity.description
+                case .providedLibrary(let path):
+                    self.kind = .providedLibrary
+                    self.location = path.pathString
                 }
                 self.name = reference.deprecatedName
             }
@@ -776,6 +785,7 @@ extension WorkspaceStateStorage {
                 case localSourceControl
                 case remoteSourceControl
                 case registry
+                case providedLibrary
             }
         }
     }
@@ -819,6 +829,8 @@ extension PackageModel.PackageReference {
             kind = .remoteSourceControl(SourceControlURL(reference.location))
         case .registry:
             kind = .registry(identity)
+        case .providedLibrary:
+            kind = try .providedLibrary(.init(validating: reference.location))
         }
 
         self.init(

Sources/Workspace/Workspace.swift

@@ -1269,6 +1269,8 @@ extension Workspace {
             try self.removeRepository(dependency: dependencyToRemove)
         case .registry:
             try self.removeRegistryArchive(for: dependencyToRemove)
+        case .providedLibrary:
+            break // NOOP
         }
 
         // Save the state.

Tests/PackageLoadingTests/PDLoadingTests.swift

@@ -97,6 +97,8 @@ class PackageDescriptionLoadingTests: XCTestCase, ManifestLoaderDelegate {
             packagePath = path
         case .remoteSourceControl, .registry:
             packagePath = .root
+        case .providedLibrary(let path):
+            packagePath = path
         }
 
         let toolsVersion = toolsVersion