@effected/walker 0.20.1 → 0.22.0

package/index.d.ts

@@ -20,10 +20,16 @@ import { GlobPattern, GlobPatternError, GlobPatternOptions } from "@effected/glo
  *   reserved device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`–`COM9`,
  *   `LPT1`–`LPT9`), in any case and with or without an extension
  *   (`nul.txt`).
+ * - `outside` — `confineReal` only: the candidate's real path, links
+ *   resolved, lies outside the base's real path.
+ * - `unresolvable` — `confineReal` only: resolving the candidate or the base
+ *   failed for a reason other than absence (a permission error, a link loop,
+ *   a file used as a directory, a dangling link), so containment cannot be
+ *   verified. The failure rides in the error's `cause`.
  *
  * @public
  */
-export declare const PathEscapeReason: Schema.Literals<readonly ["nulByte", "absolute", "traversal", "empty", "reservedName"]>;
+export declare const PathEscapeReason: Schema.Literals<readonly ["nulByte", "absolute", "traversal", "empty", "reservedName", "outside", "unresolvable"]>;
 /**
  * The decoded type of {@link (PathEscapeReason:variable)}.
  *
@@ -34,7 +40,9 @@ declare const PathEscapeError_base: Schema.Class<PathEscapeError, Schema.TaggedS
   /** The candidate path, exactly as the caller passed it. */
   readonly candidate: Schema.String;
   /** Why the candidate was refused. */
-  readonly reason: Schema.Literals<readonly ["nulByte", "absolute", "traversal", "empty", "reservedName"]>;
+  readonly reason: Schema.Literals<readonly ["nulByte", "absolute", "traversal", "empty", "reservedName", "outside", "unresolvable"]>;
+  /** The resolution failure, present when `reason` is `"unresolvable"`. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * An untrusted relative path would leave, or does not name anything under,
@@ -82,7 +90,7 @@ export declare class PathEscapeError extends PathEscapeError_base {
  * base yields the normalised relative path alone. The check is lexical, not
  * physical, and symlinks are out of scope: a symlink already inside the
  * base can still point out of it, so a caller extracting into a directory
- * it does not own resolves links separately.
+ * it does not own checks the result with `confineReal` as well.
  *
  * {@link confineRelative} is defined in terms of this function and adds
  * only the tracing span.
@@ -139,12 +147,70 @@ export declare const confineRelative: (base: string, candidate: string) => Effec
  * @public
  */
 interface DescendOptions {
-  /** Absolute directory the pattern is resolved against. Required — walker never reads `process.cwd()`. */
+  /**
+   * 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. */
   readonly maxDepth?: number;
   /** Directory names never descended into. Defaults to `["node_modules", ".git"]`; a custom list replaces the default. */
   readonly prune?: ReadonlyArray<string>;
+  /**
+   * 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<string>;
   /**
    * What an unreadable directory mid-walk does. `"fail"` (the default) fails
    * typed — downward enumeration must not silently swallow a subtree, or the
@@ -158,7 +224,9 @@ interface DescendOptions {
   readonly onUnreadable?: "fail" | "skip";
   /**
    * Whether to descend into symlinked directories. Defaults to `false`: a
-   * symlinked directory is never entered (cycle safety). Under `true` links
+   * 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
@@ -208,7 +276,7 @@ interface DescendRecordOptions extends Omit<DescendOptions, "onUnreadable"> {
  *
  * @public
  */
-interface UnreadableDirectory {
+interface UnreadableDirectory<C = PlatformError.PlatformError> {
   /**
    * The directory's path relative to `cwd`, POSIX separators.
    *
@@ -220,7 +288,7 @@ interface UnreadableDirectory {
    */
   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: PlatformError.PlatformError;
+  readonly cause: C;
 }
 /**
  * `descend`'s success value under `onUnreadable: "record"`: the matched
@@ -232,11 +300,11 @@ interface UnreadableDirectory {
  *
  * @public
  */
-interface DescendResult {
+interface DescendResult<C = PlatformError.PlatformError> {
   /** 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>;
+  readonly unreadable: ReadonlyArray<UnreadableDirectory<C>>;
 }
 declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<"DescendError", {
   /** The glob pattern's source text. */
@@ -259,6 +327,35 @@ declare const DescendError_base: Schema.Class<DescendError, Schema.TaggedStruct<
 export declare class DescendError extends DescendError_base {
   get message(): string;
 }
+/**
+ * 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
+ */
+interface DescendEntry<I = FileSystem.File.Info> {
+  /** 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
+ */
+interface DescendEntriesResult<I = FileSystem.File.Info, C = PlatformError.PlatformError> {
+  /** Matching files with their stats, sorted by path. */
+  readonly matches: ReadonlyArray<DescendEntry<I>>;
+  /** Directories that could not be read, each with its cause, in walk order. */
+  readonly unreadable: ReadonlyArray<UnreadableDirectory<C>>;
+}
 /**
  * Expand a compiled glob pattern against the filesystem under
  * `onUnreadable: "record"`, resolving to a {@link DescendResult} — the
@@ -274,15 +371,22 @@ export declare class DescendError extends DescendError_base {
 export declare function descend(pattern: GlobPattern, options: DescendRecordOptions): Effect.Effect<DescendResult, DescendError, FileSystem.FileSystem | Path.Path>;
 /**
  * Expand a compiled glob pattern against the filesystem, returning matching
- * FILE paths relative to `cwd` (POSIX separators), sorted by relative path.
+ * FILE paths relative to `cwd` (POSIX separators), sorted by relative path —
+ * or, under `match: "directory"` or `"any"`, directory paths too.
  *
  * @remarks
- * A literal pattern (no magic, not negated) fast-paths to a single stat: the
+ * 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: the
  * result is `[source]` when it resolves to a file, `[]` otherwise — a missing
- * path is zero matches, not an error. A magic pattern walks from its literal
- * directory prefix (`GlobPattern.enumerationPrefix`); a NEGATED pattern can
- * match paths outside that prefix, so it walks from `cwd` itself. A missing
- * base directory is likewise an empty result, because zero matches is a
+ * path is zero matches, not an error. 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
@@ -292,9 +396,10 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * (under the default `onUnreadable: "fail"`) or a walk past `maxDepth` fails,
  * typed as {@link DescendError}.
  *
- * Only files match. A symlink counts when it stat-resolves to a file
+ * 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 a `readLink`
+ * 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
@@ -332,6 +437,276 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * @public
  */
 export declare function descend(pattern: GlobPattern, options: DescendOptions): Effect.Effect<ReadonlyArray<string>, DescendError, FileSystem.FileSystem | Path.Path>;
+/**
+ * `descend` under `onUnreadable: "record"`, keeping each match's stat:
+ * resolves to a {@link DescendEntriesResult}.
+ *
+ * @public
+ */
+export declare function descendEntries(pattern: GlobPattern, options: DescendRecordOptions): Effect.Effect<DescendEntriesResult, DescendError, FileSystem.FileSystem | Path.Path>;
+/**
+ * `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 declare function descendEntries(pattern: GlobPattern, options: DescendOptions): Effect.Effect<ReadonlyArray<DescendEntry>, DescendError, FileSystem.FileSystem | Path.Path>;
+/**
+ * The stats {@link WalkerSyncFileSystem} answers — a structural subset of
+ * `node:fs` `Stats`, so `statSync` / `lstatSync` satisfy it verbatim.
+ *
+ * @public
+ */
+interface WalkerSyncStats {
+  /** Whether the entry is a regular file. */
+  isFile(): boolean;
+  /** Whether the entry is a directory. */
+  isDirectory(): boolean;
+  /** Whether the entry is a symbolic link (only ever true for `lstat`). */
+  isSymbolicLink(): boolean;
+  /** Modification time, epoch milliseconds. */
+  readonly mtimeMs: number;
+  /** Size in bytes. */
+  readonly size: number;
+}
+/**
+ * The synchronous file operations the sync walk needs, supplied by the
+ * consumer — `node:fs` satisfies it (`nodeWalkerFileSystem` from
+ * `@effected/walker/node-sync`).
+ *
+ * @remarks
+ * Every member reports failure by throwing a node-shaped error. A `code` of
+ * `"ENOENT"` is the benign vanished-path race (empty, never recorded); any
+ * other throw from `readDirectory` or `realPath` is an unreadable directory,
+ * handled per `onUnreadable`. A throwing `stat` or `lstat` reads as "no
+ * entry", exactly as the `Effect` walk reads its failed `stat` and `lstat`.
+ *
+ * @public
+ */
+interface WalkerSyncFileSystem {
+  /** The entry names inside the directory at `path` (`readdirSync`). */
+  readonly readDirectory: (path: string) => ReadonlyArray<string>;
+  /** Stats of `path`, following links (`statSync`). */
+  readonly stat: (path: string) => WalkerSyncStats;
+  /** Stats of `path` itself, not following a final link (`lstatSync`). */
+  readonly lstat: (path: string) => WalkerSyncStats;
+  /** The real path of `path`, links resolved (`realpathSync`). */
+  readonly realPath: (path: string) => string;
+}
+/**
+ * The synchronous path operations the sync forms need — a structural subset
+ * of `node:path`, so the module itself (or its `win32` / `posix` variant)
+ * satisfies it. It shapes only the absolute paths handed to the
+ * {@link WalkerSyncFileSystem}; matching is POSIX-relative by the glob
+ * contract.
+ *
+ * @remarks
+ * The members mirror core's `Path` service, so a sync form judges
+ * absoluteness, ascends and compares ceilings exactly as its `Effect` twin
+ * does under the `Path` layer of the same platform.
+ *
+ * @public
+ */
+interface WalkerSyncPath {
+  /** The implementation's separator (`path.sep`). */
+  readonly sep: string;
+  /** Join segments with the implementation's separator (like `path.join`). */
+  readonly join: (...segments: ReadonlyArray<string>) => string;
+  /** The parent directory of a path (like `path.dirname`); a fixpoint at the root. */
+  readonly dirname: (path: string) => string;
+  /** Resolve segments to a normalized path (like `path.resolve`). */
+  readonly resolve: (...segments: ReadonlyArray<string>) => string;
+  /** Whether a path is absolute under this implementation (like `path.isAbsolute`). */
+  readonly isAbsolute: (path: string) => boolean;
+}
+/**
+ * The platform half of every sync walk.
+ *
+ * @public
+ */
+interface WalkerSyncOps {
+  /** File operations. */
+  readonly fileSystem: WalkerSyncFileSystem;
+  /** Path joining. */
+  readonly path: WalkerSyncPath;
+}
+/**
+ * Options for `descendSync` / `descendEntriesSync`: every `DescendOptions`
+ * field, plus the platform.
+ *
+ * @public
+ */
+interface DescendSyncOptions extends DescendOptions, WalkerSyncOps {}
+/**
+ * {@link DescendSyncOptions} under `onUnreadable: "record"`.
+ *
+ * @public
+ */
+interface DescendSyncRecordOptions extends DescendRecordOptions, WalkerSyncOps {}
+/**
+ * `descend` under `onUnreadable: "record"`, synchronously over a caller-supplied port.
+ *
+ * @public
+ */
+export declare function descendSync(pattern: GlobPattern, options: DescendSyncRecordOptions): Result.Result<DescendResult<unknown>, DescendError>;
+/**
+ * `descend`, synchronously, over a caller-supplied file port: matching FILE
+ * paths relative to `cwd` (POSIX separators), sorted.
+ *
+ * @remarks
+ * The same walk as `descend` — it drives the same traversal, so every rule
+ * holds identically: the literal fast path, the enumeration prefix, `prune`,
+ * `boundaries`, the symlink posture and per-branch cycle guard under
+ * `followSymlinks`, `onUnreadable` and the `maxDepth` failure. Failures are a
+ * `Result` failure typed as `DescendError`; an invalid `maxDepth` is a defect
+ * and throws. For a caller with no Effect runtime (config evaluation, a Node
+ * SEA sidecar); inside Effect, use `descend`.
+ *
+ * @example
+ * ```ts
+ * import { GlobPattern } from "@effected/glob";
+ * import { descendSync } from "@effected/walker";
+ * import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+ * import { Result } from "effect";
+ *
+ * const pattern = Result.getOrThrow(GlobPattern.compileResult("src/**"));
+ * const files = descendSync(pattern, { cwd: "/repo", boundaries: ["package.json"], ...nodeWalkerSyncOps });
+ * ```
+ *
+ * @public
+ */
+export declare function descendSync(pattern: GlobPattern, options: DescendSyncOptions): Result.Result<ReadonlyArray<string>, DescendError>;
+/**
+ * `descendEntries` under `onUnreadable: "record"`, synchronously over a caller-supplied port.
+ *
+ * @public
+ */
+export declare function descendEntriesSync(pattern: GlobPattern, options: DescendSyncRecordOptions): Result.Result<DescendEntriesResult<WalkerSyncStats, unknown>, DescendError>;
+/**
+ * `descendEntries`, synchronously: `descendSync`'s matches, each with
+ * the stat the walk already read for it.
+ *
+ * @public
+ */
+export declare function descendEntriesSync(pattern: GlobPattern, options: DescendSyncOptions): Result.Result<ReadonlyArray<DescendEntry<WalkerSyncStats>>, DescendError>;
+/**
+ * Confine a path to a base directory PHYSICALLY: resolve links in both, and
+ * succeed with the candidate's real path only when it lies strictly inside
+ * the base's real path.
+ *
+ * @remarks
+ * Reach for it where `confineRelative` stops: a link inside the base that
+ * points out of it (a symlinked `dist`, a planted `node_modules` entry), an
+ * absolute path an agent or a tool handed over, a `descend` match — a
+ * matched link is answered even when its target lies outside `cwd`.
+ *
+ * The candidate may be absolute (checked as it is) or relative (taken
+ * against `base`). It is resolved the way the operating system resolves it:
+ * segment by segment, so a `..` after a link climbs out of the link's
+ * TARGET — `base/link/../x` is outside when `link` points outside — rather
+ * than being collapsed lexically first, as `path.resolve` and node's JS
+ * `fs.realpath` would. A path, or the tail of one, that does not exist yet
+ * is resolved lexically from its real existing ancestor, so a write target
+ * can be checked before it is created — but only once absence is proved: a
+ * segment whose real path is not found is checked again without following
+ * links, because a dangling link is "not found" too, and a write through one
+ * creates its target wherever it points. The base is resolved the same way.
+ *
+ * Refused, typed as {@link PathEscapeError}: a NUL character (`nulByte`);
+ * the empty string or any path whose real location IS the base (`empty`,
+ * the same ruling `confineRelative` makes — a caller confining a path names
+ * an entry under the base); on win32 a drive-relative `C:x` or a driveless
+ * rooted `\x`, which names the current drive (`absolute`), or a segment
+ * win32 reads as something else, such as a device name or `..  `
+ * (`reservedName`); a real path outside the base's (`outside`); and a
+ * resolution that fails for a reason other than absence, such as a
+ * permission error, a link loop, or a dangling link — a link whose target
+ * does not exist, refused even when that target would lie inside the base
+ * (`unresolvable`, with the failure in `cause`) — containment that cannot be
+ * verified is refused, never assumed.
+ *
+ * A relative `base` — the empty string included — is a **defect**: it would
+ * be resolved against the process working directory, the silent wrong-root
+ * walk `ascend` refuses for a relative `stopAt`. Absoluteness is judged by
+ * the injected `Path`, so win32 accepts `C:\repo` and `\\server\share`;
+ * a win32 `\repo`, rooted on whichever drive the process is on, is a defect
+ * too.
+ *
+ * Use the returned path, not the candidate: it is the location that was
+ * checked. Comparison is exact on the real paths, so on a case-insensitive
+ * filesystem a base and a candidate spelled in different case may be refused
+ * — the check fails closed. As with any check-then-use on a live filesystem,
+ * a link swapped in between the check and the use is not covered.
+ *
+ * @example
+ * ```ts
+ * import { confineReal } from "@effected/walker";
+ * import { Effect } from "effect";
+ *
+ * const target = confineReal("/repo", "packages/app/dist").pipe(
+ *   Effect.catchTag("PathEscapeError", (error) => Effect.die(error)),
+ * );
+ * // Requires `FileSystem` and `Path` from the platform layer.
+ * ```
+ *
+ * @param base - The absolute directory the candidate must stay under.
+ * @param candidate - The path to check: absolute, or relative to `base`.
+ * @returns An `Effect` succeeding with the candidate's real path, or failing
+ * with {@link PathEscapeError}.
+ *
+ * @public
+ */
+export declare const confineReal: (base: string, candidate: string) => Effect.Effect<string, PathEscapeError, FileSystem.FileSystem | Path.Path>;
+/**
+ * {@link confineReal}, synchronously, over a caller-supplied port.
+ *
+ * @remarks
+ * The same resolution from the same code, through the port's `realPath`; a
+ * `realPath` throwing `code: "ENOENT"` is absence only when the port's
+ * `lstat` throws `ENOENT` too (otherwise a dangling link is there); anything
+ * else is `unresolvable`, with the thrown value as the `cause`. A relative `base`
+ * throws. For a caller with no Effect runtime; inside Effect, use
+ * `confineReal`.
+ *
+ * @example
+ * ```ts
+ * import { confineRealSync } from "@effected/walker";
+ * import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+ * import { Result } from "effect";
+ *
+ * const checked = confineRealSync("/repo", "/repo/packages/app/dist", nodeWalkerSyncOps);
+ * if (Result.isFailure(checked)) console.error(checked.failure.message);
+ * ```
+ *
+ * @param base - The absolute directory the candidate must stay under.
+ * @param candidate - The path to check: absolute, or relative to `base`.
+ * @param ops - The platform: spread or pass `nodeWalkerSyncOps`.
+ * @returns A `Result` succeeding with the candidate's real path, or failing
+ * with {@link PathEscapeError}.
+ *
+ * @public
+ */
+export declare const confineRealSync: (base: string, candidate: string, ops: WalkerSyncOps) => Result.Result<string, PathEscapeError>;
 /**
  * Options for {@link compileAndExpand}: every {@link DescendOptions} field,
  * plus the glob options the pattern compiles under.
@@ -472,7 +847,8 @@ interface AscendOptions {
    *
    * 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.
+   * service, so the win32 layer accepts `C:\repo` and posix does not; a
+   * win32 `\repo`, rooted on whichever drive the process is on, dies too.
    *
    * Normalization governs the comparison only: the chain `ascend` returns is
    * still the lexical one derived from `start`, unrewritten. A ceiling naming
@@ -488,6 +864,37 @@ interface AscendOptions {
   /** Hard cap on chain length. Defaults to 256. */
   readonly maxDepth?: number;
 }
