[Request]: TECH DEBT: Add FilePath extensions under `ContainerizationOS`

[saehejkang]

Feature or enhancement request details

We are actively migrating to FilePath where appropriate, and similar path-related extensions are being added across multiple modules. We should create shared, reusable FilePath extensions in ContainerizationOS so this logic is not being duplicated. This issue will serve as a place to gather and prioritize the FilePath extensions we expect to need in the near term.

Code of Conduct

• I agree to follow this project's Code of Conduct

[jglogan]

@dcantah and I were discussing the public extensions on FileDescriptor that already exist. It might be safer (in terms of avoiding potential namespace conflicts with other libraries, and as Swift evolves) to define a FilePathOps utility type, like Java with its Paths and Files that work on Path objects.

Impetus for this was the non-DRY path resolution in apple/container#1570 and apple/container#1574.

As for the operations themselves, there's a fair few in https://github.com/apple/container/blob/main/Sources/ContainerBuild/BuildFSSync.swift.

Also a path resolution extension in apple/container#1558.

[jglogan]

See #746 for the change from FileDescriptor extensions to a static utility type.

[saehejkang]

What is the scope of size on this issue? I assume there are lots of updates to be made on the ContainerizationOS side of things.

[jglogan]

The scope could be very small, actually. Just create a FilePathOps next to FileDescriptorOps and follow that pattern. Extract the code you wrote for the image save and load into an FilePathOps.absolutePath(_ path: FilePath) -> FilePath, write some unit tests, and then this one is done.

We can create follow-on issues for additional extractions. It's best to keep the PRs small and focused and then they're easy to merge and move on to the next.

[jglogan]

For reference, these were the FilePath extensions that I had built out in my local branch for converting ContainerBuild to use FilePath.

//===----------------------------------------------------------------------===//
// Copyright © 2026 Apple Inc. and the container project authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//   https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//===----------------------------------------------------------------------===//

import Foundation
import SystemPackage

/// Local extensions to FilePath for builder operations.
extension FilePath {
    /// Returns an absolute version of this path by lexically prepending the
    /// current working directory when the path is relative.
    ///
    /// This is a purely lexical operation: no symlinks are resolved and no
    /// filesystem access is performed. It is the `FilePath` equivalent of
    /// `URL.absoluteURL`. If the path is already absolute, returns `self`.
    var absolutePath: FilePath {
        if isAbsolute { return self }
        return FilePath(FileManager.default.currentDirectoryPath)
            .appending(components)
            .lexicallyNormalized()
    }

    /// Returns the relative path that navigates from `self` to `other`.
    ///
    /// Both paths are lexically normalized before comparison. Where the two
    /// paths diverge from their longest common prefix, `..` components are
    /// inserted to climb back up to the common ancestor, followed by the
    /// remaining suffix of `other`.
    ///
    /// This is the `FilePath` equivalent of Java's `Path.relativize(Path)`.
    ///
    /// - Parameter other: The target path.
    /// - Returns: A relative path from `self` to `other`, or `"."` when both
    ///   paths resolve to the same location.
    func relativize(_ other: FilePath) -> FilePath {
        let selfComps = Array(lexicallyNormalized().components)
        let otherComps = Array(other.lexicallyNormalized().components)
        var common = 0
        for (a, b) in zip(selfComps, otherComps) {
            guard a == b else { break }
            common += 1
        }
        var result = FilePath("")
        for _ in 0..<(selfComps.count - common) {
            result.append("..")
        }
        for comp in otherComps.dropFirst(common) {
            result.append(comp)
        }
        return result.isEmpty ? FilePath(".") : result
    }

    /// Returns `true` if `other` is this path or is nested anywhere inside it.
    ///
    /// Implemented in terms of ``relativize(_:)``: `other` is a child of
    /// `self` when the relative path from `self` to `other` does not start
    /// with a `..` component — meaning navigation never needs to go *above*
    /// `self` to reach `other`.
    ///
    /// The check is purely lexical; no filesystem access is performed and
    /// symlinks are not resolved.
    ///
    /// - Parameter other: The path to test.
    func parentOf(_ other: FilePath) -> Bool {
        relativize(other).components.first?.string != ".."
    }

