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,27 @@ 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.
+    /// - Returns: an existing reference to that file, or `nil` if not found
+    func file(with path: Path) -> PBXFileReference? {
+        func absolutePath(for fileRef: PBXFileElement) -> Path? {
+            try? fileRef.fullPath(sourceRoot: ".")
+        }
+
+        guard let groupAbsPath = absolutePath(for: self) else { return nil }
+        let fileNormalizedAbsolutePath = (groupAbsPath + path).normalize()
+        return children.first {
+            guard let candidateAbsPath = absolutePath(for: $0) else { return false }
+            return candidateAbsPath.normalize() == fileNormalizedAbsolutePath
+        } as? PBXFileReference
+    }
+
     /// Creates a group with the given name and returns it.
     ///
     /// - Parameters:

Tests/XcodeProjTests/Objects/Files/PBXGroupTests.swift

@@ -199,6 +199,77 @@ final class PBXGroupTests: XCTestCase {
         XCTAssertEqual(file!.sourceTree, .developerDir)
     }
 
+    func test_whenSearchingForFilesByPath_thenNormalizedAbsolutePathsAreUsedInternallyForUniqueness() throws {
+        let project = makeEmptyPBXProj()
+        let subDirectoryName = UUID().uuidString
+
+        func prepareDirectories() throws -> (projectDir: Path, groupDir: Path, group: PBXGroup) {
+            let absolutePath = try Path.uniqueTemporary()
+            let splitSize = 2
+            let projectDir = Path(components: absolutePath.components[0..<absolutePath.components.count-splitSize])
+            let groupDir = Path(components: absolutePath.components.reversed()[0..<splitSize].reversed())
+            XCTAssertEqual(projectDir + groupDir, absolutePath)
+
+            let subDir = absolutePath + subDirectoryName
+            try subDir.mkdir()
+
+            let group = PBXGroup(children: [], sourceTree: .group, name: "group", path: ".")
+            let parent = PBXGroup(children: [group], sourceTree: .absolute, name: "parent", path: projectDir.string)
+            project.add(object: parent)
+            project.add(object: group)
+
+            return (projectDir, groupDir, group)
+        }
+
+        let (projectDir, groupDir, theGroup) = try prepareDirectories()
+
+        let fileName = UUID().uuidString
+        let file1Path = groupDir + fileName
+        let file2Path = groupDir + subDirectoryName + fileName
+
+        let fileReferenceFor = try [file1Path, file2Path]
+            .reduce([Path: PBXFileReference]()) { map, filePath in
+                let absolutePath = projectDir + filePath
+                try Data().write(to: absolutePath.url)
+                let file = try theGroup.addFile(
+                    at: absolutePath,
+                    sourceTree: .group,
+                    sourceRoot: projectDir)
+
+                return map.merging([filePath: file]) { _, new in new }
+            }
+
+        func assert(filePath: Path, hasReference: PBXFileReference?, line: UInt = #line) {
+            let actual = theGroup.file(with: filePath)
+            if let expected = hasReference {
+                XCTAssertEqual(actual, expected, file: #file, line: line)
+            } else {
+                XCTAssertNil(actual, file: #file, line: line)
+            }
+        }
+
+        assert(
+            filePath: file1Path,
+            hasReference: fileReferenceFor[file1Path]
+        )
+        assert(
+            filePath: file2Path,
+            hasReference: fileReferenceFor[file2Path]
+        )
+        assert(
+            filePath: groupDir + subDirectoryName + ".." + fileName,
+            hasReference: fileReferenceFor[file1Path]
+        )
+        assert(
+            filePath: groupDir + "foo/.." + subDirectoryName + fileName,
+            hasReference: fileReferenceFor[file2Path]
+        )
+        assert(
+            filePath: Path(UUID().uuidString),
+            hasReference: nil
+        )
+    }
+
     private func makeEmptyPBXProj() -> PBXProj {
         PBXProj(
             rootObject: nil,