@effected/walker 0.7.0 → 0.9.0

package/Descend.js

@@ -84,7 +84,10 @@ const descendImpl = Effect.fn("Walker.descend")(function* (pattern, options) {
 				reason: "unreadableDirectory",
 				path: frame.relative
 			}));
-			if (onUnreadable === "record") unreadable.push(frame.relative);
+			if (onUnreadable === "record") unreadable.push({
+				path: frame.relative,
+				cause: error
+			});
 			return Effect.succeed([]);
 		}));
 		for (const entry of entries) {

package/README.md

@@ -86,6 +86,7 @@ The predicate can be expensive — reading and parsing a `package.json` to decid
 - `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.
 
 ## License
 

package/index.d.ts

@@ -1,5 +1,5 @@
 import { GlobPattern, GlobPatternError, GlobPatternOptions } from "@effected/glob";
-import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { Effect, FileSystem, Option, Path, PlatformError, Schema } from "effect";
 //#region src/Descend.d.ts
 /**
  * Options for `descend`.
@@ -47,30 +47,41 @@ interface DescendRecordOptions extends Omit<DescendOptions, "onUnreadable"> {
   readonly onUnreadable: "record";
 }
 /**
- * `descend`'s success value under `onUnreadable: "record"`: the matched
- * FILE paths plus the `cwd`-relative path of every mid-walk directory whose
- * `readDirectory` failed for a reason other than `NotFound` (a vanished
- * directory stays a benign race in every mode and is never recorded).
+ * One directory `descend` could not read under `onUnreadable: "record"`: its
+ * `cwd`-relative path and the `PlatformError` that `readDirectory` failed
+ * with. The cause is the very failure the walk absorbed, so a caller that
+ * must report WHY a directory was unreadable never re-reads it.
  *
  * @public
  */
-interface DescendResult {
-  /** Matching FILE paths relative to `cwd`, POSIX separators, sorted — identical in shape to the `"fail"`/`"skip"` success value. */
-  readonly matches: ReadonlyArray<string>;
+interface UnreadableDirectory {
   /**
-   * `cwd`-relative paths of directories that could not be read, in walk order.
+   * The directory's path relative to `cwd`, POSIX separators.
    *
    * @remarks
    * **The walk base appears as the empty string `""`**, since its own
    * `cwd`-relative path is empty — so an unreadable base yields
-   * `{ matches: [], unreadable: [""] }`. Code matching these entries as
-   * ordinary paths will not expect that; special-case it.
-   *
-   * No cause travels with an entry. A caller that must report WHY a directory
-   * was unreadable has to re-read it to obtain the `PlatformError`, which is
-   * a second syscall for information this walk had and discarded.
+   * `{ matches: [], unreadable: [{ path: "", cause }] }`. Code matching
+   * these entries as ordinary paths will not expect that; special-case it.
    */
-  readonly unreadable: ReadonlyArray<string>;
+  readonly path: string;
+  /** The `readDirectory` failure, never `NotFound` (a vanished directory is a benign race and is not recorded). */
+  readonly cause: PlatformError.PlatformError;
+}
+/**
+ * `descend`'s success value under `onUnreadable: "record"`: the matched
+ * FILE paths plus an {@link UnreadableDirectory} for every mid-walk
+ * directory whose `readDirectory` failed for a reason other than `NotFound`
+ * (a vanished directory stays a benign race in every mode and is never
+ * recorded).
+ *
+ * @public
+ */
+interface DescendResult {
+  /** Matching FILE paths relative to `cwd`, POSIX separators, sorted — identical in shape to the `"fail"`/`"skip"` success value. */
+  readonly matches: ReadonlyArray<string>;
+  /** Directories that could not be read, each with its cause, in walk order. */
+  readonly unreadable: ReadonlyArray<UnreadableDirectory>;
 }
 declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<"DescendError", {
   /** The glob pattern's source text. */
@@ -95,11 +106,11 @@ export declare class DescendError extends DescendError_base {
 /**
  * Expand a compiled glob pattern against the filesystem under
  * `onUnreadable: "record"`, resolving to a {@link DescendResult} — the
- * matched FILE paths relative to `cwd` (POSIX separators, sorted) plus the
- * `cwd`-relative path of every mid-walk directory whose `readDirectory`
- * failed for a reason other than `NotFound`. The walk continues past each
- * such directory exactly as `"skip"` does; it never aborts and it never
- * discards the offending path.
+ * matched FILE paths relative to `cwd` (POSIX separators, sorted) plus an
+ * {@link UnreadableDirectory} — path and cause — for every mid-walk
+ * directory whose `readDirectory` failed for a reason other than `NotFound`.
+ * The walk continues past each such directory exactly as `"skip"` does; it
+ * never aborts and it never discards the offending path or its cause.
  *
  * @public
  */
@@ -355,5 +366,5 @@ export declare class Walker {
   static 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, CompileAndExpandOptions, DescendOptions, DescendRecordOptions, DescendResult };
+export type { AscendOptions, CompileAndExpandOptions, DescendOptions, DescendRecordOptions, DescendResult, UnreadableDirectory };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.7.0",
+	"version": "0.9.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.5.0",
-		"effect": "4.0.0-rc.112"
+		"@effected/glob": "^0.6.0",
+		"effect": "4.0.0-rc.115"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

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