Adding all existing files

Author: goergisn

.DS_Store

@@ -0,0 +1,36 @@
+// swift-tools-version: 5.9
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "public-api-diff",
+    platforms: [
+        .macOS(.v13)
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-argument-parser", from: "1.5.0")
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        .executableTarget(
+            name: "public-api-diff",
+            dependencies: [
+                .product(name: "ArgumentParser", package: "swift-argument-parser")
+            ],
+            path: "Sources"
+        ),
+        .testTarget(
+            name: "PublicApiDiffTests",
+            dependencies: ["public-api-diff"],
+            resources: [
+                // Copy Tests/ExampleTests/Resources directories as-is.
+                // Use to retain directory structure.
+                // Will be at top level in bundle.
+                .copy("Resources/dummy.abi.json"),
+                .copy("Resources/dummi-abi-flat-definition.md")
+            ]
+        )
+    ]
+)

Package.swift

@@ -1 +1,43 @@
-Readme
+# Swift Public API diff
+
+This tool allows comparing 2 versions of a swift package project and lists all changes in a human readable way.
+
+It makes use of `xcrun swift-api-digester -dump-sdk` to create a dump of the public api of your swift package and then runs it through a custom parser to process them.
+
+Alternatively you could use `xcrun swift-api-digester -diagnose-sdk` and pass the abi dumps into it.
+
+## How it works
+
+![image](https://github.com/user-attachments/assets/6f8b8927-d08b-487d-9d80-e5ee1b8d8302)
+
+### Project Builder
+
+Builds the swift package project which is required for the next step to run the `xcrun swift-api-digester -dump-sdk`
+
+### ABIGenerator
+
+Makes use of `xcrun swift-api-digester -dump-sdk` to "dump" the public interface into an abi.json file.
+
+### SDKDumpGenerator
+
+Parses the abi.json files into an `SDKDump` object
+
+### SDKDumpAnalyzer
+
+Analyzes 2 `SDKDump` objects and detects `addition`s & `removal`s.
+
+### ChangeConsolidator
+
+The `ChangeConsolidator` takes 2 independent changes (`addition` & `removal`) and tries to match them based on the name, declKind and parent.
+
+| Match |
+| --- |
+| ![image](https://github.com/user-attachments/assets/f057c160-f85d-45af-b08f-203b89e43b41) |
+
+| No Match | Potentially false positive |
+| --- | --- |
+| ![image](https://github.com/user-attachments/assets/5ae3b624-b32a-41cc-9026-8ba0117cec57) | ![image](https://github.com/user-attachments/assets/a7e60605-fc1c-49ef-a203-d6a5466a6fda) |
+
+### OutputGenerator
+
+Receives a list of `Change`s and processes them into a human readable format.

README.md

@@ -0,0 +1,77 @@
+//
+// Copyright (c) 2024 Adyen N.V.
+//
+// This file is open source and available under the MIT license. See the LICENSE file for more info.
+//
+
+import Foundation
+
+enum FileHandlerError: LocalizedError, Equatable {
+    /// Could not encode the output string into data
+    case couldNotEncodeOutput
+    /// Could not persist output at the specified `outputFilePath`
+    case couldNotCreateFile(outputFilePath: String)
+    /// Could not load file at the specified `filePath`
+    case couldNotLoadFile(filePath: String)
+    /// File/Directory does not exist at `path`
+    case pathDoesNotExist(path: String)
+    
+    var errorDescription: String? {
+        switch self {
+        case .couldNotEncodeOutput:
+            "Could not encode the output string into data"
+        case let .couldNotCreateFile(outputFilePath):
+            "Could not persist output at `\(outputFilePath)`"
+        case let .couldNotLoadFile(filePath):
+            "Could not load file from `\(filePath)`"
+        case let .pathDoesNotExist(path):
+            "File/Directory does not exist at `\(path)`"
+        }
+    }
+}
+
+// MARK: - Convenience
+
+extension FileHandling {
+    
+    /// Creates a directory at the specified path and deletes any old directory if existing
+    ///
+    /// - Parameters:
+    ///   - cleanDirectoryPath: The Path where to create the clean directory
+    func createCleanDirectory(
+        atPath cleanDirectoryPath: String
+    ) throws {
+        // Remove existing directory if it exists
+        try? removeItem(atPath: cleanDirectoryPath)
+        try createDirectory(atPath: cleanDirectoryPath)
+    }
+    
+    /// Persists an output string to a file
+    ///
+    /// - Parameters:
+    ///   - output: The output string to persist
+    ///   - outputFilePath: The file path to persist the output to
+    func write(_ output: String, to outputFilePath: String) throws {
+        
+        guard let data = output.data(using: String.Encoding.utf8) else {
+            throw FileHandlerError.couldNotEncodeOutput
+        }
+        
+        // Remove existing directory if it exists
+        try? removeItem(atPath: outputFilePath)
+        if !createFile(atPath: outputFilePath, contents: data) {
+            throw FileHandlerError.couldNotCreateFile(outputFilePath: outputFilePath)
+        }
+    }
+    
+    /// Get the string contents from a file at a specified path
+    ///
+    /// - Parameters:
+    ///   - filePath: The path to load the string content from
+    ///
+    /// - Returns: The string content of the file
+    func loadString(from filePath: String) throws -> String {
+        let data = try loadData(from: filePath)
+        return String(decoding: data, as: UTF8.self)
+    }
+}

Sources/.DS_Store

@@ -0,0 +1,24 @@
+//
+// Copyright (c) 2024 Adyen N.V.
+//
+// This file is open source and available under the MIT license. See the LICENSE file for more info.
+//
+
+import Foundation
+
+protocol FileHandling {
+    
+    var currentDirectoryPath: String { get }
+    
+    func loadData(from path: String) throws -> Data
+    
+    func removeItem(atPath path: String) throws
+    
+    func contentsOfDirectory(atPath path: String) throws -> [String]
+    
+    func createDirectory(atPath path: String) throws
+    
+    func createFile(atPath path: String, contents data: Data) -> Bool
+    
+    func fileExists(atPath path: String) -> Bool
+}

Sources/Helpers/.DS_Store

@@ -0,0 +1,28 @@
+//
+// Copyright (c) 2024 Adyen N.V.
+//
+// This file is open source and available under the MIT license. See the LICENSE file for more info.
+//
+
+import Foundation
+
+extension FileManager: FileHandling {
+    
+    /// Creates a directory at the specified path
+    func createDirectory(atPath path: String) throws {
+        try createDirectory(atPath: path, withIntermediateDirectories: true)
+    }
+    
+    /// Creates a file at the specified path with the provided content
+    func createFile(atPath path: String, contents data: Data) -> Bool {
+        createFile(atPath: path, contents: data, attributes: nil)
+    }
+    
+    func loadData(from filePath: String) throws -> Data {
+        guard let data = self.contents(atPath: filePath) else {
+            throw FileHandlerError.couldNotLoadFile(filePath: filePath)
+        }
+        
+        return data
+    }
+}

Sources/Helpers/FileHandling/FileHandling+Convenience.swift

@@ -0,0 +1,53 @@
+//
+// Copyright (c) 2024 Adyen N.V.
+//
+// This file is open source and available under the MIT license. See the LICENSE file for more info.
+//
+
+import Foundation
+
+enum GitError: LocalizedError, Equatable {
+    case couldNotClone(branchOrTag: String, repository: String)
+    
+    var errorDescription: String? {
+        switch self {
+        case let .couldNotClone(branchOrTag, repository):
+            "Could not clone \(repository) @ \(branchOrTag) - Please check the provided information"
+        }
+    }
+}
+
+struct Git {
+    
+    private let shell: ShellHandling
+    private let fileHandler: FileHandling
+    private let logger: Logging?
+    
+    init(
+        shell: ShellHandling,
+        fileHandler: FileHandling,
+        logger: Logging?
+    ) {
+        self.shell = shell
+        self.fileHandler = fileHandler
+        self.logger = logger
+    }
+    
+    /// Clones a repository at a specific branch or tag into the current directory
+    ///
+    /// - Parameters:
+    ///   - repository: The repository to clone
+    ///   - branchOrTag: The branch or tag to clone
+    ///   - targetDirectoryPath: The directory to clone into
+    ///
+    /// - Returns: The local directory path where to find the cloned repository
+    func clone(_ repository: String, at branchOrTag: String, targetDirectoryPath: String) throws {
+        logger?.log("🐱 Cloning \(repository) @ \(branchOrTag) into \(targetDirectoryPath)", from: String(describing: Self.self))
+        let command = "git clone -b \(branchOrTag) \(repository) \(targetDirectoryPath)"
+        shell.execute(command)
+        
+        guard fileHandler.fileExists(atPath: targetDirectoryPath) else {
+            throw GitError.couldNotClone(branchOrTag: branchOrTag, repository: repository)
+        }
+    }
+}

Sources/Helpers/FileHandling/FileHandling.swift

@@ -0,0 +1,68 @@
+//
+// Copyright (c) 2024 Adyen N.V.
+//
+// This file is open source and available under the MIT license. See the LICENSE file for more info.
+//
+
+import Foundation
+
+/// A change indicating an `addition`, `removal` or genuine `change` of an element
+struct Change: Equatable {
+    enum ChangeType: Equatable {
+        case addition(description: String)
+        case removal(description: String)
+        case change(oldDescription: String, newDescription: String)
+    }
+    
+    var changeType: ChangeType
+    var parentName: String
+
+    var listOfChanges: [String] = []
+}
+
+extension Change.ChangeType {
+
+    var isAddition: Bool {
+        switch self {
+        case .addition:
+            return true
+        case .removal:
+            return false
+        case .change:
+            return false
+        }
+    }
+
+    var isRemoval: Bool {
+        switch self {
+        case .addition:
+            return false
+        case .removal:
+            return true
+        case .change:
+            return false
+        }
+    }
+    
+    var isChange: Bool {
+        switch self {
+        case .addition:
+            return false
+        case .removal:
+            return false
+        case .change:
+            return true
+        }
+    }
+}
+
+extension [String: [Change]] {
+    
+    var totalChangeCount: Int {
+        var totalChangeCount = 0
+        keys.forEach { targetName in
+            totalChangeCount += self[targetName]?.count ?? 0
+        }
+        return totalChangeCount
+    }
+}