@effected/config-file 0.6.0 → 0.7.0

package/ConfigCodec.js

@@ -8,6 +8,15 @@ import { Schema } from "effect";
 * The underlying failure is preserved structurally in `cause` — it is never
 * stringified. Route on the `"ConfigCodecError"` tag with `Effect.catchTag`.
 *
+* `path` names the offending file when the error came through `ConfigFile`,
+* which is what makes a failure during multi-candidate discovery reportable.
+*
+* `message` deliberately does NOT name the path — read `path` when you need it.
+* A wrapper that renders its own message almost always names the file too, so
+* a message carrying the path would compose into a rendering that prints the
+* same file twice. The doubling is the default outcome, not an unlucky one:
+* the field is the API, and the message is a bare summary.
+*
 * @public
 */
 var ConfigCodecError = class extends Schema.TaggedError()("ConfigCodecError", {
@@ -16,7 +25,18 @@ var ConfigCodecError = class extends Schema.TaggedError()("ConfigCodecError", {
 	/** Which direction failed. */
 	operation: Schema.Literals(["parse", "stringify"]),
 	/** The underlying failure, preserved structurally. */
-	cause: Schema.Defect()
+	cause: Schema.Defect(),
+	/**
+	* The file the content came from, when a caller knew it.
+	*
+	* @remarks
+	* A codec sees a string, never a path, so it cannot fill this in itself.
+	* `ConfigFile`'s read/write pipeline does: every site that feeds a codec a
+	* path it resolved re-raises the error with `path` attached, so a discovery
+	* pass over several candidates still names the file that failed. Absent
+	* only when a codec was driven directly, outside that pipeline.
+	*/
+	path: Schema.optionalKey(Schema.String)
 }) {
 	get message() {
 		return `${this.codec} ${this.operation} failed`;

package/ConfigFile.js

@@ -1,3 +1,4 @@
+import { ConfigCodecError } from "./ConfigCodec.js";
 import { ConfigEvent } from "./ConfigEvent.js";
 import { ConfigResolver } from "./ConfigResolver.js";
 import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PubSub, Schema, Semaphore } from "effect";
@@ -101,6 +102,24 @@ var ConfigValidationError = class extends Schema.TaggedError()("ConfigValidation
 	}
 };
 const Service = () => (id) => Context.Service()(id);
+/**
+* Re-raise a codec failure with the file it came from attached.
+*
+* @remarks
+* A codec is handed a string and never a path, so `ConfigCodecError.path` can
+* only be filled in here, where the resolved target is in scope. An error that
+* already carries a path is left alone — a decorator codec that knew better
+* wins — and anything that is not a `ConfigCodecError` passes through
+* untouched, which is why the cast is sound: the returned value is either the
+* argument itself or a `ConfigCodecError`, and the only way a `ConfigCodecError`
+* reaches here is if `E` admits one.
+*/
+const withCodecPath = (error, target) => error instanceof ConfigCodecError && error.path === void 0 ? new ConfigCodecError({
+	codec: error.codec,
+	operation: error.operation,
+	cause: error.cause,
+	path: target
+}) : error;
 const makeImpl = (options, fs, path, resolverEnv) => {
 	/**
 	* Publish one event, or nothing at all.
@@ -143,7 +162,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 			path: target,
 			cause
 		})));
-		const parsed = yield* options.codec.parse(raw).pipe(Effect.tapError((error) => emit({
+		const parsed = yield* options.codec.parse(raw).pipe(Effect.mapError((error) => withCodecPath(error, target)), Effect.tapError((error) => emit({
 			_tag: "ParseFailed",
 			path: target,
 			codec: options.codec.name,
@@ -171,9 +190,10 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	const discover = Effect.fn("ConfigFile.discover")(function* () {
 		const sources = [];
 		for (const resolver of options.resolvers) {
-			const found = yield* Effect.provide(resolver.resolve, resolverEnv);
+			const found = resolver.resolveMatch === void 0 ? Option.map(yield* Effect.provide(resolver.resolve, resolverEnv), (path) => ({ path })) : yield* Effect.provide(resolver.resolveMatch, resolverEnv);
 			if (Option.isSome(found)) {
-				const target = found.value;
+				const match = found.value;
+				const target = match.path;
 				yield* emit({
 					_tag: "Discovered",
 					path: target,
@@ -182,6 +202,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 				sources.push({
 					path: target,
 					resolver: resolver.name,
+					match,
 					value: yield* loadFrom(target)
 				});
 			}
@@ -239,7 +260,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 			path: Option.some(target),
 			issue: error.issue
 		}))));
-		const serialized = yield* options.codec.stringify(encoded).pipe(Effect.tapError((error) => emit({
+		const serialized = yield* options.codec.stringify(encoded).pipe(Effect.mapError((error) => withCodecPath(error, target)), Effect.tapError((error) => emit({
 			_tag: "StringifyFailed",
 			codec: options.codec.name,
 			error
@@ -353,7 +374,7 @@ const read = (path, options) => Effect.gen(function* () {
 		path,
 		cause
 	})));
-	const parsed = yield* options.codec.parse(raw);
+	const parsed = yield* options.codec.parse(raw).pipe(Effect.mapError((error) => withCodecPath(error, path)));
 	return yield* Schema.decodeUnknownEffect(options.schema)(parsed, options.parseOptions).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
 		path: Option.some(path),
 		issue: error.issue

package/ConfigResolver.js

@@ -2,48 +2,72 @@ import { Effect, FileSystem, Option, Path } from "effect";
 import { Walker } from "@effected/walker";
 
 //#region src/ConfigResolver.ts
+/**
+* Build a resolver from a match-reporting lookup, deriving `resolve` from it.
+*
+* @remarks
+* Every built-in goes through here, so `resolve` and `resolveMatch` are one
+* implementation and cannot drift.
+*/
+const fromMatch = (name, resolveMatch) => ({
+	name,
+	resolve: Effect.map(resolveMatch, Option.map((match) => match.path)),
+	resolveMatch
+});
 /** Absorb any failure into `Option.none()` — the resolver contract. */
 const absorb = (effect) => Effect.catch(effect, () => Effect.succeed(Option.none()));
 const cwdOf = (given) => given ?? globalThis.process?.cwd?.() ?? "/";
-const explicitPath = (target) => ({
-	name: "explicit",
-	resolve: absorb(Effect.gen(function* () {
-		return (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some(target) : Option.none();
-	}))
-});
-const staticDir = (options) => ({
-	name: "static",
-	resolve: 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(candidate) : Option.none();
-	}))
-});
-const upwardWalk = (options) => ({
-	name: "walk",
-	resolve: Effect.gen(function* () {
-		const path = yield* Path.Path;
-		const subpaths = options.subpaths ?? ["."];
-		const dirs = yield* Walker.ascend(cwdOf(options.cwd), { ...options.stopAt !== void 0 && { stopAt: options.stopAt } });
-		return yield* Walker.findUpward(dirs, (dir) => subpaths.map((sub) => path.join(dir, sub, options.filename)));
-	})
-});
+const explicitPath = (target) => fromMatch("explicit", absorb(Effect.gen(function* () {
+	return (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some({ path: target }) : Option.none();
+})));
+const staticDir = (options) => fromMatch("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();
+})));
+const upwardWalk = (options) => fromMatch(options.name ?? "walk", Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const subpaths = options.subpaths ?? ["."];
+	const filenames = options.filenames ?? [options.filename];
+	const dirs = yield* Walker.ascend(cwdOf(options.cwd), { ...options.stopAt !== void 0 && { stopAt: options.stopAt } });
+	const candidates = [];
+	for (const dir of dirs) for (const sub of subpaths) for (const filename of filenames) candidates.push({
+		path: path.join(dir, sub, filename),
+		dir,
+		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)));
+}));
 /**
 * 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) => ({
-	name,
-	resolve: Effect.gen(function* () {
-		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();
-		const subpaths = options.subpaths ?? ["."];
-		return yield* Walker.findUpward([root.value], (dir) => subpaths.map((sub) => path.join(dir, sub, options.filename)));
-	})
-});
+const rootAnchored = (name, isRoot, options) => fromMatch(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();
+	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 }
+		};
+	});
+}));
 /** `.git` may be a directory (a normal repo) or a file (a worktree pointing at the real repo). */
 const isGitRoot = (dir) => Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
