@theunwalked/cardigantime 0.0.5 → 0.0.6

package/README.md

@@ -240,7 +240,7 @@ debug: true
 Cardigantime merges configuration from multiple sources in this order (highest to lowest priority):
 
 1. **Command-line arguments** (highest priority)
-2. **Configuration file** (medium priority)  
+2. **Configuration file(s)** (medium priority)  
 3. **Default values** (lowest priority)
 
 ```typescript
@@ -255,7 +255,105 @@ Cardigantime merges configuration from multiple sources in this order (highest t
 // debug: false    (from file)
 ```
 
-### 2. Schema Validation
+### 2. Hierarchical Configuration Discovery
+
+Cardigantime supports hierarchical configuration discovery, similar to how tools like `.gitignore`, `.eslintrc`, or `package.json` work. When the `hierarchical` feature is enabled, Cardigantime will:
+
+1. **Start from the specified config directory** (e.g., `./project/subdir/.kodrdriv`)
+2. **Search up the directory tree** for additional config directories with the same name
+3. **Merge configurations** with proper precedence (closer directories win)
+4. **Apply CLI arguments** as the final override
+
+#### Example Directory Structure
+
+```
+/home/user/projects/
+├── .kodrdriv/
+│   └── config.yaml          # Root-level config
+├── myproject/
+│   ├── .kodrdriv/
+│   │   └── config.yaml      # Project-level config  
+│   └── submodule/
+│       ├── .kodrdriv/
+│       │   └── config.yaml  # Submodule-level config
+│       └── my-script.js
+```
+
+#### Hierarchical Discovery Behavior
+
+When running from `/home/user/projects/myproject/submodule/` with hierarchical discovery:
+
+1. **Level 0 (Highest Priority)**: `/home/user/projects/myproject/submodule/.kodrdriv/config.yaml`
+2. **Level 1**: `/home/user/projects/myproject/.kodrdriv/config.yaml`  
+3. **Level 2 (Lowest Priority)**: `/home/user/projects/.kodrdriv/config.yaml`
+
+Configurations are deep-merged, with closer directories taking precedence:
+
+```yaml
+# /home/user/projects/.kodrdriv/config.yaml (Level 2)
+database:
+  host: localhost
+  port: 5432
+  ssl: false
+logging:
+  level: info
+
+# /home/user/projects/myproject/.kodrdriv/config.yaml (Level 1)  
+database:
+  port: 5433
+  ssl: true
+api:
+  timeout: 5000
+
+# /home/user/projects/myproject/submodule/.kodrdriv/config.yaml (Level 0)
+database:
+  host: dev.example.com
+logging:
+  level: debug
+
+# Final merged configuration:
+database:
+  host: dev.example.com    # From Level 0 (highest precedence)
+  port: 5433               # From Level 1  
+  ssl: true                # From Level 1
+api:
+  timeout: 5000            # From Level 1
+logging:
+  level: debug             # From Level 0 (highest precedence)
+```
+
+#### Enabling Hierarchical Discovery
+
+```typescript
+const cardigantime = create({
+  defaults: { 
+    configDirectory: '.kodrdriv',
+    configFile: 'config.yaml'
+  },
+  configShape: MyConfigSchema.shape,
+  features: ['config', 'hierarchical'], // Enable hierarchical discovery
+});
+```
+
+#### Hierarchical Discovery Options
+
+The hierarchical discovery has several built-in protections and features:
+
+- **Maximum traversal depth**: Prevents infinite loops (default: 10 levels)
+- **Symlink protection**: Tracks visited paths to prevent circular references
+- **Graceful fallback**: Falls back to single-directory mode if discovery fails
+- **Error tolerance**: Continues discovery even if some directories are unreadable
+- **Root detection**: Automatically stops at filesystem root
+
+#### Use Cases for Hierarchical Configuration
+
+1. **Monorepos**: Share common configuration across multiple packages
+2. **Project inheritance**: Override team/organization defaults for specific projects  
+3. **Environment layering**: Different configs for development/staging/production
+4. **Tool configuration**: Similar to how ESLint or Prettier find configs up the tree
+5. **Multi-tenant applications**: Tenant-specific overrides of global settings
+
+### 3. Schema Validation
 
 All configuration is validated against your Zod schema:
 
