feat(v1.0.4): Add error handling, timeout, and diagnostics improvements

- Wrap process execution in error handling to prevent crashes
- Add 5-minute timeout to prevent indefinite hangs
- Standardize logging with Diagnostics API instead of print()
- Add file count feedback to LintPlugin
- Add troubleshooting documentation to README

Author: oleksiikolomiietssnapp

Plugins/FormatPlugin/FormatPlugin.swift

@@ -71,7 +71,7 @@ struct FormatPlugin: CommandPlugin {
         formatArguments += allSourceFiles.map { $0.path(percentEncoded: false) }
 
         // Print what we're about to do
-        print("Formatting \(allSourceFiles.count) Swift files in \(targetsToFormat.count) target(s)...")
+        Diagnostics.remark("Formatting \(allSourceFiles.count) Swift files in \(targetsToFormat.count) target(s)...")
 
         // Execute swift-format
         let process = Process()
@@ -83,50 +83,61 @@ struct FormatPlugin: CommandPlugin {
         process.standardOutput = outputPipe
         process.standardError = errorPipe
 
-        try process.run()
-        process.waitUntilExit()
+        do {
+            try process.run()
 
-        // Handle output
-        let outputData = outputPipe.fileHandleForReading.readDataToEndOfFile()
-        let errorData = errorPipe.fileHandleForReading.readDataToEndOfFile()
+            // Wait for process with 5-minute timeout
+            let timeout: TimeInterval = 300  // 5 minutes
+            let deadline = Date().addingTimeInterval(timeout)
 
-        if let output = String(data: outputData, encoding: .utf8), !output.isEmpty {
-            print(output)
-        }
+            while process.isRunning && Date() < deadline {
+                try await Task.sleep(nanoseconds: 100_000_000)  // 0.1 seconds
+            }
 
-        if let errorOutput = String(data: errorData, encoding: .utf8), !errorOutput.isEmpty {
-            printError(errorOutput)
-        }
+            if process.isRunning {
+                process.terminate()
+                Diagnostics.error("swift-format timed out after \(Int(timeout))s and was terminated")
+                return
+            }
 
-        if process.terminationStatus == 0 {
-            print("✅ Formatting completed successfully!")
-        } else {
-            Diagnostics.error("swift-format failed with exit code \(process.terminationStatus)")
+            // Handle output
+            let outputData = outputPipe.fileHandleForReading.readDataToEndOfFile()
+            let errorData = errorPipe.fileHandleForReading.readDataToEndOfFile()
+
+            if let output = String(data: outputData, encoding: .utf8), !output.isEmpty {
+                Diagnostics.remark(output)
+            }
+
+            if let errorOutput = String(data: errorData, encoding: .utf8), !errorOutput.isEmpty {
+                Diagnostics.warning(errorOutput)
+            }
+
+            if process.terminationStatus == 0 {
+                Diagnostics.remark("Formatting completed successfully!")
+            } else {
+                Diagnostics.error("swift-format failed with exit code \(process.terminationStatus)")
+            }
+        } catch {
+            Diagnostics.error("Failed to execute swift-format: \(error.localizedDescription)")
         }
     }
 
     /// Finds configuration file in package root.
     /// Supports both .swiftformat and .swift-format naming conventions.
     private func findConfigurationFile(in packageDirectory: URL) -> URL? {
+        let fileManager = FileManager.default
         let swiftformatConfig = packageDirectory.appending(path: ".swiftformat")
         let swiftFormatConfig = packageDirectory.appending(path: ".swift-format")
 
         // Prefer .swiftformat first
-        if FileManager.default.fileExists(atPath: swiftformatConfig.path) {
+        if fileManager.fileExists(atPath: swiftformatConfig.path) {
             return swiftformatConfig
         }
         // Fall back to .swift-format
-        if FileManager.default.fileExists(atPath: swiftFormatConfig.path) {
+        if fileManager.fileExists(atPath: swiftFormatConfig.path) {
             return swiftFormatConfig
         }
 
         return nil
     }
 }
-
-// Helper for printing to stderr
-fileprivate func printError(_ message: String) {
-    if let data = message.data(using: .utf8) {
-        FileHandle.standardError.write(data)
-    }
-}

Plugins/LintPlugin/LintPlugin.swift

@@ -25,6 +25,8 @@ struct LintPlugin: BuildToolPlugin {
             .filter { $0.type == .source && $0.url.pathExtension == "swift" }
             .map { $0.url }
 
+        Diagnostics.remark("Linting \(swiftSourceFiles.count) Swift file(s)...")
+
         guard !swiftSourceFiles.isEmpty else {
             return []
         }
@@ -67,15 +69,16 @@ struct LintPlugin: BuildToolPlugin {
     /// Finds configuration file in package root.
     /// Supports both .swiftformat and .swift-format naming conventions.
     private func findConfigurationFile(in packageDirectory: URL) -> URL? {
+        let fileManager = FileManager.default
         let swiftformatConfig = packageDirectory.appending(path: ".swiftformat")
         let swiftFormatConfig = packageDirectory.appending(path: ".swift-format")
 
         // Prefer .swiftformat first
-        if FileManager.default.fileExists(atPath: swiftformatConfig.path) {
+        if fileManager.fileExists(atPath: swiftformatConfig.path) {
             return swiftformatConfig
         }
         // Fall back to .swift-format
-        if FileManager.default.fileExists(atPath: swiftFormatConfig.path) {
+        if fileManager.fileExists(atPath: swiftFormatConfig.path) {
             return swiftFormatConfig
         }
 
@@ -95,6 +98,8 @@ extension LintPlugin: XcodeBuildToolPlugin {
             .filter { $0.type == .source && $0.url.pathExtension == "swift" }
             .map { $0.url }
 
+        Diagnostics.remark("Linting \(swiftSourceFiles.count) Swift file(s) in Xcode project...")
+
         guard !swiftSourceFiles.isEmpty else {
             return []
         }

README.md

@@ -85,6 +85,52 @@ Example:
 - swift-format tool (included in Xcode)
 - Xcode 14+ (for Xcode project support)
 
+## Troubleshooting
+
+### "swift-format not found" error
+
+The plugin requires swift-format to be installed in your Swift toolchain.
+
+**Solution:**
+- Ensure you have a recent Swift version installed (6.0+)
+- swift-format is included with Xcode
+- Run `swift-format --version` to verify it's available
+
+### Build hangs with Lint plugin
+
+The Lint plugin has a 5-minute timeout to prevent indefinite hangs, but extremely slow disk I/O could cause delays.
+
+**Solution:**
+- Check if your disk is full: `df -h`
+- Try building a smaller target first
+- Disable other background processes consuming I/O
+
+### "Configuration file not found" warning
+
+This is normal if you don't have a `.swiftformat` configuration file. The plugin will use swift-format's default rules.
+
+**Solution (optional):**
+- Create `.swiftformat` in your package root to customize rules
+- See [swift-format documentation](https://github.com/apple/swift-format) for configuration options
+
+### FormatPlugin fails with "Permission denied"
+
+The Format plugin needs write permission to your source files.
+
+**Solution:**
+- Ensure your project files are writable: `ls -l Sources/`
+- Approve the permission prompt when running the plugin
+- Check disk permissions: `chmod u+w Sources/**/*.swift`
+
+### No output from Lint plugin during build
+
+This is normal behavior. The Lint plugin runs silently unless there are formatting issues.
+
+**To verify it's running:**
+- Build with verbose output: `swift build -v`
+- Look for "Running SwiftFormat Lint" in the output
+- The plugin will show warnings if formatting issues are found
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) file.