@@ -66,17 +90,19 @@ const isWorkspaceRoot = (dir) => Effect.gen(function* () {
 });
 const gitRoot = (options) => rootAnchored("git", isGitRoot, options);
 const workspaceRoot = (options) => rootAnchored("workspace", isWorkspaceRoot, options);
-const systemEtc = (options) => ({
-	name: "system",
-	resolve: absorb(Effect.gen(function* () {
-		if (globalThis.process?.platform === "win32") return Option.none();
-		const fs = yield* FileSystem.FileSystem;
-		const path = yield* Path.Path;
-		const base = options.dir ?? "/etc";
-		const candidate = path.join(base, options.app, options.filename);
-		return (yield* fs.exists(candidate)) ? Option.some(candidate) : Option.none();
-	}))
-});
+const systemEtc = (options) => fromMatch("system", absorb(Effect.gen(function* () {
+	if (globalThis.process?.platform === "win32") return Option.none();
+	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();
+})));
 /**
 * Built-in resolvers, in the order a typical chain uses them.
 *
@@ -91,6 +117,17 @@ var ConfigResolver = class {
 	/**
 	* Ascends from `cwd` (or the process cwd) toward `stopAt`, resolving the
 	* first `subpaths/filename` combination found at each level.
+	*
+	* @remarks
+	* `filenames` replaces `filename` with a per-directory candidate list: every
+	* name is probed at one ancestor before the walk ascends, so a child's
+	* second candidate still beats a parent's first. Registering one resolver
+	* per filename cannot do this — the chain runs a resolver to the filesystem
+	* root before starting the next.
+	*
+	* `name` overrides the reported `"walk"` so two walks in one chain are
+	* distinguishable; `ConfigSource.match` identifies the matching candidate
+	* more precisely still.
 	*/
 	static upwardWalk = upwardWalk;
 	/**

package/index.d.ts

@@ -7,6 +7,17 @@ declare const ConfigCodecError_base: Schema.Class<ConfigCodecError, Schema.Tagge
   readonly operation: Schema.Literals<readonly ["parse", "stringify"]>;
   /** The underlying failure, preserved structurally. */
   readonly cause: Schema.Defect;
