@effected/config-file 0.9.0 → 0.10.0

package/ConfigFile.js

@@ -14,11 +14,26 @@ import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PubSub, Sch
 *
 * @public
 */
-var ConfigFileNotFoundError = class extends Schema.TaggedError()("ConfigFileNotFoundError", { 
-/** The names of the resolvers that were probed, in order. */
-searched: Schema.Array(Schema.String) }) {
+var ConfigFileNotFoundError = class extends Schema.TaggedError()("ConfigFileNotFoundError", {
+	/** The names of the resolvers that were probed, in order. */
+	searched: Schema.Array(Schema.String),
+	/**
+	* The candidate paths the chain actually checked on disk, in probe order
+	* across every resolver — the failure-path mirror of {@link ConfigMatch}.
+	*
+	* @remarks
+	* One `searched` name can hide many paths: an `upwardWalk` with a
+	* `filenames` list probes every name at every ancestor. Resolvers that omit
+	* the optional `resolveProbe` member contribute nothing here, so the list
+	* can be shorter than the true search (or empty for a fully hand-rolled
+	* chain) — `searched` remains the complete resolver list either way.
+	*/
+	candidates: Schema.Array(Schema.String)
+}) {
 	get message() {
-		return `No config file found (searched: ${this.searched.join(", ")})`;
+		const count = this.candidates.length;
+		const probed = count === 0 ? "" : ` — ${count} candidate path${count === 1 ? "" : "s"} checked`;
+		return `No config file found (searched: ${this.searched.join(", ")}${probed})`;
 	}
 };
 /**
@@ -196,8 +211,15 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	});
 	const discover = Effect.fn("ConfigFile.discover")(function* () {
 		const sources = [];
+		const candidates = [];
 		for (const resolver of options.resolvers) {
-			const found = resolver.resolveMatch === void 0 ? Option.map(yield* Effect.provide(resolver.resolve, resolverEnv), (path) => ({ path })) : yield* Effect.provide(resolver.resolveMatch, resolverEnv);
+			let found;
+			if (resolver.resolveProbe !== void 0) {
+				const probe = yield* Effect.provide(resolver.resolveProbe, resolverEnv);
+				found = probe.match;
+				if (Option.isNone(found)) candidates.push(...probe.probed);
+			} else if (resolver.resolveMatch !== void 0) found = yield* Effect.provide(resolver.resolveMatch, resolverEnv);
+			else found = Option.map(yield* Effect.provide(resolver.resolve, resolverEnv), (path) => ({ path }));
 			if (Option.isSome(found)) {
 				const match = found.value;
 				const target = match.path;
@@ -214,7 +236,10 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 				});
 			}
 		}
-		return sources;
+		return {
+			sources,
+			candidates
+		};
 	});
 	const searched = options.resolvers.map((r) => r.name);
 	/**
@@ -239,15 +264,18 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		return value;
 	});
 	const load = Effect.fn("ConfigFile.load")(function* () {
-		const sources = yield* discover();
+		const { sources, candidates } = yield* discover();
 		if (sources.length === 0) {
 			yield* emit({ _tag: "NotFound" });
-			return yield* Effect.fail(new ConfigFileNotFoundError({ searched }));
+			return yield* Effect.fail(new ConfigFileNotFoundError({
+				searched,
+				candidates
+			}));
 		}
 		return yield* mergeAndEmit(sources);
 	});
 	const loadOrDefault = Effect.fn("ConfigFile.loadOrDefault")(function* (defaultValue) {
-		const sources = yield* discover();
+		const { sources } = yield* discover();
 		if (sources.length === 0) {
 			yield* emit({ _tag: "NotFound" });
 			return defaultValue;
@@ -361,7 +389,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	return {
 		load: load(),
 		loadFrom,
-		discover: discover(),
+		discover: Effect.map(discover(), (found) => found.sources),
 		loadOrDefault,
 		validate,
 		encode,

package/ConfigResolver.js

@@ -3,33 +3,44 @@ import { Walker } from "@effected/walker";
 
 //#region src/ConfigResolver.ts
 /**
-* Build a resolver from a match-reporting lookup, deriving `resolve` from it.
+* Build a resolver from a probe-reporting lookup, deriving `resolveMatch` and
+* `resolve` from it.
 *
 * @remarks
-* Every built-in goes through here, so `resolve` and `resolveMatch` are one
-* implementation and cannot drift.
+* Every built-in goes through here, so `resolve`, `resolveMatch` and
+* `resolveProbe` are one implementation and cannot drift.
 */
-const fromMatch = (name, resolveMatch) => ({
+const fromProbe = (name, resolveProbe) => ({
 	name,
-	resolve: Effect.map(resolveMatch, Option.map((match) => match.path)),
-	resolveMatch
+	resolve: Effect.map(resolveProbe, (probe) => Option.map(probe.match, (match) => match.path)),
+	resolveMatch: Effect.map(resolveProbe, (probe) => probe.match),
+	resolveProbe
 });
-/** Absorb any failure into `Option.none()` — the resolver contract. */
-const absorb = (effect) => Effect.catch(effect, () => Effect.succeed(Option.none()));
+/** Absorb any failure into an empty probe — the resolver contract. */
+const absorb = (effect) => Effect.catch(effect, () => Effect.succeed({
+	match: Option.none(),
+	probed: []
+}));
 const cwdOf = (given) => given ?? globalThis.process?.cwd?.() ?? "/";
-const explicitPath = (target) => fromMatch("explicit", absorb(Effect.gen(function* () {
-	return (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some({ path: target }) : Option.none();
+const explicitPath = (target) => fromProbe("explicit", absorb(Effect.gen(function* () {
+	return {
+		match: (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some({ path: target }) : Option.none(),
+		probed: [target]
+	};
 })));
-const staticDir = (options) => fromMatch("static", absorb(Effect.gen(function* () {
+const staticDir = (options) => fromProbe("static", absorb(Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const candidate = (yield* Path.Path).join(options.dir, options.filename);
-	return (yield* fs.exists(candidate)) ? Option.some({
-		path: candidate,
-		dir: options.dir,
-		filename: options.filename
-	}) : Option.none();
+	return {
+		match: (yield* fs.exists(candidate)) ? Option.some({
+			path: candidate,
+			dir: options.dir,
+			filename: options.filename
+		}) : Option.none(),
+		probed: [candidate]
+	};
 })));
-const upwardWalk = (options) => fromMatch(options.name ?? "walk", Effect.gen(function* () {
+const upwardWalk = (options) => fromProbe(options.name ?? "walk", Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const subpaths = options.subpaths ?? ["."];
@@ -42,31 +53,50 @@ const upwardWalk = (options) => fromMatch(options.name ?? "walk", Effect.gen(fun
 		filename,
 		...options.subpaths !== void 0 && { subpath: sub }
 	});
-	const found = yield* Walker.firstMatch(candidates.map((candidate) => candidate.path), (candidate) => fs.exists(candidate));
-	return Option.flatMap(found, (target) => Option.fromNullishOr(candidates.find((candidate) => candidate.path === target)));
+	const paths = candidates.map((candidate) => candidate.path);
+	const found = yield* Walker.firstMatch(paths, (candidate) => fs.exists(candidate));
+	const probed = Option.match(found, {
+		onNone: () => paths,
+		onSome: (target) => paths.slice(0, paths.indexOf(target) + 1)
+	});
+	return {
+		match: Option.flatMap(found, (target) => Option.fromNullishOr(candidates.find((candidate) => candidate.path === target))),
+		probed
+	};
 }));
 /**
 * Ascend from `cwd` looking for the first directory where `isRoot` reports
 * true, then probe `subpaths` under it. Shared by `gitRoot` and
 * `workspaceRoot`, which differ only in how a "root" is detected.
 */
-const rootAnchored = (name, isRoot, options) => fromMatch(name, Effect.gen(function* () {
+const rootAnchored = (name, isRoot, options) => fromProbe(name, Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const dirs = yield* Walker.ascend(cwdOf(options.cwd));
 	const root = yield* Walker.findRoot(dirs, isRoot);
-	if (Option.isNone(root)) return Option.none();
+	if (Option.isNone(root)) return {
+		match: Option.none(),
+		probed: []
+	};
 	const subpaths = options.subpaths ?? ["."];
-	const found = yield* Walker.firstMatch(subpaths.map((sub) => path.join(root.value, sub, options.filename)), (candidate) => fs.exists(candidate));
-	return Option.map(found, (target) => {
-		const matchedSubpath = options.subpaths === void 0 ? void 0 : subpaths.find((sub) => path.join(root.value, sub, options.filename) === target);
-		return {
-			path: target,
-			dir: root.value,
-			filename: options.filename,
-			...matchedSubpath !== void 0 && { subpath: matchedSubpath }
-		};
+	const paths = subpaths.map((sub) => path.join(root.value, sub, options.filename));
+	const found = yield* Walker.firstMatch(paths, (candidate) => fs.exists(candidate));
+	const probed = Option.match(found, {
+		onNone: () => paths,
+		onSome: (target) => paths.slice(0, paths.indexOf(target) + 1)
 	});
+	return {
+		match: Option.map(found, (target) => {
+			const matchedSubpath = options.subpaths === void 0 ? void 0 : subpaths.find((sub) => path.join(root.value, sub, options.filename) === target);
+			return {
+				path: target,
+				dir: root.value,
+				filename: options.filename,
+				...matchedSubpath !== void 0 && { subpath: matchedSubpath }
+			};
+		}),
+		probed
+	};
 }));
 /** `.git` may be a directory (a normal repo) or a file (a worktree pointing at the real repo). */
 const isGitRoot = (dir) => Effect.gen(function* () {
@@ -90,18 +120,24 @@ const isWorkspaceRoot = (dir) => Effect.gen(function* () {
 });
 const gitRoot = (options) => rootAnchored("git", isGitRoot, options);
 const workspaceRoot = (options) => rootAnchored("workspace", isWorkspaceRoot, options);
-const systemEtc = (options) => fromMatch("system", absorb(Effect.gen(function* () {
-	if (globalThis.process?.platform === "win32") return Option.none();
+const systemEtc = (options) => fromProbe("system", absorb(Effect.gen(function* () {
+	if (globalThis.process?.platform === "win32") return {
+		match: Option.none(),
+		probed: []
+	};
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const base = options.dir ?? "/etc";
 	const dir = path.join(base, options.app);
 	const candidate = path.join(dir, options.filename);
-	return (yield* fs.exists(candidate)) ? Option.some({
-		path: candidate,
-		dir,
-		filename: options.filename
-	}) : Option.none();
+	return {
+		match: (yield* fs.exists(candidate)) ? Option.some({
+			path: candidate,
+			dir,
+			filename: options.filename
+		}) : Option.none(),
+		probed: [candidate]
+	};
 })));
 /**
 * Built-in resolvers, in the order a typical chain uses them.

package/README.md

@@ -149,7 +149,7 @@ Every failure is a tagged error you route on with `Effect.catchTag`. The tags ex
 
 | Tag | Means | Recovery |
 | --- | --- | --- |
-| `ConfigFileNotFoundError` | The resolver chain matched nothing. Carries `searched`, the resolver names probed. | Fall back to defaults — the one failure that is often not an error. `loadOrDefault` handles it for you. |
+| `ConfigFileNotFoundError` | The resolver chain matched nothing. Carries `searched`, the resolver names probed, and `candidates`, the paths they actually checked on disk. | Fall back to defaults — the one failure that is often not an error. `loadOrDefault` handles it for you. |
 | `ConfigFileReadError` | A file was found but could not be read. Carries `path` and the structural `cause`. | Usually fatal: the file exists and the process cannot read it. Check permissions. |
 | `ConfigFileWriteError` | A file could not be written. Carries `path` and the structural `cause`. | Retry elsewhere, or surface to the user. |
 | `ConfigDefaultPathMissingError` | `save` or `update` was called on a service configured without a `defaultPath`. | A wiring bug, not a data condition. Fix the layer, or call `write` with an explicit path. |

package/index.d.ts

@@ -281,6 +281,29 @@ export interface ConfigResolver<R = never> {
    * tail.
    */
   readonly resolveMatch?: Effect.Effect<Option.Option<ConfigMatch>, never, R>;
+  /**
+   * The same lookup, additionally reporting every candidate path actually
+   * checked on disk, in probe order.
+   *
+   * @remarks
+   * Optional, and optional forever: a hand-rolled resolver that omits it is a
+   * complete `ConfigResolver`, and the pipeline falls back to `resolveMatch`
+   * (then `resolve`), contributing nothing to
+   * `ConfigFileNotFoundError.candidates` — the failure-path mirror of
+   * `ConfigSource.match` degrading to a bare path. Every built-in implements
+   * it, and derives the other two from it, so the three can never disagree.
+   *
+   * It exists because a resolver's `name` under-reports a search once one
+   * resolver probes several candidates: after the `filenames`/`subpaths`
+   * forms of `upwardWalk`, one `searched` entry can hide dozens of probed
+   * paths, and "nothing found, here is what I looked for" becomes less
+   * informative than the chain actually is.
+   *
+   * `probed` reports what the lookup CHECKED, not everything it could have:
+   * a short-circuiting walk lists the prefix ending at the match, and an
+   * absorbed filesystem failure lists nothing.
+   */
+  readonly resolveProbe?: Effect.Effect<ConfigProbe, never, R>;
 }
 /**
  * How a resolver found a config file, not merely where.
@@ -305,6 +328,29 @@ interface ConfigMatch {
   /** The `filenames`/`filename` entry that matched, when the resolver takes one. */
   readonly filename?: string;
 }
+/**
+ * The full report of one resolver lookup: what matched, and what was checked.
+ *
+ * @remarks
+ * `probed` carries the candidate paths the resolver actually asked the
+ * filesystem about, in probe order — for `upwardWalk`, the prefix of its
+ * directory-major candidate list ending at the match, or the full list when
+ * nothing matched. It exists so the failure path can be as informative as the
+ * success path: {@link ConfigMatch} says which candidate won and anchored
+ * where; `probed` says what lost, and where the search looked.
+ *
+ * @public
+ */
+interface ConfigProbe {
+  /** The match, when a candidate existed on disk. */
+  readonly match: Option.Option<ConfigMatch>;
+  /**
+   * Candidate paths checked on disk, in probe order. Empty when the lookup
+   * produced no candidate to report — no root found, a platform short-circuit,
+   * or a filesystem failure absorbed across the whole probe.
+   */
+  readonly probed: ReadonlyArray<string>;
+}
 /**
  * Options for `ConfigResolver.upwardWalk`.
  *
@@ -486,6 +532,18 @@ export declare const MergeStrategy: {
 declare const ConfigFileNotFoundError_base: Schema.Class<ConfigFileNotFoundError, Schema.TaggedStruct<"ConfigFileNotFoundError", {
   /** The names of the resolvers that were probed, in order. */
   readonly searched: Schema.$Array<Schema.String>;
+  /**
+   * The candidate paths the chain actually checked on disk, in probe order
+   * across every resolver — the failure-path mirror of {@link ConfigMatch}.
+   *
+   * @remarks
+   * One `searched` name can hide many paths: an `upwardWalk` with a
+   * `filenames` list probes every name at every ancestor. Resolvers that omit
+   * the optional `resolveProbe` member contribute nothing here, so the list
+   * can be shorter than the true search (or empty for a fully hand-rolled
+   * chain) — `searched` remains the complete resolver list either way.
+   */
+  readonly candidates: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Indicates that the resolver chain produced no configuration source.
@@ -1275,5 +1333,5 @@ export declare const TomlCodec: ConfigCodec;
  */
 export declare const YamlCodec: ConfigCodec;
 //#endregion
-export type { ConfigCodec, ConfigEncodeError, ConfigEncodeOptions, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources, UpwardWalkOptions };
+export type { ConfigCodec, ConfigEncodeError, ConfigEncodeOptions, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, ConfigProbe, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources, UpwardWalkOptions };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [