@theunwalked/cardigantime 0.0.7 → 0.0.9

package/dist/cardigantime.js.map

@@ -1 +1 @@
-{"version":3,"file":"cardigantime.js","sources":["../src/cardigantime.ts"],"sourcesContent":["import { Command } from 'commander';\nimport { Args, DefaultOptions, Feature, Cardigantime, Logger, Options } from 'types';\nimport { z, ZodObject } from 'zod';\nimport { configure } from './configure';\nimport { DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS } from './constants';\nimport { read } from './read';\nimport { ConfigSchema } from 'types';\nimport { validate } from './validate';\n\nexport * from './types';\nexport { ArgumentError, ConfigurationError, FileSystemError } from './validate';\n\n/**\n * Creates a new Cardigantime instance for configuration management.\n * \n * Cardigantime handles the complete configuration lifecycle including:\n * - Reading configuration from YAML files\n * - Validating configuration against Zod schemas\n * - Merging CLI arguments with file configuration and defaults\n * - Providing type-safe configuration objects\n * \n * @template T - The Zod schema shape type for your configuration\n * @param pOptions - Configuration options for the Cardigantime instance\n * @param pOptions.defaults - Default configuration settings\n * @param pOptions.defaults.configDirectory - Directory to search for configuration files (required)\n * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')\n * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)\n * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')\n * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])\n * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)\n * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)\n * @returns A Cardigantime instance with methods for configure, read, validate, and setLogger\n * \n * @example\n * ```typescript\n * import { create } from '@theunwalked/cardigantime';\n * import { z } from 'zod';\n * \n * const MyConfigSchema = z.object({\n *   apiKey: z.string().min(1),\n *   timeout: z.number().default(5000),\n *   debug: z.boolean().default(false),\n * });\n * \n * const cardigantime = create({\n *   defaults: {\n *     configDirectory: './config',\n *     configFile: 'myapp.yaml',\n *   },\n *   configShape: MyConfigSchema.shape,\n * });\n * ```\n */\nexport const create = <T extends z.ZodRawShape>(pOptions: {\n    defaults: Pick<DefaultOptions, 'configDirectory'> & Partial<Omit<DefaultOptions, 'configDirectory'>>,\n    features?: Feature[],\n    configShape: T, // Make configShape mandatory\n    logger?: Logger,\n}): Cardigantime<T> => {\n\n\n    const defaults: DefaultOptions = { ...DEFAULT_OPTIONS, ...pOptions.defaults } as DefaultOptions;\n    const features = pOptions.features || DEFAULT_FEATURES;\n    const configShape = pOptions.configShape;\n    let logger = pOptions.logger || DEFAULT_LOGGER;\n\n    const options: Options<T> = {\n        defaults,\n        features,\n        configShape, // Store the shape\n        logger,\n    }\n\n    const setLogger = (pLogger: Logger) => {\n        logger = pLogger;\n        options.logger = pLogger;\n    }\n\n    return {\n        setLogger,\n        configure: (command: Command) => configure(command, options),\n        validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => validate(config, options),\n        read: (args: Args) => read(args, options),\n    }\n}\n\n\n\n\n\n"],"names":["create","pOptions","defaults","DEFAULT_OPTIONS","features","DEFAULT_FEATURES","configShape","logger","DEFAULT_LOGGER","options","setLogger","pLogger","configure","command","validate","config","read","args"],"mappings":";;;;;;;;;AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyCO,MAAMA,MAAAA,GAAS,CAA0BC,QAAAA,GAAAA;AAQ5C,IAAA,MAAMC,QAAAA,GAA2B;AAAE,QAAA,GAAGC,eAAe;AAAE,QAAA,GAAGF,SAASC;AAAS,KAAA;IAC5E,MAAME,QAAAA,GAAWH,QAAAA,CAASG,QAAQ,IAAIC,gBAAAA;IACtC,MAAMC,WAAAA,GAAcL,SAASK,WAAW;IACxC,IAAIC,MAAAA,GAASN,QAAAA,CAASM,MAAM,IAAIC,cAAAA;AAEhC,IAAA,MAAMC,OAAAA,GAAsB;AACxBP,QAAAA,QAAAA;AACAE,QAAAA,QAAAA;AACAE,QAAAA,WAAAA;AACAC,QAAAA;AACJ,KAAA;AAEA,IAAA,MAAMG,YAAY,CAACC,OAAAA,GAAAA;QACfJ,MAAAA,GAASI,OAAAA;AACTF,QAAAA,OAAAA,CAAQF,MAAM,GAAGI,OAAAA;AACrB,KAAA;IAEA,OAAO;AACHD,QAAAA,SAAAA;QACAE,SAAAA,EAAW,CAACC,OAAAA,GAAqBD,SAAAA,CAAUC,OAAAA,EAASJ,OAAAA,CAAAA;QACpDK,QAAAA,EAAU,CAACC,MAAAA,GAA8DD,QAAAA,CAASC,MAAAA,EAAQN,OAAAA,CAAAA;QAC1FO,IAAAA,EAAM,CAACC,IAAAA,GAAeD,IAAAA,CAAKC,IAAAA,EAAMR,OAAAA;AACrC,KAAA;AACJ;;;;"}
+{"version":3,"file":"cardigantime.js","sources":["../src/cardigantime.ts"],"sourcesContent":["import { Command } from 'commander';\nimport { Args, DefaultOptions, Feature, Cardigantime, Logger, Options } from 'types';\nimport { z, ZodObject } from 'zod';\nimport { configure } from './configure';\nimport { DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS } from './constants';\nimport { read } from './read';\nimport { ConfigSchema } from 'types';\nimport { validate } from './validate';\n\nexport * from './types';\nexport { ArgumentError, ConfigurationError, FileSystemError } from './validate';\n\n/**\n * Creates a new Cardigantime instance for configuration management.\n * \n * Cardigantime handles the complete configuration lifecycle including:\n * - Reading configuration from YAML files\n * - Validating configuration against Zod schemas\n * - Merging CLI arguments with file configuration and defaults\n * - Providing type-safe configuration objects\n * \n * @template T - The Zod schema shape type for your configuration\n * @param pOptions - Configuration options for the Cardigantime instance\n * @param pOptions.defaults - Default configuration settings\n * @param pOptions.defaults.configDirectory - Directory to search for configuration files (required)\n * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')\n * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)\n * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')\n * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)\n * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])\n * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)\n * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)\n * @returns A Cardigantime instance with methods for configure, read, validate, and setLogger\n * \n * @example\n * ```typescript\n * import { create } from '@theunwalked/cardigantime';\n * import { z } from 'zod';\n * \n * const MyConfigSchema = z.object({\n *   apiKey: z.string().min(1),\n *   timeout: z.number().default(5000),\n *   debug: z.boolean().default(false),\n *   contextDirectories: z.array(z.string()).optional(),\n * });\n * \n * const cardigantime = create({\n *   defaults: {\n *     configDirectory: './config',\n *     configFile: 'myapp.yaml',\n *     // Resolve relative paths in contextDirectories relative to config file location\n *     pathResolution: {\n *       pathFields: ['contextDirectories'],\n *       resolvePathArray: ['contextDirectories']\n *     },\n *     // Configure how array fields are merged in hierarchical mode\n *     fieldOverlaps: {\n *       'features': 'append',              // Accumulate features from all levels\n *       'excludePatterns': 'prepend'       // Higher precedence patterns come first\n *     }\n *   },\n *   configShape: MyConfigSchema.shape,\n *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery\n * });\n * \n * // If config file is at ../config/myapp.yaml and contains:\n * // contextDirectories: ['./context', './data']\n * // These paths will be resolved relative to ../config/ directory\n * ```\n */\nexport const create = <T extends z.ZodRawShape>(pOptions: {\n    defaults: Pick<DefaultOptions, 'configDirectory'> & Partial<Omit<DefaultOptions, 'configDirectory'>>,\n    features?: Feature[],\n    configShape: T, // Make configShape mandatory\n    logger?: Logger,\n}): Cardigantime<T> => {\n\n\n    const defaults: DefaultOptions = { ...DEFAULT_OPTIONS, ...pOptions.defaults } as DefaultOptions;\n    const features = pOptions.features || DEFAULT_FEATURES;\n    const configShape = pOptions.configShape;\n    let logger = pOptions.logger || DEFAULT_LOGGER;\n\n    const options: Options<T> = {\n        defaults,\n        features,\n        configShape, // Store the shape\n        logger,\n    }\n\n    const setLogger = (pLogger: Logger) => {\n        logger = pLogger;\n        options.logger = pLogger;\n    }\n\n    return {\n        setLogger,\n        configure: (command: Command) => configure(command, options),\n        validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => validate(config, options),\n        read: (args: Args) => read(args, options),\n    }\n}\n\n\n\n\n\n"],"names":["create","pOptions","defaults","DEFAULT_OPTIONS","features","DEFAULT_FEATURES","configShape","logger","DEFAULT_LOGGER","options","setLogger","pLogger","configure","command","validate","config","read","args"],"mappings":";;;;;;;;;AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0DO,MAAMA,MAAAA,GAAS,CAA0BC,QAAAA,GAAAA;AAQ5C,IAAA,MAAMC,QAAAA,GAA2B;AAAE,QAAA,GAAGC,eAAe;AAAE,QAAA,GAAGF,SAASC;AAAS,KAAA;IAC5E,MAAME,QAAAA,GAAWH,QAAAA,CAASG,QAAQ,IAAIC,gBAAAA;IACtC,MAAMC,WAAAA,GAAcL,SAASK,WAAW;IACxC,IAAIC,MAAAA,GAASN,QAAAA,CAASM,MAAM,IAAIC,cAAAA;AAEhC,IAAA,MAAMC,OAAAA,GAAsB;AACxBP,QAAAA,QAAAA;AACAE,QAAAA,QAAAA;AACAE,QAAAA,WAAAA;AACAC,QAAAA;AACJ,KAAA;AAEA,IAAA,MAAMG,YAAY,CAACC,OAAAA,GAAAA;QACfJ,MAAAA,GAASI,OAAAA;AACTF,QAAAA,OAAAA,CAAQF,MAAM,GAAGI,OAAAA;AACrB,KAAA;IAEA,OAAO;AACHD,QAAAA,SAAAA;QACAE,SAAAA,EAAW,CAACC,OAAAA,GAAqBD,SAAAA,CAAUC,OAAAA,EAASJ,OAAAA,CAAAA;QACpDK,QAAAA,EAAU,CAACC,MAAAA,GAA8DD,QAAAA,CAASC,MAAAA,EAAQN,OAAAA,CAAAA;QAC1FO,IAAAA,EAAM,CAACC,IAAAA,GAAeD,IAAAA,CAAKC,IAAAA,EAAMR,OAAAA;AACrC,KAAA;AACJ;;;;"}

