@effected/walker 0.21.0 → 0.23.0

package/internal/descendMachine.js

@@ -1,5 +1,6 @@
 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`. */
@@ -9,7 +10,8 @@ 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, join) {
+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;
@@ -19,6 +21,19 @@ function* descendMachine(pattern, options, join) {
 		_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";
@@ -93,7 +108,8 @@ function* descendMachine(pattern, options, join) {
 			_tag: "Stat",
 			path: join(options.cwd, pattern.source)
 		});
-		return done(answer?.kind === "File" ? [{
+		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
 		}] : []);
@@ -122,7 +138,7 @@ function* descendMachine(pattern, options, join) {
 				canonical: canonical === "" ? "" : `${canonical}/`
 			};
 		});
-		/** The file at canonical `relative`, in the first spelling the pattern matches it under, or `undefined`. */
+		/** 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;
@@ -130,6 +146,17 @@ function* descendMachine(pattern, options, join) {
 				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("/");
@@ -137,10 +164,11 @@ function* descendMachine(pattern, options, join) {
 		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);
-		if ((yield* ask({
+		const baseStat = yield* ask({
 			_tag: "Stat",
 			path: absoluteBase
-		}))?.kind !== "Directory") return void 0;
+		});
+		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) {
@@ -149,6 +177,13 @@ function* descendMachine(pattern, options, join) {
 			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,
@@ -186,13 +221,20 @@ function* descendMachine(pattern, options, join) {
 				}) : own;
 				if (stat === void 0) continue;
 				if (stat.kind === "File") {
-					const path = matchedAs(relative);
-					if (path !== void 0) results.push({
-						path,
+					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;

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,252 @@
+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, requireExisting = false) {
+	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
+		};
+		if (requireExisting) return {
+			_tag: "Refused",
+			reason: "outside"
+		};
+		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, within = false) {
+	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");
+	if (within && !path.isAbsolute(candidate)) return refuse("absolute");
+	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, within !== false && within.requireExisting);
+	if (candidateReal._tag !== "Ok") return done(candidateReal);
+	const root = trimTrailing(baseReal.value, isSep);
+	const resolved = trimTrailing(candidateReal.value, isSep);
+	if (within && resolved === root) return done({
+		_tag: "Ok",
+		value: ""
+	});
+	if (resolved === root) return refuse("empty");
+	if (!resolved.startsWith(`${root}${path.sep}`)) return refuse("outside");
+	if (within) return done({
+		_tag: "Ok",
+		value: resolved.slice(root.length + 1).split(path.sep).join("/")
+	});
+	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.23.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": {

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.4"
+      "packageVersion": "7.60.0"
     }
   ]
 }