Support using the test file system in SwiftDocC tests (#756)

* Move FileManagerProtocol to a common target

* Move TestFileSystem into test utilities target

* Make TestFileSystem provide bundles like LocalFileSystemDataProvider

* Use FileManagerProtocol to read file contents in diagnostic formatter

#663

* Remove print statements in tests

* Remove unintended printing in tests

* Update InitActionTest to use _Common.FileManagerProtocol

* Avoid adding FileManagerProtocol in public API

* Move FileManagerProtocol to SwiftDocC as SPI to avoid adding new target

Author: d-ronnqvist

Package.swift

@@ -2,7 +2,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-2023 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
@@ -90,6 +90,7 @@ let package = Package(
         .target(
             name: "SwiftDocCTestUtilities",
             dependencies: [
+                .target(name: "SwiftDocC"),
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
             ],
             swiftSettings: swiftSettings

Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticConsoleWriter.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 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
@@ -27,18 +27,30 @@ public final class DiagnosticConsoleWriter: DiagnosticFormattingConsumer {
     ///   - formattingOptions: The formatting options for the diagnostics.
     ///   - baseUrl: A url to be used as a base url when formatting diagnostic source path.
     ///   - highlight: Whether or not to highlight the default diagnostic formatting output.
-    public init(
+    public convenience init(
         _ stream: TextOutputStream = LogHandle.standardError,
         formattingOptions options: DiagnosticFormattingOptions = [],
         baseURL: URL? = nil,
         highlight: Bool? = nil
+    ) {
+        self.init(stream, formattingOptions: options, baseURL: baseURL, highlight: highlight, fileManager: FileManager.default)
+    }
+    
+    @_spi(FileManagerProtocol)
+    public init(
+        _ stream: TextOutputStream = LogHandle.standardError,
+        formattingOptions options: DiagnosticFormattingOptions = [],
+        baseURL: URL? = nil,
+        highlight: Bool? = nil,
+        fileManager: FileManagerProtocol = FileManager.default
     ) {
         outputStream = stream
         formattingOptions = options
         diagnosticFormatter = Self.makeDiagnosticFormatter(
             options,
             baseURL: baseURL,
-            highlight: highlight ?? TerminalHelper.isConnectedToTerminal
+            highlight: highlight ?? TerminalHelper.isConnectedToTerminal,
+            fileManager: fileManager
         )
     }
 
@@ -72,31 +84,43 @@ public final class DiagnosticConsoleWriter: DiagnosticFormattingConsumer {
     private static func makeDiagnosticFormatter(
         _ options: DiagnosticFormattingOptions,
         baseURL: URL?,
-        highlight: Bool
+        highlight: Bool,
+        fileManager: FileManagerProtocol
     ) -> DiagnosticConsoleFormatter {
         if options.contains(.formatConsoleOutputForTools) {
             return IDEDiagnosticConsoleFormatter(options: options)
         } else {
-            return DefaultDiagnosticConsoleFormatter(baseUrl: baseURL, highlight: highlight, options: options)
+            return DefaultDiagnosticConsoleFormatter(baseUrl: baseURL, highlight: highlight, options: options, fileManager: fileManager)
         }
     }
 }
 
 // MARK: Formatted descriptions
 
 extension DiagnosticConsoleWriter {
-    
     public static func formattedDescription<Problems>(for problems: Problems, options: DiagnosticFormattingOptions = []) -> String where Problems: Sequence, Problems.Element == Problem {
-        return problems.map { formattedDescription(for: $0, options: options) }.joined(separator: "\n")
+        formattedDescription(for: problems, options: options, fileManager: FileManager.default)
+    }
+    @_spi(FileManagerProtocol)
+    public static func formattedDescription<Problems>(for problems: Problems, options: DiagnosticFormattingOptions = [], fileManager: FileManagerProtocol) -> String where Problems: Sequence, Problems.Element == Problem {
+        return problems.map { formattedDescription(for: $0, options: options, fileManager: fileManager) }.joined(separator: "\n")
     }
 
     public static func formattedDescription(for problem: Problem, options: DiagnosticFormattingOptions = []) -> String {
-        let diagnosticFormatter = makeDiagnosticFormatter(options, baseURL: nil, highlight: TerminalHelper.isConnectedToTerminal)
+        formattedDescription(for: problem, options: options, fileManager: FileManager.default)
+    }
+    @_spi(FileManagerProtocol)
+    public static func formattedDescription(for problem: Problem, options: DiagnosticFormattingOptions = [], fileManager: FileManagerProtocol = FileManager.default) -> String {
+        let diagnosticFormatter = makeDiagnosticFormatter(options, baseURL: nil, highlight: TerminalHelper.isConnectedToTerminal, fileManager: fileManager)
         return diagnosticFormatter.formattedDescription(for: problem)
     }
 
     public static func formattedDescription(for diagnostic: Diagnostic, options: DiagnosticFormattingOptions = []) -> String {
-        let diagnosticFormatter = makeDiagnosticFormatter(options, baseURL: nil, highlight: TerminalHelper.isConnectedToTerminal)
+        formattedDescription(for: diagnostic, options: options, fileManager: FileManager.default)
+    }
+    @_spi(FileManagerProtocol)
+    public static func formattedDescription(for diagnostic: Diagnostic, options: DiagnosticFormattingOptions = [], fileManager: FileManagerProtocol) -> String {
+        let diagnosticFormatter = makeDiagnosticFormatter(options, baseURL: nil, highlight: TerminalHelper.isConnectedToTerminal, fileManager: fileManager)
         return diagnosticFormatter.formattedDescription(for: diagnostic)
     }
 }
@@ -205,18 +229,21 @@ final class DefaultDiagnosticConsoleFormatter: DiagnosticConsoleFormatter {
     private let baseUrl: URL?
     private let highlight: Bool
     private var sourceLines: [URL: [String]] = [:]
+    private var fileManager: FileManagerProtocol
 
     /// The number of additional lines from the source file that should be displayed both before and after the diagnostic source line.
     private static let contextSize = 2
 
     init(
         baseUrl: URL?,
         highlight: Bool,
-        options: DiagnosticFormattingOptions
+        options: DiagnosticFormattingOptions,
+        fileManager: FileManagerProtocol
     ) {
         self.baseUrl = baseUrl
         self.highlight = highlight
         self.options = options
+        self.fileManager = fileManager
     }
 
     func formattedDescription<Problems>(for problems: Problems) -> String where Problems: Sequence, Problems.Element == Problem {
@@ -360,7 +387,7 @@ extension DefaultDiagnosticConsoleFormatter {
             // Example:
             // 9  | A line outside the diagnostic range.
             // 10 + A line inside the diagnostic range.
-            result.append("\n\(linePrefix) \(separator) \(highlightedSource)")
+            result.append("\n\(linePrefix) \(separator) \(highlightedSource)".removingTrailingWhitespace())
 
             var suggestionsPerColumn = [Int: [String]]()
 
@@ -466,8 +493,11 @@ extension DefaultDiagnosticConsoleFormatter {
         }
 
         // TODO: Add support for also getting the source lines from the symbol graph files.
-        guard let content = try? String(contentsOf: url)
-        else { return [] }
+        guard let data = fileManager.contents(atPath: url.path),
+              let content = String(data: data, encoding: .utf8)
+        else { 
+            return []
+        }
 
         let lines = content.splitByNewlines
         sourceLines[url] = lines

Sources/SwiftDocC/Infrastructure/Diagnostics/DiagnosticEngine.swift

@@ -33,6 +33,15 @@ public final class DiagnosticEngine {
         }
     }
 
+    /// Returns a Boolean value indicating whether the engine contains a consumer that satisfies the given predicate.
+    /// - Parameter predicate: A closure that takes one of the engine's consumers as its argument and returns a Boolean value that indicates whether the passed consumer represents a match.
+    /// - Returns: `true` if the engine contains a consumer that satisfies predicate; otherwise, `false`.
+    public func hasConsumer(matching predicate: (DiagnosticConsumer) throws -> Bool) rethrows -> Bool {
+        try consumers.sync {
+            try $0.values.contains(where: predicate)
+        }
+    }
+    
     /// Determines whether warnings will be treated as errors.
     private let treatWarningsAsErrors: Bool
 

Sources/SwiftDocCUtilities/Utility/FileManagerProtocol.swift renamed to Sources/SwiftDocC/Utility/FileManagerProtocol.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-2024 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
@@ -22,7 +22,8 @@ import Foundation
 /// Should you need a file system with a different storage, create your own
 /// protocol implementations to manage files in memory,
 /// on a network, in a database, or elsewhere.
-protocol FileManagerProtocol {
+@_spi(FileManagerProtocol)
+public protocol FileManagerProtocol {
 
     /// Returns the data content of a file at the given path, if it exists.
     func contents(atPath: String) -> Data?
@@ -73,9 +74,10 @@ protocol FileManagerProtocol {
     func createFile(at location: URL, contents: Data, options writingOptions: NSData.WritingOptions?) throws
 }
 
+@_spi(FileManagerProtocol)
 extension FileManagerProtocol {
     /// Returns a Boolean value that indicates whether a directory exists at a specified path.
-    func directoryExists(atPath path: String) -> Bool {
+    public func directoryExists(atPath path: String) -> Bool {
         var isDirectory = ObjCBool(booleanLiteral: false)
         let fileExistsAtPath = fileExists(atPath: path, isDirectory: &isDirectory)
         return fileExistsAtPath && isDirectory.boolValue
@@ -84,14 +86,15 @@ extension FileManagerProtocol {
 
 /// Add compliance to `FileManagerProtocol` to `FileManager`,
 /// most of the methods are already implemented in Foundation.
+@_spi(FileManagerProtocol)
 extension FileManager: FileManagerProtocol {
 
     // This method doesn't exist on `FileManager`. There is a similar looking method but it doesn't provide information about potential errors.
-    func createFile(at location: URL, contents: Data) throws {
+    public func createFile(at location: URL, contents: Data) throws {
         try contents.write(to: location, options: .atomic)
     }
 
-    func createFile(at location: URL, contents: Data, options writingOptions: NSData.WritingOptions?) throws {
+    public func createFile(at location: URL, contents: Data, options writingOptions: NSData.WritingOptions?) throws {
         if let writingOptions = writingOptions {
             try contents.write(to: location, options: writingOptions)
         } else {

Sources/SwiftDocC/Utility/FoundationExtensions/FileManager+directoryExists.swift

@@ -93,51 +93,41 @@ public struct InfoPlist: File, DataRepresentable {
     /// The information that the Into.plist file contains.
     public let content: Content
 
-    public init(displayName: String, identifier: String, versionString: String = "1.0", developmentRegion: String = "en") {
+    public init(displayName: String, identifier: String? = nil, versionString: String = "1.0") {
         self.content = Content(
             displayName: displayName,
             identifier: identifier,
-            versionString: versionString,
-            developmentRegion: developmentRegion
+            versionString: versionString
         )
     }
 
     public struct Content: Codable, Equatable {
         public let displayName: String
-        public let identifier: String
-        public let versionString: String
-        public let developmentRegion: String
+        public let identifier: String?
+        public let versionString: String?
 
-        fileprivate init(displayName: String, identifier: String, versionString: String, developmentRegion: String) {
+        fileprivate init(displayName: String, identifier: String?, versionString: String) {
             self.displayName = displayName
             self.identifier = identifier
             self.versionString = versionString
-            self.developmentRegion = developmentRegion
         }
 
         enum CodingKeys: String, CodingKey {
             case displayName = "CFBundleDisplayName"
             case identifier = "CFBundleIdentifier"
             case versionString = "CFBundleVersion"
-            case developmentRegion = "CFBundleDevelopmentRegion"
         }
     }
 
     public func data() throws -> Data {
-        // TODO: Replace this with PropertListEncoder (see below) when it's available in swift-corelibs-foundation
-        // https://github.com/apple/swift-corelibs-foundation/commit/d2d72f88d93f7645b94c21af88a7c9f69c979e4f
-        let infoPlist = [
+        let encoder = PropertyListEncoder()
+        encoder.outputFormat = .xml
+        
+        return try encoder.encode([
             Content.CodingKeys.displayName.rawValue: content.displayName,
             Content.CodingKeys.identifier.rawValue: content.identifier,
             Content.CodingKeys.versionString.rawValue: content.versionString,
-            Content.CodingKeys.developmentRegion.rawValue: content.developmentRegion,
-        ]
-
-        return try PropertyListSerialization.data(
-            fromPropertyList: infoPlist,
-            format: .xml,
-            options: 0
-        )
+        ])
     }
 }