// Downward glob-file descent — walker's second concept module, and the first // with a typed error channel. // // `@effected/glob` is a pure matching engine (no filesystem walker), and the // workspaces enumerator is internal and package-dir-specific, so "files // matching a glob under a directory" lives here. The walker is semantics-free: // dotfile behavior, case folding and every other matching option are carried // by the COMPILED pattern the caller hands in — this module never re-derives // options, it only reads `hasMagic` / `negated` / `enumerationRoots` and calls // `matches`. import type { GlobPattern } from "@effected/glob"; import type { PlatformError } from "effect"; import { Effect, FileSystem, Path, Schema } from "effect"; import type { DescendRequest, LstatAnswer, ReadAnswer, StatAnswer } from "./internal/descendMachine.js"; import { descendMachine, failureOf } from "./internal/descendMachine.js"; /** * Options for `descend`. * * @public */ export interface DescendOptions { /** * Absolute directory the pattern is resolved against. Required — walker * never reads `process.cwd()`. * * @remarks * **A missing `cwd` is an empty result, never a failure**: when `cwd` does * not exist, is a file, or is a dangling link, every pattern — literal or * magic — answers zero matches (`[]`, or `{ matches: [], unreadable: [] }` * under `"record"`), in the `Effect` and the sync forms alike. Zero * matches is a normal glob answer, so a caller that must tell "nothing * matched" from "there was nothing to look in" checks `cwd` itself first. * The same holds for a pattern's literal base below `cwd`. Only an * unreadable directory the walk does reach fails, under `"fail"`. * * **A relative `cwd` — the empty string included — is a defect**: the * `Effect` forms die and the sync forms throw. A relative directory would * resolve against the process working directory, so the same call would * walk different trees from a hook, a CLI and a test runner, and on win32 * an empty `cwd` joined with a pattern spelled `C:/x` is the drive path * `C:\x`. Absoluteness is judged by the injected `Path` (or the sync port's * `isAbsolute`), so win32 accepts `C:\repo` and `\\server\share`; a * win32 `\repo` names the root of whichever drive the process is on, so * it dies as a relative `cwd` does. */ readonly cwd: string; /** * Which entry kinds match. `"file"` (the default) answers files only, as * `descend` always has; `"directory"` answers directories only; `"any"` * answers both. * * @remarks * The kind is the RESOLVED one — links followed, as for files — so a link * to a directory matches as a directory, even where `followSymlinks: false` * keeps the walk from entering it, and even when its target lies outside * `cwd`. Check such an entry with `confineReal` before acting on it. A * directory matches as an entry of its parent: `prune`, a boundary and an * unentered link withhold what lies below a directory, never the * directory itself, so a globstar pattern for `node_modules` finds every * `node_modules` under the default `prune` without reading inside one. A directory is tested bare * and with a trailing `/`, so the directory-only glob form `dist/` * matches, answered as spelled. `cwd` itself is never a match. */ readonly match?: "file" | "directory" | "any"; /** * Hard cap on directory depth below the pattern's literal prefix. Defaults to 256. * * @remarks * It applies to the directories the walk reads, and the pattern decides * which those are: a pattern with no globstar is never read below the * depth its segments reach, so `packages/{a,b}/README.md` under a cap of 1 * does not fail on a deep tree below `packages/a` it has no reason to enter. * Going past the cap where a match could lie is still a typed * `depthExceeded` failure, never a truncation. */ readonly maxDepth?: number; /** Directory names never descended into. Defaults to `["node_modules", ".git"]`; a custom list replaces the default. */ readonly prune?: ReadonlyArray; /** * Marker FILE names that make a directory a boundary — a nested unit (another * package, say: `["package.json"]`) whose contents belong to a separate walk. * * @remarks * A directory strictly below `cwd` holding a FILE with one of these names * contributes nothing: none of its files match and its subtree is never * descended. `cwd` itself is never a boundary, and a DIRECTORY named like a * marker does not count. The rule is about where a file sits, not how the * walk reached it, so it applies to a walk that starts below `cwd` (the * pattern's literal prefix) and to a literal pattern alike: a boundary * between `cwd` and the walk base, or between `cwd` and a literal file, * also answers zero matches. Each directory pays one stat per marker it * actually lists. Defaults to none. Not to be confused with * `Walker.ascend`'s `stopAt`, an inclusive upward ceiling. */ readonly boundaries?: ReadonlyArray; /** * What an unreadable directory mid-walk does. `"fail"` (the default) fails * typed — downward enumeration must not silently swallow a subtree, or the * answer is silently missing membership dressed as an empty one. `"skip"` * absorbs the failure and continues, discarding which directory it was. * To collect the offending directories instead of discarding them, pass * {@link DescendRecordOptions} — `"record"` is deliberately NOT a member * here, because this type is the options contract of the overload that * returns a bare match array. */ readonly onUnreadable?: "fail" | "skip"; /** * Whether to descend into symlinked directories. Defaults to `false`: a * symlinked directory is never entered (cycle safety) — the walk base, and * every directory on the way to it, included: a base reached through a link * is an empty result. Under `true` links * are followed with the cycle guard kept underneath, in `@actions/glob`'s * `traversalChain` semantics: each descended directory records its real * path on its own branch's ancestor chain (only the base and each link pay * a `FileSystem.realPath`; a plain directory's is derived from its * parent's), and a directory whose real path is already an ancestor of the * current branch closes a cycle and is skipped — 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 the * failure follows `onUnreadable` exactly as an unreadable directory does: * `NotFound` is a benign race and stays silent, anything else fails typed * by default, is recorded under `"record"`, and is forgotten under * `"skip"`. Following links matches `@actions/glob`'s default * `followSymbolicLinks: true` and Node's recursive * `fs.promises.readdir` — but the cycle guard is `@actions/glob`'s * alone: Node's recursive `readdir` keeps no traversal chain and recurses * without bound on a link loop. */ readonly followSymlinks?: boolean; } /** * Options for `descend` under `onUnreadable: "record"`: every * {@link DescendOptions} field, with `onUnreadable` fixed to `"record"`. * * @remarks * A separate type rather than `DescendOptions & { onUnreadable: "record" }`, * because the two options types are the discriminator between two different * RETURN types. If `DescendOptions` itself admitted `"record"`, a value * widened to `DescendOptions` — annotated as such, or passed through a * function taking it — would select the array-returning overload at compile * time while the implementation resolved a {@link DescendResult} at runtime, * and every array method on that result would fail with no type error * anywhere. Keeping `"record"` out of `DescendOptions` makes that * unrepresentable. * * @public */ export interface DescendRecordOptions extends Omit { /** Collect every unreadable directory rather than failing or discarding it. */ readonly onUnreadable: "record"; } /** * One directory `descend` could not read under `onUnreadable: "record"`: its * `cwd`-relative path and the `PlatformError` that `readDirectory` — or, * for a symlinked directory under `followSymlinks`, `realPath` — 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 */ export interface UnreadableDirectory { /** * 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: [{ path: "", cause }] }`. Code matching * these entries as ordinary paths will not expect that; special-case it. */ readonly path: string; /** The `readDirectory` (or, for a link under `followSymlinks`, `realPath`) failure, never `NotFound` (a vanished directory is a benign race and is not recorded). */ readonly cause: C; } /** * `descend`'s success value under `onUnreadable: "record"`: the matched * FILE paths plus an {@link UnreadableDirectory} for every mid-walk * directory whose `readDirectory` (or, under `followSymlinks`, a symlinked * directory whose `realPath`) failed for a reason other than `NotFound` (a * vanished directory stays a benign race in every mode and is never * recorded). * * @public */ export interface DescendResult { /** Matching FILE paths relative to `cwd`, POSIX separators, sorted — identical in shape to the `"fail"`/`"skip"` success value. */ readonly matches: ReadonlyArray; /** Directories that could not be read, each with its cause, in walk order. */ readonly unreadable: ReadonlyArray>; } /** * Typed failure raised by `descend`: a directory mid-walk was unreadable * (under `onUnreadable: "fail"`), or the walk descended past `maxDepth`. Depth * exhaustion is a typed failure, never a truncation — silent truncation * silently changes match semantics. * * @public */ export class DescendError extends Schema.TaggedError()("DescendError", { /** The glob pattern's source text. */ pattern: Schema.String, /** Why the walk failed: a directory could not be read, or the walk went past `maxDepth`. */ reason: Schema.Literals(["unreadableDirectory", "depthExceeded"]), /** The offending directory, relative to `cwd` (`""` is the walk's base). */ path: Schema.String, /** The depth cap, present when `reason` is `"depthExceeded"`. */ limit: Schema.optionalKey(Schema.Number), }) { override get message(): string { const where = this.path === "" ? "the base directory" : JSON.stringify(this.path); return this.reason === "depthExceeded" ? `glob descent for ${JSON.stringify(this.pattern)} descended past ${this.limit ?? "the depth cap"} levels below ${where}` : `glob descent for ${JSON.stringify(this.pattern)} could not read ${where}`; } } /** * One matched entry — a file, or under `match` a directory — with the stat * the walk already read for it: `descendEntries`' element. Costs no syscall beyond `descend`'s: the walk stats every entry to * classify it, and this keeps the answer instead of discarding it. * * The type parameter is the stat's type, so the sync walk reuses this shape * with its port's stats. * * @public */ export interface DescendEntry { /** The entry's path relative to `cwd`, POSIX separators. */ readonly path: string; /** `FileSystem.stat` of the file — links followed, so a symlinked file reports its target. */ readonly info: I; } /** * `descendEntries`' success value under `onUnreadable: "record"`: the matched * {@link DescendEntry} values plus every {@link UnreadableDirectory}, exactly * as {@link DescendResult} carries them for `descend`. * * @public */ export interface DescendEntriesResult { /** Matching files with their stats, sorted by path. */ readonly matches: ReadonlyArray>; /** Directories that could not be read, each with its cause, in walk order. */ readonly unreadable: ReadonlyArray>; } /** * The one options shape spanning all three modes. Not exported: the PUBLIC * types are deliberately split so `"record"` cannot reach the array-returning * overload, and this internal union is what the single implementation body * needs in order to still branch on all three values. */ type DescendAnyOptions = Omit & { readonly onUnreadable?: "fail" | "skip" | "record"; }; const kindOf = (info: FileSystem.File.Info): "File" | "Directory" | "Other" => info.type === "File" ? "File" : info.type === "Directory" ? "Directory" : "Other"; /** * The `Effect` driver of the shared walk (`internal/descendMachine.ts`): each * request the walk yields is answered through core's `FileSystem`, joins * through `Path`. Every rule lives in the machine; the sync driver in * `DescendSync.ts` answers the same requests from a synchronous port. */ const walk = ( pattern: GlobPattern, options: DescendAnyOptions, ): Effect.Effect< { readonly entries: ReadonlyArray; readonly unreadable: ReadonlyArray; }, DescendError, FileSystem.FileSystem | Path.Path > => Effect.gen(function* () { const fs = yield* FileSystem.FileSystem; const path = yield* Path.Path; const read = (effect: Effect.Effect) => effect.pipe( Effect.map((value): ReadAnswer => ({ _tag: "Ok", value })), Effect.catch((error) => Effect.succeed>( error.reason._tag === "NotFound" ? { _tag: "NotFound" } : { _tag: "Failed", cause: error }, ), ), ); const answer = (request: DescendRequest): Effect.Effect => { switch (request._tag) { case "Stat": // `stat` follows links, as node's does; anything that does not // resolve (missing, dangling, unstatable) is "no entry". return fs.stat(request.path).pipe( Effect.map((info): StatAnswer => ({ kind: kindOf(info), info })), Effect.orElseSucceed((): StatAnswer => undefined), ); case "Lstat": // A link is reported as one, without its target; anything // unstatable is "no entry". return fs.lstat(request.path).pipe( Effect.map( (info): LstatAnswer => info.type === "SymbolicLink" ? { kind: "SymbolicLink" } : { kind: kindOf(info), info }, ), Effect.orElseSucceed((): LstatAnswer => undefined), ); case "RealPath": return read(fs.realPath(request.path)); case "ReadDirectory": return read(fs.readDirectory(request.path)); } }; const machine = descendMachine(pattern, options, { sep: path.sep, join: (a, b) => path.join(a, b), isAbsolute: (p) => path.isAbsolute(p), }); 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)); if (result._tag === "Fail") { return yield* new DescendError(failureOf(pattern, result)); } return { entries: result.entries, unreadable: result.unreadable }; }); /** Not exported — `descend`'s overloads below carry the public documentation. */ const descendImpl = Effect.fn("Walker.descend")(function* (pattern: GlobPattern, options: DescendAnyOptions) { const { entries, unreadable } = yield* walk(pattern, options); const matches = entries.map((entry) => entry.path); return options.onUnreadable === "record" ? ({ matches, unreadable } satisfies DescendResult) : matches; }); /** Not exported — `descendEntries`' overloads below carry the public documentation. */ const descendEntriesImpl = Effect.fn("Walker.descendEntries")(function* ( pattern: GlobPattern, options: DescendAnyOptions, ) { const { entries, unreadable } = yield* walk(pattern, options); return options.onUnreadable === "record" ? ({ matches: entries, unreadable } satisfies DescendEntriesResult) : entries; }); /** * 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 an * {@link UnreadableDirectory} — path and cause — for every mid-walk * directory whose `readDirectory` (or, under `followSymlinks`, a symlinked * directory whose `realPath`) 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 */ export function descend( pattern: GlobPattern, options: DescendRecordOptions, ): Effect.Effect; /** * Expand a compiled glob pattern against the filesystem, returning matching * FILE paths relative to `cwd` (POSIX separators), sorted by relative path — * or, under `match: "directory"` or `"any"`, directory paths too. * * @remarks * A path is answered in the spelling the pattern matched it under: `./src/*.ts` * answers `./src/a.ts`, and `src/*.ts` answers `src/a.ts`. A file several * brace alternatives match under different spellings (`{src,./src}/*.ts`) is * answered once, in the spelling of the earliest of them in pattern order. A * literal pattern (no magic, not negated) fast-paths to a single stat of the * path glob compiled it to — escapes undone (`src/\x/f.js` is `src/x/f.js`), * and at optimization level 1 and up a `

