Improve default diagnostic formatter (#535)

* Improve default diagnostic formatter

* Fix suggestion display ordering

* Highlight output only when connected to termnial

* Highlight diagnostic summary only when connected to terminal

* Fix exisiting tests to use tools output formatting option

* Add default diagnostic formatting tests

* Relocate default diagnostic formatting test to a separate file

* Remove URL force unwrapping

* Refactor formatted description for diagnostic

* Refactor suggestion grouping

* Remove redundant ANSIAnnotation color reset

* Improve suggestion vertical alignment prefix

* Revert public initializer changes

To make it easier to fix the formatter abstraction later, we keep the previous public initializer unchanged and add a new internal initializer that accept all 4 arguments.

* Clean up source lines after writing the diagnostics

Since the sourceLines could potentially be big if there were diagnostics in many large files, we remove the cached lines after the console writer finished writing the diagnostics.

* Improve inline documentation

* Clean up source lines cache after all diagnostics have been formatted

Introduces an API to inform the formatter that all diagnostics have been formatted.

* Improve C import

The previous import solution was working only for Darwin platforms, it needed to be update to support more platforms.

* Revert whitespace change

A trailing whitespace is added in `TestTutorial.tutorial:42`, this is expected and should not have been removed.

* Revert "Revert public initializer changes"

This reverts commit 6e1d037.

Author: arthurcro

Sources/SwiftDocC/Infrastructure/Diagnostics/ANSIAnnotation.swift

@@ -0,0 +1,57 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 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 Swift project authors
+*/
+
+import Foundation
+
+struct ANSIAnnotation {
+    enum Color: UInt8 {
+        case normal = 0
+        case red = 31
+        case green = 32
+        case yellow = 33
+        case `default` = 39
+    }
+    
+    enum Trait: UInt8 {
+        case normal = 0
+        case bold = 1
+        case italic = 3
+    }
+    
+    private var color: Color
+    private var trait: Trait
+    
+    /// The textual representation of the annotation.
+    private var code: String {
+        "\u{001B}[\(trait.rawValue);\(color.rawValue)m"
+    }
+    
+    init(color: Color, trait: Trait = .normal) {
+        self.color = color
+        self.trait = trait
+    }
+    
+    func applied(to message: String) -> String {
+        "\(code)\(message)\(ANSIAnnotation.normal.code)"
+    }
+    
+    static var normal: ANSIAnnotation {
+        self.init(color: .normal, trait: .normal)
+    }
+    
+    /// Annotation used for highlighting source text.
+    static var sourceHighlight: ANSIAnnotation {
+        ANSIAnnotation(color: .green, trait: .bold)
+    }
+    /// Annotation used for highlighting source suggestion.
+    static var sourceSuggestionHighlight: ANSIAnnotation {
+        ANSIAnnotation(color: .default, trait: .bold)
+    }
+}