+/**
+ * Options for {@link Walker.ascendSync}: every {@link AscendOptions} field,
+ * plus the path implementation the chain is computed with.
+ *
+ * @public
+ */
+interface AscendSyncOptions extends AscendOptions {
+  /** Path arithmetic — `node:path` satisfies it (`nodeWalkerPath` from `@effected/walker/node-sync`). */
+  readonly path: WalkerSyncPath;
+}
+/**
+ * Options for the synchronous upward forms that touch the filesystem —
+ * {@link Walker.ascendWithinSync} and {@link Walker.ascendToMarkerSync}: the
+ * depth cap, plus the platform (spread `nodeWalkerSyncOps` from
+ * `@effected/walker/node-sync`).
+ *
+ * @public
+ */
+interface AscendWithinSyncOptions extends Pick<AscendOptions, "maxDepth">, WalkerSyncOps {}
+/**
+ * {@link Walker.findUpwardAll}'s answer: the nearest directory holding any
+ * candidate, and every candidate that exists there.
+ *
+ * @public
+ */
+interface UpwardMatches {
+  /** The directory whose candidates produced the hits. */
+  readonly dir: string;
+  /** Every existing candidate of `dir`, in the order `candidatesFor` gave them. Never empty. */
+  readonly found: readonly [string, ...Array<string>];
+}
 /**
  * Upward path traversal primitives: the directory chain from a start path to the
  * root, and first-match scans over it.
@@ -592,6 +999,171 @@ export declare class Walker {
    * `pnpm-workspace.yaml`), and its failures are absorbed per directory.
    */
   static findRoot<E, R>(dirs: ReadonlyArray<string>, isRoot: (dir: string) => Effect.Effect<boolean, E, R>): Effect.Effect<Option.Option<string>, never, R>;
