Add ANSIDiagnosticDecorator and DiagnosticDecorator protocol

This commit introduces two significant components:

1. `DiagnosticDecorator` Protocol:
  - Defines a standard interface for decorating diagnostic output in source code.
  - Design to be used by entities like `DiagnosticsFormatter` and `GroupedDiagnostics`.

2. `ANSIDiagnosticDecorator` Struct:
  - Implements the `DiagnosticDecorator` protocol.
  - Adds severity-based prefixes to diagnostic messages.
  - Supports optional ANSI colorization to enhance visibility and interpretation.

Also includes:
- Unit tests for `ANSIDiagnosticDecorator` in `ANSIDiagnosticDecoratorTests`.

This feature enriches the diagnostic capabilities, offering customizable and visually informative feedback.

Author: Matejkob

Sources/SwiftDiagnostics/DiagnosticDecorators/ANSIDiagnosticDecorator.swift

@@ -0,0 +1,248 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+extension DiagnosticDecorator where Self == ANSIDiagnosticDecorator {
+  public static func ANSI(colorize: Bool) -> Self {
+    Self(colorize: colorize)
+  }
+}
+
+/// An implementation of ``DiagnosticDecorator`` protocol designed to enhance diagnostic messages by adding severity-based
+/// prefixes and optional ANSI colorization.
+///
+/// By leveraging ANSI codes—a set of control characters used to manipulate the formatting
+/// and appearance of text in a terminal—the decorator imbues textual information with visual cues.
+/// These visual cues vary depending on the severity of the message, such as whether it's an error, a warning,
+/// or another type of diagnostic output.
+///
+/// In essence, this decorator serves two primary functions:
+/// 1. It appends a categorization prefix (e.g., "error: ", "warning: ", "note: ", "remark: ") to the diagnostic message
+/// to indicate its level of urgency or importance.
+/// 2. It has the capability to colorize this prefix and other segments of the message for enhanced visibility
+/// and quick interpretation. This colorization feature can be toggled on or off, offering flexibility in its usage.
+public struct ANSIDiagnosticDecorator: DiagnosticDecorator {
+  /// A flag indicating whether or not to apply colorization.
+  private let colorize: Bool
+
+  /// Initializes a new `ANSIDiagnosticDecorator` instance.
+  ///
+  /// - Parameter colorize: A boolean flag indicating whether to apply colorization. Defaults to true.
+  public init(colorize: Bool) {
+    self.colorize = colorize
+  }
+
+  /// Decorates a diagnostic message by adding a severity-based prefix and optionally applying ANSI colorization.
+  ///
+  /// This method always prepends a severity-specific prefix (e.g., "error: ") to the diagnostic message. The `colorize` property
+  /// controls whether or not ANSI color codes are applied to the prefix.
+  ///
+  /// - Parameters:
+  ///   - message: The diagnostic message that needs to be decorated.
+  ///   - severity: The severity level associated with the diagnostic message.
+  ///
+  /// - Returns: A string that combines the severity-specific prefix and the original diagnostic message, with optional ANSI colorization.
+  ///
+  /// ## Examples
+  ///
+  /// When `colorize` is set to true:
+  /// ```swift
+  /// let decorator = ANSIDiagnosticDecorator(colorize: true)
+  /// let decoratedMessage = decorator.decorateMessage("File not found", basedOnSeverity: .error)
+  /// // Output would be: "error: File not found"
+  /// ```
+  /// In this case, the prefix "error: " would be colorized, likely appearing in red.
+  ///
+  /// To achieve a similar colorized output manually in the console, you can use `printf` in bash:
+  /// ```bash
+  /// printf "\e[1;31merror: \e[1;39mFile not found\e[0;0m\n"
+  /// ```
+  /// This will print the "error: " prefix in red and the message "File not found" in the default text color.
+  ///
+  /// When `colorize` is set to false:
+  /// ```swift
+  /// let decorator = ANSIDiagnosticDecorator(colorize: false)
+  /// let decoratedMessage = decorator.decorateMessage("File not found", basedOnSeverity: .error)
+  /// // Output would be: "error: File not found"
+  /// ```
+  /// In this case, the prefix "error: " would appear as plain text, with no ANSI colorization applied.
+  public func decorateMessage(_ message: String, basedOnSeverity severity: DiagnosticSeverity) -> String {
+    let severityText: String
+    let severityAnnotation: ANSIAnnotation
+
+    switch severity {
+    case .error:
+      severityText = "error"
+      severityAnnotation = .errorText
+
+    case .warning:
+      severityText = "warning"
+      severityAnnotation = .warningText
+
+    case .note:
+      severityText = "note"
+      severityAnnotation = .noteText
+
+    case .remark:
+      severityText = "remark"
+      severityAnnotation = .remarkText
+    }
+
+    let prefix = colorizeIfRequested("\(severityText): ", usingAnnotation: severityAnnotation, resetAfterApplication: false)
+
+    return prefix + colorizeIfRequested(message, usingAnnotation: .diagnosticText)
+  }
+
+  /// Decorates the outline of a source code buffer, optionally applying ANSI cyan color colorization.
+  ///
+  /// - Parameter bufferOutline: The string representation of the source code buffer outline.
+  ///
+  /// - Returns: A string with optional ANSI cyan color colorization applied to the source code buffer outline.
+  public func decorateBufferOutline(_ bufferOutline: String) -> String {
+    colorizeIfRequested(bufferOutline, usingAnnotation: .bufferOutline)
+  }
+
+  /// Decorates a text segment intended for highlighting within a source code snippet. The method can also optionally
+  /// apply ANSI colorization for enhanced visual cues.
+  ///
+  /// - Parameter highlight: The text segment to be emphasized.
+  ///
+  /// - Returns: A tuple containing:
+  ///   - `highlightedSourceCode`: A string that represents the decorated version of the original source code snippet.
+  ///   - `additionalHighlightedLine`: always with nil.
+  ///
+  /// ## Examples
+  ///
+  /// When `colorize` is set to true:
+  /// ```swift
+  /// let decorator = ANSIDiagnosticDecorator(colorize: true)
+  /// let decoratedHighlight = decorator.decorateHighlight("let x = 10")
+  /// // Output would be: ["\u{1B}[4;39mlet x = 10\u{1B}[0;0m"]
+  /// ```
+  ///
+  /// To achieve a similar colorized output manually in the console, you can use `printf` in bash:
+  /// ```bash
+  /// printf "\e[4;39mlet x = 10\e[0;0m\n"
+  /// ```
+  ///
+  /// When `colorize` is set to false:
+  /// ```swift
+  /// let decorator = ANSIDiagnosticDecorator(colorize: false)
+  /// let decoratedHighlight = decorator.decorateHighlight("let x = 10")
+  /// // Output would be: ["let x = 10"]
+  /// ```
+  public func decorateHighlight(_ highlight: String) -> (highlightedSourceCode: String, additionalHighlightedLine: String?) {
+    (highlightedSourceCode: colorizeIfRequested(highlight, usingAnnotation: .sourceHighlight), additionalHighlightedLine: nil)
+  }
+
+  /// Applies ANSI annotation to a given text segment, if colorization is enabled.
+  ///
+  /// - Parameters:
+  ///   - text: The text segment to which the annotation should be applied.
+  ///   - annotation: The ANSI annotation to apply.
+  ///   - resetAfter: A flag indicating whether to reset ANSI settings after applying them. Defaults to true.
+  ///
+  /// - Returns: A potentially colorized version of the input text.
+  private func colorizeIfRequested(
+    _ text: String,
+    usingAnnotation annotation: ANSIAnnotation,
+    resetAfterApplication resetAfter: Bool = true
+  ) -> String {
+    guard colorize, !text.isEmpty else {
+      return text
+    }
+
+    return annotation.applied(to: text, resetAfter: resetAfter)
+  }
+}
+
+/// Defines text attributes to be applied to console output.
+struct ANSIAnnotation {
+  /// Represents ANSI color codes.
+  enum Color: UInt8 {
+    case normal = 0
+    case black = 30
+    case red = 31
+    case green = 32
+    case yellow = 33
+    case blue = 34
+    case magenta = 35
+    case cyan = 36
+    case white = 37
+    case `default` = 39
+  }
+
+  /// Represents ANSI text traits.
+  enum Trait: UInt8 {
+    case normal = 0
+    case bold = 1
+    case underline = 4
+  }
+
+  /// The ANSI color to be used.
+  let color: Color
+
+  /// The ANSI text trait to be used.
+  let trait: Trait
+
+  /// Returns ANSI code as a string, including both trait and color.
+  var code: String {
+    "\u{001B}[\(trait.rawValue);\(color.rawValue)m"
+  }
+
+  /// Applies the ANSI code to a message string. Optionally resets the code after the message.
+  func applied(to message: String, resetAfter: Bool = true) -> String {
+    guard resetAfter else {
+      return "\(code)\(message)"
+    }
+    return "\(code)\(message)\(ANSIAnnotation.normal.code)"
+  }
+
+  /// The default 'normal' ANSIAnnotation used to reset styles.
+  static var normal: Self {
+    Self(color: .normal, trait: .normal)
+  }
+
+  /// Annotation used for the outline and line numbers of a buffer.
+  static var bufferOutline: Self {
+    Self(color: .cyan, trait: .normal)
+  }
+
+  /// Annotation used for highlighting source text.
+  static var sourceHighlight: Self {
+    Self(color: .default, trait: .underline)
+  }
+
+  /// Annotation used for making text bold, commonly used in diagnostic messages.
+  static var diagnosticText: Self {
+    Self(color: .default, trait: .bold)
+  }
+
+  /// Annotation used for error text.
+  static var errorText: Self {
+    Self(color: .red, trait: .bold)
+  }
+
+  /// Annotation used for warning text.
+  static var warningText: Self {
+    Self(color: .yellow, trait: .bold)
+  }
+
+  /// Annotation used for note text.
+  static var noteText: Self {
+    Self(color: .default, trait: .bold)
+  }
+
+  /// Annotation used for remarks or less critical text.
+  static var remarkText: Self {
+    Self(color: .blue, trait: .bold)
+  }
+}

