@effected/walker 0.21.0 → 0.22.0

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 };

package/node-sync.d.ts

@@ -43,17 +43,30 @@ interface WalkerSyncFileSystem {
   readonly realPath: (path: string) => string;
 }
 /**
- * The synchronous path operation the sync walk needs — a structural subset of
- * `node:path`, so the module itself (or its `win32` / `posix` variant)
+ * The synchronous path operations the sync forms need — a structural subset
+ * of `node:path`, so the module itself (or its `win32` / `posix` variant)
  * satisfies it. It shapes only the absolute paths handed to the
  * {@link WalkerSyncFileSystem}; matching is POSIX-relative by the glob
  * contract.
  *
+ * @remarks
+ * The members mirror core's `Path` service, so a sync form judges
+ * absoluteness, ascends and compares ceilings exactly as its `Effect` twin
+ * does under the `Path` layer of the same platform.
+ *
  * @public
  */
 interface WalkerSyncPath {
+  /** The implementation's separator (`path.sep`). */
+  readonly sep: string;
   /** Join segments with the implementation's separator (like `path.join`). */
   readonly join: (...segments: ReadonlyArray<string>) => string;
+  /** The parent directory of a path (like `path.dirname`); a fixpoint at the root. */
+  readonly dirname: (path: string) => string;
+  /** Resolve segments to a normalized path (like `path.resolve`). */
+  readonly resolve: (...segments: ReadonlyArray<string>) => string;
+  /** Whether a path is absolute under this implementation (like `path.isAbsolute`). */
+  readonly isAbsolute: (path: string) => boolean;
 }
 /**
  * The platform half of every sync walk.

package/node-sync.js

@@ -41,7 +41,13 @@ const nodeWalkerFileSystem = {
 *
 * @public
 */
-const nodeWalkerPath = { join: path.join };
+const nodeWalkerPath = {
+	sep: path.sep,
+	join: path.join,
+	dirname: path.dirname,
+	resolve: path.resolve,
+	isAbsolute: path.isAbsolute
+};
 /**
 * Both bindings, to spread into `descendSync` options.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.21.0",
+	"version": "0.22.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": [
@@ -42,7 +42,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.15.0",
+		"@effected/glob": "^0.16.0",
 		"effect": "^4.0.0"
 	},
 	"engines": {