@effected/walker 0.2.2 → 0.3.0

package/Expand.js

@@ -0,0 +1,96 @@
+import { DescendError, descend } from "./Descend.js";
+import { Effect, Result, Schema } from "effect";
+import { GlobPattern, GlobPatternError } from "@effected/glob";
+
+//#region src/Expand.ts
+/**
+* Typed failure raised by {@link compileAndExpand}: the single error the
+* compile+expand recipe fails with, so a caller catches one tag rather than
+* folding two error channels by hand.
+*
+* @remarks
+* One tag, two genuinely different causes — "your pattern is malformed" and
+* "that directory is unreadable" are different problems with different fixes,
+* so `cause` keeps the underlying typed error intact
+* rather than flattening it into a string. Discriminate on `cause._tag`
+* (`"GlobPatternError"` vs `"DescendError"`), or read
+* {@link GlobExpansionError.stage} when only the phase matters; either way the
+* original payload — a guard's `limit`/`actual`, a descent's `path` — is still
+* there. `cause` is also the native `Error` cause, so error chaining and
+* stack-printing work without extra wiring.
+*
+* @public
+*/
+var GlobExpansionError = class extends Schema.TaggedErrorClass()("GlobExpansionError", {
+	/** The glob pattern's source text, as handed to {@link compileAndExpand}. */
+	pattern: Schema.String,
+	/** The underlying typed failure, intact: a compile guard trip or a descent failure. */
+	cause: Schema.Union([GlobPatternError, DescendError])
+}) {
+	/**
+	* Which phase failed — `"compile"` when the pattern itself was rejected,
+	* `"descend"` when the filesystem walk failed. A convenience over
+	* `cause._tag` for callers that only need the phase.
+	*/
+	get stage() {
+		return this.cause._tag === "GlobPatternError" ? "compile" : "descend";
+	}
+	get message() {
+		const shown = this.pattern.length > 64 ? `${this.pattern.slice(0, 64)}…` : this.pattern;
+		return `glob expansion of ${JSON.stringify(shown)} failed during ${this.stage}: ${this.cause.message}`;
+	}
+};
+/**
+* Compile a glob pattern and expand it against the filesystem in one call:
+* matching FILE paths relative to `options.cwd`, POSIX separators, sorted.
+*
+* @remarks
+* The recipe form of {@link descend}. Everything `descend` documents about
+* traversal holds unchanged — the literal fast-path, the negated-pattern walk
+* from `cwd`, files-only matching, symlink and prune handling, `maxDepth`,
+* `onUnreadable` — because this delegates to it. What this adds is the seam:
+* the pattern arrives as a string, and both failure modes arrive as one
+* {@link GlobExpansionError} with the underlying error preserved in `cause`.
+*
+* A missing base directory, a pattern that climbs above `cwd`, and a pattern
+* that simply matches nothing are all an EMPTY result, not a failure — zero
+* matches is a normal glob answer. Only a rejected pattern or a failed walk
+* produces an error.
+*
+* `FileSystem` and `Path` stay in the `R` channel and are **deliberately not
+* provided here**, even though hand-providing them is the friction this
+* recipe otherwise removes. `FileSystem` cannot be provided — a library that
+* picks its own filesystem cannot be tested against a fixture tree. Given
+* that, providing `Path` internally would not save the caller a layer (they
+* still supply `FileSystem`), and it would actively break win32: the walk
+* would join paths POSIX-style against a caller's win32 filesystem. The
+* consumer's platform layer stays the single place that choice is made.
+* Provide both once at the application boundary, not per call site.
+*
+* @example
+* ```ts
+* import { compileAndExpand } from "@effected/walker"
+* import { GlobPatternOptions } from "@effected/glob"
+*
+* const files = yield* compileAndExpand("packages/*​/src/**​/*.ts", {
+*   cwd: "/repo",
+*   glob: GlobPatternOptions.make({ dot: true })
+* })
+* ```
+*
+* @public
+*/
+const compileAndExpand = Effect.fn("Walker.compileAndExpand")(function* (pattern, options) {
+	const compiled = GlobPattern.compileResult(pattern, options.glob);
+	if (Result.isFailure(compiled)) return yield* new GlobExpansionError({
+		pattern,
+		cause: compiled.failure
+	});
+	return yield* descend(compiled.success, options).pipe(Effect.mapError((cause) => new GlobExpansionError({
+		pattern,
+		cause
+	})));
+});
+
+//#endregion
+export { GlobExpansionError, compileAndExpand };

package/README.md

@@ -82,7 +82,7 @@ The predicate can be expensive — reading and parsing a `package.json` to decid
 
 ## Features
 
