@williamthorsen/toolbelt.filesystem 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.9.0 — 2026-09-15
+
+### 🎉 Features
+
+- 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
+
+  - Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
+
+  Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
+
+- Add a ReadyUp adoption kit to toolbelt.filesystem (#316)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.filesystem` that recommends `writeAtomic` where a project writes a file to a temporary path and renames it into place, and `listDirectoryChain`, `findDirectoryChainMatch`, or `listDirectoryChainMatches` where a loop ascends to the filesystem root by `path.dirname`.
+  - Promotes `writeAtomic` to the candidate tier.
+
+  Migration: Change any import of `writeAtomic` from `@williamthorsen/toolbelt.filesystem/proposed` to `@williamthorsen/toolbelt.filesystem/candidate`.
+
+- Read a directory walk's probed name through a binding or constant (#324)
+
+  - Extends the ReadyUp adoption kit in `@williamthorsen/toolbelt.packaging` to recommend `findPackageRoot` or `resolveSelfVersion` for a hand-rolled `package.json` search that checks for the file through a variable declared once inside its loop and never reassigned there, or through a string constant declared once in the same file.
+  - Stops the kit in `@williamthorsen/toolbelt.filesystem` from reporting such a search, which it previously treated as a generic directory walk.
+
+- Report hand-rolled dedents in the strings adoption kit (#330)
+
+  - Adds `no-joined-line-array`, which reports an array of string or template literals that spans several lines and is joined with a newline.
+  - Adds `no-layout-breaking-template`, which reports an untagged template literal whose later lines drop below the indentation of the line on which it opens.
+
+### 🐛 Bug fixes
+
+- Stop reading each segment of a probe's path as a separately probed name (#320)
+
+  - Fixes an issue in which `toolbelt.filesystem`'s ReadyUp adoption kit treated a loop over parent directories as a search for each directory's own `package.json` when the path checked at each level contained a `'package.json'` literal, as in `path.join(dir, 'node_modules', name, 'package.json')`, and so did not report the loop under `no-hand-rolled-directory-walk`.
+
+### ♻️ Refactoring
+
+- Move directory-walk recognition from filesystem into packages/adoption (#318)
+
+  - Adds `listDirectoryAscents` to `packages/adoption`, which reports each directory ascent once with the names probed by its innermost loop, and reduces `filesystem`'s `listChainWalkSites` to a partition of that output, so a `toolbelt.packaging` kit can partition the same ascents without its own copy of the recognition.
+  - Renames the hand-off rule `isProjectRootSearch` to `isManifestSearch` and rewrites the text in `packages/adoption` and `filesystem` that credited `findProjectRoot` alone with a `package.json` walk.
+  - Stops `filesystem`'s kit from reporting a loop that ascends one binding around an inner loop ascending another binding and probing for `package.json`, which is the only finding changed by the move.
+
+### 🧪 Tests
+
+- Move the rdy run report reader into the adoption test utilities (#323)
+
+  - Replaces the `rdy run --json` report reader copied into each of the twelve `pragma-suppression.tool.test.ts` suites with `listKitCheckReports`, a helper added to `@williamthorsen/toolbelt.adoption/test-utils` that runs a package's compiled kit over a fixture repo and returns its check reports, so a change to the shape of readyup's report needs one edit rather than twelve.
+  - Fixes the error thrown for a kit that does not load: Each copy discarded the load error recorded by `rdy` on the kit's entry and threw "the run reported no adoption checks", and the helper throws with `rdy`'s own message instead.
+
+### ⚙️ Tooling
+
+- Remove the stale repo-local cliff.toml and normalize changelog titles (#327)
+
+  - Stops `release-kit prepare` from printing a "skipped due to grouping error(s)" warning for each releasable workspace by letting it resolve the git-cliff template bundled with release-kit, previously overridden by the root `cliff.toml`.
+  - Excludes commits without a ticket prefix from future changelog entries.
+  - Renames the section titles in every `packages/*/.meta/changelog.json`, except `Dependency updates`, to the headings of release-kit's work-type taxonomy, such as "🎉 Features" and "🏗️ Internal features", and regenerates each `CHANGELOG.md` so that release-kit orders existing and new sections by the same rule.
+  - Causes the next `release-kit prepare` to plan patch releases of `dstructs`, `hof`, and `sets`, which had no other commits since their last release, because the changelog commit touches every workspace.
+
+### 📚 Documentation
+
+- Align prose with plain-speech doctrine and writing conventions (#306)
+
+  - Copy-edits prose across the repo: comments, test names, package READMEs, and `AGENTS.md`.
+  - Rewrites a few user-facing strings as well, among them `configure-project`'s help text and the errors from `parseProjectSpec`, `securityCommands`, and `hashString`.
+
+## 0.8.3 — 2026-09-06
+
+### 📚 Documentation
+
+- Repair reduced object relatives in passages recurring across files (#262)
+
+  Repairs the reduced object relative in the prose passages that recur across more than one file, in package READMEs, source comments, test titles, and the ReadyUp kits' check messages.
+
+- Repair reduced object relatives in the READMEs and AGENTS.md (#263)
+
+  Repairs the reduced object relative in `AGENTS.md`, the root `README.md`, and the package READMEs.
+
+- Repair reduced object relatives in packages/adoption (#264)
+
+  Repairs the reduced object relative in `packages/adoption`, in source comments, doc descriptions, and test titles.
+
+- Repair the repository's prose and record every rejection's ground (#290)
+
+  Applies one repo-wide `revise-prose` sweep across the repository's READMEs, `AGENTS.md`, source comments, doc descriptions, and test names.
+
 ## 0.8.2 — 2026-08-30
 
 ### Dependency updates
@@ -10,7 +94,7 @@ All notable changes to this project will be documented in this file.
 
 ## 0.8.1 — 2026-08-28
 
-### Refactoring
+### ♻️ Refactoring
 
 - Upgrade eslint-config-typescript to v12.0.1 and satisfy its new rules (#236)
 
@@ -18,7 +102,7 @@ All notable changes to this project will be documented in this file.
 
 ## 0.8.0 — 2026-08-24
 
-### Features
+### 🎉 Features
 
 - Add a recursive listFiles to createTempTree's entry API (#212)
 
@@ -26,7 +110,7 @@ All notable changes to this project will be documented in this file.
 
 ## 0.7.0 — 2026-08-21
 
-### Features
+### 🎉 Features
 
 - 🚨 **Breaking:** Fix createTempTree's symlink guard and disposal, and complete its entry API (#207)
 
@@ -40,13 +124,13 @@ All notable changes to this project will be documented in this file.
 
 ## 0.6.0 — 2026-08-16
 
-### Features
+### 🎉 Features
 
 - Add mkdir, symlink, write, and writeJson methods to `TempTree` (#176)
 
   Adds four write methods to `TempTree` in `@williamthorsen/toolbelt.filesystem`: `mkdir`, `symlink`, `write`, and `writeJson`. Each takes a tree-relative path, creates the parent directories it needs, resolves through the same containment check `resolve` applies, and returns the absolute path, so a suite writing into a built temporary tree reaches it through the handle rather than through `node:fs`. `symlink` accepts a link path and a target, and picks the link type from the target.
 
-### Tests
+### 🧪 Tests
 
 - Drop expect-type in favor of expectTypeOf (#175)
 
@@ -54,7 +138,7 @@ All notable changes to this project will be documented in this file.
 
 ## 0.5.0 — 2026-08-15
 
-### Features
+### 🎉 Features
 
 - 🚨 **Breaking:** Promote createTempTree to the candidate tier with a caller-chosen prefix and binary entries (#148)
 
@@ -68,7 +152,7 @@ All notable changes to this project will be documented in this file.
 
 ## 0.4.1 — 2026-08-13
 
-### Tooling
+### ⚙️ Tooling
 
 - Remove redundant .gitignore files
 - Populate manifest metadata and adopt a pnpm catalog (#140)
@@ -77,7 +161,7 @@ All notable changes to this project will be documented in this file.
 
 ## 0.4.0 — 2026-08-12
 
-### Features
+### 🎉 Features
 
 - 🚨 **Breaking:** Add reconcileFile to toolbelt.filesystem and promote describeError to release tier (#122)
 
@@ -95,7 +179,7 @@ All notable changes to this project will be documented in this file.
 
 ## 0.3.0 — 2026-08-08
 
-### Features
+### 🎉 Features
 
 - Migrate replaceFileExtension into filesystem package (#74)
 
@@ -121,7 +205,7 @@ All notable changes to this project will be documented in this file.
 
   `findProjectRoot` moves from `@williamthorsen/toolbelt.filesystem` to `@williamthorsen/toolbelt.packaging`. Callers of `loadConfigCascade` must now state where its upward search stops, rather than relying on a project root the function found for them.
 
-### Tooling
+### ⚙️ Tooling
 
 - Migrate Vitest configs to the nmr projects model (#73)
 
@@ -133,17 +217,17 @@ All notable changes to this project will be documented in this file.
 
 ## 0.2.1 — 2026-07-27
 
-### Tooling
+### ⚙️ Tooling
 
 - Normalize Vitest, and lint configs
 
-### Documentation
+### 📚 Documentation
 
 - Change license to ISC
 
 ## 0.2.0 — 2026-07-24
 
-### Features
+### 🎉 Features
 
 - Add the filesystem package with bounded cascading config discovery (#71)
 

package/README.md

@@ -1,8 +1,43 @@
+<!-- readme-type: library -->
+
 # @williamthorsen/toolbelt.filesystem
 
 Filesystem utilities for TypeScript and JavaScript.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.9.0 (2026-09-15)
+
+### 🎉 Features
+
+- 🚨 **Breaking:** Move createTempTree from toolbelt.filesystem to toolbelt.testing (#313)
+
+  - Moves `CreateTempTreeOptions` and the `TempTree` handle to `@williamthorsen/toolbelt.testing/candidate` along with `createTempTree`.
+
+  Migration: Import `createTempTree`, `CreateTempTreeOptions`, and `TempTree` from `@williamthorsen/toolbelt.testing/candidate`, and declare `@williamthorsen/toolbelt.testing` in the manifest that declared `@williamthorsen/toolbelt.filesystem` for them.
+
+- Add a ReadyUp adoption kit to toolbelt.filesystem (#316)
+
+  - Adds a ReadyUp adoption kit to `@williamthorsen/toolbelt.filesystem` that recommends `writeAtomic` where a project writes a file to a temporary path and renames it into place, and `listDirectoryChain`, `findDirectoryChainMatch`, or `listDirectoryChainMatches` where a loop ascends to the filesystem root by `path.dirname`.
+  - Promotes `writeAtomic` to the candidate tier.
+
+  Migration: Change any import of `writeAtomic` from `@williamthorsen/toolbelt.filesystem/proposed` to `@williamthorsen/toolbelt.filesystem/candidate`.
+
+- Read a directory walk's probed name through a binding or constant (#324)
+
+  - Extends the ReadyUp adoption kit in `@williamthorsen/toolbelt.packaging` to recommend `findPackageRoot` or `resolveSelfVersion` for a hand-rolled `package.json` search that checks for the file through a variable declared once inside its loop and never reassigned there, or through a string constant declared once in the same file.
+  - Stops the kit in `@williamthorsen/toolbelt.filesystem` from reporting such a search, which it previously treated as a generic directory walk.
+
+- Report hand-rolled dedents in the strings adoption kit (#330)
+
+  - Adds `no-joined-line-array`, which reports an array of string or template literals that spans several lines and is joined with a newline.
+  - Adds `no-layout-breaking-template`, which reports an untagged template literal whose later lines drop below the indentation of the line on which it opens.
+
+### 🐛 Bug fixes
+
+- Stop reading each segment of a probe's path as a separately probed name (#320)
+
+  - Fixes an issue in which `toolbelt.filesystem`'s ReadyUp adoption kit treated a loop over parent directories as a search for each directory's own `package.json` when the path checked at each level contained a `'package.json'` literal, as in `path.join(dir, 'node_modules', name, 'package.json')`, and so did not report the loop under `no-hand-rolled-directory-walk`.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -12,9 +47,44 @@ pnpm add @williamthorsen/toolbelt.filesystem
 
 ## Runtime requirements
 
-`createTempTree`, `findDirectoryChainMatch`, `listDirectoryChainMatches`, `loadConfigCascade`, `reconcileFile`, `reconcileFileFromFile`, and `writeAtomic` reach the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem. `listDirectoryChain` and `replaceFileExtension` touch no filesystem, so an edge runtime that exposes none runs them; they still import `node:path`, which a browser bundle has to supply.
+`findDirectoryChainMatch`, `listDirectoryChainMatches`, `loadConfigCascade`, `reconcileFile`, `reconcileFileFromFile`, and `writeAtomic` reach the filesystem through `node:` builtins, so they run under Node.js 24 or later, Bun, and Deno. They do not run in browsers, nor in edge runtimes that expose no filesystem. `listDirectoryChain` and `replaceFileExtension` touch no filesystem, so an edge runtime that exposes none runs them; they still import `node:path`, which a browser bundle has to supply.
+
+`loadConfigCascade` imports each config through the host runtime, so a `.ts` config is subject to whatever that runtime does with TypeScript. Node strips types rather than compiling them, which admits erasable syntax alone: An `enum`, a `namespace`, or a parameter property in a config file fails to parse. A `.mjs` or `.js` config sidesteps the question.
+
+## Adoption checks
+
+The package ships a ReadyUp kit, so a project that installs it can ask how far its adoption got:
+
+```sh
+rdy run --packages
+```
+
+The kit reads the project's tracked sources and reports two idioms, each counted against the calls that the project already makes into this package. Both report at `recommend`: They are correct code that a published function expresses better, not defects.
+
+`no-hand-rolled-atomic-write` reports a function body that writes a path held in a binding and renames that same binding, naming the function that holds it. A write alone, a rename alone, a `copyFile` followed by a rename, and a rename of a path that the body never wrote report nothing. The site reports at `recommend` however the temp file is staged, because a text scan cannot tell whether two paths share a volume, and one staged under the system temporary directory is the case worth checking by hand: `rename` is atomic only within one filesystem.
 
-`loadConfigCascade` imports each config through the host runtime, so a `.ts` config is subject to whatever that runtime does with TypeScript. Node strips types rather than compiling them, which admits erasable syntax alone: an `enum`, a `namespace`, or a parameter property in a config file fails to parse. A `.mjs` or `.js` config sidesteps the question.
+`no-hand-rolled-directory-walk` reports a loop that ascends by `dirname` until it reaches the filesystem root, naming the line the loop opens on. A loop that only ascends takes [`listDirectoryChain`](#listdirectorychain); one that probes each level for a name takes [`findDirectoryChainMatch`](#finddirectorychainmatch) or [`listDirectoryChainMatches`](#listdirectorychainmatches). The report names the site rather than the shape, so the fix text describes both and the reader chooses from the loop itself. A loop probing for `package.json` is left alone: That site belongs to [`@williamthorsen/toolbelt.packaging`](https://github.com/williamthorsen/toolbelt/tree/main/packages/packaging#readme), whose own kit reports it, and reporting it here would mean seeing one loop twice under conflicting advice.
+
+The walk detector under-matches by design. A recursive walk-up function is no loop, an ascent written as `path.resolve(dir, '..')` carries a different anchor, and a loop that computes a parent per item without assigning it back is no ascent. None of the three reports.
+
+Bootstrap wrappers under `bin/` are exempt: Such a wrapper imports only builtins so its build-first message survives an incomplete install, and importing this package there would replace that message with a module-resolution failure. Tests are exempt too, since they write these shapes deliberately. A source declared generated or vendored by the project in its own `.gitattributes`, under `linguist-generated` or `linguist-vendored`, is exempt as well: The sweep drops it before the kit sees it, so committed bundler output yields no advice that anyone could act on. The sweep is readyup's, so this holds on readyup 0.35.0 or later.
+
+A reviewed site is silenced by an `rdy-ignore` pragma on its own line, or `rdy-ignore-next-line` on the line above. A pragma naming a check's id suppresses that check alone; with no id it covers every check on the line. A failed check prints its id ahead of its fraction, which is the form to write:
+
+```ts
+// rdy-ignore-next-line toolbelt.filesystem/no-hand-rolled-directory-walk -- the ascent stops at a ceiling
+while (dir !== stopAtDir) {
+  dir = path.dirname(dir);
+}
+```
+
+Add the package to `.config/readyup.config.ts` to include it in a routine sweep:
+
+```ts
+export default defineRdyConfig({
+  packages: ['@williamthorsen/toolbelt.filesystem'],
+});
+```
 
 ## `listDirectoryChain`
 
@@ -36,7 +106,7 @@ listDirectoryChain('/home/dev/app/src', { stopAtDir: '/home/dev' });
 
 `stopAtDir` bounds the ascent inclusively and is resolved the same way `startDir` is, so a relative ceiling behaves like a relative start. One that is neither the start directory nor an ancestor of it throws, naming both, rather than being ignored and letting the ascent run past the bound. The comparison is exact, so a `stopAtDir` differing from its target only in case is off the chain even on a volume that would open it.
 
-The result type records that the chain is never empty, which is what spares the nearest directory an undefined check:
+The result type records that the chain is never empty, which spares the nearest directory an undefined check:
 
 ```ts
 const [nearestDir] = listDirectoryChain(process.cwd()); // string, not string | undefined
@@ -71,9 +141,9 @@ listDirectoryChainMatches('/home/dev/app/src', ['.git'], { stopAtDir: '/home/dev
 // [{ dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }]
 ```
 
-A level yields at most one match, the earliest of `names` found there, and a level holding none contributes nothing, so an empty result is an ordinary outcome rather than an error. A name matches a directory as readily as a file, which is what lets `.git` be probed without knowing whether the clone is ordinary or a worktree.
+A level yields at most one match, the earliest of `names` found there, and a level holding none contributes nothing, so an empty result is an ordinary outcome rather than an error. A name matches a directory as readily as a file, which lets `.git` be probed without knowing whether the clone is ordinary or a worktree.
 
-Each name is a path relative to the level it is probed against, so a nested location such as `.config/stack.config.mjs` works. A name that would leave its level (an absolute path, or one whose `..` segments escape it) is rejected before any level is probed, so the rejection never depends on what happens to exist on disk.
+Each name is a path relative to the level against which it is probed, so a nested location such as `.config/stack.config.mjs` works. A name that would leave its level (an absolute path, or one whose `..` segments escape it) is rejected before any level is probed, so the rejection never depends on what happens to exist on disk.
 
 `options` is forwarded to `listDirectoryChain`, so `stopAtDir` bounds the ascent the same way.
 
@@ -98,7 +168,7 @@ findDirectoryChainMatch('/home/dev/app/src', ['.git']);
 // { dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }
 ```
 
-Probing stops at the first level that matches, so no level beyond it is touched -- the reason to reach for this rather than read element zero off `listDirectoryChainMatches`, which probes to the ceiling regardless. The nullable return type is the other reason: a result that may be absent says so, where an array leaves the caller to narrow.
+Probing stops at the first level that matches, so no level beyond it is touched -- the reason to reach for this rather than read element zero off `listDirectoryChainMatches`, which probes to the ceiling regardless. The nullable return type is the other reason: A result that may be absent says so, where an array leaves the caller to narrow.
 
 ## `loadConfigCascade`
 
@@ -113,9 +183,9 @@ loadConfigCascade<TConfig>(options: {
 
 Loads every config file between `startDir` and `stopAtDir`, nearest first, and reads nothing above that boundary.
 
-Discovery is [`listDirectoryChainMatches`](#listdirectorychainmatches) bounded at `stopAtDir`: the first of `fileNames` that exists at a level becomes that level's config, a level holding none contributes nothing, and a name that would leave its level is rejected before any file is read. A `stopAtDir` that is neither the start directory nor one of its ancestors throws, on the same terms `listDirectoryChain` sets out.
+Discovery is [`listDirectoryChainMatches`](#listdirectorychainmatches) bounded at `stopAtDir`: The first of `fileNames` that exists at a level becomes that level's config, a level holding none contributes nothing, and a name that would leave its level is rejected before any file is read. A `stopAtDir` that is neither the start directory nor one of its ancestors throws, on the same terms that `listDirectoryChain` sets out.
 
-The boundary is required, and it is the caller's to choose. That is what keeps this function free of any notion of what marks a project: it never asks whether a directory holds a lockfile or a workspace manifest. Where the boundary should be a project root, [`findProjectRoot`](https://github.com/williamthorsen/toolbelt/tree/main/packages/packaging#findprojectroot) in `@williamthorsen/toolbelt.packaging` resolves one from markers.
+The boundary is required, and it is the caller's to choose. That keeps this function free of any notion of what marks a project: It never asks whether a directory holds a lockfile or a workspace manifest. Where the boundary should be a project root, [`findProjectRoot`](https://github.com/williamthorsen/toolbelt/tree/main/packages/packaging#findprojectroot) in `@williamthorsen/toolbelt.packaging` resolves one from markers.
 
 The matched files are then imported one at a time, and `shouldStopAscent` is consulted after each. Once it returns true, the ascent halts and no farther file is imported at all, rather than being loaded and discarded:
 
@@ -130,7 +200,7 @@ interface ConfigCascade<TConfig> {
 }
 ```
 
-A config is the module's default export. A matched module declaring none is rejected by name; validating what a config contains stays with the caller, which is what lets one mechanism serve schemas sharing no fields.
+A config is the module's default export. A matched module declaring none is rejected by name; validating what a config contains stays with the caller, which lets one mechanism serve schemas sharing no fields.
 
 ### The `shouldStopAscent` convention
 
@@ -155,7 +225,7 @@ const { entries, stopReason } = await loadConfigCascade<StackConfig>({
 });
 ```
 
-`stopReason` is provenance for the caller to surface, so a user can see whether the predicate ended the cascade or it simply reached the boundary. Which directory bounded it is the `stopAtDir` the caller passed in.
+`stopReason` is provenance for the caller to surface, so a user can see whether the predicate ended the cascade or it simply reached the boundary. Which directory bounded it is the `stopAtDir` passed in by the caller.
 
 ## `reconcileFile`
 
@@ -176,20 +246,20 @@ reconcileFile('.config/tool.config.ts', template);
 // { filePath: '.config/tool.config.ts', outcome: 'created' }
 ```
 
-Missing parent directories are created. `isDryRun` writes nothing and creates no directory, returning the outcome the real call would have produced, which is what lets a `--dry-run` flag print the same lines the run itself would. A write that would fail is the exception: nothing detects that without attempting it, so a dry run reports the outcome the write was headed for.
+Missing parent directories are created. `isDryRun` writes nothing and creates no directory, returning the outcome that the real call would have produced, which lets a `--dry-run` flag print what the run itself would. A write that would fail is the exception: Nothing detects that without attempting it, so a dry run reports the write's intended outcome.
 
-`conflictPolicy` decides what becomes of an existing file whose content differs, and decides nothing else: it is consulted in that case alone. The default, `'skip'`, never replaces a file the user may have edited.
+`conflictPolicy` decides what becomes of an existing file whose content differs, and decides nothing else: It is consulted in that case alone. The default, `'skip'`, never replaces a file that the user may have edited.
 
 | exists | differs | `conflictPolicy` | outcome       |
 | ------ | ------- | ---------------- | ------------- |
-| no     | —       | —                | `created`     |
+| no     | n/a     | n/a              | `created`     |
 | yes    | no      | either           | `up-to-date`  |
 | yes    | yes     | `replace`        | `overwritten` |
 | yes    | yes     | `skip`           | `skipped`     |
 
-What counts as differing follows the policy, which is the part worth reading twice. `'replace'` promises the file holds exactly `content` afterwards, so only byte-identical content reports `up-to-date`; a file differing from `content` only in trailing whitespace is rewritten, because calling it up to date would leave the caller holding a file that is not what it asked for. `'skip'` modifies nothing either way, so its comparison decides a message alone and ignores trailing whitespace per line and at end of file, which keeps formatter churn from reading as a conflict. `up-to-date` therefore means the same thing under both: this policy has no work to do.
+What counts as differing follows the policy, which is the part worth reading twice. `'replace'` promises the file holds exactly `content` afterwards, so only byte-identical content reports `up-to-date`; a file differing from `content` only in trailing whitespace is rewritten, because calling it up to date would leave the caller holding a file that is not what it asked for. `'skip'` modifies nothing either way, so its comparison decides a message alone and ignores trailing whitespace per line and at end of file, which keeps formatter churn from reading as a conflict. `up-to-date` therefore means the same thing under both: This policy has no work to do.
 
-The result discriminates on `outcome`, so a failure always carries its reason:
+The result discriminates on `outcome`, so a failure always names its reason:
 
 ```ts
 type FileReconciliation =
@@ -198,13 +268,13 @@ type FileReconciliation =
   | { filePath: string; outcome: 'failed'; error: string };
 ```
 
-An I/O error on the write path reports `failed` rather than throwing, which is what lets a command writing several files collect a result for each instead of losing the rest to the first failure.
+An I/O error on the write path reports `failed` rather than throwing, which lets a command writing several files collect a result for each instead of losing the rest to the first failure.
 
 Three behaviors are worth knowing before they surprise you:
 
-- A `skipped` result carrying an `error` means the existing file could not be read for comparison. The file was left alone, which is exactly what `'skip'` promises, so this is not a failure and a command exiting non-zero on failures should not count it as one.
-- The existence probe follows symlinks. A dangling symlink therefore reports as non-existent: the outcome is `created`, the result names the link, and the bytes land at the link's target.
-- The probe and the write are separate calls, leaving a window in which another process can create or remove the file. That gap is left open deliberately: the callers this serves are scaffolding commands with no competing writer, and an exclusive-create flag would close only the create half of it.
+- A `skipped` result with an `error` means the existing file could not be read for comparison. The file was left alone, which is exactly what `'skip'` promises, so this is not a failure and a command exiting non-zero on failures should not count it as one.
+- The existence probe follows symlinks. A dangling symlink therefore reports as non-existent: The outcome is `created`, the result names the link, and the bytes land at the link's target.
+- The probe and the write are separate calls, leaving a window in which another process can create or remove the file. That gap is left open deliberately: The callers that this serves are scaffolding commands with no competing writer, and an exclusive-create flag would close only the create half of it.
 
 ## `reconcileFileFromFile`
 
@@ -216,7 +286,7 @@ reconcileFileFromFile(
 ): FileReconciliation;
 ```
 
-Reconciles `filePath` against the content of `sourcePath`, which is what a command copying a bundled template reaches for:
+Reconciles `filePath` against the content of `sourcePath`, for which a command copying a bundled template reaches:
 
 ```ts
 import { reconcileFileFromFile } from '@williamthorsen/toolbelt.filesystem';
@@ -225,9 +295,9 @@ reconcileFileFromFile('.config/git-cliff.toml', bundledTemplatePath);
 // { filePath: '.config/git-cliff.toml', outcome: 'created' }
 ```
 
-It is [`reconcileFile`](#reconcilefile) with the read supplied: the outcome table, the conflict policy, the created parent directories, and the result type are that function's, unchanged. Three things are this one's own.
+It is [`reconcileFile`](#reconcilefile) with the read supplied: The outcome table, the conflict policy, the created parent directories, and the result type are that function's, unchanged. Three things are this one's own.
 
-The source is read as utf8 text, so a binary source is not supported: it would be decoded and re-encoded on the way through.
+The source is read as utf8 text, so a binary source is not supported: It would be decoded and re-encoded on the way through.
 
 A source that cannot be read reports `failed` rather than throwing, and a missing source is not distinguished from an unreadable one. The reason names the source and the cause:
 
@@ -235,134 +305,13 @@ A source that cannot be read reports `failed` rather than throwing, and a missin
 Failed to read /pkg/cliff.toml.template: ENOENT: no such file or directory, open '/pkg/cliff.toml.template'
 ```
 
-The path is interpolated rather than left to the underlying message, which carries none of its own at the read stage: reading a directory yields `EISDIR: illegal operation on a directory, read`. Under `ENOENT` the path therefore reads twice. The result's `filePath` is the destination on this path as on every other, so a caller copying several templates keys its results by destination and still sees which source failed.
+The path is interpolated rather than left to the underlying message, which has none of its own at the read stage: Reading a directory yields `EISDIR: illegal operation on a directory, read`. Under `ENOENT` the path therefore reads twice. The result's `filePath` is the destination on this path as on every other, so a caller copying several templates keys its results by destination and still sees which source failed.
 
 The source is read even under `isDryRun`, because the outcome depends on comparing its content. A dry run can therefore report `failed` where `reconcileFile`'s cannot, and it still writes nothing.
 
-## `createTempTree`
-
-Candidate tier: imported from `@williamthorsen/toolbelt.filesystem/candidate` rather than the package root, and subject to change.
-
-```ts
-createTempTree(entries: Record<string, string | Uint8Array>, options?: { prefix?: string }): TempTree;
-```
-
-Builds a throwaway directory tree and returns a handle that removes it when the binding leaves scope:
-
-```ts
-import { createTempTree } from '@williamthorsen/toolbelt.filesystem/candidate';
-
-{
-  using tree = createTempTree({
-    '.git/': '',
-    'packages/app/package.json': '{ "name": "app" }',
-  });
-
-  tree.dir; // '/private/var/folders/.../toolbelt-a1b2c3'
-  tree.resolve('packages/app'); // '/private/var/folders/.../toolbelt-a1b2c3/packages/app'
-}
-// The tree is gone here.
-```
-
-Each key of `entries` is a path relative to the tree root. One ending in `/` becomes a directory; any other becomes a file holding the mapped contents, with its intermediate directories created for it. A key resolving outside the root is rejected, and a call that throws leaves nothing on disk.
-
-A value is text or the bytes themselves, so a body no UTF-8 round trip survives is as writable as a string:
-
-```ts
-using tree = createTempTree({ 'logo.png': pngBytes });
-```
-
-`prefix` names the directory built under the system temporary directory, defaulting to `toolbelt-`. Set it to whatever is doing the building, so a tree outliving a crashed run says what made it:
-
-```ts
-using tree = createTempTree({}, { prefix: 'rdy-tsconfig-' });
-tree.dir; // '/private/var/folders/.../rdy-tsconfig-a1b2c3'
-```
-
-A prefix that would place the tree anywhere but directly inside the system temporary directory is rejected before anything is created. `mkdtemp` appends its random suffix to the joined path as given, so a prefix holding `/` or `\` targets a nested directory that has to already exist, or, where it ascends, a directory outside the temporary one; and a prefix that normalizes away (`''`, `'.'`, or `'..'`) lands the suffix beside the temporary directory rather than within it.
-
-```ts
-interface TempTree extends Disposable {
-  readonly dir: string;
-  exists(entryPath: string): boolean;
-  list(entryPath?: string): string[];
-  listFiles(entryPath?: string): string[];
-  mkdir(entryPath: string): string;
-  read(entryPath: string): string;
-  readJson(entryPath: string): unknown;
-  resolve(...segments: string[]): string;
-  rm(entryPath: string): void;
-  symlink(linkPath: string, targetPath: string): string;
-  write(entryPath: string, contents: string | Uint8Array): string;
-  writeAll(entries: Record<string, string | Uint8Array>): void;
-  writeJson(entryPath: string, value: unknown): string;
-}
-```
-
-`dir` is realpath-resolved, because `os.tmpdir()` is a symlink on macOS and a caller comparing paths against it would otherwise see a mismatch it did not cause.
-
-`resolve` joins `segments` against the root and throws when the result would fall outside it, so a stray `..` fails loudly rather than reaching into the enclosing directory. An absolute segment landing inside the root is returned unchanged. The containment test is lexical, so it does not follow a symlink inside the tree that points out of it.
-
-`mkdir`, `symlink`, `write`, `writeAll`, and `writeJson` write into the tree after it is built, for a fixture that varies per test or a file created to trigger a re-read:
-
-```ts
-using tree = createTempTree({ 'packages/app/package.json': '{ "name": "app" }' });
-
-tree.write('packages/app/src/main.ts', 'export {};\n'); // '/private/var/folders/.../packages/app/src/main.ts'
-tree.writeJson('tsconfig.json', { include: ['src'] });
-tree.mkdir('packages/empty');
-```
-
-Each creates the parent directories it needs, resolves through the same containment check as `resolve`, and returns the absolute path of what it wrote. `symlink`'s link path is checked; its target is not, being a string the link holds rather than a location the tree writes to.
-
-`writeAll` takes the same map the constructor takes, `/`-suffix convention included, so a fixture built in one call can be added to in one call:
-
-```ts
-tree.writeAll({ 'packages/empty/': '', 'packages/app/src/main.ts': 'export {};\n' });
-```
-
-It returns nothing, there being no single path to return, and unlike the constructor it is not atomic: a failure part-way leaves the entries already written in place, there being no whole tree to discard.
-
-They part company on an entry that already exists: `write` replaces it, `mkdir` leaves it and its contents alone, and `symlink` raises `EEXIST`.
-
-`symlink` takes the link first and the target second, inverting `fs.symlinkSync`, so that it reads like the other methods: the path being created leads. The target is stored verbatim, so it may be absolute or relative, name something outside the tree, or dangle until the target appears; a relative one resolves against the link's own directory, as POSIX resolves it. Code under test that reads a link rather than following it therefore sees the string that was passed, which is what a consumer hashing a link's target depends on.
-
-```ts
-using tree = createTempTree({ 'store/kit/package.json': '{ "name": "kit" }' });
-
-tree.symlink('node_modules/kit', '../store/kit'); // reads back as '../store/kit'
-tree.symlink('node_modules/.bin', tree.resolve('store/kit/bin')); // reads back absolute
-```
-
-The link type is chosen from the target, which is where the one portability difference lives. An absolute directory target is linked as a junction, which Windows creates without the elevation a directory symlink needs; a relative directory target is linked as a directory, which needs that elevation, because Node normalizes a junction's target to an absolute path and would discard the relative string. Every other target, one that does not exist included, is linked as a file, matching what Node falls back to when no type is given.
-
-`exists`, `list`, `listFiles`, `read`, `readJson`, and `rm` read the tree back and remove from it, each through the same containment check:
-
-```ts
-using tree = createTempTree({ 'packages/app/package.json': '{ "name": "app" }', 'packages/app/src/main.ts': 'export {};\n' });
-
-tree.list(); // ['packages'], defaulting to the tree root
-tree.list('packages/app'); // ['package.json', 'src'], sorted
-tree.listFiles('packages'); // ['app/package.json', 'app/src/main.ts'], at any depth
-tree.read('packages/app/src/main.ts'); // 'export {};\n'
-tree.readJson('packages/app/package.json'); // unknown, for the caller to narrow
-tree.exists('packages/app/tsconfig.json'); // false
-tree.rm('packages/app');
-```
-
-`listFiles` reaches every depth and reports paths relative to the directory it was given, sorted, with `/` as the separator on every platform: a path a test asserts on is a value rather than a location, so `'app/src/main.ts'` should not vary by platform. It parts from `list` twice. A directory that is not there answers `[]` where `list` raises `ENOENT`, which is what lets a suite assert that a build emitted nothing without guarding the call; a path that exists as a file still raises `ENOTDIR`, as `list` does. And a symlink below the directory it was given is neither named nor descended, so every path in the result names a file held inside the tree, where `list` reports a link by name at its own level. The directory given as the argument is the exception, followed as `list`, `read`, and `exists` follow theirs: one naming a link out of the tree lists the target's files.
-
-`read` returns UTF-8 text, and a missing entry raises `ENOENT` rather than answering emptily -- `exists` is the check. `readJson` returns `unknown`, so a caller narrows it rather than trusting an asserted type; contents that do not parse raise an error naming the entry, which the parse error alone does not. `exists` follows a symlink, so a dangling one answers `false`. `rm` is recursive and silent on an entry that is not there.
-
-`writeJson` writes two-space-indented JSON ending in a newline, so a tree outliving a crashed run reads as a real config file would. A fixture needing exact bytes goes through `write` instead. A value `JSON.stringify` cannot represent -- `undefined`, a function, a symbol -- is refused rather than written, so an optional binding that arrived empty fails at the call that passed it instead of surfacing later as a parse error.
-
-Disposal is idempotent, and it removes a tree that has been made unwritable: unlinking an entry needs write permission on the directory containing it, so disposal restores permission across the tree and retries once before giving up. A suite that chmods a directory to exercise a write-failure path therefore needs no wrapper to chmod it back.
-
-`Disposable` is declared in `lib.esnext.disposable.d.ts` alone, so consuming this export requires `ESNext.Disposable` in your `lib`.
-
 ## `replaceFileExtension`
 
-Proposed tier: imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
+Proposed tier: Imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
 
 ```ts
 replaceFileExtension(filePath: string, newExtension: string, options?: { oldExtension?: string }): string;
@@ -390,7 +339,7 @@ Two inputs throw rather than returning a path that would quietly be wrong: a `fi
 
 ## `writeAtomic`
 
-Proposed tier: imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
+Candidate tier: Imported from `@williamthorsen/toolbelt.filesystem/candidate` rather than the package root, and subject to change.
 
 ```ts
 writeAtomic(filePath: string, content: string | Uint8Array): Promise<void>;
@@ -399,19 +348,19 @@ writeAtomic(filePath: string, content: string | Uint8Array): Promise<void>;
 Writes `content` to `filePath` through a temp file and a rename, so a concurrent reader sees either the previous file or the complete new one, never a partial write:
 
 ```ts
-import { writeAtomic } from '@williamthorsen/toolbelt.filesystem/proposed';
+import { writeAtomic } from '@williamthorsen/toolbelt.filesystem/candidate';
 
 await writeAtomic('.agents/manifest.json', `${JSON.stringify(manifest, null, 2)}\n`);
 ```
 
-The temp file is a sibling of the target, which is the part a hand-rolled copy most often gets wrong: `rename` is atomic only within one filesystem, so a temp file staged under the system temporary directory fails with `EXDEV` the moment the target lives on another volume. Its name is dot-prefixed and carries a random component, so it stays out of `*` globs and two processes writing the same target do not collide.
+The temp file is a sibling of the target, which is the part that a hand-rolled copy most often gets wrong: `rename` is atomic only within one filesystem, so a temp file staged under the system temporary directory fails with `EXDEV` the moment the target lives on another volume. Its name is dot-prefixed and contains a random component, so it stays out of `*` globs and two processes writing the same target do not collide.
 
 Missing parent directories are created, as they are for [`reconcileFile`](#reconcilefile).
 
-An existing target's permission bits are carried onto the replacement. A plain `writeFile` truncates the file in place and so preserves its mode, while a rename replaces the inode and would otherwise reset it to the platform default; without this, swapping a plain write for an atomic one would silently widen a `0o600` file to world-readable. A target that does not exist yet gets the platform default, exactly as a plain write would.
+An existing target's permission bits are copied onto the replacement. A plain `writeFile` truncates the file in place and so preserves its mode, while a rename replaces the inode and would otherwise reset it to the platform default; without this, swapping a plain write for an atomic one would silently widen a `0o600` file to world-readable. A target that does not exist yet gets the platform default, exactly as a plain write would.
 
 Three behaviors are worth knowing before they surprise you:
 
-- Nothing is fsynced. "Atomic" here means no torn reads, not survives-power-loss: a write this function has returned from can still be lost to a power failure. A durability option is additive if a caller ever needs one.
+- Nothing is fsynced. "Atomic" here means no torn reads, not survives-power-loss: A write from which this function has returned can still be lost to a power failure. A durability option is additive if a caller ever needs one.
 - A symlink at `filePath` is replaced by a regular file rather than written through, because the rename replaces the target's directory entry. The link's former target is left untouched.
 - A failure removes the temp file best-effort and rethrows the error that caused it, never the cleanup's own. Where the cleanup also fails, the temp file survives beside the target under its dot-prefixed name ending in `.tmp`, which is where to look for one.

package/dist/esm/1-proposed/index.d.ts

@@ -1,2 +1 @@
 export { replaceFileExtension, type ReplaceFileExtensionOptions } from './replaceFileExtension.js';
-export { writeAtomic } from './writeAtomic.js';

package/dist/esm/1-proposed/index.js

@@ -1,2 +1 @@
 export { replaceFileExtension } from "./replaceFileExtension.js";
-export { writeAtomic } from "./writeAtomic.js";

package/dist/esm/1-proposed/replaceFileExtension.d.ts

@@ -1,4 +1,24 @@
+/**
+ * Returns `filePath` with its extension replaced by `newExtension`.
+ *
+ * The extension is the substring beginning at the final period in the file name, which must come at the very end
+ * of the path. A multi-part extension is indivisible to `path.extname` (`.d.ts` reports as `.ts`), so declare one
+ * through `oldExtension` to replace it whole.
+ *
+ * Either extension may be written with or without its leading period, so `'js'` and `'.js'` are equivalent. An
+ * empty `newExtension` removes the extension. Throws when `filePath` ends with a separator, and when `filePath`
+ * does not end with a declared `oldExtension`.
+ *
+ * @example
+ * replaceFileExtension('src/main.ts', '.js');                              // 'src/main.js'
+ * replaceFileExtension('src/main.d.ts', '.js', { oldExtension: '.d.ts' }); // 'src/main.js'
+ *
+ * @category Filesystem
+ * @experimental
+ * @stage proposed
+ */
 export declare function replaceFileExtension(filePath: string, newExtension: string, options?: ReplaceFileExtensionOptions): string;
 export interface ReplaceFileExtensionOptions {
+    /** The extension to replace; defaults to the value returned by Node's `path.extname`. */
     oldExtension?: string | undefined;
 }

package/dist/esm/3-candidate/index.d.ts

@@ -1 +1 @@
-export { createTempTree, type CreateTempTreeOptions, type TempTree } from './createTempTree.js';
+export { writeAtomic } from './writeAtomic.js';

package/dist/esm/3-candidate/index.js

@@ -1 +1 @@
-export { createTempTree } from "./createTempTree.js";
+export { writeAtomic } from "./writeAtomic.js";