@optique/config 1.0.0-dev.428 → 1.0.0-dev.429

package/dist/{index-CYn_0yAG.d.ts → index-0XaZnIP1.d.ts}

@@ -9,6 +9,26 @@ import { Parser } from "@optique/core/parser";
  * @since 0.10.0
  */
 declare const configKey: unique symbol;
+/**
+ * Unique symbol for config metadata in annotations.
+ * @since 1.0.0
+ */
+declare const configMetaKey: unique symbol;
+/**
+ * Metadata about the loaded config source.
+ *
+ * @since 1.0.0
+ */
+interface ConfigMeta {
+  /**
+   * Directory containing the config file.
+   */
+  readonly configDir: string;
+  /**
+   * Absolute path to the config file.
+   */
+  readonly configPath: string;
+}
 /**
  * Sets active config data for a context.
  * @internal
@@ -24,6 +44,21 @@ declare function getActiveConfig<T>(contextId: symbol): T | undefined;
  * @internal
  */
 declare function clearActiveConfig(contextId: symbol): void;
+/**
+ * Sets active config metadata for a context.
+ * @internal
+ */
+declare function setActiveConfigMeta<T>(contextId: symbol, meta: T): void;
+/**
+ * Gets active config metadata for a context.
+ * @internal
+ */
+declare function getActiveConfigMeta<T>(contextId: symbol): T | undefined;
+/**
+ * Clears active config metadata for a context.
+ * @internal
+ */
+declare function clearActiveConfigMeta(contextId: symbol): void;
 /**
  * Options for creating a config context.
  *
@@ -64,7 +99,7 @@ interface ConfigContextRequiredOptions {
  * @template T The validated config data type.
  * @since 0.10.0
  */
-interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
+interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<ConfigContextRequiredOptions> {
   /**
    * The Standard Schema validator for the config file.
    */
@@ -77,6 +112,7 @@ interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
  * with runWith() or runWithConfig() to provide configuration file support.
  *
  * @template T The output type of the config schema.
+ * @template TConfigMeta The metadata type for config sources.
  * @param options Configuration options including schema and optional parser.
  * @returns A config context that can be used with bindConfig() and runWithConfig().
  * @since 0.10.0
@@ -94,7 +130,7 @@ interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
  * const configContext = createConfigContext({ schema });
  * ```
  */
-declare function createConfigContext<T>(options: ConfigContextOptions<T>): ConfigContext<T>;
+declare function createConfigContext<T, TConfigMeta = ConfigMeta>(options: ConfigContextOptions<T>): ConfigContext<T, TConfigMeta>;
 /**
  * Options for binding a parser to config values.
  *
@@ -102,17 +138,18 @@ declare function createConfigContext<T>(options: ConfigContextOptions<T>): Confi
  * @template TValue The value type extracted from config.
  * @since 0.10.0
  */
-interface BindConfigOptions<T, TValue> {
+interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
   /**
    * The config context to use for fallback values.
    */
-  readonly context: ConfigContext<T>;
+  readonly context: ConfigContext<T, TConfigMeta>;
   /**
    * Key or accessor function to extract the value from config.
    * Can be a property key (for top-level config values) or a function
-   * that extracts nested values.
+   * that extracts nested values. Accessor callbacks receive config metadata
+   * as the second argument.
    */
-  readonly key: keyof T | ((config: T) => TValue);
+  readonly key: keyof T | ((config: T, meta: TConfigMeta) => TValue);
   /**
    * Default value to use when neither CLI nor config provides a value.
    * If not specified, the parser will fail when no value is available.
@@ -150,6 +187,6 @@ interface BindConfigOptions<T, TValue> {
  * });
  * ```
  */
-declare function bindConfig<M extends "sync" | "async", TValue, TState, T>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue>): Parser<M, TValue, TState>;
+declare function bindConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue, TConfigMeta>): Parser<M, TValue, TState>;
 //#endregion
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/dist/{index-D25zYfjf.d.cts → index-BZLEbR0f.d.cts}

@@ -9,6 +9,26 @@ import { Parser } from "@optique/core/parser";
  * @since 0.10.0
  */
 declare const configKey: unique symbol;
+/**
+ * Unique symbol for config metadata in annotations.
+ * @since 1.0.0
+ */
+declare const configMetaKey: unique symbol;
+/**
+ * Metadata about the loaded config source.
+ *
+ * @since 1.0.0
+ */
+interface ConfigMeta {
+  /**
+   * Directory containing the config file.
+   */
+  readonly configDir: string;
+  /**
+   * Absolute path to the config file.
+   */
+  readonly configPath: string;
+}
 /**
  * Sets active config data for a context.
  * @internal
@@ -24,6 +44,21 @@ declare function getActiveConfig<T>(contextId: symbol): T | undefined;
  * @internal
  */
 declare function clearActiveConfig(contextId: symbol): void;
