[APIDiff] Add baseline management flags (#3532)

* [APIDiff] Allow overriding the baselines directory

* [APIDiff] Support force-regenerating the baseline with --regenerate-baseline

Author: owenv

Sources/Commands/APIDigester.swift

@@ -64,18 +64,20 @@ struct APIDigesterBaselineDumper {
     }
 
     /// Emit the API baseline files and return the path to their directory.
-    func emitAPIBaseline(for modulesToDiff: Set<String>) throws -> AbsolutePath {
+    func emitAPIBaseline(for modulesToDiff: Set<String>,
+                         at baselineDir: AbsolutePath?,
+                         force: Bool) throws -> AbsolutePath {
         var modulesToDiff = modulesToDiff
         let apiDiffDir = inputBuildParameters.apiDiff
-        let baselineDir = apiDiffDir.appending(component: baselineTreeish)
+        let baselineDir = (baselineDir ?? apiDiffDir).appending(component: baselineTreeish)
         let baselinePath: (String)->AbsolutePath = { module in
             baselineDir.appending(component: module + ".json")
         }
 
-        for module in modulesToDiff {
-            if localFileSystem.exists(baselinePath(module)) {
-                // If this baseline already exists, we don't need to regenerate it.
-                modulesToDiff.remove(module)
+        if !force {
+            // Baselines which already exist don't need to be regenerated.
+            modulesToDiff = modulesToDiff.filter {
+                !localFileSystem.exists(baselinePath($0))
             }
         }
 

Sources/Commands/SwiftPackageTool.swift

@@ -323,6 +323,13 @@ extension SwiftPackageTool {
                 help: "One or more targets to include in the API comparison. If present, only the specified targets (and any products specified using `--products`) will be compared.")
         var targets: [String] = []
 
+        @Option(name: .customLong("baseline-dir"),
+                help: "The path to a directory used to store API baseline files. If unspecified, a temporary directory will be used.")
+        var overrideBaselineDir: AbsolutePath?
+
+        @Flag(help: "Regenerate the API baseline, even if an existing one is available.")
+        var regenerateBaseline: Bool = false
+
         func run(_ swiftTool: SwiftTool) throws {
             let apiDigesterPath = try swiftTool.getToolchain().getSwiftAPIDigester()
             let apiDigesterTool = SwiftAPIDigester(tool: apiDigesterPath)
@@ -348,7 +355,9 @@ extension SwiftPackageTool {
                 apiDigesterTool: apiDigesterTool,
                 diags: swiftTool.diagnostics
             )
-            let baselineDir = try baselineDumper.emitAPIBaseline(for: modulesToDiff)
+            let baselineDir = try baselineDumper.emitAPIBaseline(for: modulesToDiff,
+                                                                 at: overrideBaselineDir,
+                                                                 force: regenerateBaseline)
 
             let results = ThreadSafeArrayStore<SwiftAPIDigester.ComparisonResult>()
             let group = DispatchGroup()

Tests/CommandsTests/APIDiffTests.swift

@@ -360,4 +360,74 @@ final class APIDiffTests: XCTestCase {
         throw XCTSkip("Test unsupported on current platform")
         #endif
     }
+
+    func testBaselineDirOverride() 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: "Foo")
+            // Overwrite the existing decl.
+            try localFileSystem.writeFileContents(packageRoot.appending(component: "Foo.swift")) {
+                $0 <<< "public let foo = 42"
+            }
+
+            let baselineDir = prefix.appending(component: "Baselines")
+
+            XCTAssertThrowsError(try execute(["experimental-api-diff", "1.2.3",
+                                              "--baseline-dir", baselineDir.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 Foo"))
+                XCTAssertTrue(output.contains("💔 API breakage: func foo() has been removed"))
+                XCTAssertTrue(localFileSystem.exists(baselineDir.appending(components: "1.2.3", "Foo.json")))
+            }
+        }
+        #else
+        throw XCTSkip("Test unsupported on current platform")
+        #endif
+    }
+
+    func testRegenerateBaseline() 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: "Foo")
+            // Overwrite the existing decl.
+            try localFileSystem.writeFileContents(packageRoot.appending(component: "Foo.swift")) {
+                $0 <<< "public let foo = 42"
+            }
+
+            let baselineDir = prefix.appending(component: "Baselines")
+            let fooBaselinePath = baselineDir.appending(components: "1.2.3", "Foo.json")
+
+            try localFileSystem.createDirectory(fooBaselinePath.parentDirectory, recursive: true)
+            try localFileSystem.writeFileContents(fooBaselinePath) {
+                $0 <<< "Old Baseline"
+            }
+
+            XCTAssertThrowsError(try execute(["experimental-api-diff", "1.2.3",
+                                              "--baseline-dir", baselineDir.pathString,
+                                              "--regenerate-baseline"],
+                                             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 Foo"))
+                XCTAssertTrue(output.contains("💔 API breakage: func foo() has been removed"))
+                XCTAssertTrue(localFileSystem.exists(fooBaselinePath))
+                XCTAssertNotEqual((try! localFileSystem.readFileContents(fooBaselinePath)).description, "Old Baseline")
+            }
+        }
+        #else
+        throw XCTSkip("Test unsupported on current platform")
+        #endif
+    }
 }