@@ -276,7 +374,7 @@ const cardigantime = create({
 });
 ```
 
-### 3. Type Safety
+### 4. Type Safety
 
 Cardigantime provides full TypeScript support:
 
@@ -293,7 +391,7 @@ if (config.features.includes('auth')) {
 }
 ```
 
-### 4. Error Handling
+### 5. Error Handling
 
 Cardigantime provides detailed error messages for common issues:
 
@@ -365,6 +463,129 @@ Sets a custom logger for debugging and error reporting.
 
 ## Advanced Usage
 
+### Hierarchical Configuration Discovery
+
+Here's a complete example of using hierarchical configuration discovery for a monorepo setup:
+
+```typescript
+import { create } from '@theunwalked/cardigantime';
+import { z } from 'zod';
+
+// Define a comprehensive configuration schema
+const ProjectConfigSchema = z.object({
+  projectName: z.string(),
+  environment: z.enum(['development', 'staging', 'production']).default('development'),
+  database: z.object({
+    host: z.string().default('localhost'),
+    port: z.number().default(5432),
+    ssl: z.boolean().default(false),
+    maxConnections: z.number().default(10),
+  }),
+  api: z.object({
+    baseUrl: z.string().url(),
+    timeout: z.number().default(5000),
+    retries: z.number().default(3),
+  }),
+  features: z.record(z.boolean()).default({}),
+  logging: z.object({
+    level: z.enum(['error', 'warn', 'info', 'debug']).default('info'),
+    outputs: z.array(z.string()).default(['console']),
+  }),
+});
+
+// Enable hierarchical discovery
+const cardigantime = create({
+  defaults: {
+    configDirectory: '.myapp',
+    configFile: 'config.yaml',
+  },
+  configShape: ProjectConfigSchema.shape,
+  features: ['config', 'hierarchical'], // Enable hierarchical discovery
+});
+
+// Usage in a CLI tool
+async function setupProject() {
+  try {
+    const config = await cardigantime.read(process.argv);
+    await cardigantime.validate(config);
+    
+    console.log(`Setting up ${config.projectName} in ${config.environment} mode`);
+    console.log(`Database: ${config.database.host}:${config.database.port}`);
+    console.log(`API: ${config.api.baseUrl}`);
+    
+    return config;
+  } catch (error) {
+    console.error('Configuration error:', error.message);
+    process.exit(1);
+  }
+}
+```
+
+**Directory Structure:**
+```
+/workspace/
+├── .myapp/
+│   └── config.yaml              # Global defaults
+├── team-frontend/
+│   ├── .myapp/
+│   │   └── config.yaml          # Team-specific settings
+│   ├── app1/
+│   │   ├── .myapp/
+│   │   │   └── config.yaml      # App-specific overrides
+│   │   └── package.json
+│   └── app2/
+│       └── package.json         # Uses team + global config
+```
+
+**Configuration Files:**
+```yaml
+# /workspace/.myapp/config.yaml (Global)
+database:
+  host: prod.db.company.com
+  ssl: true
+api:
+  baseUrl: https://api.company.com
+logging:
+  level: warn
+  outputs: [console, file]
+
+# /workspace/team-frontend/.myapp/config.yaml (Team)
+database:
+  host: team-frontend.db.company.com
+api:
+  timeout: 3000
+features:
+  analytics: true
+  darkMode: true
+
+# /workspace/team-frontend/app1/.myapp/config.yaml (App)
+projectName: frontend-app1
+environment: development
+database:
+  host: localhost  # Override for local development
+logging:
+  level: debug
+```
+
+When running from `/workspace/team-frontend/app1/`, the final merged configuration will be:
+
+```yaml
+projectName: frontend-app1           # From app level
+environment: development             # From app level  
+database:
+  host: localhost                   # From app level (highest precedence)
+  ssl: true                         # From global level
+api:
+  baseUrl: https://api.company.com  # From global level
+  timeout: 3000                     # From team level
+features:
+  analytics: true                   # From team level
+  darkMode: true                    # From team level
+logging:
+  level: debug                      # From app level (highest precedence)
+  outputs: [console, file]          # From global level
+```
+
 ### Custom Logger
 
 ```typescript

package/dist/cardigantime.cjs

@@ -415,6 +415,257 @@ const create$1 = (params)=>{
     };
 };
 
+/**
+ * Discovers configuration directories by traversing up the directory tree.
+ * 
+ * Starting from the specified directory (or current working directory),
+ * this function searches for directories with the given name, continuing
+ * up the directory tree until it reaches the filesystem root or the
+ * maximum number of levels.
+ * 
+ * @param options Configuration options for discovery
+ * @returns Promise resolving to array of discovered configuration directories
+ * 
+ * @example
+ * ```typescript
+ * const dirs = await discoverConfigDirectories({
+ *   configDirName: '.kodrdriv',
+ *   configFileName: 'config.yaml',
+ *   maxLevels: 5
+ * });
+ * // Returns: [
+ * //   { path: '/project/.kodrdriv', level: 0 },
+ * //   { path: '/project/parent/.kodrdriv', level: 1 }
+ * // ]
+ * ```
+ */ async function discoverConfigDirectories(options) {
+    const { configDirName, maxLevels = 10, startingDir = process.cwd(), logger } = options;
+    const storage = create$1({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    const discoveredDirs = [];
+    let currentDir = path.resolve(startingDir);
+    let level = 0;
+    const visited = new Set(); // Prevent infinite loops with symlinks
+    logger === null || logger === void 0 ? void 0 : logger.debug(`Starting hierarchical discovery from: ${currentDir}`);
+    while(level < maxLevels){
+        // Prevent infinite loops with symlinks
+        const realPath = path.resolve(currentDir);
+        if (visited.has(realPath)) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Already visited ${realPath}, stopping discovery`);
+            break;
+        }
+        visited.add(realPath);
+        const configDirPath = path.join(currentDir, configDirName);
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Checking for config directory: ${configDirPath}`);
+        try {
+            const exists = await storage.exists(configDirPath);
+            const isReadable = exists && await storage.isDirectoryReadable(configDirPath);
+            if (exists && isReadable) {
+                discoveredDirs.push({
+                    path: configDirPath,
+                    level
+                });
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Found config directory at level ${level}: ${configDirPath}`);
+            } else if (exists && !isReadable) {
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Config directory exists but is not readable: ${configDirPath}`);
+            }
+        } catch (error) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Error checking config directory ${configDirPath}: ${error.message}`);
+        }
+        // Move up one directory level
+        const parentDir = path.dirname(currentDir);
+        // Check if we've reached the root directory
+        if (parentDir === currentDir) {
+            logger === null || logger === void 0 ? void 0 : logger.debug('Reached filesystem root, stopping discovery');
+            break;
+        }
+        currentDir = parentDir;
+        level++;
+    }
+    logger === null || logger === void 0 ? void 0 : logger.debug(`Discovery complete. Found ${discoveredDirs.length} config directories`);
+    return discoveredDirs;
+}
+/**
+ * Loads and parses a configuration file from a directory.
+ * 
+ * @param configDir Path to the configuration directory
+ * @param configFileName Name of the configuration file
+ * @param encoding File encoding
+ * @param logger Optional logger
+ * @returns Promise resolving to parsed configuration object or null if not found
+ */ async function loadConfigFromDirectory(configDir, configFileName, encoding = 'utf8', logger) {
+    const storage = create$1({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    const configFilePath = path.join(configDir, configFileName);
+    try {
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Attempting to load config file: ${configFilePath}`);
+        const exists = await storage.exists(configFilePath);
+        if (!exists) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file does not exist: ${configFilePath}`);
+            return null;
+        }
+        const isReadable = await storage.isFileReadable(configFilePath);
+        if (!isReadable) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file exists but is not readable: ${configFilePath}`);
+            return null;
+        }
+        const yamlContent = await storage.readFile(configFilePath, encoding);
+        const parsedYaml = yaml__namespace.load(yamlContent);
+        if (parsedYaml !== null && typeof parsedYaml === 'object') {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Successfully loaded config from: ${configFilePath}`);
+            return parsedYaml;
+        } else {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file contains invalid format: ${configFilePath}`);
+            return null;
+        }
+    } catch (error) {
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Error loading config from ${configFilePath}: ${error.message}`);
+        return null;
+    }
+}
+/**
+ * Deep merges multiple configuration objects with proper precedence.
+ * 
+ * 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).
+ * 
+ * @param configs Array of configuration objects, ordered from lowest to highest precedence
+ * @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'] }
+ * ```
+ */ function deepMergeConfigs(configs) {
+    if (configs.length === 0) {
+        return {};
+    }
+    if (configs.length === 1) {
+        return {
+            ...configs[0]
+        };
+    }
+    return configs.reduce((merged, current)=>{
+        return deepMergeTwo(merged, current);
+    }, {});
+}
+/**
+ * Deep merges two objects with proper precedence.
+ * 
+ * @param target Target object (lower precedence)
+ * @param source Source object (higher precedence)
+ * @returns Merged object
+ */ function deepMergeTwo(target, source) {
+    // Handle null/undefined
+    if (source == null) return target;
+    if (target == null) return source;
+    // Handle non-objects (primitives, arrays, functions, etc.)
+    if (typeof source !== 'object' || typeof target !== 'object') {
+        return source; // Source takes precedence
+    }
+    // Handle arrays - replace entirely, don't merge
+    if (Array.isArray(source)) {
+        return [
+            ...source
+        ];
+    }
+    if (Array.isArray(target)) {
+        return source; // Source object replaces target array
+    }
+    // Deep merge objects
+    const result = {
+        ...target
+    };
+    for(const key in source){
+        if (Object.prototype.hasOwnProperty.call(source, 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]);
+            } else {
+                // Replace with source value (higher precedence)
+                result[key] = source[key];
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Loads configurations from multiple directories and merges them with proper precedence.
+ * 
+ * This is the main function for hierarchical configuration loading. It:
+ * 1. Discovers configuration directories up the directory tree
+ * 2. Loads configuration files from each discovered directory
+ * 3. Merges them with proper precedence (closer directories win)
+ * 4. Returns the merged configuration with metadata
+ * 
+ * @param options Configuration options for hierarchical loading
+ * @returns Promise resolving to hierarchical configuration result
+ * 
+ * @example
+ * ```typescript
+ * const result = await loadHierarchicalConfig({
+ *   configDirName: '.kodrdriv',
+ *   configFileName: 'config.yaml',
+ *   startingDir: '/project/subdir',
+ *   maxLevels: 5
+ * });
+ * 
+ * // result.config contains merged configuration
+ * // result.discoveredDirs shows where configs were found
+ * // result.errors contains any non-fatal errors
+ * ```
+ */ async function loadHierarchicalConfig(options) {
+    const { configFileName, encoding = 'utf8', logger } = options;
+    logger === null || logger === void 0 ? void 0 : logger.debug('Starting hierarchical configuration loading');
+    // Discover all configuration directories
+    const discoveredDirs = await discoverConfigDirectories(options);
+    if (discoveredDirs.length === 0) {
+        logger === null || logger === void 0 ? void 0 : logger.debug('No configuration directories found');
+        return {
+            config: {},
+            discoveredDirs: [],
+            errors: []
+        };
+    }
+    // Load configurations from each directory
+    const configs = [];
+    const errors = [];
+    // Sort by level (highest level first = lowest precedence first)
+    const sortedDirs = [
+        ...discoveredDirs
+    ].sort((a, b)=>b.level - a.level);
+    for (const dir of sortedDirs){
+        try {
+            const config = await loadConfigFromDirectory(dir.path, configFileName, encoding, logger);
+            if (config !== null) {
+                configs.push(config);
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Loaded config from level ${dir.level}: ${dir.path}`);
+            } else {
+                logger === null || logger === void 0 ? void 0 : logger.debug(`No valid config found at level ${dir.level}: ${dir.path}`);
+            }
+        } catch (error) {
+            const errorMsg = `Failed to load config from ${dir.path}: ${error.message}`;
+            errors.push(errorMsg);
+            logger === null || logger === void 0 ? void 0 : logger.debug(errorMsg);
+        }
+    }
+    // Merge all configurations with proper precedence
+    const mergedConfig = deepMergeConfigs(configs);
+    logger === null || logger === void 0 ? void 0 : logger.debug(`Hierarchical loading complete. Merged ${configs.length} configurations`);
+    return {
+        config: mergedConfig,
+        discoveredDirs,
+        errors
+    };
+}
+
 /**
  * Removes undefined values from an object to create a clean configuration.
  * This is used to merge configuration sources while avoiding undefined pollution.
@@ -509,15 +760,70 @@ const create$1 = (params)=>{
  */ const read = async (args, options)=>{
     var _options_defaults;
     const logger = options.logger;
-    const storage = create$1({
-        log: logger.debug
-    });
     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.debug('Resolved config directory');
+    let rawFileConfig = {};
+    // Check if hierarchical configuration discovery is enabled
+    if (options.features.includes('hierarchical')) {
+        logger.debug('Hierarchical configuration discovery enabled');
+        try {
+            // 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
+            });
+            rawFileConfig = hierarchicalResult.config;
+            if (hierarchicalResult.discoveredDirs.length > 0) {
+                logger.debug(`Hierarchical discovery found ${hierarchicalResult.discoveredDirs.length} configuration directories`);
+                hierarchicalResult.discoveredDirs.forEach((dir)=>{
+                    logger.debug(`  Level ${dir.level}: ${dir.path}`);
+                });
+            } else {
+                logger.debug('No configuration directories found in hierarchy');
+            }
+            if (hierarchicalResult.errors.length > 0) {
+                hierarchicalResult.errors.forEach((error)=>logger.warn(`Hierarchical config warning: ${error}`));
+            }
+        } catch (error) {
+            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));
+            // Fall back to single directory mode
+            logger.debug('Falling back to single directory configuration loading');
+            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+        }
+    } else {
+        // Use traditional single directory configuration loading
+        logger.debug('Using single directory configuration loading');
+        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+    }
+    const config = clean({
+        ...rawFileConfig,
+        ...{
+            configDirectory: resolvedConfigDir
+        }
+    });
+    return config;
+};
+/**
+ * Loads configuration from a single directory (traditional mode).
+ * 
+ * @param resolvedConfigDir - The resolved configuration directory path
+ * @param options - Cardigantime options
+ * @param logger - Logger instance
+ * @returns Promise resolving to the configuration object
+ */ async function loadSingleDirectoryConfig(resolvedConfigDir, options, logger) {
+    const storage = create$1({
+        log: logger.debug
+    });
     const configFile = validatePath(options.defaults.configFile, resolvedConfigDir);
     logger.debug('Attempting to load config file for cardigantime');
     let rawFileConfig = {};
@@ -539,14 +845,8 @@ const create$1 = (params)=>{
             logger.error('Failed to load or parse configuration file: ' + (error.message || 'Unknown error'));
         }
     }
-    const config = clean({
-        ...rawFileConfig,
-        ...{
-            configDirectory: resolvedConfigDir
-        }
-    });
-    return config;
-};
+    return rawFileConfig;
+}
 
 /**
  * Error thrown when configuration validation fails