@effected/walker 0.22.0 → 0.24.0

package/ConfineReal.js

@@ -1,7 +1,7 @@
 import { PathEscapeError } from "./Confine.js";
 import { runUpward, runUpwardSync } from "./internal/upwardDrivers.js";
 import { confineRealMachine } from "./internal/upwardMachine.js";
-import { Effect, Path, Result } from "effect";
+import { Effect, Option, Path, Result } from "effect";
 
 // src/ConfineReal.ts
 /** The typed error a refusal describes — the one conversion both forms share. */
@@ -119,5 +119,65 @@ const confineReal = Effect.fn("Walker.confineReal")(function* (base, candidate)
 * @public
 */
 const confineRealSync = (base, candidate, ops) => toResult(candidate, runUpwardSync(confineRealMachine("Walker.confineRealSync", base, candidate, ops.path), ops.fileSystem));
+const within = (options) => ({ requireExisting: options?.missing === "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
+*/
+const relativeWithin = Effect.fn("Walker.relativeWithin")(function* (base, absolute, options) {
+	const path = yield* Path.Path;
+	const outcome = yield* runUpward(confineRealMachine("Walker.relativeWithin", base, absolute, path, within(options)));
+	return outcome._tag === "Ok" ? Option.some(outcome.value) : Option.none();
+});
+/**
+* {@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
+*/
+const relativeWithinSync = (base, absolute, ops, options) => {
+	const outcome = runUpwardSync(confineRealMachine("Walker.relativeWithinSync", base, absolute, ops.path, within(options)), ops.fileSystem);
+	return outcome._tag === "Ok" ? Option.some(outcome.value) : Option.none();
+};
 
-export { confineReal, confineRealSync };
+export { confineReal, confineRealSync, relativeWithin, relativeWithinSync };

package/README.md

@@ -8,10 +8,10 @@
 Path traversal as Effect primitives. `Walker.ascend` gives you the directory chain from a starting path to the filesystem root; `Walker.findUpward` returns the nearest existing file among per-directory candidates; `Walker.findRoot` returns the nearest directory a marker predicate accepts. Every probe absorbs its own failure, so a single unreadable ancestor cannot hide a valid `.git` or `pnpm-workspace.yaml` above it. Going the other way, `descend` expands a compiled [`@effected/glob`](https://www.npmjs.com/package/@effected/glob) pattern under a directory into the matching file paths — sorted, symlink-safe, and typed about unreadable subtrees instead of silently swallowing them. `FileSystem` and `Path` arrive from `effect` core, so no platform package is pulled in — not even in tests.
 
 > **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
-> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> Effect v4 (`effect` `~4.1.0`) and still in `0.x` development. Stable Effect
 > makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
 > `@effect/*` versions on the line the kit is built and tested against, install
-> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+> [`@effected/pnpm-plugin-effected`](https://www.npmjs.com/package/@effected/pnpm-plugin-effected).
 >
 > **Stability: unstable.** This package's API surface is not yet considered
 > complete and may change across `0.x` releases. Pin an exact version — even a

package/index.d.ts

@@ -707,6 +707,72 @@ export declare const confineReal: (base: string, candidate: string) => Effect.Ef
  * @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.
@@ -1165,5 +1231,5 @@ export declare class Walker {
    */
   static findUpwardAllSync(dirs: ReadonlyArray<string>, candidatesFor: (dir: string) => ReadonlyArray<string>, ops: WalkerSyncOps): Option.Option<UpwardMatches>;
 }
-export type { AscendOptions, AscendSyncOptions, AscendWithinSyncOptions, CompileAndExpandOptions, DescendEntriesResult, DescendEntry, DescendOptions, DescendRecordOptions, DescendResult, DescendSyncOptions, DescendSyncRecordOptions, UnreadableDirectory, UpwardMatches, 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,8 +1,8 @@
 import { PathEscapeError, PathEscapeReason, confineRelative, confineRelativeResult } from "./Confine.js";
-import { confineReal, confineRealSync } from "./ConfineReal.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, confineReal, confineRealSync, 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/upwardMachine.js

@@ -147,7 +147,7 @@ const isWin32Reserved = (segment) => segment.includes(":") || DOTS_AND_SPACES.te
 * two requests) is unresolvable, its target unverified. Any failure other
 * than `NotFound` makes the path unresolvable too. Fail closed throughout.
 */
-function* resolvePhysical(absolute, path, win32, checkSegments) {
+function* resolvePhysical(absolute, path, win32, checkSegments, requireExisting = false) {
 	let root = absolute;
 	for (let parent = path.dirname(root); parent !== root; parent = path.dirname(root)) root = parent;
 	const segments = (absolute.startsWith(root) ? absolute.slice(root.length) : absolute).split(win32 ? /[\\/]/ : "/").filter((segment) => segment !== "");
@@ -198,6 +198,10 @@ function* resolvePhysical(absolute, path, win32, checkSegments) {
 			_tag: "Unresolvable",
 			cause: answer.cause
 		};
+		if (requireExisting) return {
+			_tag: "Refused",
+			reason: "outside"
+		};
 		current = next;
 	}
 	return {
@@ -209,7 +213,7 @@ function* resolvePhysical(absolute, path, win32, checkSegments) {
 * `confineReal`: the candidate's real path when it lies strictly inside the
 * base's real path, or why not. A relative `base` is a wiring defect.
 */
-function* confineRealMachine(name, base, candidate, path) {
+function* confineRealMachine(name, base, candidate, path, within = false) {
 	if (base.includes("\0") || !isPinnedAbsolute(base, path)) return defect(`${name}: base must be an absolute path, received ${JSON.stringify(base)}`);
 	const refuse = (reason) => done({
 		_tag: "Refused",
@@ -217,6 +221,7 @@ function* confineRealMachine(name, base, candidate, path) {
 	});
 	if (candidate.includes("\0")) return refuse("nulByte");
 	if (candidate === "") return refuse("empty");
+	if (within && !path.isAbsolute(candidate)) return refuse("absolute");
 	const win32 = path.sep === "\\";
 	const isSep = (character) => character === path.sep || win32 && character === "/";
 	if (win32 && DRIVE.test(candidate) && !path.isAbsolute(candidate)) return refuse("absolute");
@@ -224,12 +229,20 @@ function* confineRealMachine(name, base, candidate, path) {
 	const full = path.isAbsolute(candidate) ? candidate : `${trimTrailing(base, isSep)}${path.sep}${candidate}`;
 	const baseReal = yield* resolvePhysical(base, path, win32, false);
 	if (baseReal._tag !== "Ok") return done(baseReal);
-	const candidateReal = yield* resolvePhysical(full, path, win32, true);
+	const candidateReal = yield* resolvePhysical(full, path, win32, true, within !== false && within.requireExisting);
 	if (candidateReal._tag !== "Ok") return done(candidateReal);
 	const root = trimTrailing(baseReal.value, isSep);
 	const resolved = trimTrailing(candidateReal.value, isSep);
+	if (within && resolved === root) return done({
+		_tag: "Ok",
+		value: ""
+	});
 	if (resolved === root) return refuse("empty");
 	if (!resolved.startsWith(`${root}${path.sep}`)) return refuse("outside");
+	if (within) return done({
+		_tag: "Ok",
+		value: resolved.slice(root.length + 1).split(path.sep).join("/")
+	});
 	return done({
 		_tag: "Ok",
 		value: candidateReal.value

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/walker",
-	"version": "0.22.0",
+	"version": "0.24.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": [
@@ -42,8 +42,8 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.16.0",
-		"effect": "^4.0.0"
+		"@effected/glob": "^0.17.0",
+		"effect": "~4.1.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

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