Ensure that preview-specific errors are written to console (#1022)

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticConsoleWriter.swift

@@ -69,6 +69,7 @@ public final class DiagnosticConsoleWriter: DiagnosticFormattingConsumer {
         } else {
             let text = self.diagnosticFormatter.formattedDescription(for: problems)
             outputStream.write(text)
+            outputStream.write("\n")
         }
         problems = [] // `flush()` is called more than once. Don't emit the same problems again.
         self.diagnosticFormatter.finalize()

Sources/SwiftDocCUtilities/Action/Actions/PreviewAction.swift

@@ -59,8 +59,6 @@ public final class PreviewAction: Action, RecreatingContext {
 
     /// A unique ID to access the action's preview server.
     let serverIdentifier = ProcessInfo.processInfo.globallyUniqueString
-
-    private let diagnosticEngine: DiagnosticEngine
 
     /// Creates a new preview action from the given parameters.
     ///
@@ -89,9 +87,7 @@ public final class PreviewAction: Action, RecreatingContext {
         self.createConvertAction = createConvertAction
         self.convertAction = try createConvertAction()
         self.workspace = workspace
-        let engine = self.convertAction.diagnosticEngine
-        self.diagnosticEngine = engine
-        self.context = try context ?? DocumentationContext(dataProvider: workspace, diagnosticEngine: engine)
+        self.context = try context ?? DocumentationContext(dataProvider: workspace, diagnosticEngine: self.convertAction.diagnosticEngine)
         self.printHTMLTemplatePath = printTemplatePath
     }
 
@@ -155,7 +151,10 @@ public final class PreviewAction: Action, RecreatingContext {
             try servers[serverIdentifier]!.start()
             previewResult = ActionResult(didEncounterError: false)
         } catch {
+            let diagnosticEngine = convertAction.diagnosticEngine
             diagnosticEngine.emit(.init(description: error.localizedDescription, source: nil))
+            diagnosticEngine.flush()
+            
             // Stale server entry, remove it from the list
             servers.removeValue(forKey: serverIdentifier)
             previewResult = ActionResult(didEncounterError: true)

Tests/SwiftDocCTests/Diagnostics/DiagnosticConsoleWriterDefaultFormattingTest.swift

@@ -42,6 +42,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             \u{001B}[1;31merror: \(summary)\u{001B}[0;0m
             \(explanation)
             \(expectedPath)
+            
             """)
         }
 
@@ -56,6 +57,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             \u{001B}[1;33mwarning: \(summary)\u{001B}[0;0m
             \(explanation)
             \(expectedPath)
+            
             """)
         }
 
@@ -70,6 +72,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             \u{001B}[1;39mnotice: \(summary)\u{001B}[0;0m
             \(explanation)
             \(expectedPath)
+            
             """)
         }
 
@@ -84,6 +87,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             \u{001B}[1;39mnote: \(summary)\u{001B}[0;0m
             \(explanation)
             \(expectedPath)
+            
             """)
         }
     }
@@ -106,6 +110,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         \u{001B}[1;33mwarning: \(summary)\u{001B}[0;0m
         \(explanation)
         --> file.md:1:8-10:21
+        
         """)
     }
 
@@ -140,6 +145,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         \(explanation)
         /path/to/other/file.md:1:1: This is a note
         --> /path/to/file.md:1:8-10:21
+        
         """)
     }
 
@@ -214,6 +220,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         \u{001B}[1;33mwarning: Third diagnostic summary\u{001B}[0;0m
         Third diagnostic explanation
         --> /path/to/other/file.md
+        
         """)
     }
 
@@ -243,6 +250,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         44 +          This section link refers to this section itself: \u{001B}[1;32m<doc:/tutorials/Test-Bundle/TestTutorial#Create-a-New-AR-Project-%F0%9F%92%BB>.\u{001B}[0;0m
         45 |          This is an external link to Swift documentation: [Swift Documentation](https://swift.org/documentation/).
         46 |          This section link refers to the next section in this file: <doc:/tutorials/Test-Bundle/TestTutorial#Initiate-ARKit-Plane-Detection>.
+        
         """)
     }
 
@@ -288,6 +296,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
         3 + A short abstract \u{001B}[1;32mwith emoji 💻 in\u{001B}[0;0m it.
         4 |
         5 | @Metadata {
+        
         """)
     }
 
@@ -332,6 +341,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
                |                                                           ╰─\u{001B}[1;39msuggestion: Solution summary\u{001B}[0;0m
             45 |          This is an external link to Swift documentation: [Swift Documentation](https://swift.org/documentation/).
             46 |          This section link refers to the next section in this file: <doc:/tutorials/Test-Bundle/TestTutorial#Initiate-ARKit-Plane-Detection>.
+            
             """)
         }
 
@@ -355,6 +365,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
                |                                                           ╰─\u{001B}[1;39msuggestion: Solution summary\u{001B}[0;0m
             45 |          This is an external link to Swift documentation: [Swift Documentation](https://swift.org/documentation/).
             46 |          This section link refers to the next section in this file: <doc:/tutorials/Test-Bundle/TestTutorial#Initiate-ARKit-Plane-Detection>.
+            
             """)
         }
 
@@ -386,6 +397,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
                |                                                           ╰─\u{001B}[1;39msuggestion: Solution summary\u{001B}[0;0m
             45 |          This is an external link to Swift documentation: [Swift Documentation](https://swift.org/documentation/).
             46 |          This section link refers to the next section in this file: <doc:/tutorials/Test-Bundle/TestTutorial#Initiate-ARKit-Plane-Detection>.
+            
             """)
         }
     }
@@ -431,6 +443,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             1 + # \u{001B}[1;32mTitle\u{001B}[0;0m
             2 |
             3 | A very short article with only an abstract.
+            
             """)
 
         // Highlight the "short" word on line 3
@@ -441,6 +454,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             1 | # Title
             2 |
             3 + A very \u{001B}[1;32mshort\u{001B}[0;0m article with only an abstract.
+            
             """)
 
         // Extend the highlight beyond the end of that line
@@ -451,6 +465,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             1 | # Title
             2 |
             3 + A very \u{001B}[1;32mshort article with only an abstract.\u{001B}[0;0m
+            
             """)
 
         // Extend the highlight beyond the start of that line
@@ -461,34 +476,39 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             1 | # Title
             2 |
             3 + \u{001B}[1;32mA very short\u{001B}[0;0m article with only an abstract.
+            
             """)
 
         // Highlight a line before the start of the file
         XCTAssertEqual(try logMessageFor(start: (line: -4, column: 1), end: (line: -4, column: 5)), """
             \u{001B}[1;33mwarning: \(summary)\u{001B}[0;0m
             \(explanation)
             --> Something.docc/Article.md:1:1-1:5
+            
             """)
 
         // Highlight a line after the end of the file
         XCTAssertEqual(try logMessageFor(start: (line: 100, column: 1), end: (line: 100, column: 5)), """
             \u{001B}[1;33mwarning: \(summary)\u{001B}[0;0m
             \(explanation)
             --> Something.docc/Article.md:100:1-100:5
+            
             """)
 
         // Extended the highlighted lines before the start of the file
         XCTAssertEqual(try logMessageFor(start: (line: -4, column: 1), end: (line: 1, column: 5)), """
             \u{001B}[1;33mwarning: \(summary)\u{001B}[0;0m
             \(explanation)
             --> Something.docc/Article.md:1:1-1:5
+            
             """)
 
         // Extended the highlighted lines after the end of the file
         XCTAssertEqual(try logMessageFor(start: (line: 1, column: 1), end: (line: 100, column: 5)), """
             \u{001B}[1;33mwarning: \(summary)\u{001B}[0;0m
             \(explanation)
             --> Something.docc/Article.md:1:1-100:5
+            
             """)
     }
 
@@ -522,6 +542,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             suggestion:
             0 + var slothName = \"slothy\"
             1 + var slothDiet = .vegetarian
+            
             """
         )
 
@@ -554,6 +575,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             suggestion:
             0 + var slothName = SlothGenerator().generateName()
             1 + var slothDiet = SlothGenerator().generateDiet()
+            
             """
         )
 
@@ -589,6 +611,7 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             suggestion:
             0 + var beeName = "Bee"
             1 + var beeDiet = .vegetarian
+            
             """
         )
     }

Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift

@@ -685,7 +685,7 @@ class ParametersAndReturnValidatorTests: XCTestCase {
         })
 
         context.diagnosticEngine.flush()
-        return logStorage.text
+        return logStorage.text.trimmingCharacters(in: .newlines)
     }
 
     private let start = SymbolGraph.LineList.SourceRange.Position(line: 7, character: 6) // an arbitrary non-zero start position

Tests/SwiftDocCTests/Utility/ListItemExtractorTests.swift

@@ -325,6 +325,7 @@ class ListItemExtractorTests: XCTestCase {
         19 |   ```
         20 |
         21 +   > Warning: Inner aside, with ``\u{001B}[1;32mThirdNotFoundSymbol\u{001B}[0;0m`` link
+        
         """, file: file, line: line)
     }
 
