@effected/walker 0.20.0 → 0.21.0

package/Confine.js

@@ -1,4 +1,5 @@
 import { resolveSegments } from "./internal/segments.js";
+import { trimTrailing } from "./internal/trimTrailing.js";
 import { Effect, Result, Schema } from "effect";
 
 // src/Confine.ts
@@ -71,12 +72,8 @@ const DOTS_AND_SPACES = /^[. ]+$/;
 const DEVICE_NAME = /^(?:con|prn|aux|nul|com[0-9\u00b9\u00b2\u00b3]|lpt[0-9\u00b9\u00b2\u00b3]|conin\$|conout\$) *(?:\..*)?$/i;
 /** Whether win32 reads a normalised segment as something other than a plain entry. */
 const isReservedSegment = (segment) => segment.includes(":") || DOTS_AND_SPACES.test(segment) || DEVICE_NAME.test(segment);
-/** `path` without trailing `/` or `\`: a loop, because `/[\\/]+$/` backtracks quadratically on a long separator run. */
-const stripTrailingSeparators = (path) => {
-	let end = path.length;
-	while (end > 0 && (path[end - 1] === "/" || path[end - 1] === "\\")) end -= 1;
-	return path.slice(0, end);
-};
+/** `path` without trailing `/` or `\`, by a loop: `/[\\/]+$/` backtracks quadratically on a long separator run. */
+const stripTrailingSeparators = (path) => trimTrailing(path, (character) => character === "/" || character === "\\");
 /**
 * Confine an untrusted relative path to a base directory, synchronously.
 *

package/Descend.js

@@ -1,4 +1,4 @@
-import { resolveSegments } from "./internal/segments.js";
+import { descendMachine, failureOf } from "./internal/descendMachine.js";
 import { Effect, FileSystem, Path, Schema } from "effect";
 
 // src/Descend.ts
@@ -25,140 +25,70 @@ var DescendError = class extends Schema.TaggedError()("DescendError", {
 		return this.reason === "depthExceeded" ? `glob descent for ${JSON.stringify(this.pattern)} descended past ${this.limit ?? "the depth cap"} levels below ${where}` : `glob descent for ${JSON.stringify(this.pattern)} could not read ${where}`;
 	}
 };
-/** Directory names never descended into unless the caller overrides `prune`. */
-const DEFAULT_PRUNE = ["node_modules", ".git"];
+const kindOf = (info) => info.type === "File" ? "File" : info.type === "Directory" ? "Directory" : "Other";
 /**
-* Whether a cwd-relative pattern path lexically climbs above `cwd` via `..`
-* segments. Walked paths never contain `..`, so such a pattern can never match
-* one — the answer is zero matches, and no filesystem access outside `cwd`
-* ever happens (a pattern must not enumerate the tree above its documented
-* root).
+* The `Effect` driver of the shared walk (`internal/descendMachine.ts`): each
+* request the walk yields is answered through core's `FileSystem`, joins
+* through `Path`. Every rule lives in the machine; the sync driver in
+* `DescendSync.ts` answers the same requests from a synchronous port.
 */
