@theunwalked/cardigantime 0.0.8 → 0.0.10

package/dist/cardigantime.cjs

@@ -176,6 +176,10 @@ class ArgumentError extends Error {
             throw error;
         }
     }, validatedDefaultDir);
+    // Add the init config option
+    retCommand = retCommand.option('--init-config', 'Generate initial configuration file and exit');
+    // Add the check config option
+    retCommand = retCommand.option('--check-config', 'Display resolved configuration with source tracking and exit');
     return retCommand;
 };
 
@@ -590,24 +594,26 @@ const create$1 = (params)=>{
     }
 }
 /**
- * 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 {};
     }
@@ -617,16 +623,18 @@ const create$1 = (params)=>{
         };
     }
     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;
@@ -634,11 +642,17 @@ const create$1 = (params)=>{
     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
@@ -649,17 +663,72 @@ const create$1 = (params)=>{
     };
     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.
  * 
@@ -678,15 +747,19 @@ const create$1 = (params)=>{
  *   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);
@@ -720,8 +793,8 @@ const create$1 = (params)=>{
             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,
@@ -909,7 +982,8 @@ const create$1 = (params)=>{
                 encoding: options.defaults.encoding,
                 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
+                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) {
@@ -981,6 +1055,263 @@ const create$1 = (params)=>{
     }
     return rawFileConfig;
 }
+/**
+ * Recursively tracks the source of configuration values from hierarchical loading.
+ * 
+ * @param config - The configuration object to track
+ * @param sourcePath - Path to the configuration file
+ * @param level - Hierarchical level
+ * @param prefix - Current object path prefix for nested values
+ * @param tracker - The tracker object to populate
+ */ function trackConfigSources(config, sourcePath, level, prefix = '', tracker = {}) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        // For primitives and arrays, track the entire value
+        tracker[prefix] = {
+            value: config,
+            sourcePath,
+            level,
+            sourceLabel: `Level ${level}: ${path__namespace.basename(path__namespace.dirname(sourcePath))}`
+        };
+        return tracker;
+    }
+    // For objects, recursively track each property
+    for (const [key, value] of Object.entries(config)){
+        const fieldPath = prefix ? `${prefix}.${key}` : key;
+        trackConfigSources(value, sourcePath, level, fieldPath, tracker);
+    }
+    return tracker;
+}
+/**
+ * Merges multiple configuration source trackers with proper precedence.
+ * Lower level numbers have higher precedence.
+ * 
+ * @param trackers - Array of trackers from different config sources
+ * @returns Merged tracker with proper precedence
+ */ function mergeConfigTrackers(trackers) {
+    const merged = {};
+    for (const tracker of trackers){
+        for (const [key, info] of Object.entries(tracker)){
+            // Only update if we don't have this key yet, or if this source has higher precedence (lower level)
+            if (!merged[key] || info.level < merged[key].level) {
+                merged[key] = info;
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Formats a configuration value for display, handling different types appropriately.
+ * 
+ * @param value - The configuration value to format
+ * @returns Formatted string representation
+ */ function formatConfigValue(value) {
+    if (value === null) return 'null';
+    if (value === undefined) return 'undefined';
+    if (typeof value === 'string') return `"${value}"`;
+    if (typeof value === 'boolean') return value.toString();
+    if (typeof value === 'number') return value.toString();
+    if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        if (value.length <= 3) {
+            return `[${value.map(formatConfigValue).join(', ')}]`;
+        }
+        return `[${value.slice(0, 2).map(formatConfigValue).join(', ')}, ... (${value.length} items)]`;
+    }
+    if (typeof value === 'object') {
+        const keys = Object.keys(value);
+        if (keys.length === 0) return '{}';
+        if (keys.length <= 2) {
+            return `{${keys.slice(0, 2).join(', ')}}`;
+        }
+        return `{${keys.slice(0, 2).join(', ')}, ... (${keys.length} keys)}`;
+    }
+    return String(value);
+}
+/**
+ * Displays configuration with source tracking in a git blame-like format.
+ * 
+ * @param config - The resolved configuration object
+ * @param tracker - Configuration source tracker
+ * @param discoveredDirs - Array of discovered configuration directories
+ * @param logger - Logger instance for output
+ */ function displayConfigWithSources(config, tracker, discoveredDirs, logger) {
+    logger.info('\n' + '='.repeat(80));
+    logger.info('CONFIGURATION SOURCE ANALYSIS');
+    logger.info('='.repeat(80));
+    // Display discovered configuration hierarchy
+    logger.info('\nDISCOVERED CONFIGURATION HIERARCHY:');
+    if (discoveredDirs.length === 0) {
+        logger.info('  No configuration directories found in hierarchy');
+    } else {
+        discoveredDirs.sort((a, b)=>a.level - b.level) // Sort by precedence (lower level = higher precedence)
+        .forEach((dir)=>{
+            const precedence = dir.level === 0 ? '(highest precedence)' : dir.level === Math.max(...discoveredDirs.map((d)=>d.level)) ? '(lowest precedence)' : '';
+            logger.info(`  Level ${dir.level}: ${dir.path} ${precedence}`);
+        });
+    }
+    // Display resolved configuration with sources
+    logger.info('\nRESOLVED CONFIGURATION WITH SOURCES:');
+    logger.info('Format: [Source] key: value\n');
+    const sortedKeys = Object.keys(tracker).sort();
+    const maxKeyLength = Math.max(...sortedKeys.map((k)=>k.length), 20);
+    const maxSourceLength = Math.max(...Object.values(tracker).map((info)=>info.sourceLabel.length), 25);
+    for (const key of sortedKeys){
+        const info = tracker[key];
+        const paddedKey = key.padEnd(maxKeyLength);
+        const paddedSource = info.sourceLabel.padEnd(maxSourceLength);
+        const formattedValue = formatConfigValue(info.value);
+        logger.info(`[${paddedSource}] ${paddedKey}: ${formattedValue}`);
+    }
+    // Display summary
+    logger.info('\n' + '-'.repeat(80));
+    logger.info('SUMMARY:');
+    logger.info(`  Total configuration keys: ${Object.keys(tracker).length}`);
+    logger.info(`  Configuration sources: ${discoveredDirs.length}`);
+    // Count values by source
+    const sourceCount = {};
+    for (const info of Object.values(tracker)){
+        sourceCount[info.sourceLabel] = (sourceCount[info.sourceLabel] || 0) + 1;
+    }
+    logger.info('  Values by source:');
+    for (const [source, count] of Object.entries(sourceCount)){
+        logger.info(`    ${source}: ${count} value(s)`);
+    }
+    logger.info('='.repeat(80));
+}
+/**
+ * Checks and displays the resolved configuration with detailed source tracking.
+ * 
+ * This function provides a git blame-like view of configuration resolution,
+ * showing which file and hierarchical level contributed each configuration value.
+ * 
+ * @template T - The Zod schema shape type for configuration validation
+ * @param args - Parsed command-line arguments
+ * @param options - Cardigantime options with defaults, schema, and logger
+ * @returns Promise that resolves when the configuration check is complete
+ * 
+ * @example
+ * ```typescript
+ * await checkConfig(cliArgs, {
+ *   defaults: { configDirectory: './config', configFile: 'app.yaml' },
+ *   configShape: MySchema.shape,
+ *   logger: console,
+ *   features: ['config', 'hierarchical']
+ * });
+ * // Outputs detailed configuration source analysis
+ * ```
+ */ const checkConfig = async (args, options)=>{
+    var _options_defaults, _options_defaults_pathResolution;
+    const logger = options.logger;
+    logger.info('Starting configuration check...');
+    const rawConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
+    if (!rawConfigDir) {
+        throw new Error('Configuration directory must be specified');
+    }
+    const resolvedConfigDir = validateConfigDirectory$1(rawConfigDir);
+    logger.verbose(`Resolved config directory: ${resolvedConfigDir}`);
+    let rawFileConfig = {};
+    let discoveredDirs = [];
+    let tracker = {};
+    // Check if hierarchical configuration discovery is enabled
+    if (options.features.includes('hierarchical')) {
+        logger.verbose('Using hierarchical configuration discovery for source tracking');
+        try {
+            var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
+            // Extract the config directory name from the path for hierarchical discovery
+            const configDirName = path__namespace.basename(resolvedConfigDir);
+            const startingDir = path__namespace.dirname(resolvedConfigDir);
+            logger.debug(`Using hierarchical discovery: configDirName=${configDirName}, startingDir=${startingDir}`);
+            const hierarchicalResult = await loadHierarchicalConfig({
+                configDirName,
+                configFileName: options.defaults.configFile,
+                startingDir,
+                encoding: options.defaults.encoding,
+                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;
+            discoveredDirs = hierarchicalResult.discoveredDirs;
+            // Build detailed source tracking by re-loading each config individually
+            const trackers = [];
+            // Sort by level (highest level first = lowest precedence first) to match merge order
+            const sortedDirs = [
+                ...discoveredDirs
+            ].sort((a, b)=>b.level - a.level);
+            for (const dir of sortedDirs){
+                const storage = create$1({
+                    log: logger.debug
+                });
+                const configFilePath = path__namespace.join(dir.path, options.defaults.configFile);
+                try {
+                    const exists = await storage.exists(configFilePath);
+                    if (!exists) continue;
+                    const isReadable = await storage.isFileReadable(configFilePath);
+                    if (!isReadable) continue;
+                    const yamlContent = await storage.readFile(configFilePath, options.defaults.encoding);
+                    const parsedYaml = yaml__namespace.load(yamlContent);
+                    if (parsedYaml !== null && typeof parsedYaml === 'object') {
+                        const levelTracker = trackConfigSources(parsedYaml, configFilePath, dir.level);
+                        trackers.push(levelTracker);
+                    }
+                } catch (error) {
+                    logger.debug(`Error loading config for source tracking from ${configFilePath}: ${error.message}`);
+                }
+            }
+            // Merge trackers with proper precedence
+            tracker = mergeConfigTrackers(trackers);
+            if (hierarchicalResult.errors.length > 0) {
+                logger.warn('Configuration loading warnings:');
+                hierarchicalResult.errors.forEach((error)=>logger.warn(`  ${error}`));
+            }
+        } catch (error) {
+            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));
+            logger.verbose('Falling back to single directory configuration loading');
+            // Fall back to single directory mode for source tracking
+            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+            const configFilePath = path__namespace.join(resolvedConfigDir, options.defaults.configFile);
+            tracker = trackConfigSources(rawFileConfig, configFilePath, 0);
+            discoveredDirs = [
+                {
+                    path: resolvedConfigDir,
+                    level: 0
+                }
+            ];
+        }
+    } else {
+        // Use traditional single directory configuration loading
+        logger.verbose('Using single directory configuration loading for source tracking');
+        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+        const configFilePath = path__namespace.join(resolvedConfigDir, options.defaults.configFile);
+        tracker = trackConfigSources(rawFileConfig, configFilePath, 0);
+        discoveredDirs = [
+            {
+                path: resolvedConfigDir,
+                level: 0
+            }
+        ];
+    }
+    // Apply path resolution if configured (this doesn't change source tracking)
+    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 || []);
+    }
+    // Build final configuration including built-in values
+    const finalConfig = clean({
+        ...processedConfig,
+        configDirectory: resolvedConfigDir
+    });
+    // Add built-in configuration to tracker
+    tracker['configDirectory'] = {
+        value: resolvedConfigDir,
+        sourcePath: 'built-in',
+        level: -1,
+        sourceLabel: 'Built-in (runtime)'
+    };
+    // Display the configuration with source information
+    displayConfigWithSources(finalConfig, tracker, discoveredDirs, logger);
+};
 
 /**
  * Error thrown when configuration validation fails
@@ -1293,6 +1624,110 @@ class ConfigurationError extends Error {
     return;
 };
 
+/**
+ * Extracts default values from a Zod schema recursively.
+ * 
+ * This function traverses a Zod schema and builds an object containing
+ * all the default values defined in the schema. It handles:
+ * - ZodDefault types with explicit default values
+ * - ZodOptional/ZodNullable types by unwrapping them
+ * - ZodObject types by recursively processing their shape
+ * - ZodArray types by providing an empty array as default
+ * 
+ * @param schema - The Zod schema to extract defaults from
+ * @returns An object containing all default values from the schema
+ * 
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   name: z.string().default('app'),
+ *   port: z.number().default(3000),
+ *   debug: z.boolean().default(false),
+ *   database: z.object({
+ *     host: z.string().default('localhost'),
+ *     port: z.number().default(5432)
+ *   })
+ * });
+ * 
+ * const defaults = extractSchemaDefaults(schema);
+ * // Returns: { name: 'app', port: 3000, debug: false, database: { host: 'localhost', port: 5432 } }
+ * ```
+ */ const extractSchemaDefaults = (schema)=>{
+    // Handle ZodDefault - extract the default value
+    if (schema._def && schema._def.typeName === 'ZodDefault') {
+        const defaultSchema = schema;
+        return defaultSchema._def.defaultValue();
+    }
+    // Handle ZodOptional and ZodNullable - unwrap and recurse
+    if (schema._def && (schema._def.typeName === 'ZodOptional' || schema._def.typeName === 'ZodNullable')) {
+        const unwrappable = schema;
+        return extractSchemaDefaults(unwrappable.unwrap());
+    }
+    // Handle ZodObject - recursively process shape
+    if (schema._def && schema._def.typeName === 'ZodObject') {
+        const objectSchema = schema;
+        const result = {};
+        for (const [key, subschema] of Object.entries(objectSchema.shape)){
+            const defaultValue = extractSchemaDefaults(subschema);
+            if (defaultValue !== undefined) {
+                result[key] = defaultValue;
+            }
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    // Handle ZodArray - provide empty array as default
+    if (schema._def && schema._def.typeName === 'ZodArray') {
+        const arraySchema = schema;
+        const elementDefaults = extractSchemaDefaults(arraySchema.element);
+        // Return an empty array, or an array with one example element if it has defaults
+        return elementDefaults !== undefined ? [
+            elementDefaults
+        ] : [];
+    }
+    // Handle ZodRecord - provide empty object as default
+    if (schema._def && schema._def.typeName === 'ZodRecord') {
+        return {};
+    }
+    // For other types, return undefined (no default available)
+    return undefined;
+};
+/**
+ * Generates a complete configuration object with all default values populated.
+ * 
+ * This function combines the base ConfigSchema with a user-provided schema shape
+ * and extracts all available default values to create a complete configuration
+ * example that can be serialized to YAML.
+ * 
+ * @template T - The Zod schema shape type
+ * @param configShape - The user's configuration schema shape
+ * @param configDirectory - The configuration directory to include in the defaults
+ * @returns An object containing all default values suitable for YAML serialization
+ * 
+ * @example
+ * ```typescript
+ * const shape = z.object({
+ *   apiKey: z.string().describe('Your API key'),
+ *   timeout: z.number().default(5000).describe('Request timeout in milliseconds'),
+ *   features: z.array(z.string()).default(['auth', 'logging'])
+ * }).shape;
+ * 
+ * const config = generateDefaultConfig(shape, './config');
+ * // Returns: { timeout: 5000, features: ['auth', 'logging'] }
+ * // Note: apiKey is not included since it has no default
+ * ```
+ */ const generateDefaultConfig = (configShape, configDirectory)=>{
+    // Create the full schema by combining base and user schema
+    const fullSchema = zod.z.object({
+        ...configShape
+    });
+    // Extract defaults from the full schema
+    const defaults = extractSchemaDefaults(fullSchema);
+    // Don't include configDirectory in the generated file since it's runtime-specific
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { configDirectory: _, ...configDefaults } = defaults || {};
+    return configDefaults || {};
+};
+
 /**
  * Creates a new Cardigantime instance for configuration management.
  * 
@@ -1335,9 +1770,15 @@ class ConfigurationError extends Error {
  *     pathResolution: {
  *       pathFields: ['contextDirectories'],
  *       resolvePathArray: ['contextDirectories']
+ *     },
+ *     // Configure how array fields are merged in hierarchical mode
+ *     fieldOverlaps: {
+ *       'features': 'append',              // Accumulate features from all levels
+ *       'excludePatterns': 'prepend'       // Higher precedence patterns come first
  *     }
  *   },
  *   configShape: MyConfigSchema.shape,
+ *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery
  * });
  * 
  * // If config file is at ../config/myapp.yaml and contains:
@@ -1362,11 +1803,76 @@ class ConfigurationError extends Error {
         logger = pLogger;
         options.logger = pLogger;
     };
+    const generateConfig = async (configDirectory)=>{
+        const targetDir = configDirectory || options.defaults.configDirectory;
+        const configFile = options.defaults.configFile;
+        const encoding = options.defaults.encoding;
+        logger.verbose(`Generating configuration file in: ${targetDir}`);
+        // Create storage utility
+        const storage = create$1({
+            log: logger.debug
+        });
+        // Ensure the target directory exists
+        const dirExists = await storage.exists(targetDir);
+        if (!dirExists) {
+            logger.info(`Creating configuration directory: ${targetDir}`);
+            try {
+                await storage.createDirectory(targetDir);
+            } catch (error) {
+                throw FileSystemError.directoryCreationFailed(targetDir, error);
+            }
+        }
+        // Check if directory is writable
+        const isWritable = await storage.isDirectoryWritable(targetDir);
+        if (!isWritable) {
+            throw new FileSystemError('not_writable', 'Configuration directory is not writable', targetDir, 'directory_write');
+        }
+        // Build the full config file path
+        const configFilePath = path__namespace.join(targetDir, configFile);
+        // Generate default configuration
+        const defaultConfig = generateDefaultConfig(options.configShape);
+        // Convert to YAML with nice formatting
+        const yamlContent = yaml__namespace.dump(defaultConfig, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+            sortKeys: true
+        });
+        // Add header comment to the YAML file
+        const header = `# Configuration file generated by Cardigantime
+# This file contains default values for your application configuration.
+# Modify the values below to customize your application's behavior.
+#
+# For more information about Cardigantime configuration:
+# https://github.com/SemicolonAmbulance/cardigantime
+
+`;
+        const finalContent = header + yamlContent;
+        // Check if config file already exists
+        const configExists = await storage.exists(configFilePath);
+        if (configExists) {
+            logger.warn(`Configuration file already exists: ${configFilePath}`);
+            logger.warn('This file was not overwritten, but here is what the default configuration looks like if you want to copy it:');
+            logger.info('\n' + '='.repeat(60));
+            logger.info(finalContent.trim());
+            logger.info('='.repeat(60));
+            return;
+        }
+        // Write the configuration file
+        try {
+            await storage.writeFile(configFilePath, finalContent, encoding);
+            logger.info(`Configuration file generated successfully: ${configFilePath}`);
+        } catch (error) {
+            throw FileSystemError.operationFailed('write configuration file', configFilePath, error);
+        }
+    };
     return {
         setLogger,
         configure: (command)=>configure(command, options),
         validate: (config)=>validate(config, options),
-        read: (args)=>read(args, options)
+        read: (args)=>read(args, options),
+        generateConfig,
+        checkConfig: (args)=>checkConfig(args, options)
     };
 };