@effected/walker 0.12.0 → 0.14.0

package/README.md

@@ -82,11 +82,19 @@ The predicate can be expensive — reading and parsing a `package.json` to decid
 
 ## Features
 
+The upward walk lives on the `Walker` class as statics; the downward walk is two free-standing functions. Import them side by side — there is no `Walker.descend`:
+
+```ts
+import { Walker, compileAndExpand, descend } from "@effected/walker";
+```
+
 - `Walker.ascend(start, options?)` — the directory chain from `start` toward the filesystem root, nearest first. `stopAt` halts the ascent inclusively — it must be absolute, and is matched in normalized form, so a trailing separator or a `.`/`..` segment still stops where it names; a relative ceiling is a defect rather than being resolved against the working directory, exactly as an invalid `maxDepth` is. `maxDepth` (default 256) caps the chain. Lexical, not physical: `Path.dirname` does not resolve symlinks, so ascending out of a symlinked directory follows the path you were given.
+- `Walker.ascendWithin(start, ceiling, options?)` — `ascend` bounded by a physical ceiling, passed as an `Option<string>` so an unbounded walk is only ever asked for explicitly (`Option.none()` behaves exactly like `ascend(start)`, the answer outside any repository): it stops at the nearest directory whose real path is the ceiling's real path. Reach for it when the ceiling resolves symlinks — `Git.repoRoot` does — because `ascend`'s lexical `stopAt` never matches such a ceiling from a start reached through a symlink (every macOS tmpdir, any symlinked checkout), and the ascent runs to the filesystem root. The chain stays lexical; a ceiling the chain already spells costs no I/O, and an ancestor whose `realPath` fails is absorbed as "not the ceiling".
 - `Walker.firstMatch(candidates, predicate)` — the first candidate the predicate accepts. Absorbs each predicate failure individually and short-circuits at the first match.
 - `Walker.findUpward(dirs, candidatesFor)` — the first existing path, directory-major: every candidate in the nearest directory is tried before ascending.
 - `Walker.findRoot(dirs, isRoot)` — the nearest directory a marker predicate accepts. `firstMatch` where the candidate expansion is the identity.
 - `descend(pattern, options)` — the file paths a compiled `@effected/glob` pattern selects under `cwd`, POSIX separators, sorted. `onUnreadable` decides what an unreadable directory mid-walk means: `"fail"` (the default) raises a typed `DescendError`, `"skip"` continues past it and forgets it, and `"record"` continues past it and returns a `DescendResult` — `{ matches, unreadable }`, where each `UnreadableDirectory` carries the directory's `cwd`-relative `path` and the `PlatformError` it failed with, so a report never has to re-read the directory to learn why. The walk base records as `path: ""`, and a directory that vanished mid-walk (`NotFound`) is a benign race, never recorded. `followSymlinks` (default `false`) decides symlinked directories: by default they are never entered (cycle safety); under `true` they are descended under `@actions/glob`'s `traversalChain` cycle guard — a directory is a cycle only when its real path is already an ancestor of the current branch, so link loops terminate while two sibling links resolving to the same target both enumerate; a link whose real path cannot be resolved is never entered, and that failure follows `onUnreadable` exactly as an unreadable directory does — matching `@actions/glob`'s default `followSymbolicLinks: true` (Node's recursive `readdir` also follows links, but keeps no traversal chain and recurses without bound on a loop).
+- `compileAndExpand(pattern, options)` — `descend` from a glob **string**: compiles it with `@effected/glob` (`options.glob`) and expands it, failing typed with `GlobExpansionError` when the pattern does not compile.
 
 ## License
 

package/Walker.js

@@ -18,6 +18,25 @@ const ascend = (start, options) => Effect.gen(function* () {
 	}
 	return dirs;
 });