-const escapesCwd = (relative) => resolveSegments(relative.split("/")) === void 0;
-/** Shared empty ancestor chain: frames under `followSymlinks: false` never consult theirs. */
-const NO_ANCESTORS = Object.freeze([]);
-/** Not exported — `descend`'s overloads below carry the public documentation. */
-const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
+const walk = (pattern, options) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
-	const maxDepth = options.maxDepth ?? 256;
-	if (!Number.isInteger(maxDepth) || maxDepth < 1) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.descend: maxDepth must be a positive integer, received ${maxDepth}`));
-	const prune = new Set(options.prune ?? DEFAULT_PRUNE);
-	const onUnreadable = options.onUnreadable ?? "fail";
-	const followSymlinks = options.followSymlinks ?? false;
-	const unreadable = [];
-	/** The stat-resolved type of `absolute`, or `undefined` when it does not resolve (missing, dangling symlink, unstatable). */
-	const typeOf = (absolute) => fs.stat(absolute).pipe(Effect.map((info) => info.type), Effect.orElseSucceed(() => void 0));
-	/** Whether `absolute` is itself a symlink. `readLink` succeeds only on links; any failure means "not one". */
-	const isSymbolicLink = (absolute) => fs.readLink(absolute).pipe(Effect.map(() => true), Effect.orElseSucceed(() => false));
-	/**
-	* The real path of a directory the cycle guard must identify — the walk
-	* base, or a symlinked directory — or `undefined` when the walk must not
-	* enter it. A link the resolver cannot resolve is one the guard cannot
-	* reason about: recording a stand-in (the link's own path) would make
-	* every hop around a loop look unseen, so the subtree is never queued.
-	* Whether the caller HEARS about it follows `onUnreadable` exactly as a
-	* failed `readDirectory` does: a `NotFound` is the benign vanished-target
-	* race (the subtree would have read as empty anyway) and stays silent in
-	* every mode; anything else — `EACCES` on a path component, above all —
-	* is a subtree this walk was asked to enumerate and cannot, so the
-	* default fails typed, `"record"` keeps the path and the cause, and
-	* `"skip"` forgets it. A silent skip here would hand a caller a smaller
-	* answer with nothing reporting it, which is the failure `"fail"` exists
-	* to prevent.
-	*/
-	const realPathOf = (absolute, relative) => fs.realPath(absolute).pipe(Effect.map((real) => real), Effect.catch((error) => {
-		if (error.reason._tag === "NotFound") return Effect.succeed(void 0);
-		if (onUnreadable === "fail") return Effect.fail(new DescendError({
-			pattern: pattern.source,
-			reason: "unreadableDirectory",
-			path: relative
-		}));
-		if (onUnreadable === "record") unreadable.push({
-			path: relative,
-			cause: error
-		});
-		return Effect.succeed(void 0);
-	}));
-	/** Wrap the walk's success value per `onUnreadable`: a plain array unless "record" asked for the pair. */
-	const finish = (matches) => onUnreadable === "record" ? {
+	const read = (effect) => effect.pipe(Effect.map((value) => ({
+		_tag: "Ok",
+		value
+	})), Effect.catch((error) => Effect.succeed(error.reason._tag === "NotFound" ? { _tag: "NotFound" } : {
+		_tag: "Failed",
+		cause: error
+	})));
+	const answer = (request) => {
+		switch (request._tag) {
+			case "Stat": return fs.stat(request.path).pipe(Effect.map((info) => ({
+				kind: kindOf(info),
+				info
+			})), Effect.orElseSucceed(() => void 0));
+			case "Lstat": return fs.lstat(request.path).pipe(Effect.map((info) => info.type === "SymbolicLink" ? { kind: "SymbolicLink" } : {
+				kind: kindOf(info),
+				info
+			}), Effect.orElseSucceed(() => void 0));
+			case "RealPath": return read(fs.realPath(request.path));
+			case "ReadDirectory": return read(fs.readDirectory(request.path));
+		}
+	};
+	const machine = descendMachine(pattern, options, (a, b) => path.join(a, b));
+	let step = machine.next();
+	while (step.done !== true) step = machine.next(yield* answer(step.value));
+	const result = step.value;
+	if (result._tag === "Defect") return yield* Effect.die(new Error(result.message));
+	if (result._tag === "Fail") return yield* new DescendError(failureOf(pattern, result));
+	return {
+		entries: result.entries,
+		unreadable: result.unreadable
+	};
+});
+/** Not exported — `descend`'s overloads below carry the public documentation. */
+const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
+	const { entries, unreadable } = yield* walk(pattern, options);
+	const matches = entries.map((entry) => entry.path);
+	return options.onUnreadable === "record" ? {
 		matches,
 		unreadable
 	} : matches;
-	if (!pattern.hasMagic && !pattern.negated) {
-		if (escapesCwd(pattern.source)) return finish([]);
-		return finish((yield* typeOf(path.join(options.cwd, pattern.source))) === "File" ? [pattern.source] : []);
-	}
-	const base = pattern.negated ? "" : pattern.enumerationPrefix.replace(/\/+$/, "");
-	if (escapesCwd(base)) return finish([]);
-	const absoluteBase = base === "" ? options.cwd : path.join(options.cwd, base);
-	if ((yield* typeOf(absoluteBase)) !== "Directory") return finish([]);
-	let baseAncestors = NO_ANCESTORS;
-	if (followSymlinks) {
-		const real = yield* realPathOf(absoluteBase, base);
-		if (real === void 0) return finish([]);
-		baseAncestors = [real];
-	}
-	const deep = pattern.crossesSegments || pattern.negated;
-	const results = [];
-	const frames = [{
-		relative: base,
-		absolute: absoluteBase,
-		depth: 0,
-		ancestors: baseAncestors
-	}];
-	for (let head = 0; head < frames.length; head += 1) {
-		const frame = frames[head];
-		if (frame === void 0) break;
-		const entries = yield* fs.readDirectory(frame.absolute).pipe(Effect.catch((error) => {
-			if (error.reason._tag === "NotFound") return Effect.succeed([]);
-			if (onUnreadable === "fail") return Effect.fail(new DescendError({
-				pattern: pattern.source,
-				reason: "unreadableDirectory",
-				path: frame.relative
-			}));
-			if (onUnreadable === "record") unreadable.push({
-				path: frame.relative,
-				cause: error
-			});
-			return Effect.succeed([]);
-		}));
-		for (const entry of entries) {
-			const relative = frame.relative === "" ? entry : `${frame.relative}/${entry}`;
-			const absolute = path.join(frame.absolute, entry);
-			const kind = yield* typeOf(absolute);
-			if (kind === "File") {
-				if (pattern.matches(relative)) results.push(relative);
-				continue;
-			}
-			if (kind !== "Directory" || !deep) continue;
-			if (prune.has(entry)) continue;
-			let ancestors = frame.ancestors;
-			if (followSymlinks) {
-				const parentReal = frame.ancestors[frame.ancestors.length - 1] ?? frame.absolute;
-				const real = (yield* isSymbolicLink(absolute)) ? yield* realPathOf(absolute, relative) : path.join(parentReal, entry);
-				if (real === void 0 || frame.ancestors.includes(real)) continue;
-				ancestors = [...frame.ancestors, real];
-			} else if (yield* isSymbolicLink(absolute)) continue;
-			if (frame.depth + 1 > maxDepth) return yield* new DescendError({
-				pattern: pattern.source,
-				reason: "depthExceeded",
-				path: frame.relative,
-				limit: maxDepth
-			});
-			frames.push({
-				relative,
-				absolute,
-				depth: frame.depth + 1,
-				ancestors
-			});
-		}
-	}
-	results.sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
-	return finish(results);
+});
+/** Not exported — `descendEntries`' overloads below carry the public documentation. */
+const descendEntriesImpl = Effect.fn("Walker.descendEntries")(function* (pattern, options) {
+	const { entries, unreadable } = yield* walk(pattern, options);
+	return options.onUnreadable === "record" ? {
+		matches: entries,
+		unreadable
+	} : entries;
 });
 function descend(pattern, options) {
 	return descendImpl(pattern, options);
 }
+function descendEntries(pattern, options) {
+	return descendEntriesImpl(pattern, options);
+}
 
-export { DescendError, descend };
+export { DescendError, descend, descendEntries };

package/DescendSync.js

@@ -0,0 +1,75 @@
+import { descendMachine, failureOf } from "./internal/descendMachine.js";
+import { DescendError } from "./Descend.js";
+import { Result } from "effect";
+
+// src/DescendSync.ts
+const isNotFound = (error) => typeof error === "object" && error !== null && error.code === "ENOENT";
+const kindOf = (stats) => stats.isFile() ? "File" : stats.isDirectory() ? "Directory" : "Other";
+/** The sync driver of the shared walk. Throws only for a defect (an invalid `maxDepth`). */
+const walkSync = (pattern, options) => {
+	const { fileSystem, path } = options;
+	const read = (f) => {
+		try {
+			return {
+				_tag: "Ok",
+				value: f()
+			};
+		} catch (cause) {
+			return isNotFound(cause) ? { _tag: "NotFound" } : {
+				_tag: "Failed",
+				cause
+			};
+		}
+	};
+	const answer = (request) => {
+		switch (request._tag) {
+			case "Stat": try {
+				const info = fileSystem.stat(request.path);
+				return {
+					kind: kindOf(info),
+					info
+				};
+			} catch {
+				return;
+			}
+			case "Lstat": try {
+				const info = fileSystem.lstat(request.path);
+				return info.isSymbolicLink() ? { kind: "SymbolicLink" } : {
+					kind: kindOf(info),
+					info
+				};
+			} catch {
+				return;
+			}
+			case "RealPath": return read(() => fileSystem.realPath(request.path));
+			case "ReadDirectory": return read(() => fileSystem.readDirectory(request.path));
+		}
+	};
+	const machine = descendMachine(pattern, options, (a, b) => path.join(a, b));
+	let step = machine.next();
+	while (step.done !== true) step = machine.next(answer(step.value));
+	const result = step.value;
+	if (result._tag === "Defect") throw new Error(result.message);
+	if (result._tag === "Fail") return Result.fail(new DescendError(failureOf(pattern, result)));
+	return Result.succeed({
+		entries: result.entries,
+		unreadable: result.unreadable
+	});
+};
+function descendSync(pattern, options) {
+	return Result.map(walkSync(pattern, options), ({ entries, unreadable }) => {
+		const matches = entries.map((entry) => entry.path);
+		return options.onUnreadable === "record" ? {
+			matches,
+			unreadable
+		} : matches;
+	});
+}
+function descendEntriesSync(pattern, options) {
+	return Result.map(walkSync(pattern, options), ({ entries, unreadable }) => options.onUnreadable === "record" ? {
+		matches: entries,
+		unreadable
+	} : entries);
+}
+
+export { descendEntriesSync, descendSync };

package/Walker.js

@@ -1,32 +1,11 @@
 import { Effect, FileSystem, Option, Path } from "effect";
 
 // src/Walker.ts
-const ascend = (start, options) => Effect.gen(function* () {
-	const path = yield* Path.Path;
-	const maxDepth = options?.maxDepth ?? 256;
-	if (!Number.isInteger(maxDepth) || maxDepth < 1) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: maxDepth must be a positive integer, received ${maxDepth}`));
-	if (options?.stopAt !== void 0 && !path.isAbsolute(options.stopAt)) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: stopAt must be an absolute path, received ${JSON.stringify(options.stopAt)} (ascending from ${JSON.stringify(start)})`));
-	const ceiling = options?.stopAt === void 0 ? void 0 : path.resolve(options.stopAt);
-	const dirs = [];
-	let current = start;
-	for (let depth = 0; depth < maxDepth; depth++) {
-		dirs.push(current);
-		if (ceiling !== void 0 && (current === ceiling || path.resolve(current) === ceiling)) break;
-		const parent = path.dirname(current);
-		if (parent === current) break;
-		current = parent;
-	}
-	return dirs;
-});
-const ascendWithin = (start, ceiling, options) => Effect.gen(function* () {
-	if (Option.isNone(ceiling)) return yield* ascend(start, options);
-	return yield* ascendToPhysical(start, ceiling.value, options);
-});
 const ascendToPhysical = (start, ceiling, options) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	if (!path.isAbsolute(ceiling)) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascendWithin: ceiling must be an absolute path, received ${JSON.stringify(ceiling)} (ascending from ${JSON.stringify(start)})`));
