@effected/walker 0.20.1 → 0.22.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
@@ -22,6 +23,12 @@ import { Effect, Result, Schema } from "effect";
 *   reserved device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`,
 *   `LPT1`–`LPT9`), in any case and with or without an extension
 *   (`nul.txt`).
+* - `outside` — `confineReal` only: the candidate's real path, links
+*   resolved, lies outside the base's real path.
+* - `unresolvable` — `confineReal` only: resolving the candidate or the base
+*   failed for a reason other than absence (a permission error, a link loop,
+*   a file used as a directory, a dangling link), so containment cannot be
+*   verified. The failure rides in the error's `cause`.
 *
 * @public
 */
@@ -30,7 +37,9 @@ const PathEscapeReason = Schema.Literals([
 	"absolute",
 	"traversal",
 	"empty",
-	"reservedName"
+	"reservedName",
+	"outside",
+	"unresolvable"
 ]);
 /**
 * An untrusted relative path would leave, or does not name anything under,
@@ -49,7 +58,9 @@ var PathEscapeError = class extends Schema.TaggedError()("PathEscapeError", {
 	/** The candidate path, exactly as the caller passed it. */
 	candidate: Schema.String,
 	/** Why the candidate was refused. */
-	reason: PathEscapeReason
+	reason: PathEscapeReason,
+	/** The resolution failure, present when `reason` is `"unresolvable"`. */
+	cause: Schema.optionalKey(Schema.Defect())
 }) {
 	get message() {
 		return `the path ${JSON.stringify(this.candidate)} ${REASON_TEXT[this.reason]}`;
@@ -61,7 +72,9 @@ const REASON_TEXT = {
 	absolute: "is absolute, so it is not confined to the base directory",
 	traversal: "climbs above the base directory",
 	empty: "names the base directory itself, not an entry under it",
-	reservedName: "has a segment win32 reserves or reads as something else"
+	reservedName: "has a segment win32 reserves or reads as something else",
+	outside: "resolves, links followed, to a path outside the base directory",
+	unresolvable: "could not be resolved, so its containment cannot be verified"
 };
 /** A win32 drive prefix: `C:\x`, `C:/x`, and the drive-relative `C:x`. */
 const DRIVE_PREFIX = /^[A-Za-z]:/;
@@ -71,12 +84,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.
 *
@@ -107,7 +116,7 @@ const stripTrailingSeparators = (path) => {
 * base yields the normalised relative path alone. The check is lexical, not
 * physical, and symlinks are out of scope: a symlink already inside the
 * base can still point out of it, so a caller extracting into a directory
-* it does not own resolves links separately.
+* it does not own checks the result with `confineReal` as well.
 *
 * {@link confineRelative} is defined in terms of this function and adds
 * only the tracing span.

package/ConfineReal.js

@@ -0,0 +1,123 @@
+import { PathEscapeError } from "./Confine.js";
+import { runUpward, runUpwardSync } from "./internal/upwardDrivers.js";
+import { confineRealMachine } from "./internal/upwardMachine.js";
+import { Effect, Path, Result } from "effect";
+
+// src/ConfineReal.ts
+/** The typed error a refusal describes — the one conversion both forms share. */
+const toResult = (candidate, outcome) => {
+	if (outcome._tag === "Ok") return Result.succeed(outcome.value);
+	if (outcome._tag === "Unresolvable") return Result.fail(new PathEscapeError({
+		candidate,
+		reason: "unresolvable",
+		cause: outcome.cause
+	}));
+	return Result.fail(new PathEscapeError({
+		candidate,
+		reason: outcome.reason
+	}));
+};
+/**
+* Confine a path to a base directory PHYSICALLY: resolve links in both, and
+* succeed with the candidate's real path only when it lies strictly inside
+* the base's real path.
+*
+* @remarks
+* Reach for it where `confineRelative` stops: a link inside the base that
+* points out of it (a symlinked `dist`, a planted `node_modules` entry), an
+* absolute path an agent or a tool handed over, a `descend` match — a
+* matched link is answered even when its target lies outside `cwd`.
+*
+* The candidate may be absolute (checked as it is) or relative (taken
+* against `base`). It is resolved the way the operating system resolves it:
+* segment by segment, so a `..` after a link climbs out of the link's
+* TARGET — `base/link/../x` is outside when `link` points outside — rather
+* than being collapsed lexically first, as `path.resolve` and node's JS
+* `fs.realpath` would. A path, or the tail of one, that does not exist yet
+* is resolved lexically from its real existing ancestor, so a write target
+* can be checked before it is created — but only once absence is proved: a
+* segment whose real path is not found is checked again without following
+* links, because a dangling link is "not found" too, and a write through one
+* creates its target wherever it points. The base is resolved the same way.
+*
+* Refused, typed as {@link PathEscapeError}: a NUL character (`nulByte`);
+* the empty string or any path whose real location IS the base (`empty`,
+* the same ruling `confineRelative` makes — a caller confining a path names
+* an entry under the base); on win32 a drive-relative `C:x` or a driveless
+* rooted `\x`, which names the current drive (`absolute`), or a segment
+* win32 reads as something else, such as a device name or `..  `
+* (`reservedName`); a real path outside the base's (`outside`); and a
+* resolution that fails for a reason other than absence, such as a
+* permission error, a link loop, or a dangling link — a link whose target
+* does not exist, refused even when that target would lie inside the base
+* (`unresolvable`, with the failure in `cause`) — containment that cannot be
+* verified is refused, never assumed.
+*
+* A relative `base` — the empty string included — is a **defect**: it would
+* be resolved against the process working directory, the silent wrong-root
+* walk `ascend` refuses for a relative `stopAt`. Absoluteness is judged by
+* the injected `Path`, so win32 accepts `C:\repo` and `\\server\share`;
+* a win32 `\repo`, rooted on whichever drive the process is on, is a defect
+* too.
+*
+* Use the returned path, not the candidate: it is the location that was
+* checked. Comparison is exact on the real paths, so on a case-insensitive
+* filesystem a base and a candidate spelled in different case may be refused
+* — the check fails closed. As with any check-then-use on a live filesystem,
+* a link swapped in between the check and the use is not covered.
+*
+* @example
+* ```ts
+* import { confineReal } from "@effected/walker";
+* import { Effect } from "effect";
+*
+* const target = confineReal("/repo", "packages/app/dist").pipe(
+*   Effect.catchTag("PathEscapeError", (error) => Effect.die(error)),
+* );
+* // Requires `FileSystem` and `Path` from the platform layer.
+* ```
+*
+* @param base - The absolute directory the candidate must stay under.
+* @param candidate - The path to check: absolute, or relative to `base`.
+* @returns An `Effect` succeeding with the candidate's real path, or failing
+* with {@link PathEscapeError}.
+*
+* @public
+*/
+const confineReal = Effect.fn("Walker.confineReal")(function* (base, candidate) {
+	const path = yield* Path.Path;
+	const outcome = yield* runUpward(confineRealMachine("Walker.confineReal", base, candidate, path));
+	return yield* Effect.fromResult(toResult(candidate, outcome));
+});
+/**
+* {@link confineReal}, synchronously, over a caller-supplied port.
+*
+* @remarks
+* The same resolution from the same code, through the port's `realPath`; a
+* `realPath` throwing `code: "ENOENT"` is absence only when the port's
+* `lstat` throws `ENOENT` too (otherwise a dangling link is there); anything
+* else is `unresolvable`, with the thrown value as the `cause`. A relative `base`
+* throws. For a caller with no Effect runtime; inside Effect, use
+* `confineReal`.
+*
+* @example
+* ```ts
+* import { confineRealSync } from "@effected/walker";
+* import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+* import { Result } from "effect";
+*
+* const checked = confineRealSync("/repo", "/repo/packages/app/dist", nodeWalkerSyncOps);
+* if (Result.isFailure(checked)) console.error(checked.failure.message);
+* ```
+*
+* @param base - The absolute directory the candidate must stay under.
+* @param candidate - The path to check: absolute, or relative to `base`.
+* @param ops - The platform: spread or pass `nodeWalkerSyncOps`.
+* @returns A `Result` succeeding with the candidate's real path, or failing
+* with {@link PathEscapeError}.
+*
+* @public
+*/
+const confineRealSync = (base, candidate, ops) => toResult(candidate, runUpwardSync(confineRealMachine("Walker.confineRealSync", base, candidate, ops.path), ops.fileSystem));
+
+export { confineReal, confineRealSync };

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,74 @@ 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, {
+		sep: path.sep,
+		join: (a, b) => path.join(a, b),
+		isAbsolute: (p) => path.isAbsolute(p)
+	});
+	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,79 @@
+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, {
+		sep: path.sep,
+		join: (a, b) => path.join(a, b),
+		isAbsolute: (p) => path.isAbsolute(p)
+	});
+	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 };