improve error message when Package.resolved cannot be loaded

motivation: provide clear and actionable information when trying to load pacakge.resolved file from a non-supported version, or otherwise malformed.

changes:
* add contextual information to error message
* add few tests

Author: tomerd

Sources/Basics/FileSystem+Extensions.swift

@@ -11,6 +11,7 @@
 import class Foundation.FileManager
 import struct Foundation.Data
 import TSCBasic
+import PackageDescription
 
 // MARK: - user level
 
@@ -118,8 +119,19 @@ extension FileSystem {
     public func readFileContents(_ path: AbsolutePath) throws -> Data {
         return try Data(self.readFileContents(path).contents)
     }
-
+    
+    public func readFileContents(_ path: AbsolutePath) throws -> String {
+        guard let string = try String(data: self.readFileContents(path), encoding: .utf8) else {
+            throw StringError("invalid UTF8 string")
+        }
+        return string
+    }
+    
     public func writeFileContents(_ path: AbsolutePath, data: Data) throws {
-        return try self.writeFileContents(path, bytes: ByteString(data))
+        return try self.writeFileContents(path, bytes: .init(data))
+    }
+    
+    public func writeFileContents(_ path: AbsolutePath, string: String) throws {
+        return try self.writeFileContents(path, bytes: .init(encodingAsUTF8: string))
     }
 }

Sources/PackageGraph/PinsStore.swift

@@ -139,7 +139,7 @@ fileprivate struct PinsStorage {
                     partial[iterator.packageRef.identity] = iterator
                 }
             default:
-                throw InternalError("unknown RepositoryManager version: \(version)")
+                throw StringError("unknown '\(Self.self)' version '\(version.version)' at '\(self.path)'.")
             }
         }
     }

Sources/SourceControl/RepositoryManager.swift

@@ -469,7 +469,7 @@ fileprivate struct RepositoryManagerStorage {
                 let v1 = try self.decoder.decode(path: self.path, fileSystem: self.fileSystem, as: V1.self)
                 return try v1.object.repositories.mapValues{ try .init($0, manager: manager) }
             default:
-                throw InternalError("unknown RepositoryManager version: \(version)")
+                throw StringError("unknown '\(Self.self)' version '\(version.version)' at '\(self.path)'")
             }
         }
     }

Sources/Workspace/WorkspaceState.swift

@@ -98,7 +98,7 @@ fileprivate struct WorkspaceStateStorage {
                 let artifacts = v4.object.artifacts.map{ Workspace.ManagedArtifact($0) }
                 return (dependencies: .init(dependencyMap: dependencyMap), artifacts: .init(artifacts))
             default:
-                throw InternalError("unknown RepositoryManager version: \(version)")
+                throw StringError("unknown '\(Self.self)' version '\(version.version)' at '\(self.path)'")
             }
         }
     }

Tests/WorkspaceTests/PinsStoreTests.swift

@@ -106,40 +106,100 @@ final class PinsStoreTests: XCTestCase {
         let fs = InMemoryFileSystem()
         let pinsFile = AbsolutePath("/pinsfile.txt")
 
-        try fs.writeFileContents(pinsFile) {
-            $0 <<< """
-                {
-                  "object": {
-                    "pins": [
-                      {
-                        "package": "Clang_C",
-                        "repositoryURL": "https://github.com/something/Clang_C.git",
-                        "state": {
-                          "branch": null,
-                          "revision": "90a9574276f0fd17f02f58979423c3fd4d73b59e",
-                          "version": "1.0.2",
-                        }
-                      },
-                      {
-                        "package": "Commandant",
-                        "repositoryURL": "https://github.com/something/Commandant.git",
-                        "state": {
-                          "branch": null,
-                          "revision": "c281992c31c3f41c48b5036c5a38185eaec32626",
-                          "version": "0.12.0"
-                        }
-                      }
-                    ]
+        try fs.writeFileContents(pinsFile, string:
+            """
+            {
+              "version": 1,
+              "object": {
+                "pins": [
+                  {
+                    "package": "Clang_C",
+                    "repositoryURL": "https://github.com/something/Clang_C.git",
+                    "state": {
+                      "branch": null,
+                      "revision": "90a9574276f0fd17f02f58979423c3fd4d73b59e",
+                      "version": "1.0.2",
+                    }
                   },
-                  "version": 1
-                }
-                """
-        }
+                  {
+                    "package": "Commandant",
+                    "repositoryURL": "https://github.com/something/Commandant.git",
+                    "state": {
+                      "branch": null,
+                      "revision": "c281992c31c3f41c48b5036c5a38185eaec32626",
+                      "version": "0.12.0"
+                    }
+                  }
+                ]
+              }
+            }
+            """
+        )
 
         let store = try PinsStore(pinsFile: pinsFile, workingDirectory: .root, fileSystem: fs, mirrors: .init())
         XCTAssertEqual(store.pinsMap.keys.map { $0.description }.sorted(), ["clang_c", "commandant"])
     }
 
+    func testLoadingSchema2() throws {
+        let fs = InMemoryFileSystem()
+        let pinsFile = AbsolutePath("/pinsfile.txt")
+
+        try fs.writeFileContents(pinsFile, string:
+            """
+            {
+                "version": 2,
+                "pins": [
+                  {
+                    "identity": "clang_c",
+                    "location": "https://github.com/something/Clang_C.git",
+                    "state": {
+                      "branch": null,
+                      "revision": "90a9574276f0fd17f02f58979423c3fd4d73b59e",
+                      "version": "1.0.2",
+                    }
+                  },
+                  {
+                    "identity": "commandant",
+                    "location": "https://github.com/something/Commandant.git",
+                    "state": {
+                      "branch": null,
+                      "revision": "c281992c31c3f41c48b5036c5a38185eaec32626",
+                      "version": "0.12.0"
+                    }
+                  }
+                ]
+            }
+            """
+        )
+
+        let store = try PinsStore(pinsFile: pinsFile, workingDirectory: .root, fileSystem: fs, mirrors: .init())
+        XCTAssertEqual(store.pinsMap.keys.map { $0.description }.sorted(), ["clang_c", "commandant"])
+    }
+
+    func testLoadingUnknownSchemaVersion() throws {
+        let fs = InMemoryFileSystem()
+        let pinsFile = AbsolutePath("/pinsfile.txt")
+
+        let version = -1
+        try fs.writeFileContents(pinsFile, string: "{ \"version\": \(version) }");
+
+        XCTAssertThrowsError(try PinsStore(pinsFile: pinsFile, workingDirectory: .root, fileSystem: fs, mirrors: .init()), "error expected", { error in
+            XCTAssertEqual("\(error)", "Package.resolved file is corrupted or malformed; fix or delete the file to continue: unknown 'PinsStorage' version '\(version)' at '\(pinsFile)'.")
+        })
+
+    }
+
+    func testLoadingBadFormat() throws {
+        let fs = InMemoryFileSystem()
+        let pinsFile = AbsolutePath("/pinsfile.txt")
+
+        try fs.writeFileContents(pinsFile, string: "boom")
+
+        XCTAssertThrowsError(try PinsStore(pinsFile: pinsFile, workingDirectory: .root, fileSystem: fs, mirrors: .init()), "error expected", { error in
+            XCTAssertMatch("\(error)", .contains("Package.resolved file is corrupted or malformed; fix or delete the file to continue"))
+        })
+    }
+
     func testEmptyPins() throws {
         let fs = InMemoryFileSystem()
         let pinsFile = AbsolutePath("/pinsfile.txt")