    /// Returns a new `FilePath` with all symlinks resolved and `.`/`..`
    /// components normalized, by calling `realpath(3)`.
    ///
    /// Unlike ``lexicallyNormalized()``, this method accesses the file system.
    /// It throws ``Errno/noSuchFileOrDirectory`` if any component of the path
    /// does not exist.
    ///
    /// The returned path is always absolute. If the receiver is a relative path,
    /// it is resolved against the process's current working directory.
    public func resolvingSymlinks() throws -> FilePath {
        try withPlatformString { cPath in
            guard let resolved = Darwin.realpath(cPath, nil) else {
                throw Errno(rawValue: Darwin.errno)
            }
            defer { free(resolved) }
            return FilePath(platformString: resolved)
        }
    }

    /// Returns `true` if this path refers to a directory on the filesystem.
    ///
    /// Unlike `URL.hasDirectoryPath`, this property performs a filesystem lookup
    /// rather than inspecting the path string for a trailing slash. Returns
    /// `false` if the path does not exist or is not a directory.
    var isDirectory: Bool {
        var isDir: ObjCBool = false
        return FileManager.default.fileExists(atPath: string, isDirectory: &isDir) && isDir.boolValue
    }

    /// Returns `true` if this path refers to a symbolic link.
    ///
    /// Uses `lstat(2)` to inspect the link itself rather than its target.
    /// Returns `false` if the path does not exist.
    var isSymlink: Bool {
        var st = stat()
        guard lstat(string, &st) == 0 else { return false }
        return (st.st_mode & S_IFMT) == S_IFLNK
    }

    // MARK: - File attributes

    /// Returns the size of the file in bytes.
    ///
    /// Throws if the path does not exist or the attribute is unavailable.
    func fileSize() throws -> UInt64 {
        let attrs = try FileManager.default.attributesOfItem(atPath: string)
        guard let size = attrs[.size] as? UInt64 else {
            throw Errno.noSuchFileOrDirectory
        }
        return size
    }

    /// Returns the last modification date of the file.
    ///
    /// Throws if the path does not exist or the attribute is unavailable.
    func modificationDate() throws -> Date {
        let attrs = try FileManager.default.attributesOfItem(atPath: string)
        guard let date = attrs[.modificationDate] as? Date else {
            throw Errno.noSuchFileOrDirectory
        }
        return date
    }

    /// Returns the POSIX permission bits of the file as a raw mode value.
    ///
    /// Throws if the path does not exist or the attribute is unavailable.
    func permissions() throws -> UInt32 {
        let attrs = try FileManager.default.attributesOfItem(atPath: string)
        guard let mode = attrs[.posixPermissions] as? NSNumber else {
            throw Errno.noSuchFileOrDirectory
        }
        return mode.uint32Value
    }

    /// Returns the numeric user ID of the file's owner.
    ///
    /// Throws if the path does not exist or the attribute is unavailable.
    func ownerUserID() throws -> UInt32 {
        let attrs = try FileManager.default.attributesOfItem(atPath: string)
        guard let uid = (attrs[.ownerAccountID] as? NSNumber)?.uint32Value else {
            throw Errno.noSuchFileOrDirectory
        }
        return uid
    }

    /// Returns the numeric group ID of the file's owning group.
    ///
    /// Throws if the path does not exist or the attribute is unavailable.
    func ownerGroupID() throws -> UInt32 {
        let attrs = try FileManager.default.attributesOfItem(atPath: string)
        guard let gid = (attrs[.groupOwnerAccountID] as? NSNumber)?.uint32Value else {
            throw Errno.noSuchFileOrDirectory
        }
        return gid
    }

    /// Creates a new subdirectory inside the system temporary directory and
    /// returns its path.
    ///
    /// Using ``FilePath/Component`` (rather than a plain `String`) as the name
    /// parameter ensures the caller cannot accidentally supply a multi-segment
    /// or path-separator–containing string, keeping the result a single level
    /// below the system temp root.
    ///
    /// - Parameter component: The name of the new temporary directory.
    /// - Returns: The path of the newly created directory.
    /// - Throws: Any `FileManager` error encountered while creating the directory.
    static func makeTemporaryDirectory(named component: Component) throws -> FilePath {
        let path = FilePath(NSTemporaryDirectory()).appending(component)
        try FileManager.default.createDirectory(
            atPath: path.string,
            withIntermediateDirectories: true
        )
        return path
    }

    // MARK: - Glob

