Add color-diagnostics/no-color-diagnostics CLI flags (#8365)

Added the no-color-diagnostics flag to allow users to toggle on/off
color diagnostics


Continuation of
#8316

Motivation:

Not everyone has access to tty, or like colors in their terminal, or are
color blind. This feature allows them to control if they want to see
colors or not.

Modifications:

Added the color-diagnostics/no-color-diagnostics flag
Added test cases to test for colors
edited snippets to include this feature too


Result:

Developers can now control their color diagnostics when building,
running, testing, installing sdks, or browsing code snippets within the
swift package learn feature.

---------

Co-authored-by: John Bute <[email protected]>
Co-authored-by: Max Desiatov <[email protected]>

Author: 3 people

Sources/Basics/Observability.swift

@@ -16,6 +16,7 @@ import Foundation
 import struct TSCBasic.Diagnostic
 import protocol TSCBasic.DiagnosticData
 import protocol TSCBasic.DiagnosticLocation
+import class TSCBasic.TerminalController
 import class TSCBasic.UnknownLocation
 import protocol TSCUtility.DiagnosticDataConvertible
 import enum TSCUtility.Diagnostics
@@ -161,7 +162,7 @@ public protocol DiagnosticsHandler: Sendable {
     func handleDiagnostic(scope: ObservabilityScope, diagnostic: Diagnostic)
 }
 
-// helper protocol to share default behavior
+/// Helper protocol to share default behavior.
 public protocol DiagnosticsEmitterProtocol {
     func emit(_ diagnostic: Diagnostic)
 }
@@ -393,7 +394,7 @@ public struct Diagnostic: Sendable, CustomStringConvertible {
         case info
         case debug
 
-        internal var naturalIntegralValue: Int {
+        var naturalIntegralValue: Int {
             switch self {
             case .debug:
                 return 0
@@ -409,6 +410,39 @@ public struct Diagnostic: Sendable, CustomStringConvertible {
         public static func < (lhs: Self, rhs: Self) -> Bool {
             lhs.naturalIntegralValue < rhs.naturalIntegralValue
         }
+
+        /// A string that represents the log label associated with the severity level.
+        /// This property provides a descriptive prefix for log messages, indicating the type of message based on its
+        /// severity.
+        public var logLabel: String {
+            switch self {
+            case .debug:
+                return "debug: "
+            case .info:
+                return "info: "
+            case .warning:
+                return "warning: "
+            case .error:
+                return "error: "
+            }
+        }
+
+        public var color: TerminalController.Color {
+            switch self {
+            case .debug:
+                return .white
+            case .info:
+                return .white
+            case .error:
+                return .red
+            case .warning:
+                return .yellow
+            }
+        }
+
+        public var isBold: Bool {
+            return true
+        }
     }
 }
 
@@ -417,7 +451,8 @@ public struct Diagnostic: Sendable, CustomStringConvertible {
 /// Provides type-safe access to the ObservabilityMetadata's values.
 /// This API should ONLY be used inside of accessor implementations.
 ///
-/// End users should use "accessors" the key's author MUST define rather than using this subscript, following this pattern:
+/// End users should use "accessors" the key's author MUST define rather than using this subscript, following this
+/// pattern:
 ///
 ///     extension ObservabilityMetadata {
 ///       var testID: String? {
@@ -538,7 +573,8 @@ public struct ObservabilityMetadata: Sendable, CustomDebugStringConvertible {
         }
     }
 
-    /// A type-erased `ObservabilityMetadataKey` used when iterating through the `ObservabilityMetadata` using its `forEach` method.
+    /// A type-erased `ObservabilityMetadataKey` used when iterating through the `ObservabilityMetadata` using its
+    /// `forEach` method.
     public struct AnyKey: Sendable {
         /// The key's type represented erased to an `Any.Type`.
         public let keyType: Any.Type

Sources/Basics/ProgressAnimation/PercentProgressAnimation.swift

@@ -19,12 +19,17 @@ extension ProgressAnimation {
     public static func percent(
         stream: WritableByteStream,
         verbose: Bool,
-        header: String
+        header: String,
+        isColorized: Bool
     ) -> any ProgressAnimationProtocol {
         Self.dynamic(
             stream: stream,
             verbose: verbose,
-            ttyTerminalAnimationFactory: { RedrawingPercentProgressAnimation(terminal: $0, header: header) },
+            ttyTerminalAnimationFactory: { RedrawingPercentProgressAnimation(
+                terminal: $0,
+                header: header,
+                isColorized: isColorized
+            ) },
             dumbTerminalAnimationFactory: { SingleLinePercentProgressAnimation(stream: stream, header: header) },
             defaultAnimationFactory: { MultiLinePercentProgressAnimation(stream: stream, header: header) }
         )
@@ -35,11 +40,13 @@ extension ProgressAnimation {
 final class RedrawingPercentProgressAnimation: ProgressAnimationProtocol {
     private let terminal: TerminalController
     private let header: String
+    private let isColorized: Bool
     private var hasDisplayedHeader = false
 
-    init(terminal: TerminalController, header: String) {
+    init(terminal: TerminalController, header: String, isColorized: Bool) {
         self.terminal = terminal
         self.header = header
+        self.isColorized = isColorized
     }
 
     /// Creates repeating string for count times.
@@ -48,14 +55,23 @@ final class RedrawingPercentProgressAnimation: ProgressAnimationProtocol {
         return String(repeating: string, count: max(count, 0))
     }
 
+    func colorizeText(color: TerminalController.Color = .noColor) -> TerminalController.Color {
+        if self.isColorized {
+            return color
+        }
+        return .noColor
+    }
+
     func update(step: Int, total: Int, text: String) {
         assert(step <= total)
+        let isBold = self.isColorized
 
         let width = terminal.width
+
         if !hasDisplayedHeader {
             let spaceCount = width / 2 - header.utf8.count / 2
             terminal.write(repeating(string: " ", count: spaceCount))
-            terminal.write(header, inColor: .cyan, bold: true)
+            terminal.write(header, inColor: colorizeText(color: .cyan), bold: isBold)
             terminal.endLine()
             hasDisplayedHeader = true
         } else {
@@ -65,14 +81,18 @@ final class RedrawingPercentProgressAnimation: ProgressAnimationProtocol {
         terminal.clearLine()
         let percentage = step * 100 / total
         let paddedPercentage = percentage < 10 ? " \(percentage)" : "\(percentage)"
-        let prefix = "\(paddedPercentage)% " + terminal.wrap("[", inColor: .green, bold: true)
+        let prefix = "\(paddedPercentage)% " + terminal
+            .wrap("[", inColor: colorizeText(color: .green), bold: isBold)
         terminal.write(prefix)
 
         let barWidth = width - prefix.utf8.count
         let n = Int(Double(barWidth) * Double(percentage) / 100.0)
 
-        terminal.write(repeating(string: "=", count: n) + repeating(string: "-", count: barWidth - n), inColor: .green)
-        terminal.write("]", inColor: .green, bold: true)
+        terminal.write(
+            repeating(string: "=", count: n) + repeating(string: "-", count: barWidth - n),
+            inColor: colorizeText(color: .green)
+        )
+        terminal.write("]", inColor: colorizeText(color: .green), bold: isBold)
         terminal.endLine()
 
         terminal.clearLine()
@@ -131,9 +151,7 @@ final class MultiLinePercentProgressAnimation: ProgressAnimationProtocol {
         lastDisplayedText = text
     }
 
-    func complete(success: Bool) {
-    }
+    func complete(success: Bool) {}
 
-    func clear() {
-    }
+    func clear() {}
 }

Sources/Build/BuildOperation.swift

@@ -10,20 +10,20 @@
 //
 //===----------------------------------------------------------------------===//
 
+import _Concurrency
 @_spi(SwiftPMInternal)
 import Basics
-import _Concurrency
+import Foundation
 import LLBuildManifest
 import PackageGraph
 import PackageLoading
 import PackageModel
 import SPMBuildCore
 import SPMLLBuild
-import Foundation
 
+import class Basics.AsyncProcess
 import class TSCBasic.DiagnosticsEngine
 import protocol TSCBasic.OutputByteStream
-import class Basics.AsyncProcess
 import struct TSCBasic.RegEx
 
 import enum TSCUtility.Diagnostics
@@ -88,7 +88,7 @@ package struct LLBuildSystemConfiguration {
         }
     }
 
-    func buildEnvironment(for destination:  BuildParameters.Destination) -> BuildEnvironment {
+    func buildEnvironment(for destination: BuildParameters.Destination) -> BuildEnvironment {
         switch destination {
         case .host: self.toolsBuildParameters.buildEnvironment
         case .target: self.destinationBuildParameters.buildEnvironment
@@ -246,11 +246,13 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
     ) {
         /// Checks if stdout stream is tty.
         var productsBuildParameters = productsBuildParameters
-        productsBuildParameters.outputParameters.isColorized = outputStream.isTTY
-
+        if productsBuildParameters.outputParameters.isColorized {
+            productsBuildParameters.outputParameters.isColorized = outputStream.isTTY
+        }
         var toolsBuildParameters = toolsBuildParameters
-        toolsBuildParameters.outputParameters.isColorized = outputStream.isTTY
-
+        if toolsBuildParameters.outputParameters.isColorized {
+            toolsBuildParameters.outputParameters.isColorized = outputStream.isTTY
+        }
         self.config = LLBuildSystemConfiguration(
             toolsBuildParameters: toolsBuildParameters,
             destinationBuildParameters: productsBuildParameters,
@@ -362,9 +364,9 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
                                         fileSystem: localFileSystem,
                                         executor: executor)
                 guard !consumeDiagnostics.hasErrors else {
-                  // If we could not init the driver with this command, something went wrong,
-                  // proceed without checking this target.
-                  continue
+                    // If we could not init the driver with this command, something went wrong,
+                    // proceed without checking this target.
+                    continue
                 }
                 let imports = try driver.performImportPrescan().imports
                 let nonDependencyTargetsSet =
@@ -521,9 +523,11 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
                 self.preparationStepName = preparationStepName
                 self.progressTracker = progressTracker
             }
+
             func willCompilePlugin(commandLine: [String], environment: [String: String]) {
                 self.progressTracker?.preparationStepStarted(preparationStepName)
             }
+
             func didCompilePlugin(result: PluginCompilationResult) {
                 self.progressTracker?.preparationStepHadOutput(
                     preparationStepName,
@@ -539,6 +543,7 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
                 }
                 self.progressTracker?.preparationStepFinished(preparationStepName, result: (result.succeeded ? .succeeded : .failed))
             }
+
             func skippedCompilingPlugin(cachedResult: PluginCompilationResult) {
                 // Historically we have emitted log info about cached plugins that are used. We should reconsider whether this is the right thing to do.
                 self.progressTracker?.preparationStepStarted(preparationStepName)
@@ -682,7 +687,6 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
             fileSystem: self.fileSystem,
             observabilityScope: self.observabilityScope
         )
-
     }
 
     /// Create the build plan and return the build description.

Sources/Commands/Snippets/CardStack.swift

@@ -60,10 +60,17 @@ struct CardStack {
     }
 
     func askForLineInput(prompt: String?) -> String? {
+        let isColorized: Bool = swiftCommandState.options.logging.colorDiagnostics
+
         if let prompt {
-            print(brightBlack { prompt }.terminalString())
+            isColorized ?
+                print(brightBlack { prompt }.terminalString()) :
+                print(plain { prompt }.terminalString())
         }
-        terminal.write(">>> ", inColor: .green, bold: true)
+        isColorized ?
+            terminal.write(">>> ", inColor: .green, bold: true)
+            : terminal.write(">>> ", inColor: .noColor, bold: false)
+
         return readLine(strippingNewline: true)
     }
 
@@ -87,10 +94,12 @@ struct CardStack {
 
             askForLine: while let line = askForLineInput(prompt: top.inputPrompt) {
                 inputFinished = false
-                let trimmedLine = String(line.drop { $0.isWhitespace }
-                                            .reversed()
-                                            .drop { $0.isWhitespace }
-                                            .reversed())
+                let trimmedLine = String(
+                    line.drop { $0.isWhitespace }
+                        .reversed()
+                        .drop { $0.isWhitespace }
+                        .reversed()
+                )
                 let response = await top.acceptLineInput(trimmedLine)
                 switch response {
                 case .none:

Sources/Commands/Snippets/Cards/SnippetCard.swift

@@ -14,8 +14,8 @@ import Basics
 import CoreCommands
 import PackageModel
 
-import enum TSCBasic.ProcessEnv
 import func TSCBasic.exec
+import enum TSCBasic.ProcessEnv
 
 /// A card displaying a ``Snippet`` at the terminal.
 struct SnippetCard: Card {
@@ -29,6 +29,7 @@ struct SnippetCard: Card {
             }
         }
     }
+
     /// The snippet to display in the terminal.
     var snippet: Snippet
 
@@ -39,20 +40,35 @@ struct SnippetCard: Card {
     var swiftCommandState: SwiftCommandState
 
     func render() -> String {
-        var rendered = colorized {
+        let isColorized: Bool = swiftCommandState.options.logging.colorDiagnostics
+        var rendered = isColorized ? colorized {
             brightYellow {
                 "# "
                 snippet.name
             }
             "\n\n"
         }.terminalString()
+            :
+            plain {
+                plain {
+                    "# "
+                    snippet.name
+                }
+                "\n\n"
+            }.terminalString()
 
         if !snippet.explanation.isEmpty {
-            rendered += brightBlack {
+            rendered += isColorized ? brightBlack {
+                snippet.explanation
+                    .split(separator: "\n", omittingEmptySubsequences: false)
+                    .map { "// " + $0 }
+                    .joined(separator: "\n")
+            }.terminalString()
+            : plain {
                 snippet.explanation
-                .split(separator: "\n", omittingEmptySubsequences: false)
-                .map { "// " + $0 }
-                .joined(separator: "\n")
+                    .split(separator: "\n", omittingEmptySubsequences: false)
+                    .map { "// " + $0 }
+                    .joined(separator: "\n")
             }.terminalString()
 
             rendered += "\n\n"