Provide context necessary to resolve identity conflict. (#8390)

Update error messaging to be a bit more clear where the conflict of
identities is coming from.

### Motivation:

#8311 — when multiple packages share the same identity (for example:
`gh/swiftlang/swift-driver` and `gh/apple/swift-driver` share the same
identity `swift-driver`) then the error doesn't help to resolve the
conflict. It is particularly confusing when the conflicting package is
pulled from transitive dependencies. I wanted to offer more context to
resolve these types of conflicts, particularly:

 - how the conflict is introduced in relation to the root package
- itemize all paths for both sides of the conflict, so that users can
better understand how to approach resolution, but not overwhelm the
error message with too many details

### Modifications:

- Rephrase error message for clarity, add a suggestion to work with
maintainers of transitive dependencies.
- Reconstruct the dependency chains from roots to the conflicting
packages.

### Result:

Before: 

`'swift-build': 'swift-build' dependency on
'https://github.com/swiftlang/swift-driver.git' conflicts with
dependency on 'https://github.com/apple/swift-driver.git' which has the
same identity 'swift-driver'.`

After:

`Conflicting identity for swift-driver: dependency
'github.com/swiftlang/swift-driver' and dependency
'github.com/apple/swift-driver' both point to the same package identity
'swift-driver'. The dependencies are introduced through the following
chains: (A)
/users/yy/pub/swift-package-manager->github.com/swiftlang/swift-build->github.com/swiftlang/swift-driver
(B) /users/yy/pub/swift-package-manager->github.com/apple/swift-driver.
If there are multiple chains that lead to the same dependency, only the
first chain is shown here. To see all chains use debug output option. To
resolve the conflict, coordinate with the maintainer of the package that
introduces the conflicting dependency.
`

Plus also debug logs:

`debug: 'swift-build': Conflicting identity for swift-driver: chains of
dependencies for https://github.com/swiftlang/swift-driver.git:
[[/users/yy/pub/swift-package-manager, github.com/swiftlang/swift-build,
github.com/swiftlang/swift-driver]]`

`debug: 'swift-build': Conflicting identity for swift-driver: chains of
dependencies for https://github.com/apple/swift-driver.git:
[[/users/yy/pub/swift-package-manager, github.com/apple/swift-driver]]`

Author: yyvch

Sources/PackageGraph/ModulesGraph+Loading.swift

@@ -336,6 +336,45 @@ fileprivate extension ResolvedProduct {
     }
 }
 
