@effected/walker 0.20.1 → 0.22.0

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