    /// Expands a glob pattern rooted at `self` and returns the matching paths.
    ///
    /// Patterns follow Docker/BuildKit FSSync semantics: a leading `./` is
    /// stripped, a bare `.` expands to `*`, and consecutive `**` sequences are
    /// collapsed. Within a pattern, `**` matches zero or more path segments,
    /// `*` matches any sequence of non-separator characters, and `?` matches a
    /// single non-separator character.
    ///
    /// - Parameter pattern: A glob pattern relative to `self`.
    /// - Returns: All matching absolute paths.
    func glob(_ pattern: String) throws -> Set<FilePath> {
        var results = Set<FilePath>()
        try matchPattern(pattern, results: &results)
        return results
    }

    private func matchPattern(_ pattern: String, results: inout Set<FilePath>) throws {
        let adjusted =
            pattern
            .replacingOccurrences(of: #"^\./(?=.)"#, with: "", options: .regularExpression)
            .replacingOccurrences(of: "^\\.[/]?$", with: "*", options: .regularExpression)
            .replacingOccurrences(of: "\\*{2,}[/]", with: "*/**/", options: .regularExpression)
            .replacingOccurrences(of: "[/]\\*{2,}([^/])", with: "/**/*$1", options: .regularExpression)
            .replacingOccurrences(of: "^\\*{2,}([^/])", with: "**/*$1", options: .regularExpression)
        let components = adjusted.split(separator: "/").map(String.init)
        for child in directChildren() {
            try child.matchComponents(components, root: self, results: &results)
        }
    }

    private func matchComponents(
        _ components: [String],
        root: FilePath,
        results: inout Set<FilePath>
    ) throws {
        guard !components.isEmpty else {
            // Pattern fully consumed: include this node, all its ancestors up
            // to (but not including) root, and all descendants.
            var dir = lexicallyNormalized()
            let normalizedRoot = root.lexicallyNormalized()
            while dir != normalizedRoot {
                results.insert(dir)
                let parent = dir.removingLastComponent()
                guard parent != dir else { break }
                dir = parent
            }
            recursiveChildren().forEach { results.insert($0) }
            return
        }

        let head = components.first!
        let tail = Array(components.dropFirst())

        if head == "**" {
            var collapsedTail = tail
            while collapsedTail.first == "**" {
                collapsedTail = Array(collapsedTail.dropFirst())
            }
            // Zero segments consumed by **.
            try matchComponents(collapsedTail, root: root, results: &results)
            // One segment consumed by **, then continue matching **.
            for child in directChildren() {
                try child.matchComponents(components, root: root, results: &results)
            }
            return
        }

        if try globNameMatch(lastComponent?.string ?? "", pattern: head) {
            try matchComponents(tail, root: root, results: &results)
            for child in directChildren() where try globNameMatch(child.lastComponent?.string ?? "", pattern: tail.first ?? "") {
                try child.matchComponents(tail, root: root, results: &results)
            }
        }
    }

    private func globNameMatch(_ name: String, pattern: String) throws -> Bool {
        let regexPattern =
            "^"
            + NSRegularExpression.escapedPattern(for: pattern)
            .replacingOccurrences(of: "\\*", with: "[^/]*")
            .replacingOccurrences(of: "\\?", with: "[^/]")
            .replacingOccurrences(of: "[\\^", with: "[^")
            .replacingOccurrences(of: "\\[", with: "[")
            .replacingOccurrences(of: "\\]", with: "]") + "$"
        _ = try Regex(regexPattern)
        return name.range(of: regexPattern, options: .regularExpression) != nil
    }

    private func directChildren() -> [FilePath] {
        guard let names = try? FileManager.default.contentsOfDirectory(atPath: string) else { return [] }
        return names.map { appending($0) }
    }

    private func recursiveChildren() -> [FilePath] {
        var children: [FilePath] = [self]
        guard
            let enumerator = FileManager.default.enumerator(
                at: URL(fileURLWithPath: string),
                includingPropertiesForKeys: [.isDirectoryKey, .isSymbolicLinkKey]
            )
        else { return children }
        while let child = enumerator.nextObject() as? URL {
            children.append(FilePath(child.path))
        }
        return children
    }
}

[jglogan]

Also, FilePath.allocatedSize(): apple/container#1555.

A wrapper around FileDescriptorOps.enumerate() would be convenient as well.

[saehejkang]

Extract the code you wrote for the image save and load into an FilePathOps.absolutePath(_ path: FilePath) -> FilePath, write some unit tests, and then this one is done.

I will work on these changes.