@effected/walker 0.10.0 → 0.12.0

package/Descend.js

@@ -41,6 +41,8 @@ const escapesCwd = (relative) => {
 	}
 	return false;
 };
+/** 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 fs = yield* FileSystem.FileSystem;
@@ -49,11 +51,41 @@ const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
 	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" ? {
 		matches,
@@ -67,12 +99,19 @@ const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
 	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
+		depth: 0,
+		ancestors: baseAncestors
 	}];
 	for (let head = 0; head < frames.length; head += 1) {
 		const frame = frames[head];
@@ -100,7 +139,13 @@ const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
 			}
 			if (kind !== "Directory" || !deep) continue;
 			if (prune.has(entry)) continue;
-			if (yield* isSymbolicLink(absolute)) 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",
@@ -110,7 +155,8 @@ const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
 			frames.push({
 				relative,
 				absolute,
-				depth: frame.depth + 1
+				depth: frame.depth + 1,
+				ancestors
 			});
 		}
 	}

package/README.md

@@ -86,7 +86,7 @@ The predicate can be expensive — reading and parsing a `package.json` to decid
 - `Walker.firstMatch(candidates, predicate)` — the first candidate the predicate accepts. Absorbs each predicate failure individually and short-circuits at the first match.
 - `Walker.findUpward(dirs, candidatesFor)` — the first existing path, directory-major: every candidate in the nearest directory is tried before ascending.
 - `Walker.findRoot(dirs, isRoot)` — the nearest directory a marker predicate accepts. `firstMatch` where the candidate expansion is the identity.
-- `descend(pattern, options)` — the file paths a compiled `@effected/glob` pattern selects under `cwd`, POSIX separators, sorted. `onUnreadable` decides what an unreadable directory mid-walk means: `"fail"` (the default) raises a typed `DescendError`, `"skip"` continues past it and forgets it, and `"record"` continues past it and returns a `DescendResult` — `{ matches, unreadable }`, where each `UnreadableDirectory` carries the directory's `cwd`-relative `path` and the `PlatformError` it failed with, so a report never has to re-read the directory to learn why. The walk base records as `path: ""`, and a directory that vanished mid-walk (`NotFound`) is a benign race, never recorded.
+- `descend(pattern, options)` — the file paths a compiled `@effected/glob` pattern selects under `cwd`, POSIX separators, sorted. `onUnreadable` decides what an unreadable directory mid-walk means: `"fail"` (the default) raises a typed `DescendError`, `"skip"` continues past it and forgets it, and `"record"` continues past it and returns a `DescendResult` — `{ matches, unreadable }`, where each `UnreadableDirectory` carries the directory's `cwd`-relative `path` and the `PlatformError` it failed with, so a report never has to re-read the directory to learn why. The walk base records as `path: ""`, and a directory that vanished mid-walk (`NotFound`) is a benign race, never recorded. `followSymlinks` (default `false`) decides symlinked directories: by default they are never entered (cycle safety); under `true` they are descended 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 link loops terminate while two sibling links resolving to the same target both enumerate; a link whose real path cannot be resolved is never entered, and that failure follows `onUnreadable` exactly as an unreadable directory does — matching `@actions/glob`'s default `followSymbolicLinks: true` (Node's recursive `readdir` also follows links, but keeps no traversal chain and recurses without bound on a loop).
 
 ## License
 

package/index.d.ts

@@ -24,6 +24,27 @@ interface DescendOptions {
    * returns a bare match array.
    */
   readonly onUnreadable?: "fail" | "skip";
+  /**
+   * Whether to descend into symlinked directories. Defaults to `false`: a
+   * symlinked directory is never entered (cycle safety). 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
+   * a `FileSystem.realPath`; a plain directory's is derived from its
+   * parent's), and a directory whose real path is already an ancestor of the
+   * current branch closes a cycle and is skipped — so link loops terminate
+   * while two sibling links resolving to the same target both enumerate. A
+   * link whose real path cannot be resolved is never entered, and the
+   * failure follows `onUnreadable` exactly as an unreadable directory does:
+   * `NotFound` is a benign race and stays silent, anything else fails typed
+   * by default, is recorded under `"record"`, and is forgotten under
+   * `"skip"`. Following links matches `@actions/glob`'s default
+   * `followSymbolicLinks: true` and Node's recursive
+   * `fs.promises.readdir` — but the cycle guard is `@actions/glob`'s
+   * alone: Node's recursive `readdir` keeps no traversal chain and recurses
+   * without bound on a link loop.
+   */
+  readonly followSymlinks?: boolean;
 }
 /**
  * Options for `descend` under `onUnreadable: "record"`: every
@@ -48,7 +69,8 @@ interface DescendRecordOptions extends Omit<DescendOptions, "onUnreadable"> {
 }
 /**
  * One directory `descend` could not read under `onUnreadable: "record"`: its
- * `cwd`-relative path and the `PlatformError` that `readDirectory` failed
+ * `cwd`-relative path and the `PlatformError` that `readDirectory` — or,
+ * for a symlinked directory under `followSymlinks`, `realPath` — failed
  * with. The cause is the very failure the walk absorbed, so a caller that
  * must report WHY a directory was unreadable never re-reads it.
  *
@@ -65,14 +87,15 @@ interface UnreadableDirectory {
    * these entries as ordinary paths will not expect that; special-case it.
    */
   readonly path: string;
-  /** The `readDirectory` failure, never `NotFound` (a vanished directory is a benign race and is not recorded). */
+  /** 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;
 }
 /**
  * `descend`'s success value under `onUnreadable: "record"`: the matched
  * FILE paths plus an {@link UnreadableDirectory} for every mid-walk
- * directory whose `readDirectory` failed for a reason other than `NotFound`
- * (a vanished directory stays a benign race in every mode and is never
+ * directory whose `readDirectory` (or, under `followSymlinks`, a symlinked
+ * directory whose `realPath`) failed for a reason other than `NotFound` (a
+ * vanished directory stays a benign race in every mode and is never
  * recorded).
  *
  * @public
@@ -108,7 +131,8 @@ export declare class DescendError extends DescendError_base {
  * `onUnreadable: "record"`, resolving to a {@link DescendResult} — the
  * matched FILE paths relative to `cwd` (POSIX separators, sorted) plus an
  * {@link UnreadableDirectory} — path and cause — for every mid-walk
- * directory whose `readDirectory` failed for a reason other than `NotFound`.
+ * directory whose `readDirectory` (or, under `followSymlinks`, a symlinked
+ * directory whose `realPath`) failed for a reason other than `NotFound`.
  * The walk continues past each such directory exactly as `"skip"` does; it
  * never aborts and it never discards the offending path or its cause.
  *
@@ -127,18 +151,28 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * 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
+ * via `..` segments (walked paths never contain `..`). "Never reads outside
+ * its documented root" holds lexically always, and physically only while
+ * `followSymlinks` is off: under it, a link whose target lives outside `cwd`
+ * is descended, exactly as `@actions/glob` follows links out of the tree.
+ * 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.
+ * never descended into by default (cycle safety — detected by a `readLink`
+ * 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
+ * links resolving to the same target both enumerate. A link whose real path
+ * cannot be resolved is never entered, and a resolution failure other than
+ * `NotFound` is an unreadable directory under `onUnreadable`. 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`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.10.0",
+	"version": "0.12.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": [
@@ -37,8 +37,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.7.0",
-		"effect": "4.0.0-rc.116"
+		"@effected/glob": "^0.8.0",
+		"effect": "4.0.0-rc.117"
 	},
 	"engines": {
 		"node": ">=24.11.0"