@williamthorsen/toolbelt.filesystem 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.3.0 — 2026-08-08
+
+### Features
+
+- Migrate replaceFileExtension into filesystem package (#74)
+
+  Adds `replaceFileExtension` to the filesystem utilities. The function replaces the file extension in a file path; unlike analogous built-in functions, it supports multi-part extensions such as `.d.ts`.
+
+- Add directory-chain ascent and lookup exports (#102)
+
+  Adds three functions for upward directory search, which walk from a starting directory to either the filesystem root or a bounded ceiling, finding named files or directories at each level along the way:
+
+  - `listDirectoryChain` returns the directories alone
+  - `listDirectoryChainMatches` returns every level's match
+  - `findDirectoryChainMatch` finds only the nearest match
+
+  All three reject a path that falls outside the range they were asked to search. `findProjectRoot` now applies that same rule to its markers.
+
+- Add createTempTree with scope-bound disposal (#106)
+
+  Adds `createTempTree` to `@williamthorsen/toolbelt.filesystem/proposed`. The new function allows a caller to describe a directory tree as a plain object mapping paths to contents and receive a handle in return; the tree is removed when that handle goes out of scope.
+
+- 🚨 **Breaking:** Add findPackageRoot, getSelfVersion, and findProjectRoot to toolbelt.packaging (#107)
+
+  Adds a way for any module, whether it runs from a source tree or a compiled build, to identify the package that owns it and the version that package declares.
+
+  `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
+
+- Migrate Vitest configs to the nmr projects model (#73)
+
+  Packages no longer need to declare their own Vitest config. Test suites are now selected by a test file's name suffix rather than by choosing a config file: `*.app.test.ts` and `*.int.test.ts` route to the app and integration suites, and everything else runs as a unit test. Local development is now declared to require Node 24.16 or later.
+
+- Use identical compiler settings for all packages (#105)
+
+  All packages now have identical compiler settings, using the settings from the `@williamthorsen/tsconfig` base config without modification.
+
 ## 0.2.1 — 2026-07-27
 
 ### Tooling

package/README.md

@@ -2,7 +2,35 @@
 
 Filesystem utilities for TypeScript and JavaScript.
 
-<!-- section:release-notes --><!-- /section:release-notes -->
+<!-- section:release-notes -->
+## Release notes — v0.3.0 (2026-08-08)
+
+### Features
+
+- Migrate replaceFileExtension into filesystem package (#74)
+
+  Adds `replaceFileExtension` to the filesystem utilities. The function replaces the file extension in a file path; unlike analogous built-in functions, it supports multi-part extensions such as `.d.ts`.
+
+- Add directory-chain ascent and lookup exports (#102)
+
+  Adds three functions for upward directory search, which walk from a starting directory to either the filesystem root or a bounded ceiling, finding named files or directories at each level along the way:
+
+  - `listDirectoryChain` returns the directories alone
+  - `listDirectoryChainMatches` returns every level's match
+  - `findDirectoryChainMatch` finds only the nearest match
+
+  All three reject a path that falls outside the range they were asked to search. `findProjectRoot` now applies that same rule to its markers.
+
+- Add createTempTree with scope-bound disposal (#106)
+
+  Adds `createTempTree` to `@williamthorsen/toolbelt.filesystem/proposed`. The new function allows a caller to describe a directory tree as a plain object mapping paths to contents and receive a handle in return; the tree is removed when that handle goes out of scope.
+
+- 🚨 **Breaking:** Add findPackageRoot, getSelfVersion, and findProjectRoot to toolbelt.packaging (#107)
+
+  Adds a way for any module, whether it runs from a source tree or a compiled build, to identify the package that owns it and the version that package declares.
+
+  `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.
+<!-- /section:release-notes -->
 
 ## Installation
 
@@ -12,64 +40,110 @@ pnpm add @williamthorsen/toolbelt.filesystem
 
 ## Runtime requirements
 
-Both functions 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.
+`createTempTree`, `findDirectoryChainMatch`, `listDirectoryChainMatches`, and `loadConfigCascade` 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.
 
-## `findProjectRoot`
+## `listDirectoryChain`
 
 ```ts
-findProjectRoot(startDir: string, options?: { markers?: ReadonlyArray<string> }): ProjectRoot;
+listDirectoryChain(startDir: string, options?: { stopAtDir?: string }): [string, ...string[]];
 ```
 
-Resolves `startDir` to an absolute path, ascends from it, and returns the first directory carrying a root marker, along with the evidence that identified it:
+Resolves `startDir` to an absolute path and returns it followed by each of its ancestors, nearest first. It manipulates paths as strings and reads nothing from disk.
 
 ```ts
-interface ProjectRoot {
-  marker: string | null; // the marker that matched, or null when a fallback answered
-  rootDir: string;
-  source: 'marker' | 'package-json' | 'start-dir';
-}
+import { listDirectoryChain } from '@williamthorsen/toolbelt.filesystem';
+
+listDirectoryChain('/home/dev/app/src');
+// ['/home/dev/app/src', '/home/dev/app', '/home/dev', '/home', '/']
+
+listDirectoryChain('/home/dev/app/src', { stopAtDir: '/home/dev' });
+// ['/home/dev/app/src', '/home/dev/app', '/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:
+
+```ts
+const [nearestDir] = listDirectoryChain(process.cwd()); // string, not string | undefined
 ```
 
-`DEFAULT_ROOT_MARKERS` is consulted in order, so the earliest entry wins when one directory carries several:
+The ascent terminates at the filesystem root on every platform, so a Windows drive root or UNC share is as safe a starting point as a POSIX path.
+
+## `listDirectoryChainMatches`
+
+```ts
+listDirectoryChainMatches(
+  startDir: string,
+  names: ReadonlyArray<string>,
+  options?: { stopAtDir?: string },
+): DirectoryChainMatch[];
+```
 
-1. `.git`, matching either a directory (an ordinary clone) or a file (a worktree or submodule);
-2. `pnpm-workspace.yaml`;
-3. `pnpm-lock.yaml`;
-4. `package-lock.json`;
-5. `yarn.lock`;
-6. `bun.lock`.
+Returns, for each directory in the chain at or above `startDir`, the first of `names` that exists there:
 
-Passing `markers` replaces that list rather than extending it. Spread `DEFAULT_ROOT_MARKERS` to add to it:
+```ts
+interface DirectoryChainMatch {
+  dir: string; // the chain level, which differs from the entry's own directory for a nested name
+  entryName: string;
+  entryPath: string;
+}
+```
 
 ```ts
-import { DEFAULT_ROOT_MARKERS, findProjectRoot } from '@williamthorsen/toolbelt.filesystem';
+import { listDirectoryChainMatches } from '@williamthorsen/toolbelt.filesystem';
 
-findProjectRoot(process.cwd(), { markers: [...DEFAULT_ROOT_MARKERS, 'deno.json'] });
+listDirectoryChainMatches('/home/dev/app/src', ['.git'], { stopAtDir: '/home/dev' });
+// [{ dir: '/home/dev/app', entryName: '.git', entryPath: '/home/dev/app/.git' }]
 ```
 
-When no directory up to and including the filesystem root carries a marker, the result falls back in this order, reporting a `null` marker either way:
+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.
 
-1. the nearest ancestor holding a `package.json`, reported as `source: 'package-json'`;
-2. `startDir` itself, reported as `source: 'start-dir'`.
+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.
 
-The ascent terminates at the filesystem root on every platform, so a Windows drive root or UNC share is as safe a starting point as a POSIX path.
+`options` is forwarded to `listDirectoryChain`, so `stopAtDir` bounds the ascent the same way.
+
+Every level is probed, because every level's match is reported. Where only the nearest match matters, [`findDirectoryChainMatch`](#finddirectorychainmatch) returns it and stops there.
+
+## `findDirectoryChainMatch`
+
+```ts
+findDirectoryChainMatch(
+  startDir: string,
+  names: ReadonlyArray<string>,
+  options?: { stopAtDir?: string },
+): DirectoryChainMatch | undefined;
+```
+
+Returns the nearest directory at or above `startDir` holding one of `names`, or `undefined` when none does. It is `listDirectoryChainMatches` narrowed to the first hit, sharing its result shape, its options, and its name validation:
+
+```ts
+import { findDirectoryChainMatch } from '@williamthorsen/toolbelt.filesystem';
+
+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.
 
 ## `loadConfigCascade`
 
 ```ts
 loadConfigCascade<TConfig>(options: {
   fileNames: ReadonlyArray<string>;
-  markers?: ReadonlyArray<string>;
   shouldStopAscent?: (config: TConfig) => boolean;
   startDir: string;
+  stopAtDir: string;
 }): Promise<ConfigCascade<TConfig>>;
 ```
 
-Loads every config file between `startDir` and its project root, nearest first, and reads nothing above that root.
+Loads every config file between `startDir` and `stopAtDir`, nearest first, and reads nothing above that boundary.
 
-At each level from `startDir` up to and including the root, the first of `fileNames` that exists becomes that level's config; a level holding none contributes nothing. Each name is a path relative to the level, 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 file is read, since following it would breach the bound the cascade exists to enforce. The project root is resolved by `findProjectRoot`, and `markers` is forwarded to it.
+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.
+
+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 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:
 
@@ -80,8 +154,7 @@ interface ConfigCascade<TConfig> {
     dir: string; // the cascade level, which differs from the file's own directory for a nested file name
     filePath: string;
   }>;
-  projectRoot: ProjectRoot;
-  stopReason: 'predicate' | 'project-root';
+  stopReason: 'predicate' | 'stop-dir';
 }
 ```
 
@@ -93,17 +166,91 @@ The predicate is the caller's whole stop policy, so any field can drive it. By c
 
 ```ts
 import { loadConfigCascade } from '@williamthorsen/toolbelt.filesystem';
+import { findProjectRoot } from '@williamthorsen/toolbelt.packaging';
 
 interface StackConfig {
   rules?: Record<string, string>;
   shouldStopAscent?: boolean;
 }
 
-const { entries, projectRoot, stopReason } = await loadConfigCascade<StackConfig>({
+const { rootDir } = findProjectRoot(process.cwd());
+
+const { entries, stopReason } = await loadConfigCascade<StackConfig>({
   fileNames: ['stack.config.mjs', 'stack.config.js'],
   shouldStopAscent: (config) => config.shouldStopAscent === true,
   startDir: process.cwd(),
+  stopAtDir: rootDir,
 });
 ```
 
-`projectRoot` and `stopReason` are provenance for the caller to surface, so a user can see which directory bounded the cascade and what ended it.
+`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.
+
+## `createTempTree`
+
+Proposed tier: imported from `@williamthorsen/toolbelt.filesystem/proposed` rather than the package root, and subject to change.
+
+```ts
+createTempTree(entries: Record<string, 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/proposed';
+
+{
+  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.
+
+```ts
+interface TempTree extends Disposable {
+  readonly dir: string;
+  resolve(...segments: string[]): 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.
+
+Disposal is idempotent.
+
+`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.
+
+```ts
+replaceFileExtension(filePath: string, newExtension: string, options?: { oldExtension?: string }): string;
+```
+
+Returns `filePath` with its extension replaced. It manipulates the string alone and touches no filesystem.
+
+```ts
+import { replaceFileExtension } from '@williamthorsen/toolbelt.filesystem/proposed';
+
+replaceFileExtension('src/main.ts', '.js'); // 'src/main.js'
+replaceFileExtension('src/main.ts', 'js'); // 'src/main.js' -- the leading period is optional
+replaceFileExtension('src/main.ts', ''); // 'src/main' -- an empty replacement removes the extension
+```
+
+The extension being replaced defaults to whatever `path.extname` reports, which is the substring from the final period in the file name. That is wrong for a multi-part extension: `path.extname('src/main.d.ts')` returns `.ts`, so the default would yield `src/main.d.js`. Declare the whole extension through `oldExtension` to replace it entire:
+
+```ts
+replaceFileExtension('src/main.d.ts', '.js', { oldExtension: '.d.ts' }); // 'src/main.js'
+```
+
+Which extension is meant is genuinely ambiguous, since `archive.tar.gz` could reasonably end in `.gz` or in `.tar.gz`, so the caller declares it rather than the function guessing.
+
+Two inputs throw rather than returning a path that would quietly be wrong: a `filePath` ending in a separator, which names a directory rather than a file, and a `filePath` that does not end with a declared `oldExtension`.

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

@@ -0,0 +1,5 @@
+export declare function createTempTree(entries: Record<string, string>): TempTree;
+export interface TempTree extends Disposable {
+    readonly dir: string;
+    resolve(...segments: string[]): string;
+}

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

@@ -0,0 +1,38 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function createTempTree(entries) {
+    const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'toolbelt-')));
+    try {
+        for (const [entry, contents] of Object.entries(entries)) {
+            const entryPath = resolveWithinTree(dir, [entry]);
+            if (entry.endsWith('/')) {
+                fs.mkdirSync(entryPath, { recursive: true });
+            }
+            else {
+                fs.mkdirSync(path.dirname(entryPath), { recursive: true });
+                fs.writeFileSync(entryPath, contents);
+            }
+        }
+    }
+    catch (error) {
+        fs.rmSync(dir, { force: true, recursive: true });
+        throw error;
+    }
+    return {
+        dir,
+        resolve(...segments) {
+            return resolveWithinTree(dir, segments);
+        },
+        [Symbol.dispose]() {
+            fs.rmSync(dir, { force: true, recursive: true });
+        },
+    };
+}
+function resolveWithinTree(dir, segments) {
+    const target = path.resolve(dir, ...segments);
+    if (target !== dir && !target.startsWith(dir + path.sep)) {
+        throw new Error(`Path "${target}" falls outside the temporary tree at "${dir}"`);
+    }
+    return target;
+}

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

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

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

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

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

@@ -0,0 +1,4 @@
+export declare function replaceFileExtension(filePath: string, newExtension: string, options?: ReplaceFileExtensionOptions): string;
+export interface ReplaceFileExtensionOptions {
+    oldExtension?: string | undefined;
+}

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

@@ -0,0 +1,23 @@
+import path from 'node:path';
+export function replaceFileExtension(filePath, newExtension, options = {}) {
+    if (endsWithSeparator(filePath)) {
+        throw new Error(`File path "${filePath}" ends with a path separator, so it names a directory`);
+    }
+    const oldExtension = toDotPrefixed(options.oldExtension ?? path.extname(filePath));
+    const replacement = toDotPrefixed(newExtension);
+    if (oldExtension === '') {
+        return `${filePath}${replacement}`;
+    }
+    if (!filePath.endsWith(oldExtension)) {
+        throw new Error(`File path "${filePath}" does not end with extension "${oldExtension}"`);
+    }
+    return filePath.slice(0, -oldExtension.length) + replacement;
+}
+function endsWithSeparator(filePath) {
+    return filePath.endsWith('/') || filePath.endsWith(path.sep);
+}
+function toDotPrefixed(extension) {
+    if (extension === '' || extension.startsWith('.'))
+        return extension;
+    return `.${extension}`;
+}

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

@@ -0,0 +1,9 @@
+import { type ListDirectoryChainOptions } from './listDirectoryChain.js';
+export interface DirectoryChainMatch {
+    dir: string;
+    entryName: string;
+    entryPath: string;
+}
+export type DirectoryChainMatchOptions = ListDirectoryChainOptions;
+export declare function findDirectoryChainMatch(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch | undefined;
+export declare function listDirectoryChainMatches(startDir: string, names: ReadonlyArray<string>, options?: DirectoryChainMatchOptions): DirectoryChainMatch[];

package/dist/esm/4-release/directory-chain-matches.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { listDirectoryChain } from "./listDirectoryChain.js";
+export function findDirectoryChainMatch(startDir, names, options = {}) {
+    assertLevelRelativeNames(names);
+    for (const dir of listDirectoryChain(startDir, options)) {
+        const entryName = findMatchingName(dir, names);
+        if (entryName !== undefined) {
+            return { dir, entryName, entryPath: path.join(dir, entryName) };
+        }
+    }
+    return undefined;
+}
+export function listDirectoryChainMatches(startDir, names, options = {}) {
+    assertLevelRelativeNames(names);
+    const matches = [];
+    for (const dir of listDirectoryChain(startDir, options)) {
+        const entryName = findMatchingName(dir, names);
+        if (entryName !== undefined) {
+            matches.push({ dir, entryName, entryPath: path.join(dir, entryName) });
+        }
+    }
+    return matches;
+}
+function assertLevelRelativeNames(names) {
+    for (const name of names) {
+        if (path.isAbsolute(name)) {
+            throw new Error(`Entry name must be relative to its directory level: ${name}`);
+        }
+        const normalized = path.normalize(name);
+        if (normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
+            throw new Error(`Entry name must not ascend above its directory level: ${name}`);
+        }
+    }
+}
+function findMatchingName(dir, names) {
+    for (const name of names) {
+        if (fs.existsSync(path.join(dir, name))) {
+            return name;
+        }
+    }
+    return undefined;
+}

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

@@ -1,2 +1,3 @@
-export { DEFAULT_ROOT_MARKERS, findProjectRoot, type FindProjectRootOptions, type ProjectRoot, type ProjectRootSource, } from './findProjectRoot.js';
+export { type DirectoryChainMatch, type DirectoryChainMatchOptions, findDirectoryChainMatch, listDirectoryChainMatches, } from './directory-chain-matches.js';
+export { listDirectoryChain, type ListDirectoryChainOptions } from './listDirectoryChain.js';
 export { type CascadeStopReason, type ConfigCascade, type ConfigEntry, loadConfigCascade, type LoadConfigCascadeOptions, } from './loadConfigCascade.js';

package/dist/esm/4-release/index.js

@@ -1,2 +1,3 @@
-export { DEFAULT_ROOT_MARKERS, findProjectRoot, } from "./findProjectRoot.js";
+export { findDirectoryChainMatch, listDirectoryChainMatches, } from "./directory-chain-matches.js";
+export { listDirectoryChain } from "./listDirectoryChain.js";
 export { loadConfigCascade, } from "./loadConfigCascade.js";

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

@@ -0,0 +1,4 @@
+export declare function listDirectoryChain(startDir: string, options?: ListDirectoryChainOptions): [string, ...string[]];
+export interface ListDirectoryChainOptions {
+    stopAtDir?: string | undefined;
+}

package/dist/esm/4-release/listDirectoryChain.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+export function listDirectoryChain(startDir, options = {}) {
+    const { stopAtDir } = options;
+    const resolvedStartDir = path.resolve(startDir);
+    const resolvedStopAtDir = stopAtDir === undefined ? undefined : path.resolve(stopAtDir);
+    const chain = [resolvedStartDir];
+    let dir = resolvedStartDir;
+    let hasReachedStopAtDir = dir === resolvedStopAtDir;
+    while (!hasReachedStopAtDir) {
+        const parentDir = path.dirname(dir);
+        if (parentDir === dir)
+            break;
+        chain.push(parentDir);
+        dir = parentDir;
+        hasReachedStopAtDir = dir === resolvedStopAtDir;
+    }
+    if (resolvedStopAtDir !== undefined && !hasReachedStopAtDir) {
+        throw new Error('Stop directory must be the start directory or one of its ancestors: ' +
+            `stopAtDir=${resolvedStopAtDir}, startDir=${resolvedStartDir}`);
+    }
+    return chain;
+}

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

@@ -1,9 +1,7 @@
-import { type ProjectRoot } from './findProjectRoot.js';
 export declare function loadConfigCascade<TConfig = unknown>(options: LoadConfigCascadeOptions<TConfig>): Promise<ConfigCascade<TConfig>>;
-export type CascadeStopReason = 'predicate' | 'project-root';
+export type CascadeStopReason = 'predicate' | 'stop-dir';
 export interface ConfigCascade<TConfig> {
     entries: ConfigEntry<TConfig>[];
-    projectRoot: ProjectRoot;
     stopReason: CascadeStopReason;
 }
 export interface ConfigEntry<TConfig> {
@@ -13,7 +11,7 @@ export interface ConfigEntry<TConfig> {
 }
 export interface LoadConfigCascadeOptions<TConfig> {
     fileNames: ReadonlyArray<string>;
-    markers?: ReadonlyArray<string> | undefined;
     shouldStopAscent?: ((config: TConfig) => boolean) | undefined;
     startDir: string;
+    stopAtDir: string;
 }

package/dist/esm/4-release/loadConfigCascade.js

@@ -6,56 +6,22 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import fs from 'node:fs';
-import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { findProjectRoot } from "./findProjectRoot.js";
+import { listDirectoryChainMatches } from "./directory-chain-matches.js";
 export async function loadConfigCascade(options) {
-    const { fileNames, markers, shouldStopAscent, startDir } = options;
-    assertLevelRelativeFileNames(fileNames);
-    const projectRoot = findProjectRoot(startDir, { markers });
-    const candidates = collectCandidates(path.resolve(startDir), projectRoot.rootDir, fileNames);
+    const { fileNames, shouldStopAscent, startDir, stopAtDir } = options;
+    const matches = listDirectoryChainMatches(startDir, fileNames, { stopAtDir });
     const entries = [];
-    let stopReason = 'project-root';
-    for (const { dir, filePath } of candidates) {
-        const config = await importDefaultExport(filePath);
-        entries.push({ config, dir, filePath });
+    let stopReason = 'stop-dir';
+    for (const { dir, entryPath } of matches) {
+        const config = await importDefaultExport(entryPath);
+        entries.push({ config, dir, filePath: entryPath });
         if (shouldStopAscent?.(config) === true) {
             stopReason = 'predicate';
             break;
         }
     }
-    return { entries, projectRoot, stopReason };
-}
-function assertLevelRelativeFileNames(fileNames) {
-    for (const fileName of fileNames) {
-        if (path.isAbsolute(fileName)) {
-            throw new Error(`Config file name must be relative to its directory level: ${fileName}`);
-        }
-        const normalized = path.normalize(fileName);
-        if (normalized === '..' || normalized.startsWith(`..${path.sep}`)) {
-            throw new Error(`Config file name must not ascend above its directory level: ${fileName}`);
-        }
-    }
-}
-function collectCandidates(startDir, rootDir, fileNames) {
-    const candidates = [];
-    let dir = startDir;
-    let previousDir = '';
-    while (dir !== previousDir) {
-        for (const fileName of fileNames) {
-            const filePath = path.join(dir, fileName);
-            if (fs.existsSync(filePath)) {
-                candidates.push({ dir, filePath });
-                break;
-            }
-        }
-        if (dir === rootDir)
-            break;
-        previousDir = dir;
-        dir = path.dirname(dir);
-    }
-    return candidates;
+    return { entries, stopReason };
 }
 async function importDefaultExport(filePath) {
     const configModule = await import(__rewriteRelativeImportExtension(pathToFileURL(filePath).href));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Filesystem utilities",
   "keywords": [],
   "homepage": "https://github.com/williamthorsen/toolbelt/tree/main/packages/filesystem#readme",

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

@@ -1,11 +0,0 @@
-export declare const DEFAULT_ROOT_MARKERS: ReadonlyArray<string>;
-export declare function findProjectRoot(startDir: string, options?: FindProjectRootOptions): ProjectRoot;
-export interface FindProjectRootOptions {
-    markers?: ReadonlyArray<string> | undefined;
-}
-export interface ProjectRoot {
-    marker: string | null;
-    rootDir: string;
-    source: ProjectRootSource;
-}
-export type ProjectRootSource = 'marker' | 'package-json' | 'start-dir';

package/dist/esm/4-release/findProjectRoot.js

@@ -1,33 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-export const DEFAULT_ROOT_MARKERS = [
-    '.git',
-    'pnpm-workspace.yaml',
-    'pnpm-lock.yaml',
-    'package-lock.json',
-    'yarn.lock',
-    'bun.lock',
-];
-export function findProjectRoot(startDir, options = {}) {
-    const { markers = DEFAULT_ROOT_MARKERS } = options;
-    const resolvedStartDir = path.resolve(startDir);
-    let nearestPackageJsonDir;
-    let dir = resolvedStartDir;
-    let previousDir = '';
-    while (dir !== previousDir) {
-        for (const marker of markers) {
-            if (fs.existsSync(path.join(dir, marker))) {
-                return { marker, rootDir: dir, source: 'marker' };
-            }
-        }
-        if (nearestPackageJsonDir === undefined && fs.existsSync(path.join(dir, 'package.json'))) {
-            nearestPackageJsonDir = dir;
-        }
-        previousDir = dir;
-        dir = path.dirname(dir);
-    }
-    if (nearestPackageJsonDir !== undefined) {
-        return { marker: null, rootDir: nearestPackageJsonDir, source: 'package-json' };
-    }
-    return { marker: null, rootDir: resolvedStartDir, source: 'start-dir' };
-}