@effected/walker 0.21.0 → 0.23.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,8 +147,49 @@ 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. */
@@ -279,8 +328,8 @@ export declare class DescendError extends DescendError_base {
   get message(): string;
 }
 /**
- * One matched file with the stat the walk already read for it — `descendEntries`'
- * element. Costs no syscall beyond `descend`'s: the walk stats every entry to
+ * 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
@@ -289,7 +338,7 @@ export declare class DescendError extends DescendError_base {
  * @public
  */
 interface DescendEntry<I = FileSystem.File.Info> {
-  /** The file's path relative to `cwd`, POSIX separators. */
+  /** 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;
@@ -322,7 +371,8 @@ interface DescendEntriesResult<I = FileSystem.File.Info, C = PlatformError.Platf
 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 path is answered in the spelling the pattern matched it under: `./src/*.ts`
@@ -334,8 +384,9 @@ export declare function descend(pattern: GlobPattern, options: DescendRecordOpti
  * 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
- * base directory is likewise an empty result, because zero matches is a
+ * 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
@@ -345,7 +396,8 @@ 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 an `lstat`
  * probe), unless `followSymlinks: true` asks for it, which follows links under
@@ -462,17 +514,30 @@ interface WalkerSyncFileSystem {
   readonly realPath: (path: string) => string;
 }
 /**
- * The synchronous path operation the sync walk needs — a structural subset of
- * `node:path`, so the module itself (or its `win32` / `posix` variant)
+ * 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.
@@ -544,6 +609,170 @@ export declare function descendEntriesSync(pattern: GlobPattern, options: Descen
  * @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 relativeWithin}.
+ *
+ * @public
+ */
+interface RelativeWithinOptions {
+  /**
+   * What a path that does not exist yet means. `"ancestor"` (the default)
+   * resolves the missing tail from the deepest existing ancestor, so a
+   * destination can be placed before it is created; `"refuse"` answers `None`
+   * for any path that does not exist.
+   */
+  readonly missing?: "ancestor" | "refuse";
+}
+/**
+ * The posix, base-relative path of an absolute path that lies inside a base
+ * directory PHYSICALLY, or `None` when it does not.
+ *
+ * @remarks
+ * The question `confineReal` does not answer: where, under `base`, does this
+ * absolute path sit? It resolves links the way `confineReal` does, and a path
+ * or tail that does not exist yet is resolved lexically from its deepest
+ * existing ancestor, so a destination can be placed before it is created.
+ * The base itself answers `""`. `None` covers every refusal: a relative or
+ * NUL-bearing candidate, a real location outside the base, and a resolution
+ * that cannot be verified (a permission error, a loop, a dangling link) —
+ * containment that cannot be proved is never assumed. A relative `base` is a
+ * **defect**, as it is for `confineReal`.
+ *
+ * @example
+ * ```ts
+ * import { relativeWithin } from "@effected/walker";
+ * import { Effect } from "effect";
+ *
+ * const inside = relativeWithin("/repo", "/repo/docs/new.md");
+ * // Requires `FileSystem` and `Path`; succeeds with Option.some("docs/new.md").
+ * ```
+ *
+ * @param base - The absolute directory the path must stay inside.
+ * @param absolute - The absolute path to place under `base`.
+ * @param options - See {@link RelativeWithinOptions}.
+ * @returns An `Effect` succeeding with the base-relative posix path, or `None`.
+ *
+ * @public
+ */
+export declare const relativeWithin: (base: string, absolute: string, options?: RelativeWithinOptions) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem | Path.Path>;
+/**
+ * {@link relativeWithin}, synchronously, over a caller-supplied port.
+ *
+ * @example
+ * ```ts
+ * import { relativeWithinSync } from "@effected/walker";
+ * import { nodeWalkerSyncOps } from "@effected/walker/node-sync";
+ *
+ * const inside = relativeWithinSync("/repo", "/repo/docs/new.md", nodeWalkerSyncOps);
+ * ```
+ *
+ * @param base - The absolute directory the path must stay inside.
+ * @param absolute - The absolute path to place under `base`.
+ * @param ops - The platform: spread or pass `nodeWalkerSyncOps`.
+ * @param options - See {@link RelativeWithinOptions}.
+ * @returns The base-relative posix path, or `None`.
+ *
+ * @public
+ */
+export declare const relativeWithinSync: (base: string, absolute: string, ops: WalkerSyncOps, options?: RelativeWithinOptions) => Option.Option<string>;
 /**
  * Options for {@link compileAndExpand}: every {@link DescendOptions} field,
  * plus the glob options the pattern compiles under.
@@ -684,7 +913,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
@@ -700,6 +930,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.
@@ -804,6 +1065,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, DescendEntriesResult, DescendEntry, DescendOptions, DescendRecordOptions, DescendResult, DescendSyncOptions, DescendSyncRecordOptions, UnreadableDirectory, WalkerSyncFileSystem, WalkerSyncOps, WalkerSyncPath, WalkerSyncStats };
+export type { AscendOptions, AscendSyncOptions, AscendWithinSyncOptions, CompileAndExpandOptions, DescendEntriesResult, DescendEntry, DescendOptions, DescendRecordOptions, DescendResult, DescendSyncOptions, DescendSyncRecordOptions, RelativeWithinOptions, UnreadableDirectory, UpwardMatches, WalkerSyncFileSystem, WalkerSyncOps, WalkerSyncPath, WalkerSyncStats };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,7 +1,8 @@
 import { PathEscapeError, PathEscapeReason, confineRelative, confineRelativeResult } from "./Confine.js";
+import { confineReal, confineRealSync, relativeWithin, relativeWithinSync } from "./ConfineReal.js";
 import { DescendError, descend, descendEntries } from "./Descend.js";
 import { descendEntriesSync, descendSync } from "./DescendSync.js";
 import { GlobExpansionError, compileAndExpand } from "./Expand.js";
 import { Walker } from "./Walker.js";
 
-export { DescendError, GlobExpansionError, PathEscapeError, PathEscapeReason, Walker, compileAndExpand, confineRelative, confineRelativeResult, descend, descendEntries, descendEntriesSync, descendSync };
+export { DescendError, GlobExpansionError, PathEscapeError, PathEscapeReason, Walker, compileAndExpand, confineReal, confineRealSync, confineRelative, confineRelativeResult, descend, descendEntries, descendEntriesSync, descendSync, relativeWithin, relativeWithinSync };

package/internal/absolute.js

@@ -0,0 +1,19 @@
+// src/internal/absolute.ts
+/**
+* A win32 path rooted on the CURRENT drive: one leading separator, not two
+* (`\\server\share` and `\\?\C:\x` are UNC and device paths, which name their
+* root). `path.win32.isAbsolute` calls `\repo` absolute, yet which drive it
+* names depends on the process working directory — exactly like the
+* drive-relative `C:x`.
+*/
+const CURRENT_DRIVE_ROOT = /^[\\/](?![\\/])/;
+/** Whether `path` is rooted on the current drive under win32 path rules. */
+const isCurrentDriveRooted = (path, sep) => sep === "\\" && CURRENT_DRIVE_ROOT.test(path);
+/**
+* Whether `path` names one location whatever the process working directory:
+* absolute to the injected implementation, and on win32 not rooted on the
+* current drive.
+*/
+const isPinnedAbsolute = (path, ops) => ops.isAbsolute(path) && !isCurrentDriveRooted(path, ops.sep);
+
+export { isCurrentDriveRooted, isPinnedAbsolute };