Add an optional diagnostic category to diagnostics

A diagnostic category provides a category name that is used to identify
a set of related diagnostics. It can also include a documentation path
to provide more information about those diagnostics, to help guide the
user in resolving them.

Always render a category as [#CategoryName] at the end of the
diagnostic message. When we are producing colored output and there is a
documentation path, make the category name a hyperlink to the
documentation using the OSC 8 scheme.

Author: DougGregor

Sources/SwiftDiagnostics/DiagnosticDecorators/ANSIDiagnosticDecorator.swift

@@ -48,7 +48,8 @@ extension DiagnosticDecorator where Self == ANSIDiagnosticDecorator {
   /// ```
   @_spi(Testing) public func decorateMessage(
     _ message: String,
-    basedOnSeverity severity: DiagnosticSeverity
+    basedOnSeverity severity: DiagnosticSeverity,
+    category: DiagnosticCategory? = nil
   ) -> String {
     let severityText: String
     let severityAnnotation: ANSIAnnotation
@@ -77,7 +78,24 @@ extension DiagnosticDecorator where Self == ANSIDiagnosticDecorator {
       resetAfterApplication: false
     )
 
-    return prefix + colorizeIfNotEmpty(message, usingAnnotation: .diagnosticText)
+    // Append the [#CategoryName] suffix when there is a category.
+    let categorySuffix: String
+    if let category {
+      // Make the category name a link to the documentation, if there is
+      // documentation.
+      let categoryName: String
+      if let documentationPath = category.documentationPath {
+        categoryName = ANSIAnnotation.hyperlink(category.name, to: documentationPath)
+      } else {
+        categoryName = category.name
+      }
+
+      categorySuffix = " [#\(categoryName)]"
+    } else {
+      categorySuffix = ""
+    }
+
+    return prefix + colorizeIfNotEmpty(message, usingAnnotation: .diagnosticText) + categorySuffix
   }
 
   /// Decorates a source code buffer outline using ANSI cyan color codes.
@@ -220,4 +238,9 @@ private struct ANSIAnnotation {
   static var remarkText: Self {
     Self(color: .blue, trait: .bold)
   }
+
+  /// Forms a hyperlink to the given URL with the given text.
+  static func hyperlink(_ text: String, to url: String) -> String {
+    "\u{001B}]8;;\(url)\u{001B}\\\(text)\u{001B}]8;;\u{001B}\\"
+  }
 }

Sources/SwiftDiagnostics/DiagnosticDecorators/BasicDiagnosticDecorator.swift

@@ -34,7 +34,8 @@ extension DiagnosticDecorator where Self == BasicDiagnosticDecorator {
   /// - Returns: A string that combines the severity-specific prefix and the original diagnostic message.
   @_spi(Testing) public func decorateMessage(
     _ message: String,
-    basedOnSeverity severity: DiagnosticSeverity
+    basedOnSeverity severity: DiagnosticSeverity,
+    category: DiagnosticCategory? = nil
   ) -> String {
     let severityText: String
 
@@ -49,7 +50,10 @@ extension DiagnosticDecorator where Self == BasicDiagnosticDecorator {
       severityText = "remark"
     }
 
-    return severityText + ": " + message
+    // Append the [#CategoryName] suffix when there is a category.
+    let categorySuffix: String = category.map { category in " [#\(category.name)]" } ?? ""
+
+    return severityText + ": " + message + categorySuffix
   }
 
   /// Passes through the source code buffer outline without modification.

Sources/SwiftDiagnostics/DiagnosticDecorators/DiagnosticDecorator.swift

@@ -39,7 +39,7 @@ protocol DiagnosticDecorator {
   ///
   /// - 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.
-  func decorateMessage(_ message: String, basedOnSeverity severity: DiagnosticSeverity) -> String
+  func decorateMessage(_ message: String, basedOnSeverity severity: DiagnosticSeverity, category: DiagnosticCategory?) -> String
 
   /// Decorates the outline of a source code buffer to visually enhance its structure.
   ///
@@ -69,6 +69,6 @@ extension DiagnosticDecorator {
   ///
   /// - Returns: A decorated version of the diagnostic message, determined by its severity level.
   func decorateDiagnosticMessage(_ diagnosticMessage: DiagnosticMessage) -> String {
-    decorateMessage(diagnosticMessage.message, basedOnSeverity: diagnosticMessage.severity)
+    decorateMessage(diagnosticMessage.message, basedOnSeverity: diagnosticMessage.severity, category: diagnosticMessage.category)
   }
 }

Sources/SwiftDiagnostics/GroupedDiagnostics.swift

@@ -227,7 +227,8 @@ extension GroupedDiagnostics {
             let bufferLoc = slc.location(for: rootPosition)
             let decoratedMessage = diagnosticDecorator.decorateMessage(
               "expanded code originates here",
-              basedOnSeverity: .note
+              basedOnSeverity: .note,
+              category: nil
             )
             prefixString += "`- \(bufferLoc.file):\(bufferLoc.line):\(bufferLoc.column): \(decoratedMessage)\n"
           }

Sources/SwiftDiagnostics/Message.swift

@@ -33,6 +33,21 @@ public enum DiagnosticSeverity: Sendable, Hashable {
   case remark
 }
 
+/// Describes a category of diagnostics, which covers a set of related
+/// diagnostics that can share documentation.
+public struct DiagnosticCategory: Sendable, Hashable {
+  /// Name that identifies the category, e.g., StrictMemorySafety.
+  public let name: String
+
+  /// Path to a file providing documentation documentation for this category.
+  public let documentationPath: String?
+
+  public init(name: String, documentationPath: String?) {
+    self.name = name
+    self.documentationPath = documentationPath
+  }
+}
+
 /// Types conforming to this protocol represent diagnostic messages that can be
 /// shown to the client.
 public protocol DiagnosticMessage: Sendable {
@@ -43,4 +58,12 @@ public protocol DiagnosticMessage: Sendable {
   var diagnosticID: MessageID { get }
 
   var severity: DiagnosticSeverity { get }
+
+  /// The category that this diagnostic belongs in.
+  var category: DiagnosticCategory? { get }
+}
+
+extension DiagnosticMessage {
+  /// Diagnostic messages default to having no category.
+  public var category: DiagnosticCategory? { nil }
 }

Tests/SwiftDiagnosticsTest/DiagnosticDecorators/ANSIDiagnosticDecoratorTests.swift

@@ -34,6 +34,13 @@ final class ANSIDiagnosticDecoratorTests: XCTestCase {
 
     let decoratedMessageForRemark = decorator.decorateMessage(message, basedOnSeverity: .remark)
     assertStringsEqualWithDiff(decoratedMessageForRemark, "\u{1B}[1;34mremark: \u{1B}[1;39mFile not found\u{1B}[0;0m")
+
+    let decoratedMessageWithCategory = decorator.decorateMessage(
+      message,
+      basedOnSeverity: .error,
+      category: DiagnosticCategory(name: "Filesystem", documentationPath: "http://www.swift.org")
+    )
+    assertStringsEqualWithDiff(decoratedMessageWithCategory, "\u{1B}[1;31merror: \u{1B}[1;39mFile not found\u{1B}[0;0m [#\u{001B}]8;;http://www.swift.org\u{001B}\\Filesystem\u{001B}]8;;\u{001B}\\]")
   }
 
   func testDecorateMessageWithEmptyMessage() {

Tests/SwiftDiagnosticsTest/DiagnosticDecorators/BasicDiagnosticDecoratorTests.swift

@@ -34,6 +34,13 @@ final class BasicDiagnosticDecoratorTests: XCTestCase {
 
     let decoratedMessageForRemark = decorator.decorateMessage(message, basedOnSeverity: .remark)
     assertStringsEqualWithDiff(decoratedMessageForRemark, "remark: File not found")
+
+    let decoratedMessageWithCategory = decorator.decorateMessage(
+      message,
+      basedOnSeverity: .error,
+      category: DiagnosticCategory(name: "Filesystem", documentationPath: "http://www.swift.org")
+    )
+    assertStringsEqualWithDiff(decoratedMessageWithCategory, "error: File not found [#Filesystem]")
   }
 
   // MARK: - Decorate Buffer Outline Tests

Tests/SwiftDiagnosticsTest/DiagnosticTestingUtils.swift

@@ -62,6 +62,9 @@ struct DiagnosticDescriptor {
   /// The severity level of the diagnostic message.
   let severity: DiagnosticSeverity
 
+  /// The diagnostic category.
+  let category: DiagnosticCategory?
+
   /// The syntax elements to be highlighted for this diagnostic message.
   let highlight: [Syntax]  // TODO: How to create an abstract model for this?
 
@@ -86,6 +89,7 @@ struct DiagnosticDescriptor {
     id: MessageID = MessageID(domain: "test", id: "conjured"),
     message: String,
     severity: DiagnosticSeverity = .error,
+    category: DiagnosticCategory? = nil,
     highlight: [Syntax] = [],
     noteDescriptors: [NoteDescriptor] = [],
     fixIts: [FixIt] = []
@@ -94,6 +98,7 @@ struct DiagnosticDescriptor {
     self.id = id
     self.message = message
     self.severity = severity
+    self.category = category
     self.highlight = highlight
     self.noteDescriptors = noteDescriptors
     self.fixIts = fixIts
@@ -139,7 +144,8 @@ struct DiagnosticDescriptor {
       message: SimpleDiagnosticMessage(
         message: self.message,
         diagnosticID: self.id,
-        severity: self.severity
+        severity: self.severity,
+        category: category
       ),
       highlights: self.highlight,
       notes: notes,
@@ -181,6 +187,16 @@ struct SimpleDiagnosticMessage: DiagnosticMessage {
 
   /// The severity level of the diagnostic message.
   let severity: DiagnosticSeverity
+
+  /// The category for this diagnostic.
+  let category: DiagnosticCategory?
+
+  init(message: String, diagnosticID: MessageID, severity: DiagnosticSeverity, category: DiagnosticCategory? = nil) {
+    self.message = message
+    self.diagnosticID = diagnosticID
+    self.severity = severity
+    self.category = category
+  }
 }
 
 /// Asserts that the annotated source generated from diagnostics matches an expected annotated source.