- formattedDiagnosticSource allows addition of new content file into the diagnostic message.

- Replaced `org.swift.docc.MissingTechnologyRoot` diagnostic for `org.swift.docc.MissingTableOfContents`

Author: sofiaromorales

Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticConsoleWriter.swift

@@ -294,9 +294,29 @@ extension DefaultDiagnosticConsoleFormatter {
 
         guard let url = diagnostic.source
         else { return "" }
-        
         guard let diagnosticRange = diagnostic.range
-        else { return "\n--> \(formattedSourcePath(url))" }
+        else {
+            // If the replacement operation involves adding new files,
+            // emit the file content as an addition instead of a replacement.
+            //
+            // Example:
+            // --> /path/to/new/file.md
+            // Summary
+            // suggestion:
+            // 0 + Addition file and
+            // 1 + multiline file content.
+            var addition = ""
+            solutions.forEach { solution in
+                addition.append("\n" + solution.summary)
+                solution.replacements.forEach { replacement in
+                    let solutionFragments = replacement.replacement.split(separator: "\n")
+                    addition += "\nsuggestion:\n" + solutionFragments.enumerated().map {
+                        "\($0.offset) + \($0.element)"
+                    }.joined(separator: "\n")
+                }
+            }
+            return "\n--> \(formattedSourcePath(url))\(addition)"
+        }
 
         let sourceLines = readSourceLines(url)
 

Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift

@@ -469,23 +469,39 @@ public struct ConvertAction: Action, RecreatingContext {
         }
 
         var didEncounterError = analysisProblems.containsErrors || conversionProblems.containsErrors
-        if (try context.renderRootModules + context.rootTechnologies).isEmpty {
-            // Check if the converted documentation is a tutorial to provide
-            // a specific error message.
-            let hasTutorial = context.knownPages.contains(where: {
-                guard let kind = try? context.entity(with: $0).kind else { return false }
-                return kind == .tutorial || kind == .tutorialArticle
-            })
+        let hasTutorial = context.knownPages.contains(where: {
+            guard let kind = try? context.entity(with: $0).kind else { return false }
+            return kind == .tutorial || kind == .tutorialArticle
+        })
+        // Warn the user if the catalog is a tutorial but does not contains a table of contents
+        // and provide template content to fix this problem.
+        if (
+            context.rootTechnologies.isEmpty &&
+            hasTutorial &&
+            !analysisProblems.contains(where: {$0.diagnostic.identifier == "org.swift.docc.HasExactlyOne<Tutorials, Intro>.Missing"})
+        ) {
+            let tableOfContentsFilename = "table-of-contents.tutorial"
+            let source = rootURL?.appendingPathComponent(tableOfContentsFilename)
             postConversionProblems.append(
                 Problem(
                     diagnostic: Diagnostic(
+                        source: source,
                         severity: .warning,
-                        identifier: "org.swift.docc.MissingTechnologyRoot",
-                         summary: "There was no root found for this documentation catalog.",
-                         explanation: hasTutorial ? """
-                        For Tutorials please add a table of contents page (indicated by a `Tutorials` directive with the corresponding `Intro` and `Chapters` directive) to define the root of the documentation hierarchy. \n
-                        """ : ""
-                     )
+                        identifier: "org.swift.docc.MissingTableOfContents",
+                        summary: "Missing tutorial table of contents page.",
+                        explanation: "`@Tutorial` and `@Article` pages require a `@Tutorials` table of content page to define the documentation hierarchy."
+                    ),
+                    possibleSolutions: [
+                        Solution(
+                            summary: "Create a `@Tutorials` table of content page.",
+                            replacements: [
+                                Replacement(
+                                    range: .init(line: 1, column: 1, source: source) ..< .init(line: 1, column: 1, source: source),
+                                    replacement: CatalogTemplateKind.tutorialTemplateFiles(converter.firstAvailableBundle()?.displayName ?? "Project Name")[tableOfContentsFilename]! // this file name is known to exist in the dictionary
+                                )
+                            ]
+                        )
+                    ]
                 )
             )
         }

Tests/SwiftDocCTests/Diagnostics/DiagnosticConsoleWriterDefaultFormattingTest.swift

@@ -375,4 +375,105 @@ class DiagnosticConsoleWriterDefaultFormattingTest: XCTestCase {
             """)
         }
     }
+    
+    func testEmitAdditionReplacementSolution() throws {
+        func problemsLoggerOutput(possibleSolutions: [Solution]) -> String {
+            let logger = Logger()
+            let consumer = DiagnosticConsoleWriter(logger)
+            let problem = Problem(diagnostic: Diagnostic(source: URL(fileURLWithPath: "/path/to/file.md"), severity: .warning, range: nil, identifier: "org.swift.docc.tests", summary: "Test diagnostic"), possibleSolutions: possibleSolutions)
+            consumer.receive([problem])
+            try? consumer.flush()
+            return logger.output
+        }
+        let sourcelocation = SourceLocation(line: 1, column: 1, source: nil)
+        let range = sourcelocation..<sourcelocation
+        XCTAssertEqual(
+            problemsLoggerOutput(possibleSolutions: [
+                Solution(summary: "Create a sloth.", replacements: [
+                    Replacement(
+                        range: range,
+                        replacement: """
+                        var slothName = "slothy"
+                        var slothDiet = .vegetarian
+                        """
+                    )
+                ])
+            ]),
+            """
+            \u{1B}[1;33mwarning: Test diagnostic\u{1B}[0;0m
+            --> /path/to/file.md
+            Create a sloth.
+            suggestion:
+            0 + var slothName = \"slothy\"
+            1 + var slothDiet = .vegetarian
+            """
+        )
+        
+        XCTAssertEqual(
+            problemsLoggerOutput(possibleSolutions: [
+                Solution(summary: "Create a sloth.", replacements: [
+                    Replacement(
+                        range: range,
+                        replacement: """
+                        var slothName = "slothy"
+                        var slothDiet = .vegetarian
+                        """
+                    ),
+                    Replacement(
+                        range: range,
+                        replacement: """
+                        var slothName = SlothGenerator().generateName()
+                        var slothDiet = SlothGenerator().generateDiet()
+                        """
+                    )
+                ])
+            ]),
+            """
+            \u{1B}[1;33mwarning: Test diagnostic\u{1B}[0;0m
+            --> /path/to/file.md
+            Create a sloth.
+            suggestion:
+            0 + var slothName = "slothy"
+            1 + var slothDiet = .vegetarian
+            suggestion:
+            0 + var slothName = SlothGenerator().generateName()
+            1 + var slothDiet = SlothGenerator().generateDiet()
+            """
+        )
+        
+        XCTAssertEqual(
+            problemsLoggerOutput(possibleSolutions: [
+                Solution(summary: "Create a sloth.", replacements: [
+                    Replacement(
+                        range: range,
+                        replacement: """
+                        var slothName = "slothy"
+                        var slothDiet = .vegetarian
+                        """
+                    ),
+                ]),
+                Solution(summary: "Create a bee.", replacements: [
+                    Replacement(
+                        range: range,
+                        replacement: """
+                        var beeName = "Bee"
+                        var beeDiet = .vegetarian
+                        """
+                    )
+                ])
+            ]),
+            """
+            \u{1B}[1;33mwarning: Test diagnostic\u{1B}[0;0m
+            --> /path/to/file.md
+            Create a sloth.
+            suggestion:
+            0 + var slothName = "slothy"
+            1 + var slothDiet = .vegetarian
+            Create a bee.
+            suggestion:
+            0 + var beeName = "Bee"
+            1 + var beeDiet = .vegetarian
+            """
+        )
+    }
 }

Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift

@@ -3092,13 +3092,6 @@ class ConvertActionTests: XCTestCase {
             return engine.problems
         }
 
-        
-        let TutorialArticleWithNoContentProblems = try problemsFromConverting([
-            InfoPlist(displayName: "TestBundle", identifier: "com.test.example"),
-            TextFile(name: "Article.tutorial", utf8Content: "")
-        ])
-        XCTAssert(TutorialArticleWithNoContentProblems.contains(where: { $0.diagnostic.identifier == "org.swift.docc.MissingTechnologyRoot" }))
-        
         let onlyTutorialArticleProblems = try problemsFromConverting([
             InfoPlist(displayName: "TestBundle", identifier: "com.test.example"),
             TextFile(name: "Article.tutorial", utf8Content: """
@@ -3110,17 +3103,27 @@ class ConvertActionTests: XCTestCase {
                 """
             ),
         ])
-        XCTAssert(onlyTutorialArticleProblems.contains(where: { $0.diagnostic.identifier == "org.swift.docc.MissingTechnologyRoot" }))
+        XCTAssert(onlyTutorialArticleProblems.contains(where: {
+            $0.diagnostic.identifier == "org.swift.docc.MissingTableOfContents"
+        }))
 
         let tutorialTableOfContentProblem = try problemsFromConverting([
             InfoPlist(displayName: "TestBundle", identifier: "com.test.example"),
             TextFile(name: "table-of-contents.tutorial", utf8Content: """
-                @Tutorials(name: "Tutorial") {
+                """
+            ),
+            TextFile(name: "article.tutorial", utf8Content: """
+                @Article(time: 20) {
+                   @Intro(title: "Slothy Tutorials") {
+                      This is an abstract for the intro.
+                   }
                 }
                 """
             ),
         ])
-        XCTAssert(tutorialTableOfContentProblem.contains(where: { $0.diagnostic.identifier == "org.swift.docc.MissingTechnologyRoot" }))
+        XCTAssert(tutorialTableOfContentProblem.contains(where: {
+            $0.diagnostic.identifier == "org.swift.docc.MissingTableOfContents"
+        }))
     }
 
     func testWrittenDiagnosticsAfterConvert() throws {
@@ -3159,21 +3162,20 @@ class ConvertActionTests: XCTestCase {
         )
 
         let _ = try action.perform(logHandle: .standardOutput)
-        XCTAssertEqual(engine.problems.count, 2)
+        XCTAssertEqual(engine.problems.count, 1)
 
         XCTAssert(FileManager.default.fileExists(atPath: diagnosticFile.path))
 
         let diagnosticFileContent = try JSONDecoder().decode(DiagnosticFile.self, from: Data(contentsOf: diagnosticFile))
-        XCTAssertEqual(diagnosticFileContent.diagnostics.count, 2)
+        XCTAssertEqual(diagnosticFileContent.diagnostics.count, 1)
 
         XCTAssertEqual(diagnosticFileContent.diagnostics.map(\.summary).sorted(), [
-            "There was no root found for this documentation catalog.",
             "No symbol matched 'ModuleThatDoesNotExist'. Can't resolve 'ModuleThatDoesNotExist'."
         ].sorted())
 
         let logLines = logStorage.text.splitByNewlines
-        XCTAssertEqual(logLines.filter { ($0 as NSString).contains("warning:") }.count, 2, "There should be two warnings printed to the console")
-        XCTAssertEqual(logLines.filter { ($0 as NSString).contains("There was no root found for this documentation catalog.") }.count, 1, "The root page warning shouldn't be repeated.")
+        XCTAssertEqual(logLines.filter { ($0 as NSString).contains("warning:") }.count, 1, "There should be two warnings printed to the console")
+        XCTAssertEqual(logLines.filter { ($0 as NSString).contains("There was no root found for this documentation catalog.") }.count, 0, "The root page warning shouldn't be repeated.")
         XCTAssertEqual(logLines.filter { ($0 as NSString).contains("No symbol matched 'ModuleThatDoesNotExist'. Can't resolve 'ModuleThatDoesNotExist'.") }.count, 1, "The link warning shouldn't be repeated.")
     }