+/**
+ * Sets active config metadata for a context.
+ * @internal
+ */
+declare function setActiveConfigMeta<T>(contextId: symbol, meta: T): void;
+/**
+ * Gets active config metadata for a context.
+ * @internal
+ */
+declare function getActiveConfigMeta<T>(contextId: symbol): T | undefined;
+/**
+ * Clears active config metadata for a context.
+ * @internal
+ */
+declare function clearActiveConfigMeta(contextId: symbol): void;
 /**
  * Options for creating a config context.
  *
@@ -64,7 +99,7 @@ interface ConfigContextRequiredOptions {
  * @template T The validated config data type.
  * @since 0.10.0
  */
-interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
+interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<ConfigContextRequiredOptions> {
   /**
    * The Standard Schema validator for the config file.
    */
@@ -77,6 +112,7 @@ interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
  * with runWith() or runWithConfig() to provide configuration file support.
  *
  * @template T The output type of the config schema.
+ * @template TConfigMeta The metadata type for config sources.
  * @param options Configuration options including schema and optional parser.
  * @returns A config context that can be used with bindConfig() and runWithConfig().
  * @since 0.10.0
@@ -94,7 +130,7 @@ interface ConfigContext<T> extends SourceContext<ConfigContextRequiredOptions> {
  * const configContext = createConfigContext({ schema });
  * ```
  */
-declare function createConfigContext<T>(options: ConfigContextOptions<T>): ConfigContext<T>;
+declare function createConfigContext<T, TConfigMeta = ConfigMeta>(options: ConfigContextOptions<T>): ConfigContext<T, TConfigMeta>;
 /**
  * Options for binding a parser to config values.
  *
@@ -102,17 +138,18 @@ declare function createConfigContext<T>(options: ConfigContextOptions<T>): Confi
  * @template TValue The value type extracted from config.
  * @since 0.10.0
  */
-interface BindConfigOptions<T, TValue> {
+interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
   /**
    * The config context to use for fallback values.
    */
-  readonly context: ConfigContext<T>;
+  readonly context: ConfigContext<T, TConfigMeta>;
   /**
    * Key or accessor function to extract the value from config.
    * Can be a property key (for top-level config values) or a function
-   * that extracts nested values.
+   * that extracts nested values. Accessor callbacks receive config metadata
+   * as the second argument.
    */
-  readonly key: keyof T | ((config: T) => TValue);
+  readonly key: keyof T | ((config: T, meta: TConfigMeta) => TValue);
   /**
    * Default value to use when neither CLI nor config provides a value.
    * If not specified, the parser will fail when no value is available.
@@ -150,6 +187,6 @@ interface BindConfigOptions<T, TValue> {
  * });
  * ```
  */
-declare function bindConfig<M extends "sync" | "async", TValue, TState, T>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue>): Parser<M, TValue, TState>;
+declare function bindConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta>(parser: Parser<M, TValue, TState>, options: BindConfigOptions<T, TValue, TConfigMeta>): Parser<M, TValue, TState>;
 //#endregion
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/dist/index.cjs

@@ -1,8 +1,12 @@
-const require_src = require('./src-9MkUoh9z.cjs');
+const require_src = require('./src-loxvrkxq.cjs');
 
 exports.bindConfig = require_src.bindConfig;
 exports.clearActiveConfig = require_src.clearActiveConfig;
+exports.clearActiveConfigMeta = require_src.clearActiveConfigMeta;
 exports.configKey = require_src.configKey;
+exports.configMetaKey = require_src.configMetaKey;
 exports.createConfigContext = require_src.createConfigContext;
 exports.getActiveConfig = require_src.getActiveConfig;
-exports.setActiveConfig = require_src.setActiveConfig;
+exports.getActiveConfigMeta = require_src.getActiveConfigMeta;
+exports.setActiveConfig = require_src.setActiveConfig;
+exports.setActiveConfigMeta = require_src.setActiveConfigMeta;

package/dist/index.d.cts

@@ -1,2 +1,2 @@
-import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-D25zYfjf.cjs";
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta } from "./index-BZLEbR0f.cjs";
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./index-CYn_0yAG.js";
-export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+import { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta } from "./index-0XaZnIP1.js";
+export { BindConfigOptions, ConfigContext, ConfigContextOptions, ConfigContextRequiredOptions, ConfigMeta, bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig } from "./src-Dm_17c1d.js";
+import { bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta } from "./src-DaFxoeAp.js";
 
