@theholocron/fs-utils 1.12.0 → 1.13.0

package/README.md

@@ -11,7 +11,14 @@ pnpm add @theholocron/fs-utils
 ## Usage
 
 ```typescript
-import { findExecutable, findExecutableSync, findRoot, findUpward, hasGitEntry } from "@theholocron/fs-utils";
+import {
+  findExecutable,
+  findExecutableSync,
+  findRoot,
+  findUpward,
+  hasGitEntry,
+  walkFilesSync,
+} from "@theholocron/fs-utils";
 
 // nearest ancestor holding a marker file or directory
 const repoRoot = await findRoot(process.cwd(), ".git");
@@ -84,6 +91,21 @@ than "not there" / "not permitted".
 const tsc = findExecutableSync("tsc", { path: join(cwd, "node_modules", ".bin") }) ?? findExecutableSync("tsc");
 ```
 
+### `walkFilesSync(dir, options?)`
+
+Every regular file under `dir`, as absolute paths in a stable (name-sorted,
+depth-first) order. `options.skip` names the directories not entered, at any
+depth (default `.git` and `node_modules`; it replaces the default); a _file_
+with that name is still listed. Symlinks found while walking are neither
+followed nor listed, so a link back up the tree can't loop; `dir` itself is
+followed if it is a symlink. A subdirectory that can't be read is skipped; `dir`
+itself must be readable — its error propagates. The tree is assumed not to
+change mid-walk.
+
+```typescript
+const sources = walkFilesSync(repoRoot, { skip: [".git", "node_modules", "dist"] });
+```
+
 ### `hasGitEntry(dir)`
 
 Returns `true` when `dir` has a `.git` entry — a directory in a normal

package/dist/index.d.mts

@@ -88,4 +88,22 @@ export declare function findUpward<T>(startDir: string, check: (dir: string) =>
  * nearest `.git` as the project root, searched but not walked past.
  */
 export declare function hasGitEntry(dir: string): Promise<boolean>;
+//#endregion
+//#region src/walk-files.d.ts
+export interface WalkFilesOptions {
+  /** Directory names not descended into, at any depth (files with these names are still listed). Defaults to `.git` and `node_modules`. */
+  skip?: Iterable<string>;
+}
+/**
+ * Every regular file under `dir`, as absolute paths in a stable (name-sorted,
+ * depth-first) order. Directories named in `options.skip` are not entered.
+ *
+ * Symlinks found while walking are neither followed nor listed, so a link back
+ * up the tree can't loop; `dir` itself is the caller's choice and is followed
+ * if it is a symlink. A subdirectory that can't be read is skipped; `dir`
+ * itself must be readable — its error propagates, since a typo'd root is a bug
+ * to surface, not an empty result. The tree is assumed not to change while it
+ * is walked: an entry swapped for a symlink mid-walk is not detected.
+ */
+export declare function walkFilesSync(dir: string, options?: WalkFilesOptions): string[];
 //#endregion

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { accessSync, constants, lstatSync, readdirSync, 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
@@ -190,4 +190,53 @@ function findRootSync(startDir, marker, options = {}) {
 	}
 }
 //#endregion
-export { findExecutable, findExecutableSync, findRoot, findRootSync, findUpward, hasGitEntry };
+//#region src/walk-files.ts
+const DEFAULT_SKIP = [".git", "node_modules"];
+/** The entry's type, asking the filesystem when the platform's directory listing couldn't say. */
+function entryKind(entry, full) {
+	if (entry.isDirectory()) return "directory";
+	if (entry.isFile()) return "file";
+	if (entry.isSymbolicLink()) return "other";
+	try {
+		const stats = lstatSync(full);
+		return stats.isDirectory() ? "directory" : stats.isFile() ? "file" : "other";
+	} catch {
+		return "other";
+	}
+}
+/**
+* Every regular file under `dir`, as absolute paths in a stable (name-sorted,
+* depth-first) order. Directories named in `options.skip` are not entered.
+*
+* Symlinks found while walking are neither followed nor listed, so a link back
+* up the tree can't loop; `dir` itself is the caller's choice and is followed
+* if it is a symlink. A subdirectory that can't be read is skipped; `dir`
+* itself must be readable — its error propagates, since a typo'd root is a bug
+* to surface, not an empty result. The tree is assumed not to change while it
+* is walked: an entry swapped for a symlink mid-walk is not detected.
+*/
+function walkFilesSync(dir, options = {}) {
+	const skip = new Set(options.skip ?? DEFAULT_SKIP);
+	const files = [];
+	function walk(current, isRoot) {
+		let entries;
+		try {
+			entries = readdirSync(current, { withFileTypes: true });
+		} catch (error) {
+			if (isRoot) throw error;
+			return;
+		}
+		entries.sort((a, b) => Number(a.name > b.name) - Number(a.name < b.name));
+		for (const entry of entries) {
+			const full = join(current, entry.name);
+			const kind = entryKind(entry, full);
+			if (kind === "directory") {
+				if (!skip.has(entry.name)) walk(full, false);
+			} else if (kind === "file") files.push(full);
+		}
+	}
+	walk(resolve(dir), true);
+	return files;
+}
+//#endregion
+export { findExecutable, findExecutableSync, findRoot, findRootSync, findUpward, hasGitEntry, walkFilesSync };

package/package.json

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