-- `Walker.ascend(start, options?)` — the directory chain from `start` toward the filesystem root, nearest first. `stopAt` halts the ascent inclusively, `maxDepth` (default 256) caps it. Lexical, not physical: `Path.dirname` does not resolve symlinks, so ascending out of a symlinked directory follows the path you were given.
+- `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.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.

package/Walker.js

@@ -14,17 +14,28 @@ import { Effect, FileSystem, Option, Path } from "effect";
 * Bounded twice over: `dirname` is a fixpoint at the root, and `maxDepth` guards
 * a pathological `Path` implementation that never reaches one.
 *
+* `stopAt` is compared in normalized form — see {@link AscendOptions.stopAt}.
+* Raw string equality made the ceiling fail OPEN: an unnormalized ceiling
+* matched nothing and the ascent ran silently to the filesystem root, which is
+* the unbounded walk the option exists to prevent, with no error to notice it
+* by. A relative ceiling **dies** for the same reason — resolving one against
+* `process.cwd()` would reintroduce the silent-wrong-walk failure through a
+* different door. See {@link AscendOptions.stopAt} for why that is a defect
+* rather than a typed error; the error channel stays `never`.
+*
 * @public
 */
 const ascend = (start, options) => 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 (options?.stopAt !== void 0 && current === options.stopAt) break;
+		if (ceiling !== void 0 && (current === ceiling || path.resolve(current) === ceiling)) break;
 		const parent = path.dirname(current);
 		if (parent === current) break;
 		current = parent;

package/index.d.ts

@@ -1,4 +1,4 @@
-import { GlobPattern } from "@effected/glob";
+import { GlobPattern, GlobPatternError, GlobPatternOptions } from "@effected/glob";
 import { Effect, FileSystem, Option, Path, Schema } from "effect";
 //#region src/Descend.d.ts
 /**
@@ -75,6 +75,104 @@ declare class DescendError extends DescendError_base {
  */
 declare const descend: (pattern: GlobPattern, options: DescendOptions) => Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
 //#endregion
+//#region src/Expand.d.ts
+/**
+ * Options for {@link compileAndExpand}: every {@link DescendOptions} field,
+ * plus the glob options the pattern compiles under.
+ *
+ * @public
+ */
+interface CompileAndExpandOptions extends DescendOptions {
+  /**
+   * The options the pattern compiles under — **required, deliberately**.
+   *
+   * @remarks
+   * Matching semantics (`dot` above all) are the thing two call sites most
+   * easily disagree about, and an optional field invites exactly that: one
+   * site passes `{ dot: true }`, another omits it, and the same package now
+   * has two glob dialects that nothing makes visible. Required means every
+   * call site states its dialect in its own source, so a divergence is a
+   * visible difference between two spellings rather than the absence of one.
+   * Pass `GlobPatternOptions.make({})` to mean "the defaults" — that is a
+   * deliberate choice being written down, not boilerplate.
+   */
+  readonly glob: GlobPatternOptions;
+}
+declare const GlobExpansionError_base: Schema.Class<GlobExpansionError, Schema.TaggedStruct<"GlobExpansionError", {
+  /** The glob pattern's source text, as handed to {@link compileAndExpand}. */
+  readonly pattern: Schema.String;
+  /** The underlying typed failure, intact: a compile guard trip or a descent failure. */
+  readonly cause: Schema.Union<readonly [typeof GlobPatternError, typeof DescendError]>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Typed failure raised by {@link compileAndExpand}: the single error the
+ * compile+expand recipe fails with, so a caller catches one tag rather than
+ * folding two error channels by hand.
+ *
+ * @remarks
+ * One tag, two genuinely different causes — "your pattern is malformed" and
+ * "that directory is unreadable" are different problems with different fixes,
+ * so `cause` keeps the underlying typed error intact
+ * rather than flattening it into a string. Discriminate on `cause._tag`
+ * (`"GlobPatternError"` vs `"DescendError"`), or read
+ * {@link GlobExpansionError.stage} when only the phase matters; either way the
+ * original payload — a guard's `limit`/`actual`, a descent's `path` — is still
+ * there. `cause` is also the native `Error` cause, so error chaining and
+ * stack-printing work without extra wiring.
+ *
+ * @public
+ */
+declare class GlobExpansionError extends GlobExpansionError_base {
+  /**
+   * Which phase failed — `"compile"` when the pattern itself was rejected,
+   * `"descend"` when the filesystem walk failed. A convenience over
+   * `cause._tag` for callers that only need the phase.
+   */
+  get stage(): "compile" | "descend";
+  get message(): string;
+}
+/**
+ * Compile a glob pattern and expand it against the filesystem in one call:
+ * matching FILE paths relative to `options.cwd`, POSIX separators, sorted.
+ *
+ * @remarks
+ * The recipe form of {@link descend}. Everything `descend` documents about
+ * traversal holds unchanged — the literal fast-path, the negated-pattern walk
+ * from `cwd`, files-only matching, symlink and prune handling, `maxDepth`,
+ * `onUnreadable` — because this delegates to it. What this adds is the seam:
+ * the pattern arrives as a string, and both failure modes arrive as one
+ * {@link GlobExpansionError} with the underlying error preserved in `cause`.
+ *
+ * A missing base directory, a pattern that climbs above `cwd`, and a pattern
+ * that simply matches nothing are all an EMPTY result, not a failure — zero
+ * matches is a normal glob answer. Only a rejected pattern or a failed walk
+ * produces an error.
+ *
+ * `FileSystem` and `Path` stay in the `R` channel and are **deliberately not
+ * provided here**, even though hand-providing them is the friction this
+ * recipe otherwise removes. `FileSystem` cannot be provided — a library that
+ * picks its own filesystem cannot be tested against a fixture tree. Given
+ * that, providing `Path` internally would not save the caller a layer (they
+ * still supply `FileSystem`), and it would actively break win32: the walk
+ * would join paths POSIX-style against a caller's win32 filesystem. The
+ * consumer's platform layer stays the single place that choice is made.
+ * Provide both once at the application boundary, not per call site.
+ *
+ * @example
+ * ```ts
+ * import { compileAndExpand } from "@effected/walker"
+ * import { GlobPatternOptions } from "@effected/glob"
+ *
+ * const files = yield* compileAndExpand("packages/*​/src/**​/*.ts", {
+ *   cwd: "/repo",
+ *   glob: GlobPatternOptions.make({ dot: true })
+ * })
+ * ```
+ *
+ * @public
+ */
+declare const compileAndExpand: (pattern: string, options: CompileAndExpandOptions) => Effect.Effect<ReadonlyArray<string>, GlobExpansionError, FileSystem.FileSystem | Path.Path>;
+//#endregion
 //#region src/Walker.d.ts
 /**
  * Options for {@link Walker.ascend}.
@@ -82,7 +180,46 @@ declare const descend: (pattern: GlobPattern, options: DescendOptions) => Effect
  * @public
  */
 interface AscendOptions {
-  /** Stop after this directory, inclusive. */
+  /**
+   * Stop after this directory, inclusive.
+   *
+   * **Must be absolute**, and is **normalized before comparison**. The ceiling
+   * is matched against each directory's `Path.resolve` form rather than by raw
+   * string equality, so a trailing separator, a `.` or `..` segment, or a
+   * duplicated separator all stop at the ancestor they name. Normalization is
+   * idempotent — an already-resolved absolute path is unchanged — so callers
+   * that resolve at the call site are unaffected.
+   *
+   * A **relative** ceiling is a **defect**, not a typed failure, and is never
+   * resolved against the process working directory. Two rules meet here:
+   *
+   * - Malformed *input* fails typed; bad *wiring* dies. A relative ceiling is
+   *   a caller-supplied option that is statically wrong at the call site — the
+   *   same category as a `NaN` `maxDepth` just below, not a recoverable
+   *   environmental condition — so it dies exactly as that does.
+   * - **Do not "upgrade" this to a typed error.** A typed error is only loud
+   *   if somebody handles it, and `@effected/config-file`'s resolver contract
+   *   absorbs every failure into `Option.none()`. A typed ceiling rejection
+   *   would be swallowed there and re-emerge as a clean-looking "no config
+   *   found" — the silent-wrong-answer failure this whole guard exists to
+   *   close, reappearing through a third door. `Effect.catch` does not catch
+   *   defects, so dying is what survives that absorption.
+   *
+   * Resolving a relative ceiling would be just as bad: the same `stopAt` would
+   * name different directories in a lint-staged hook, a CLI run from a package
+   * directory, and a test runner, with no way for the caller to see which they
+   * got. Rejecting costs one `path.resolve` at the site that knows the answer.
+   * It is also why `ascend` reads `process.cwd()` nowhere.
+   *
+   * Only the CEILING is constrained — a relative `start` is fine and ascends
+   * to the relative root. Absoluteness is judged by the injected `Path`
+   * service, so the win32 layer accepts `C:\repo` and posix does not.
+   *
+   * Normalization governs the comparison only: the chain `ascend` returns is
+   * 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.
+   */
   readonly stopAt?: string;
   /** Hard cap on chain length. Defaults to 256. */
   readonly maxDepth?: number;
@@ -99,5 +236,5 @@ declare const Walker: {
   readonly findRoot: <E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>) => Effect.Effect<Option.Option<string>, never, R>;
 };
 //#endregion
-export { type AscendOptions, DescendError, type DescendOptions, Walker, descend };
+export { type AscendOptions, type CompileAndExpandOptions, DescendError, type DescendOptions, GlobExpansionError, Walker, compileAndExpand, descend };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,4 +1,5 @@
 import { DescendError, descend } from "./Descend.js";
+import { GlobExpansionError, compileAndExpand } from "./Expand.js";
 import { Walker } from "./Walker.js";
 
-export { DescendError, Walker, descend };
+export { DescendError, GlobExpansionError, Walker, compileAndExpand, descend };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.2.2",
+	"version": "0.3.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,7 +37,7 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "0.1.2",
+		"@effected/glob": "0.2.0",
 		"effect": "4.0.0-beta.99"
 	},
 	"engines": {