Add diagnostic testing utils for enhanced diagnostics testing

Introduces `DiagnosticTestingUtils.swift`, a utility suite designed to aid in writing unit tests for `DiagnosticsFormatter` and `GroupedDiagnostics`. Highlights include:

1. `LocationMarker` Typealias:
  - Enhances readability and precision in location identification within AST.

2. `DiagnosticDescriptor` and `NoteDescriptor` Structs:
  - Offers a robust mechanism to construct and describe diagnostics and notes for testing.

3. Simple Implementations for Protocols:
  - `SimpleNoteMessage` and `SimpleDiagnosticMessage` for streamlined testing.

4. `assertAnnotated` Function:
  - Asserts that annotated source generated from diagnostics aligns with the expected output.

This addition significantly bolsters the testing utilities, providing a comprehensive framework for ensuring accurate and effective diagnostics.

Author: Matejkob

Tests/SwiftDiagnosticsTest/DiagnosticTestingUtils.swift

@@ -0,0 +1,216 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2023 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 SwiftParser
+import SwiftSyntax
+import XCTest
+import _SwiftSyntaxTestSupport
+
+/// A typealias representing a location marker.
+///
+/// This string serves to pinpoint the exact location of a particular token in the Abstract Syntax Tree (AST).
+/// Once the token location is identified, it can be leveraged for various test-specific operations such as inserting diagnostics, notes, or fix-its,
+/// or for closer examination of the syntax tree.
+///
+/// Markers are instrumental in writing unit tests that require precise location data. They are commonly represented using emojis like 1️⃣, 2️⃣, 3️⃣, etc., to improve readability.
+///
+/// ### Example
+///
+/// In the following test code snippet, the emojis 1️⃣ and 2️⃣ are used as location markers:
+///
+/// ```swift
+/// func foo() -> Int {
+///   if 1️⃣1 != 0 2️⃣{
+///     return 0
+///   }
+///   return 1
+/// }
+/// ```
+typealias LocationMarker = String
+
+/// Represents a descriptor for constructing a diagnostic in testing.
+struct DiagnosticDescriptor {
+  /// The marker pointing to location in source code.
+  let locationMarker: LocationMarker
+
+  /// The ID associated with the message, used for categorizing or referencing it.
+  let id: MessageID
+
+  /// The textual content of the message to be displayed.
+  let message: String
+
+  /// The severity level of the diagnostic message.
+  let severity: DiagnosticSeverity
+
+  /// The syntax elements to be highlighted for this diagnostic message.
+  let highlight: [Syntax]  // TODO: How to create an abstract model for this?
+
+  /// Descriptors for any accompanying notes for this diagnostic message.
+  let noteDescriptors: [NoteDescriptor]
+
+  /// Descriptors for any Fix-Its that can be applied for this diagnostic message.
+  let fixIts: [FixIt]  // TODO: How to create an abstract model for this?
+
+  /// Initializes a new `DiagnosticDescriptor`.
+  ///
+  /// - Parameters:
+  ///   - locationMarker: The marker pointing to location in source code.
+  ///   - id: The message ID of the diagnostic.
+  ///   - message: The textual message to display for the diagnostic.
+  ///   - severity: The severity level of the diagnostic. Default is `.error`.
+  ///   - highlight: The syntax elements to be highlighted. Default is an empty array.
+  ///   - noteDescriptors: An array of note descriptors for additional context. Default is an empty array.
+  ///   - fixIts: An array of Fix-It descriptors for quick fixes. Default is an empty array.
+  init(
+    locationMarker: LocationMarker,
+    id: MessageID,
+    message: String,
+    severity: DiagnosticSeverity = .error,
+    highlight: [Syntax] = [],
+    noteDescriptors: [NoteDescriptor] = [],
+    fixIts: [FixIt] = []
+  ) {
+    self.locationMarker = locationMarker
+    self.id = id
+    self.message = message
+    self.severity = severity
+    self.highlight = highlight
+    self.noteDescriptors = noteDescriptors
+    self.fixIts = fixIts
+  }
+
+  /// Creates a ``Diagnostic`` instance from a given ``DiagnosticDescriptor``, syntax tree, and location markers.
+  ///
+  /// - Parameters:
+  ///   - tree: The syntax tree where the diagnostic is rooted.
+  ///   - markers: A dictionary mapping location markers to their respective offsets in the source code.
+  ///   - file: The file where the test is located, used for reporting failures.
+  ///   - line: The line where the test is located, used for reporting failures.
+  ///
+  /// - Returns: A ``Diagnostic`` instance populated with details from the ``DiagnosticDescriptor``, or `nil` if it fails.
+  func createDiagnostic(
+    inSyntaxTree tree: some SyntaxProtocol,
+    usingLocationMarkers markers: [LocationMarker: Int],
+    file: StaticString = #file,
+    line: UInt = #line
+  ) -> Diagnostic? {
+    func node(at marker: LocationMarker) -> Syntax? {
+      guard let markedOffset = markers[marker] else {
+        XCTFail("Marker \(marker) not found in the marked source", file: file, line: line)
+        return nil
+      }
+      let markedPosition = AbsolutePosition(utf8Offset: markedOffset)
+      guard let token = tree.token(at: markedPosition) else {
+        XCTFail("Node not found at marker \(marker)", file: file, line: line)
+        return nil
+      }
+      return Syntax(token)
+    }
+
+    guard let diagnosticNode = node(at: self.locationMarker) else { return nil }
+
+    var notes = [Note]()
+    for noteDescriptor in self.noteDescriptors {
+      guard let noteNode = node(at: noteDescriptor.locationMarker) else { continue }
+
+      let note = Note(
+        node: noteNode,
+        message: SimpleNoteMessage(message: noteDescriptor.message, fixItID: noteDescriptor.id)
+      )
+      notes.append(note)
+    }
+
+    return Diagnostic(
+      node: diagnosticNode,
+      message: SimpleDiagnosticMessage(
+        message: self.message,
+        diagnosticID: self.id,
+        severity: self.severity
+      ),
+      highlights: self.highlight,
+      notes: notes,
+      fixIts: self.fixIts
+    )
+  }
+}
+
+/// Represents a descriptor for constructing a note message in testing.
+struct NoteDescriptor {
+  /// The marker pointing to location in source code.
+  let locationMarker: LocationMarker
+
+  /// The ID associated with the note message.
+  let id: MessageID
+
+  /// The textual content of the note to be displayed.
+  let message: String
+}
+
+/// A simple implementation of the `NoteMessage` protocol for testing.
+/// This struct holds the message text and a fix-it ID for a note.
+struct SimpleNoteMessage: NoteMessage {
+  /// The textual content of the note to be displayed.
+  let message: String
+
+  /// The ID associated with the fix-it, if applicable.
+  let fixItID: MessageID
+}
+
+/// A simple implementation of the `DiagnosticMessage` protocol for testing.
+/// This struct holds the message text, diagnostic ID, and severity for a diagnostic.
+struct SimpleDiagnosticMessage: DiagnosticMessage {
+  /// The textual content of the diagnostic message to be displayed.
+  let message: String
+
+  /// The ID associated with the diagnostic message for categorization or referencing.
+  let diagnosticID: MessageID
+
+  /// The severity level of the diagnostic message.
+  let severity: DiagnosticSeverity
+}
+
+/// Asserts that the annotated source generated from diagnostics matches an expected annotated source.
+///
+/// - Parameters:
+///   - markedSource: The source code with location markers `LocationMarker` for diagnostics.
+///   - withDiagnostics: An array of diagnostic descriptors to generate diagnostics.
+///   - matches: The expected annotated source after applying the diagnostics.
+///   - file: The file in which failure occurred.
+///   - line: The line number on which failure occurred.
+func assertAnnotated(
+  markedSource: String,
+  withDiagnostics diagnosticDescriptors: [DiagnosticDescriptor],
+  matches expectedAnnotatedSource: String,
+  file: StaticString = #file,
+  line: UInt = #line
+) {
+
+  let (markers, source) = extractMarkers(markedSource)
+  let tree = Parser.parse(source: source)
+
+  // if ParseDiagnosticsGenerator.diagnostics(for: tree) contains any diagnostics
+  // run XCTFail with information.
+
+  let diagnostics = diagnosticDescriptors.compactMap {
+    $0.createDiagnostic(inSyntaxTree: tree, usingLocationMarkers: markers)
+  }
+
+  let annotatedSource = DiagnosticsFormatter.annotatedSource(inSyntaxTree: tree, withDiagnostics: diagnostics)
+
+  assertStringsEqualWithDiff(
+    annotatedSource,
+    expectedAnnotatedSource,
+    file: file,
+    line: line
+  )
+}