@@ -391,6 +392,7 @@ class ListItemExtractorTests: XCTestCase {
         20 |     ```
         21 |
         22 +     > Warning: Inner aside, with ``\u{001B}[1;32mThirdNotFoundSymbol\u{001B}[0;0m`` link
+        
         """, file: file, line: line)
     }
 

Tests/SwiftDocCUtilitiesTests/PreviewActionIntegrationTests.swift

@@ -315,8 +315,6 @@ class PreviewActionIntegrationTests: XCTestCase {
         }
         // Start watching the source and get the initial (successful) state.
         do {
-            let engine = preview.convertAction.diagnosticEngine
-            
             // Wait for watch to produce output.
             let logOutputExpectation = expectation(description: "Did produce log output")
             let logChecker = OutputChecker(fileURL: pipeURL, expectation: logOutputExpectation) { output in
@@ -334,7 +332,7 @@ class PreviewActionIntegrationTests: XCTestCase {
                 }
 
                 XCTAssertTrue(result.didEncounterError, "Did not find an error when running preview", file: file, line: line)
-                XCTAssertNotNil(engine.problems.first(where: { problem -> Bool in
+                XCTAssertNotNil(preview.convertAction.diagnosticEngine.problems.first(where: { problem -> Bool in
                     DiagnosticConsoleWriter.formattedDescription(for: problem.diagnostic).contains(expectedErrorMessage)
                 }), "Didn't find expected error message '\(expectedErrorMessage)'", file: file, line: line)