@effected/walker 0.20.1 → 0.22.0

package/index.js

@@ -1,6 +1,8 @@
 import { PathEscapeError, PathEscapeReason, confineRelative, confineRelativeResult } from "./Confine.js";
-import { DescendError, descend } from "./Descend.js";
+import { confineReal, confineRealSync } from "./ConfineReal.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, confineReal, confineRealSync, confineRelative, confineRelativeResult, descend, descendEntries, descendEntriesSync, descendSync };

package/internal/absolute.js

@@ -0,0 +1,19 @@
+// src/internal/absolute.ts
+/**
+* A win32 path rooted on the CURRENT drive: one leading separator, not two
+* (`\\server\share` and `\\?\C:\x` are UNC and device paths, which name their
+* root). `path.win32.isAbsolute` calls `\repo` absolute, yet which drive it
+* names depends on the process working directory — exactly like the
+* drive-relative `C:x`.
+*/
+const CURRENT_DRIVE_ROOT = /^[\\/](?![\\/])/;
+/** Whether `path` is rooted on the current drive under win32 path rules. */
+const isCurrentDriveRooted = (path, sep) => sep === "\\" && CURRENT_DRIVE_ROOT.test(path);
+/**
+* Whether `path` names one location whatever the process working directory:
+* absolute to the injected implementation, and on win32 not rooted on the
+* current drive.
+*/
+const isPinnedAbsolute = (path, ops) => ops.isAbsolute(path) && !isCurrentDriveRooted(path, ops.sep);
+
+export { isCurrentDriveRooted, isPinnedAbsolute };

package/internal/descendMachine.js

