Add support for "warnings as errors" (#365)

Kyle-Ye · web-flow · commit 566a1770f491 · 2022-09-10T13:02:44.000+08:00
diff --git a/Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticEngine.swift b/Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticEngine.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -32,6 +32,9 @@ public final class DiagnosticEngine {
             self.filter = { $0.diagnostic.severity.rawValue <= self.filterLevel.rawValue }
         }
     }
+    
+    /// Determines whether warnings will be treated as errors.
+    private let treatWarningsAsErrors: Bool
 
     /// Determines which problems should be emitted.
     private var filter: (Problem) -> Bool
@@ -42,8 +45,9 @@ public final class DiagnosticEngine {
     }
 
     /// Creates a new diagnostic engine instance with no consumers.
-    public init(filterLevel: DiagnosticSeverity = .warning) {
+    public init(filterLevel: DiagnosticSeverity = .warning, treatWarningsAsErrors: Bool = false) {
         self.filterLevel = filterLevel
+        self.treatWarningsAsErrors = treatWarningsAsErrors
         self.filter = { $0.diagnostic.severity.rawValue <= filterLevel.rawValue }
     }
 
@@ -65,7 +69,14 @@ public final class DiagnosticEngine {
     /// - Parameter problems: The array of diagnostics to dispatch to this engine's currently subscribed consumers.
     /// > Note: Diagnostics are dispatched asynchronously.
     public func emit(_ problems: [Problem]) {
-        let filteredProblems = problems.filter(filter)
+        let mappedProblems = problems.map { problem -> Problem in
+            var problem = problem
+            if treatWarningsAsErrors, problem.diagnostic.severity == .warning {
+                problem.diagnostic.severity = .error
+            }
+            return problem
+        }
+        let filteredProblems = mappedProblems.filter(filter)
         guard !filteredProblems.isEmpty else { return }
 
         if filteredProblems.containsErrors {
diff --git a/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift b/Sources/SwiftDocCUtilities/Action/Actions/Convert/ConvertAction.swift
@@ -33,6 +33,7 @@ public struct ConvertAction: Action, RecreatingContext {
     let htmlTemplateDirectory: URL?
     let emitDigest: Bool
     let inheritDocs: Bool
+    let treatWarningsAsErrors: Bool
     let experimentalEnableCustomTemplates: Bool
     let buildLMDBIndex: Bool
     let documentationCoverageOptions: DocumentationCoverageOptions
@@ -99,6 +100,7 @@ public struct ConvertAction: Action, RecreatingContext {
         diagnosticEngine: DiagnosticEngine? = nil,
         emitFixits: Bool = false,
         inheritDocs: Bool = false,
+        treatWarningsAsErrors: Bool = false,
         experimentalEnableCustomTemplates: Bool = false,
         transformForStaticHosting: Bool = false,
         hostingBasePath: String? = nil,
@@ -135,10 +137,11 @@ public struct ConvertAction: Action, RecreatingContext {
             formattingOptions = []
         }
         self.inheritDocs = inheritDocs
+        self.treatWarningsAsErrors = treatWarningsAsErrors
 
         self.experimentalEnableCustomTemplates = experimentalEnableCustomTemplates
         
-        let engine = diagnosticEngine ?? DiagnosticEngine()
+        let engine = diagnosticEngine ?? DiagnosticEngine(treatWarningsAsErrors: treatWarningsAsErrors)
         engine.filterLevel = filterLevel
         engine.add(DiagnosticConsoleWriter(formattingOptions: formattingOptions))
         
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/ActionExtensions/ConvertAction+CommandInitialization.swift
@@ -78,6 +78,7 @@ extension ConvertAction {
             diagnosticLevel: convert.diagnosticLevel,
             emitFixits: convert.emitFixits,
             inheritDocs: convert.enableInheritedDocs,
+            treatWarningsAsErrors: convert.warningsAsErrors,
             experimentalEnableCustomTemplates: convert.experimentalEnableCustomTemplates,
             transformForStaticHosting: convert.transformForStaticHosting,
             hostingBasePath: convert.hostingBasePath,
diff --git a/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift b/Sources/SwiftDocCUtilities/ArgumentParsing/Subcommands/Convert.swift
@@ -138,6 +138,10 @@ extension Docc {
         @Flag(help: "Inherit documentation for inherited symbols")
         public var enableInheritedDocs = false
         
+        
+        @Flag(help: "Treat warnings as errors")
+        public var warningsAsErrors = false
+        
         /// Arguments for specifying information about the source code repository that hosts the documented project's code.
         @OptionGroup()
         public var sourceRepositoryArguments: SourceRepositoryArguments
diff --git a/Tests/SwiftDocCTests/Diagnostics/DiagnosticEngineTests.swift b/Tests/SwiftDocCTests/Diagnostics/DiagnosticEngineTests.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -129,4 +129,38 @@ class DiagnosticEngineTests: XCTestCase {
             note: Test information
             """)
     }
+    
+    func testTreatWarningsAsErrors() {
+        let error = Problem(diagnostic: Diagnostic(source: nil, severity: .error, range: nil, identifier: "org.swift.docc.tests", summary: "Test error"), possibleSolutions: [])
+        let warning = Problem(diagnostic: Diagnostic(source: nil, severity: .warning, range: nil, identifier: "org.swift.docc.tests", summary: "Test warning"), possibleSolutions: [])
+        let information = Problem(diagnostic: Diagnostic(source: nil, severity: .information, range: nil, identifier: "org.swift.docc.tests", summary: "Test information"), possibleSolutions: [])
+
+        let defaultEngine = DiagnosticEngine()
+        defaultEngine.emit(error)
+        defaultEngine.emit(warning)
+        defaultEngine.emit(information)
+        XCTAssertEqual(defaultEngine.problems.localizedDescription, """
+            error: Test error
+            warning: Test warning
+            """)
+
+        let engine = DiagnosticEngine(filterLevel: .information, treatWarningsAsErrors: true)
+        engine.emit(error)
+        engine.emit(warning)
+        engine.emit(information)
+        XCTAssertEqual(engine.problems.localizedDescription, """
+            error: Test error
+            error: Test warning
+            note: Test information
+            """)
+        
+        let errorFilterLevelEngine = DiagnosticEngine(filterLevel: .error, treatWarningsAsErrors: true)
+        errorFilterLevelEngine.emit(error)
+        errorFilterLevelEngine.emit(warning)
+        errorFilterLevelEngine.emit(information)
+        XCTAssertEqual(errorFilterLevelEngine.problems.localizedDescription, """
+            error: Test error
+            error: Test warning
+            """)
+    }
 }
diff --git a/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift b/Tests/SwiftDocCUtilitiesTests/ArgumentParsing/ConvertSubcommandTests.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -437,4 +437,26 @@ class ConvertSubcommandTests: XCTestCase {
             XCTAssertFalse(convertOptions.transformForStaticHosting)
         }
     }
+    
+    func testTreatWarningAsrror() throws {
+        setenv(TemplateOption.environmentVariableKey, testTemplateURL.path, 1)
+        do {
+            // Passing no argument should default to the current working directory.
+            let convert = try Docc.Convert.parse([])
+            let convertAction = try ConvertAction(fromConvertCommand: convert)
+            XCTAssertEqual(convertAction.treatWarningsAsErrors, false)
+        } catch {
+            XCTFail("Failed to run docc convert without arguments.")
+        }
+        do {
+            // Passing no argument should default to the current working directory.
+            let convert = try Docc.Convert.parse([
+                "--warnings-as-errors"
+            ])
+            let convertAction = try ConvertAction(fromConvertCommand: convert)
+            XCTAssertEqual(convertAction.treatWarningsAsErrors, true)
+        } catch {
+            XCTFail("Failed to run docc convert without arguments.")
+        }
+    }
 }
diff --git a/Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift b/Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -2557,6 +2557,87 @@ class ConvertActionTests: XCTestCase {
         expectedOutput.assertExist(at: result.outputs[0], fileManager: FileManager.default)
     }
     
+    func testTreatWarningsAsErrors() throws {
+        let bundle = Folder(name: "unit-test.docc", content: [
+            InfoPlist(displayName: "TestBundle", identifier: "com.test.example"),
+            CopyOfFile(original: symbolGraphFile, newName: "MyKit.symbols.json"),
+            TextFile(name: "Article.md", utf8Content: """
+            Bad title
+
+            This article has a malformed title and can't be analyzed, so it
+            produces one warning.
+            """),
+        ])
+
+        let testDataProvider = try TestFileSystem(folders: [bundle, Folder.emptyHTMLTemplateDirectory])
+        let targetDirectory = URL(fileURLWithPath: testDataProvider.currentDirectoryPath)
+            .appendingPathComponent("target", isDirectory: true)
+
+        // Test DiagnosticEngine with "treatWarningsAsErrors" set to false
+        do {
+            let engine = DiagnosticEngine(treatWarningsAsErrors: false)
+            var action = try ConvertAction(
+                documentationBundleURL: bundle.absoluteURL,
+                outOfProcessResolver: nil,
+                analyze: true,
+                targetDirectory: targetDirectory,
+                htmlTemplateDirectory: Folder.emptyHTMLTemplateDirectory.absoluteURL,
+                emitDigest: false,
+                currentPlatforms: nil,
+                dataProvider: testDataProvider,
+                fileManager: testDataProvider,
+                temporaryDirectory: createTemporaryDirectory(),
+                diagnosticEngine: engine
+            )
+            let result = try action.perform(logHandle: .none)
+            XCTAssertEqual(engine.problems.count, 1)
+            XCTAssertTrue(engine.problems.contains(where: { $0.diagnostic.severity == .warning }))
+            XCTAssertFalse(result.didEncounterError)
+        }
+        
+        // Test DiagnosticEngine with "treatWarningsAsErrors" set to true
+        do {
+            let engine = DiagnosticEngine(treatWarningsAsErrors: true)
+            var action = try ConvertAction(
+                documentationBundleURL: bundle.absoluteURL,
+                outOfProcessResolver: nil,
+                analyze: true,
+                targetDirectory: targetDirectory,
+                htmlTemplateDirectory: Folder.emptyHTMLTemplateDirectory.absoluteURL,
+                emitDigest: false,
+                currentPlatforms: nil,
+                dataProvider: testDataProvider,
+                fileManager: testDataProvider,
+                temporaryDirectory: createTemporaryDirectory(),
+                diagnosticEngine: engine
+            )
+            let result = try action.perform(logHandle: .none)
+            XCTAssertEqual(engine.problems.count, 1)
+            XCTAssertTrue(result.didEncounterError)
+        }
+        
+        do {
+            var action = try ConvertAction(
+                documentationBundleURL: bundle.absoluteURL,
+                outOfProcessResolver: nil,
+                analyze: true,
+                targetDirectory: targetDirectory,
+                htmlTemplateDirectory: Folder.emptyHTMLTemplateDirectory.absoluteURL,
+                emitDigest: false,
+                currentPlatforms: nil,
+                dataProvider: testDataProvider,
+                fileManager: testDataProvider,
+                temporaryDirectory: createTemporaryDirectory(),
+                diagnosticEngine: nil,
+                treatWarningsAsErrors: true
+            )
+            let result = try action.perform(logHandle: .none)
+            XCTAssertTrue(result.didEncounterError)
+        }
+
+    }
+
+    
     private func uniformlyPrintDiagnosticMessages(_ problems: [Problem]) -> String {
         return problems.sorted(by: { (lhs, rhs) -> Bool in
             guard lhs.diagnostic.identifier != rhs.diagnostic.identifier else {