+  /**
+   * {@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: string, markers: ReadonlyArray<string>, options?: Pick<AscendOptions, "maxDepth">): Effect.Effect<ReadonlyArray<string>, never, FileSystem.FileSystem | Path.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: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>): Effect.Effect<Option.Option<UpwardMatches>, never, FileSystem.FileSystem>;
+  /**
+   * {@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: string, options: AscendSyncOptions): ReadonlyArray<string>;
+  /**
+   * {@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: string, ceiling: Option.Option<string>, options: AscendWithinSyncOptions): ReadonlyArray<string>;
+  /**
+   * {@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: string, markers: ReadonlyArray<string>, options: AscendWithinSyncOptions): ReadonlyArray<string>;
+  /**
+   * {@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: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>, ops: WalkerSyncOps): Option.Option<string>;
+  /**
+   * {@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: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>, ops: WalkerSyncOps): Option.Option<UpwardMatches>;
 }
-export type { AscendOptions, CompileAndExpandOptions, DescendOptions, DescendRecordOptions, DescendResult, UnreadableDirectory };
+export type { AscendOptions, AscendSyncOptions, AscendWithinSyncOptions, CompileAndExpandOptions, DescendEntriesResult, DescendEntry, DescendOptions, DescendRecordOptions, DescendResult, DescendSyncOptions, DescendSyncRecordOptions, UnreadableDirectory, UpwardMatches, WalkerSyncFileSystem, WalkerSyncOps, WalkerSyncPath, WalkerSyncStats };
 //# sourceMappingURL=index.d.ts.map