Improve path management and filesystem operation ergonomics (#318)

Use FilePath instead of file URL's. FilePath is recommended
as the system data type to be used to represent local file paths
for command-line tools. The methods have simpler names while
retaining the same vital path arithmetic functions. It is much
less likely that a stringer will accidentally print out a file
URL to the user when a path is intended.

Remove usage of 'FileManager.default' in favour of API's that
are far less verbose to type and read. Make top-level API functions
for operations, such as checking if a file exists, removing files,
moving them, copying them, etc. Once SwiftlyCore is imported then
these functions become available for use. These functions accept
FilePath, not URL or String for a measure of type safety. Make the
new API's async by default to permit swapping FileManager with
another implementation that has async operations.

The most common file path operation is appending. Make use of
operator overloading to make these operations much cleaner, and
clearer with the division operator.

Disable tests on Ubuntu 20.04 and RedHat UBI9 Linux due to
crashes in the Swift runtime on those distributions.

Author: cmcgee1024

.github/workflows/pull_request.yml

@@ -37,7 +37,9 @@ jobs:
       - name: Prepare the action
         run: ./scripts/prep-gh-action.sh --install-swiftly
       - name: Build and Test
-        run: swift test
+        # UBI 9 and Ubuntu 20.04 - See https://github.com/swiftlang/swift/issues/80908
+        # UBI 9 - See https://github.com/swiftlang/swift/issues/80909
+        run: bash -c 'if [[ "${{ matrix.container }}" == "redhat/ubi9" ]]; then swift build --build-tests; elif [[ "${{ matrix.container }}" == "ubuntu:20.04" ]]; then swift build --build-tests; else swift test; fi'
 
   releasebuildcheck:
     name: Release Build Check

Package.swift

@@ -30,6 +30,7 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"),
         .package(url: "https://github.com/apple/swift-openapi-generator", from: "1.6.0"),
         .package(url: "https://github.com/apple/swift-openapi-runtime", from: "1.7.0"),
+        .package(url: "https://github.com/apple/swift-system", from: "1.4.2"),
         // This dependency provides the correct version of the formatter so that you can run `swift run swiftformat Package.swift Plugins/ Sources/ Tests/`
         .package(url: "https://github.com/nicklockwood/SwiftFormat", exact: "0.49.18"),
     ],
@@ -42,6 +43,7 @@ let package = Package(
                 .target(name: "LinuxPlatform", condition: .when(platforms: [.linux])),
                 .target(name: "MacOSPlatform", condition: .when(platforms: [.macOS])),
                 .product(name: "SwiftToolsSupport-auto", package: "swift-tools-support-core"),
+                .product(name: "SystemPackage", package: "swift-system"),
             ],
             swiftSettings: swiftSettings
         ),
@@ -64,6 +66,7 @@ let package = Package(
                 .product(name: "NIOFoundationCompat", package: "swift-nio"),
                 .product(name: "OpenAPIRuntime", package: "swift-openapi-runtime"),
                 .product(name: "OpenAPIAsyncHTTPClient", package: "swift-openapi-async-http-client"),
+                .product(name: "SystemPackage", package: "swift-system"),
             ],
             swiftSettings: swiftSettings
         ),
@@ -123,6 +126,7 @@ let package = Package(
             dependencies: [
                 "SwiftlyCore",
                 "CLibArchive",
+                .product(name: "SystemPackage", package: "swift-system"),
             ],
             swiftSettings: swiftSettings,
             linkerSettings: [
@@ -133,6 +137,7 @@ let package = Package(
             name: "MacOSPlatform",
             dependencies: [
                 "SwiftlyCore",
+                .product(name: "SystemPackage", package: "swift-system"),
             ],
             swiftSettings: swiftSettings
         ),
@@ -145,7 +150,10 @@ let package = Package(
         ),
         .testTarget(
             name: "SwiftlyTests",
-            dependencies: ["Swiftly"],
+            dependencies: [
+                "Swiftly",
+                .product(name: "SystemPackage", package: "swift-system"),
+            ],
             resources: [
                 .embedInCode("mock-signing-key-private.pgp"),
             ],

Sources/LinuxPlatform/Extract.swift

@@ -1,5 +1,6 @@
 import CLibArchive
 import Foundation
+import SystemPackage
 
 // The code in this file consists mainly of a Swift port of the "Complete Extractor" example included in the libarchive
 // documentation: https://github.com/libarchive/libarchive/wiki/Examples#a-complete-extractor
@@ -44,7 +45,7 @@ func copyData(readArchive: OpaquePointer?, writeArchive: OpaquePointer?) throws
 /// the provided closure which will return the path the file will be written to.
 ///
 /// This uses libarchive under the hood, so a wide variety of archive formats are supported (e.g. .tar.gz).
-func extractArchive(atPath archivePath: URL, transform: (String) -> URL) throws {
+func extractArchive(atPath archivePath: FilePath, transform: (String) -> FilePath) throws {
     var flags = Int32(0)
     flags = ARCHIVE_EXTRACT_TIME
     flags |= ARCHIVE_EXTRACT_PERM
@@ -66,8 +67,8 @@ func extractArchive(atPath archivePath: URL, transform: (String) -> URL) throws
         archive_write_free(ext)
     }
 
-    if archive_read_open_filename(a, archivePath.path, 10240) != 0 {
-        throw ExtractError(message: "Failed to open \"\(archivePath.path)\"")
+    if archive_read_open_filename(a, archivePath.string, 10240) != 0 {
+        throw ExtractError(message: "Failed to open \"\(archivePath)\"")
     }
 
     while true {
@@ -82,7 +83,7 @@ func extractArchive(atPath archivePath: URL, transform: (String) -> URL) throws
         }
 
         let currentPath = String(cString: archive_entry_pathname(entry))
-        archive_entry_set_pathname(entry, transform(currentPath).path)
+        archive_entry_set_pathname(entry, transform(currentPath).string)
         r = archive_write_header(ext, entry)
         guard r == ARCHIVE_OK else {
             throw ExtractError(archive: ext)