-	const dirs = yield* ascend(start, {
+	const dirs = yield* Walker.ascend(start, {
 		...options,
 		stopAt: ceiling
 	});
@@ -34,27 +13,16 @@ const ascendToPhysical = (start, ceiling, options) => Effect.gen(function* () {
 	if (last !== void 0 && path.resolve(last) === path.resolve(ceiling)) return dirs;
 	const physical = yield* Effect.option(fs.realPath(ceiling));
 	if (Option.isNone(physical)) return dirs;
-	const hit = yield* findRoot(dirs, (dir) => Effect.map(fs.realPath(dir), (real) => real === physical.value));
+	const hit = yield* Walker.findRoot(dirs, (dir) => Effect.map(fs.realPath(dir), (real) => real === physical.value));
 	return Option.isSome(hit) ? dirs.slice(0, dirs.indexOf(hit.value) + 1) : dirs;
 });
-const firstMatch = (candidates, predicate) => Effect.gen(function* () {
-	for (const candidate of candidates) if (yield* Effect.catch(predicate(candidate), () => Effect.succeed(false))) return Option.some(candidate);
-	return Option.none();
-});
-const findUpward = (dirs, candidatesFor) => Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const candidates = [];
-	for (const dir of dirs) candidates.push(...candidatesFor(dir));
-	return yield* firstMatch(candidates, (candidate) => fs.exists(candidate));
-});
-const findRoot = (dirs, isRoot) => firstMatch(dirs, isRoot);
 /**
 * Upward path traversal primitives: the directory chain from a start path to the
 * root, and first-match scans over it.
 *
 * @public
 */
