[APIDiff] Support forwarding breakage allowlists to the api digester

Author: owenv

Sources/Commands/APIDigester.swift

@@ -199,14 +199,18 @@ public struct SwiftAPIDigester {
     public func compareAPIToBaseline(
         at baselinePath: AbsolutePath,
         for module: String,
-        buildPlan: BuildPlan
+        buildPlan: BuildPlan,
+        breakageAllowlistPath: AbsolutePath?
     ) -> ComparisonResult? {
         var args = [
             "-diagnose-sdk",
             "-baseline-path", baselinePath.pathString,
             "-module", module
         ]
         args.append(contentsOf: buildPlan.createAPIToolCommonArgs(includeLibrarySearchPaths: false))
+        if let breakageAllowlistPath = breakageAllowlistPath {
+            args.append(contentsOf: ["-breakage-allowlist-path", breakageAllowlistPath.pathString])
+        }
 
         return try? withTemporaryFile(deleteOnClose: false) { file in
             args.append(contentsOf: ["-serialize-diagnostics-path", file.path.pathString])

Sources/Commands/SwiftPackageTool.swift

@@ -305,6 +305,14 @@ extension SwiftPackageTool {
         @OptionGroup(_hiddenFromHelp: true)
         var swiftOptions: SwiftToolOptions
 
+        @Option(help: """
+        The path to a text file containing breaking changes which should be ignored by the API comparison. \
+        Each ignored breaking change in the file should appear on its own line and contain the exact message \
+        to be ignored (e.g. 'API breakage: func foo() has been removed'). If this option is not present, \
+        a file named 'api-breakage-allowlist.txt' at the package root will be used if it exists.
+        """)
+        var breakageAllowlistPath: AbsolutePath?
+
         @Argument(help: "The baseline treeish to compare to (e.g. a commit hash, branch name, tag, etc.)")
         var treeish: String
 
@@ -343,6 +351,16 @@ extension SwiftPackageTool {
             )
             let baselineDir = try baselineDumper.emitAPIBaseline(for: modulesToDiff)
 
+            let allowlistPath: AbsolutePath?
+            let defaultAllowlistPath = try swiftTool.getPackageRoot().appending(component: "api-breakage-allowlist.txt")
+            if let breakageAllowlistPath = breakageAllowlistPath {
+                allowlistPath = breakageAllowlistPath
+            } else if localFileSystem.exists(defaultAllowlistPath) {
+                allowlistPath = defaultAllowlistPath
+            } else {
+                allowlistPath = nil
+            }
+
             let results = ThreadSafeArrayStore<SwiftAPIDigester.ComparisonResult>()
             let group = DispatchGroup()
             let semaphore = DispatchSemaphore(value: Int(buildOp.buildParameters.jobs))
@@ -360,7 +378,8 @@ extension SwiftPackageTool {
                     if let comparisonResult = apiDigesterTool.compareAPIToBaseline(
                         at: moduleBaselinePath,
                         for: module,
-                        buildPlan: buildOp.buildPlan!
+                        buildPlan: buildOp.buildPlan!,
+                        breakageAllowlistPath: allowlistPath
                     ) {
                         results.append(comparisonResult)
                     }

Tests/CommandsTests/APIDiffTests.swift

@@ -82,6 +82,62 @@ final class APIDiffTests: XCTestCase {
         #endif
     }
 
+    func testBreakageAllowlist() throws {
+        #if os(macOS)
+        guard (try? Resources.default.toolchain.getSwiftAPIDigester()) != nil else {
+            throw XCTSkip("swift-api-digester not available")
+        }
+        fixture(name: "Miscellaneous/APIDiff/") { prefix in
+            let packageRoot = prefix.appending(component: "Bar")
+            try localFileSystem.writeFileContents(packageRoot.appending(components: "Sources", "Baz", "Baz.swift")) {
+                $0 <<< "public func baz() -> String { \"hello, world!\" }"
+            }
+            try localFileSystem.writeFileContents(packageRoot.appending(components: "Sources", "Qux", "Qux.swift")) {
+                $0 <<< "public class Qux<T, U> { private let x = 1 }"
+            }
+            try localFileSystem.writeFileContents(packageRoot.appending(components: "api-breakage-allowlist.txt")) {
+                $0 <<< "API breakage: class Qux has generic signature change from <T> to <T, U>\n"
+                $0 <<< "API breakage: func bar() has been removed\n"
+            }
+            let customAllowlistPath = packageRoot.appending(components: "foo", "allowlist.txt")
+            try localFileSystem.writeFileContents(customAllowlistPath) {
+                $0 <<< "API breakage: class Qux has generic signature change from <T> to <T, U>\n"
+            }
+            try localFileSystem.writeFileContents(packageRoot.appending(components: "api-breakage-allowlist.txt")) {
+                $0 <<< "API breakage: class Qux has generic signature change from <T> to <T, U>\n"
+                $0 <<< "API breakage: func bar() has been removed\n"
+            }
+            XCTAssertThrowsError(try execute(["experimental-api-diff", "1.2.3", "-j", "2"], packagePath: packageRoot)) { error in
+                guard case SwiftPMProductError.executionFailure(error: _, output: let output, stderr: _) = error else {
+                    XCTFail("Unexpected error")
+                    return
+                }
+                XCTAssertTrue(output.contains("1 breaking change detected in Qux"))
+                XCTAssertFalse(output.contains("💔 API breakage: class Qux has generic signature change from <T> to <T, U>"))
+                XCTAssertTrue(output.contains("💔 API breakage: var Qux.x has been removed"))
+                XCTAssertTrue(output.contains("No breaking changes detected in Baz"))
+                XCTAssertFalse(output.contains("💔 API breakage: func bar() has been removed"))
+            }
+            XCTAssertThrowsError(try execute(["experimental-api-diff", "1.2.3", "-j", "2",
+                                              "--breakage-allowlist-path", customAllowlistPath.pathString],
+                                             packagePath: packageRoot)) { error in
+                guard case SwiftPMProductError.executionFailure(error: _, output: let output, stderr: _) = error else {
+                    XCTFail("Unexpected error")
+                    return
+                }
+                XCTAssertTrue(output.contains("1 breaking change detected in Qux"))
+                XCTAssertFalse(output.contains("💔 API breakage: class Qux has generic signature change from <T> to <T, U>"))
+                XCTAssertTrue(output.contains("💔 API breakage: var Qux.x has been removed"))
+                XCTAssertTrue(output.contains("1 breaking change detected in Baz"))
+                XCTAssertTrue(output.contains("💔 API breakage: func bar() has been removed"))
+            }
+
+        }
+        #else
+        throw XCTSkip("Test unsupported on current platform")
+        #endif
+    }
+
     func testCheckVendedModulesOnly() throws {
         #if os(macOS)
         guard (try? Resources.default.toolchain.getSwiftAPIDigester()) != nil else {