@@ -0,0 +1,282 @@
+import { resolveSegments } from "./segments.js";
+import { trimTrailing } from "./trimTrailing.js";
+import { isPinnedAbsolute } from "./absolute.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, path) {
+	const join = path.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}`
+	};
+	if (options.cwd.includes("\0") || !isPinnedAbsolute(options.cwd, path)) return {
+		_tag: "Defect",
+		message: `Walker.descend: cwd must be an absolute path, received ${JSON.stringify(options.cwd)}`
+	};
+	const match = options.match ?? "file";
+	if (match !== "file" && match !== "directory" && match !== "any") return {
+		_tag: "Defect",
+		message: `Walker.descend: match must be "file", "directory" or "any", received ${JSON.stringify(match)}`
+	};
+	const matchFiles = match !== "directory";
+	const matchDirectories = match !== "file";
+	/** Canonical paths of the directories already answered: a root's base may also be an entry of another root. */
+	const answeredDirectories = /* @__PURE__ */ new Set();
+	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)
+		});
+		const wanted = answer?.kind === "File" && matchFiles || answer?.kind === "Directory" && matchDirectories && segments.length > 0;
+		return done(answer !== void 0 && wanted ? [{
+			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 entry 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;
+			}
+		};
+		/**
+		* The directory at canonical `relative`, in the first spelling the pattern
+		* matches it under — bare, or with a trailing `/` (a glob's directory-only
+		* form) — or `undefined`. Each directory is answered once.
+		*/
+		const matchedDirectoryAs = (relative) => {
+			if (answeredDirectories.has(relative)) return void 0;
+			const answer = matchedAs(relative) ?? matchedAs(`${relative}/`);
+			if (answer !== void 0) answeredDirectories.add(relative);
+			return answer;
+		};
+		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);
+		const baseStat = yield* ask({
+			_tag: "Stat",
+			path: absoluteBase
+		});
+		if (baseStat?.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];
+		}
+		if (matchDirectories && base !== "") {
+			const answer = matchedDirectoryAs(base);
+			if (answer !== void 0) results.push({
+				path: answer,
+				info: baseStat.info
+			});
+		}
+		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 answer = matchFiles ? matchedAs(relative) : void 0;
+					if (answer !== void 0) results.push({
+						path: answer,
+						info: stat.info
+					});
+					continue;
+				}
+				if (stat.kind === "Directory" && matchDirectories) {
+					const answer = matchedDirectoryAs(relative);
+					if (answer !== void 0) results.push({
+						path: answer,
+						info: stat.info
+					});
+				}
+				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/internal/upwardDrivers.js

@@ -0,0 +1,71 @@
+import { Effect, FileSystem } from "effect";
+
+// src/internal/upwardDrivers.ts
+/** Runs a machine against core's `FileSystem`. A machine's `Defect` dies. */
+const runUpward = (machine) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const answer = (request) => {
+		if (request._tag === "Exists") return fs.exists(request.path).pipe(Effect.orElseSucceed(() => false));
+		if (request._tag === "Present") return fs.lstat(request.path).pipe(Effect.map(() => ({ _tag: "Present" })), Effect.catch((error) => Effect.succeed(error.reason._tag === "NotFound" ? { _tag: "NotFound" } : {
+			_tag: "Failed",
+			cause: error
+		})));
+		return fs.realPath(request.path).pipe(Effect.map((value) => ({
+			_tag: "Ok",
+			value
+		})), Effect.catch((error) => Effect.succeed(error.reason._tag === "NotFound" ? {
+			_tag: "NotFound",
+			cause: error
+		} : {
+			_tag: "Failed",
+			cause: error
+		})));
+	};
+	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));
+	return result.value;
+});
+const isNotFound = (error) => typeof error === "object" && error !== null && error.code === "ENOENT";
+/** Runs a machine against a synchronous port. A machine's `Defect` throws. */
+const runUpwardSync = (machine, fileSystem) => {
+	const answer = (request) => {
+		if (request._tag === "Exists") try {
+			fileSystem.stat(request.path);
+			return true;
+		} catch {
+			return false;
+		}
+		if (request._tag === "Present") try {
+			fileSystem.lstat(request.path);
+			return { _tag: "Present" };
+		} catch (cause) {
+			return isNotFound(cause) ? { _tag: "NotFound" } : {
+				_tag: "Failed",
+				cause
+			};
+		}
+		try {
+			return {
+				_tag: "Ok",
+				value: fileSystem.realPath(request.path)
+			};
+		} catch (cause) {
+			return isNotFound(cause) ? {
+				_tag: "NotFound",
+				cause
+			} : {
+				_tag: "Failed",
+				cause
+			};
+		}
+	};
+	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);
+	return result.value;
+};
+
+export { runUpward, runUpwardSync };

package/internal/upwardMachine.js

@@ -0,0 +1,239 @@
+import { trimTrailing } from "./trimTrailing.js";
+import { isCurrentDriveRooted, isPinnedAbsolute } from "./absolute.js";
+
+// src/internal/upwardMachine.ts
+/** Asks for the real path at `path`. */
+function* realPath(path) {
+	return yield {
+		_tag: "RealPath",
+		path
+	};
+}
+/** Asks whether anything — a dangling link included — lives at `path` itself. */
+function* present(path) {
+	return yield {
+		_tag: "Present",
+		path
+	};
+}
+/** Asks whether `path` exists. */
+function* exists(path) {
+	return yield {
+		_tag: "Exists",
+		path
+	};
+}
+const done = (value) => ({
+	_tag: "Done",
+	value
+});
+const defect = (message) => ({
+	_tag: "Defect",
+	message
+});
+/**
+* The lexical chain from `start` toward the root, nearest first — `ascend`'s
+* whole algorithm. Pure: it reads no filesystem, so it is not a generator.
+* `name` prefixes the defect messages, so each public form reports itself.
+*/
+const ascendChain = (name, start, options, path) => {
+	const maxDepth = options?.maxDepth ?? 256;
+	if (!Number.isInteger(maxDepth) || maxDepth < 1) return defect(`${name}: maxDepth must be a positive integer, received ${maxDepth}`);
+	if (options?.stopAt !== void 0 && !isPinnedAbsolute(options.stopAt, path)) return defect(`${name}: 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 done(dirs);
+};
+/** The real path at `path`, or `undefined` when it cannot be resolved for any reason. */
+function* realPathOrUndefined(path) {
+	const answer = yield* realPath(path);
+	return answer._tag === "Ok" ? answer.value : void 0;
+}
+/**
+* `ascendWithin`: the lexical chain, stopped at the nearest ancestor whose real
+* path is the ceiling's. `ceiling === undefined` is `Option.none()` — the chain
+* runs to the root exactly as `ascend` gives it.
+*/
+function* ascendWithinMachine(name, start, ceiling, options, path) {
+	const maxDepth = options?.maxDepth === void 0 ? {} : { maxDepth: options.maxDepth };
+	if (ceiling === void 0) return ascendChain(name, start, maxDepth, path);
+	if (!isPinnedAbsolute(ceiling, path)) return defect(`${name}: ceiling must be an absolute path, received ${JSON.stringify(ceiling)} (ascending from ${JSON.stringify(start)})`);
+	const lexical = ascendChain(name, start, {
+		...maxDepth,
+		stopAt: ceiling
+	}, path);
+	if (lexical._tag === "Defect") return lexical;
+	const dirs = lexical.value;
+	const last = dirs.at(-1);
+	if (last !== void 0 && path.resolve(last) === path.resolve(ceiling)) return lexical;
+	const physical = yield* realPathOrUndefined(ceiling);
+	if (physical === void 0) return lexical;
+	for (let index = 0; index < dirs.length; index += 1) if ((yield* realPathOrUndefined(dirs[index] ?? "")) === physical) return done(dirs.slice(0, index + 1));
+	return lexical;
+}
+/**
+* `ascendToMarker`: the lexical chain, stopped at the nearest directory that
+* holds any of `markers`, inclusive. Probes stop at the hit — nothing above it
+* is ever touched.
+*/
+function* ascendToMarkerMachine(name, start, markers, options, path) {
+	if (markers.length === 0) return defect(`${name}: markers must name at least one entry (ascending from ${JSON.stringify(start)})`);
+	if (markers.find((marker) => marker === "") !== void 0) return defect(`${name}: a marker must be a non-empty entry name (ascending from ${JSON.stringify(start)})`);
+	const chain = ascendChain(name, start, options?.maxDepth === void 0 ? {} : { maxDepth: options.maxDepth }, path);
+	if (chain._tag === "Defect") return chain;
+	const dirs = chain.value;
+	for (let index = 0; index < dirs.length; index += 1) {
+		const dir = dirs[index] ?? "";
+		for (const marker of markers) if (yield* exists(path.join(dir, marker))) return done(dirs.slice(0, index + 1));
+	}
+	return chain;
+}
+/** `findUpward`: the first existing candidate, directory-major, or `undefined`. */
+function* findUpwardMachine(dirs, candidatesFor) {
+	const candidates = [];
+	for (const dir of dirs) candidates.push(...candidatesFor(dir));
+	for (const candidate of candidates) if (yield* exists(candidate)) return done(candidate);
+	return done(void 0);
+}
+/**
+* `findUpwardAll`: every existing candidate of the nearest directory with any
+* hit, in candidate order — that directory's candidates are ALL probed, so a
+* second hit (an ambiguity) is never hidden; nothing above it is probed.
+*/
+function* findUpwardAllMachine(dirs, candidatesFor) {
+	const expanded = dirs.map((dir) => ({
+		dir,
+		candidates: candidatesFor(dir)
+	}));
+	for (const { dir, candidates } of expanded) {
+		const found = [];
+		for (const candidate of candidates) if (yield* exists(candidate)) found.push(candidate);
+		const [first, ...rest] = found;
+		if (first !== void 0) return done({
+			dir,
+			found: [first, ...rest]
+		});
+	}
+	return done(void 0);
+}
+/** A segment of dots and spaces only, which win32 trims to nothing or to `..`. */
+const DOTS_AND_SPACES = /^[. ]+$/;
+/** A win32 reserved device name, with or without an extension, in any case. */
+const DEVICE_NAME = /^(?:con|prn|aux|nul|com[0-9\u00b9\u00b2\u00b3]|lpt[0-9\u00b9\u00b2\u00b3]|conin\$|conout\$) *(?:\..*)?$/i;
+/** A win32 drive designator at the start of a path: `C:`, `C:x`, `C:\x`. */
+const DRIVE = /^[A-Za-z]:/;
+/** Whether win32 reads a segment as something other than a plain entry (`.` and `..` are handled before). */
+const isWin32Reserved = (segment) => segment.includes(":") || DOTS_AND_SPACES.test(segment) || DEVICE_NAME.test(segment);
+/**
+* Resolve `absolute` physically, segment by segment, the way the operating
+* system would: a `..` after a link climbs out of the link's TARGET, never
+* lexically out of the link. A first `RealPath` on the whole path settles the
+* common case in one request when no `..` is present (a lexical-first
+* `realpath` — node's JS `fs.realpath` — would otherwise collapse `link/..`
+* before resolving the link). A path, or tail, that does not exist yet is
+* resolved lexically from its real existing ancestor — but `NotFound` from a
+* real-path request is NOT proof of absence: a dangling link answers it too,
+* and a write through one creates its target wherever it points. So every
+* `NotFound` segment is checked with `Present`, and only "nothing lives here"
+* continues lexically; a dangling link (or an entry that appeared between the
+* two requests) is unresolvable, its target unverified. Any failure other
+* than `NotFound` makes the path unresolvable too. Fail closed throughout.
+*/
+function* resolvePhysical(absolute, path, win32, checkSegments) {
+	let root = absolute;
+	for (let parent = path.dirname(root); parent !== root; parent = path.dirname(root)) root = parent;
+	const segments = (absolute.startsWith(root) ? absolute.slice(root.length) : absolute).split(win32 ? /[\\/]/ : "/").filter((segment) => segment !== "");
+	if (checkSegments && win32) {
+		for (const segment of segments) if (segment !== "." && segment !== ".." && isWin32Reserved(segment)) return {
+			_tag: "Refused",
+			reason: "reservedName"
+		};
+	}
+	const isSep = (character) => character === path.sep || win32 && character === "/";
+	const real = (target) => realPath(target);
+	if (!segments.includes("..")) {
+		const whole = yield* real(absolute);
+		if (whole._tag === "Ok") return whole;
+		if (whole._tag === "Failed") return {
+			_tag: "Unresolvable",
+			cause: whole.cause
+		};
+	}
+	const rootAnswer = yield* real(root);
+	if (rootAnswer._tag === "Failed") return {
+		_tag: "Unresolvable",
+		cause: rootAnswer.cause
+	};
+	let current = rootAnswer._tag === "Ok" ? rootAnswer.value : root;
+	for (const segment of segments) {
+		if (segment === ".") continue;
+		if (segment === "..") {
+			current = path.dirname(current);
+			continue;
+		}
+		const next = `${trimTrailing(current, isSep)}${path.sep}${segment}`;
+		const answer = yield* real(next);
+		if (answer._tag === "Failed") return {
+			_tag: "Unresolvable",
+			cause: answer.cause
+		};
+		if (answer._tag === "Ok") {
+			current = answer.value;
+			continue;
+		}
+		const entry = yield* present(next);
+		if (entry._tag === "Failed") return {
+			_tag: "Unresolvable",
+			cause: entry.cause
+		};
+		if (entry._tag === "Present") return {
+			_tag: "Unresolvable",
+			cause: answer.cause
+		};
+		current = next;
+	}
+	return {
+		_tag: "Ok",
+		value: current
+	};
+}
+/**
+* `confineReal`: the candidate's real path when it lies strictly inside the
+* base's real path, or why not. A relative `base` is a wiring defect.
+*/
+function* confineRealMachine(name, base, candidate, path) {
+	if (base.includes("\0") || !isPinnedAbsolute(base, path)) return defect(`${name}: base must be an absolute path, received ${JSON.stringify(base)}`);
+	const refuse = (reason) => done({
+		_tag: "Refused",
+		reason
+	});
+	if (candidate.includes("\0")) return refuse("nulByte");
+	if (candidate === "") return refuse("empty");
+	const win32 = path.sep === "\\";
+	const isSep = (character) => character === path.sep || win32 && character === "/";
+	if (win32 && DRIVE.test(candidate) && !path.isAbsolute(candidate)) return refuse("absolute");
+	if (isCurrentDriveRooted(candidate, path.sep)) return refuse("absolute");
+	const full = path.isAbsolute(candidate) ? candidate : `${trimTrailing(base, isSep)}${path.sep}${candidate}`;
+	const baseReal = yield* resolvePhysical(base, path, win32, false);
+	if (baseReal._tag !== "Ok") return done(baseReal);
+	const candidateReal = yield* resolvePhysical(full, path, win32, true);
+	if (candidateReal._tag !== "Ok") return done(candidateReal);
+	const root = trimTrailing(baseReal.value, isSep);
+	const resolved = trimTrailing(candidateReal.value, isSep);
+	if (resolved === root) return refuse("empty");
+	if (!resolved.startsWith(`${root}${path.sep}`)) return refuse("outside");
+	return done({
+		_tag: "Ok",
+		value: candidateReal.value
+	});
+}
+
+export { ascendChain, ascendToMarkerMachine, ascendWithinMachine, confineRealMachine, findUpwardAllMachine, findUpwardMachine };