/..` popped, as glob matches it — * answered in that spelling when it resolves to a file, `[]` otherwise: a * missing path is zero matches, not an error. A `.`, `..` or empty segment * left in that path resolves as a real stat does, only after a real * directory, so `f.js/x/..` at level 0 is `[]` where a lexical join would * reach `f.js`. A magic pattern walks each of its * `GlobPattern.enumerationRoots`, reading each directory once however many * alternatives spell it; a NEGATED pattern can match paths outside those * roots, so it walks from `cwd` itself. A missing `cwd` or * base directory (absent, a file, a dangling link) is likewise an empty * result — see `DescendOptions.cwd` — because zero matches is a * normal glob answer — as is any pattern that lexically climbs above `cwd` * via `..` segments (walked paths never contain `..`). "Never reads outside * its documented root" holds lexically always, and physically only while * `followSymlinks` is off: under it, a link whose target lives outside `cwd` * is descended, exactly as `@actions/glob` follows links out of the tree. * Only an unreadable directory mid-walk * (under the default `onUnreadable: "fail"`) or a walk past `maxDepth` fails, * typed as {@link DescendError}. * * Only files match by default (`match` widens that to directories). A symlink * counts when it stat-resolves to a file * (`FileSystem.stat` follows links, as node's does); a symlinked directory is * never descended into by default (cycle safety — detected by an `lstat` * probe), unless `followSymlinks: true` asks for it, which follows links 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 sibling * links resolving to the same target both enumerate. A link whose real path * cannot be resolved is never entered, and a resolution failure other than * `NotFound` is an unreadable directory under `onUnreadable`. A dangling * symlink is not a match. A * directory that vanishes between its parent's listing and its own read is a * benign race and reads as empty. A pattern that cannot match below one level * (no globstar, no mid-pattern magic segment) reads a single level and never * descends. More generally the walk reads only directories a match can lie * in: a pattern with no globstar is never read deeper than its segments * reach, and under `dot: false` a hidden directory is never entered unless a * segment of the pattern names one. Neither bound changes the answer. * * The descent is a worklist, not a recursion — it cannot overflow the stack — * dequeued by head index, never `Array.shift()`. Like `ascend`, `maxDepth` * must be a positive integer: anything else is a defect, never a * silently-empty result. * * Passing `onUnreadable: "record"` resolves to a {@link DescendResult} * instead — see that overload. * * @example * ```ts * import { GlobPattern } from "@effected/glob"; * import { descend } from "@effected/walker"; * import { Effect } from "effect"; * * const program = Effect.gen(function* () { * const pattern = yield* GlobPattern.compile("src/*.ts"); * // Sorted, cwd-relative POSIX paths of the matching files. * return yield* descend(pattern, { cwd: "/repo" }); * }); * // Requires `FileSystem` and `Path` from the platform layer. * ``` * * @public */ export function descend( pattern: GlobPattern, options: DescendOptions, ): Effect.Effect, DescendError, FileSystem.FileSystem | Path.Path>; export function descend( pattern: GlobPattern, options: DescendOptions | DescendRecordOptions, ): Effect.Effect | DescendResult, DescendError, FileSystem.FileSystem | Path.Path> { return descendImpl(pattern, options); } /** * `descend` under `onUnreadable: "record"`, keeping each match's stat: * resolves to a {@link DescendEntriesResult}. * * @public */ export function descendEntries( pattern: GlobPattern, options: DescendRecordOptions, ): Effect.Effect; /** * `descend`, keeping the stat the walk already read for each matched * file: resolves to {@link DescendEntry} values sorted by path. * * @remarks * The same walk, the same matches in the same order, the same errors — only * the element type differs, and at no extra syscall (the walk stats every * entry to classify it). For a cache signature over a tree, map each entry's * `path` and `info.mtime` (or `info.size`) into whatever key the cache needs; * the kit does not choose the fingerprint. * * @example * ```ts * import { GlobPattern, GlobPatternOptions } from "@effected/glob"; * import { descendEntries } from "@effected/walker"; * import { Effect, Option } from "effect"; * * const signature = Effect.gen(function* () { * const pattern = yield* GlobPattern.compile("**", GlobPatternOptions.make({ dot: true })); * const entries = yield* descendEntries(pattern, { cwd: "/repo/src", boundaries: ["package.json"] }); * return entries.map((e) => `${e.path}:${Option.match(e.info.mtime, { onNone: () => "", onSome: (d) => d.getTime() })}`).join("|"); * }); * ``` * * @public */ export function descendEntries( pattern: GlobPattern, options: DescendOptions, ): Effect.Effect, DescendError, FileSystem.FileSystem | Path.Path>; export function descendEntries( pattern: GlobPattern, options: DescendOptions | DescendRecordOptions, ): Effect.Effect | DescendEntriesResult, DescendError, FileSystem.FileSystem | Path.Path> { return descendEntriesImpl(pattern, options); }