Introduce path ancestry methods for AbsolutePath

This allows checking if a path is an ancestor or descendent of a given
path, and deprecates the "contains" method which is confusingly named
and may lead readers of the code to incorrectly conclude that a string
containment check is being done, rather than a semantic comparison of
the actual path components.

Author: jakepetroules

Sources/TSCBasic/Path.swift

@@ -911,10 +911,42 @@ extension AbsolutePath {
     ///
     /// This method is strictly syntactic and does not access the file system
     /// in any way.
+    @available(*, deprecated, renamed: "isDescendantOfOrEqual(to:)")
     public func contains(_ other: AbsolutePath) -> Bool {
-        return self.components.starts(with: other.components)
+        return isDescendantOfOrEqual(to: other)
     }
 
+    /// Returns true if the path is an ancestor of the given path.
+    ///
+    /// This method is strictly syntactic and does not access the file system
+    /// in any way.
+    public func isAncestor(of descendant: AbsolutePath) -> Bool {
+        return descendant.components.dropLast().starts(with: self.components)
+    }
+
+    /// Returns true if the path is an ancestor of or equal to the given path.
+    ///
+    /// This method is strictly syntactic and does not access the file system
+    /// in any way.
+    public func isAncestorOfOrEqual(to descendant: AbsolutePath) -> Bool {
+        return descendant.components.starts(with: self.components)
+    }
+
+    /// Returns true if the path is a descendant of the given path.
+    ///
+    /// This method is strictly syntactic and does not access the file system
+    /// in any way.
+    public func isDescendant(of ancestor: AbsolutePath) -> Bool {
+        return self.components.dropLast().starts(with: ancestor.components)
+    }
+
+    /// Returns true if the path is a descendant of or equal to the given path.
+    ///
+    /// This method is strictly syntactic and does not access the file system
+    /// in any way.
+    public func isDescendantOfOrEqual(to ancestor: AbsolutePath) -> Bool {
+        return self.components.starts(with: ancestor.components)
+    }
 }
 
 extension PathValidationError: CustomNSError {

Tests/TSCBasicTests/PathTests.swift

@@ -289,13 +289,26 @@ class PathTests: XCTestCase {
         XCTAssertTrue(AbsolutePath("/2.1") >= AbsolutePath("/2"));
     }
 
-    func testContains() {
-        XCTAssertTrue(AbsolutePath("/a/b/c/d/e/f").contains(AbsolutePath("/a/b/c/d")))
-        XCTAssertTrue(AbsolutePath("/a/b/c/d/e/f.swift").contains(AbsolutePath("/a/b/c")))
-        XCTAssertTrue(AbsolutePath("/").contains(AbsolutePath("/")))
-        XCTAssertTrue(AbsolutePath("/foo/bar").contains(AbsolutePath("/")))
-        XCTAssertFalse(AbsolutePath("/foo/bar").contains(AbsolutePath("/foo/bar/baz")))
-        XCTAssertFalse(AbsolutePath("/foo/bar").contains(AbsolutePath("/bar")))
+    func testAncestry() {
+        XCTAssertTrue(AbsolutePath("/a/b/c/d/e/f").isDescendantOfOrEqual(to: AbsolutePath("/a/b/c/d")))
+        XCTAssertTrue(AbsolutePath("/a/b/c/d/e/f.swift").isDescendantOfOrEqual(to: AbsolutePath("/a/b/c")))
+        XCTAssertTrue(AbsolutePath("/").isDescendantOfOrEqual(to: AbsolutePath("/")))
+        XCTAssertTrue(AbsolutePath("/foo/bar").isDescendantOfOrEqual(to: AbsolutePath("/")))
+        XCTAssertFalse(AbsolutePath("/foo/bar").isDescendantOfOrEqual(to: AbsolutePath("/foo/bar/baz")))
+        XCTAssertFalse(AbsolutePath("/foo/bar").isDescendantOfOrEqual(to: AbsolutePath("/bar")))
+
+        XCTAssertFalse(AbsolutePath("/foo/bar").isDescendant(of: AbsolutePath("/foo/bar")))
+        XCTAssertTrue(AbsolutePath("/foo/bar").isDescendant(of: AbsolutePath("/foo")))
+
+        XCTAssertTrue(AbsolutePath("/a/b/c/d").isAncestorOfOrEqual(to: AbsolutePath("/a/b/c/d/e/f")))
+        XCTAssertTrue(AbsolutePath("/a/b/c").isAncestorOfOrEqual(to: AbsolutePath("/a/b/c/d/e/f.swift")))
+        XCTAssertTrue(AbsolutePath("/").isAncestorOfOrEqual(to: AbsolutePath("/")))
+        XCTAssertTrue(AbsolutePath("/").isAncestorOfOrEqual(to: AbsolutePath("/foo/bar")))
+        XCTAssertFalse(AbsolutePath("/foo/bar/baz").isAncestorOfOrEqual(to: AbsolutePath("/foo/bar")))
+        XCTAssertFalse(AbsolutePath("/bar").isAncestorOfOrEqual(to: AbsolutePath("/foo/bar")))
+
+        XCTAssertFalse(AbsolutePath("/foo/bar").isAncestor(of: AbsolutePath("/foo/bar")))
+        XCTAssertTrue(AbsolutePath("/foo").isAncestor(of: AbsolutePath("/foo/bar")))
     }
 
     func testAbsolutePathValidation() {