@williamthorsen/toolbelt.filesystem 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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
+
+- Bumped `@williamthorsen/toolbelt.errors` to 0.6.3
+
 ## 0.8.1 — 2026-08-28
 
 ### Refactoring

package/README.md

@@ -73,7 +73,7 @@ listDirectoryChainMatches('/home/dev/app/src', ['.git'], { stopAtDir: '/home/dev
 
 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.
 
-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.
 
@@ -155,7 +155,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,18 +176,18 @@ 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 is what 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:
 
@@ -204,7 +204,7 @@ 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.
+- 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`
 
@@ -266,7 +266,7 @@ import { createTempTree } from '@williamthorsen/toolbelt.filesystem/candidate';
 
 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:
+A value is text or the bytes themselves, so a body that no UTF-8 round trip survives is as writable as a string:
 
 ```ts
 using tree = createTempTree({ 'logo.png': pngBytes });
@@ -299,7 +299,7 @@ interface TempTree extends Disposable {
 }
 ```
 
-`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.
+`dir` is realpath-resolved, because `os.tmpdir()` is a symlink on macOS and a caller comparing paths against it would otherwise see a mismatch that 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.
 
@@ -313,9 +313,9 @@ 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.
+Each creates the parent directories that 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 held by the link rather than a location to which the tree writes.
 
-`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:
+`writeAll` takes the same map as the constructor, `/`-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' });
@@ -334,7 +334,7 @@ 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.
+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 needed by a directory symlink; 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:
 
@@ -350,11 +350,11 @@ 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.
+`listFiles` reaches every depth and reports paths relative to the directory given to it, sorted, with `/` as the separator on every platform: a path in a test's assertion 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 returns `[]` 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 given to it 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.
+`read` returns UTF-8 text, and a missing entry raises `ENOENT` rather than returning an empty string -- `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 it returns `false` for a dangling one. `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.
+`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 that `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.
 
@@ -404,7 +404,7 @@ import { writeAtomic } from '@williamthorsen/toolbelt.filesystem/proposed';
 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 carries 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).
 
@@ -412,6 +412,6 @@ An existing target's permission bits are carried onto the replacement. A plain `
 
 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/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/1-proposed/writeAtomic.d.ts

@@ -1 +1,24 @@
+/**
+ * Writes `content` to `filePath` through a sibling temp file and a rename, so a concurrent reader sees either the
+ * previous file or the complete new one, never a partial write. Siting the temp file beside the target is what
+ * keeps the rename within one filesystem, where it is atomic.
+ *
+ * Missing parent directories are created. An existing target's permission bits are carried onto the replacement,
+ * which a bare `writeFile` would preserve by truncating in place and a rename would otherwise reset to the
+ * platform default.
+ *
+ * Two guarantees that it does not make. Nothing is fsynced, so a power loss can lose a write from which this
+ * function has already returned; "atomic" here means no torn reads. And the rename replaces the target's directory
+ * entry, so a symlink at `filePath` becomes a regular file rather than being written through.
+ *
+ * A failure removes the temp file best-effort and rethrows the error that caused it. Where the cleanup itself
+ * fails, the temp file survives beside the target under a dot-prefixed name ending in `.tmp`.
+ *
+ * @example
+ * await writeAtomic('.agents/manifest.json', `${JSON.stringify(manifest, null, 2)}\n`);
+ *
+ * @category Filesystem
+ * @experimental
+ * @stage proposed
+ */
 export declare function writeAtomic(filePath: string, content: string | Uint8Array): Promise<void>;

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

@@ -1,19 +1,85 @@
+/**
+ * Creates a throwaway directory tree and returns a handle that removes it on disposal. Each key of `entries` is a
+ * path relative to the tree root: One ending in `/` becomes a directory, and any other becomes a file holding the
+ * mapped contents, given as text or as the bytes themselves. A key resolving outside the root is rejected, and a
+ * call that throws leaves nothing on disk.
+ *
+ * The handle writes into the tree after it is built, through `mkdir`, `symlink`, `write`, `writeAll`, and
+ * `writeJson`. Each creates the parent directories that it needs and takes its entry path through the containment
+ * check applied by `resolve`; `symlink`'s target is the exception, stored verbatim. Every one but `writeAll`,
+ * which takes a map, returns the absolute path that it wrote. It reads the tree back through `exists`, `list`,
+ * `listFiles`, `read`, and `readJson`, and removes an entry through `rm`.
+ *
+ * `prefix` names the directory, so a tree outliving a crashed run still shows what made it.
+ *
+ * @example
+ * using tree = createTempTree({ '.git/': '', 'src/main.ts': 'export {};\n' });
+ * tree.resolve('src/main.ts'); // '/private/var/folders/…/toolbelt-a1b2c3/src/main.ts'
+ *
+ * @category Filesystem
+ * @experimental
+ * @stage candidate
+ */
 export declare function createTempTree(entries: Record<string, string | Uint8Array>, options?: CreateTempTreeOptions): TempTree;
 export interface CreateTempTreeOptions {
+    /** Leading text of the generated directory's name, to which a random suffix is appended. Defaults to `toolbelt-`. */
     prefix?: string;
 }
 export interface TempTree extends Disposable {
+    /** Realpath of the tree root, resolved because `os.tmpdir()` is a symlink on macOS. */
     readonly dir: string;
+    /** Reports whether a tree-relative path exists, following a symlink, so a dangling one yields `false`. */
     exists(entryPath: string): boolean;
+    /** Lists the names directly inside a tree-relative directory, sorted, defaulting to the tree root. */
     list(entryPath?: string): string[];
+    /**
+     * Lists every file below a tree-relative directory, at any depth, as `/`-separated paths relative to it, sorted,
+     * defaulting to the tree root. A symlink below that directory is neither listed nor descended, so every path in
+     * the result names a file held inside the tree. 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. A path
+     * that does not exist yields an empty array, where `list` throws; one that exists as a file raises `ENOTDIR`, as
+     * `list` does.
+     */
     listFiles(entryPath?: string): string[];
+    /** Creates the directory at a tree-relative path, along with its parents, leaving an existing one as it is. */
     mkdir(entryPath: string): string;
+    /** Reads the file at a tree-relative path as UTF-8 text. */
     read(entryPath: string): string;
+    /**
+     * Reads the file at a tree-relative path as JSON. The result is `unknown`, for the caller to narrow; contents
+     * that do not parse raise an error naming the entry, which the parse error alone does not.
+     */
     readJson(entryPath: string): unknown;
+    /**
+     * Resolves `segments` against the tree root, throwing when the result falls outside it. An absolute segment
+     * landing inside the root is returned. The containment test is lexical, so it does not follow a symlink within
+     * the tree that points out of it.
+     */
     resolve(...segments: string[]): string;
+    /** Removes a tree-relative entry, along with its contents where it is a directory, and a missing one silently. */
     rm(entryPath: string): void;
+    /**
+     * Links a tree-relative path to `targetPath`, taking the link first and so inverting `fs.symlinkSync`. The target
+     * is stored verbatim and is not containment-checked, being a string held by the link rather than a location to
+     * which the tree writes: It may be absolute or relative, name something outside the tree, or dangle. A relative one
+     * resolves against the link's own directory, as POSIX resolves it. An occupied link path raises `EEXIST`.
+     *
+     * The link type is the one portability difference. An absolute directory target is linked as a junction, which
+     * Windows creates without the elevation needed by a directory symlink; a relative directory target is linked as a
+     * directory, which needs that elevation; every other target, a missing one included, is linked as a file.
+     */
     symlink(linkPath: string, targetPath: string): string;
+    /** Writes `contents` at a tree-relative path, replacing an existing file. */
     write(entryPath: string, contents: string | Uint8Array): string;
+    /**
+     * Writes a map of entries in the shape taken by the constructor, so a fixture built in one call there can be
+     * added to in one call here. Unlike the constructor, a failure part-way leaves the entries already written in
+     * place, there being no whole tree to discard.
+     */
     writeAll(entries: Record<string, string | Uint8Array>): void;
+    /**
+     * Writes `value` at a tree-relative path as two-space-indented JSON ending in a newline. A value with no JSON
+     * representation -- `undefined`, a function, a symbol -- is refused rather than written.
+     */
     writeJson(entryPath: string, value: unknown): string;
 }

package/dist/esm/4-release/directory-chain-matches.d.ts

@@ -1,9 +1,48 @@
 import { type ListDirectoryChainOptions } from './listDirectoryChain.js';
 export interface DirectoryChainMatch {
+    /** The chain level at which the match was found, which differs from the entry's own directory for a nested name. */
     dir: string;
     entryName: string;
     entryPath: string;
 }
+/** Forwarded to `listDirectoryChain`. */
 export type DirectoryChainMatchOptions = ListDirectoryChainOptions;
+/**
+ * Returns the nearest directory at or above `startDir` holding one of `names`, or `undefined` when none does.
+ *
+ * Probing stops at the first level that matches, so no level beyond it is touched. Where every level's match
+ * matters rather than the nearest, `listDirectoryChainMatches` collects them all.
+ *
+ * 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 is rejected before any level is probed.
+ *
+ * @example
+ * findDirectoryChainMatch('/home/dev/app/src', ['.git']);
+ * // { dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If a name is absolute or escapes its level, or if `stopAtDir` is not on the chain.
+ */
 export declare function findDirectoryChainMatch(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch | undefined;
+/**
+ * Returns, for each directory in the chain at or above `startDir`, the first of `names` that exists there.
+ *
+ * Ordering is nearest first, and a level yields at most one match: the earliest of `names` found there. 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.
+ *
+ * Every level is probed. Where only the nearest match matters, `findDirectoryChainMatch` stops at the first.
+ *
+ * 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 is rejected before any level is probed.
+ *
+ * @example
+ * listDirectoryChainMatches('/home/dev/app/src', ['.git'], { stopAtDir: '/home/dev' });
+ * // [{ dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }]
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If a name is absolute or escapes its level, or if `stopAtDir` is not on the chain.
+ */
 export declare function listDirectoryChainMatches(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch[];

package/dist/esm/4-release/listDirectoryChain.d.ts

@@ -1,4 +1,19 @@
+/**
+ * Returns `startDir` resolved to an absolute path, followed by each of its ancestors, nearest first.
+ *
+ * The chain runs to the filesystem root unless `stopAtDir` bounds it, and always holds at least the start
+ * directory, which is what the return type records. Paths are manipulated as strings; nothing is read from disk.
+ *
+ * @example
+ * listDirectoryChain('/home/dev/app/src', { stopAtDir: '/home/dev' });
+ * // ['/home/dev/app/src', '/home/dev/app', '/home/dev']
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If `stopAtDir` is neither the start directory nor one of its ancestors.
+ */
 export declare function listDirectoryChain(startDir: string, options?: ListDirectoryChainOptions): [string, ...string[]];
 export interface ListDirectoryChainOptions {
+    /** Bounds the ascent, inclusive. Must be the start directory or one of its ancestors. */
     stopAtDir?: string | undefined;
 }

package/dist/esm/4-release/loadConfigCascade.d.ts

@@ -1,17 +1,53 @@
+/**
+ * Loads every config file between a starting directory and `stopAtDir`, nearest first.
+ *
+ * At each level from `startDir` up to and including `stopAtDir`, the first of `fileNames` that exists
+ * is taken as that level's config; levels holding none contribute nothing. The matched files are then
+ * imported one at a time, nearest first, and `shouldStopAscent` is consulted after each: Once it returns
+ * true, the ascent halts and no farther file is imported. Nothing above `stopAtDir` is ever read:
+ * Each name must stay within the level against which it is probed, so one that escapes is rejected up front.
+ *
+ * The boundary is the caller's to choose, which is what keeps this function free of any notion of what
+ * marks a project. `findProjectRoot` from `@williamthorsen/toolbelt.packaging` resolves one from markers.
+ *
+ * Each config is the module's default export; validating its contents is the caller's job.
+ *
+ * @example
+ * const { entries } = await loadConfigCascade({
+ *   fileNames: ['stack.config.mjs'],
+ *   shouldStopAscent: (config) => config.shouldStopAscent === true,
+ *   startDir: process.cwd(),
+ *   stopAtDir: findProjectRoot(process.cwd()).rootDir,
+ * });
+ *
+ * @category Filesystem
+ * @stage release
+ * @throws If a file name is absolute or escapes its level, if `stopAtDir` is off the chain, or if a matched
+ * file has no default export.
+ */
 export declare function loadConfigCascade<TConfig = unknown>(options: LoadConfigCascadeOptions<TConfig>): Promise<ConfigCascade<TConfig>>;
 export type CascadeStopReason = 'predicate' | 'stop-dir';
 export interface ConfigCascade<TConfig> {
+    /** Ordered nearest first, starting at `startDir`. */
     entries: ConfigEntry<TConfig>[];
     stopReason: CascadeStopReason;
 }
 export interface ConfigEntry<TConfig> {
     config: TConfig;
+    /** The cascade level at which the file was found, which differs from the file's own directory when `fileNames` holds a nested path. */
     dir: string;
     filePath: string;
 }
 export interface LoadConfigCascadeOptions<TConfig> {
+    /**
+     * Paths relative to each level, in precedence order; the first that exists at a level is that level's config.
+     * A name that leaves its level (an absolute path, or one whose `..` segments escape it) is rejected, since
+     * it would read outside the bounds that the cascade exists to enforce.
+     */
     fileNames: ReadonlyArray<string>;
+    /** Called after each config is loaded; returning true halts the ascent before the next import. */
     shouldStopAscent?: ((config: TConfig) => boolean) | undefined;
     startDir: string;
+    /** Bounds the ascent, inclusive. Must be the start directory or one of its ancestors. */
     stopAtDir: string;
 }

package/dist/esm/4-release/reconcileFile.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Writes `content` to `filePath`, reporting what the write took rather than throwing.
+ *
+ * Missing parent directories are created. An existing file is compared against `content` first, and what counts
+ * as a difference follows `conflictPolicy`: `'replace'` promises the file holds exactly `content` afterwards, so
+ * only byte-identical content reports `up-to-date`; `'skip'` modifies nothing either way, so its comparison
+ * 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 policies: This one has no work to do.
+ *
+ * An I/O error is reported as `failed` rather than thrown, which is what lets a caller writing several files
+ * collect a result for each instead of losing the rest to the first failure. A dry run writes nothing and
+ * creates no directory, returning the outcome that the real call would have produced, short of a write failure,
+ * which nothing detects without attempting the write.
+ *
+ * @example
+ * reconcileFile('.config/tool.config.ts', template, { conflictPolicy: 'replace' });
+ * // { filePath: '.config/tool.config.ts', outcome: 'overwritten' }
+ *
+ * @category Filesystem
+ * @stage release
+ */
 export declare function reconcileFile(filePath: string, content: string, options?: ReconcileFileOptions): FileReconciliation;
 export type FileReconciliation = {
     filePath: string;
@@ -12,6 +33,7 @@ export type FileReconciliation = {
     error: string;
 };
 export interface ReconcileFileOptions {
+    /** What to do with an existing file whose content differs. Defaults to `'skip'`, which never destroys one. */
     conflictPolicy?: 'replace' | 'skip' | undefined;
     isDryRun?: boolean | undefined;
 }

package/dist/esm/4-release/reconcileFileFromFile.d.ts

@@ -1,2 +1,23 @@
 import { type FileReconciliation, type ReconcileFileOptions } from './reconcileFile.js';
+/**
+ * Reconciles `filePath` against the utf8 text of `sourcePath`, reporting what the write took rather than throwing.
+ *
+ * Everything past the read is `reconcileFile`: The comparison, the conflict policy, the created parent directories,
+ * and the outcome vocabulary are its. A source that cannot be read reports `failed`, and a missing source is not
+ * distinguished from an unreadable one. The reason names `sourcePath` and the cause; the path is interpolated
+ * because a read-stage failure carries none of its own (`EISDIR: illegal operation on a directory, read`) and the
+ * result's `filePath` is the destination.
+ *
+ * The source is read even under `isDryRun`, because the outcome depends on comparing its content, so a dry run can
+ * report `failed` where `reconcileFile` cannot. It still writes nothing.
+ *
+ * The read is utf8 text, so a binary source is not supported.
+ *
+ * @example
+ * reconcileFileFromFile('.config/git-cliff.toml', bundledTemplatePath);
+ * // { filePath: '.config/git-cliff.toml', outcome: 'created' }
+ *
+ * @category Filesystem
+ * @stage release
+ */
 export declare function reconcileFileFromFile(filePath: string, sourcePath: string, options?: ReconcileFileOptions): FileReconciliation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Filesystem utilities",
   "keywords": [
     "config-cascade",
@@ -44,7 +44,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@williamthorsen/toolbelt.errors": "0.6.2"
+    "@williamthorsen/toolbelt.errors": "0.7.0"
   },
   "engines": {
     "node": ">=24.0.0"