feat: Report formatter failures via the Xcode extension error banner

Previously every failure path called completionHandler(nil), so a failed
format silently did nothing on save. Surface the failures a user can act
on while keeping genuine no-ops silent.

Add FormatterError and FormatterOutcome.classify in the Shared layer: a
non-zero exit throws .failed carrying the formatter's stderr, a missing
executable throws .executableNotFound, and undecodable/unchanged/blank
output stays an .unchanged no-op. Make SourceEditorCommand.format throw
and route errors to completionHandler so Xcode shows its error banner;
keep the buffer mutation guarded behind the .formatted outcome.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: macmade

EditorExtension/SourceEditorCommand.swift

@@ -41,42 +41,56 @@ public class SourceEditorCommand: NSObject, XCSourceEditorCommand
 
         configuration.withConfigurations
         {
-            if uti == .swiftSource, let config = $0.swiftFormat?.path
+            do
             {
-                self.format( buffer: invocation.buffer, executable: "swiftformat", arguments: [ "--config", config ] )
+                if uti == .swiftSource, let config = $0.swiftFormat?.path
+                {
+                    try self.format( buffer: invocation.buffer, executable: "swiftformat", arguments: [ "--config", config ] )
+                }
+                else if let language = UncrustifyLanguage.argument( for: uti ), let config = $0.uncrustify?.path
+                {
+                    try self.format( buffer: invocation.buffer, executable: "uncrustify", arguments: [ "-c", config, "-l", language, "-q" ] )
+                }
+
+                $0.finished()
+                completionHandler( nil )
             }
-            else if let language = UncrustifyLanguage.argument( for: uti ), let config = $0.uncrustify?.path
+            catch
             {
-                self.format( buffer: invocation.buffer, executable: "uncrustify", arguments: [ "-c", config, "-l", language, "-q" ] )
+                $0.finished()
+                completionHandler( error )
             }
-
-            $0.finished()
-            completionHandler( nil )
         }
         error:
         {
             completionHandler( nil )
         }
     }
 
