Wrap all incoming errors for diagnostic purposes.

Author: dabrahams

.cursorrules

@@ -36,6 +36,8 @@ Avoid conditional compilation as it makes code that runs on other platforms impo
 
 Never swallow errors. When a function can fail, use `throws` to propagate descriptive errors rather than returning optionals or silently failing. This ensures failures are visible and debuggable.
 
+When system APIs or external processes throw errors, wrap them in `Failure` with contextual information about what operation was being performed. This makes errors easier to diagnose, especially on different platforms. For example, wrap file I/O errors with the path being accessed, and process execution errors with the command being run.
+
 When invoking `swiftc`, pass `-module-cache-path` with a temporary directory to avoid conflicts when running in parallel (e.g., during `swift test`).
 
 ## Naming Guidelines

Sources/gyb-swift/ExecutionContext.swift

@@ -134,7 +134,11 @@ struct CodeGenerator {
       try? FileManager.default.removeItem(at: temp)
     }
 
-    try swiftCode.write(to: temp, atomically: true, encoding: .utf8)
+    do {
+      try swiftCode.write(to: temp, atomically: true, encoding: .utf8)
+    } catch {
+      throw Failure("Failed to write temporary Swift file to '\(temp.path)'", error)
+    }
 
     let result = try runProcess("swift", arguments: [temp.platformString])
 
@@ -150,7 +154,11 @@ struct CodeGenerator {
     let tempFiles = createTempFiles()
     defer { cleanupTempFiles(tempFiles) }
 
-    try swiftCode.write(to: tempFiles.source, atomically: true, encoding: .utf8)
+    do {
+      try swiftCode.write(to: tempFiles.source, atomically: true, encoding: .utf8)
+    } catch {
+      throw Failure("Failed to write temporary Swift file to '\(tempFiles.source.path)'", error)
+    }
     try compileSwiftCode(
       source: tempFiles.source, output: tempFiles.executable, moduleCache: tempFiles.moduleCache)
     return try runCompiledExecutable(tempFiles.actualExecutable)

Sources/gyb-swift/ProcessUtilities.swift

@@ -38,13 +38,21 @@ private func runProcessForOutput(
   return result.stdout.trimmingCharacters(in: .whitespacesAndNewlines)
 }
 
-struct Failure: Error {
+struct Failure: Error, CustomStringConvertible {
   let reason: String
   let error: (any Error)?
+
   init(_ reason: String, _ error: (any Error)? = nil) {
     self.reason = reason
     self.error = error
   }
+
+  var description: String {
+    if let error = error {
+      return "\(reason): \(error)"
+    }
+    return reason
+  }
 }
 
 /// Searches for an executable in PATH on Windows using `where.exe`.
@@ -133,7 +141,11 @@ func runProcess(_ command: String, arguments: [String]) throws -> ProcessOutput
   process.standardOutput = stdoutPipe
   process.standardError = stderrPipe
 
-  try process.run()
+  do {
+    try process.run()
+  } catch {
+    throw Failure("Failed to run '\(command) \(arguments.joined(separator: " "))'", error)
+  }
 
   // Read pipes on background threads to prevent deadlock if output exceeds pipe buffer size.
   // The child process will block if pipe buffers fill up, so we must drain them continuously.

Sources/gyb-swift/gyb_swift.swift

@@ -142,7 +142,11 @@ struct GYBSwift: ParsableCommand {
     } else {
       // Read from file
       let source = URL(fileURLWithPath: file)
-      templateText = try String(contentsOf: source, encoding: .utf8)
+      do {
+        templateText = try String(contentsOf: source, encoding: .utf8)
+      } catch {
+        throw Failure("Failed to read template file '\(file)'", error)
+      }
       filename = file
     }
 
@@ -190,7 +194,11 @@ struct GYBSwift: ParsableCommand {
       print(result, terminator: "")
     } else {
       let destination = URL(fileURLWithPath: output)
-      try result.write(to: destination, atomically: true, encoding: .utf8)
+      do {
+        try result.write(to: destination, atomically: true, encoding: .utf8)
+      } catch {
+        throw Failure("Failed to write output to '\(output)'", error)
+      }
     }
   }
 }