Add a method Error.asDiagnostics(at:) to unpack errors into diagnostics

This is a useful convenience function to handle cases where we have a
thrown error from some API and we want to translate it into a
diagnostic that we need to emit at a particular location.

Author: DougGregor

Release Notes/601.md

@@ -11,6 +11,10 @@
   - Description: Returns the node or the first ancestor that satisfies `condition`.
   - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2696
 
+- `Error` protocol now has an `asDiagnostics(at:)` method.
+  - Description: This method translates an error into one or more diagnostics, recognizing `DiagnosticsError` and `DiagnosticMessage` instances or providing its own `Diagnostic` as needed.
+  - Pull Request: https://github.com/swiftlang/swift-syntax/pull/1816
+
 ## API Behavior Changes
 
 - `SyntaxProtocol.trimmed` detaches the node

Sources/SwiftDiagnostics/Diagnostic.swift

@@ -92,3 +92,38 @@ public struct DiagnosticsError: Error, Sendable {
     )
   }
 }
+
+/// Diagnostic message used for thrown errors.
+private struct DiagnosticFromError: DiagnosticMessage {
+  let error: Error
+  let severity: DiagnosticSeverity = .error
+
+  var message: String {
+    return String(describing: error)
+  }
+
+  var diagnosticID: MessageID {
+    .init(domain: "SwiftDiagnostics", id: "\(type(of: error))")
+  }
+}
+
+extension Error {
+  /// Given an error, produce an array of diagnostics reporting the error,
+  /// using the given syntax node as the location if it wasn't otherwise known.
+  ///
+  /// This operation will look for diagnostics of known type, such as
+  /// `DiagnosticsError` and `DiagnosticMessage` to retain information. If
+  /// none of those apply, it will produce an `error` diagnostic whose message
+  /// comes from rendering the error as a string.
+  public func asDiagnostics(at node: some SyntaxProtocol) -> [Diagnostic] {
+    if let diagnosticsError = self as? DiagnosticsError {
+      return diagnosticsError.diagnostics
+    }
+
+    if let message = self as? DiagnosticMessage {
+      return [Diagnostic(node: Syntax(node), message: message)]
+    }
+
+    return [Diagnostic(node: Syntax(node), message: DiagnosticFromError(error: self))]
+  }
+}

Sources/SwiftSyntaxMacros/MacroExpansionContext.swift

@@ -102,14 +102,23 @@ extension MacroExpansionContext {
   #endif
 }
 
-/// Diagnostic message used for thrown errors.
-private struct ThrownErrorDiagnostic: DiagnosticMessage {
-  let message: String
+private enum MacroExpansionContextError: DiagnosticMessage {
+  case internalError(SyntaxStringInterpolationInvalidNodeTypeError)
+  case missingError
+
+  var message: String {
+    switch self {
+    case .internalError(let error):
+      return "Internal macro error: \(error.description)"
+    case .missingError:
+      return "macro expansion failed without generating an error"
+    }
+  }
 
   var severity: DiagnosticSeverity { .error }
 
   var diagnosticID: MessageID {
-    .init(domain: "SwiftSyntaxMacros", id: "ThrownErrorDiagnostic")
+    .init(domain: "SwiftDiagnostics", id: "MacroExpansionContextError")
   }
 }
 
@@ -118,18 +127,15 @@ extension MacroExpansionContext {
   public func addDiagnostics(from error: Error, node: some SyntaxProtocol) {
     // Inspect the error to form an appropriate set of diagnostics.
     var diagnostics: [Diagnostic]
-    if let diagnosticsError = error as? DiagnosticsError {
-      diagnostics = diagnosticsError.diagnostics
-    } else if let message = error as? DiagnosticMessage {
-      diagnostics = [Diagnostic(node: Syntax(node), message: message)]
-    } else if let error = error as? SyntaxStringInterpolationInvalidNodeTypeError {
+
+    if let error = error as? SyntaxStringInterpolationInvalidNodeTypeError {
       let diagnostic = Diagnostic(
         node: Syntax(node),
-        message: ThrownErrorDiagnostic(message: "Internal macro error: \(error.description)")
+        message: MacroExpansionContextError.internalError(error)
       )
       diagnostics = [diagnostic]
     } else {
-      diagnostics = [Diagnostic(node: Syntax(node), message: ThrownErrorDiagnostic(message: String(describing: error)))]
+      diagnostics = error.asDiagnostics(at: node)
     }
 
     // Emit the diagnostics.
@@ -144,9 +150,7 @@ extension MacroExpansionContext {
       diagnose(
         Diagnostic(
           node: Syntax(node),
-          message: ThrownErrorDiagnostic(
-            message: "macro expansion failed without generating an error"
-          )
+          message: MacroExpansionContextError.missingError
         )
       )
     }