-    private func format( buffer: XCSourceTextBuffer, executable: String, arguments: [ String ] )
+    private func format( buffer: XCSourceTextBuffer, executable: String, arguments: [ String ] ) throws
     {
-        guard let data   = buffer.completeBuffer.data( using: .utf8 ),
-              let task   = Task.run( name: executable, arguments: arguments, input: data ),
-              let status = task.terminationStatus,
-              let out    = String( data: task.standardOutput, encoding: .utf8 ),
-              status     == 0
+        guard let data = buffer.completeBuffer.data( using: .utf8 )
         else
         {
             return
         }
 
-        if buffer.completeBuffer == out
+        guard let task = Task.run( name: executable, arguments: arguments, input: data )
+        else
         {
-            return
+            throw FormatterError.executableNotFound( executable )
+        }
+
+        guard let status = task.terminationStatus
+        else
+        {
+            throw FormatterError.failed( executable: executable, status: -1, message: "" )
         }
 
-        if out.trimmingCharacters( in: .whitespacesAndNewlines ).isEmpty
+        let outcome = try FormatterOutcome.classify( executable: executable, input: buffer.completeBuffer, status: status, standardOutput: task.standardOutput, standardError: task.standardError )
+
+        guard case .formatted( let out ) = outcome
+        else
         {
             return
         }

Shared/FormatterError.swift

@@ -0,0 +1,58 @@
+/*******************************************************************************
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2022, Jean-David Gadina - www.xs-labs.com
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the Software), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ ******************************************************************************/
+
+import Foundation
+
+/// A user-actionable formatting failure, surfaced through Xcode's extension
+/// error banner.
+public enum FormatterError: LocalizedError, Equatable
+{
+    /// The formatter executable could not be found / launched.
+    case executableNotFound( String )
+
+    /// The formatter ran but exited with a non-zero status. `message` carries
+    /// its captured standard-error text.
+    case failed( executable: String, status: Int32, message: String )
+
+    public var errorDescription: String?
+    {
+        switch self
+        {
+            case .executableNotFound( let name ):
+
+                return "The formatter “\( name )” could not be found."
+
+            case .failed( let executable, let status, let message ):
+
+                let detail = message.trimmingCharacters( in: .whitespacesAndNewlines )
+
+                if detail.isEmpty
+                {
+                    return "\( executable ) failed with status \( status )."
+                }
+
+                return "\( executable ) failed with status \( status ):\n\( detail )"
+        }
+    }
+}

Shared/FormatterOutcome.swift

@@ -0,0 +1,71 @@
+/*******************************************************************************
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2022, Jean-David Gadina - www.xs-labs.com
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the Software), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ ******************************************************************************/
+
+import Foundation
+
+/// The result of classifying a completed formatter run.
+public enum FormatterOutcome: Equatable
+{
+    /// Nothing to apply — the formatter made no change (or produced no usable
+    /// output). The buffer is left untouched and no error is reported.
+    case unchanged
+
+    /// The formatter produced new, non-empty output that should replace the
+    /// buffer's contents.
+    case formatted( String )
+
+    /// Classifies a finished formatter run into an outcome, throwing a
+    /// `FormatterError` for failures the user can act on.
+    ///
+    /// - A non-zero `status` throws `.failed`, carrying the formatter's stderr.
+    /// - Output that is undecodable, identical to the input, or empty after
+    ///   trimming is treated as `.unchanged` (a silent no-op).
+    /// - Otherwise the new output is returned as `.formatted`.
+    public static func classify( executable: String, input: String, status: Int32, standardOutput: Data, standardError: Data ) throws -> FormatterOutcome
+    {
+        guard status == 0
+        else
+        {
+            throw FormatterError.failed( executable: executable, status: status, message: String( data: standardError, encoding: .utf8 ) ?? "" )
+        }
+
+        guard let output = String( data: standardOutput, encoding: .utf8 )
+        else
+        {
+            return .unchanged
+        }
+
+        if output == input
+        {
+            return .unchanged
+        }
+
+        if output.trimmingCharacters( in: .whitespacesAndNewlines ).isEmpty
+        {
+            return .unchanged
+        }
+
+        return .formatted( output )
+    }
+}

SharedTests/FormatterErrorTests.swift

@@ -0,0 +1,61 @@
+/*******************************************************************************
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2022, Jean-David Gadina - www.xs-labs.com
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the Software), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ ******************************************************************************/
+
+import Foundation
+import Testing
+
+@Suite( "FormatterError" )
+struct FormatterErrorTests
+{
+    @Test( "Failed error description includes executable, status and stderr" )
+    func failedErrorDescription()
+    {
+        let error       = FormatterError.failed( executable: "uncrustify", status: 2, message: "  parse error\n" )
+        let description = error.errorDescription
+
+        #expect( description?.contains( "uncrustify" ) == true )
+        #expect( description?.contains( "2" ) == true )
+        #expect( description?.contains( "parse error" ) == true )
+    }
+
+    @Test( "Failed error description omits the colon when stderr is empty" )
+    func failedErrorDescriptionWithoutStderr() throws
+    {
+        let error       = FormatterError.failed( executable: "swiftformat", status: 1, message: "   \n" )
+        let description  = try #require( error.errorDescription )
+
+        #expect( description.contains( "swiftformat" ) )
+        #expect( description.contains( "1" ) )
+        #expect( description.hasSuffix( ":" ) == false )
+    }
+
+    @Test( "Executable-not-found error description includes the name" )
+    func executableNotFoundDescription() throws
+    {
+        let error       = FormatterError.executableNotFound( "swiftformat" )
+        let description = try #require( error.errorDescription )
+
+        #expect( description.contains( "swiftformat" ) )
+    }
+}

SharedTests/FormatterOutcomeTests.swift

@@ -0,0 +1,106 @@
+/*******************************************************************************
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2022, Jean-David Gadina - www.xs-labs.com
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the Software), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ ******************************************************************************/
+
+import Foundation
+import Testing
+
+@Suite( "FormatterOutcome.classify" )
+struct FormatterOutcomeTests
+{
+    private func data( _ string: String ) -> Data
+    {
+        Data( string.utf8 )
+    }
+
+    @Test( "Returns .formatted when output differs and is non-empty" )
+    func formattedWhenChanged() throws
+    {
+        let outcome = try FormatterOutcome.classify(
+            executable:     "swiftformat",
+            input:          "let x=1",
+            status:         0,
+            standardOutput: self.data( "let x = 1\n" ),
+            standardError:  Data()
+        )
+
+        #expect( outcome == .formatted( "let x = 1\n" ) )
+    }
+
+    @Test( "Returns .unchanged when output equals input" )
+    func unchangedWhenIdentical() throws
+    {
+        let outcome = try FormatterOutcome.classify(
+            executable:     "swiftformat",
+            input:          "let x = 1\n",
+            status:         0,
+            standardOutput: self.data( "let x = 1\n" ),
+            standardError:  Data()
+        )
+
+        #expect( outcome == .unchanged )
+    }
+
+    @Test( "Returns .unchanged when output is empty after trimming" )
+    func unchangedWhenBlankOutput() throws
+    {
+        let outcome = try FormatterOutcome.classify(
+            executable:     "swiftformat",
+            input:          "let x = 1\n",
+            status:         0,
+            standardOutput: self.data( "   \n\t " ),
+            standardError:  Data()
+        )
+
+        #expect( outcome == .unchanged )
+    }
+
+    @Test( "Returns .unchanged when output is completely empty" )
+    func unchangedWhenEmptyOutput() throws
+    {
+        let outcome = try FormatterOutcome.classify(
+            executable:     "swiftformat",
+            input:          "let x = 1\n",
+            status:         0,
+            standardOutput: Data(),
+            standardError:  Data()
+        )
+
+        #expect( outcome == .unchanged )
+    }
+
+    @Test( "Throws .failed with stderr text on a non-zero status" )
+    func throwsOnNonZeroStatus()
+    {
+        #expect( throws: FormatterError.failed( executable: "uncrustify", status: 1, message: "bad config at line 3" ) )
+        {
+            try FormatterOutcome.classify(
+                executable:     "uncrustify",
+                input:          "int x;",
+                status:         1,
+                standardOutput: Data(),
+                standardError:  self.data( "bad config at line 3" )
+            )
+        }
+    }
+}