+const ascendWithin = (start, ceiling, options) => Effect.gen(function* () {
+	if (Option.isNone(ceiling)) return yield* ascend(start, options);
+	return yield* ascendToPhysical(start, ceiling.value, options);
+});
+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* 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* 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;
+});
 const firstMatch = (candidates, predicate) => Effect.gen(function* () {
 	for (const candidate of candidates) if (yield* Effect.catch(predicate(candidate), () => Effect.succeed(false))) return Option.some(candidate);
 	return Option.none();
@@ -60,6 +79,34 @@ var Walker = class {
 	*/
 	static ascend = ascend;
 	/**
+	* {@link Walker.ascend} bounded by a PHYSICAL ceiling: stops at the nearest
+	* directory whose real path is the ceiling's real path, inclusive.
+	*
+	* @remarks
+	* Use this when the ceiling came from something that resolves symlinks —
+	* `Git.repoRoot` (`git rev-parse --show-toplevel`) above all. `ascend`
+	* compares `stopAt` lexically, so when `start` is reached through a symlink
+	* (every macOS tmpdir: `/var` → `/private/var`; any symlinked checkout) the
+	* chain never spells git's root, the ceiling never matches, and the walk
+	* runs silently to the filesystem root.
+	*
+	* The chain is still the lexical one derived from `start`, exactly as
+	* `ascend` yields it; only the stopping test is physical. A ceiling the
+	* chain already spells stops without touching the filesystem. Otherwise each
+	* ancestor's `realPath` is compared with the ceiling's, and a failed probe
+	* is absorbed as "not the ceiling", as {@link Walker.firstMatch} absorbs
+	* one. A ceiling that names no ancestor, or cannot itself be resolved,
+	* leaves the chain running to the filesystem root, as `ascend` does.
+	*
+	* The ceiling is an `Option` so "no ceiling" is spelled explicitly:
+	* `Option.none()` ascends to the filesystem root exactly as `ascend(start)`
+	* does, which is the natural answer outside any repository —
+	* `Walker.ascendWithin(start, yield* Effect.option(git.repoRoot(start)))`.
+	* A present ceiling must be absolute; a relative one **dies**, for the
+	* reasons {@link AscendOptions.stopAt} gives.
+	*/
+	static ascendWithin = ascendWithin;
+	/**
 	* The first candidate whose `predicate` reports true, or `Option.none()`.
 	*
 	* @remarks

package/index.d.ts

@@ -330,6 +330,11 @@ interface AscendOptions {
    * still the lexical one derived from `start`, unrewritten. A ceiling naming
    * no ancestor of `start` never matches and the ascent runs to the
    * filesystem root.
+   *
+   * **Lexical, never physical.** A ceiling spelled with symlinks resolved —
+   * `Git.repoRoot`'s answer is one — does not match a chain reached through a
+   * symlink, and the ascent runs to the filesystem root. Use
+   * {@link Walker.ascendWithin} for a physical ceiling.
    */
   readonly stopAt?: string;
   /** Hard cap on chain length. Defaults to 256. */
@@ -365,6 +370,34 @@ export declare class Walker {
    * rather than a typed error; the error channel stays `never`.
    */
   static readonly ascend: (start: string, options?: AscendOptions) => Effect.Effect<ReadonlyArray<string>, never, Path.Path>;
+  /**
+   * {@link Walker.ascend} bounded by a PHYSICAL ceiling: stops at the nearest
+   * directory whose real path is the ceiling's real path, inclusive.
+   *
+   * @remarks
+   * Use this when the ceiling came from something that resolves symlinks —
+   * `Git.repoRoot` (`git rev-parse --show-toplevel`) above all. `ascend`
+   * compares `stopAt` lexically, so when `start` is reached through a symlink
+   * (every macOS tmpdir: `/var` → `/private/var`; any symlinked checkout) the
+   * chain never spells git's root, the ceiling never matches, and the walk
+   * runs silently to the filesystem root.
+   *
+   * The chain is still the lexical one derived from `start`, exactly as
+   * `ascend` yields it; only the stopping test is physical. A ceiling the
+   * chain already spells stops without touching the filesystem. Otherwise each
+   * ancestor's `realPath` is compared with the ceiling's, and a failed probe
+   * is absorbed as "not the ceiling", as {@link Walker.firstMatch} absorbs
+   * one. A ceiling that names no ancestor, or cannot itself be resolved,
+   * leaves the chain running to the filesystem root, as `ascend` does.
+   *
+   * The ceiling is an `Option` so "no ceiling" is spelled explicitly:
+   * `Option.none()` ascends to the filesystem root exactly as `ascend(start)`
+   * does, which is the natural answer outside any repository —
+   * `Walker.ascendWithin(start, yield* Effect.option(git.repoRoot(start)))`.
+   * A present ceiling must be absolute; a relative one **dies**, for the
+   * reasons {@link AscendOptions.stopAt} gives.
+   */
+  static readonly ascendWithin: (start: string, ceiling: Option.Option<string>, options?: Pick<AscendOptions, "maxDepth">) => Effect.Effect<ReadonlyArray<string>, never, FileSystem.FileSystem | Path.Path>;
   /**
    * The first candidate whose `predicate` reports true, or `Option.none()`.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.12.0",
+	"version": "0.14.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": [
@@ -37,8 +37,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.8.0",
-		"effect": "4.0.0-rc.117"
+		"@effected/glob": "^0.9.0",
+		"effect": "4.0.0-rc.118"
 	},
 	"engines": {
 		"node": ">=24.11.0"