+  /**
+   * The file the content came from, when a caller knew it.
+   *
+   * @remarks
+   * A codec sees a string, never a path, so it cannot fill this in itself.
+   * `ConfigFile`'s read/write pipeline does: every site that feeds a codec a
+   * path it resolved re-raises the error with `path` attached, so a discovery
+   * pass over several candidates still names the file that failed. Absent
+   * only when a codec was driven directly, outside that pipeline.
+   */
+  readonly path: Schema.optionalKey<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Indicates that a codec failed to parse or stringify configuration content.
@@ -15,6 +26,15 @@ declare const ConfigCodecError_base: Schema.Class<ConfigCodecError, Schema.Tagge
  * The underlying failure is preserved structurally in `cause` — it is never
  * stringified. Route on the `"ConfigCodecError"` tag with `Effect.catchTag`.
  *
+ * `path` names the offending file when the error came through `ConfigFile`,
+ * which is what makes a failure during multi-candidate discovery reportable.
+ *
+ * `message` deliberately does NOT name the path — read `path` when you need it.
+ * A wrapper that renders its own message almost always names the file too, so
+ * a message carrying the path would compose into a rendering that prints the
+ * same file twice. The doubling is the default outcome, not an unlucky one:
+ * the field is the API, and the message is a bare summary.
+ *
  * @public
  */
 export declare class ConfigCodecError extends ConfigCodecError_base {
@@ -242,7 +262,103 @@ export declare class ConfigEvents extends ConfigEvents_base {
 export interface ConfigResolver<R = never> {
   readonly name: string;
   readonly resolve: Effect.Effect<Option.Option<string>, never, R>;
+  /**
+   * The same lookup, reporting **how** the file was found rather than only
+   * where.
+   *
+   * @remarks
+   * Optional, and optional forever: a hand-rolled resolver that omits it is a
+   * complete `ConfigResolver`, and the pipeline falls back to `resolve`,
+   * reporting a bare `{ path }` match. Every built-in implements it, and
+   * derives `resolve` from it, so the two can never disagree.
+   *
+   * It exists because a resolver's `name` cannot identify *which* candidate
+   * matched once one resolver probes several — `upwardWalk` with a
+   * `filenames` list, or with `subpaths`, is one resolver with many
+   * candidates. A consumer that needs the anchor directory (a CLI computing
+   * its project root from the discovered config) reads
+   * {@link ConfigMatch.dir} instead of string-matching the discovered path's
+   * tail.
+   */
+  readonly resolveMatch?: Effect.Effect<Option.Option<ConfigMatch>, never, R>;
 }
+/**
+ * How a resolver found a config file, not merely where.
+ *
+ * @remarks
+ * `path` is always present; the rest describe the candidate that matched and
+ * are populated only when the resolver knows them. `dir` is the **anchor**: the
+ * directory the candidate was resolved against — the ancestor `upwardWalk`
+ * stopped at, the root `gitRoot`/`workspaceRoot` found, `staticDir`'s `dir`.
+ * `subpath` and `filename` are the `subpaths`/`filenames` entries that matched,
+ * exactly as the caller spelled them.
+ *
+ * @public
+ */
+interface ConfigMatch {
+  /** The filesystem path that matched. */
+  readonly path: string;
+  /** The directory the matching candidate was resolved against, when the resolver has one. */
+  readonly dir?: string;
+  /** The `subpaths` entry that matched, when the resolver takes `subpaths`. */
+  readonly subpath?: string;
+  /** The `filenames`/`filename` entry that matched, when the resolver takes one. */
+  readonly filename?: string;
+}
+/**
+ * Options for `ConfigResolver.upwardWalk`.
+ *
+ * @remarks
+ * Exactly one of `filename` and `filenames` is given. `filename` is the
+ * original one-name form and keeps working unchanged; `filenames` is the
+ * per-directory candidate list — every name is probed at each ancestor before
+ * the walk ascends, which is the "config-dir" convention (`.app.toml`, then
+ * `app.toml`, then `.config/app.toml`, all at one level) that separate
+ * `upwardWalk` entries cannot express, because the chain exhausts one resolver
+ * to the filesystem root before starting the next.
+ *
+ * A `filenames` entry may itself carry a relative directory
+ * (`".config/app.toml"`), which is how a mixed convention is spelled without a
+ * `subpaths` cross product.
+ *
+ * @public
+ */
+type UpwardWalkOptions = {
+  /** The single file name probed at each ancestor directory. */
+  readonly filename: string;
+  readonly filenames?: undefined;
+  /** Where the walk starts. Defaults to the process cwd. */
+  readonly cwd?: string;
+  /** An absolute ceiling the walk stops at, inclusive. */
+  readonly stopAt?: string;
+  /** Directories probed under each ancestor, in order. Defaults to `["."]`. */
+  readonly subpaths?: ReadonlyArray<string>;
+  /**
+   * The resolver's reported name. Defaults to `"walk"`.
+   *
+   * @remarks
+   * Two `upwardWalk` entries in one chain otherwise report the same
+   * `"walk"`, so `ConfigSource.resolver` cannot tell them apart. Pass a
+   * distinct name per call — or read `ConfigSource.match` instead, which
+   * identifies the matching candidate rather than the resolver.
+   */
+  readonly name?: string;
+} | {
+  /**
+   * The candidate file names probed at each ancestor directory, in order,
+   * before the walk ascends.
+   */
+  readonly filenames: ReadonlyArray<string>;
+  readonly filename?: undefined;
+  /** Where the walk starts. Defaults to the process cwd. */
+  readonly cwd?: string;
+  /** An absolute ceiling the walk stops at, inclusive. */
+  readonly stopAt?: string;
+  /** Directories probed under each ancestor, in order. Defaults to `["."]`. */
+  readonly subpaths?: ReadonlyArray<string>;
+  /** The resolver's reported name. Defaults to `"walk"`. */
+  readonly name?: string;
+};
 /**
  * Built-in resolvers, in the order a typical chain uses them.
  *
@@ -260,13 +376,19 @@ export declare class ConfigResolver {
   /**
    * Ascends from `cwd` (or the process cwd) toward `stopAt`, resolving the
    * first `subpaths/filename` combination found at each level.
+   *
+   * @remarks
+   * `filenames` replaces `filename` with a per-directory candidate list: every
+   * name is probed at one ancestor before the walk ascends, so a child's
+   * second candidate still beats a parent's first. Registering one resolver
+   * per filename cannot do this — the chain runs a resolver to the filesystem
+   * root before starting the next.
+   *
+   * `name` overrides the reported `"walk"` so two walks in one chain are
+   * distinguishable; `ConfigSource.match` identifies the matching candidate
+   * more precisely still.
    */
-  static readonly upwardWalk: (options: {
-    readonly filename: string;
-    readonly cwd?: string;
-    readonly stopAt?: string;
-    readonly subpaths?: ReadonlyArray<string>;
-  }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+  static readonly upwardWalk: (options: UpwardWalkOptions) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
   /**
    * Ascends from `cwd` to the nearest workspace root — a directory with a
    * `pnpm-workspace.yaml`, or a `package.json` carrying a `workspaces` field —
@@ -314,6 +436,18 @@ interface ConfigSource<A> {
   readonly path: string;
   /** The name of the resolver that found it. */
   readonly resolver: string;
+  /**
+   * How the resolver found it — the anchor directory and the candidate that
+   * matched.
+   *
+   * @remarks
+   * Populated by `ConfigFile.discover` for every source it produces: a
+   * resolver implementing `ConfigResolver.resolveMatch` reports its own
+   * detail, and one that does not yields a bare `{ path }`. Optional on the
+   * type so a hand-built `ConfigSource` — a merge-strategy test, a synthetic
+   * source — stays valid without one.
+   */
+  readonly match?: ConfigMatch;
   /** The decoded, validated configuration value. */
   readonly value: A;
 }
@@ -1097,5 +1231,5 @@ export declare const TomlCodec: ConfigCodec;
  */
 export declare const YamlCodec: ConfigCodec;
 //#endregion
-export type { ConfigCodec, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMigrationOptions, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources };
+export type { ConfigCodec, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, 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.6.0",
+	"version": "0.7.0",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -45,8 +45,8 @@
 	"peerDependencies": {
 		"@effected/jsonc": "^0.9.0",
 		"@effected/toml": "^0.6.0",
-		"@effected/walker": "^0.6.0",
-		"@effected/yaml": "^0.13.0",
+		"@effected/walker": "^0.7.0",
+		"@effected/yaml": "^0.14.0",
 		"effect": "4.0.0-rc.112"
 	},
 	"engines": {