@effected/walker 0.21.0 → 0.22.0

package/Confine.js

@@ -23,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
 */
@@ -31,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,
@@ -50,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]}`;
@@ -62,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]:/;
@@ -104,7 +116,7 @@ const stripTrailingSeparators = (path) => trimTrailing(path, (character) => char
 * 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

@@ -56,7 +56,11 @@ const walk = (pattern, options) => Effect.gen(function* () {
 			case "ReadDirectory": return read(fs.readDirectory(request.path));
 		}
 	};
-	const machine = descendMachine(pattern, options, (a, b) => path.join(a, b));
+	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;

package/DescendSync.js

@@ -45,7 +45,11 @@ const walkSync = (pattern, options) => {
 			case "ReadDirectory": return read(() => fileSystem.readDirectory(request.path));
 		}
 	};
-	const machine = descendMachine(pattern, options, (a, b) => path.join(a, b));
+	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;

package/Walker.js

@@ -1,21 +1,8 @@
-import { Effect, FileSystem, Option, Path } from "effect";
+import { runUpward, runUpwardSync } from "./internal/upwardDrivers.js";
+import { ascendChain, ascendToMarkerMachine, ascendWithinMachine, findUpwardAllMachine, findUpwardMachine } from "./internal/upwardMachine.js";
+import { Effect, Option, Path } from "effect";
 
 // src/Walker.ts
-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* Walker.ascend(start, {
-		...options,
-		stopAt: ceiling
-	});
-	const last = dirs.at(-1);
-	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* 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;
-});
 /**
 * Upward path traversal primitives: the directory chain from a start path to the
 * root, and first-match scans over it.
@@ -61,20 +48,9 @@ var Walker = class Walker {
 	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;
+			const chain = ascendChain("Walker.ascend", start, options, path);
+			if (chain._tag === "Defect") return yield* Effect.die(new Error(chain.message));
+			return chain.value;
 		});
 	}
 	/**
@@ -106,8 +82,8 @@ var Walker = class Walker {
 	*/
 	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);
+			const path = yield* Path.Path;
+			return yield* runUpward(ascendWithinMachine("Walker.ascendWithin", start, Option.getOrUndefined(ceiling), options, path));
 		});
 	}
 	/**
@@ -139,12 +115,7 @@ var Walker = class Walker {
 	* output — a few hundred strings under the default `maxDepth`.
 	*/
 	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));
-		});
+		return Effect.map(runUpward(findUpwardMachine(dirs, candidatesFor)), Option.fromUndefinedOr);
 	}
 	/**
 	* The first directory in `dirs` that `isRoot` accepts.
@@ -157,6 +128,190 @@ var Walker = class Walker {
 	static findRoot(dirs, isRoot) {
 		return Walker.firstMatch(dirs, isRoot);
 	}
+	/**
+	* {@link Walker.ascend} stopped at the nearest directory that holds any of
+	* `markers`, inclusive: the chain from `start` up to and including the
+	* first directory with a `.git` (or whatever the markers name) entry.
+	*
+	* @remarks
+	* A marker is an entry NAME probed with `FileSystem.exists` in each
+	* directory, nearest first, so any entry kind counts — a `.git` directory,
+	* or the `.git` FILE of a worktree or submodule — and a link counts when it
+	* resolves. The probes stop at the hit: nothing above the directory that
+	* holds a marker is ever touched. With no marker anywhere the chain runs to
+	* the filesystem root, exactly as `ascend(start)` gives it.
+	*
+	* A failed probe is absorbed as "no marker here", as
+	* {@link Walker.firstMatch} absorbs one, so one unreadable directory never
+	* hides a marker above it. An empty `markers` list, or an empty marker
+	* name, is a **defect**: the first would silently ask for the unbounded
+	* walk and the second would match every directory, and both are
+	* statically wrong at the call site. An invalid `maxDepth` dies exactly as
+	* `ascend`'s does.
+	*
+	* There is no `stopAt` here: a marker stop and a lexical ceiling answer the
+	* same question two ways. To bound a marker walk by a ceiling as well,
+	* take the shorter of the two chains.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { Effect } from "effect";
+	*
+	* const program = Effect.gen(function* () {
+	* 	// With `.git` in /repo: ["/repo/packages/app", "/repo/packages", "/repo"]
+	* 	return yield* Walker.ascendToMarker("/repo/packages/app", [".git"]);
+	* });
+	* // Requires `FileSystem` and `Path` from the platform layer.
+	* ```
+	*/
+	static ascendToMarker(start, markers, options) {
+		return Effect.gen(function* () {
+			const path = yield* Path.Path;
+			return yield* runUpward(ascendToMarkerMachine("Walker.ascendToMarker", start, markers, options, path));
+		});
+	}
+	/**
+	* Every existing candidate of the NEAREST directory in `dirs` that has any,
+	* or `Option.none()` — {@link Walker.findUpward} for a caller that must see
+	* a second hit (an ambiguity) rather than have the first one chosen.
+	*
+	* @remarks
+	* Directories are scanned in order, and every candidate of a directory is
+	* probed before the scan ascends; the scan stops after the first directory
+	* with a hit, so nothing above it is probed. `found` keeps the order
+	* `candidatesFor` produced and is never empty. A failed probe is absorbed
+	* as "not there", as in `findUpward`, so not-found and cannot-look are
+	* indistinguishable here too.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { Effect, Option } from "effect";
+	*
+	* const program = Effect.gen(function* () {
+	* 	const dirs = yield* Walker.ascend("/repo/packages/app");
+	* 	const hits = yield* Walker.findUpwardAll(dirs, (dir) => [`${dir}/tool.config.ts`, `${dir}/tool.config.js`]);
+	* 	// Two config files in one directory is the caller's ambiguity to report.
+	* 	return Option.map(hits, ({ found }) => found.length > 1);
+	* });
+	* ```
+	*/
+	static findUpwardAll(dirs, candidatesFor) {
+		return Effect.map(runUpward(findUpwardAllMachine(dirs, candidatesFor)), Option.fromUndefinedOr);
+	}
+	/**
+	* {@link Walker.ascend}, synchronously, over a caller-supplied path
+	* implementation.
+	*
+	* @remarks
+	* The same chain from the same code: lexical, nearest first, `stopAt`
+	* inclusive and compared in resolved form. A relative `stopAt` or an
+	* invalid `maxDepth` is a defect, which here THROWS, since there is no
+	* error channel to die through. For a caller with no Effect runtime (a CLI
+	* helper that runs before one, a bundler-plugin hook); inside Effect, use
+	* `ascend`.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { nodeWalkerPath } from "@effected/walker/node-sync";
+	*
+	* const dirs = Walker.ascendSync("/repo/packages/app", { stopAt: "/repo", path: nodeWalkerPath });
+	* // => ["/repo/packages/app", "/repo/packages", "/repo"]
+	* ```
+	*/
+	static ascendSync(start, options) {
+		const chain = ascendChain("Walker.ascendSync", start, options, options.path);
+		if (chain._tag === "Defect") throw new Error(chain.message);
+		return chain.value;
+	}
+	/**
+	* {@link Walker.ascendWithin}, synchronously, over a caller-supplied port:
+	* the lexical chain stopped at the nearest directory whose `realPath` is
+	* the ceiling's.
+	*
+	* @remarks
+	* The same walk from the same code as `ascendWithin`: `Option.none()` is
+	* exactly `ascendSync(start)`, a ceiling the chain already spells costs no
+	* `realPath`, a `realPath` that throws is absorbed as "not the ceiling",
+	* and an unresolvable ceiling leaves the lexical chain standing. A
+	* relative ceiling or an invalid `maxDepth` throws.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+	* import { Option } from "effect";
+	*
+	* const dirs = Walker.ascendWithinSync("/repo/packages/app", Option.some("/repo"), nodeWalkerSyncOps);
+	* ```
+	*/
+	static ascendWithinSync(start, ceiling, options) {
+		return runUpwardSync(ascendWithinMachine("Walker.ascendWithinSync", start, Option.getOrUndefined(ceiling), options, options.path), options.fileSystem);
+	}
+	/**
+	* {@link Walker.ascendToMarker}, synchronously, over a caller-supplied port.
+	*
+	* @remarks
+	* The same walk from the same code. A marker exists when the port's `stat`
+	* (links followed) answers for it; a `stat` that throws, for any reason,
+	* is "no marker here", as the `Effect` form absorbs a failed probe. An
+	* empty `markers` list, an empty marker name or an invalid `maxDepth`
+	* throws.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+	*
+	* const dirs = Walker.ascendToMarkerSync("/repo/packages/app", [".git"], nodeWalkerSyncOps);
+	* ```
+	*/
+	static ascendToMarkerSync(start, markers, options) {
+		return runUpwardSync(ascendToMarkerMachine("Walker.ascendToMarkerSync", start, markers, options, options.path), options.fileSystem);
+	}
+	/**
+	* {@link Walker.findUpward}, synchronously, over a caller-supplied port: the
+	* first existing candidate, directory-major, or `Option.none()`.
+	*
+	* @remarks
+	* The same scan from the same code. A candidate exists when the port's
+	* `stat` (links followed) answers for it; a `stat` that throws is "not
+	* there". A throwing `candidatesFor` throws before any probe.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+	*
+	* const dirs = Walker.ascendSync("/repo/packages/app", { path: nodeWalkerSyncOps.path });
+	* const workspace = Walker.findUpwardSync(dirs, (dir) => [`${dir}/pnpm-workspace.yaml`], nodeWalkerSyncOps);
+	* ```
+	*/
+	static findUpwardSync(dirs, candidatesFor, ops) {
+		return Option.fromUndefinedOr(runUpwardSync(findUpwardMachine(dirs, candidatesFor), ops.fileSystem));
+	}
+	/**
+	* {@link Walker.findUpwardAll}, synchronously, over a caller-supplied port.
+	*
+	* @remarks
+	* The same scan from the same code: every existing candidate of the
+	* nearest directory with any, in candidate order, and nothing above it
+	* probed. A candidate exists when the port's `stat` answers for it.
+	*
+	* @example
+	* ```ts
+	* import { Walker } from "@effected/walker";
+	* import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+	*
+	* const dirs = Walker.ascendSync("/repo/packages/app", { path: nodeWalkerSyncOps.path });
+	* const hits = Walker.findUpwardAllSync(dirs, (dir) => [`${dir}/a.config.ts`, `${dir}/a.config.js`], nodeWalkerSyncOps);
+	* ```
+	*/
+	static findUpwardAllSync(dirs, candidatesFor, ops) {
+		return Option.fromUndefinedOr(runUpwardSync(findUpwardAllMachine(dirs, candidatesFor), ops.fileSystem));
+	}
 };
 
 export { Walker };