Refactor DiagnosticsFormatter and extend its functionality

This commit refactors the existing code for `DiagnosticsFormatter` and introduces several new features, complete with documentation and unit tests.

Key Enhancements:

1. Nested Diagnostic Support: Enhanced to include not only top-level diagnostics but also related notes, improving the debugging experience.

2. Custom Decorators: Incorporate the `DiagnosticDecorator` protocol, allowing for custom formatting and styling of diagnostic output.

3. Context Size Control: Added options to control the `ContextSize`, providing more flexibility in how much source code context is displayed around each diagnostic.

Documentation:

- Comprehensive documentation added, detailing the purpose, usage examples, and future developments for `DiagnosticsFormatter`.

Testing:

- Added robust unit tests to validate the new features and ensure reliability.

This refactor and feature addition make `DiagnosticsFormatter` a more versatile and developer-friendly tool for debugging and understanding Swift code.

Sources/SwiftDiagnostics/DiagnosticDecorators/ANSIDiagnosticDecorator.swift

@@ -12,7 +12,7 @@
 
 extension DiagnosticDecorator where Self == ANSIDiagnosticDecorator {
   /// - SeeAlso: ``ANSIDiagnosticDecorator``
-  static var ANSI: Self {
+  public static var ANSI: Self {
     Self()
   }
 }
@@ -21,9 +21,9 @@ extension DiagnosticDecorator where Self == ANSIDiagnosticDecorator {
 /// buffer outlines, and code highlights—by applying severity-based prefixes and ANSI color codes.
 ///
 /// This decorator uses ANSI codes—control characters specialized for text formatting in terminals—to provide visual cues.
-@_spi(Testing) public struct ANSIDiagnosticDecorator: DiagnosticDecorator {
+public struct ANSIDiagnosticDecorator: DiagnosticDecorator {
 
-  @_spi(Testing) public init() {}
+  public init() {}
 
   /// Decorates a diagnostic message by appending a severity-based prefix and applying ANSI color codes.
   ///

Sources/SwiftDiagnostics/DiagnosticDecorators/BasicDiagnosticDecorator.swift

@@ -12,7 +12,7 @@
 
 extension DiagnosticDecorator where Self == BasicDiagnosticDecorator {
   /// - Seealso: ``BasicDiagnosticDecorator``
-  static var basic: Self {
+  public static var basic: Self {
     Self()
   }
 }
@@ -21,9 +21,9 @@ extension DiagnosticDecorator where Self == BasicDiagnosticDecorator {
 /// buffer outlines, and code highlights—by appending severity-based prefixes.
 ///
 /// Unlike `ANSIDiagnosticDecorator`, this decorator does not use ANSI color codes and solely relies on textual cues.
-@_spi(Testing) public struct BasicDiagnosticDecorator: DiagnosticDecorator {
+public struct BasicDiagnosticDecorator: DiagnosticDecorator {
 
-  @_spi(Testing) public init() {}
+  public init() {}
 
   /// Decorates a diagnostic message by appending a severity-based prefix.
   ///

Sources/SwiftDiagnostics/DiagnosticDecorators/DiagnosticDecorator.swift

@@ -28,7 +28,7 @@
 /// The protocol is designed to be easily customizable. Developers can create their own entities that conform
 /// to `DiagnosticDecorator` to implement custom decorating logic. This allows for different visual representations,
 /// such as using ANSI colors, underscores, emoji-based or other markers, for diagnostics in source code.
-protocol DiagnosticDecorator {
+public protocol DiagnosticDecorator {
   /// Decorates a diagnostic message based on its severity level.
   ///
   /// Implementations are expected to prepend a severity-specific prefix (e.g., "error: ", "warning: ") to the diagnostic message.