@theholocron/fs-utils 1.9.2 → 1.11.0

package/README.md

@@ -11,7 +11,11 @@ pnpm add @theholocron/fs-utils
 ## Usage
 
 ```typescript
-import { findUpward, hasGitEntry } from "@theholocron/fs-utils";
+import { findExecutable, findExecutableSync, 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,51 @@ 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 });
+```
+
+### `findExecutable(bin, options?)` / `findExecutableSync(...)`
+
+The first runnable file named `bin` on `options.path` (default `process.env.PATH`),
+or `undefined` — a `which`. Directories and files without the exec bit don't
+count. `bin` must be a bare command name (an empty string, `.`, `..` or anything
+with a path separator throws a `TypeError`), as does any filesystem error other
+than "not there" / "not permitted".
+
+- `options.path` — directories to search, delimited like `PATH` on the target
+  platform (`:` on POSIX, `;` on Windows). Empty entries are skipped; relative
+  ones are resolved against the working directory when the call starts, so
+  results are always absolute.
+- `options.pathExt` / `options.platform` — on Windows there is no exec bit:
+  `bin` is tried with each `PATHEXT` extension (default `.COM;.EXE;.BAT;.CMD`)
+  unless it already ends in one. An extension containing a path separator
+  throws a `TypeError`.
+
+```typescript
+// a project-local binary first, then the real PATH
+const tsc = findExecutableSync("tsc", { path: join(cwd, "node_modules", ".bin") }) ?? findExecutableSync("tsc");
+```
+
 ### `hasGitEntry(dir)`
 
 Returns `true` when `dir` has a `.git` entry — a directory in a normal

package/dist/index.d.mts

@@ -1,3 +1,69 @@
+//#region src/find-executable.d.ts
+export interface FindExecutableOptions {
+  /**
+   * Directories to search, delimited the way `PATH` is on `platform` (`:` on
+   * POSIX, `;` on Windows). Defaults to `process.env.PATH`. Empty entries are
+   * skipped rather than read as the working directory; relative ones are
+   * resolved against the working directory when the call starts.
+   */
+  path?: string;
+  /**
+   * Windows only: the extensions that make a file runnable, delimited with
+   * `;`. Defaults to `process.env.PATHEXT`, else `.COM;.EXE;.BAT;.CMD`. Each
+   * must be a bare extension — one with a path separator throws a `TypeError`,
+   * since it would otherwise reach outside the searched directory.
+   */
+  pathExt?: string;
+  /** Defaults to `process.platform`. Windows has no exec bit, so only the extension decides. */
+  platform?: NodeJS.Platform;
+}
+/**
+ * The first runnable file named `bin` in `options.path` (default
+ * `process.env.PATH`), as an absolute path, or `undefined`.
+ * Directories and files without the exec bit don't count.
+ *
+ * `bin` 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" / "not permitted".
+ */
+export declare function findExecutable(bin: string, options?: FindExecutableOptions): Promise<string | undefined>;
+/** Synchronous twin of {@link findExecutable}. */
+export declare function findExecutableSync(bin: string, options?: FindExecutableOptions): string | undefined;
+//#endregion
+//#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,77 @@
-import { stat } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+//#region src/find-executable.ts
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/** A bare command name, joined onto each search directory — never a path of its own. */
+function assertBare(bin) {
+	if (bin === "" || bin === "." || bin === ".." || /[\\/]/.test(bin) || bin.includes("\0")) throw new TypeError(`findExecutable: bin must be a bare command name, got ${JSON.stringify(bin)}`);
+}
+/**
+* Every file name `bin` could run as in one directory, in the order they are
+* tried. Computed once per call so the order can't shift mid-search if the
+* environment changes underneath an in-flight lookup.
+*/
+function namesFor(bin, options) {
+	if ((options.platform ?? process.platform) !== "win32") return [bin];
+	const exts = (options.pathExt ?? process.env["PATHEXT"] ?? DEFAULT_PATHEXT).split(";").filter(Boolean);
+	for (const ext of exts) if (/[\\/]/.test(ext) || ext.includes("\0")) throw new TypeError(`findExecutable: pathExt entries must not contain path separators, got ${JSON.stringify(ext)}`);
+	if (exts.some((ext) => bin.toLowerCase().endsWith(ext.toLowerCase()))) return [bin];
+	return exts.map((ext) => bin + ext);
+}
+/** The search directories, absolute, so a `chdir` during the awaits can't change what a relative entry means. */
+function dirsOf(options) {
+	const win = (options.platform ?? process.platform) === "win32";
+	return (options.path ?? process.env["PATH"] ?? "").split(win ? ";" : ":").filter(Boolean).map((dir) => resolve(dir));
+}
+/** Only "nothing there" or "not runnable" means this candidate isn't it; anything else is real. */
+const isMiss = (err) => {
+	const code = err?.code;
+	return code === "ENOENT" || code === "ENOTDIR" || code === "EACCES" || code === "EPERM";
+};
+/**
+* The first runnable file named `bin` in `options.path` (default
+* `process.env.PATH`), as an absolute path, or `undefined`.
+* Directories and files without the exec bit don't count.
+*
+* `bin` 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" / "not permitted".
+*/
+async function findExecutable(bin, options = {}) {
+	assertBare(bin);
+	const win = (options.platform ?? process.platform) === "win32";
+	const dirs = dirsOf(options);
+	const names = namesFor(bin, options);
+	for (const dir of dirs) for (const name of names) {
+		const candidate = join(dir, name);
+		try {
+			if (!(await stat(candidate)).isFile()) continue;
+			if (!win) await access(candidate, constants.X_OK);
+			return candidate;
+		} catch (err) {
+			if (!isMiss(err)) throw err;
+		}
+	}
+}
+/** Synchronous twin of {@link findExecutable}. */
+function findExecutableSync(bin, options = {}) {
+	assertBare(bin);
+	const win = (options.platform ?? process.platform) === "win32";
+	const dirs = dirsOf(options);
+	const names = namesFor(bin, options);
+	for (const dir of dirs) for (const name of names) {
+		const candidate = join(dir, name);
+		try {
+			if (!statSync(candidate).isFile()) continue;
+			if (!win) accessSync(candidate, constants.X_OK);
+			return candidate;
+		} catch (err) {
+			if (!isMiss(err)) throw err;
+		}
+	}
+}
+//#endregion
 //#region src/find-upward.ts
 /**
 * Walks upward from `startDir` — `startDir` itself first, then its parent,
@@ -42,4 +114,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 { findExecutable, findExecutableSync, findRoot, findRootSync, findUpward, hasGitEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/fs-utils",
-  "version": "1.9.2",
+  "version": "1.11.0",
   "description": "Walk a directory tree upward to find the nearest match or project root.",
   "keywords": [
     "filesystem",