@effected/walker 0.1.0 → 0.2.1

package/Descend.js

@@ -0,0 +1,139 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+
+//#region src/Descend.ts
+/**
+* Typed failure raised by {@link descend}: a directory mid-walk was unreadable
+* (under `onUnreadable: "fail"`), or the walk descended past `maxDepth`. Depth
+* exhaustion is a typed failure, never a truncation — silent truncation
+* silently changes match semantics.
+*
+* @public
+*/
+var DescendError = class extends Schema.TaggedErrorClass()("DescendError", {
+	/** The glob pattern's source text. */
+	pattern: Schema.String,
+	reason: Schema.Literals(["unreadableDirectory", "depthExceeded"]),
+	/** The offending directory, relative to `cwd` (`""` is the walk's base). */
+	path: Schema.String,
+	/** The depth cap, present when `reason` is `"depthExceeded"`. */
+	limit: Schema.optionalKey(Schema.Number)
+}) {
+	get message() {
+		const where = this.path === "" ? "the base directory" : JSON.stringify(this.path);
+		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"];
+/**
+* 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).
+*/
+const escapesCwd = (relative) => {
+	let depth = 0;
+	for (const segment of relative.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		depth += segment === ".." ? -1 : 1;
+		if (depth < 0) return true;
+	}
+	return false;
+};
+/**
+* Expand a compiled glob pattern against the filesystem, returning matching
+* 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
+* 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
+* 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 `..`, and the walk never
+* reads outside its documented root). Only an unreadable directory mid-walk
+* (under the default `onUnreadable: "fail"`) or a walk past `maxDepth` fails,
+* typed as {@link DescendError}.
+*
+* 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 (cycle safety — detected by a `readLink` probe); a
+* dangling symlink is not a match. A directory that vanishes between its
+* parent's listing and its own read is a benign race and reads as empty. A
+* pattern that cannot match below one level (no globstar, no mid-pattern
+* magic segment) reads a single level and never descends.
+*
+* The descent is a worklist, not a recursion — it cannot overflow the stack —
+* dequeued by head index, never `Array.shift()`. Like `ascend`, `maxDepth`
+* must be a positive integer: anything else is a defect, never a
+* silently-empty result.
+*
+* @public
+*/
+const descend = Effect.fn("Walker.descend")(function* (pattern, options) {
+	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";
+	/** 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));
+	if (!pattern.hasMagic && !pattern.negated) {
+		if (escapesCwd(pattern.source)) return [];
+		return (yield* typeOf(path.join(options.cwd, pattern.source))) === "File" ? [pattern.source] : [];
+	}
+	const base = pattern.negated ? "" : pattern.enumerationPrefix.replace(/\/+$/, "");
+	if (escapesCwd(base)) return [];
+	const absoluteBase = base === "" ? options.cwd : path.join(options.cwd, base);
+	if ((yield* typeOf(absoluteBase)) !== "Directory") return [];
+	const deep = pattern.crossesSegments || pattern.negated;
+	const results = [];
+	const frames = [{
+		relative: base,
+		absolute: absoluteBase,
+		depth: 0
+	}];
+	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) => error.reason._tag === "NotFound" || onUnreadable === "skip" ? Effect.succeed([]) : Effect.fail(new DescendError({
+			pattern: pattern.source,
+			reason: "unreadableDirectory",
+			path: frame.relative
+		}))));
+		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;
+			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
+			});
+		}
+	}
+	results.sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+	return results;
+});
+
+//#endregion
+export { DescendError, descend };

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Upward path traversal as Effect primitives. `Walker.ascend` gives you the directory chain from a starting path to the filesystem root; `Walker.findUpward` returns the nearest existing file among per-directory candidates; `Walker.findRoot` returns the nearest directory a marker predicate accepts. Every probe absorbs its own failure, so a single unreadable ancestor cannot hide a valid `.git` or `pnpm-workspace.yaml` above it. `FileSystem` and `Path` arrive from `effect` core, so no platform package is pulled in — not even in tests.
+Path traversal as Effect primitives. `Walker.ascend` gives you the directory chain from a starting path to the filesystem root; `Walker.findUpward` returns the nearest existing file among per-directory candidates; `Walker.findRoot` returns the nearest directory a marker predicate accepts. Every probe absorbs its own failure, so a single unreadable ancestor cannot hide a valid `.git` or `pnpm-workspace.yaml` above it. Going the other way, `descend` expands a compiled [`@effected/glob`](https://www.npmjs.com/package/@effected/glob) pattern under a directory into the matching file paths — sorted, symlink-safe, and typed about unreadable subtrees instead of silently swallowing them. `FileSystem` and `Path` arrive from `effect` core, so no platform package is pulled in — not even in tests.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
 > development against a single pinned Effect v4 beta. Packages graduate to
@@ -21,7 +21,7 @@ Upward path traversal as Effect primitives. `Walker.ascend` gives you the direct
 
 ## Why @effected/walker
 
-Walking up a directory tree looks like four lines of code until you meet the edges, and the edges are where the hand-rolled version quietly gets it wrong. If a probe on one ancestor fails — an `EACCES` on a directory you had no business reading anyway — the naive loop propagates that error and the whole search fails, so an unreadable directory hides the workspace root sitting one level above it. Walker absorbs each probe individually: a failed probe means "this candidate did not match", never "abort the scan". Every public error channel is `never` as a result, and the trade is stated up front rather than discovered later — not-found and cannot-look are deliberately indistinguishable, because discovery is best-effort.
+Walking up a directory tree looks like four lines of code until you meet the edges, and the edges are where the hand-rolled version quietly gets it wrong. If a probe on one ancestor fails — an `EACCES` on a directory you had no business reading anyway — the naive loop propagates that error and the whole search fails, so an unreadable directory hides the workspace root sitting one level above it. Walker absorbs each probe individually: a failed probe means "this candidate did not match", never "abort the scan". Every upward error channel is `never` as a result, and the trade is stated up front rather than discovered later — not-found and cannot-look are deliberately indistinguishable, because discovery is best-effort. The downward walk makes the opposite call on purpose: an unreadable subtree during glob expansion fails typed by default, because "no matches there" would be a wrong answer dressed as an empty one.
 
 The other edges get the same treatment. Absorption uses `Effect.catch`, which catches failures and not defects, so a predicate that *throws* is still programmer error and still surfaces. `findUpward` scans directory-major — every candidate in the nearest directory is exhausted before ascending — so a distant ancestor's `.apprc` can never beat a nearer `config/.apprc`. `maxDepth` must be a positive integer: `NaN`, `2.5` and `0` are defects rather than a silently empty chain, which is the failure mode that looks exactly like "nothing found". And `start` is required — walker never reads `process.cwd()` on your behalf.
 
@@ -35,7 +35,9 @@ npm install @effected/walker effect
 pnpm add @effected/walker effect
 ```
 
-Requires Node.js >=24.11.0. `effect` v4 is a peer dependency, and it is the only one — walker has no runtime dependencies of its own.
+Requires Node.js >=24.11.0. `effect` v4 and `@effected/glob` are peer dependencies — walker has no runtime dependencies of its own, and the glob peer is consumed as types plus `matches()` calls only.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
 
 `Path` and `FileSystem` come from `effect` core, not from a platform package, so a consumer provides them once at the edge (`@effect/platform-node` on Node, `@effect/platform-bun` on Bun) and a test provides `Path.layer` and `FileSystem.layerNoop` straight from core with nothing else installed.
 

package/index.d.ts

@@ -1,4 +1,80 @@
-import { Effect, FileSystem, Option, Path } from "effect";
+import { GlobPattern } from "@effected/glob";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+//#region src/Descend.d.ts
+/**
+ * Options for {@link descend}.
+ *
+ * @public
+ */
+interface DescendOptions {
+  /** Absolute directory the pattern is resolved against. Required — walker never reads `process.cwd()`. */
+  readonly cwd: string;
+  /** Hard cap on directory depth below the pattern's literal prefix. Defaults to 256. */
+  readonly maxDepth?: number;
+  /** Directory names never descended into. Defaults to `["node_modules", ".git"]`; a custom list replaces the default. */
+  readonly prune?: ReadonlyArray<string>;
+  /**
+   * What an unreadable directory mid-walk does. `"fail"` (the default) fails
+   * typed — downward enumeration must not silently swallow a subtree, or the
+   * answer is silently missing membership dressed as an empty one. `"skip"`
+   * absorbs the failure and continues.
+   */
+  readonly onUnreadable?: "fail" | "skip";
+}
+declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<"DescendError", {
+  /** The glob pattern's source text. */
+  readonly pattern: Schema.String;
+  readonly reason: Schema.Literals<readonly ["unreadableDirectory", "depthExceeded"]>;
+  /** The offending directory, relative to `cwd` (`""` is the walk's base). */
+  readonly path: Schema.String;
+  /** The depth cap, present when `reason` is `"depthExceeded"`. */
+  readonly limit: Schema.optionalKey<Schema.Number>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Typed failure raised by {@link descend}: a directory mid-walk was unreadable
+ * (under `onUnreadable: "fail"`), or the walk descended past `maxDepth`. Depth
+ * exhaustion is a typed failure, never a truncation — silent truncation
+ * silently changes match semantics.
+ *
+ * @public
+ */
+declare class DescendError extends DescendError_base {
+  get message(): string;
+}
+/**
+ * Expand a compiled glob pattern against the filesystem, returning matching
+ * 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
+ * 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
+ * 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 `..`, and the walk never
+ * reads outside its documented root). Only an unreadable directory mid-walk
+ * (under the default `onUnreadable: "fail"`) or a walk past `maxDepth` fails,
+ * typed as {@link DescendError}.
+ *
+ * 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 (cycle safety — detected by a `readLink` probe); a
+ * dangling symlink is not a match. A directory that vanishes between its
+ * parent's listing and its own read is a benign race and reads as empty. A
+ * pattern that cannot match below one level (no globstar, no mid-pattern
+ * magic segment) reads a single level and never descends.
+ *
+ * The descent is a worklist, not a recursion — it cannot overflow the stack —
+ * dequeued by head index, never `Array.shift()`. Like `ascend`, `maxDepth`
+ * must be a positive integer: anything else is a defect, never a
+ * silently-empty result.
+ *
+ * @public
+ */
+declare const descend: (pattern: GlobPattern, options: DescendOptions) => Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
+//#endregion
 //#region src/Walker.d.ts
 /**
  * Options for {@link Walker.ascend}.
@@ -23,5 +99,5 @@ declare const Walker: {
   readonly findRoot: <E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
 };
 //#endregion
-export { type AscendOptions, Walker };
+export { type AscendOptions, DescendError, type DescendOptions, Walker, descend };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,3 +1,4 @@
+import { DescendError, descend } from "./Descend.js";
 import { Walker } from "./Walker.js";
 
-export { Walker };
+export { DescendError, Walker, descend };

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@effected/walker",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"private": false,
-	"description": "Upward path traversal as Effect primitives: ascend a directory chain and return the first candidate satisfying a predicate.",
+	"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": [
 		"path",
 		"traversal",
@@ -36,6 +36,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
+		"@effected/glob": "0.1.1",
 		"effect": "4.0.0-beta.98"
 	},
 	"engines": {

package/tsdoc-metadata.json

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