package/dist/constants.js

@@ -6,7 +6,8 @@
  */ const DEFAULT_OPTIONS = {
     configFile: DEFAULT_CONFIG_FILE,
     isRequired: false,
-    encoding: DEFAULT_ENCODING
+    encoding: DEFAULT_ENCODING,
+    pathResolution: undefined
 };
 /**
  * Default features enabled when creating a Cardigantime instance.

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["import { DefaultOptions, Feature, Logger } from \"./types\";\n\n/** Version string populated at build time with git and system information */\nexport const VERSION = '__VERSION__ (__GIT_BRANCH__/__GIT_COMMIT__ __GIT_TAGS__ __GIT_COMMIT_DATE__) __SYSTEM_INFO__';\n\n/** The program name used in CLI help and error messages */\nexport const PROGRAM_NAME = 'cardigantime';\n\n/** Default file encoding for reading configuration files */\nexport const DEFAULT_ENCODING = 'utf8';\n\n/** Default configuration file name to look for in the config directory */\nexport const DEFAULT_CONFIG_FILE = 'config.yaml';\n\n/**\n * Default configuration options applied when creating a Cardigantime instance.\n * These provide sensible defaults that work for most use cases.\n */\nexport const DEFAULT_OPTIONS: Partial<DefaultOptions> = {\n    configFile: DEFAULT_CONFIG_FILE,\n    isRequired: false,\n    encoding: DEFAULT_ENCODING,\n}\n\n/**\n * Default features enabled when creating a Cardigantime instance.\n * Currently includes only the 'config' feature for configuration file support.\n */\nexport const DEFAULT_FEATURES: Feature[] = ['config'];\n\n/**\n * Default logger implementation using console methods.\n * Provides basic logging functionality when no custom logger is specified.\n * The verbose and silly methods are no-ops to avoid excessive output.\n */\nexport const DEFAULT_LOGGER: Logger = {\n    // eslint-disable-next-line no-console\n    debug: console.debug,\n    // eslint-disable-next-line no-console\n    info: console.info,\n    // eslint-disable-next-line no-console\n    warn: console.warn,\n    // eslint-disable-next-line no-console\n    error: console.error,\n\n    verbose: () => { },\n\n    silly: () => { },\n}\n"],"names":["DEFAULT_ENCODING","DEFAULT_CONFIG_FILE","DEFAULT_OPTIONS","configFile","isRequired","encoding","DEFAULT_FEATURES","DEFAULT_LOGGER","debug","console","info","warn","error","verbose","silly"],"mappings":"AAQA,6DACO,MAAMA,gBAAAA,GAAmB;AAEhC,2EACO,MAAMC,mBAAAA,GAAsB;AAEnC;;;UAIaC,eAAAA,GAA2C;IACpDC,UAAAA,EAAYF,mBAAAA;IACZG,UAAAA,EAAY,KAAA;IACZC,QAAAA,EAAUL;AACd;AAEA;;;UAIaM,gBAAAA,GAA8B;AAAC,IAAA;;AAE5C;;;;UAKaC,cAAAA,GAAyB;;AAElCC,IAAAA,KAAAA,EAAOC,QAAQD,KAAK;;AAEpBE,IAAAA,IAAAA,EAAMD,QAAQC,IAAI;;AAElBC,IAAAA,IAAAA,EAAMF,QAAQE,IAAI;;AAElBC,IAAAA,KAAAA,EAAOH,QAAQG,KAAK;AAEpBC,IAAAA,OAAAA,EAAS,IAAA,EAAQ;AAEjBC,IAAAA,KAAAA,EAAO,IAAA;AACX;;;;"}
+{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["import { DefaultOptions, Feature, Logger } from \"./types\";\n\n/** Version string populated at build time with git and system information */\nexport const VERSION = '__VERSION__ (__GIT_BRANCH__/__GIT_COMMIT__ __GIT_TAGS__ __GIT_COMMIT_DATE__) __SYSTEM_INFO__';\n\n/** The program name used in CLI help and error messages */\nexport const PROGRAM_NAME = 'cardigantime';\n\n/** Default file encoding for reading configuration files */\nexport const DEFAULT_ENCODING = 'utf8';\n\n/** Default configuration file name to look for in the config directory */\nexport const DEFAULT_CONFIG_FILE = 'config.yaml';\n\n/**\n * Default configuration options applied when creating a Cardigantime instance.\n * These provide sensible defaults that work for most use cases.\n */\nexport const DEFAULT_OPTIONS: Partial<DefaultOptions> = {\n    configFile: DEFAULT_CONFIG_FILE,\n    isRequired: false,\n    encoding: DEFAULT_ENCODING,\n    pathResolution: undefined, // No path resolution by default\n}\n\n/**\n * Default features enabled when creating a Cardigantime instance.\n * Currently includes only the 'config' feature for configuration file support.\n */\nexport const DEFAULT_FEATURES: Feature[] = ['config'];\n\n/**\n * Default logger implementation using console methods.\n * Provides basic logging functionality when no custom logger is specified.\n * The verbose and silly methods are no-ops to avoid excessive output.\n */\nexport const DEFAULT_LOGGER: Logger = {\n    // eslint-disable-next-line no-console\n    debug: console.debug,\n    // eslint-disable-next-line no-console\n    info: console.info,\n    // eslint-disable-next-line no-console\n    warn: console.warn,\n    // eslint-disable-next-line no-console\n    error: console.error,\n\n    verbose: () => { },\n\n    silly: () => { },\n}\n"],"names":["DEFAULT_ENCODING","DEFAULT_CONFIG_FILE","DEFAULT_OPTIONS","configFile","isRequired","encoding","pathResolution","undefined","DEFAULT_FEATURES","DEFAULT_LOGGER","debug","console","info","warn","error","verbose","silly"],"mappings":"AAQA,6DACO,MAAMA,gBAAAA,GAAmB;AAEhC,2EACO,MAAMC,mBAAAA,GAAsB;AAEnC;;;UAIaC,eAAAA,GAA2C;IACpDC,UAAAA,EAAYF,mBAAAA;IACZG,UAAAA,EAAY,KAAA;IACZC,QAAAA,EAAUL,gBAAAA;IACVM,cAAAA,EAAgBC;AACpB;AAEA;;;UAIaC,gBAAAA,GAA8B;AAAC,IAAA;;AAE5C;;;;UAKaC,cAAAA,GAAyB;;AAElCC,IAAAA,KAAAA,EAAOC,QAAQD,KAAK;;AAEpBE,IAAAA,IAAAA,EAAMD,QAAQC,IAAI;;AAElBC,IAAAA,IAAAA,EAAMF,QAAQE,IAAI;;AAElBC,IAAAA,KAAAA,EAAOH,QAAQG,KAAK;AAEpBC,IAAAA,OAAAA,EAAS,IAAA,EAAQ;AAEjBC,IAAAA,KAAAA,EAAO,IAAA;AACX;;;;"}

package/dist/read.js

@@ -12,6 +12,68 @@ import { loadHierarchicalConfig } from './util/hierarchical.js';
  */ function clean(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([_, v])=>v !== undefined));
 }
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ * 
+ * @param config - The configuration object to process
+ * @param configDir - The directory containing the configuration file
+ * @param pathFields - Array of field names (using dot notation) that contain paths to be resolved
+ * @param resolvePathArray - Array of field names whose array elements should all be resolved as paths
+ * @returns The configuration object with resolved paths
+ */ function resolveConfigPaths(config, configDir, pathFields = [], resolvePathArray = []) {
+    if (!config || typeof config !== 'object' || pathFields.length === 0) {
+        return config;
+    }
+    const resolvedConfig = {
+        ...config
+    };
+    for (const fieldPath of pathFields){
+        const value = getNestedValue(resolvedConfig, fieldPath);
+        if (value !== undefined) {
+            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);
+            const resolvedValue = resolvePathValue(value, configDir, shouldResolveArrayElements);
+            setNestedValue(resolvedConfig, fieldPath, resolvedValue);
+        }
+    }
+    return resolvedConfig;
+}
+/**
+ * Gets a nested value from an object using dot notation.
+ */ function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key)=>current === null || current === void 0 ? void 0 : current[key], obj);
+}
+/**
+ * Sets a nested value in an object using dot notation.
+ */ function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    const target = keys.reduce((current, key)=>{
+        if (!(key in current)) {
+            current[key] = {};
+        }
+        return current[key];
+    }, obj);
+    target[lastKey] = value;
+}
+/**
+ * Resolves a path value (string or array of strings) relative to the config directory.
+ */ function resolvePathValue(value, configDir, resolveArrayElements) {
+    if (typeof value === 'string') {
+        return resolveSinglePath(value, configDir);
+    }
+    if (Array.isArray(value) && resolveArrayElements) {
+        return value.map((item)=>typeof item === 'string' ? resolveSinglePath(item, configDir) : item);
+    }
+    return value;
+}
+/**
+ * Resolves a single path string relative to the config directory if it's a relative path.
+ */ function resolveSinglePath(pathStr, configDir) {
+    if (!pathStr || path.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path.resolve(configDir, pathStr);
+}
 /**
  * Validates and secures a user-provided path to prevent path traversal attacks.
  * 
@@ -95,7 +157,7 @@ import { loadHierarchicalConfig } from './util/hierarchical.js';
  * // config is fully typed based on your schema
  * ```
  */ const read = async (args, options)=>{
-    var _options_defaults;
+    var _options_defaults, _options_defaults_pathResolution;
     const logger = options.logger;
     const rawConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
     if (!rawConfigDir) {
@@ -108,6 +170,7 @@ import { loadHierarchicalConfig } from './util/hierarchical.js';
     if (options.features.includes('hierarchical')) {
         logger.verbose('Hierarchical configuration discovery enabled');
         try {
+            var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
             // Extract the config directory name from the path for hierarchical discovery
             const configDirName = path.basename(resolvedConfigDir);
             const startingDir = path.dirname(resolvedConfigDir);
@@ -117,7 +180,10 @@ import { loadHierarchicalConfig } from './util/hierarchical.js';
                 configFileName: options.defaults.configFile,
                 startingDir,
                 encoding: options.defaults.encoding,
-                logger
+                logger,
+                pathFields: (_options_defaults_pathResolution1 = options.defaults.pathResolution) === null || _options_defaults_pathResolution1 === void 0 ? void 0 : _options_defaults_pathResolution1.pathFields,
+                resolvePathArray: (_options_defaults_pathResolution2 = options.defaults.pathResolution) === null || _options_defaults_pathResolution2 === void 0 ? void 0 : _options_defaults_pathResolution2.resolvePathArray,
+                fieldOverlaps: options.defaults.fieldOverlaps
             });
             rawFileConfig = hierarchicalResult.config;
             if (hierarchicalResult.discoveredDirs.length > 0) {
@@ -142,8 +208,13 @@ import { loadHierarchicalConfig } from './util/hierarchical.js';
         logger.verbose('Using single directory configuration loading');
         rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
     }
+    // Apply path resolution if configured
+    let processedConfig = rawFileConfig;
+    if ((_options_defaults_pathResolution = options.defaults.pathResolution) === null || _options_defaults_pathResolution === void 0 ? void 0 : _options_defaults_pathResolution.pathFields) {
+        processedConfig = resolveConfigPaths(rawFileConfig, resolvedConfigDir, options.defaults.pathResolution.pathFields, options.defaults.pathResolution.resolvePathArray || []);
+    }
     const config = clean({
-        ...rawFileConfig,
+        ...processedConfig,
         ...{
             configDirectory: resolvedConfigDir
         }

package/dist/read.js.map

@@ -1 +1 @@
-{"version":3,"file":"read.js","sources":["../src/read.ts"],"sourcesContent":["import * as yaml from 'js-yaml';\nimport * as path from 'path';\nimport { z, ZodObject } from 'zod';\nimport { Args, ConfigSchema, Options } from './types';\nimport * as Storage from './util/storage';\nimport { loadHierarchicalConfig } from './util/hierarchical';\n\n/**\n * Removes undefined values from an object to create a clean configuration.\n * This is used to merge configuration sources while avoiding undefined pollution.\n * \n * @param obj - The object to clean\n * @returns A new object with undefined values filtered out\n */\nfunction clean(obj: any) {\n    return Object.fromEntries(\n        Object.entries(obj).filter(([_, v]) => v !== undefined)\n    );\n}\n\n/**\n * Validates and secures a user-provided path to prevent path traversal attacks.\n * \n * Security checks include:\n * - Path traversal prevention (blocks '..')\n * - Absolute path detection\n * - Path separator validation\n * \n * @param userPath - The user-provided path component\n * @param basePath - The base directory to join the path with\n * @returns The safely joined and normalized path\n * @throws {Error} When path traversal or absolute paths are detected\n */\nfunction validatePath(userPath: string, basePath: string): string {\n    if (!userPath || !basePath) {\n        throw new Error('Invalid path parameters');\n    }\n\n    const normalized = path.normalize(userPath);\n\n    // Prevent path traversal attacks\n    if (normalized.includes('..') || path.isAbsolute(normalized)) {\n        throw new Error('Invalid path: path traversal detected');\n    }\n\n    // Ensure the path doesn't start with a path separator\n    if (normalized.startsWith('/') || normalized.startsWith('\\\\')) {\n        throw new Error('Invalid path: absolute path detected');\n    }\n\n    return path.join(basePath, normalized);\n}\n\n/**\n * Validates a configuration directory path for security and basic formatting.\n * \n * Performs validation to prevent:\n * - Null byte injection attacks\n * - Extremely long paths that could cause DoS\n * - Empty or invalid directory specifications\n * \n * @param configDir - The configuration directory path to validate\n * @returns The normalized configuration directory path\n * @throws {Error} When the directory path is invalid or potentially dangerous\n */\nfunction validateConfigDirectory(configDir: string): string {\n    if (!configDir) {\n        throw new Error('Configuration directory is required');\n    }\n\n    // Check for null bytes which could be used for path injection\n    if (configDir.includes('\\0')) {\n        throw new Error('Invalid path: null byte detected');\n    }\n\n    const normalized = path.normalize(configDir);\n\n    // Basic validation - could be expanded based on requirements\n    if (normalized.length > 1000) {\n        throw new Error('Configuration directory path too long');\n    }\n\n    return normalized;\n}\n\n/**\n * Reads configuration from files and merges it with CLI arguments.\n * \n * This function implements the core configuration loading logic:\n * 1. Validates and resolves the configuration directory path\n * 2. Attempts to read the YAML configuration file\n * 3. Safely parses the YAML content with security protections\n * 4. Merges file configuration with runtime arguments\n * 5. Returns a typed configuration object\n * \n * The function handles missing files gracefully and provides detailed\n * logging for troubleshooting configuration issues.\n * \n * @template T - The Zod schema shape type for configuration validation\n * @param args - Parsed command-line arguments containing potential config overrides\n * @param options - Cardigantime options with defaults, schema, and logger\n * @returns Promise resolving to the merged and typed configuration object\n * @throws {Error} When configuration directory is invalid or required files cannot be read\n * \n * @example\n * ```typescript\n * const config = await read(cliArgs, {\n *   defaults: { configDirectory: './config', configFile: 'app.yaml' },\n *   configShape: MySchema.shape,\n *   logger: console,\n *   features: ['config']\n * });\n * // config is fully typed based on your schema\n * ```\n */\nexport const read = async <T extends z.ZodRawShape>(args: Args, options: Options<T>): Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>> => {\n    const logger = options.logger;\n\n    const rawConfigDir = args.configDirectory || options.defaults?.configDirectory;\n    if (!rawConfigDir) {\n        throw new Error('Configuration directory must be specified');\n    }\n\n    const resolvedConfigDir = validateConfigDirectory(rawConfigDir);\n    logger.verbose('Resolved config directory');\n\n    let rawFileConfig: object = {};\n\n    // Check if hierarchical configuration discovery is enabled\n    if (options.features.includes('hierarchical')) {\n        logger.verbose('Hierarchical configuration discovery enabled');\n\n        try {\n            // Extract the config directory name from the path for hierarchical discovery\n            const configDirName = path.basename(resolvedConfigDir);\n            const startingDir = path.dirname(resolvedConfigDir);\n\n            logger.debug(`Using hierarchical discovery: configDirName=${configDirName}, startingDir=${startingDir}`);\n\n            const hierarchicalResult = await loadHierarchicalConfig({\n                configDirName,\n                configFileName: options.defaults.configFile,\n                startingDir,\n                encoding: options.defaults.encoding,\n                logger\n            });\n\n            rawFileConfig = hierarchicalResult.config;\n\n            if (hierarchicalResult.discoveredDirs.length > 0) {\n                logger.verbose(`Hierarchical discovery found ${hierarchicalResult.discoveredDirs.length} configuration directories`);\n                hierarchicalResult.discoveredDirs.forEach(dir => {\n                    logger.debug(`  Level ${dir.level}: ${dir.path}`);\n                });\n            } else {\n                logger.verbose('No configuration directories found in hierarchy');\n            }\n\n            if (hierarchicalResult.errors.length > 0) {\n                hierarchicalResult.errors.forEach(error => logger.warn(`Hierarchical config warning: ${error}`));\n            }\n\n        } catch (error: any) {\n            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));\n            // Fall back to single directory mode\n            logger.verbose('Falling back to single directory configuration loading');\n            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);\n        }\n    } else {\n        // Use traditional single directory configuration loading\n        logger.verbose('Using single directory configuration loading');\n        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);\n    }\n\n    const config: z.infer<ZodObject<T & typeof ConfigSchema.shape>> = clean({\n        ...rawFileConfig,\n        ...{\n            configDirectory: resolvedConfigDir,\n        }\n    }) as z.infer<ZodObject<T & typeof ConfigSchema.shape>>;\n\n    return config;\n}\n\n/**\n * Loads configuration from a single directory (traditional mode).\n * \n * @param resolvedConfigDir - The resolved configuration directory path\n * @param options - Cardigantime options\n * @param logger - Logger instance\n * @returns Promise resolving to the configuration object\n */\nasync function loadSingleDirectoryConfig<T extends z.ZodRawShape>(\n    resolvedConfigDir: string,\n    options: Options<T>,\n    logger: any\n): Promise<object> {\n    const storage = Storage.create({ log: logger.debug });\n    const configFile = validatePath(options.defaults.configFile, resolvedConfigDir);\n    logger.verbose('Attempting to load config file for cardigantime');\n\n    let rawFileConfig: object = {};\n\n    try {\n        const yamlContent = await storage.readFile(configFile, options.defaults.encoding);\n\n        // SECURITY FIX: Use safer parsing options to prevent code execution vulnerabilities\n        const parsedYaml = yaml.load(yamlContent);\n\n        if (parsedYaml !== null && typeof parsedYaml === 'object') {\n            rawFileConfig = parsedYaml;\n            logger.verbose('Loaded configuration file successfully');\n        } else if (parsedYaml !== null) {\n            logger.warn('Ignoring invalid configuration format. Expected an object, got ' + typeof parsedYaml);\n        }\n    } catch (error: any) {\n        if (error.code === 'ENOENT' || /not found|no such file/i.test(error.message)) {\n            logger.verbose('Configuration file not found. Using empty configuration.');\n        } else {\n            // SECURITY FIX: Don't expose internal paths or detailed error information\n            logger.error('Failed to load or parse configuration file: ' + (error.message || 'Unknown error'));\n        }\n    }\n\n    return rawFileConfig;\n}"],"names":["clean","obj","Object","fromEntries","entries","filter","_","v","undefined","validatePath","userPath","basePath","Error","normalized","path","normalize","includes","isAbsolute","startsWith","join","validateConfigDirectory","configDir","length","read","args","options","logger","rawConfigDir","configDirectory","defaults","resolvedConfigDir","verbose","rawFileConfig","features","configDirName","basename","startingDir","dirname","debug","hierarchicalResult","loadHierarchicalConfig","configFileName","configFile","encoding","config","discoveredDirs","forEach","dir","level","errors","error","warn","message","loadSingleDirectoryConfig","storage","Storage","log","yamlContent","readFile","parsedYaml","yaml","load","code","test"],"mappings":"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"}
+{"version":3,"file":"read.js","sources":["../src/read.ts"],"sourcesContent":["import * as yaml from 'js-yaml';\nimport * as path from 'path';\nimport { z, ZodObject } from 'zod';\nimport { Args, ConfigSchema, Options } from './types';\nimport * as Storage from './util/storage';\nimport { loadHierarchicalConfig } from './util/hierarchical';\n\n/**\n * Removes undefined values from an object to create a clean configuration.\n * This is used to merge configuration sources while avoiding undefined pollution.\n * \n * @param obj - The object to clean\n * @returns A new object with undefined values filtered out\n */\nfunction clean(obj: any) {\n    return Object.fromEntries(\n        Object.entries(obj).filter(([_, v]) => v !== undefined)\n    );\n}\n\n/**\n * Resolves relative paths in configuration values relative to the configuration file's directory.\n * \n * @param config - The configuration object to process\n * @param configDir - The directory containing the configuration file\n * @param pathFields - Array of field names (using dot notation) that contain paths to be resolved\n * @param resolvePathArray - Array of field names whose array elements should all be resolved as paths\n * @returns The configuration object with resolved paths\n */\nfunction resolveConfigPaths(\n    config: any,\n    configDir: string,\n    pathFields: string[] = [],\n    resolvePathArray: string[] = []\n): any {\n    if (!config || typeof config !== 'object' || pathFields.length === 0) {\n        return config;\n    }\n\n    const resolvedConfig = { ...config };\n\n    for (const fieldPath of pathFields) {\n        const value = getNestedValue(resolvedConfig, fieldPath);\n        if (value !== undefined) {\n            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);\n            const resolvedValue = resolvePathValue(value, configDir, shouldResolveArrayElements);\n            setNestedValue(resolvedConfig, fieldPath, resolvedValue);\n        }\n    }\n\n    return resolvedConfig;\n}\n\n/**\n * Gets a nested value from an object using dot notation.\n */\nfunction getNestedValue(obj: any, path: string): any {\n    return path.split('.').reduce((current, key) => current?.[key], obj);\n}\n\n/**\n * Sets a nested value in an object using dot notation.\n */\nfunction setNestedValue(obj: any, path: string, value: any): void {\n    const keys = path.split('.');\n    const lastKey = keys.pop()!;\n    const target = keys.reduce((current, key) => {\n        if (!(key in current)) {\n            current[key] = {};\n        }\n        return current[key];\n    }, obj);\n    target[lastKey] = value;\n}\n\n/**\n * Resolves a path value (string or array of strings) relative to the config directory.\n */\nfunction resolvePathValue(value: any, configDir: string, resolveArrayElements: boolean): any {\n    if (typeof value === 'string') {\n        return resolveSinglePath(value, configDir);\n    }\n\n    if (Array.isArray(value) && resolveArrayElements) {\n        return value.map(item =>\n            typeof item === 'string' ? resolveSinglePath(item, configDir) : item\n        );\n    }\n\n    return value;\n}\n\n/**\n * Resolves a single path string relative to the config directory if it's a relative path.\n */\nfunction resolveSinglePath(pathStr: string, configDir: string): string {\n    if (!pathStr || path.isAbsolute(pathStr)) {\n        return pathStr;\n    }\n\n    return path.resolve(configDir, pathStr);\n}\n\n/**\n * Validates and secures a user-provided path to prevent path traversal attacks.\n * \n * Security checks include:\n * - Path traversal prevention (blocks '..')\n * - Absolute path detection\n * - Path separator validation\n * \n * @param userPath - The user-provided path component\n * @param basePath - The base directory to join the path with\n * @returns The safely joined and normalized path\n * @throws {Error} When path traversal or absolute paths are detected\n */\nfunction validatePath(userPath: string, basePath: string): string {\n    if (!userPath || !basePath) {\n        throw new Error('Invalid path parameters');\n    }\n\n    const normalized = path.normalize(userPath);\n\n    // Prevent path traversal attacks\n    if (normalized.includes('..') || path.isAbsolute(normalized)) {\n        throw new Error('Invalid path: path traversal detected');\n    }\n\n    // Ensure the path doesn't start with a path separator\n    if (normalized.startsWith('/') || normalized.startsWith('\\\\')) {\n        throw new Error('Invalid path: absolute path detected');\n    }\n\n    return path.join(basePath, normalized);\n}\n\n/**\n * Validates a configuration directory path for security and basic formatting.\n * \n * Performs validation to prevent:\n * - Null byte injection attacks\n * - Extremely long paths that could cause DoS\n * - Empty or invalid directory specifications\n * \n * @param configDir - The configuration directory path to validate\n * @returns The normalized configuration directory path\n * @throws {Error} When the directory path is invalid or potentially dangerous\n */\nfunction validateConfigDirectory(configDir: string): string {\n    if (!configDir) {\n        throw new Error('Configuration directory is required');\n    }\n\n    // Check for null bytes which could be used for path injection\n    if (configDir.includes('\\0')) {\n        throw new Error('Invalid path: null byte detected');\n    }\n\n    const normalized = path.normalize(configDir);\n\n    // Basic validation - could be expanded based on requirements\n    if (normalized.length > 1000) {\n        throw new Error('Configuration directory path too long');\n    }\n\n    return normalized;\n}\n\n/**\n * Reads configuration from files and merges it with CLI arguments.\n * \n * This function implements the core configuration loading logic:\n * 1. Validates and resolves the configuration directory path\n * 2. Attempts to read the YAML configuration file\n * 3. Safely parses the YAML content with security protections\n * 4. Merges file configuration with runtime arguments\n * 5. Returns a typed configuration object\n * \n * The function handles missing files gracefully and provides detailed\n * logging for troubleshooting configuration issues.\n * \n * @template T - The Zod schema shape type for configuration validation\n * @param args - Parsed command-line arguments containing potential config overrides\n * @param options - Cardigantime options with defaults, schema, and logger\n * @returns Promise resolving to the merged and typed configuration object\n * @throws {Error} When configuration directory is invalid or required files cannot be read\n * \n * @example\n * ```typescript\n * const config = await read(cliArgs, {\n *   defaults: { configDirectory: './config', configFile: 'app.yaml' },\n *   configShape: MySchema.shape,\n *   logger: console,\n *   features: ['config']\n * });\n * // config is fully typed based on your schema\n * ```\n */\nexport const read = async <T extends z.ZodRawShape>(args: Args, options: Options<T>): Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>> => {\n    const logger = options.logger;\n\n    const rawConfigDir = args.configDirectory || options.defaults?.configDirectory;\n    if (!rawConfigDir) {\n        throw new Error('Configuration directory must be specified');\n    }\n\n    const resolvedConfigDir = validateConfigDirectory(rawConfigDir);\n    logger.verbose('Resolved config directory');\n\n    let rawFileConfig: object = {};\n\n    // Check if hierarchical configuration discovery is enabled\n    if (options.features.includes('hierarchical')) {\n        logger.verbose('Hierarchical configuration discovery enabled');\n\n        try {\n            // Extract the config directory name from the path for hierarchical discovery\n            const configDirName = path.basename(resolvedConfigDir);\n            const startingDir = path.dirname(resolvedConfigDir);\n\n            logger.debug(`Using hierarchical discovery: configDirName=${configDirName}, startingDir=${startingDir}`);\n\n            const hierarchicalResult = await loadHierarchicalConfig({\n                configDirName,\n                configFileName: options.defaults.configFile,\n                startingDir,\n                encoding: options.defaults.encoding,\n                logger,\n                pathFields: options.defaults.pathResolution?.pathFields,\n                resolvePathArray: options.defaults.pathResolution?.resolvePathArray,\n                fieldOverlaps: options.defaults.fieldOverlaps\n            });\n\n            rawFileConfig = hierarchicalResult.config;\n\n            if (hierarchicalResult.discoveredDirs.length > 0) {\n                logger.verbose(`Hierarchical discovery found ${hierarchicalResult.discoveredDirs.length} configuration directories`);\n                hierarchicalResult.discoveredDirs.forEach(dir => {\n                    logger.debug(`  Level ${dir.level}: ${dir.path}`);\n                });\n            } else {\n                logger.verbose('No configuration directories found in hierarchy');\n            }\n\n            if (hierarchicalResult.errors.length > 0) {\n                hierarchicalResult.errors.forEach(error => logger.warn(`Hierarchical config warning: ${error}`));\n            }\n\n        } catch (error: any) {\n            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));\n            // Fall back to single directory mode\n            logger.verbose('Falling back to single directory configuration loading');\n            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);\n        }\n    } else {\n        // Use traditional single directory configuration loading\n        logger.verbose('Using single directory configuration loading');\n        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);\n    }\n\n    // Apply path resolution if configured\n    let processedConfig = rawFileConfig;\n    if (options.defaults.pathResolution?.pathFields) {\n        processedConfig = resolveConfigPaths(\n            rawFileConfig,\n            resolvedConfigDir,\n            options.defaults.pathResolution.pathFields,\n            options.defaults.pathResolution.resolvePathArray || []\n        );\n    }\n\n    const config: z.infer<ZodObject<T & typeof ConfigSchema.shape>> = clean({\n        ...processedConfig,\n        ...{\n            configDirectory: resolvedConfigDir,\n        }\n    }) as z.infer<ZodObject<T & typeof ConfigSchema.shape>>;\n\n    return config;\n}\n\n/**\n * Loads configuration from a single directory (traditional mode).\n * \n * @param resolvedConfigDir - The resolved configuration directory path\n * @param options - Cardigantime options\n * @param logger - Logger instance\n * @returns Promise resolving to the configuration object\n */\nasync function loadSingleDirectoryConfig<T extends z.ZodRawShape>(\n    resolvedConfigDir: string,\n    options: Options<T>,\n    logger: any\n): Promise<object> {\n    const storage = Storage.create({ log: logger.debug });\n    const configFile = validatePath(options.defaults.configFile, resolvedConfigDir);\n    logger.verbose('Attempting to load config file for cardigantime');\n\n    let rawFileConfig: object = {};\n\n    try {\n        const yamlContent = await storage.readFile(configFile, options.defaults.encoding);\n\n        // SECURITY FIX: Use safer parsing options to prevent code execution vulnerabilities\n        const parsedYaml = yaml.load(yamlContent);\n\n        if (parsedYaml !== null && typeof parsedYaml === 'object') {\n            rawFileConfig = parsedYaml;\n            logger.verbose('Loaded configuration file successfully');\n        } else if (parsedYaml !== null) {\n            logger.warn('Ignoring invalid configuration format. Expected an object, got ' + typeof parsedYaml);\n        }\n    } catch (error: any) {\n        if (error.code === 'ENOENT' || /not found|no such file/i.test(error.message)) {\n            logger.verbose('Configuration file not found. Using empty configuration.');\n        } else {\n            // SECURITY FIX: Don't expose internal paths or detailed error information\n            logger.error('Failed to load or parse configuration file: ' + (error.message || 'Unknown error'));\n        }\n    }\n\n    return rawFileConfig;\n}"],"names":["clean","obj","Object","fromEntries","entries","filter","_","v","undefined","resolveConfigPaths","config","configDir","pathFields","resolvePathArray","length","resolvedConfig","fieldPath","value","getNestedValue","shouldResolveArrayElements","includes","resolvedValue","resolvePathValue","setNestedValue","path","split","reduce","current","key","keys","lastKey","pop","target","resolveArrayElements","resolveSinglePath","Array","isArray","map","item","pathStr","isAbsolute","resolve","validatePath","userPath","basePath","Error","normalized","normalize","startsWith","join","validateConfigDirectory","read","args","options","logger","rawConfigDir","configDirectory","defaults","resolvedConfigDir","verbose","rawFileConfig","features","configDirName","basename","startingDir","dirname","debug","hierarchicalResult","loadHierarchicalConfig","configFileName","configFile","encoding","pathResolution","fieldOverlaps","discoveredDirs","forEach","dir","level","errors","error","warn","message","loadSingleDirectoryConfig","processedConfig","storage","Storage","log","yamlContent","readFile","parsedYaml","yaml","load","code","test"],"mappings":"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"}

package/dist/types.d.ts

@@ -7,6 +7,40 @@ import { ZodObject, z } from 'zod';
  * - 'hierarchical': Hierarchical configuration discovery and layering
  */
 export type Feature = 'config' | 'hierarchical';
+/**
+ * Defines how array fields should be merged in hierarchical configurations.
+ *
+ * - 'override': Higher precedence arrays completely replace lower precedence arrays (default)
+ * - 'append': Higher precedence array elements are appended to lower precedence arrays
+ * - 'prepend': Higher precedence array elements are prepended to lower precedence arrays
+ */
+export type ArrayOverlapMode = 'override' | 'append' | 'prepend';
+/**
+ * Configuration for how fields should be merged in hierarchical configurations.
+ * Maps field names (using dot notation) to their overlap behavior.
+ *
+ * @example
+ * ```typescript
+ * const fieldOverlaps: FieldOverlapOptions = {
+ *   'features': 'append',           // features arrays will be combined by appending
+ *   'api.endpoints': 'prepend',     // nested endpoint arrays will be combined by prepending
+ *   'excludePatterns': 'override'   // excludePatterns arrays will replace each other (default behavior)
+ * };
+ * ```
+ */
+export interface FieldOverlapOptions {
+    [fieldPath: string]: ArrayOverlapMode;
+}
+/**
+ * Configuration for resolving relative paths in configuration values.
+ * Paths specified in these fields will be resolved relative to the configuration file's directory.
+ */
+export interface PathResolutionOptions {
+    /** Array of field names (using dot notation) that contain paths to be resolved */
+    pathFields?: string[];
+    /** Array of field names whose array elements should all be resolved as paths */
+    resolvePathArray?: string[];
+}
 /**
  * Default configuration options for Cardigantime.
  * These define the basic behavior of configuration loading.
@@ -20,6 +54,14 @@ export interface DefaultOptions {
     isRequired: boolean;
     /** File encoding for reading configuration files (e.g., 'utf8', 'ascii') */
     encoding: string;
+    /** Configuration for resolving relative paths in configuration values */
+    pathResolution?: PathResolutionOptions;
+    /**
+     * Configuration for how array fields should be merged in hierarchical mode.
+     * Only applies when the 'hierarchical' feature is enabled.
+     * If not specified, all arrays use 'override' behavior (default).
+     */
+    fieldOverlaps?: FieldOverlapOptions;
 }
 /**
  * Complete options object passed to Cardigantime functions.

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../src/types.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { ZodObject } from \"zod\";\n\nimport { z } from \"zod\";\n\n/**\n * Available features that can be enabled in Cardigantime.\n * Currently supports:\n * - 'config': Configuration file reading and validation\n * - 'hierarchical': Hierarchical configuration discovery and layering\n */\nexport type Feature = 'config' | 'hierarchical';\n\n/**\n * Default configuration options for Cardigantime.\n * These define the basic behavior of configuration loading.\n */\nexport interface DefaultOptions {\n    /** Directory path where configuration files are located */\n    configDirectory: string;\n    /** Name of the configuration file (e.g., 'config.yaml', 'app.yml') */\n    configFile: string;\n    /** Whether the configuration directory must exist. If true, throws error if directory doesn't exist */\n    isRequired: boolean;\n    /** File encoding for reading configuration files (e.g., 'utf8', 'ascii') */\n    encoding: string;\n}\n\n/**\n * Complete options object passed to Cardigantime functions.\n * Combines defaults, features, schema shape, and logger.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Options<T extends z.ZodRawShape> {\n    /** Default configuration options */\n    defaults: DefaultOptions,\n    /** Array of enabled features */\n    features: Feature[],\n    /** Zod schema shape for validating user configuration */\n    configShape: T;\n    /** Logger instance for debugging and error reporting */\n    logger: Logger;\n}\n\n/**\n * Logger interface for Cardigantime's internal logging.\n * Compatible with popular logging libraries like Winston, Bunyan, etc.\n */\nexport interface Logger {\n    /** Debug-level logging for detailed troubleshooting information */\n    debug: (message: string, ...args: any[]) => void;\n    /** Info-level logging for general information */\n    info: (message: string, ...args: any[]) => void;\n    /** Warning-level logging for non-critical issues */\n    warn: (message: string, ...args: any[]) => void;\n    /** Error-level logging for critical problems */\n    error: (message: string, ...args: any[]) => void;\n    /** Verbose-level logging for extensive detail */\n    verbose: (message: string, ...args: any[]) => void;\n    /** Silly-level logging for maximum detail */\n    silly: (message: string, ...args: any[]) => void;\n}\n\n/**\n * Main Cardigantime interface providing configuration management functionality.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Cardigantime<T extends z.ZodRawShape> {\n    /** \n     * Adds Cardigantime's CLI options to a Commander.js command.\n     * This includes options like --config-directory for runtime config path overrides.\n     */\n    configure: (command: Command) => Promise<Command>;\n    /** Sets a custom logger for debugging and error reporting */\n    setLogger: (logger: Logger) => void;\n    /** \n     * Reads configuration from files and merges with CLI arguments.\n     * Returns a fully typed configuration object.\n     */\n    read: (args: Args) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;\n    /** \n     * Validates the merged configuration against the Zod schema.\n     * Throws ConfigurationError if validation fails.\n     */\n    validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => Promise<void>;\n}\n\n/**\n * Parsed command-line arguments object, typically from Commander.js opts().\n * Keys correspond to CLI option names with values from user input.\n */\nexport interface Args {\n    [key: string]: any;\n}\n\n/**\n * Base Zod schema for core Cardigantime configuration.\n * Contains the minimum required configuration fields.\n */\nexport const ConfigSchema = z.object({\n    /** The resolved configuration directory path */\n    configDirectory: z.string(),\n});\n\n/**\n * Base configuration type derived from the core schema.\n */\nexport type Config = z.infer<typeof ConfigSchema>;\n"],"names":["ConfigSchema","z","object","configDirectory","string"],"mappings":";;AAiGA;;;AAGC,IACM,MAAMA,YAAAA,GAAeC,CAAAA,CAAEC,MAAM,CAAC;qDAEjCC,eAAAA,EAAiBF,CAAAA,CAAEG,MAAM;AAC7B,CAAA;;;;"}
+{"version":3,"file":"types.js","sources":["../src/types.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { ZodObject } from \"zod\";\n\nimport { z } from \"zod\";\n\n/**\n * Available features that can be enabled in Cardigantime.\n * Currently supports:\n * - 'config': Configuration file reading and validation\n * - 'hierarchical': Hierarchical configuration discovery and layering\n */\nexport type Feature = 'config' | 'hierarchical';\n\n/**\n * Defines how array fields should be merged in hierarchical configurations.\n * \n * - 'override': Higher precedence arrays completely replace lower precedence arrays (default)\n * - 'append': Higher precedence array elements are appended to lower precedence arrays\n * - 'prepend': Higher precedence array elements are prepended to lower precedence arrays\n */\nexport type ArrayOverlapMode = 'override' | 'append' | 'prepend';\n\n/**\n * Configuration for how fields should be merged in hierarchical configurations.\n * Maps field names (using dot notation) to their overlap behavior.\n * \n * @example\n * ```typescript\n * const fieldOverlaps: FieldOverlapOptions = {\n *   'features': 'append',           // features arrays will be combined by appending\n *   'api.endpoints': 'prepend',     // nested endpoint arrays will be combined by prepending\n *   'excludePatterns': 'override'   // excludePatterns arrays will replace each other (default behavior)\n * };\n * ```\n */\nexport interface FieldOverlapOptions {\n    [fieldPath: string]: ArrayOverlapMode;\n}\n\n/**\n * Configuration for resolving relative paths in configuration values.\n * Paths specified in these fields will be resolved relative to the configuration file's directory.\n */\nexport interface PathResolutionOptions {\n    /** Array of field names (using dot notation) that contain paths to be resolved */\n    pathFields?: string[];\n    /** Array of field names whose array elements should all be resolved as paths */\n    resolvePathArray?: string[];\n}\n\n/**\n * Default configuration options for Cardigantime.\n * These define the basic behavior of configuration loading.\n */\nexport interface DefaultOptions {\n    /** Directory path where configuration files are located */\n    configDirectory: string;\n    /** Name of the configuration file (e.g., 'config.yaml', 'app.yml') */\n    configFile: string;\n    /** Whether the configuration directory must exist. If true, throws error if directory doesn't exist */\n    isRequired: boolean;\n    /** File encoding for reading configuration files (e.g., 'utf8', 'ascii') */\n    encoding: string;\n    /** Configuration for resolving relative paths in configuration values */\n    pathResolution?: PathResolutionOptions;\n    /** \n     * Configuration for how array fields should be merged in hierarchical mode.\n     * Only applies when the 'hierarchical' feature is enabled.\n     * If not specified, all arrays use 'override' behavior (default).\n     */\n    fieldOverlaps?: FieldOverlapOptions;\n}\n\n/**\n * Complete options object passed to Cardigantime functions.\n * Combines defaults, features, schema shape, and logger.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Options<T extends z.ZodRawShape> {\n    /** Default configuration options */\n    defaults: DefaultOptions,\n    /** Array of enabled features */\n    features: Feature[],\n    /** Zod schema shape for validating user configuration */\n    configShape: T;\n    /** Logger instance for debugging and error reporting */\n    logger: Logger;\n}\n\n/**\n * Logger interface for Cardigantime's internal logging.\n * Compatible with popular logging libraries like Winston, Bunyan, etc.\n */\nexport interface Logger {\n    /** Debug-level logging for detailed troubleshooting information */\n    debug: (message: string, ...args: any[]) => void;\n    /** Info-level logging for general information */\n    info: (message: string, ...args: any[]) => void;\n    /** Warning-level logging for non-critical issues */\n    warn: (message: string, ...args: any[]) => void;\n    /** Error-level logging for critical problems */\n    error: (message: string, ...args: any[]) => void;\n    /** Verbose-level logging for extensive detail */\n    verbose: (message: string, ...args: any[]) => void;\n    /** Silly-level logging for maximum detail */\n    silly: (message: string, ...args: any[]) => void;\n}\n\n/**\n * Main Cardigantime interface providing configuration management functionality.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Cardigantime<T extends z.ZodRawShape> {\n    /** \n     * Adds Cardigantime's CLI options to a Commander.js command.\n     * This includes options like --config-directory for runtime config path overrides.\n     */\n    configure: (command: Command) => Promise<Command>;\n    /** Sets a custom logger for debugging and error reporting */\n    setLogger: (logger: Logger) => void;\n    /** \n     * Reads configuration from files and merges with CLI arguments.\n     * Returns a fully typed configuration object.\n     */\n    read: (args: Args) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;\n    /** \n     * Validates the merged configuration against the Zod schema.\n     * Throws ConfigurationError if validation fails.\n     */\n    validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => Promise<void>;\n}\n\n/**\n * Parsed command-line arguments object, typically from Commander.js opts().\n * Keys correspond to CLI option names with values from user input.\n */\nexport interface Args {\n    [key: string]: any;\n}\n\n/**\n * Base Zod schema for core Cardigantime configuration.\n * Contains the minimum required configuration fields.\n */\nexport const ConfigSchema = z.object({\n    /** The resolved configuration directory path */\n    configDirectory: z.string(),\n});\n\n/**\n * Base configuration type derived from the core schema.\n */\nexport type Config = z.infer<typeof ConfigSchema>;\n"],"names":["ConfigSchema","z","object","configDirectory","string"],"mappings":";;AA8IA;;;AAGC,IACM,MAAMA,YAAAA,GAAeC,CAAAA,CAAEC,MAAM,CAAC;qDAEjCC,eAAAA,EAAiBF,CAAAA,CAAEG,MAAM;AAC7B,CAAA;;;;"}

package/dist/util/hierarchical.d.ts

@@ -1,4 +1,4 @@
-import { Logger } from '../types';
+import { Logger, FieldOverlapOptions } from '../types';
 /**
  * Represents a discovered configuration directory with its path and precedence level.
  */
@@ -24,6 +24,12 @@ export interface HierarchicalDiscoveryOptions {
     encoding?: string;
     /** Logger for debugging */
     logger?: Logger;
+    /** Array of field names that contain paths to be resolved */
+    pathFields?: string[];
+    /** Array of field names whose array elements should all be resolved as paths */
+    resolvePathArray?: string[];
+    /** Configuration for how array fields should be merged in hierarchical mode */
+    fieldOverlaps?: FieldOverlapOptions;
 }
 /**
  * Result of loading configurations from multiple directories.
@@ -68,29 +74,33 @@ export declare function discoverConfigDirectories(options: HierarchicalDiscovery
  * @param configFileName Name of the configuration file
  * @param encoding File encoding
  * @param logger Optional logger
+ * @param pathFields Optional array of field names that contain paths to be resolved
+ * @param resolvePathArray Optional array of field names whose array elements should all be resolved as paths
  * @returns Promise resolving to parsed configuration object or null if not found
  */
-export declare function loadConfigFromDirectory(configDir: string, configFileName: string, encoding?: string, logger?: Logger): Promise<object | null>;
+export declare function loadConfigFromDirectory(configDir: string, configFileName: string, encoding?: string, logger?: Logger, pathFields?: string[], resolvePathArray?: string[]): Promise<object | null>;
 /**
- * Deep merges multiple configuration objects with proper precedence.
+ * Deep merges multiple configuration objects with proper precedence and configurable array overlap behavior.
  *
  * Objects are merged from lowest precedence to highest precedence,
  * meaning that properties in later objects override properties in earlier objects.
- * Arrays are replaced entirely (not merged).
+ * Arrays can be merged using different strategies based on the fieldOverlaps configuration.
  *
  * @param configs Array of configuration objects, ordered from lowest to highest precedence
+ * @param fieldOverlaps Configuration for how array fields should be merged (optional)
  * @returns Merged configuration object
  *
  * @example
  * ```typescript
  * const merged = deepMergeConfigs([
- *   { api: { timeout: 5000 }, debug: true },        // Lower precedence
- *   { api: { retries: 3 }, features: ['auth'] },    // Higher precedence
- * ]);
- * // Result: { api: { timeout: 5000, retries: 3 }, debug: true, features: ['auth'] }
+ *   { api: { timeout: 5000 }, features: ['auth'] },        // Lower precedence
+ *   { api: { retries: 3 }, features: ['analytics'] },      // Higher precedence
+ * ], {
+ *   'features': 'append'  // Results in features: ['auth', 'analytics']
+ * });
  * ```
  */
-export declare function deepMergeConfigs(configs: object[]): object;
+export declare function deepMergeConfigs(configs: object[], fieldOverlaps?: FieldOverlapOptions): object;
 /**
  * Loads configurations from multiple directories and merges them with proper precedence.
  *
@@ -109,10 +119,14 @@ export declare function deepMergeConfigs(configs: object[]): object;
  *   configDirName: '.kodrdriv',
  *   configFileName: 'config.yaml',
  *   startingDir: '/project/subdir',
- *   maxLevels: 5
+ *   maxLevels: 5,
+ *   fieldOverlaps: {
+ *     'features': 'append',
+ *     'excludePatterns': 'prepend'
+ *   }
  * });
  *
- * // result.config contains merged configuration
+ * // result.config contains merged configuration with custom array merging
  * // result.discoveredDirs shows where configs were found
  * // result.errors contains any non-fatal errors
  * ```