@theholocron/fs-utils 1.8.3 → 1.10.0

package/README.md

@@ -11,7 +11,11 @@ pnpm add @theholocron/fs-utils
 ## Usage
 
 ```typescript
-import { findUpward, hasGitEntry } from "@theholocron/fs-utils";
+import { findRoot, findUpward, hasGitEntry } from "@theholocron/fs-utils";
+
+// nearest ancestor holding a marker file or directory
+const repoRoot = await findRoot(process.cwd(), ".git");
+const monorepoRoot = await findRoot(process.cwd(), ["pnpm-workspace.yaml", "turbo.json"]);
 
 // find the nearest ancestor holding a config file, stopping at the repo root
 const configDir = await findUpward(
@@ -35,6 +39,29 @@ with no result, instead of continuing to the parent. Without `stop`,
 walks all the way to the filesystem root. Always terminates: directory
 nesting is finite.
 
+### `findRoot(startDir, marker, options?)` / `findRootSync(...)`
+
+The nearest ancestor of `startDir` — itself first — that contains `marker`: a
+file or directory name, or a list of names where any one counts. Resolves to
+`undefined` when nothing is found. `findRootSync` is the synchronous twin.
+Each marker must be a bare name — an empty string, `.`, `..` or anything with a
+path separator throws a `TypeError`, as does any filesystem error other than
+"not there" (e.g. `EACCES`). A relative `startDir` is resolved against the
+working directory up front, so results are always absolute.
+
+- `options.fallback: "start"` — return the start directory instead of
+  `undefined` when nothing is found (a soft-skip for callers that treat the
+  start dir as the root anyway; always absolute).
+- `options.realpath: true` — resolve symlinks of `startDir` before
+  walking, so a symlinked start walks the physical tree instead of the link's
+  own ancestors. A start path that doesn't exist
+  counts as not found.
+
+```typescript
+// a git root that never throws and never returns undefined
+const root = findRootSync(cwd, ".git", { fallback: "start", realpath: true });
+```
+
 ### `hasGitEntry(dir)`
 
 Returns `true` when `dir` has a `.git` entry — a directory in a normal

package/dist/index.d.mts

@@ -1,3 +1,37 @@
+//#region src/find-root.d.ts
+export interface FindRootOptions {
+  /**
+   * `"start"` returns the start directory instead of `undefined` when no
+   * marker is found anywhere up the tree — a soft-skip for callers that
+   * treat the start dir as the root anyway. The returned path is always
+   * absolute (a relative `startDir` is resolved against the working
+   * directory), and symlink-resolved when `realpath` is on and the start
+   * exists.
+   */
+  fallback?: "start";
+  /**
+   * Resolve symlinks of `startDir` before walking, so a symlinked start
+   * dir walks the physical tree instead of the link's own lexical
+   * ancestors. A start path that doesn't exist on disk counts as "not
+   * found". Any other failure resolving it (e.g. `EACCES`) is thrown.
+   */
+  realpath?: boolean;
+}
+/**
+ * The nearest ancestor of `startDir` (itself first) that contains `marker` —
+ * a file or directory name, or a list of names where any one counts. For
+ * example `".git"`, `"pnpm-workspace.yaml"`, or `["turbo.json", "nx.json"]`.
+ *
+ * Each marker must be a bare name (no separators, `.`, `..` or empty) or a
+ * `TypeError` is thrown; so is any filesystem error other than "not there".
+ * Resolves to `undefined` when nothing is found, unless `options.fallback` is
+ * `"start"`. See {@link FindRootOptions}; {@link findRootSync} is the
+ * synchronous twin. Built on {@link findUpward}.
+ */
+export declare function findRoot(startDir: string, marker: string | readonly string[], options?: FindRootOptions): Promise<string | undefined>;
+/** Synchronous {@link findRoot}. */
+export declare function findRootSync(startDir: string, marker: string | readonly string[], options?: FindRootOptions): string | undefined;
+//#endregion
 //#region src/find-upward.d.ts
 /**
  * Walks upward from `startDir` — `startDir` itself first, then its parent,

package/dist/index.mjs

@@ -1,5 +1,6 @@
-import { stat } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { realpathSync, statSync } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
 //#region src/find-upward.ts
 /**
 * Walks upward from `startDir` — `startDir` itself first, then its parent,
@@ -42,4 +43,80 @@ async function hasGitEntry(dir) {
 	}
 }
 //#endregion
-export { findUpward, hasGitEntry };
+//#region src/find-root.ts
+/** Only "nothing there" means the marker is absent; every other fs error is real. */
+const isAbsent = (err) => {
+	const code = err?.code;
+	return code === "ENOENT" || code === "ENOTDIR";
+};
+/**
+* Markers are bare names, joined onto each ancestor. Anything that could
+* address a path outside that ancestor (`..`, a separator) or the ancestor
+* itself (`""`, `.`) is rejected rather than probed.
+*/
+function asMarkers(marker) {
+	const list = typeof marker === "string" ? [marker] : marker;
+	if (list.length === 0) throw new TypeError("findRoot: at least one marker is required");
+	for (const m of list) if (m === "" || m === "." || m === ".." || /[\\/]/.test(m) || m.includes("\0")) throw new TypeError(`findRoot: marker must be a single file or directory name, got ${JSON.stringify(m)}`);
+	return list;
+}
+async function hasAny(dir, markers) {
+	for (const marker of markers) try {
+		await stat(join(dir, marker));
+		return true;
+	} catch (err) {
+		if (!isAbsent(err)) throw err;
+	}
+	return false;
+}
+function hasAnySync(dir, markers) {
+	for (const marker of markers) try {
+		statSync(join(dir, marker));
+		return true;
+	} catch (err) {
+		if (!isAbsent(err)) throw err;
+	}
+	return false;
+}
+/**
+* The nearest ancestor of `startDir` (itself first) that contains `marker` —
+* a file or directory name, or a list of names where any one counts. For
+* example `".git"`, `"pnpm-workspace.yaml"`, or `["turbo.json", "nx.json"]`.
+*
+* Each marker must be a bare name (no separators, `.`, `..` or empty) or a
+* `TypeError` is thrown; so is any filesystem error other than "not there".
+* Resolves to `undefined` when nothing is found, unless `options.fallback` is
+* `"start"`. See {@link FindRootOptions}; {@link findRootSync} is the
+* synchronous twin. Built on {@link findUpward}.
+*/
+async function findRoot(startDir, marker, options = {}) {
+	const markers = asMarkers(marker);
+	let start = resolve(startDir);
+	if (options.realpath) try {
+		start = await realpath(start);
+	} catch (err) {
+		if (!isAbsent(err)) throw err;
+		return options.fallback === "start" ? start : void 0;
+	}
+	return await findUpward(start, async (dir) => await hasAny(dir, markers) ? dir : void 0) ?? (options.fallback === "start" ? start : void 0);
+}
+/** Synchronous {@link findRoot}. */
+function findRootSync(startDir, marker, options = {}) {
+	const markers = asMarkers(marker);
+	let start = resolve(startDir);
+	if (options.realpath) try {
+		start = realpathSync(start);
+	} catch (err) {
+		if (!isAbsent(err)) throw err;
+		return options.fallback === "start" ? start : void 0;
+	}
+	let dir = start;
+	for (;;) {
+		if (hasAnySync(dir, markers)) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return options.fallback === "start" ? start : void 0;
+		dir = parent;
+	}
+}
+//#endregion
+export { findRoot, findRootSync, findUpward, hasGitEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/fs-utils",
-  "version": "1.8.3",
+  "version": "1.10.0",
   "description": "Walk a directory tree upward to find the nearest match or project root.",
   "keywords": [
     "filesystem",
@@ -31,7 +31,7 @@
     "dist"
   ],
   "devDependencies": {
-    "@theholocron/cli": "5.0.0-alpha.3",
+    "@theholocron/cli": "5.0.0-alpha.114",
     "@theholocron/tsdown-config": "^8.2.0",
     "@theholocron/vitest-config": "^8.2.0",
     "@tsconfig/node-lts": "^24.0.1",