osfs: Adopt os.Root for path containment, add RootOS, refresh helpers/tests

[pjbgf]

Overhauls the osfs package, replacing the filepath-securejoin-based path containment with Go's native os.Root (introduced in Go 1.24). It also reworks the chroot and mount helpers, expands cross-implementation tests, adds a go-git integration job to CI, and tightens documentation across every filesystem implementation.

Removes any references to the deduplication logic and the previous ChrootOS FS.

Benchstat

Less memory churn and less allocations:

                             │  before  │               after              │
                             │    sec/op    │    sec/op     vs base                │
Compare/osfs.boundOS_open-24   2.412µ ± 11%   2.576µ ± 12%  +6.82% (p=0.041 n=6)
Compare/osfs.boundOS_read-24   24.20µ ±  6%   24.53µ ±  6%       ~ (p=0.310 n=6)
Compare/osfs.rootOS_open-24                   1.605µ ±  6%
Compare/osfs.rootOS_read-24                   24.44µ ±  3%
geomean                        4.668µ         7.057µ        +4.06%               ¹
¹ benchmark set differs from baseline; geomeans may not be comparable

                             │      before   │                 after               │
                             │      B/op      │    B/op     vs base                   │
Compare/osfs.boundOS_open-24    1080.0 ± 0%     376.0 ± 0%  -65.19% (p=0.002 n=6)
Compare/osfs.boundOS_read-24     0.000 ± 0%     0.000 ± 0%        ~ (p=1.000 n=6) ¹
Compare/osfs.rootOS_open-24                     248.0 ± 0%
Compare/osfs.rootOS_read-24                     0.000 ± 0%
geomean                                     ²               -41.00%               ³ ²
¹ all samples are equal
² summaries must be >0 to compute geomean
³ benchmark set differs from baseline; geomeans may not be comparable

                             │  before  │               after               │
                             │  allocs/op   │ allocs/op   vs base                   │
Compare/osfs.boundOS_open-24   24.00 ± 0%     17.00 ± 0%  -29.17% (p=0.002 n=6)
Compare/osfs.boundOS_read-24   0.000 ± 0%     0.000 ± 0%        ~ (p=1.000 n=6) ¹
Compare/osfs.rootOS_open-24                   12.00 ± 0%
Compare/osfs.rootOS_read-24                   0.000 ± 0%
geomean                                   ²               -15.84%               ³ ²


                             │  before  │               after             │
                             │     B/s      │     B/s       vs base              │
Compare/osfs.boundOS_read-24   1.261Gi ± 6%   1.244Gi ± 5%       ~ (p=0.310 n=6)
Compare/osfs.rootOS_read-24                   1.249Gi ± 3%
geomean                        1.261Gi        1.246Gi       -1.36%

[Copilot]

Pull request overview

This PR modernizes the osfs implementation by switching path containment from filepath-securejoin to Go’s native os.Root, and introduces a new RootOS variant for caller-managed root lifecycle. It also updates tests/benchmarks and adds CI coverage by running go-git integration tests against the local go-billy checkout.

Changes:

• Replace filepath-securejoin containment with os.Root, adding RootOS (FromRoot) and updating BoundOS to use per-operation os.Root.
• Refresh and expand cross-filesystem tests (especially around symlinks, chroot behavior, and escape errors).
• Add a go-git integration GitHub Actions workflow; remove filepath-securejoin dependency from go.mod/go.sum.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
test/symlink_test.go	Normalizes Readlink assertions across platforms (slash vs host separators).
test/fs_test.go	Updates expected error for containment escapes to osfs.ErrPathEscapesParent.
osfs/os.go	Updates OS FS factory docs/behavior to always return BoundOS backed by os.Root.
osfs/os_rootfs.go	Adds RootOS, FromRoot, and shared containment/error-translation helpers.
osfs/os_options.go	Moves Option type behind !js build tag for consistent builds.
osfs/os_js.go	Keeps js/wasm option/types available; adds Option type definition for js builds.
osfs/os_bound.go	Rewrites BoundOS to open/close os.Root per operation; refactors containment logic.
osfs/os_bound_windows_test.go	Adds Windows-specific path normalization tests (drive + slash-prefixed forms).
osfs/os_bound_test.go	Overhauls tests for new os.Root containment behavior and new RootOS.
osfs/os_bench_test.go	Expands benchmarks to compare BoundOS vs RootOS vs stdlib.
helper/chroot/chroot.go	Updates chroot helper docs and refines symlink target rewrite/readlink translation.
helper/chroot/chroot_test.go	Adds tests for readlink normalization/preservation across edge cases (incl. Windows forms).
go.mod	Drops filepath-securejoin dependency.
go.sum	Removes checksums for dropped dependency.
embedfs/embed.go	Tightens documentation for embed-backed read-only filesystem semantics.
.github/workflows/go-git-integration.yml	Adds CI job to test go-git against the PR’s local go-billy.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.