From 14e4fc4e58b30be079939fca6a61f7e669c154ad Mon Sep 17 00:00:00 2001
From: Doug Gregor <dgregor@apple.com>
Date: Wed, 16 Apr 2025 17:39:25 -0700
Subject: [PATCH 1/2] 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.
---
 Release Notes/602.md                          |  5 +++
 .../DiagnosticsFormatter.swift                |  6 ++++
 .../DiagnosticFormatterTests.swift            | 31 +++++++++++++++++++
 3 files changed, 42 insertions(+)
 create mode 100644 Tests/SwiftDiagnosticsTest/DiagnosticFormatterTests.swift

diff --git a/Release Notes/602.md b/Release Notes/602.md
index 12c16b08703..66a9a9d6017 100644
--- a/Release Notes/602.md	
+++ b/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
diff --git a/Sources/SwiftDiagnostics/DiagnosticsFormatter.swift b/Sources/SwiftDiagnostics/DiagnosticsFormatter.swift
index 9717ecb4ac7..e93bc1d609f 100644
--- a/Sources/SwiftDiagnostics/DiagnosticsFormatter.swift
+++ b/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.,
diff --git a/Tests/SwiftDiagnosticsTest/DiagnosticFormatterTests.swift b/Tests/SwiftDiagnosticsTest/DiagnosticFormatterTests.swift
new file mode 100644
index 00000000000..2980b046504
--- /dev/null
+++ b/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]")
+  }
+}

From 8ced3b647ecbaafcf8e8ba294c77c1c82caae0e5 Mon Sep 17 00:00:00 2001
From: Doug Gregor <dgregor@apple.com>
Date: Wed, 16 Apr 2025 17:41:49 -0700
Subject: [PATCH 2/2] Add pull request number

---
 Release Notes/602.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Release Notes/602.md b/Release Notes/602.md
index 66a9a9d6017..0d5750bdd2e 100644
--- a/Release Notes/602.md	
+++ b/Release Notes/602.md	
@@ -14,7 +14,7 @@
 
 - `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
+  - Pull Request: https://github.com/swiftlang/swift-syntax/pull/3059
   - Migration steps: None required.
 
 - `FixIt.Change` has a new case `replaceText` that performs a textual replacement of a range of text with another string.