-export { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+export { bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/dist/run.cjs

@@ -1,4 +1,4 @@
-const require_src = require('./src-9MkUoh9z.cjs');
+const require_src = require('./src-loxvrkxq.cjs');
 const node_fs_promises = require_src.__toESM(require("node:fs/promises"));
 const node_path = require_src.__toESM(require("node:path"));
 const node_process = require_src.__toESM(require("node:process"));
@@ -18,132 +18,69 @@ function createConfigSourceContext(context, options) {
 		async getAnnotations(parsed) {
 			if (!parsed) return {};
 			let configData;
+			let configMeta;
 			if ("load" in options) {
 				const customOptions = options;
-				try {
-					const rawData = await Promise.resolve(customOptions.load(parsed));
-					const validation = context.schema["~standard"].validate(rawData);
-					let validationResult;
-					if (validation instanceof Promise) validationResult = await validation;
-					else validationResult = validation;
-					if (validationResult.issues) {
-						const firstIssue = validationResult.issues[0];
-						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-					}
-					configData = validationResult.value;
-				} catch (error) {
-					if (error instanceof Error && error.message.includes("validation")) throw error;
-					throw error;
+				const loaded = await Promise.resolve(customOptions.load(parsed));
+				const validation = context.schema["~standard"].validate(loaded.config);
+				let validationResult;
+				if (validation instanceof Promise) validationResult = await validation;
+				else validationResult = validation;
+				if (validationResult.issues) {
+					const firstIssue = validationResult.issues[0];
+					throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
 				}
+				configData = validationResult.value;
+				configMeta = loaded.meta;
 			} else {
 				const singleFileOptions = options;
 				const configPath = singleFileOptions.getConfigPath(parsed);
-				if (configPath) try {
-					const contents = await (0, node_fs_promises.readFile)(configPath);
-					let rawData;
-					if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
-					else {
-						const text = new TextDecoder().decode(contents);
-						rawData = JSON.parse(text);
-					}
-					const validation = context.schema["~standard"].validate(rawData);
-					let validationResult;
-					if (validation instanceof Promise) validationResult = await validation;
-					else validationResult = validation;
-					if (validationResult.issues) {
-						const firstIssue = validationResult.issues[0];
-						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+				if (configPath) {
+					const absoluteConfigPath = (0, node_path.resolve)(configPath);
+					const singleFileMeta = {
+						configDir: (0, node_path.dirname)(absoluteConfigPath),
+						configPath: absoluteConfigPath
+					};
+					try {
+						const contents = await (0, node_fs_promises.readFile)(absoluteConfigPath);
+						let rawData;
+						if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
+						else {
+							const text = new TextDecoder().decode(contents);
+							rawData = JSON.parse(text);
+						}
+						const validation = context.schema["~standard"].validate(rawData);
+						let validationResult;
+						if (validation instanceof Promise) validationResult = await validation;
+						else validationResult = validation;
+						if (validationResult.issues) {
+							const firstIssue = validationResult.issues[0];
+							throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+						}
+						configData = validationResult.value;
+						configMeta = singleFileMeta;
+					} catch (error) {
+						if (isErrnoException(error) && error.code === "ENOENT") configData = void 0;
+						else if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${absoluteConfigPath}: ${error.message}`);
+						else throw error;
 					}
-					configData = validationResult.value;
-				} catch (error) {
-					if (isErrnoException(error) && error.code === "ENOENT") configData = void 0;
-					else if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${configPath}: ${error.message}`);
-					else throw error;
 				}
 			}
 			if (configData !== void 0 && configData !== null) {
 				require_src.setActiveConfig(context.id, configData);
+				if (configMeta !== void 0) {
+					require_src.setActiveConfigMeta(context.id, configMeta);
+					return {
+						[require_src.configKey]: configData,
+						[require_src.configMetaKey]: configMeta
+					};
+				}
 				return { [require_src.configKey]: configData };
 			}
 			return {};
 		}
 	};
 }
-/**
-* Runs a parser with configuration file support using two-pass parsing.
-*
-* This function performs the following steps:
-* 1. First pass: Parse arguments to extract config path or data
-* 2. Load and validate: Load config file(s) and validate using Standard Schema
-* 3. Second pass: Parse arguments again with config data as annotations
-*
-* The priority order for values is: CLI > config file > default.
-*
-* The function also supports help, version, and completion features. When these
-* special commands are detected, config loading is skipped entirely, ensuring
-* these features work even when config files don't exist.
-*
-* @template M The parser mode (sync or async).
-* @template TValue The parser value type.
-* @template TState The parser state type.
-* @template T The config data type.
-* @template THelp The return type when help is shown.
-* @template TError The return type when an error occurs.
-* @param parser The parser to execute.
-* @param context The config context with schema.
-* @param options Run options - either SingleFileOptions or CustomLoadOptions.
-* @returns Promise that resolves to the parsed result.
-* @throws Error if config file validation fails.
-* @since 0.10.0
-*
-* @example Single file mode
-* ```typescript
-* import { z } from "zod";
-* import { runWithConfig } from "@optique/config/run";
-* import { createConfigContext, bindConfig } from "@optique/config";
-*
-* const schema = z.object({
-*   host: z.string(),
-*   port: z.number(),
-* });
-*
-* const context = createConfigContext({ schema });
-*
-* const parser = object({
-*   config: option("--config", string()),
-*   host: bindConfig(option("--host", string()), {
-*     context,
-*     key: "host",
-*     default: "localhost",
-*   }),
-* });
-*
-* const result = await runWithConfig(parser, context, {
-*   getConfigPath: (parsed) => parsed.config,
-*   args: process.argv.slice(2),
-*   help: { mode: "option", onShow: () => process.exit(0) },
-*   version: { value: "1.0.0", onShow: () => process.exit(0) },
-* });
-* ```
-*
-* @example Custom load mode (multi-file merging)
-* ```typescript
-* import { deepMerge } from "es-toolkit";
-*
-* const result = await runWithConfig(parser, context, {
-*   load: async (parsed) => {
-*     const configs = await Promise.all([
-*       loadToml("/etc/app/config.toml").catch(() => ({})),
-*       loadToml("~/.config/app/config.toml").catch(() => ({})),
-*       loadToml("./.app.toml").catch(() => ({})),
-*     ]);
-*     return deepMerge(...configs);
-*   },
-*   args: process.argv.slice(2),
-*   help: { mode: "option", onShow: () => process.exit(0) },
-* });
-* ```
-*/
 async function runWithConfig(parser, context, options) {
 	const effectiveProgramName = options.programName ?? (typeof node_process.default !== "undefined" && node_process.default.argv?.[1] ? (0, node_path.basename)(node_process.default.argv[1]) : "cli");
 	const wrapperContext = createConfigSourceContext(context, options);
@@ -182,6 +119,7 @@ async function runWithConfig(parser, context, options) {
 		throw error;
 	} finally {
 		require_src.clearActiveConfig(context.id);
+		require_src.clearActiveConfigMeta(context.id);
 	}
 }
 

package/dist/run.d.cts

@@ -1,4 +1,4 @@
-import { ConfigContext } from "./index-D25zYfjf.cjs";
+import { ConfigContext, ConfigMeta } from "./index-BZLEbR0f.cjs";
 import { Parser } from "@optique/core/parser";
 import { RunOptions } from "@optique/core/facade";
 
@@ -109,6 +109,22 @@ interface SingleFileOptions<TValue, THelp = void, TError = never> {
    */
   readonly onError?: RunOptions<THelp, TError>["onError"];
 }
+/**
+ * Result type for custom config loading.
+ *
+ * @template TConfigMeta Metadata type associated with loaded config data.
+ * @since 1.0.0
+ */
+interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
+  /**
+   * Raw config data to validate against the schema.
+   */
+  readonly config: unknown;
+  /**
+   * Metadata about where the config came from.
+   */
+  readonly meta: TConfigMeta;
+}
 /**
  * Options for custom config loading with multi-file merging support.
  *
@@ -117,7 +133,7 @@ interface SingleFileOptions<TValue, THelp = void, TError = never> {
  * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-interface CustomLoadOptions<TValue, THelp = void, TError = never> {
+interface CustomLoadOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> {
   /**
    * Custom loader function that receives the first-pass parse result and
    * returns the config data (or a Promise of it). This allows full control
@@ -126,9 +142,9 @@ interface CustomLoadOptions<TValue, THelp = void, TError = never> {
    * The returned data will be validated against the schema.
    *
    * @param parsed The result from the first parse pass.
-   * @returns The raw config data (will be validated by schema).
+   * @returns Config data and metadata (config is validated by schema).
    */
-  readonly load: (parsed: TValue) => Promise<unknown> | unknown;
+  readonly load: (parsed: TValue) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
   /**
    * Command-line arguments to parse.
    * If not provided, defaults to an empty array.
@@ -216,7 +232,7 @@ interface CustomLoadOptions<TValue, THelp = void, TError = never> {
  * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, THelp, TError>;
+type RunWithConfigOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, TConfigMeta, THelp, TError>;
 /**
  * Runs a parser with configuration file support using two-pass parsing.
  *
@@ -235,6 +251,7 @@ type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOpti
  * @template TValue The parser value type.
  * @template TState The parser state type.
  * @template T The config data type.
+ * @template TConfigMeta The config metadata type.
  * @template THelp The return type when help is shown.
  * @template TError The return type when an error occurs.
  * @param parser The parser to execute.
@@ -285,13 +302,22 @@ type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOpti
  *       loadToml("~/.config/app/config.toml").catch(() => ({})),
  *       loadToml("./.app.toml").catch(() => ({})),
  *     ]);
- *     return deepMerge(...configs);
+ *
+ *     const configPath = parsed.config ?? "./.app.toml";
+ *     return {
+ *       config: deepMerge(...configs),
+ *       meta: {
+ *         configPath,
+ *         configDir: configPath.slice(0, configPath.lastIndexOf("/")),
+ *       },
+ *     };
  *   },
  *   args: process.argv.slice(2),
  *   help: { mode: "option", onShow: () => process.exit(0) },
  * });
  * ```
  */
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T>, options: RunWithConfigOptions<TValue, THelp, TError>): Promise<TValue>;
+declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, ConfigMeta>, options: SingleFileOptions<TValue, THelp, TError>): Promise<TValue>;
+declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, TConfigMeta>, options: CustomLoadOptions<TValue, TConfigMeta, THelp, TError>): Promise<TValue>;
 //#endregion