-var Walker = class {
+var Walker = class Walker {
 	constructor() {}
 	/**
 	* Ascend from `start` toward the filesystem root, yielding each directory,
@@ -90,7 +58,25 @@ var Walker = class {
 	* // Requires `Path` from the platform layer.
 	* ```
 	*/
-	static ascend = ascend;
+	static ascend(start, options) {
+		return Effect.gen(function* () {
+			const path = yield* Path.Path;
+			const maxDepth = options?.maxDepth ?? 256;
+			if (!Number.isInteger(maxDepth) || maxDepth < 1) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: maxDepth must be a positive integer, received ${maxDepth}`));
+			if (options?.stopAt !== void 0 && !path.isAbsolute(options.stopAt)) return yield* Effect.die(/* @__PURE__ */ new Error(`Walker.ascend: stopAt must be an absolute path, received ${JSON.stringify(options.stopAt)} (ascending from ${JSON.stringify(start)})`));
+			const ceiling = options?.stopAt === void 0 ? void 0 : path.resolve(options.stopAt);
+			const dirs = [];
+			let current = start;
+			for (let depth = 0; depth < maxDepth; depth++) {
+				dirs.push(current);
+				if (ceiling !== void 0 && (current === ceiling || path.resolve(current) === ceiling)) break;
+				const parent = path.dirname(current);
+				if (parent === current) break;
+				current = parent;
+			}
+			return dirs;
+		});
+	}
 	/**
 	* {@link Walker.ascend} bounded by a PHYSICAL ceiling: stops at the nearest
 	* directory whose real path is the ceiling's real path, inclusive.
@@ -118,7 +104,12 @@ var Walker = class {
 	* A present ceiling must be absolute; a relative one **dies**, for the
 	* reasons {@link AscendOptions.stopAt} gives.
 	*/
-	static ascendWithin = ascendWithin;
+	static ascendWithin(start, ceiling, options) {
+		return Effect.gen(function* () {
+			if (Option.isNone(ceiling)) return yield* Walker.ascend(start, options);
+			return yield* ascendToPhysical(start, ceiling.value, options);
+		});
+	}
 	/**
 	* The first candidate whose `predicate` reports true, or `Option.none()`.
 	*
@@ -133,7 +124,12 @@ var Walker = class {
 	* programmer error and surfaces as a defect. Do not change this to
 	* `Effect.catchCause` — the distinction is load-bearing.
 	*/
-	static firstMatch = firstMatch;
+	static firstMatch(candidates, predicate) {
+		return Effect.gen(function* () {
+			for (const candidate of candidates) if (yield* Effect.catch(predicate(candidate), () => Effect.succeed(false))) return Option.some(candidate);
+			return Option.none();
+		});
+	}
 	/**
 	* The first existing path among the candidates `candidatesFor` produces for each
 	* directory in `dirs`, scanned in order. Nearer directories win.
@@ -142,7 +138,14 @@ var Walker = class {
 	* Candidates materialize up front, bounded by `dirs.length × candidatesFor`'s
 	* output — a few hundred strings under the default `maxDepth`.
 	*/
-	static findUpward = findUpward;
+	static findUpward(dirs, candidatesFor) {
+		return Effect.gen(function* () {
+			const fs = yield* FileSystem.FileSystem;
+			const candidates = [];
+			for (const dir of dirs) candidates.push(...candidatesFor(dir));
+			return yield* Walker.firstMatch(candidates, (candidate) => fs.exists(candidate));
+		});
+	}
 	/**
 	* The first directory in `dirs` that `isRoot` accepts.
 	*
@@ -151,7 +154,9 @@ var Walker = class {
 	* identity. `isRoot` is a caller-supplied marker test (a `.git` entry, a
 	* `pnpm-workspace.yaml`), and its failures are absorbed per directory.
 	*/
-	static findRoot = findRoot;
+	static findRoot(dirs, isRoot) {
+		return Walker.firstMatch(dirs, isRoot);
+	}
 };
 
 export { Walker };

package/index.d.ts

@@ -145,6 +145,23 @@ interface DescendOptions {
   readonly maxDepth?: number;
   /** Directory names never descended into. Defaults to `["node_modules", ".git"]`; a custom list replaces the default. */
   readonly prune?: ReadonlyArray<string>;
+  /**
+   * Marker FILE names that make a directory a boundary — a nested unit (another
+   * package, say: `["package.json"]`) whose contents belong to a separate walk.
+   *
+   * @remarks
+   * A directory strictly below `cwd` holding a FILE with one of these names
+   * contributes nothing: none of its files match and its subtree is never
+   * descended. `cwd` itself is never a boundary, and a DIRECTORY named like a
+   * marker does not count. The rule is about where a file sits, not how the
+   * walk reached it, so it applies to a walk that starts below `cwd` (the
+   * pattern's literal prefix) and to a literal pattern alike: a boundary
+   * between `cwd` and the walk base, or between `cwd` and a literal file,
+   * also answers zero matches. Each directory pays one stat per marker it
+   * actually lists. Defaults to none. Not to be confused with
+   * `Walker.ascend`'s `stopAt`, an inclusive upward ceiling.
+   */
+  readonly boundaries?: ReadonlyArray<string>;
   /**
    * What an unreadable directory mid-walk does. `"fail"` (the default) fails
    * typed — downward enumeration must not silently swallow a subtree, or the
@@ -158,7 +175,9 @@ interface DescendOptions {
   readonly onUnreadable?: "fail" | "skip";
   /**
    * Whether to descend into symlinked directories. Defaults to `false`: a
-   * symlinked directory is never entered (cycle safety). Under `true` links
+   * symlinked directory is never entered (cycle safety) — the walk base, and
+   * every directory on the way to it, included: a base reached through a link
+   * is an empty result. Under `true` links
    * are followed with the cycle guard kept underneath, in `@actions/glob`'s
    * `traversalChain` semantics: each descended directory records its real
    * path on its own branch's ancestor chain (only the base and each link pay
@@ -208,7 +227,7 @@ interface DescendRecordOptions extends Omit<DescendOptions, "onUnreadable"> {
  *
  * @public
  */
-interface UnreadableDirectory {
+interface UnreadableDirectory<C = PlatformError.PlatformError> {
   /**
    * The directory's path relative to `cwd`, POSIX separators.
    *
@@ -220,7 +239,7 @@ interface UnreadableDirectory {
    */
   readonly path: string;
   /** The `readDirectory` (or, for a link under `followSymlinks`, `realPath`) failure, never `NotFound` (a vanished directory is a benign race and is not recorded). */
-  readonly cause: PlatformError.PlatformError;
+  readonly cause: C;
 }
 /**
  * `descend`'s success value under `onUnreadable: "record"`: the matched
@@ -232,11 +251,11 @@ interface UnreadableDirectory {
  *
  * @public
  */
-interface DescendResult {
+interface DescendResult<C = PlatformError.PlatformError> {
   /** Matching FILE paths relative to `cwd`, POSIX separators, sorted — identical in shape to the `"fail"`/`"skip"` success value. */
   readonly matches: ReadonlyArray<string>;
   /** Directories that could not be read, each with its cause, in walk order. */
-  readonly unreadable: ReadonlyArray<UnreadableDirectory>;
+  readonly unreadable: ReadonlyArray<UnreadableDirectory<C>>;
 }
 declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<"DescendError", {
   /** The glob pattern's source text. */
@@ -259,6 +278,35 @@ declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<
 export declare class DescendError extends DescendError_base {
   get message(): string;
 }
+/**
+ * One matched file with the stat the walk already read for it — `descendEntries`'
+ * element. Costs no syscall beyond `descend`'s: the walk stats every entry to
+ * classify it, and this keeps the answer instead of discarding it.
+ *
+ * The type parameter is the stat's type, so the sync walk reuses this shape
+ * with its port's stats.
+ *
+ * @public
+ */
+interface DescendEntry<I = FileSystem.File.Info> {
+  /** The file's path relative to `cwd`, POSIX separators. */
+  readonly path: string;
+  /** `FileSystem.stat` of the file — links followed, so a symlinked file reports its target. */
+  readonly info: I;
+}
+/**
+ * `descendEntries`' success value under `onUnreadable: "record"`: the matched
+ * {@link DescendEntry} values plus every {@link UnreadableDirectory}, exactly
+ * as {@link DescendResult} carries them for `descend`.
+ *
+ * @public
+ */
+interface DescendEntriesResult<I = FileSystem.File.Info, C = PlatformError.PlatformError> {
+  /** Matching files with their stats, sorted by path. */
+  readonly matches: ReadonlyArray<DescendEntry<I>>;
+  /** Directories that could not be read, each with its cause, in walk order. */
+  readonly unreadable: ReadonlyArray<UnreadableDirectory<C>>;
+}
 /**
  * Expand a compiled glob pattern against the filesystem under
  * `onUnreadable: "record"`, resolving to a {@link DescendResult} — the
@@ -277,11 +325,16 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * FILE paths relative to `cwd` (POSIX separators), sorted by relative path.
  *
  * @remarks
- * A literal pattern (no magic, not negated) fast-paths to a single stat: the
+ * A path is answered in the spelling the pattern matched it under: `./src/*.ts`
+ * answers `./src/a.ts`, and `src/*.ts` answers `src/a.ts`. A file several
+ * brace alternatives match under different spellings (`{src,./src}/*.ts`) is
+ * answered once, in the spelling of the earliest of them in pattern order. A
+ * literal pattern (no magic, not negated) fast-paths to a single stat: the
  * result is `[source]` when it resolves to a file, `[]` otherwise — a missing
- * path is zero matches, not an error. A magic pattern walks from its literal
- * directory prefix (`GlobPattern.enumerationPrefix`); a NEGATED pattern can
- * match paths outside that prefix, so it walks from `cwd` itself. A missing
+ * path is zero matches, not an error. A magic pattern walks each of its
+ * `GlobPattern.enumerationRoots`, reading each directory once however many
+ * alternatives spell it; a NEGATED pattern can match paths outside those
+ * roots, so it walks from `cwd` itself. A missing
  * base directory is likewise an empty result, because zero matches is a
  * normal glob answer — as is any pattern that lexically climbs above `cwd`
  * via `..` segments (walked paths never contain `..`). "Never reads outside
@@ -294,7 +347,7 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  *
  * Only files match. A symlink counts when it stat-resolves to a file
  * (`FileSystem.stat` follows links, as node's does); a symlinked directory is
- * never descended into by default (cycle safety — detected by a `readLink`
+ * never descended into by default (cycle safety — detected by an `lstat`
  * probe), unless `followSymlinks: true` asks for it, which follows links under
  * `@actions/glob`'s `traversalChain` cycle guard: a directory is a cycle only
  * when its real path is already an ancestor of the current branch, so sibling
@@ -332,6 +385,165 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * @public
  */
 export declare function descend(pattern: GlobPattern, options: DescendOptions): Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
+/**
+ * `descend` under `onUnreadable: "record"`, keeping each match's stat:
+ * resolves to a {@link DescendEntriesResult}.
+ *
+ * @public
+ */
+export declare function descendEntries(pattern: GlobPattern, options: DescendRecordOptions): Effect.Effect<DescendEntriesResult, DescendError, FileSystem.FileSystem | Path.Path>;
+/**
+ * `descend`, keeping the stat the walk already read for each matched
+ * file: resolves to {@link DescendEntry} values sorted by path.
+ *
+ * @remarks
+ * The same walk, the same matches in the same order, the same errors — only
+ * the element type differs, and at no extra syscall (the walk stats every
+ * entry to classify it). For a cache signature over a tree, map each entry's
+ * `path` and `info.mtime` (or `info.size`) into whatever key the cache needs;
+ * the kit does not choose the fingerprint.
+ *
+ * @example
+ * ```ts
+ * import { GlobPattern, GlobPatternOptions } from "@effected/glob";
+ * import { descendEntries } from "@effected/walker";
+ * import { Effect, Option } from "effect";
+ *
+ * const signature = Effect.gen(function* () {
+ * 	const pattern = yield* GlobPattern.compile("**", GlobPatternOptions.make({ dot: true }));
+ * 	const entries = yield* descendEntries(pattern, { cwd: "/repo/src", boundaries: ["package.json"] });
+ * 	return entries.map((e) => `${e.path}:${Option.match(e.info.mtime, { onNone: () => "", onSome: (d) => d.getTime() })}`).join("|");
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function descendEntries(pattern: GlobPattern, options: DescendOptions): Effect.Effect<ReadonlyArray<DescendEntry>, DescendError, FileSystem.FileSystem | Path.Path>;
+/**
+ * The stats {@link WalkerSyncFileSystem} answers — a structural subset of
+ * `node:fs` `Stats`, so `statSync` / `lstatSync` satisfy it verbatim.
+ *
+ * @public
+ */
+interface WalkerSyncStats {
+  /** Whether the entry is a regular file. */
+  isFile(): boolean;
+  /** Whether the entry is a directory. */
+  isDirectory(): boolean;
+  /** Whether the entry is a symbolic link (only ever true for `lstat`). */
+  isSymbolicLink(): boolean;
+  /** Modification time, epoch milliseconds. */
+  readonly mtimeMs: number;
+  /** Size in bytes. */
+  readonly size: number;
+}
+/**
+ * The synchronous file operations the sync walk needs, supplied by the
+ * consumer — `node:fs` satisfies it (`nodeWalkerFileSystem` from
+ * `@effected/walker/node-sync`).
+ *
+ * @remarks
+ * Every member reports failure by throwing a node-shaped error. A `code` of
+ * `"ENOENT"` is the benign vanished-path race (empty, never recorded); any
+ * other throw from `readDirectory` or `realPath` is an unreadable directory,
+ * handled per `onUnreadable`. A throwing `stat` or `lstat` reads as "no
+ * entry", exactly as the `Effect` walk reads its failed `stat` and `lstat`.
+ *
+ * @public
+ */
+interface WalkerSyncFileSystem {
+  /** The entry names inside the directory at `path` (`readdirSync`). */
+  readonly readDirectory: (path: string) => ReadonlyArray<string>;
+  /** Stats of `path`, following links (`statSync`). */
+  readonly stat: (path: string) => WalkerSyncStats;
+  /** Stats of `path` itself, not following a final link (`lstatSync`). */
+  readonly lstat: (path: string) => WalkerSyncStats;
+  /** The real path of `path`, links resolved (`realpathSync`). */
+  readonly realPath: (path: string) => string;
+}
+/**
+ * The synchronous path operation the sync walk needs — a structural subset of
+ * `node:path`, so the module itself (or its `win32` / `posix` variant)
+ * satisfies it. It shapes only the absolute paths handed to the
+ * {@link WalkerSyncFileSystem}; matching is POSIX-relative by the glob
+ * contract.
+ *
+ * @public
+ */
+interface WalkerSyncPath {
+  /** Join segments with the implementation's separator (like `path.join`). */
+  readonly join: (...segments: ReadonlyArray<string>) => string;
+}
+/**
+ * The platform half of every sync walk.
+ *
+ * @public
+ */
+interface WalkerSyncOps {
+  /** File operations. */
+  readonly fileSystem: WalkerSyncFileSystem;
+  /** Path joining. */
+  readonly path: WalkerSyncPath;
+}
+/**
+ * Options for `descendSync` / `descendEntriesSync`: every `DescendOptions`
+ * field, plus the platform.
+ *
+ * @public
+ */
+interface DescendSyncOptions extends DescendOptions, WalkerSyncOps {}
+/**
+ * {@link DescendSyncOptions} under `onUnreadable: "record"`.
+ *
+ * @public
+ */
+interface DescendSyncRecordOptions extends DescendRecordOptions, WalkerSyncOps {}
+/**
+ * `descend` under `onUnreadable: "record"`, synchronously over a caller-supplied port.
+ *
+ * @public
+ */
+export declare function descendSync(pattern: GlobPattern, options: DescendSyncRecordOptions): Result.Result<DescendResult<unknown>, DescendError>;
+/**
+ * `descend`, synchronously, over a caller-supplied file port: matching FILE
+ * paths relative to `cwd` (POSIX separators), sorted.
+ *
+ * @remarks
+ * The same walk as `descend` — it drives the same traversal, so every rule
+ * holds identically: the literal fast path, the enumeration prefix, `prune`,
+ * `boundaries`, the symlink posture and per-branch cycle guard under
+ * `followSymlinks`, `onUnreadable` and the `maxDepth` failure. Failures are a
+ * `Result` failure typed as `DescendError`; an invalid `maxDepth` is a defect
+ * and throws. For a caller with no Effect runtime (config evaluation, a Node
+ * SEA sidecar); inside Effect, use `descend`.
+ *
+ * @example
+ * ```ts
+ * import { GlobPattern } from "@effected/glob";
+ * import { descendSync } from "@effected/walker";
+ * import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+ * import { Result } from "effect";
+ *
+ * const pattern = Result.getOrThrow(GlobPattern.compileResult("src/**"));
+ * const files = descendSync(pattern, { cwd: "/repo", boundaries: ["package.json"], ...nodeWalkerSyncOps });
+ * ```
+ *
+ * @public
+ */
+export declare function descendSync(pattern: GlobPattern, options: DescendSyncOptions): Result.Result<ReadonlyArray<string>, DescendError>;
+/**
+ * `descendEntries` under `onUnreadable: "record"`, synchronously over a caller-supplied port.
+ *
+ * @public
+ */
+export declare function descendEntriesSync(pattern: GlobPattern, options: DescendSyncRecordOptions): Result.Result<DescendEntriesResult<WalkerSyncStats, unknown>, DescendError>;
+/**
+ * `descendEntries`, synchronously: `descendSync`'s matches, each with
+ * the stat the walk already read for it.
+ *
+ * @public
+ */
+export declare function descendEntriesSync(pattern: GlobPattern, options: DescendSyncOptions): Result.Result<ReadonlyArray<DescendEntry<WalkerSyncStats>>, DescendError>;
 /**
  * Options for {@link compileAndExpand}: every {@link DescendOptions} field,
  * plus the glob options the pattern compiles under.
@@ -530,7 +742,7 @@ export declare class Walker {
    * // Requires `Path` from the platform layer.
    * ```
    */
-  static readonly ascend: (start: string, options?: AscendOptions) => Effect.Effect<ReadonlyArray<string>, never, Path.Path>;
+  static ascend(start: string, options?: AscendOptions): Effect.Effect<ReadonlyArray<string>, never, Path.Path>;
   /**
    * {@link Walker.ascend} bounded by a PHYSICAL ceiling: stops at the nearest
    * directory whose real path is the ceiling's real path, inclusive.
@@ -558,7 +770,7 @@ export declare class Walker {
    * A present ceiling must be absolute; a relative one **dies**, for the
    * reasons {@link AscendOptions.stopAt} gives.
    */
-  static readonly ascendWithin: (start: string, ceiling: Option.Option<string>, options?: Pick<AscendOptions, "maxDepth">) => Effect.Effect<ReadonlyArray<string>, never, FileSystem.FileSystem | Path.Path>;
+  static ascendWithin(start: string, ceiling: Option.Option<string>, options?: Pick<AscendOptions, "maxDepth">): Effect.Effect<ReadonlyArray<string>, never, FileSystem.FileSystem | Path.Path>;
   /**
    * The first candidate whose `predicate` reports true, or `Option.none()`.
    *
@@ -573,7 +785,7 @@ export declare class Walker {
    * programmer error and surfaces as a defect. Do not change this to
    * `Effect.catchCause` — the distinction is load-bearing.
    */
-  static readonly firstMatch: <E, R>(candidates: ReadonlyArray<string>, predicate: (candidate: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
+  static firstMatch<E, R>(candidates: ReadonlyArray<string>, predicate: (candidate: string) => Effect.Effect<boolean, E, R>): Effect.Effect<Option.Option<string>, never, R>;
   /**
    * The first existing path among the candidates `candidatesFor` produces for each
    * directory in `dirs`, scanned in order. Nearer directories win.
@@ -582,7 +794,7 @@ export declare class Walker {
    * Candidates materialize up front, bounded by `dirs.length × candidatesFor`'s
    * output — a few hundred strings under the default `maxDepth`.
    */
-  static readonly findUpward: (dirs: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem>;
+  static findUpward(dirs: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>): Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem>;
   /**
    * The first directory in `dirs` that `isRoot` accepts.
    *
@@ -591,7 +803,7 @@ export declare class Walker {
    * identity. `isRoot` is a caller-supplied marker test (a `.git` entry, a
    * `pnpm-workspace.yaml`), and its failures are absorbed per directory.
    */
-  static readonly findRoot: <E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
+  static findRoot<E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>): Effect.Effect<Option.Option<string>, never, R>;
 }
-export type { AscendOptions, CompileAndExpandOptions, DescendOptions, DescendRecordOptions, DescendResult, UnreadableDirectory };
+export type { AscendOptions, CompileAndExpandOptions, DescendEntriesResult, DescendEntry, DescendOptions, DescendRecordOptions, DescendResult, DescendSyncOptions, DescendSyncRecordOptions, UnreadableDirectory, WalkerSyncFileSystem, WalkerSyncOps, WalkerSyncPath, WalkerSyncStats };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,6 +1,7 @@
 import { PathEscapeError, PathEscapeReason, confineRelative, confineRelativeResult } from "./Confine.js";
-import { DescendError, descend } from "./Descend.js";
+import { DescendError, descend, descendEntries } from "./Descend.js";
+import { descendEntriesSync, descendSync } from "./DescendSync.js";
 import { GlobExpansionError, compileAndExpand } from "./Expand.js";
 import { Walker } from "./Walker.js";
 
-export { DescendError, GlobExpansionError, PathEscapeError, PathEscapeReason, Walker, compileAndExpand, confineRelative, confineRelativeResult, descend };
+export { DescendError, GlobExpansionError, PathEscapeError, PathEscapeReason, Walker, compileAndExpand, confineRelative, confineRelativeResult, descend, descendEntries, descendEntriesSync, descendSync };

package/internal/descendMachine.js

@@ -0,0 +1,240 @@
+import { resolveSegments } from "./segments.js";
+import { trimTrailing } from "./trimTrailing.js";
+
+// src/internal/descendMachine.ts
+/** Directory names never descended into unless the caller overrides `prune`. */
+const DEFAULT_PRUNE = ["node_modules", ".git"];
+/** A glob pattern's one separator: its backslash is an escape, never a separator. */
+const isSlash = (character) => character === "/";
+/** Shared empty ancestor chain: frames under `followSymlinks: false` never consult theirs. */
+const NO_ANCESTORS = Object.freeze([]);
+/** The walk. */
+function* descendMachine(pattern, options, join) {
+	/** Yields one request; the answer is typed by the request's tag. */
+	function* ask(request) {
+		return yield request;
+	}
+	const maxDepth = options.maxDepth ?? 256;
+	if (!Number.isInteger(maxDepth) || maxDepth < 1) return {
+		_tag: "Defect",
+		message: `Walker.descend: maxDepth must be a positive integer, received ${maxDepth}`
+	};
+	const prune = new Set(options.prune ?? DEFAULT_PRUNE);
+	const boundaries = options.boundaries ?? [];
+	const onUnreadable = options.onUnreadable ?? "fail";
+	const followSymlinks = options.followSymlinks ?? false;
+	const unreadable = [];
+	const done = (entries) => {
+		entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+		return {
+			_tag: "Done",
+			entries,
+			unreadable
+		};
+	};
+	const unreadableFail = (path) => ({
+		_tag: "Fail",
+		reason: "unreadableDirectory",
+		path
+	});
+	/**
+	* Whether the directory at `absolute` is a boundary: it holds a marker
+	* FILE. `listing`, when the directory was just read, spares the stat for
+	* every marker it does not name; a directory named like a marker is not one.
+	*/
+	function* isBoundary(absolute, listing) {
+		for (const marker of boundaries) {
+			if (listing !== void 0 && !listing.includes(marker)) continue;
+			if ((yield* ask({
+				_tag: "Stat",
+				path: join(absolute, marker)
+			}))?.kind === "File") return true;
+		}
+		return false;
+	}
+	/**
+	* Whether the way down `segments` (below `cwd`) is closed: a directory among
+	* the first `boundaryCount` is a boundary, or — without followSymlinks,
+	* where a symlinked directory is never entered — a link is among the first
+	* `directoryCount`. Either way the answer is nothing.
+	*/
+	function* blocked(segments, directoryCount, boundaryCount) {
+		if (boundaries.length === 0 && followSymlinks) return false;
+		let absolute = options.cwd;
+		for (let index = 0; index < directoryCount; index += 1) {
+			absolute = join(absolute, segments[index] ?? "");
+			if (index < boundaryCount && (yield* isBoundary(absolute, void 0))) return true;
+			if (!followSymlinks && (yield* ask({
+				_tag: "Lstat",
+				path: absolute
+			}))?.kind === "SymbolicLink") return true;
+		}
+		return false;
+	}
+	/** The real path of a directory the cycle guard must identify, or `undefined` when the walk must not enter it. */
+	function* realPathOf(absolute, relative) {
+		const answer = yield* ask({
+			_tag: "RealPath",
+			path: absolute
+		});
+		if (answer._tag === "Ok") return answer.value;
+		if (answer._tag === "NotFound") return void 0;
+		if (onUnreadable === "fail") return { fail: true };
+		if (onUnreadable === "record") unreadable.push({
+			path: relative,
+			cause: answer.cause
+		});
+	}
+	if (!pattern.hasMagic && !pattern.negated && !/[{}]/.test(pattern.source)) {
+		const segments = resolveSegments(pattern.source.split("/"));
+		if (segments === void 0) return done([]);
+		if (yield* blocked(segments, segments.length - 1, segments.length - 1)) return done([]);
+		const answer = yield* ask({
+			_tag: "Stat",
+			path: join(options.cwd, pattern.source)
+		});
+		return done(answer?.kind === "File" ? [{
+			path: pattern.source,
+			info: answer.info
+		}] : []);
+	}
+	const results = [];
+	/**
+	* Walks one root: the literal directory `base` and everything below it a
+	* match can lie in — one level, or all of it when `deep`. An absent base,
+	* one that climbs above `cwd`, or one behind a boundary or a link is
+	* skipped; a `Fail` aborts the walk.
+	*
+	* The walk itself is canonical (`cwd` is `""`, never `.`), so each directory
+	* is read once however many spellings name it. What it answers is spelled
+	* the way the pattern spells it: a file matches when its path, re-spelled
+	* through one of the root's spellings, matches the pattern, and it is
+	* answered ONCE, in the first such spelling — the earliest brace
+	* alternative's, since spellings come in pattern order. A directory the
+	* walk reports (unreadable, too deep) is spelled through the root's own
+	* earliest spelling.
+	*/
+	function* walkRoot(rawBase, deep, spellings) {
+		const spelled = spellings.map((spelling) => {
+			const canonical = resolveSegments(spelling.split("/"))?.join("/") ?? "";
+			return {
+				spelling,
+				canonical: canonical === "" ? "" : `${canonical}/`
+			};
+		});
+		/** The file at canonical `relative`, in the first spelling the pattern matches it under, or `undefined`. */
+		const matchedAs = (relative) => {
+			for (const { spelling, canonical } of spelled) {
+				if (canonical !== "" && !relative.startsWith(canonical)) continue;
+				const candidate = spelling + relative.slice(canonical.length);
+				if (pattern.matches(candidate)) return candidate;
+			}
+		};
+		const baseSegments = resolveSegments(rawBase.split("/"));
+		if (baseSegments === void 0) return void 0;
+		const base = baseSegments.join("/");
+		const baseCanonical = base === "" ? "" : `${base}/`;
+		const own = spelled.find(({ canonical }) => canonical === baseCanonical)?.spelling ?? baseCanonical;
+		const shown = (relative) => relative === base ? trimTrailing(own, isSlash) : own + relative.slice(baseCanonical.length);
+		const absoluteBase = base === "" ? options.cwd : join(options.cwd, base);
+		if ((yield* ask({
+			_tag: "Stat",
+			path: absoluteBase
+		}))?.kind !== "Directory") return void 0;
+		if (yield* blocked(baseSegments, baseSegments.length, baseSegments.length - 1)) return void 0;
+		let baseAncestors = NO_ANCESTORS;
+		if (followSymlinks) {
+			const real = yield* realPathOf(absoluteBase, shown(base));
+			if (typeof real === "object") return unreadableFail(shown(base));
+			if (real === void 0) return void 0;
+			baseAncestors = [real];
+		}
+		const frames = [{
+			relative: base,
+			absolute: absoluteBase,
+			depth: 0,
+			ancestors: baseAncestors
+		}];
+		for (let head = 0; head < frames.length; head += 1) {
+			const frame = frames[head];
+			if (frame === void 0) break;
+			const read = yield* ask({
+				_tag: "ReadDirectory",
+				path: frame.absolute
+			});
+			let entries = [];
+			if (read._tag === "Ok") entries = read.value;
+			else if (read._tag === "Failed") {
+				if (onUnreadable === "fail") return unreadableFail(shown(frame.relative));
+				if (onUnreadable === "record") unreadable.push({
+					path: shown(frame.relative),
+					cause: read.cause
+				});
+			}
+			if (frame.relative !== "" && (yield* isBoundary(frame.absolute, entries))) continue;
+			for (const entry of entries) {
+				const relative = frame.relative === "" ? entry : `${frame.relative}/${entry}`;
+				const absolute = join(frame.absolute, entry);
+				const own = yield* ask({
+					_tag: "Lstat",
+					path: absolute
+				});
+				const link = own?.kind === "SymbolicLink";
+				const stat = link ? yield* ask({
+					_tag: "Stat",
+					path: absolute
+				}) : own;
+				if (stat === void 0) continue;
+				if (stat.kind === "File") {
+					const path = matchedAs(relative);
+					if (path !== void 0) results.push({
+						path,
+						info: stat.info
+					});
+					continue;
+				}
+				if (stat.kind !== "Directory" || !deep) continue;
+				if (prune.has(entry)) continue;
+				let ancestors = frame.ancestors;
+				if (followSymlinks) {
+					const parentReal = frame.ancestors[frame.ancestors.length - 1] ?? frame.absolute;
+					const real = link ? yield* realPathOf(absolute, shown(relative)) : join(parentReal, entry);
+					if (typeof real === "object") return unreadableFail(shown(relative));
+					if (real === void 0 || frame.ancestors.includes(real)) continue;
+					ancestors = [...frame.ancestors, real];
+				} else if (link) continue;
+				if (frame.depth + 1 > maxDepth) return {
+					_tag: "Fail",
+					reason: "depthExceeded",
+					path: shown(frame.relative),
+					limit: maxDepth
+				};
+				frames.push({
+					relative,
+					absolute,
+					depth: frame.depth + 1,
+					ancestors
+				});
+			}
+		}
+	}
+	const roots = pattern.negated ? [{
+		prefix: "",
+		deep: true,
+		spellings: [""]
+	}] : pattern.enumerationRoots;
+	for (const root of roots) {
+		const failed = yield* walkRoot(trimTrailing(root.prefix, isSlash), root.deep, root.spellings);
+		if (failed !== void 0) return failed;
+	}
+	return done(results);
+}
+/** The typed error a `Fail` result describes — the one conversion both drivers share. */
+const failureOf = (pattern, result) => ({
+	pattern: pattern.source,
+	reason: result.reason,
+	path: result.path,
+	...result.limit === void 0 ? {} : { limit: result.limit }
+});
+
+export { DEFAULT_PRUNE, descendMachine, failureOf };

package/internal/trimTrailing.js

@@ -0,0 +1,13 @@
+// src/internal/trimTrailing.ts
+/**
+* `text` without its trailing run of characters `isTrailing` accepts, in time linear in the run.
+*
+* @internal
+*/
+const trimTrailing = (text, isTrailing) => {
+	let end = text.length;
+	while (end > 0 && isTrailing(text.charAt(end - 1))) end -= 1;
+	return end === text.length ? text : text.slice(0, end);
+};
+
+export { trimTrailing };

package/node-sync.d.ts

@@ -0,0 +1,89 @@
+import "@effected/glob";
+import "effect";
+/**
+ * The stats {@link WalkerSyncFileSystem} answers — a structural subset of
+ * `node:fs` `Stats`, so `statSync` / `lstatSync` satisfy it verbatim.
+ *
+ * @public
+ */
+interface WalkerSyncStats {
+  /** Whether the entry is a regular file. */
+  isFile(): boolean;
+  /** Whether the entry is a directory. */
+  isDirectory(): boolean;
+  /** Whether the entry is a symbolic link (only ever true for `lstat`). */
+  isSymbolicLink(): boolean;
+  /** Modification time, epoch milliseconds. */
+  readonly mtimeMs: number;
+  /** Size in bytes. */
+  readonly size: number;
+}
+/**
+ * The synchronous file operations the sync walk needs, supplied by the
+ * consumer — `node:fs` satisfies it (`nodeWalkerFileSystem` from
+ * `@effected/walker/node-sync`).
+ *
+ * @remarks
+ * Every member reports failure by throwing a node-shaped error. A `code` of
+ * `"ENOENT"` is the benign vanished-path race (empty, never recorded); any
+ * other throw from `readDirectory` or `realPath` is an unreadable directory,
+ * handled per `onUnreadable`. A throwing `stat` or `lstat` reads as "no
+ * entry", exactly as the `Effect` walk reads its failed `stat` and `lstat`.
+ *
+ * @public
+ */
+interface WalkerSyncFileSystem {
+  /** The entry names inside the directory at `path` (`readdirSync`). */
+  readonly readDirectory: (path: string) => ReadonlyArray<string>;
+  /** Stats of `path`, following links (`statSync`). */
+  readonly stat: (path: string) => WalkerSyncStats;
+  /** Stats of `path` itself, not following a final link (`lstatSync`). */
+  readonly lstat: (path: string) => WalkerSyncStats;
+  /** The real path of `path`, links resolved (`realpathSync`). */
+  readonly realPath: (path: string) => string;
+}
+/**
+ * The synchronous path operation the sync walk needs — a structural subset of
+ * `node:path`, so the module itself (or its `win32` / `posix` variant)
+ * satisfies it. It shapes only the absolute paths handed to the
+ * {@link WalkerSyncFileSystem}; matching is POSIX-relative by the glob
+ * contract.
+ *
+ * @public
+ */
+interface WalkerSyncPath {
+  /** Join segments with the implementation's separator (like `path.join`). */
+  readonly join: (...segments: ReadonlyArray<string>) => string;
+}
+/**
+ * The platform half of every sync walk.
+ *
+ * @public
+ */
+interface WalkerSyncOps {
+  /** File operations. */
+  readonly fileSystem: WalkerSyncFileSystem;
+  /** Path joining. */
+  readonly path: WalkerSyncPath;
+}
+/**
+ * `WalkerSyncFileSystem` over `node:fs`: `readdirSync`, `statSync`,
+ * `lstatSync`, `realpathSync`.
+ *
+ * @public
+ */
+export declare const nodeWalkerFileSystem: WalkerSyncFileSystem;
+/**
+ * `WalkerSyncPath` over `node:path` (the host platform's separator).
+ *
+ * @public
+ */
+export declare const nodeWalkerPath: WalkerSyncPath;
+/**
+ * Both bindings, to spread into `descendSync` options.
+ *
+ * @public
+ */
+export declare const nodeWalkerSyncOps: WalkerSyncOps;
+export type { WalkerSyncFileSystem, WalkerSyncOps, WalkerSyncPath, WalkerSyncStats };
+//# sourceMappingURL=node-sync.d.ts.map

package/node-sync.js

@@ -0,0 +1,55 @@
+import { lstatSync, readdirSync, realpathSync, statSync } from "node:fs";
+import * as path from "node:path";
+
+// src/node-sync.ts
+/**
+* The Node.js binding for the synchronous walk — a ready-made
+* `WalkerSyncFileSystem` over `node:fs` and `WalkerSyncPath` over `node:path`,
+* so adopting `descendSync` is one import.
+*
+* Deliberately a **separate subpath** (`@effected/walker/node-sync`), not part
+* of the main entry: the main entry takes its platform through `R` (or, for the
+* sync forms, from the caller) and imports nothing platform-shaped.
+*
+* @example
+* ```ts
+* import { GlobPattern } from "@effected/glob";
+* import { descendSync } from "@effected/walker";
+* import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+* import { Result } from "effect";
+*
+* const pattern = Result.getOrThrow(GlobPattern.compileResult("src/**"));
+* const files = descendSync(pattern, { cwd: process.cwd(), ...nodeWalkerSyncOps });
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* `WalkerSyncFileSystem` over `node:fs`: `readdirSync`, `statSync`,
+* `lstatSync`, `realpathSync`.
+*
+* @public
+*/
+const nodeWalkerFileSystem = {
+	readDirectory: (p) => readdirSync(p),
+	stat: (p) => statSync(p),
+	lstat: (p) => lstatSync(p),
+	realPath: (p) => realpathSync(p)
+};
+/**
+* `WalkerSyncPath` over `node:path` (the host platform's separator).
+*
+* @public
+*/
+const nodeWalkerPath = { join: path.join };
+/**
+* Both bindings, to spread into `descendSync` options.
+*
+* @public
+*/
+const nodeWalkerSyncOps = {
+	fileSystem: nodeWalkerFileSystem,
+	path: nodeWalkerPath
+};
+
+export { nodeWalkerFileSystem, nodeWalkerPath, nodeWalkerSyncOps };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.20.0",
+	"version": "0.21.0",
 	"private": false,
 	"description": "Path traversal as Effect primitives: ascend a directory chain to the first matching candidate, or descend a tree expanding a glob against the filesystem.",
 	"keywords": [
@@ -34,10 +34,15 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./node-sync": {
+			"types": "./node-sync.d.ts",
+			"import": "./node-sync.js",
+			"default": "./node-sync.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.14.0",
+		"@effected/glob": "^0.15.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.59.4"
     }
   ]
 }