improve handling of redundant output on stdout for commands that emit consumable information (#4118)

motvation: some CLI command emit consumable informaiton such as json. in those case we dont want to include any other information on stdout, so that it can be consumed by pipes

changes:

* for the following commands:
  * swift package dump-package
  * swift package dump-pif
  * swift package describe
  * swift package experimental-api-diff
  * swift package show-dependencies
  * swift test --list
* redirect stdout to stderr prior to calling other actions
* adjust result printing to always use stdout
* adjust tests

rdar://78612028

Author: tomerd

Sources/Commands/SwiftPackageTool.swift

@@ -173,6 +173,9 @@ extension SwiftPackageTool {
         var type: DescribeMode = .text
 
         func run(_ swiftTool: SwiftTool) throws {
+            // redirect all other output to stderr so that the output is the only thing that is printed on stdout
+            swiftTool.redirectStdoutToStderr()
+
             let workspace = try swiftTool.getActiveWorkspace()
 
             guard let packagePath = try swiftTool.getWorkspaceRoot().packages.first else {
@@ -187,11 +190,11 @@ extension SwiftPackageTool {
                 )
             }
 
-            try self.describe(package, in: type, on: swiftTool.outputStream)
+            try self.describe(package, in: type)
         }
 
         /// Emits a textual description of `package` to `stream`, in the format indicated by `mode`.
-        func describe(_ package: Package, in mode: DescribeMode, on stream: OutputByteStream) throws {
+        func describe(_ package: Package, in mode: DescribeMode) throws {
             let desc = DescribedPackage(from: package)
             let data: Data
             switch mode {
@@ -204,8 +207,7 @@ extension SwiftPackageTool {
                 encoder.formattingOptions = [.prettyPrinted]
                 data = try encoder.encode(desc)
             }
-            stream <<< String(decoding: data, as: UTF8.self) <<< "\n"
-            stream.flush()
+            print(String(decoding: data, as: UTF8.self))
         }
 
         enum DescribeMode: String, ExpressibleByArgument {
@@ -366,6 +368,9 @@ extension SwiftPackageTool {
         var regenerateBaseline: Bool = false
 
         func run(_ swiftTool: SwiftTool) throws {
+            // redirect all other output to stderr so that the output is the only thing that is printed on stdout
+            swiftTool.redirectStdoutToStderr()
+
             let apiDigesterPath = try swiftTool.getToolchain().getSwiftAPIDigester()
             let apiDigesterTool = SwiftAPIDigester(tool: apiDigesterPath)
 
@@ -595,6 +600,9 @@ extension SwiftPackageTool {
         var swiftOptions: SwiftToolOptions
 
         func run(_ swiftTool: SwiftTool) throws {
+            // redirect all other output to stderr so that the output is the only thing that is printed on stdout
+            swiftTool.redirectStdoutToStderr()
+
             let workspace = try swiftTool.getActiveWorkspace()
             let root = try swiftTool.getWorkspaceRoot()
 
@@ -626,6 +634,9 @@ extension SwiftPackageTool {
         var preserveStructure: Bool = false
 
         func run(_ swiftTool: SwiftTool) throws {
+            // redirect all other output to stderr so that the output is the only thing that is printed on stdout
+            swiftTool.redirectStdoutToStderr()
+
             let graph = try swiftTool.loadPackageGraph(createMultipleTestProducts: true)
             let parameters = try PIFBuilderParameters(swiftTool.buildParameters())
             let builder = PIFBuilder(
@@ -715,8 +726,13 @@ extension SwiftPackageTool {
         var outputPath: AbsolutePath?
 
         func run(_ swiftTool: SwiftTool) throws {
+            if outputPath == nil {
+                // redirect all other output to stderr so that the output is the only thing that is printed on stdout
+                swiftTool.redirectStdoutToStderr()
+            }
+
             let graph = try swiftTool.loadPackageGraph()
-            let stream = try outputPath.map { try LocalFileOutputByteStream($0) } ?? swiftTool.outputStream
+            let stream: OutputByteStream = try outputPath.map { try LocalFileOutputByteStream($0) } ?? TSCBasic.stdoutStream
             Self.dumpDependenciesOf(rootPackage: graph.rootPackages[0], mode: format, on: stream)
         }
 

Sources/Commands/SwiftTestTool.swift

@@ -211,6 +211,9 @@ public struct SwiftTestTool: SwiftCommand {
 
         switch options.mode {
         case .listTests:
+            // redirect all other output to stderr so that the list is the only thing that is printed on stdout
+            swiftTool.redirectStdoutToStderr()
+
             let testProducts = try buildTestsIfNeeded(swiftTool: swiftTool)
             let testSuites = try TestingSupport.getTestSuites(in: testProducts, swiftTool: swiftTool, swiftOptions: swiftOptions)
             let tests = try testSuites

Tests/FunctionalTests/DependencyResolutionTests.swift

@@ -91,8 +91,10 @@ class DependencyResolutionTests: XCTestCase {
             // run with no mirror
             do {
                 let output = try executeSwiftPackage(appPath, extraArgs: ["show-dependencies"])
-                XCTAssertMatch(output.stdout, .contains("Fetching \(prefix.pathString)/Foo\n"))
-                XCTAssertMatch(output.stdout, .contains("Fetching \(prefix.pathString)/Bar\n"))
+                // logs are in stderr
+                XCTAssertMatch(output.stderr, .contains("Fetching \(prefix.pathString)/Foo\n"))
+                XCTAssertMatch(output.stderr, .contains("Fetching \(prefix.pathString)/Bar\n"))
+                // results are in stdout
                 XCTAssertMatch(output.stdout, .contains("foo<\(prefix.pathString)/Foo@unspecified"))
                 XCTAssertMatch(output.stdout, .contains("bar<\(prefix.pathString)/Bar@unspecified"))
 
@@ -115,10 +117,11 @@ class DependencyResolutionTests: XCTestCase {
             // run with mirror
             do {
                 let output = try executeSwiftPackage(appPath, extraArgs: ["show-dependencies"])
-                XCTAssertMatch(output.stdout, .contains("Fetching \(prefix.pathString)/Foo\n"))
-                XCTAssertMatch(output.stdout, .contains("Fetching \(prefix.pathString)/BarMirror\n"))
-                XCTAssertNoMatch(output.stdout, .contains("Fetching \(prefix.pathString)/Bar\n"))
-
+                // logs are in stderr
+                XCTAssertMatch(output.stderr, .contains("Fetching \(prefix.pathString)/Foo\n"))
+                XCTAssertMatch(output.stderr, .contains("Fetching \(prefix.pathString)/BarMirror\n"))
+                XCTAssertNoMatch(output.stderr, .contains("Fetching \(prefix.pathString)/Bar\n"))
+                // result are in stdout
                 XCTAssertMatch(output.stdout, .contains("foo<\(prefix.pathString)/Foo@unspecified"))
                 XCTAssertMatch(output.stdout, .contains("barmirror<\(prefix.pathString)/BarMirror@unspecified"))
                 XCTAssertNoMatch(output.stdout, .contains("bar<\(prefix.pathString)/Bar@unspecified"))