-export { CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };
+export { ConfigLoadResult, CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };

package/dist/run.d.ts

@@ -1,4 +1,4 @@
-import { ConfigContext } from "./index-CYn_0yAG.js";
+import { ConfigContext, ConfigMeta } from "./index-0XaZnIP1.js";
 import { RunOptions } from "@optique/core/facade";
 import { Parser } from "@optique/core/parser";
 
@@ -109,6 +109,22 @@ interface SingleFileOptions<TValue, THelp = void, TError = never> {
    */
   readonly onError?: RunOptions<THelp, TError>["onError"];
 }
+/**
+ * Result type for custom config loading.
+ *
+ * @template TConfigMeta Metadata type associated with loaded config data.
+ * @since 1.0.0
+ */
+interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
+  /**
+   * Raw config data to validate against the schema.
+   */
+  readonly config: unknown;
+  /**
+   * Metadata about where the config came from.
+   */
+  readonly meta: TConfigMeta;
+}
 /**
  * Options for custom config loading with multi-file merging support.
  *
@@ -117,7 +133,7 @@ interface SingleFileOptions<TValue, THelp = void, TError = never> {
  * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-interface CustomLoadOptions<TValue, THelp = void, TError = never> {
+interface CustomLoadOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> {
   /**
    * Custom loader function that receives the first-pass parse result and
    * returns the config data (or a Promise of it). This allows full control
@@ -126,9 +142,9 @@ interface CustomLoadOptions<TValue, THelp = void, TError = never> {
    * The returned data will be validated against the schema.
    *
    * @param parsed The result from the first parse pass.
-   * @returns The raw config data (will be validated by schema).
+   * @returns Config data and metadata (config is validated by schema).
    */
