Tweak grouped-diagnostics formatting to put the primary diagnostics up front

One of the usability issues with the new grouped diagnostics code is
that the actual error/warning/remark buried within the source code,
with only a header like

    === t.swift:1 ===

to show where the issue occurs. Instead, display the diagnostic
file:line:column and text right up front, the same way as the existing
compiler's style, e.g.,

    t.swift:5:3: error: no exact matches in call to global function 'f'

The is better for humans, because it puts the primary issue right up
front, and also better for tools that scrape logs to find the
diagnostics using this form.

Author: DougGregor

Sources/SwiftDiagnostics/DiagnosticsFormatter.swift

@@ -176,20 +176,24 @@ public struct DiagnosticsFormatter {
     return resultSourceString
   }
 
+  struct PrimaryDiagnostic {
+    var location: SourceLocation
+    var diagnostic: Diagnostic
+  }
+
   /// Print given diagnostics for a given syntax tree on the command line
   ///
   /// - Parameters:
   ///   - suffixTexts: suffix text to be printed at the given absolute
   ///                  locations within the source file.
   func annotatedSource(
-    fileName: String?,
     tree: some SyntaxProtocol,
     diags: [Diagnostic],
     indentString: String,
     suffixTexts: [AbsolutePosition: String],
     sourceLocationConverter: SourceLocationConverter? = nil
   ) -> String {
-    let slc = sourceLocationConverter ?? SourceLocationConverter(fileName: fileName ?? "", tree: tree)
+    let slc = sourceLocationConverter ?? SourceLocationConverter(fileName: "<unknown>", tree: tree)
 
     // First, we need to put each line and its diagnostics together
     var annotatedSourceLines = [AnnotatedSourceLine]()
@@ -218,20 +222,9 @@ public struct DiagnosticsFormatter {
       return nil
     }
 
+    // Accumulate the fully annotated source files here.
     var annotatedSource = ""
 
-    // If there was a filename, add it first.
-    if let fileName {
-      let header = colorizeBufferOutline("===")
-      let firstLine =
-        1
-        + (annotatedSourceLines.enumerated().first { (lineIndex, sourceLine) in
-          !sourceLine.isFreeOfAnnotations
-        }?.offset ?? 0)
-
-      annotatedSource.append("\(indentString)\(header) \(fileName):\(firstLine) \(header)\n")
-    }
-
     /// Keep track if a line missing char should be printed
     var hasLineBeenSkipped = false
 
@@ -318,7 +311,6 @@ public struct DiagnosticsFormatter {
     diags: [Diagnostic]
   ) -> String {
     return annotatedSource(
-      fileName: nil,
       tree: tree,
       diags: diags,
       indentString: "",
@@ -328,7 +320,7 @@ public struct DiagnosticsFormatter {
 
   /// Annotates the given ``DiagnosticMessage`` with an appropriate ANSI color code (if the value of the `colorize`
   /// property is `true`) and returns the result as a printable string.
-  private func colorizeIfRequested(_ message: DiagnosticMessage) -> String {
+  func colorizeIfRequested(_ message: DiagnosticMessage) -> String {
     switch message.severity {
     case .error:
       let annotation = ANSIAnnotation(color: .red, trait: .bold)

Sources/SwiftDiagnostics/GroupedDiagnostics.swift

@@ -133,6 +133,31 @@ extension GroupedDiagnostics {
     }
   }
 
+  // Find the "primary" diagnostic that will be shown at the top of the diagnostic
+  // message. This is typically the error, warning, or remark.
+  private func findPrimaryDiagnostic(in sourceFile: SourceFile) -> (SourceFile, Diagnostic)? {
+    // If there is a non-note diagnostic, it's the primary diagnostic.
+    if let primaryDiag = sourceFile.diagnostics.first(where: { $0.diagMessage.severity != .note }) {
+      return (sourceFile, primaryDiag)
+    }
+
+    // If one of our child source files has a primary diagnostic, return that.
+    for childID in sourceFile.children {
+      if let foundInChild = findPrimaryDiagnostic(in: sourceFiles[childID.id]) {
+        return foundInChild
+      }
+    }
+
+    // If this is a root note, take the first note.
+    if sourceFile.parent == nil,
+       let note = sourceFile.diagnostics.first {
+      return (sourceFile, note)
+    }
+
+    // There is no primary diagnostic.
+    return nil
+  }
+
   /// Annotate the source for a given source file ID, embedding its child
   /// source files.
   func annotateSource(
@@ -168,7 +193,17 @@ extension GroupedDiagnostics {
     let suffixString: String
 
     if isRoot {
-      prefixString = ""
+      // If there's a primary diagnostic,
+      if let (primaryDiagSourceFile, primaryDiag) = findPrimaryDiagnostic(in: sourceFile) {
+        let primaryDiagSLC = SourceLocationConverter(fileName: primaryDiagSourceFile.displayName, tree: primaryDiagSourceFile.tree)
+        let location = primaryDiag.location(converter: primaryDiagSLC)
+
+        prefixString = "\(location.file):\(location.line):\(location.column): \(formatter.colorizeIfRequested(primaryDiag.diagMessage))\n"
+      } else {
+        let firstLine = sourceFile.diagnostics.first.map { $0.location(converter: slc).line } ?? 0
+        prefixString = "\(sourceFile.displayName): \(firstLine):"
+      }
+
       suffixString = ""
     } else {
       let padding = indentString.dropLast(1)
@@ -190,7 +225,6 @@ extension GroupedDiagnostics {
     // Render the buffer.
     return prefixString
       + formatter.annotatedSource(
-        fileName: isRoot ? sourceFile.displayName : nil,
         tree: sourceFile.tree,
         diags: sourceFile.diagnostics,
         indentString: colorizeBufferOutline(indentString),

Tests/SwiftDiagnosticsTest/GroupDiagnosticsFormatterTests.swift

@@ -112,8 +112,7 @@ final class GroupedDiagnosticsFormatterTests: XCTestCase {
     assertStringsEqualWithDiff(
       annotated,
       """
-      === main.swift:5 ===
-        ┆
+      main.swift:6:14: error: expected ')' to end function call
       3 │ // test
       4 │ let pi = 3.14159
       5 │ #myAssert(pi == 3)
@@ -141,7 +140,7 @@ final class GroupedDiagnosticsFormatterTests: XCTestCase {
       """
       let pi = 3.14159
       1️⃣#myAssert(pi == 3)
-      print("hello"
+      print("hello")
       """,
       displayName: "main.swift",
       extraDiagnostics: ["1️⃣": ("in expansion of macro 'myAssert' here", .note)]
@@ -181,7 +180,7 @@ final class GroupedDiagnosticsFormatterTests: XCTestCase {
     assertStringsEqualWithDiff(
       annotated,
       """
-      === main.swift:2 ===
+      #invertedEqualityCheck:1:7: error: no matching operator '==' for types 'Double' and 'Int'
       1 │ let pi = 3.14159
       2 │ #myAssert(pi == 3)
         │ ╰─ note: in expansion of macro 'myAssert' here
@@ -197,8 +196,7 @@ final class GroupedDiagnosticsFormatterTests: XCTestCase {
         │4 │   fatalError("assertion failed: pi != 3")
         │5 │ }
         ╰─────────────────────────────────────────────────────────────────────
-      3 │ print("hello"
-        │              ╰─ error: expected ')' to end function call
+      3 │ print("hello")
 
       """
     )