Adding more documentation

goergisn · goergisn · commit f7ba528eaa97 · 2024-10-09T14:23:14.000+02:00
diff --git a/README.md b/README.md
@@ -41,4 +41,7 @@ The `ChangeConsolidator` takes 2 independent changes (`addition` & `removal`) an
 
 ### OutputGenerator
 
-Receives a list of `Change`s and processes them into a human readable format.
+Receives a dictionary of `[{SCOPE_NAME}: [Change]]` and processes them into a human readable format.
+
+## Inspiration
+- SwiftInterfaceParser: https://github.com/sdidla/Hatch/blob/main/Sources/Hatch/SymbolParser.swift
diff --git a/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Actor.swift b/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Actor.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-class SwiftInterfaceActor: SwiftInterfaceElement, SwiftInterfaceExtendableElement {
+class SwiftInterfaceActor: SwiftInterfaceExtendableElement {
     
     var pathComponentName: String { name }
     
diff --git a/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Class.swift b/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Class.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-class SwiftInterfaceClass: SwiftInterfaceElement, SwiftInterfaceExtendableElement {
+class SwiftInterfaceClass: SwiftInterfaceExtendableElement {
     
     /// e.g. @discardableResult, @MainActor, @objc, @_spi(...), ...
     let attributes: [String]
diff --git a/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Enum.swift b/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Enum.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-class SwiftInterfaceEnum: SwiftInterfaceElement, SwiftInterfaceExtendableElement {
+class SwiftInterfaceEnum: SwiftInterfaceExtendableElement {
     
     /// e.g. @discardableResult, @MainActor, @objc, @_spi(...), ...
     let attributes: [String]
diff --git a/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Protocol.swift b/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Protocol.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-class SwiftInterfaceProtocol: SwiftInterfaceElement, SwiftInterfaceExtendableElement {
+class SwiftInterfaceProtocol: SwiftInterfaceExtendableElement {
     
     /// e.g. @discardableResult, @MainActor, @objc, @_spi(...), ...
     let attributes: [String]
diff --git a/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Struct.swift b/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement+Declaration/SwiftInterfaceElement+Struct.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-class SwiftInterfaceStruct: SwiftInterfaceElement, SwiftInterfaceExtendableElement {
+class SwiftInterfaceStruct: SwiftInterfaceExtendableElement {
     
     /// e.g. @discardableResult, @MainActor, @objc, @_spi(...), ...
     let attributes: [String]
diff --git a/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement.swift b/Sources/Helpers/Models/SwiftInterface/SwiftInterfaceElement.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-protocol SwiftInterfaceExtendableElement: AnyObject {
+protocol SwiftInterfaceExtendableElement: SwiftInterfaceElement {
     
     /// Name of the type
     ///
@@ -51,6 +51,12 @@ extension SwiftInterfaceElement {
         }
     }
     
+    /// The path to the parent based on the `pathComponentName`
+    ///
+    /// The path does not including the own `pathComponentName`
+    ///
+    /// - Important: `SwiftInterfaceExtension`'s parentPath is always the `extendedType` 
+    /// of the element to group them under the extended element
     var parentPath: String {
         if let extensionElement = self as? SwiftInterfaceExtension {
             // We want to group all extensions under the type that they are extending
@@ -105,6 +111,7 @@ extension SwiftInterfaceElement {
 
 extension SwiftInterfaceElement {
     
+    /// Produces the complete recursive description of the element
     func recursiveDescription(indentation: Int = 0) -> String {
         let spacer = "  "
         var recursiveDescription = "\(String(repeating: spacer, count: indentation))\(description)"
diff --git a/Sources/Helpers/SwiftInterfaceType.swift b/Sources/Helpers/SwiftInterfaceType.swift
@@ -1,6 +1,7 @@
 import Foundation
 import ArgumentParser
 
+/// The type of the .swiftinterface to parse/generate
 enum SwiftInterfaceType {
     case `private`
     case `public`
diff --git a/Sources/Helpers/XcodeTools.swift b/Sources/Helpers/XcodeTools.swift
@@ -16,7 +16,6 @@ struct XcodeToolsError: LocalizedError, CustomDebugStringConvertible {
 struct XcodeTools {
     
     internal enum Constants {
-        static let deviceTarget: String = "x86_64-apple-ios17.4-simulator" // TODO: Match the iOS version to the sdk
         static let derivedDataPath: String = ".build"
         static let simulatorSdkCommand = "xcrun --sdk iphonesimulator --show-sdk-path"
     }
@@ -82,8 +81,4 @@ struct XcodeTools {
             return derivedDataPath
         }.value
     }
-    
-    private var iOSTarget: String {
-        "-sdk `\(Constants.simulatorSdkCommand)` -target \(Constants.deviceTarget)"
-    }
 }
diff --git a/Sources/Pipeline/Modules/SwiftInterfaceAnalyzer/SwiftInterfaceAnalyzer.swift b/Sources/Pipeline/Modules/SwiftInterfaceAnalyzer/SwiftInterfaceAnalyzer.swift
@@ -8,8 +8,6 @@ import Foundation
 
 struct SwiftInterfaceAnalyzer: SwiftInterfaceAnalyzing {
     
-    // TODO: Surface changes that happened to a subclass/protocol/extension
-    
     let changeConsolidator: SwiftInterfaceChangeConsolidating
     
     init(
@@ -23,6 +21,9 @@ struct SwiftInterfaceAnalyzer: SwiftInterfaceAnalyzing {
         new: some SwiftInterfaceElement
     ) -> [Change] {
         
+        // Very naive diff from both sides
+        // There is room for improvement here but it's "performant enough" for now
+        
         let individualChanges = Self.recursiveCompare(
             element: old,
             to: new,
diff --git a/Sources/Pipeline/Modules/SwiftInterfaceAnalyzer/SwiftInterfaceChangeConsolidator.swift b/Sources/Pipeline/Modules/SwiftInterfaceAnalyzer/SwiftInterfaceChangeConsolidator.swift
@@ -50,9 +50,10 @@ struct SwiftInterfaceChangeConsolidator: SwiftInterfaceChangeConsolidating {
             let newDescription = change.oldFirst ? match.element.description : change.element.description
             let listOfChanges = listOfChanges(between: change, and: match)
             
-            // TODO: We should not even end up here if an element does not have any changes
-            // This is just a quick fix for now but we should explore why we sometimes get here
-            if listOfChanges.isEmpty { break }
+            if listOfChanges.isEmpty {
+                assertionFailure("We should not end up here - investigate how this happened")
+                break
+            }
             
             consolidatedChanges.append(
                 .init(
diff --git a/Sources/Pipeline/Modules/SwiftInterfaceFileLocator.swift b/Sources/Pipeline/Modules/SwiftInterfaceFileLocator.swift
@@ -1,5 +1,6 @@
 import Foundation
 
+/// A helper to locate `.swiftinterface` files
 struct SwiftInterfaceFileLocator {
     
     let fileHandler: any FileHandling
@@ -16,6 +17,14 @@ struct SwiftInterfaceFileLocator {
         self.logger = logger
     }
     
+    
+    /// Tries to locate a `.swiftinterface` files in the derivedData folder for a specific scheme
+    /// - Parameters:
+    ///   - scheme: The scheme to find the `.swiftinterface` file for
+    ///   - derivedDataPath: The path to the derived data directory (e.g. .../.build)
+    ///   - type: The swift interface type (.public, .private) to look for
+    /// - Returns: The file url to the found `.swiftinterface`
+    /// - Throws: An error if no `.swiftinterface` file can be found for the given scheme + derived data path
     func locate(for scheme: String, derivedDataPath: String, type: SwiftInterfaceType) throws -> URL {
         let schemeSwiftModuleName = "\(scheme).swiftmodule"
         
@@ -24,7 +33,7 @@ struct SwiftInterfaceFileLocator {
             .map { URL(filePath: $0) }
 
         guard let swiftModulePath = swiftModulePathsForScheme.first?.path() else {
-            throw FileHandlerError.pathDoesNotExist(path: "find . -type d -name '\(schemeSwiftModuleName)'") // TODO: Better error
+            throw FileHandlerError.pathDoesNotExist(path: "find . -type d -name '\(schemeSwiftModuleName)'")
         }
         
         let completeSwiftModulePath = derivedDataPath + "/" + swiftModulePath
@@ -42,9 +51,9 @@ struct SwiftInterfaceFileLocator {
         guard let swiftInterfacePath = swiftInterfacePaths.first else {
             switch type {
             case .private:
-                throw FileHandlerError.pathDoesNotExist(path: "'\(scheme).private.swiftinterface'") // TODO: Better error
+                throw FileHandlerError.pathDoesNotExist(path: "'\(completeSwiftModulePath)/\(scheme).private.swiftinterface'")
             case .public:
-                throw FileHandlerError.pathDoesNotExist(path: "'\(scheme).swiftinterface'") // TODO: Better error
+                throw FileHandlerError.pathDoesNotExist(path: "'\(completeSwiftModulePath)/\(scheme).swiftinterface'")
             }
         }
         
diff --git a/Sources/Pipeline/Modules/SwiftInterfaceParser/SwiftInterfaceParser+Root.swift b/Sources/Pipeline/Modules/SwiftInterfaceParser/SwiftInterfaceParser+Root.swift
@@ -2,6 +2,7 @@ import Foundation
 
 extension SwiftInterfaceParser {
     
+    /// The root element returned as the result of parsing the interface
     class Root: SwiftInterfaceElement {
         
         var parent: (any SwiftInterfaceElement)? = nil
@@ -10,6 +11,7 @@ extension SwiftInterfaceParser {
         
         var consolidatableName: String { "" }
         
+        /// Produces the complete recursive description of the interface
         var description: String {
             var description = ""
             children.forEach { child in
@@ -35,61 +37,111 @@ extension SwiftInterfaceParser {
         func differences<T: SwiftInterfaceElement>(to otherElement: T) -> [String] {
             return []
         }
+    }
+}
+
+// MARK: - Convenience methods
+
+private extension SwiftInterfaceParser.Root {
+    
+    /// Attempting to merge extensions into their extended type to allow for better diffing
+    ///
+    /// Independent extensions (without a where clause) are very hard to diff as the only information we have
+    /// is the ``SwiftInterfaceExtension.extendedType`` and there might be a lot of changes inside of the extensions between versions
+    ///
+    /// Example:
+    /// ```
+    /// struct S {
+    ///    var a: String
+    /// }
+    ///
+    /// extension S: SomeProtocol {
+    ///     var b: Int { 1 }
+    /// }
+    /// ```
+    ///
+    /// ... Is turned into ...
+    /// ```
+    /// struct S: SomeProtocol {
+    ///    var a: String
+    ///    var b: Int { 1 }
+    /// }
+    /// ```
+    static func mergeExtensions(for elements: [any SwiftInterfaceElement], moduleName: String) -> [any SwiftInterfaceElement] {
         
-        /// Attempting to merge extensions into their extended type to allow for better diffing
-        /// Independent extensions (without a where clause) are very hard to diff as the only information we have
-        /// is the extended type and there might be a lot of changes inside of the extensions between versions
-        static func mergeExtensions(for elements: [any SwiftInterfaceElement], moduleName: String) -> [any SwiftInterfaceElement] {
-            let extensions = elements.compactMap { $0 as? (SwiftInterfaceExtension & SwiftInterfaceElement) }
-            let extendableElements = elements.compactMap { $0 as? (SwiftInterfaceExtendableElement & SwiftInterfaceElement) }
-            let nonExtensions = elements.filter { !($0 is SwiftInterfaceExtension) }
-            
-            var adjustedElements: [any SwiftInterfaceElement] = nonExtensions
+        let extensions = elements.compactMap { $0 as? SwiftInterfaceExtension }
+        let extendableElements = elements.compactMap { $0 as? SwiftInterfaceExtendableElement }
+        let nonExtensions = elements.filter { !($0 is SwiftInterfaceExtension) }
+        
+        var adjustedElements: [any SwiftInterfaceElement] = nonExtensions
+        
+        extensions.forEach { extensionElement in
             
-            extensions.forEach { extensionElement in
-                
-                // We want to merge all extensions that don't have a where clause into the extended type
-                guard extensionElement.genericWhereClauseDescription == nil else {
-                    adjustedElements.append(extensionElement)
-                    return
-                }
-                
-                if merge(extensionElement: extensionElement, with: extendableElements, prefix: moduleName) {
-                    return // We found the matching extended element
-                }
-                
-                // We could not find the extended type so we add the extension to the list
+            // We want to merge all extensions that don't have a where clause into the extended type
+            guard extensionElement.genericWhereClauseDescription == nil else {
                 adjustedElements.append(extensionElement)
+                return
             }
             
-            return adjustedElements
-        }
-        
-        /// Attempting to recursively merge an extension element with potential matches of extendable elements
-        /// The prefix provides the parent path as the types don't include it but the `extension.extendedType` does
-        static func merge(
-            extensionElement: any (SwiftInterfaceExtension & SwiftInterfaceElement),
-            with extendableElements: [any (SwiftInterfaceExtendableElement & SwiftInterfaceElement)],
-            prefix: String
-        ) -> Bool {
-            
-            if let extendedElement = extendableElements.first(where: { extensionElement.extendedType.hasPrefix("\(prefix).\($0.typeName)") }) {
-                
-                let extendedElementPrefix = "\(prefix).\(extendedElement.typeName)"
-                
-                // We found the extended type
-                if extendedElementPrefix == extensionElement.extendedType {
-                    extendedElement.inheritance = (extendedElement.inheritance ?? []) + (extensionElement.inheritance ?? [])
-                    extendedElement.children += extensionElement.children
-                    return true
-                }
-                
-                // We're looking for the extended type inside of the children
-                let extendableChildren = extendedElement.children.compactMap { $0 as? (SwiftInterfaceExtendableElement & SwiftInterfaceElement) }
-                return merge(extensionElement: extensionElement, with: extendableChildren, prefix: extendedElementPrefix)
+            if merge(extensionElement: extensionElement, with: extendableElements, prefix: moduleName) {
+                return // We found the matching extended element
             }
             
+            // We could not find the extended type so we add the extension to the list
+            adjustedElements.append(extensionElement)
+        }
+        
+        return adjustedElements
+    }
+    
+    /// Attempting to recursively merge an extension element with potential matches of extendable elements
+    /// The prefix provides the parent path as the types don't include it but the `extension.extendedType` does
+    ///
+    /// Example:
+    /// ```
+    /// struct S {
+    ///    enum E {
+    ///       class C {}
+    ///    }
+    /// }
+    ///
+    /// extension S.E.C: SomeProtocol {
+    ///     var b: Int { 1 }
+    /// }
+    /// ```
+    ///
+    /// ... Is turned into ...
+    /// ```
+    /// struct S {
+    ///    enum E {
+    ///       class C: SomeProtocol {
+    ///          var b: Int { 1 }
+    ///       }
+    ///    }
+    /// }
+    /// ```
+    static func merge(
+        extensionElement: SwiftInterfaceExtension,
+        with extendableElements: [any SwiftInterfaceExtendableElement],
+        prefix: String
+    ) -> Bool {
+        
+        // Finding the first extendable element that has the same prefix as the extension
+        guard let extendedElement = extendableElements.first(where: { extensionElement.extendedType.hasPrefix("\(prefix).\($0.typeName)") }) else {
             return false
         }
+            
+        let extendedElementPrefix = "\(prefix).\(extendedElement.typeName)"
+        
+        // We found the extended type
+        if extendedElementPrefix == extensionElement.extendedType {
+            extendedElement.inheritance = (extendedElement.inheritance ?? []) + (extensionElement.inheritance ?? [])
+            extendedElement.children += extensionElement.children
+            return true
+        }
+        
+        // We're looking for the extended type inside of the children
+        let extendableChildren = extendedElement.children.compactMap { $0 as? SwiftInterfaceExtendableElement }
+        return merge(extensionElement: extensionElement, with: extendableChildren, prefix: extendedElementPrefix)
     }
 }
diff --git a/Sources/Pipeline/Modules/SwiftInterfaceParser/SwiftInterfaceParser.swift b/Sources/Pipeline/Modules/SwiftInterfaceParser/SwiftInterfaceParser.swift
@@ -3,7 +3,6 @@ import SwiftSyntax
 import SwiftParser
 
 /**
- Inspired by: https://github.com/sdidla/Hatch/blob/main/Sources/Hatch/SymbolParser.swift
  Documentation about DeclSyntax:
  - https://swiftpackageindex.com/swiftlang/swift-syntax/600.0.1/documentation/swiftsyntax/declsyntax
  */
@@ -177,9 +176,8 @@ class SwiftInterfaceParser: SyntaxVisitor, SwiftInterfaceParsing {
     }
 }
 
-// MARK: - Models
+// MARK: - Scope
 
-/// Inspired by: https://github.com/sdidla/Hatch/blob/main/Sources/Hatch/SymbolParser.swift
 fileprivate indirect enum Scope {
 
     /// The root scope of a file

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,6 @@ struct XcodeToolsError: LocalizedError, CustomDebugStringConvertible {`
`16`	`16`	`struct XcodeTools {`
`17`	`17`
`18`	`18`	`internal enum Constants {`
`19`		`- static let deviceTarget: String = "x86_64-apple-ios17.4-simulator" // TODO: Match the iOS version to the sdk`
`20`	`19`	`static let derivedDataPath: String = ".build"`
`21`	`20`	`static let simulatorSdkCommand = "xcrun --sdk iphonesimulator --show-sdk-path"`
`22`	`21`	`}`
`@@ -82,8 +81,4 @@ struct XcodeTools {`
`82`	`81`	`return derivedDataPath`
`83`	`82`	`}.value`
`84`	`83`	`}`
`85`		`-`
`86`		`- private var iOSTarget: String {`
`87`		- "-sdk `\(Constants.simulatorSdkCommand)` -target \(Constants.deviceTarget)"
`88`		`- }`
`89`	`84`	`}`