-  readonly load: (parsed: TValue) => Promise<unknown> | unknown;
+  readonly load: (parsed: TValue) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
   /**
    * Command-line arguments to parse.
    * If not provided, defaults to an empty array.
@@ -216,7 +232,7 @@ interface CustomLoadOptions<TValue, THelp = void, TError = never> {
  * @template TError The return type when an error occurs.
  * @since 0.10.0
  */
-type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, THelp, TError>;
+type RunWithConfigOptions<TValue, TConfigMeta = ConfigMeta, THelp = void, TError = never> = SingleFileOptions<TValue, THelp, TError> | CustomLoadOptions<TValue, TConfigMeta, THelp, TError>;
 /**
  * Runs a parser with configuration file support using two-pass parsing.
  *
@@ -235,6 +251,7 @@ type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOpti
  * @template TValue The parser value type.
  * @template TState The parser state type.
  * @template T The config data type.
+ * @template TConfigMeta The config metadata type.
  * @template THelp The return type when help is shown.
  * @template TError The return type when an error occurs.
  * @param parser The parser to execute.
@@ -285,13 +302,22 @@ type RunWithConfigOptions<TValue, THelp = void, TError = never> = SingleFileOpti
  *       loadToml("~/.config/app/config.toml").catch(() => ({})),
  *       loadToml("./.app.toml").catch(() => ({})),
  *     ]);
- *     return deepMerge(...configs);
+ *
+ *     const configPath = parsed.config ?? "./.app.toml";
+ *     return {
+ *       config: deepMerge(...configs),
+ *       meta: {
+ *         configPath,
+ *         configDir: configPath.slice(0, configPath.lastIndexOf("/")),
+ *       },
+ *     };
  *   },
  *   args: process.argv.slice(2),
  *   help: { mode: "option", onShow: () => process.exit(0) },
  * });
  * ```
  */
-declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T>, options: RunWithConfigOptions<TValue, THelp, TError>): Promise<TValue>;
+declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, ConfigMeta>, options: SingleFileOptions<TValue, THelp, TError>): Promise<TValue>;
+declare function runWithConfig<M extends "sync" | "async", TValue, TState, T, TConfigMeta = ConfigMeta, THelp = void, TError = never>(parser: Parser<M, TValue, TState>, context: ConfigContext<T, TConfigMeta>, options: CustomLoadOptions<TValue, TConfigMeta, THelp, TError>): Promise<TValue>;
 //#endregion
-export { CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };
+export { ConfigLoadResult, CustomLoadOptions, RunWithConfigOptions, SingleFileOptions, runWithConfig };

package/dist/run.js

