Add API to search for files in a group with path. Handles non-unique filenames in groups

Sources/XcodeProj/Objects/Files/PBXGroup.swift

@@ -117,6 +117,8 @@ public extension PBXGroup {
     }
 
     /// Returns the file in the group with the given name.
+    /// - Note: Performs a linear search based on the file's name _only_. To search for a specific file
+    /// based on file-system location, use the `file(with path:)` method.
     ///
     /// - Parameter name: file name.
     /// - Returns: file with the given name contained in the given parent group.
@@ -126,6 +128,19 @@ public extension PBXGroup {
             .first(where: { $0.name == name })
     }
 
+    /// Returns the file in the group with the given path, based on locations on-disk.
+    /// - Note: Paths function as-in Xcode; with respect to the group's `PBXSourceTree`.
+    /// Internally, identity is calculated based on normalized absolute paths for all files involved; i.e. actual
+    /// location in the file system.
+    ///
+    /// - Parameters:
+    ///   - path: a file path to search for.
+    ///   - sourceRoot: path to project's source root.
+    /// - Returns: an existing reference to that file, or `nil` if not found
+    func file(with path: Path, sourceRoot: Path) -> PBXFileReference? {
+        try? existingFileReference(with: path, sourceRoot: sourceRoot)?.value
+    }
+
     /// Creates a group with the given name and returns it.
     ///
     /// - Parameters:
@@ -187,17 +202,11 @@ public extension PBXGroup {
         }
         let groupPath = try fullPath(sourceRoot: sourceRoot)
 
-        if override, let existingFileReference = try projectObjects.fileReferences.first(where: {
-            // Optimization: compare lastComponent before fullPath compare
-            guard let fileRefPath = $0.value.path else {
-                return try filePath == $0.value.fullPath(sourceRoot: sourceRoot)
-            }
-            let fileRefLastPathComponent = fileRefPath.split(separator: "/").last!
-            if filePath.lastComponent == fileRefLastPathComponent {
-                return try filePath == $0.value.fullPath(sourceRoot: sourceRoot)
-            }
-            return false
-        }) {
+        if override, let existingFileReference = try self.existingFileReference(
+            from: projectObjects,
+            with: filePath,
+            sourceRoot: sourceRoot
+        ) {
             if !childrenReferences.contains(existingFileReference.key) {
                 existingFileReference.value.path = groupPath.flatMap { filePath.relative(to: $0) }?.string
                 childrenReferences.append(existingFileReference.key)
@@ -233,3 +242,24 @@ public extension PBXGroup {
         return fileReference
     }
 }
+
+private extension PBXGroup {
+
+    func existingFileReference(
+        from objects: PBXObjects? = nil,
+        with filePath: Path,
+        sourceRoot: Path
+    ) throws -> (key: PBXObjectReference, value: PBXFileReference)? {
+        try (objects ?? self.objects()).fileReferences.first(where: {
+            // Optimization: compare lastComponent before fullPath compare
+            guard let fileRefPath = $0.value.path else {
+                return try filePath == $0.value.fullPath(sourceRoot: sourceRoot)
+            }
+            let fileRefLastPathComponent = fileRefPath.split(separator: "/").last!
+            if filePath.lastComponent == fileRefLastPathComponent {
+                return try filePath == $0.value.fullPath(sourceRoot: sourceRoot)
+            }
+            return false
+        })
+    }
+}