@williamthorsen/toolbelt.filesystem 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.2.0 — 2026-07-24
+
+### Features
+
+- Add the filesystem package with bounded cascading config discovery (#71)
+
+  Adds a new package, `@williamthorsen/toolbelt.filesystem`, and its first functions: `findProjectRoot`, which locates a project's root directory, and `loadConfigCascade`, which loads the configuration files layered across the directories between a starting point and that root.
+
+<!-- Generated by release-kit. Do not edit this file. Use .meta/changelog-overrides.json to override entries. -->

package/LICENSE

@@ -0,0 +1,7 @@
+UNLICENSED SOFTWARE
+
+Copyright (c) 2026 William Thorsen
+
+All rights reserved.
+
+This software is provided 'as-is', without any express or implied warranty. No rights are granted to use, copy, modify, or distribute this software for any purpose. For full legal details, consult a legal expert. This notice may not be removed or altered from any distribution.

package/README.md

@@ -1 +1,117 @@
-Placeholder for `@williamthorsen/toolbelt.filesystem` — awaiting first release.
+# @williamthorsen/toolbelt.filesystem
+
+Filesystem utilities for TypeScript and JavaScript.
+
+<!-- section:release-notes -->
+## Release notes — v0.2.0 (2026-07-24)
+
+### Features
+
+- Add the filesystem package with bounded cascading config discovery (#71)
+
+  Adds a new package, `@williamthorsen/toolbelt.filesystem`, and its first functions: `findProjectRoot`, which locates a project's root directory, and `loadConfigCascade`, which loads the configuration files layered across the directories between a starting point and that root.
+<!-- /section:release-notes -->
+
+## Installation
+
+```sh
+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.
+
+`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`
+
+```ts
+findProjectRoot(startDir: string, options?: { markers?: ReadonlyArray<string> }): ProjectRoot;
+```
+
+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:
+
+```ts
+interface ProjectRoot {
+  marker: string | null; // the marker that matched, or null when a fallback answered
+  rootDir: string;
+  source: 'marker' | 'package-json' | 'start-dir';
+}
+```
+
+`DEFAULT_ROOT_MARKERS` is consulted in order, so the earliest entry wins when one directory carries several:
+
+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`.
+
+Passing `markers` replaces that list rather than extending it. Spread `DEFAULT_ROOT_MARKERS` to add to it:
+
+```ts
+import { DEFAULT_ROOT_MARKERS, findProjectRoot } from '@williamthorsen/toolbelt.filesystem';
+
+findProjectRoot(process.cwd(), { markers: [...DEFAULT_ROOT_MARKERS, 'deno.json'] });
+```
+
+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:
+
+1. the nearest ancestor holding a `package.json`, reported as `source: 'package-json'`;
+2. `startDir` itself, reported as `source: 'start-dir'`.
+
+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.
+
+## `loadConfigCascade`
+
+```ts
+loadConfigCascade<TConfig>(options: {
+  fileNames: ReadonlyArray<string>;
+  markers?: ReadonlyArray<string>;
+  shouldStopAscent?: (config: TConfig) => boolean;
+  startDir: string;
+}): Promise<ConfigCascade<TConfig>>;
+```
+
+Loads every config file between `startDir` and its project root, nearest first, and reads nothing above that root.
+
+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.
+
+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:
+
+```ts
+interface ConfigCascade<TConfig> {
+  entries: Array<{
+    config: 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';
+}
+```
+
+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.
+
+### The `shouldStopAscent` convention
+
+The predicate is the caller's whole stop policy, so any field can drive it. By convention a config declares a boolean `shouldStopAscent`, which a consumer reads directly:
+
+```ts
+import { loadConfigCascade } from '@williamthorsen/toolbelt.filesystem';
+
+interface StackConfig {
+  rules?: Record<string, string>;
+  shouldStopAscent?: boolean;
+}
+
+const { entries, projectRoot, stopReason } = await loadConfigCascade<StackConfig>({
+  fileNames: ['stack.config.mjs', 'stack.config.js'],
+  shouldStopAscent: (config) => config.shouldStopAscent === true,
+  startDir: process.cwd(),
+});
+```
+
+`projectRoot` and `stopReason` are provenance for the caller to surface, so a user can see which directory bounded the cascade and what ended it.

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

package/dist/esm/2-draft/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/2-draft/index.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +1,33 @@
+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' };
+}

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

@@ -0,0 +1,2 @@
+export { DEFAULT_ROOT_MARKERS, findProjectRoot, type FindProjectRootOptions, type ProjectRoot, type ProjectRootSource, } from './findProjectRoot.js';
+export { type CascadeStopReason, type ConfigCascade, type ConfigEntry, loadConfigCascade, type LoadConfigCascadeOptions, } from './loadConfigCascade.js';

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

@@ -0,0 +1,2 @@
+export { DEFAULT_ROOT_MARKERS, findProjectRoot, } from "./findProjectRoot.js";
+export { loadConfigCascade, } from "./loadConfigCascade.js";

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

@@ -0,0 +1,19 @@
+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 interface ConfigCascade<TConfig> {
+    entries: ConfigEntry<TConfig>[];
+    projectRoot: ProjectRoot;
+    stopReason: CascadeStopReason;
+}
+export interface ConfigEntry<TConfig> {
+    config: TConfig;
+    dir: string;
+    filePath: string;
+}
+export interface LoadConfigCascadeOptions<TConfig> {
+    fileNames: ReadonlyArray<string>;
+    markers?: ReadonlyArray<string> | undefined;
+    shouldStopAscent?: ((config: TConfig) => boolean) | undefined;
+    startDir: string;
+}

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

@@ -0,0 +1,66 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { findProjectRoot } from "./findProjectRoot.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 entries = [];
+    let stopReason = 'project-root';
+    for (const { dir, filePath } of candidates) {
+        const config = await importDefaultExport(filePath);
+        entries.push({ config, dir, filePath });
+        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;
+}
+async function importDefaultExport(filePath) {
+    const configModule = await import(__rewriteRelativeImportExtension(pathToFileURL(filePath).href));
+    if (!('default' in configModule)) {
+        throw new Error(`Config file has no default export: ${filePath}`);
+    }
+    return configModule.default;
+}

package/package.json

@@ -1,4 +1,44 @@
 {
   "name": "@williamthorsen/toolbelt.filesystem",
-  "version": "0.0.0"
-}
+  "version": "0.2.0",
+  "description": "Filesystem utilities",
+  "keywords": [],
+  "homepage": "https://github.com/williamthorsen/toolbelt/tree/main/packages/filesystem#readme",
+  "bugs": {
+    "url": "https://github.com/williamthorsen/toolbelt/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/williamthorsen/toolbelt.git",
+    "directory": "packages/filesystem"
+  },
+  "license": "UNLICENSED",
+  "author": "William Thorsen <william@thorsen.dev> (https://github.com/williamthorsen)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/4-release/index.js"
+    },
+    "./candidate": {
+      "import": "./dist/esm/3-candidate/index.js"
+    },
+    "./draft": {
+      "import": "./dist/esm/2-draft/index.js"
+    },
+    "./proposed": {
+      "import": "./dist/esm/1-proposed/index.js"
+    }
+  },
+  "files": [
+    "dist/*",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {}
+}