@@ -1,6 +1,6 @@
-import { clearActiveConfig, configKey, setActiveConfig } from "./src-Dm_17c1d.js";
+import { clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, setActiveConfig, setActiveConfigMeta } from "./src-DaFxoeAp.js";
 import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import process from "node:process";
 import { runWith } from "@optique/core/facade";
 
@@ -18,132 +18,69 @@ function createConfigSourceContext(context, options) {
 		async getAnnotations(parsed) {
 			if (!parsed) return {};
 			let configData;
+			let configMeta;
 			if ("load" in options) {
 				const customOptions = options;
-				try {
-					const rawData = await Promise.resolve(customOptions.load(parsed));
-					const validation = context.schema["~standard"].validate(rawData);
-					let validationResult;
-					if (validation instanceof Promise) validationResult = await validation;
-					else validationResult = validation;
-					if (validationResult.issues) {
-						const firstIssue = validationResult.issues[0];
-						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
-					}
-					configData = validationResult.value;
-				} catch (error) {
-					if (error instanceof Error && error.message.includes("validation")) throw error;
-					throw error;
+				const loaded = await Promise.resolve(customOptions.load(parsed));
+				const validation = context.schema["~standard"].validate(loaded.config);
+				let validationResult;
+				if (validation instanceof Promise) validationResult = await validation;
+				else validationResult = validation;
+				if (validationResult.issues) {
+					const firstIssue = validationResult.issues[0];
+					throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
 				}
+				configData = validationResult.value;
+				configMeta = loaded.meta;
 			} else {
 				const singleFileOptions = options;
 				const configPath = singleFileOptions.getConfigPath(parsed);
-				if (configPath) try {
-					const contents = await readFile(configPath);
-					let rawData;
-					if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
-					else {
-						const text = new TextDecoder().decode(contents);
-						rawData = JSON.parse(text);
-					}
-					const validation = context.schema["~standard"].validate(rawData);
-					let validationResult;
-					if (validation instanceof Promise) validationResult = await validation;
-					else validationResult = validation;
-					if (validationResult.issues) {
-						const firstIssue = validationResult.issues[0];
-						throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+				if (configPath) {
+					const absoluteConfigPath = resolve(configPath);
+					const singleFileMeta = {
+						configDir: dirname(absoluteConfigPath),
+						configPath: absoluteConfigPath
+					};
+					try {
+						const contents = await readFile(absoluteConfigPath);
+						let rawData;
+						if (singleFileOptions.fileParser) rawData = singleFileOptions.fileParser(contents);
+						else {
+							const text = new TextDecoder().decode(contents);
+							rawData = JSON.parse(text);
+						}
+						const validation = context.schema["~standard"].validate(rawData);
+						let validationResult;
+						if (validation instanceof Promise) validationResult = await validation;
+						else validationResult = validation;
+						if (validationResult.issues) {
+							const firstIssue = validationResult.issues[0];
+							throw new Error(`Config validation failed: ${firstIssue?.message ?? "Unknown error"}`);
+						}
+						configData = validationResult.value;
+						configMeta = singleFileMeta;
+					} catch (error) {
+						if (isErrnoException(error) && error.code === "ENOENT") configData = void 0;
+						else if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${absoluteConfigPath}: ${error.message}`);
+						else throw error;
 					}
-					configData = validationResult.value;
-				} catch (error) {
-					if (isErrnoException(error) && error.code === "ENOENT") configData = void 0;
-					else if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${configPath}: ${error.message}`);
-					else throw error;
 				}
 			}
 			if (configData !== void 0 && configData !== null) {
 				setActiveConfig(context.id, configData);
+				if (configMeta !== void 0) {
+					setActiveConfigMeta(context.id, configMeta);
+					return {
+						[configKey]: configData,
+						[configMetaKey]: configMeta
+					};
+				}
 				return { [configKey]: configData };
 			}
 			return {};
 		}
 	};
 }
-/**
-* Runs a parser with configuration file support using two-pass parsing.
-*
-* This function performs the following steps:
-* 1. First pass: Parse arguments to extract config path or data
-* 2. Load and validate: Load config file(s) and validate using Standard Schema
-* 3. Second pass: Parse arguments again with config data as annotations
-*
-* The priority order for values is: CLI > config file > default.
-*
-* The function also supports help, version, and completion features. When these
-* special commands are detected, config loading is skipped entirely, ensuring
-* these features work even when config files don't exist.
-*
-* @template M The parser mode (sync or async).
-* @template TValue The parser value type.
-* @template TState The parser state type.
-* @template T The config data type.
-* @template THelp The return type when help is shown.
-* @template TError The return type when an error occurs.
-* @param parser The parser to execute.
-* @param context The config context with schema.
-* @param options Run options - either SingleFileOptions or CustomLoadOptions.
-* @returns Promise that resolves to the parsed result.
-* @throws Error if config file validation fails.
-* @since 0.10.0
-*
-* @example Single file mode
-* ```typescript
-* import { z } from "zod";
-* import { runWithConfig } from "@optique/config/run";
-* import { createConfigContext, bindConfig } from "@optique/config";
-*
-* const schema = z.object({
-*   host: z.string(),
-*   port: z.number(),
-* });
-*
-* const context = createConfigContext({ schema });
-*
-* const parser = object({
-*   config: option("--config", string()),
-*   host: bindConfig(option("--host", string()), {
-*     context,
-*     key: "host",
-*     default: "localhost",
-*   }),
-* });
-*
-* const result = await runWithConfig(parser, context, {
-*   getConfigPath: (parsed) => parsed.config,
-*   args: process.argv.slice(2),
-*   help: { mode: "option", onShow: () => process.exit(0) },
-*   version: { value: "1.0.0", onShow: () => process.exit(0) },
-* });
-* ```
-*
-* @example Custom load mode (multi-file merging)
-* ```typescript
-* import { deepMerge } from "es-toolkit";
-*
-* const result = await runWithConfig(parser, context, {
-*   load: async (parsed) => {
-*     const configs = await Promise.all([
-*       loadToml("/etc/app/config.toml").catch(() => ({})),
-*       loadToml("~/.config/app/config.toml").catch(() => ({})),
-*       loadToml("./.app.toml").catch(() => ({})),
-*     ]);
-*     return deepMerge(...configs);
-*   },
-*   args: process.argv.slice(2),
-*   help: { mode: "option", onShow: () => process.exit(0) },
-* });
-* ```
-*/
 async function runWithConfig(parser, context, options) {
 	const effectiveProgramName = options.programName ?? (typeof process !== "undefined" && process.argv?.[1] ? basename(process.argv[1]) : "cli");
 	const wrapperContext = createConfigSourceContext(context, options);
@@ -182,6 +119,7 @@ async function runWithConfig(parser, context, options) {
 		throw error;
 	} finally {
 		clearActiveConfig(context.id);
+		clearActiveConfigMeta(context.id);
 	}
 }
 

package/dist/{src-Dm_17c1d.js → src-DaFxoeAp.js}

@@ -8,6 +8,11 @@ import { message } from "@optique/core/message";
 */
 const configKey = Symbol.for("@optique/config");
 /**
+* Unique symbol for config metadata in annotations.
+* @since 1.0.0
+*/
+const configMetaKey = Symbol.for("@optique/config/meta");
+/**
 * Internal registry for active config data during runWithConfig execution.
 * This is a workaround for the limitation that object() doesn't propagate
 * annotations to child field parsers.
@@ -15,6 +20,11 @@ const configKey = Symbol.for("@optique/config");
 */
 const activeConfigRegistry = /* @__PURE__ */ new Map();
 /**
+* Internal registry for active config metadata during runWithConfig execution.
+* @internal
+*/
+const activeConfigMetaRegistry = /* @__PURE__ */ new Map();
+/**
 * Sets active config data for a context.
 * @internal
 */
@@ -36,12 +46,34 @@ function clearActiveConfig(contextId) {
 	activeConfigRegistry.delete(contextId);
 }
 /**
+* Sets active config metadata for a context.
+* @internal
+*/
+function setActiveConfigMeta(contextId, meta) {
+	activeConfigMetaRegistry.set(contextId, meta);
+}
+/**
+* Gets active config metadata for a context.
+* @internal
+*/
+function getActiveConfigMeta(contextId) {
+	return activeConfigMetaRegistry.get(contextId);
+}
+/**
+* Clears active config metadata for a context.
+* @internal
+*/
+function clearActiveConfigMeta(contextId) {
+	activeConfigMetaRegistry.delete(contextId);
+}
+/**
 * Creates a config context for use with Optique parsers.
 *
 * The config context implements the SourceContext interface and can be used
 * with runWith() or runWithConfig() to provide configuration file support.
 *
 * @template T The output type of the config schema.
+* @template TConfigMeta The metadata type for config sources.
 * @param options Configuration options including schema and optional parser.
 * @returns A config context that can be used with bindConfig() and runWithConfig().
 * @since 0.10.0
@@ -208,13 +240,15 @@ function bindConfig(parser, options) {
 function getConfigOrDefault(state, options) {
 	const annotations = getAnnotations(state);
 	let configData = annotations?.[configKey];
+	let configMeta = annotations?.[configMetaKey];
 	if (configData === void 0 || configData === null) {
 		const contextId = options.context.id;
 		configData = getActiveConfig(contextId);
+		configMeta = getActiveConfigMeta(contextId);
 	}
 	let configValue;
 	if (configData !== void 0 && configData !== null) if (typeof options.key === "function") try {
-		configValue = options.key(configData);
+		configValue = options.key(configData, configMeta);
 	} catch {
 		configValue = void 0;
 	}
@@ -234,4 +268,4 @@ function getConfigOrDefault(state, options) {
 }
 
 //#endregion
-export { bindConfig, clearActiveConfig, configKey, createConfigContext, getActiveConfig, setActiveConfig };
+export { bindConfig, clearActiveConfig, clearActiveConfigMeta, configKey, configMetaKey, createConfigContext, getActiveConfig, getActiveConfigMeta, setActiveConfig, setActiveConfigMeta };

package/dist/{src-9MkUoh9z.cjs → src-loxvrkxq.cjs}

@@ -31,6 +31,11 @@ const __optique_core_message = __toESM(require("@optique/core/message"));
 */
 const configKey = Symbol.for("@optique/config");
 /**
+* Unique symbol for config metadata in annotations.
+* @since 1.0.0
+*/
+const configMetaKey = Symbol.for("@optique/config/meta");
+/**
 * Internal registry for active config data during runWithConfig execution.
 * This is a workaround for the limitation that object() doesn't propagate
 * annotations to child field parsers.
@@ -38,6 +43,11 @@ const configKey = Symbol.for("@optique/config");
 */
 const activeConfigRegistry = /* @__PURE__ */ new Map();
 /**
+* Internal registry for active config metadata during runWithConfig execution.
+* @internal
+*/
+const activeConfigMetaRegistry = /* @__PURE__ */ new Map();
+/**
 * Sets active config data for a context.
 * @internal
 */
@@ -59,12 +69,34 @@ function clearActiveConfig(contextId) {
 	activeConfigRegistry.delete(contextId);
 }
 /**
+* Sets active config metadata for a context.
+* @internal
+*/
+function setActiveConfigMeta(contextId, meta) {
+	activeConfigMetaRegistry.set(contextId, meta);
+}
+/**
+* Gets active config metadata for a context.
+* @internal
+*/
+function getActiveConfigMeta(contextId) {
+	return activeConfigMetaRegistry.get(contextId);
+}
+/**
+* Clears active config metadata for a context.
+* @internal
+*/
+function clearActiveConfigMeta(contextId) {
+	activeConfigMetaRegistry.delete(contextId);
+}
+/**
 * Creates a config context for use with Optique parsers.
 *
 * The config context implements the SourceContext interface and can be used
 * with runWith() or runWithConfig() to provide configuration file support.
 *
 * @template T The output type of the config schema.
+* @template TConfigMeta The metadata type for config sources.
 * @param options Configuration options including schema and optional parser.
 * @returns A config context that can be used with bindConfig() and runWithConfig().
 * @since 0.10.0
@@ -231,13 +263,15 @@ function bindConfig(parser, options) {
 function getConfigOrDefault(state, options) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
 	let configData = annotations?.[configKey];
+	let configMeta = annotations?.[configMetaKey];
 	if (configData === void 0 || configData === null) {
 		const contextId = options.context.id;
 		configData = getActiveConfig(contextId);
+		configMeta = getActiveConfigMeta(contextId);
 	}
 	let configValue;
 	if (configData !== void 0 && configData !== null) if (typeof options.key === "function") try {
-		configValue = options.key(configData);
+		configValue = options.key(configData, configMeta);
 	} catch {
 		configValue = void 0;
 	}
@@ -275,12 +309,24 @@ Object.defineProperty(exports, 'clearActiveConfig', {
     return clearActiveConfig;
   }
 });
+Object.defineProperty(exports, 'clearActiveConfigMeta', {
+  enumerable: true,
+  get: function () {
+    return clearActiveConfigMeta;
+  }
+});
 Object.defineProperty(exports, 'configKey', {
   enumerable: true,
   get: function () {
     return configKey;
   }
 });
+Object.defineProperty(exports, 'configMetaKey', {
+  enumerable: true,
+  get: function () {
+    return configMetaKey;
+  }
+});
 Object.defineProperty(exports, 'createConfigContext', {
   enumerable: true,
   get: function () {
@@ -293,9 +339,21 @@ Object.defineProperty(exports, 'getActiveConfig', {
     return getActiveConfig;
   }
 });
+Object.defineProperty(exports, 'getActiveConfigMeta', {
+  enumerable: true,
+  get: function () {
+    return getActiveConfigMeta;
+  }
+});
 Object.defineProperty(exports, 'setActiveConfig', {
   enumerable: true,
   get: function () {
     return setActiveConfig;
   }
+});
+Object.defineProperty(exports, 'setActiveConfigMeta', {
+  enumerable: true,
+  get: function () {
+    return setActiveConfigMeta;
+  }
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "1.0.0-dev.428+d513f36f",
+  "version": "1.0.0-dev.429+66edc8ed",
   "description": "Configuration file support for Optique with Standard Schema validation",
   "keywords": [
     "CLI",
@@ -67,7 +67,7 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.428+d513f36f"
+    "@optique/core": "1.0.0-dev.429+66edc8ed"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",