Add a new API DiagnosticsFormatter.formattedMessage(_:) for messages without source location info

Some tools want to use the diagnostics formatter to produce diagnostics
that don't relate to source code, or for which the source code isn't
available. This API allows them to do so while maintaining consistent
presentation. The first client is the compiler itself, when it doesn't
have a source location for a specific diagnostic.

Author: DougGregor

Release Notes/602.md

@@ -12,6 +12,11 @@
   - Pull Request: https://github.com/swiftlang/swift-syntax/pull/2981
   - Migration steps: None required. The new `category` property has optional type, and there is a default implementation that returns `nil`. Types that conform to `DiagnosticMessage` can choose to implement this property and provide a category when appropriate.
 
+- `DiagnosticsFormatter` has a new method, `formattedMessage`, that formats a diagnostic message without any corresponding syntax node.
+  - Description: Some tools want to use the diagnostics formatter to produce diagnostics that don't relate to source code, or for which the source code isn't available. This API allows them to do so while maintaining consistent presentation.
+  - Pull Request: TBD
+  - Migration steps: None required.
+
 - `FixIt.Change` has a new case `replaceText` that performs a textual replacement of a range of text with another string.
   - Description: The other `FixIt.Change` cases provide structured
     modifications to syntax trees, such as replacing specific notes. Some

Sources/SwiftDiagnostics/DiagnosticsFormatter.swift

@@ -360,6 +360,12 @@ public struct DiagnosticsFormatter {
     )
   }
 
+  /// Produce a string that formats the given diagnostic message with any
+  /// source-location information.
+  public func formattedMessage(_ message: some DiagnosticMessage) -> String {
+    diagnosticDecorator.decorateDiagnosticMessage(message)
+  }
+
   /// Produce a string containing "footnotes" for each of the diagnostic
   /// category provided that has associated documentation. Each category
   /// is printed in Markdown link format, e.g.,

Tests/SwiftDiagnosticsTest/DiagnosticFormatterTests.swift

@@ -0,0 +1,31 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See https://swift.org/LICENSE.txt for license information
+// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftDiagnostics
+import XCTest
+
+final class DiagnosticFormatterTests: XCTestCase {
+  func testFormattedMessage() {
+    let message = SimpleDiagnosticMessage(
+      message: "something went wrong",
+      diagnosticID: MessageID(domain: "swift-syntax", id: "testing"),
+      severity: .error,
+      category: DiagnosticCategory(
+        name: "Testing",
+        documentationURL: "http://example.com"
+      )
+    )
+
+    let formattedText = DiagnosticsFormatter().formattedMessage(message)
+    XCTAssertEqual(formattedText, "error: something went wrong [#Testing]")
+  }
+}