+/// Find all transitive dependencies between `root` and `dependency`.
+/// - root: A root package to start search from
+/// - dependency: A dependency which to find transitive dependencies for.
+/// - graph: List of resolved package builders representing a dependency graph.
+/// The function returns all possible dependency chains, each chain is a list of nodes representing transitive
+/// dependencies between `root` and `dependency`. A dependency chain
+/// "A root depends on B, which depends on C" is returned as [Root, B, C].
+/// If `root` doesn't actually depend on `dependency` then the function returns empty list.
+private func findAllTransitiveDependencies(
+    root: CanonicalPackageLocation,
+    dependency: CanonicalPackageLocation,
+    graph: [ResolvedPackageBuilder]
+) throws -> [[CanonicalPackageLocation]] {
+    let edges = try Dictionary(uniqueKeysWithValues: graph.map { try (
+        $0.package.manifest.canonicalPackageLocation,
+        Set(
+            $0.package.manifest.dependenciesRequired(for: $0.productFilter, $0.enabledTraits)
+                .map(\.packageRef.canonicalLocation)
+        )
+    ) })
+    // Use BFS to find paths between start and finish.
+    var queue: [(CanonicalPackageLocation, [CanonicalPackageLocation])] = []
+    var foundPaths: [[CanonicalPackageLocation]] = []
+    queue.append((root, []))
+    while !queue.isEmpty {
+        let currentItem = queue.removeFirst()
+        let current = currentItem.0
+        let pathToCurrent = currentItem.1
+        if current == dependency {
+            let pathToFinish = pathToCurrent + [current]
+            foundPaths.append(pathToFinish)
+        }
+        for dependency in edges[current] ?? [] {
+            queue.append((dependency, pathToCurrent + [current]))
+        }
+    }
+    return foundPaths
+}
+
 /// Create resolved packages from the loaded packages.
 private func createResolvedPackages(
     nodes: [GraphLoadingNode],
@@ -410,9 +449,9 @@ private func createResolvedPackages(
                 guard dependencies[resolvedPackage.package.identity] == nil else {
                     let error = PackageGraphError.dependencyAlreadySatisfiedByIdentifier(
                         package: package.identity.description,
-                        dependencyLocation: dependencyPackageRef.locationString,
-                        otherDependencyURL: resolvedPackage.package.manifest.packageLocation,
-                        identity: dependency.identity
+                        identity: dependency.identity,
+                        dependencyLocation: dependencyPackageRef.canonicalLocation.description,
+                        otherDependencyLocation: resolvedPackage.package.manifest.canonicalPackageLocation.description,
                     )
                     return packageObservabilityScope.emit(error)
                 }
@@ -423,11 +462,40 @@ private func createResolvedPackages(
                 if resolvedPackage.package.manifest.canonicalPackageLocation != dependencyPackageRef
                     .canonicalLocation && !resolvedPackage.allowedToOverride
                 {
+                    let rootPackages = packageBuilders.filter { $0.allowedToOverride == true }
+                    let dependenciesPaths = try rootPackages.map { try findAllTransitiveDependencies(
+                        root: $0.package.manifest.canonicalPackageLocation,
+                        dependency: dependencyPackageRef.canonicalLocation,
+                        graph: packageBuilders
+                    ) }.filter { !$0.isEmpty }.flatMap { $0 }
+                    let otherDependenciesPaths = try rootPackages.map { try findAllTransitiveDependencies(
+                        root: $0.package.manifest.canonicalPackageLocation,
+                        dependency: resolvedPackage.package.manifest.canonicalPackageLocation,
+                        graph: packageBuilders
+                    ) }.filter { !$0.isEmpty }.flatMap { $0 }
+                    packageObservabilityScope
+                        .emit(
+                            debug: (
+                                "Conflicting identity for \(dependency.identity): " +
+                                "chains of dependencies for \(dependencyPackageRef.locationString): " +
+                                "\(String(describing: dependenciesPaths))"
+                            )
+                        )
+                    packageObservabilityScope
+                        .emit(
+                            debug: (
+                                "Conflicting identity for \(dependency.identity): " +
+                                "chains of dependencies for \(resolvedPackage.package.manifest.packageLocation): " +
+                                "\(String(describing: otherDependenciesPaths))"
+                            )
+                        )
                     let error = PackageGraphError.dependencyAlreadySatisfiedByIdentifier(
                         package: package.identity.description,
-                        dependencyLocation: dependencyPackageRef.locationString,
-                        otherDependencyURL: resolvedPackage.package.manifest.packageLocation,
-                        identity: dependency.identity
+                        identity: dependency.identity,
+                        dependencyLocation: dependencyPackageRef.canonicalLocation.description,
+                        otherDependencyLocation: resolvedPackage.package.manifest.canonicalPackageLocation.description,
+                        dependencyPath: (dependenciesPaths.first ?? []).map(\.description),
+                        otherDependencyPath: (otherDependenciesPaths.first ?? []).map(\.description)
                     )
                     // 9/2021 this is currently emitting a warning only to support
                     // backwards compatibility with older versions of SwiftPM that had too weak of a validation
@@ -439,7 +507,7 @@ private func createResolvedPackages(
                         packageObservabilityScope
                             .emit(
                                 warning: error
-                                    .description + ". this will be escalated to an error in future versions of SwiftPM."
+                                    .description + " This will be escalated to an error in future versions of SwiftPM."
                             )
                     } else {
                         return packageObservabilityScope.emit(error)

Sources/PackageGraph/ModulesGraph.swift

@@ -36,11 +36,19 @@ enum PackageGraphError: Swift.Error {
     )
 
     /// The package dependency already satisfied by a different dependency package
+    ///  - package: Package for which the dependency conflict was detected.
+    ///  - identity: Conflicting identity.
+    ///  - dependencyLocation: Dependency from the current package which triggered the conflict.
+    ///  - otherDependencyLocation: Conflicting dependency from another package.
+    ///  - dependencyPath: a dependency path as a list of locations from the root to the dependency that triggered the conflict.
+    ///  - otherDependencyPath: a dependency path as a list of locations from the root to the conflicting dependency from another package.
     case dependencyAlreadySatisfiedByIdentifier(
         package: String,
+        identity: PackageIdentity,
         dependencyLocation: String,
-        otherDependencyURL: String,
-        identity: PackageIdentity
+        otherDependencyLocation: String,
+        dependencyPath: [String] = [],
+        otherDependencyPath: [String] = []
     )
 
     /// The package dependency already satisfied by a different dependency package
@@ -300,8 +308,30 @@ extension PackageGraphError: CustomStringConvertible {
                 }
                 return description
             }
-        case .dependencyAlreadySatisfiedByIdentifier(let package, let dependencyURL, let otherDependencyURL, let identity):
-            return "'\(package)' dependency on '\(dependencyURL)' conflicts with dependency on '\(otherDependencyURL)' which has the same identity '\(identity)'"
+        case .dependencyAlreadySatisfiedByIdentifier(
+            _,
+            let identity,
+            let dependencyURL,
+            let otherDependencyURL,
+            let dependencyPath,
+            let otherDependencyPath
+        ):
+            var description =
+                "Conflicting identity for \(identity): " +
+                "dependency '\(dependencyURL)' and dependency '\(otherDependencyURL)' " +
+                "both point to the same package identity '\(identity)'."
+            if !dependencyPath.isEmpty && !otherDependencyPath.isEmpty {
+                let chainA = dependencyPath.map { String(describing: $0) }.joined(separator: "->")
+                let chainB = otherDependencyPath.map { String(describing: $0) }.joined(separator: "->")
+                description += (
+                    " The dependencies are introduced through the following chains: " +
+                    "(A) \(chainA) (B) \(chainB). If there are multiple chains that lead to the same dependency, " +
+                    "only the first chain is shown here. To see all chains use debug output option. " +
+                    "To resolve the conflict, coordinate with the maintainer of the package " +
+                    "that introduces the conflicting dependency."
+                )
+            }
+            return description
 
         case .dependencyAlreadySatisfiedByName(let package, let dependencyURL, let otherDependencyURL, let name):
             return "'\(package)' dependency on '\(dependencyURL)' conflicts with dependency on '\(otherDependencyURL)' which has the same explicit name '\(name)'"

Sources/PackageModel/PackageIdentity.swift

@@ -413,7 +413,7 @@ struct PackageIdentityParser {
 ///   ```
 ///   file:///Users/mona/LinkedList → /Users/mona/LinkedList
 ///   ```
-public struct CanonicalPackageLocation: Equatable, CustomStringConvertible {
+public struct CanonicalPackageLocation: Equatable, CustomStringConvertible, Hashable {
     /// A textual representation of this instance.
     public let description: String