Sources/SwiftDiagnostics/DiagnosticDecorators/DiagnosticDecorator.swift

@@ -0,0 +1,71 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+/// Protocol that defines a standard interface for decorating diagnostic output in source code.
+/// This protocol is intended to be used by entities such as ``DiagnosticsFormatter`` and ``GroupedDiagnostics``
+/// to apply custom decorations to diagnostic messages, buffer outlines, and code highlights.
+///
+/// ## Conforming to `DiagnosticDecorator`:
+///
+/// To conform to the `DiagnosticDecorator` protocol, you must implement three required methods:
+///
+/// 1. `decorateMessage(_:basedOnSeverity:)`: For decorating diagnostic messages.
+/// 2. `decorateBufferOutline(_:)`: For decorating the outlines of source code buffers.
+/// 3. `decorateHighlight(_:)`: For decorating individual highlights within a source code snippet.
+///
+/// ## Customization:
+///
+/// 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.
+public protocol DiagnosticDecorator {
+  /// Decorates a diagnostic message based on its severity level.
+  ///
+  /// - Parameters:
+  ///   - message: The diagnostic message that needs to be decorated.
+  ///   - severity: The severity level associated with the diagnostic message.
+  ///
+  /// - Returns: A decorated version of the diagnostic message, enhanced by visual cues like color, text styles, or other markers
+  ///            based on its severity level.
+  func decorateMessage(_ message: String, basedOnSeverity severity: DiagnosticSeverity) -> String
+
+  /// Decorates the outline of a source code buffer to visually enhance its structure.
+  ///
+  /// - Parameter bufferOutline: The string representation of the source code buffer outline.
+  ///
+  /// - Returns: A decorated version of the buffer outline, improved with visual cues like color, text styles, or other markers.
+  func decorateBufferOutline(_ bufferOutline: String) -> String
+
+  /// Decorates a highlight within a source code snippet to emphasize it.
+  ///
+  /// - Parameter highlight: The text segment within the source code snippet that should be emphasized.
+  ///
+  /// - Returns: A tuple containing:
+  ///   - `highlightedSourceCode`: A string that represents the decorated version of the original source code snippet.
+  ///   - `additionalHighlightedLine`: An optional string containing additional lines of highlighting, if applicable.
+  ///
+  /// - Note: The method returns a tuple to offer more flexibility in decorating highlights.
+  ///         This allows for a variety of techniques to be used, such as ANSI codes for color
+  ///         and additional lines for contextual emphasis, which will be combined during the rendering process.
+  func decorateHighlight(_ highlight: String) -> (highlightedSourceCode: String, additionalHighlightedLine: String?)
+}
+
+extension DiagnosticDecorator {
+  /// Decorates a ``DiagnosticMessage`` instance by delegating to the `decorateMessage(_:basedOnSeverity:)` method.
+  ///
+  /// - Parameter diagnosticMessage: The ``DiagnosticMessage`` instance that encapsulates both the message and its severity level.
+  ///
+  /// - Returns: A decorated version of the diagnostic message, determined by its severity level.
+  public func decorateDiagnosticMessage(_ diagnosticMessage: DiagnosticMessage) -> String {
+    decorateMessage(diagnosticMessage.message, basedOnSeverity: diagnosticMessage.severity)
+  }
+}