@theunwalked/cardigantime 0.0.8 → 0.0.10

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 * 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            });\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","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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"}
+{"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, DiscoveredConfigDir } 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}\n\n/**\n * Represents a configuration value with its source information.\n */\ninterface ConfigSourceInfo {\n    /** The configuration value */\n    value: any;\n    /** Path to the configuration file that provided this value */\n    sourcePath: string;\n    /** Hierarchical level (0 = closest/highest precedence) */\n    level: number;\n    /** Short description of the source for display */\n    sourceLabel: string;\n}\n\n/**\n * Tracks configuration values to their sources during hierarchical loading.\n */\ninterface ConfigSourceTracker {\n    [key: string]: ConfigSourceInfo;\n}\n\n/**\n * Recursively tracks the source of configuration values from hierarchical loading.\n * \n * @param config - The configuration object to track\n * @param sourcePath - Path to the configuration file\n * @param level - Hierarchical level\n * @param prefix - Current object path prefix for nested values\n * @param tracker - The tracker object to populate\n */\nfunction trackConfigSources(\n    config: any,\n    sourcePath: string,\n    level: number,\n    prefix: string = '',\n    tracker: ConfigSourceTracker = {}\n): ConfigSourceTracker {\n    if (!config || typeof config !== 'object' || Array.isArray(config)) {\n        // For primitives and arrays, track the entire value\n        tracker[prefix] = {\n            value: config,\n            sourcePath,\n            level,\n            sourceLabel: `Level ${level}: ${path.basename(path.dirname(sourcePath))}`\n        };\n        return tracker;\n    }\n\n    // For objects, recursively track each property\n    for (const [key, value] of Object.entries(config)) {\n        const fieldPath = prefix ? `${prefix}.${key}` : key;\n        trackConfigSources(value, sourcePath, level, fieldPath, tracker);\n    }\n\n    return tracker;\n}\n\n/**\n * Merges multiple configuration source trackers with proper precedence.\n * Lower level numbers have higher precedence.\n * \n * @param trackers - Array of trackers from different config sources\n * @returns Merged tracker with proper precedence\n */\nfunction mergeConfigTrackers(trackers: ConfigSourceTracker[]): ConfigSourceTracker {\n    const merged: ConfigSourceTracker = {};\n\n    for (const tracker of trackers) {\n        for (const [key, info] of Object.entries(tracker)) {\n            // Only update if we don't have this key yet, or if this source has higher precedence (lower level)\n            if (!merged[key] || info.level < merged[key].level) {\n                merged[key] = info;\n            }\n        }\n    }\n\n    return merged;\n}\n\n/**\n * Formats a configuration value for display, handling different types appropriately.\n * \n * @param value - The configuration value to format\n * @returns Formatted string representation\n */\nfunction formatConfigValue(value: any): string {\n    if (value === null) return 'null';\n    if (value === undefined) return 'undefined';\n    if (typeof value === 'string') return `\"${value}\"`;\n    if (typeof value === 'boolean') return value.toString();\n    if (typeof value === 'number') return value.toString();\n    if (Array.isArray(value)) {\n        if (value.length === 0) return '[]';\n        if (value.length <= 3) {\n            return `[${value.map(formatConfigValue).join(', ')}]`;\n        }\n        return `[${value.slice(0, 2).map(formatConfigValue).join(', ')}, ... (${value.length} items)]`;\n    }\n    if (typeof value === 'object') {\n        const keys = Object.keys(value);\n        if (keys.length === 0) return '{}';\n        if (keys.length <= 2) {\n            return `{${keys.slice(0, 2).join(', ')}}`;\n        }\n        return `{${keys.slice(0, 2).join(', ')}, ... (${keys.length} keys)}`;\n    }\n    return String(value);\n}\n\n/**\n * Displays configuration with source tracking in a git blame-like format.\n * \n * @param config - The resolved configuration object\n * @param tracker - Configuration source tracker\n * @param discoveredDirs - Array of discovered configuration directories\n * @param logger - Logger instance for output\n */\nfunction displayConfigWithSources(\n    config: any,\n    tracker: ConfigSourceTracker,\n    discoveredDirs: DiscoveredConfigDir[],\n    logger: any\n): void {\n    logger.info('\\n' + '='.repeat(80));\n    logger.info('CONFIGURATION SOURCE ANALYSIS');\n    logger.info('='.repeat(80));\n\n    // Display discovered configuration hierarchy\n    logger.info('\\nDISCOVERED CONFIGURATION HIERARCHY:');\n    if (discoveredDirs.length === 0) {\n        logger.info('  No configuration directories found in hierarchy');\n    } else {\n        discoveredDirs\n            .sort((a, b) => a.level - b.level) // Sort by precedence (lower level = higher precedence)\n            .forEach(dir => {\n                const precedence = dir.level === 0 ? '(highest precedence)' :\n                    dir.level === Math.max(...discoveredDirs.map(d => d.level)) ? '(lowest precedence)' :\n                        '';\n                logger.info(`  Level ${dir.level}: ${dir.path} ${precedence}`);\n            });\n    }\n\n    // Display resolved configuration with sources\n    logger.info('\\nRESOLVED CONFIGURATION WITH SOURCES:');\n    logger.info('Format: [Source] key: value\\n');\n\n    const sortedKeys = Object.keys(tracker).sort();\n    const maxKeyLength = Math.max(...sortedKeys.map(k => k.length), 20);\n    const maxSourceLength = Math.max(...Object.values(tracker).map(info => info.sourceLabel.length), 25);\n\n    for (const key of sortedKeys) {\n        const info = tracker[key];\n        const paddedKey = key.padEnd(maxKeyLength);\n        const paddedSource = info.sourceLabel.padEnd(maxSourceLength);\n        const formattedValue = formatConfigValue(info.value);\n\n        logger.info(`[${paddedSource}] ${paddedKey}: ${formattedValue}`);\n    }\n\n    // Display summary\n    logger.info('\\n' + '-'.repeat(80));\n    logger.info('SUMMARY:');\n    logger.info(`  Total configuration keys: ${Object.keys(tracker).length}`);\n    logger.info(`  Configuration sources: ${discoveredDirs.length}`);\n\n    // Count values by source\n    const sourceCount: { [source: string]: number } = {};\n    for (const info of Object.values(tracker)) {\n        sourceCount[info.sourceLabel] = (sourceCount[info.sourceLabel] || 0) + 1;\n    }\n\n    logger.info('  Values by source:');\n    for (const [source, count] of Object.entries(sourceCount)) {\n        logger.info(`    ${source}: ${count} value(s)`);\n    }\n\n    logger.info('='.repeat(80));\n}\n\n/**\n * Checks and displays the resolved configuration with detailed source tracking.\n * \n * This function provides a git blame-like view of configuration resolution,\n * showing which file and hierarchical level contributed each configuration value.\n * \n * @template T - The Zod schema shape type for configuration validation\n * @param args - Parsed command-line arguments\n * @param options - Cardigantime options with defaults, schema, and logger\n * @returns Promise that resolves when the configuration check is complete\n * \n * @example\n * ```typescript\n * await checkConfig(cliArgs, {\n *   defaults: { configDirectory: './config', configFile: 'app.yaml' },\n *   configShape: MySchema.shape,\n *   logger: console,\n *   features: ['config', 'hierarchical']\n * });\n * // Outputs detailed configuration source analysis\n * ```\n */\nexport const checkConfig = async <T extends z.ZodRawShape>(\n    args: Args,\n    options: Options<T>\n): Promise<void> => {\n    const logger = options.logger;\n\n    logger.info('Starting configuration check...');\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: ${resolvedConfigDir}`);\n\n    let rawFileConfig: object = {};\n    let discoveredDirs: DiscoveredConfigDir[] = [];\n    let tracker: ConfigSourceTracker = {};\n\n    // Check if hierarchical configuration discovery is enabled\n    if (options.features.includes('hierarchical')) {\n        logger.verbose('Using hierarchical configuration discovery for source tracking');\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            discoveredDirs = hierarchicalResult.discoveredDirs;\n\n            // Build detailed source tracking by re-loading each config individually\n            const trackers: ConfigSourceTracker[] = [];\n\n            // Sort by level (highest level first = lowest precedence first) to match merge order\n            const sortedDirs = [...discoveredDirs].sort((a, b) => b.level - a.level);\n\n            for (const dir of sortedDirs) {\n                const storage = Storage.create({ log: logger.debug });\n                const configFilePath = path.join(dir.path, options.defaults.configFile);\n\n                try {\n                    const exists = await storage.exists(configFilePath);\n                    if (!exists) continue;\n\n                    const isReadable = await storage.isFileReadable(configFilePath);\n                    if (!isReadable) continue;\n\n                    const yamlContent = await storage.readFile(configFilePath, options.defaults.encoding);\n                    const parsedYaml = yaml.load(yamlContent);\n\n                    if (parsedYaml !== null && typeof parsedYaml === 'object') {\n                        const levelTracker = trackConfigSources(parsedYaml, configFilePath, dir.level);\n                        trackers.push(levelTracker);\n                    }\n                } catch (error: any) {\n                    logger.debug(`Error loading config for source tracking from ${configFilePath}: ${error.message}`);\n                }\n            }\n\n            // Merge trackers with proper precedence\n            tracker = mergeConfigTrackers(trackers);\n\n            if (hierarchicalResult.errors.length > 0) {\n                logger.warn('Configuration loading warnings:');\n                hierarchicalResult.errors.forEach(error => logger.warn(`  ${error}`));\n            }\n\n        } catch (error: any) {\n            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));\n            logger.verbose('Falling back to single directory configuration loading');\n\n            // Fall back to single directory mode for source tracking\n            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);\n            const configFilePath = path.join(resolvedConfigDir, options.defaults.configFile);\n            tracker = trackConfigSources(rawFileConfig, configFilePath, 0);\n            discoveredDirs = [{\n                path: resolvedConfigDir,\n                level: 0\n            }];\n        }\n    } else {\n        // Use traditional single directory configuration loading\n        logger.verbose('Using single directory configuration loading for source tracking');\n        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);\n        const configFilePath = path.join(resolvedConfigDir, options.defaults.configFile);\n        tracker = trackConfigSources(rawFileConfig, configFilePath, 0);\n        discoveredDirs = [{\n            path: resolvedConfigDir,\n            level: 0\n        }];\n    }\n\n    // Apply path resolution if configured (this doesn't change source tracking)\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    // Build final configuration including built-in values\n    const finalConfig = clean({\n        ...processedConfig,\n        configDirectory: resolvedConfigDir,\n    });\n\n    // Add built-in configuration to tracker\n    tracker['configDirectory'] = {\n        value: resolvedConfigDir,\n        sourcePath: 'built-in',\n        level: -1,\n        sourceLabel: 'Built-in (runtime)'\n    };\n\n    // Display the configuration with source information\n    displayConfigWithSources(finalConfig, tracker, discoveredDirs, logger);\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","trackConfigSources","sourcePath","prefix","tracker","sourceLabel","mergeConfigTrackers","trackers","merged","info","formatConfigValue","toString","slice","String","displayConfigWithSources","repeat","sort","a","b","precedence","Math","max","d","sortedKeys","maxKeyLength","k","maxSourceLength","values","paddedKey","padEnd","paddedSource","formattedValue","sourceCount","source","count","checkConfig","sortedDirs","configFilePath","exists","isReadable","isFileReadable","levelTracker","push","finalConfig"],"mappings":"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"}

