diff --git a/Sources/SwiftDiagnostics/DiagnosticDecorators/DiagnosticDecorator.swift b/Sources/SwiftDiagnostics/DiagnosticDecorators/DiagnosticDecorator.swift
index 6b999b56d52..e3228803de3 100644
--- a/Sources/SwiftDiagnostics/DiagnosticDecorators/DiagnosticDecorator.swift
+++ b/Sources/SwiftDiagnostics/DiagnosticDecorators/DiagnosticDecorator.swift
@@ -36,6 +36,8 @@ protocol DiagnosticDecorator {
   /// - Parameters:
   ///   - message: The diagnostic message that needs to be decorated.
   ///   - severity: The severity level associated with the diagnostic message.
+  ///   - categoryChain: The category chain ordered leaf-first; see ``DiagnosticMessage/categoryChain-property``
+  ///                    for more.
   ///
   /// - Returns: A decorated version of the diagnostic message, enhanced by visual cues like color, text styles, or other markers,
   ///            as well as a severity-specific prefix, based on its severity level.
diff --git a/Sources/SwiftDiagnostics/DiagnosticsFormatter.swift b/Sources/SwiftDiagnostics/DiagnosticsFormatter.swift
index e93bc1d609f..873d4bfc73e 100644
--- a/Sources/SwiftDiagnostics/DiagnosticsFormatter.swift
+++ b/Sources/SwiftDiagnostics/DiagnosticsFormatter.swift
@@ -54,11 +54,27 @@ extension Sequence where Element == Range<Int> {
 }
 
 public struct DiagnosticsFormatter {
-
-  /// A wrapper struct for a source line, its diagnostics, and any
-  /// non-diagnostic text that follows the line.
+  /// A wrapper struct for a source line, its annotations (diagnostics
+  /// and notes), along with any non-diagnostic text that follows the line.
   private struct AnnotatedSourceLine {
-    var diagnostics: [Diagnostic]
+    // An abstraction for a diagnostic or note that is anchored to a source line.
+    enum Annotation {
+      case diagnostic(Diagnostic)
+      case note(Note)
+
+      func location(converter: SourceLocationConverter) -> SourceLocation {
+        switch self {
+        case .diagnostic(let diag):
+          return diag.location(converter: converter)
+        case .note(let note):
+          return note.location(converter: converter)
+        }
+      }
+    }
+
+    /// Annotations (diagnostics or notes) anchored to this source line.
+    var annotations: [Annotation]
+    /// The source line itself.
     var sourceString: String
 
     /// Non-diagnostic text that is appended after this source line.
@@ -70,7 +86,7 @@ public struct DiagnosticsFormatter {
 
     /// Whether this line is free of annotations.
     var isFreeOfAnnotations: Bool {
-      return diagnostics.isEmpty && suffixText.isEmpty
+      return annotations.isEmpty && suffixText.isEmpty
     }
 
     /// Converts a UTF-8 column index into an index that considers each character as a single column, not each UTF-8
@@ -126,15 +142,22 @@ public struct DiagnosticsFormatter {
     tree: some SyntaxProtocol,
     sourceLocationConverter slc: SourceLocationConverter
   ) -> String {
-    if annotatedLine.diagnostics.isEmpty {
+    if annotatedLine.annotations.isEmpty {
       return annotatedLine.sourceString
     }
 
     // Compute the set of highlight ranges that land on this line. These
     // are column ranges, sorted in order of increasing starting column, and
     // with overlapping ranges merged.
-    let highlightRanges: [Range<Int>] = annotatedLine.diagnostics.map {
-      $0.highlights
+    let highlightRanges: [Range<Int>] = annotatedLine.annotations.map { annotation in
+      // Only diagnostics have highlights; notes don't.
+      switch annotation {
+      case .diagnostic(let diag):
+        return diag.highlights
+      case .note:
+        // TODO: Should a note add a `note.node`
+        return []
+      }
     }.joined().compactMap { (highlight) -> Range<Int>? in
       if highlight.root != Syntax(tree) {
         return nil
@@ -206,37 +229,66 @@ public struct DiagnosticsFormatter {
   /// 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.
+  ///   - tree: The syntax tree for which diagnostics should be printed
+  ///   - diags: The diagnostics to print
+  ///   - indentString: The string prefixed to each line of the annotated
+  ///       source.
+  ///   - suffixTexts: Suffix text to be printed at the given absolute
+  ///       locations within the source file.
+  ///   - includeNotes: Whether notes should be included in the annotated source
+  ///   - sourceLocationConverter: The source location converter for computing
+  ///       line and column information for the diagnostics
   func annotatedSource(
     tree: some SyntaxProtocol,
     diags: [Diagnostic],
     indentString: String,
     suffixTexts: [AbsolutePosition: String],
+    includeNotes: Bool = true,
     sourceLocationConverter: SourceLocationConverter? = nil
   ) -> String {
     let slc = sourceLocationConverter ?? SourceLocationConverter(fileName: "<unknown>", tree: tree)
 
-    // First, we need to put each line and its diagnostics together
-    var annotatedSourceLines = [AnnotatedSourceLine]()
-
-    for (sourceLineIndex, sourceLine) in slc.sourceLines.enumerated() {
-      let diagsForLine = diags.filter { diag in
-        return diag.location(converter: slc).line == (sourceLineIndex + 1)
-      }
-      let suffixText = suffixTexts.compactMap { (position, text) in
-        if slc.location(for: position).line == (sourceLineIndex + 1) {
-          return text
+    // === Group Annotations By Line ===
+    //
+    // Group annotations by the line they are anchored to.
+    var annotationsPerLine = [Int: [AnnotatedSourceLine.Annotation]]()
+    // Add annotations to the map.
+    for diagnostic in diags {
+      // Add diagnostic to the map.
+      let line = diagnostic.location(converter: slc).line
+      annotationsPerLine[line, default: []].append(.diagnostic(diagnostic))
+
+      // Add notes to the map if includeNotes is true.
+      if includeNotes {
+        for note in diagnostic.notes {
+          let line = note.location(converter: slc).line
+          annotationsPerLine[line, default: []].append(.note(note))
         }
+      }
+    }
 
-        return nil
-      }.joined()
-
-      annotatedSourceLines.append(
-        AnnotatedSourceLine(diagnostics: diagsForLine, sourceString: sourceLine, suffixText: suffixText)
-      )
+    // Group suffix texts by the line they are anchored to, and add them to the map.
+    var suffixTextPerLine = [Int: String]()
+    for (position, text) in suffixTexts {
+      let line = slc.location(for: position).line
+      // Concatenate suffix texts if there are multiple for the same line.
+      suffixTextPerLine[line, default: ""].append(text)
     }
 
+    // Put each line and its diagnostics together.
+    let annotatedSourceLines: [AnnotatedSourceLine] = slc.sourceLines.enumerated()
+      .map { (sourceLineIndex, sourceLine) in
+        let lineNumber = sourceLineIndex + 1
+
+        return AnnotatedSourceLine(
+          annotations: annotationsPerLine[lineNumber] ?? [],
+          sourceString: sourceLine,
+          suffixText: suffixTextPerLine[lineNumber] ?? ""
+        )
+      }
+
+    // === Calculate Lines to Print ===
+    //
     // Only lines with diagnostic messages should be printed, but including some context
     let rangesToPrint = annotatedSourceLines.enumerated().compactMap { (lineIndex, sourceLine) -> Range<Int>? in
       let lineNumber = lineIndex + 1
@@ -246,14 +298,17 @@ public struct DiagnosticsFormatter {
       return nil
     }
 
+    // === Render Annotated Source ===
+    //
     // Accumulate the fully annotated source files here.
     var annotatedSource = ""
-
     /// Keep track if a line missing char should be printed
     var hasLineBeenSkipped = false
-
+    // The maximum number of digits in the line numbers.
+    // Helps calculate padding for line numbers.
     let maxNumberOfDigits = String(annotatedSourceLines.count).count
 
+    // Render each line and its annotations.
     for (lineIndex, annotatedLine) in annotatedSourceLines.enumerated() {
       let lineNumber = lineIndex + 1
       guard
@@ -265,7 +320,7 @@ public struct DiagnosticsFormatter {
         continue
       }
 
-      // line numbers should be right aligned
+      // Line numbers should be right aligned
       let lineNumberString = String(lineNumber)
       let leadingSpaces = String(repeating: " ", count: maxNumberOfDigits - lineNumberString.count)
       let linePrefix = "\(leadingSpaces)\(diagnosticDecorator.decorateBufferOutline("\(lineNumberString) |")) "
@@ -279,10 +334,10 @@ public struct DiagnosticsFormatter {
       }
       hasLineBeenSkipped = false
 
-      // add indentation
+      // Add indentation
       annotatedSource.append(indentString)
 
-      // print the source line
+      // Print the source line
       annotatedSource.append(linePrefix)
       annotatedSource.append(
         colorizeSourceLine(
@@ -293,30 +348,47 @@ public struct DiagnosticsFormatter {
         )
       )
 
-      // Remove any trailing newline and replace it; this may seem
-      // counterintuitive, but if we're running within CMake and we let a
-      // '\r\n' through, CMake will turn that into *two* newlines.
+      // Remove any trailing newline and replace it.
+      //
+      // This may seem counterintuitive, but if we're running within CMake
+      // and we let a '\r\n' through, CMake will turn that into *two* newlines.
       if let last = annotatedSource.last, last.isNewline {
         annotatedSource.removeLast()
       }
       annotatedSource.append("\n")
 
+      // Group annotations by column.
+      //
+      // Helps render multiple diagnostics in one line, e.g.
+      // 1 | foo.[].[].[]
+      //   |     |  |  `- error: expected name in member access
+      //   |     |  `- error: expected name in member access
+      //   |     `- error: expected name in member access
+      //
+      // First, identify the columns that have diagnostics. Helps
+      // place the "|" characters in the prefix string's previous lines.
       let columnsWithDiagnostics = Set(
-        annotatedLine.diagnostics.map {
-          annotatedLine.characterColumn(ofUtf8Column: $0.location(converter: slc).column)
+        annotatedLine.annotations.map { annotation in
+          annotatedLine.characterColumn(ofUtf8Column: annotation.location(converter: slc).column)
         }
       )
-      let diagsPerColumn = Dictionary(grouping: annotatedLine.diagnostics) { diag in
-        annotatedLine.characterColumn(ofUtf8Column: diag.location(converter: slc).column)
+      // Then, group annotations by column, and sort so that annotations for
+      // later columns are printed first.
+      let annotationsPerColumn = Dictionary(grouping: annotatedLine.annotations) { annotation in
+        annotatedLine.characterColumn(ofUtf8Column: annotation.location(converter: slc).column)
       }.sorted { lhs, rhs in
         lhs.key > rhs.key
       }
 
-      for (column, diags) in diagsPerColumn {
-        // compute the string that is shown before each message
+      // Print annotations from higher column to lower column.
+      for (column, lineAnnotations) in annotationsPerColumn {
+        // Compute the string that is shown before each message
+        //
+        // Add indentation and space for line numbers.
         var preMessage =
           indentString + String(repeating: " ", count: maxNumberOfDigits) + " "
           + diagnosticDecorator.decorateBufferOutline("|")
+        // Add "|" characters for each column that has diagnostics, up to the current column.
         for c in 0..<column {
           if columnsWithDiagnostics.contains(c) {
             preMessage.append("|")
@@ -325,12 +397,25 @@ public struct DiagnosticsFormatter {
           }
         }
 
-        for diag in diags.dropLast(1) {
-          annotatedSource.append("\(preMessage)|- \(diagnosticDecorator.decorateDiagnosticMessage(diag.diagMessage))\n")
+        // Print annotations for this column.
+        for (index, annotation) in lineAnnotations.enumerated() {
+          // Decorate the diagnostic or note using the diagnostic decorator.
+          let decoratedMessage =
+            switch annotation {
+            case .diagnostic(let diag):
+              diagnosticDecorator.decorateDiagnosticMessage(diag.diagMessage)
+            case .note(let note):
+              // Attached notes don't inherit the category chain of the main diagnostic.
+              diagnosticDecorator.decorateMessage(note.message, basedOnSeverity: .note, categoryChain: [])
+            }
+
+          // Compute annotation header
+          // We use "|-" for intermediate annotations, and "`-" for the last annotation.
+          let annotationHeader = (index == lineAnnotations.count - 1) ? "`-" : "|-"
+
+          // Add decorated message to the annotated source.
+          annotatedSource.append("\(preMessage)\(annotationHeader) \(decoratedMessage)\n")
         }
-        annotatedSource.append(
-          "\(preMessage)`- \(diagnosticDecorator.decorateDiagnosticMessage(diags.last!.diagMessage))\n"
-        )
       }
 
       // Add suffix text.
diff --git a/Sources/SwiftDiagnostics/GroupedDiagnostics.swift b/Sources/SwiftDiagnostics/GroupedDiagnostics.swift
index a1e8f507b6c..be38731c74b 100644
--- a/Sources/SwiftDiagnostics/GroupedDiagnostics.swift
+++ b/Sources/SwiftDiagnostics/GroupedDiagnostics.swift
@@ -16,6 +16,11 @@ public import SwiftSyntax
 import SwiftSyntax
 #endif
 
+/// A set of diagnostics spread across different source files
+/// but linked through source-code generation. For instance, an error
+/// occurs in a macro and additional errors/notes are emitted
+/// in the macro expansion buffer. We render the main diagnostic at the top
+/// of the message, and render the nested diagnostics in boxes underneath.
 public struct GroupedDiagnostics {
   /// A unique identifier for a source file.
   public struct SourceFileID: Equatable, Hashable {
diff --git a/Tests/SwiftDiagnosticsTest/GroupDiagnosticsFormatterTests.swift b/Tests/SwiftDiagnosticsTest/GroupDiagnosticsFormatterTests.swift
index d4892a26020..96d8bad7b20 100644
--- a/Tests/SwiftDiagnosticsTest/GroupDiagnosticsFormatterTests.swift
+++ b/Tests/SwiftDiagnosticsTest/GroupDiagnosticsFormatterTests.swift
@@ -147,7 +147,8 @@ final class GroupedDiagnosticsFormatterTests: XCTestCase {
         |5 | }
         +---------------------------------------------------------------------
       6 | print("hello"
-        |              `- error: expected ')' to end function call
+        |      |       `- error: expected ')' to end function call
+        |      `- note: to match this opening '('
 
       """
     )
@@ -234,6 +235,163 @@ final class GroupedDiagnosticsFormatterTests: XCTestCase {
     )
   }
 
+  func testGroupingForSameLineDiagnostics() {
+    var group = GroupedDiagnostics()
+
+    // Main source file.
+    let (mainSourceID, mainSourceMarkers) = group.addTestFile(
+      """
+      1️⃣let pi = 2️⃣"3.14159"
+      3️⃣#myAssert(pi == 4️⃣3)
+      print("hello")
+      """,
+      displayName: "main.swift",
+      diagnosticDescriptors: [
+        DiagnosticDescriptor(
+          locationMarker: "3️⃣",
+          message: "in expansion of macro 'myAssert' here", 
+          severity: .note,
+          noteDescriptors: [
+            NoteDescriptor(
+              locationMarker: "1️⃣", id: MessageID(domain: "test", id: "conjured"), 
+              message: "Inferred type 'String' here"
+            ),
+            NoteDescriptor(
+              locationMarker: "4️⃣", id: MessageID(domain: "test", id: "conjured"), 
+              message: "Inferred type 'Int' here"
+            )
+          ]
+        )
+      ]
+    )
+    let inExpansionNotePos = mainSourceMarkers["3️⃣"]!
+
+    // Outer expansion source file
+    let (outerExpansionSourceID, outerExpansionSourceMarkers) = group.addTestFile(
+      """
+      let 1️⃣__a = pi
+      let 2️⃣__b = 3
+      if 3️⃣#invertedEqualityCheck(__a, __b) {
+        fatalError("assertion failed: pi != 3")
+      }
+      """,
+      displayName: "#myAssert",
+      parent: (mainSourceID, inExpansionNotePos),
+      diagnosticDescriptors: [
+        DiagnosticDescriptor(
+          locationMarker: "3️⃣",
+          message: "in expansion of macro 'invertedEqualityCheck' here",
+          severity: .note,
+          noteDescriptors: [
+            NoteDescriptor(
+              locationMarker: "3️⃣", 
+              id: MessageID(domain: "test", id: "conjured"), 
+              message: "#invertedEqualityCheck expects operands of the same type"
+            ),
+            NoteDescriptor(
+              locationMarker: "3️⃣", 
+              id: MessageID(domain: "test", id: "conjured"), 
+              message: "#invertedEqualityCheck expects '__a' and '__b' to have the same type"
+            ),
+            NoteDescriptor(
+              locationMarker: "1️⃣", 
+              id: MessageID(domain: "test", id: "conjured"), 
+              message: "Inferred type 'String' here"
+            ),
+            NoteDescriptor(
+              locationMarker: "2️⃣", 
+              id: MessageID(domain: "test", id: "conjured"), 
+              message: "Inferred type 'Int' here"
+            )
+          ]
+        )
+      ]
+    )
+    let inInnerExpansionNotePos = outerExpansionSourceMarkers["3️⃣"]!
+
+    // Expansion source file
+    _ = group.addTestFile(
+      """
+      1️⃣!(2️⃣__a 3️⃣== 4️⃣__b)
+      """,
+      displayName: "#invertedEqualityCheck",
+      parent: (outerExpansionSourceID, inInnerExpansionNotePos),
+      diagnosticDescriptors: [
+        DiagnosticDescriptor(
+          locationMarker: "3️⃣",
+          message: "no matching operator '==' for types 'String' and 'Int'",
+          severity: .error,
+          noteDescriptors: [
+            NoteDescriptor(
+              locationMarker: "1️⃣", 
+              id: MessageID(domain: "test", id: "conjured"), 
+              message: "#invertedEqualityCheck expects operands of the same type"
+            ),
+            NoteDescriptor(
+              locationMarker: "2️⃣",
+              id: MessageID(domain: "test", id: "conjured"), 
+              message: "Inferred type 'String' here"
+            ),
+            NoteDescriptor(
+              locationMarker: "4️⃣", 
+              id: MessageID(domain: "test", id: "conjured"), 
+              message: "Inferred type 'Int' here"
+            ),
+          ]
+        ),
+        DiagnosticDescriptor(
+          locationMarker: "3️⃣",
+          id: MessageID(domain: "test", id: "conjuredError2"),
+          message: "operator `==` is unavailable: unavailable in embedded Swift",
+          severity: .error
+        ),
+        DiagnosticDescriptor(
+          locationMarker: "3️⃣",
+          id: MessageID(domain: "test", id: "conjuredError2"),
+          message: "#invertedEqualityCheck expects operands to be integer literals",
+          severity: .error
+        )
+      ]
+    )
+
+    let annotated = DiagnosticsFormatter.annotateSources(in: group)
+    assertStringsEqualWithDiff(
+      annotated,
+      """
+      #invertedEqualityCheck:1:7: error: no matching operator '==' for types 'String' and 'Int'
+      `- main.swift:2:1: note: expanded code originates here
+      1 | let pi = "3.14159"
+        | `- note: Inferred type 'String' here
+      2 | #myAssert(pi == 3)
+        | |               `- note: Inferred type 'Int' here
+        | `- note: in expansion of macro 'myAssert' here
+        +--- #myAssert -------------------------------------------------------
+        |1 | let __a = pi
+        |  |     `- note: Inferred type 'String' here
+        |2 | let __b = 3
+        |  |     `- note: Inferred type 'Int' here
+        |3 | if #invertedEqualityCheck(__a, __b) {
+        |  |    |- note: in expansion of macro 'invertedEqualityCheck' here
+        |  |    |- note: #invertedEqualityCheck expects operands of the same type
+        |  |    `- note: #invertedEqualityCheck expects '__a' and '__b' to have the same type
+        |  +--- #invertedEqualityCheck ---------------------------------------
+        |  |1 | !(__a == __b)
+        |  |  | | |   |  `- note: Inferred type 'Int' here
+        |  |  | | |   |- error: no matching operator '==' for types 'String' and 'Int'
+        |  |  | | |   |- error: operator `==` is unavailable: unavailable in embedded Swift
+        |  |  | | |   `- error: #invertedEqualityCheck expects operands to be integer literals
+        |  |  | | `- note: Inferred type 'String' here
+        |  |  | `- note: #invertedEqualityCheck expects operands of the same type
+        |  +------------------------------------------------------------------
+        |4 |   fatalError("assertion failed: pi != 3")
+        |5 | }
+        +---------------------------------------------------------------------
+      3 | print("hello")
+      
+      """
+    )
+  }
+
   func testCategoryFootnotes() {
     let categories = [
       DiagnosticCategory(
diff --git a/Tests/SwiftDiagnosticsTest/ParserDiagnosticsFormatterIntegrationTests.swift b/Tests/SwiftDiagnosticsTest/ParserDiagnosticsFormatterIntegrationTests.swift
index d40353270c0..716bc18a9f0 100644
--- a/Tests/SwiftDiagnosticsTest/ParserDiagnosticsFormatterIntegrationTests.swift
+++ b/Tests/SwiftDiagnosticsTest/ParserDiagnosticsFormatterIntegrationTests.swift
@@ -65,8 +65,10 @@ final class ParserDiagnosticsFormatterIntegrationTests: XCTestCase {
       i = bar(
       """
     let expectedOutput = """
+       1 | var i = 1
        2 | i = 2
        3 | i = foo(
+         |        `- note: to match this opening '('
        4 | i = 4
          |      `- error: expected ')' to end function call
        5 | i = 5
@@ -128,7 +130,8 @@ final class ParserDiagnosticsFormatterIntegrationTests: XCTestCase {
 
     let expectedOutput = """
       \u{001B}[0;36m1 |\u{001B}[0;0m for \u{001B}[4;39m(i\u{001B}[0;0m \u{001B}[4;39m= 🐮; i != 👩‍👩‍👦‍👦; i += 1)\u{001B}[0;0m { }
-        \u{001B}[0;36m|\u{001B}[0;0m |     `- \u{001B}[1;31merror: \u{001B}[1;39mexpected ')' to end tuple pattern\u{001B}[0;0m
+        \u{001B}[0;36m|\u{001B}[0;0m |   | `- \u{001B}[1;31merror: \u{001B}[1;39mexpected ')' to end tuple pattern\u{001B}[0;0m
+        \u{001B}[0;36m|\u{001B}[0;0m |   `- \u{001B}[1;39mnote: \u{001B}[1;39mto match this opening '('\u{001B}[0;0m
         \u{001B}[0;36m|\u{001B}[0;0m `- \u{001B}[1;31merror: \u{001B}[1;39mC-style for statement has been removed in Swift 3\u{001B}[0;0m
 
       """