v1.7.1 — Resources reach the app bundle as regular files, and the sandbox honours TMPDIR

[ericodx]

This release fixes a run that could not start on an iOS test host with a folder of resources. The sandbox linked every unchanged file to the original, Xcode kept those links when it copied a folder reference into the bundle, and the simulator refused to install an app whose symlinks point outside it (#245). Unchanged resources are now copied into the sandbox; unchanged Swift sources stay linked. The sandbox directory also moves to $TMPDIR/swift-mutation-testing when TMPDIR is set, as the documentation always said. The rest of the release is documentation and code quality.

---

Bug fixes

Resources copied into the sandbox, not linked (#245)

• An iOS test host embedding a framework with a folder reference of resources built in the sandbox but failed to install: MIInstallerErrorDomain code 70, InvalidSymlink, naming a file under Frameworks/<name>.framework/Resources/…. The baseline failed before any test ran
• Every unchanged file that is not a .swift source is now a copy of the original, with its modification date kept, so an incremental build on a kept sandbox still sees it unchanged. Unchanged .swift files, and files that are symlinks in the project itself, stay links
• The special case that copied Icon Composer .icon bundles (v1.6.3, Icon Composer bundles fail to build because sandbox files are symlinks #180) is gone: the general rule covers it
• Measured on the iOS app of the v1.7.0 notes with a 1000-file, 128 MB resource folder added: the run takes the same time as before, cold and refreshed, and the verdicts match

iOS app, 112 mutants, 2 simulators	v1.7.0, first run	v1.7.0, second run	v1.7.1, first run	v1.7.1, second run
Duration	330 s	327 s	328 s	337 s
Kept slot on disk	136 MB	142 MB	265 MB	270 MB

TMPDIR names the sandbox root (#245)

• On macOS, Foundation's temporary directory comes from confstr(_CS_DARWIN_USER_TEMP_DIR) and ignores TMPDIR, so setting the variable did not move the sandboxes although the documentation said $TMPDIR/swift-mutation-testing. A non-empty TMPDIR is now used; when it is absent or empty, the Foundation directory is the fallback, as before
• The orphan sweep and the kept sandboxes follow the same root, so a run with TMPDIR set neither sees nor leaves anything in the default location

--help alignment (#238)

• The --testing-framework line was one column off, and <project-path> was described as an Xcode project root only. It accepts an SPM package root too

---

Documentation

• Every document checked against the code (Review all documentation, diagrams included, against what the CLI does and how it is implemented #238): Docs/, README, CONTRIBUTING, SECURITY, the PR template and the Claude Code skill. Wrong statements fixed, 31 Mermaid diagrams redrawn where the flow had changed, console samples matched to what the tool prints, and the CodeBase index lists all 353 declarations of Sources
• Operator campaign rates (Operator campaign drops equivalence reviews whose mutation text spans several lines #239): the script that regenerates Docs/operators/results.md dropped reviews whose text spans several lines, so OPERATORS.md and results.md disagreed with equivalence.csv. It now reads whole CSV records, and the three agree
• Sandbox copy rule: Architecture, CodeBase and USAGE describe which files are links and which are copies, and why

---

Code quality

• TestBundleInvocation.requests takes an Options value instead of nine parameters, and the SPM request builder nests two closures instead of three (requests takes 9 parameters and spmRequests nests 3 closures #233)
• Line coverage of Sources/ by the unit tests is 100% (Unit tests leave 11 lines of Sources uncovered #235), and periphery scan reports no declaration without a caller (Periphery reports 13 declarations in Sources that only the tests use #242). The helpers only the tests used moved to the test target
• No behaviour change from any of these

---

Upgrading

• No configuration change
• A kept sandbox now holds a copy of every non-Swift file of the project instead of a link, so $TMPDIR/swift-mutation-testing grows by the project's resources per slot. The first run after upgrading refreshes each slot once
• If you set TMPDIR, the sandboxes move there. Slots left in the Foundation temporary directory by earlier versions are not removed; delete swift-mutation-testing under $(getconf DARWIN_USER_TEMP_DIR) to reclaim them

---

Requirements

• macOS 15+
• Swift 6.2+ (Xcode 26)
• Xcode project or workspace with a valid scheme and test target, or an SPM package with a test target

---

Installation

See the Installation Guide for Homebrew, pre-built binary, and build from source instructions.

---

What's Changed

• Copy unchanged resources into the sandbox and root it at TMPDIR by @ericodx in Copy unchanged resources into the sandbox and root it at TMPDIR #247

Full Changelog: v1.7.0...v1.7.1

---

This discussion was created from the release v1.7.1 — Resources reach the app bundle as regular files, and the sandbox honours `TMPDIR`.