package/dist/types.d.ts

@@ -7,6 +7,30 @@ 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.
@@ -32,6 +56,12 @@ export interface DefaultOptions {
     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.
@@ -90,6 +120,16 @@ export interface Cardigantime<T extends z.ZodRawShape> {
      * Throws ConfigurationError if validation fails.
      */
     validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => Promise<void>;
+    /**
+     * Generates a configuration file with default values in the specified directory.
+     * Creates the directory if it doesn't exist and writes a config file with all default values populated.
+     */
+    generateConfig: (configDirectory?: string) => Promise<void>;
+    /**
+     * Checks and displays the resolved configuration with detailed source tracking.
+     * Shows which file and hierarchical level contributed each configuration value in a git blame-like format.
+     */
+    checkConfig: (args: Args) => Promise<void>;
 }
 /**
  * Parsed command-line arguments object, typically from Commander.js opts().

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 * 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\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":";;AA8GA;;;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     * Generates a configuration file with default values in the specified directory.\n     * Creates the directory if it doesn't exist and writes a config file with all default values populated.\n     */\n    generateConfig: (configDirectory?: string) => Promise<void>;\n    /** \n     * Checks and displays the resolved configuration with detailed source tracking.\n     * Shows which file and hierarchical level contributed each configuration value in a git blame-like format.\n     */\n    checkConfig: (args: Args) => 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":";;AAwJA;;;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.
  */
@@ -28,6 +28,8 @@ export interface HierarchicalDiscoveryOptions {
     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.
@@ -78,25 +80,27 @@ export declare function discoverConfigDirectories(options: HierarchicalDiscovery
  */
 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.
  *
@@ -115,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
  * ```

package/dist/util/hierarchical.js

@@ -176,24 +176,26 @@ import { create } from './storage.js';
     }
 }
 /**
- * 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']
+ * });
  * ```
- */ function deepMergeConfigs(configs) {
+ */ function deepMergeConfigs(configs, fieldOverlaps) {
     if (configs.length === 0) {
         return {};
     }
@@ -203,16 +205,18 @@ import { create } from './storage.js';
         };
     }
     return configs.reduce((merged, current)=>{
-        return deepMergeTwo(merged, current);
+        return deepMergeTwo(merged, current, fieldOverlaps);
     }, {});
 }
 /**
- * Deep merges two objects with proper precedence.
+ * Deep merges two objects with proper precedence and configurable array overlap behavior.
  * 
  * @param target Target object (lower precedence)
  * @param source Source object (higher precedence)
+ * @param fieldOverlaps Configuration for how array fields should be merged (optional)
+ * @param currentPath Current field path for nested merging (used internally)
  * @returns Merged object
- */ function deepMergeTwo(target, source) {
+ */ function deepMergeTwo(target, source, fieldOverlaps, currentPath = '') {
     // Handle null/undefined
     if (source == null) return target;
     if (target == null) return source;
@@ -220,11 +224,17 @@ import { create } from './storage.js';
     if (typeof source !== 'object' || typeof target !== 'object') {
         return source; // Source takes precedence
     }
-    // Handle arrays - replace entirely, don't merge
+    // Handle arrays with configurable overlap behavior
     if (Array.isArray(source)) {
-        return [
-            ...source
-        ];
+        if (Array.isArray(target) && fieldOverlaps) {
+            const overlapMode = getOverlapModeForPath(currentPath, fieldOverlaps);
+            return mergeArrays(target, source, overlapMode);
+        } else {
+            // Default behavior: replace entirely
+            return [
+                ...source
+            ];
+        }
     }
     if (Array.isArray(target)) {
         return source; // Source object replaces target array
@@ -235,17 +245,72 @@ import { create } from './storage.js';
     };
     for(const key in source){
         if (Object.prototype.hasOwnProperty.call(source, key)) {
+            const fieldPath = currentPath ? `${currentPath}.${key}` : key;
             if (Object.prototype.hasOwnProperty.call(result, key) && typeof result[key] === 'object' && typeof source[key] === 'object' && !Array.isArray(source[key]) && !Array.isArray(result[key])) {
                 // Recursively merge nested objects
-                result[key] = deepMergeTwo(result[key], source[key]);
+                result[key] = deepMergeTwo(result[key], source[key], fieldOverlaps, fieldPath);
             } else {
-                // Replace with source value (higher precedence)
-                result[key] = source[key];
+                // Handle arrays and primitives with overlap consideration
+                if (Array.isArray(source[key]) && Array.isArray(result[key]) && fieldOverlaps) {
+                    const overlapMode = getOverlapModeForPath(fieldPath, fieldOverlaps);
+                    result[key] = mergeArrays(result[key], source[key], overlapMode);
+                } else {
+                    // Replace with source value (higher precedence)
+                    result[key] = source[key];
+                }
             }
         }
     }
     return result;
 }
+/**
+ * Determines the overlap mode for a given field path.
+ * 
+ * @param fieldPath The current field path (dot notation)
+ * @param fieldOverlaps Configuration mapping field paths to overlap modes
+ * @returns The overlap mode to use for this field path
+ */ function getOverlapModeForPath(fieldPath, fieldOverlaps) {
+    // Check for exact match first
+    if (fieldPath in fieldOverlaps) {
+        return fieldOverlaps[fieldPath];
+    }
+    // Check for any parent path matches (for nested configurations)
+    const pathParts = fieldPath.split('.');
+    for(let i = pathParts.length - 1; i > 0; i--){
+        const parentPath = pathParts.slice(0, i).join('.');
+        if (parentPath in fieldOverlaps) {
+            return fieldOverlaps[parentPath];
+        }
+    }
+    // Default to override if no specific configuration found
+    return 'override';
+}
+/**
+ * Merges two arrays based on the specified overlap mode.
+ * 
+ * @param targetArray The lower precedence array
+ * @param sourceArray The higher precedence array
+ * @param mode The overlap mode to use
+ * @returns The merged array
+ */ function mergeArrays(targetArray, sourceArray, mode) {
+    switch(mode){
+        case 'append':
+            return [
+                ...targetArray,
+                ...sourceArray
+            ];
+        case 'prepend':
+            return [
+                ...sourceArray,
+                ...targetArray
+            ];
+        case 'override':
+        default:
+            return [
+                ...sourceArray
+            ];
+    }
+}
 /**
  * Loads configurations from multiple directories and merges them with proper precedence.
  * 
@@ -264,15 +329,19 @@ import { create } from './storage.js';
  *   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
  * ```
  */ async function loadHierarchicalConfig(options) {
-    const { configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray } = options;
+    const { configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray, fieldOverlaps } = options;
     logger === null || logger === void 0 ? void 0 : logger.verbose('Starting hierarchical configuration loading');
     // Discover all configuration directories
     const discoveredDirs = await discoverConfigDirectories(options);
@@ -306,8 +375,8 @@ import { create } from './storage.js';
             logger === null || logger === void 0 ? void 0 : logger.debug(errorMsg);
         }
     }
-    // Merge all configurations with proper precedence
-    const mergedConfig = deepMergeConfigs(configs);
+    // Merge all configurations with proper precedence and configurable array overlap
+    const mergedConfig = deepMergeConfigs(configs, fieldOverlaps);
     logger === null || logger === void 0 ? void 0 : logger.verbose(`Hierarchical loading complete. Merged ${configs.length} configurations`);
     return {
         config: mergedConfig,