@theunwalked/cardigantime 0.0.6 → 0.0.8

package/dist/cardigantime.cjs

@@ -187,7 +187,8 @@ class ArgumentError extends Error {
  */ const DEFAULT_OPTIONS = {
     configFile: DEFAULT_CONFIG_FILE,
     isRequired: false,
-    encoding: DEFAULT_ENCODING
+    encoding: DEFAULT_ENCODING,
+    pathResolution: undefined
 };
 /**
  * Default features enabled when creating a Cardigantime instance.
@@ -415,6 +416,62 @@ const create$1 = (params)=>{
     };
 };
 
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ */ function resolveConfigPaths$1(config, configDir, pathFields = [], resolvePathArray = []) {
+    if (!config || typeof config !== 'object' || pathFields.length === 0) {
+        return config;
+    }
+    const resolvedConfig = {
+        ...config
+    };
+    for (const fieldPath of pathFields){
+        const value = getNestedValue$1(resolvedConfig, fieldPath);
+        if (value !== undefined) {
+            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);
+            const resolvedValue = resolvePathValue$1(value, configDir, shouldResolveArrayElements);
+            setNestedValue$1(resolvedConfig, fieldPath, resolvedValue);
+        }
+    }
+    return resolvedConfig;
+}
+/**
+ * Gets a nested value from an object using dot notation.
+ */ function getNestedValue$1(obj, path) {
+    return path.split('.').reduce((current, key)=>current === null || current === void 0 ? void 0 : current[key], obj);
+}
+/**
+ * Sets a nested value in an object using dot notation.
+ */ function setNestedValue$1(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    const target = keys.reduce((current, key)=>{
+        if (!(key in current)) {
+            current[key] = {};
+        }
+        return current[key];
+    }, obj);
+    target[lastKey] = value;
+}
+/**
+ * Resolves a path value (string or array of strings) relative to the config directory.
+ */ function resolvePathValue$1(value, configDir, resolveArrayElements) {
+    if (typeof value === 'string') {
+        return resolveSinglePath$1(value, configDir);
+    }
+    if (Array.isArray(value) && resolveArrayElements) {
+        return value.map((item)=>typeof item === 'string' ? resolveSinglePath$1(item, configDir) : item);
+    }
+    return value;
+}
+/**
+ * Resolves a single path string relative to the config directory if it's a relative path.
+ */ function resolveSinglePath$1(pathStr, configDir) {
+    if (!pathStr || path.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path.resolve(configDir, pathStr);
+}
 /**
  * Discovers configuration directories by traversing up the directory tree.
  * 
@@ -483,7 +540,7 @@ const create$1 = (params)=>{
         currentDir = parentDir;
         level++;
     }
-    logger === null || logger === void 0 ? void 0 : logger.debug(`Discovery complete. Found ${discoveredDirs.length} config directories`);
+    logger === null || logger === void 0 ? void 0 : logger.verbose(`Discovery complete. Found ${discoveredDirs.length} config directories`);
     return discoveredDirs;
 }
 /**
@@ -493,14 +550,16 @@ const create$1 = (params)=>{
  * @param configFileName Name of the configuration file
  * @param encoding File encoding
  * @param logger Optional logger
+ * @param pathFields Optional array of field names that contain paths to be resolved
+ * @param resolvePathArray Optional array of field names whose array elements should all be resolved as paths
  * @returns Promise resolving to parsed configuration object or null if not found
- */ async function loadConfigFromDirectory(configDir, configFileName, encoding = 'utf8', logger) {
+ */ async function loadConfigFromDirectory(configDir, configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray) {
     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}`);
+        logger === null || logger === void 0 ? void 0 : logger.verbose(`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}`);
@@ -514,8 +573,13 @@ const create$1 = (params)=>{
         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;
+            let config = parsedYaml;
+            // Apply path resolution if configured
+            if (pathFields && pathFields.length > 0) {
+                config = resolveConfigPaths$1(config, configDir, pathFields, resolvePathArray || []);
+            }
+            logger === null || logger === void 0 ? void 0 : logger.verbose(`Successfully loaded config from: ${configFilePath}`);
+            return config;
         } else {
             logger === null || logger === void 0 ? void 0 : logger.debug(`Config file contains invalid format: ${configFilePath}`);
             return null;
@@ -622,12 +686,12 @@ const create$1 = (params)=>{
  * // 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');
+    const { configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray } = options;
+    logger === null || logger === void 0 ? void 0 : logger.verbose('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');
+        logger === null || logger === void 0 ? void 0 : logger.verbose('No configuration directories found');
         return {
             config: {},
             discoveredDirs: [],
@@ -643,7 +707,7 @@ const create$1 = (params)=>{
     ].sort((a, b)=>b.level - a.level);
     for (const dir of sortedDirs){
         try {
-            const config = await loadConfigFromDirectory(dir.path, configFileName, encoding, logger);
+            const config = await loadConfigFromDirectory(dir.path, configFileName, encoding, logger, pathFields, resolvePathArray);
             if (config !== null) {
                 configs.push(config);
                 logger === null || logger === void 0 ? void 0 : logger.debug(`Loaded config from level ${dir.level}: ${dir.path}`);
@@ -658,7 +722,7 @@ const create$1 = (params)=>{
     }
     // 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`);
+    logger === null || logger === void 0 ? void 0 : logger.verbose(`Hierarchical loading complete. Merged ${configs.length} configurations`);
     return {
         config: mergedConfig,
         discoveredDirs,
@@ -675,6 +739,68 @@ const create$1 = (params)=>{
  */ function clean(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([_, v])=>v !== undefined));
 }
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ * 
+ * @param config - The configuration object to process
+ * @param configDir - The directory containing the configuration file
+ * @param pathFields - Array of field names (using dot notation) that contain paths to be resolved
+ * @param resolvePathArray - Array of field names whose array elements should all be resolved as paths
+ * @returns The configuration object with resolved paths
+ */ function resolveConfigPaths(config, configDir, pathFields = [], resolvePathArray = []) {
+    if (!config || typeof config !== 'object' || pathFields.length === 0) {
+        return config;
+    }
+    const resolvedConfig = {
+        ...config
+    };
+    for (const fieldPath of pathFields){
+        const value = getNestedValue(resolvedConfig, fieldPath);
+        if (value !== undefined) {
+            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);
+            const resolvedValue = resolvePathValue(value, configDir, shouldResolveArrayElements);
+            setNestedValue(resolvedConfig, fieldPath, resolvedValue);
+        }
+    }
+    return resolvedConfig;
+}
+/**
+ * Gets a nested value from an object using dot notation.
+ */ function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key)=>current === null || current === void 0 ? void 0 : current[key], obj);
+}
+/**
+ * Sets a nested value in an object using dot notation.
+ */ function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    const target = keys.reduce((current, key)=>{
+        if (!(key in current)) {
+            current[key] = {};
+        }
+        return current[key];
+    }, obj);
+    target[lastKey] = value;
+}
+/**
+ * Resolves a path value (string or array of strings) relative to the config directory.
+ */ function resolvePathValue(value, configDir, resolveArrayElements) {
+    if (typeof value === 'string') {
+        return resolveSinglePath(value, configDir);
+    }
+    if (Array.isArray(value) && resolveArrayElements) {
+        return value.map((item)=>typeof item === 'string' ? resolveSinglePath(item, configDir) : item);
+    }
+    return value;
+}
+/**
+ * Resolves a single path string relative to the config directory if it's a relative path.
+ */ function resolveSinglePath(pathStr, configDir) {
+    if (!pathStr || path__namespace.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path__namespace.resolve(configDir, pathStr);
+}
 /**
  * Validates and secures a user-provided path to prevent path traversal attacks.
  * 
@@ -758,19 +884,20 @@ const create$1 = (params)=>{
  * // config is fully typed based on your schema
  * ```
  */ const read = async (args, options)=>{
-    var _options_defaults;
+    var _options_defaults, _options_defaults_pathResolution;
     const logger = options.logger;
     const rawConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
     if (!rawConfigDir) {
         throw new Error('Configuration directory must be specified');
     }
     const resolvedConfigDir = validateConfigDirectory$1(rawConfigDir);
-    logger.debug('Resolved config directory');
+    logger.verbose('Resolved config directory');
     let rawFileConfig = {};
     // Check if hierarchical configuration discovery is enabled
     if (options.features.includes('hierarchical')) {
-        logger.debug('Hierarchical configuration discovery enabled');
+        logger.verbose('Hierarchical configuration discovery enabled');
         try {
+            var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
             // Extract the config directory name from the path for hierarchical discovery
             const configDirName = path__namespace.basename(resolvedConfigDir);
             const startingDir = path__namespace.dirname(resolvedConfigDir);
@@ -780,16 +907,18 @@ const create$1 = (params)=>{
                 configFileName: options.defaults.configFile,
                 startingDir,
                 encoding: options.defaults.encoding,
-                logger
+                logger,
+                pathFields: (_options_defaults_pathResolution1 = options.defaults.pathResolution) === null || _options_defaults_pathResolution1 === void 0 ? void 0 : _options_defaults_pathResolution1.pathFields,
+                resolvePathArray: (_options_defaults_pathResolution2 = options.defaults.pathResolution) === null || _options_defaults_pathResolution2 === void 0 ? void 0 : _options_defaults_pathResolution2.resolvePathArray
             });
             rawFileConfig = hierarchicalResult.config;
             if (hierarchicalResult.discoveredDirs.length > 0) {
-                logger.debug(`Hierarchical discovery found ${hierarchicalResult.discoveredDirs.length} configuration directories`);
+                logger.verbose(`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');
+                logger.verbose('No configuration directories found in hierarchy');
             }
             if (hierarchicalResult.errors.length > 0) {
                 hierarchicalResult.errors.forEach((error)=>logger.warn(`Hierarchical config warning: ${error}`));
@@ -797,16 +926,21 @@ const create$1 = (params)=>{
         } 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');
+            logger.verbose('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');
+        logger.verbose('Using single directory configuration loading');
         rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
     }
+    // Apply path resolution if configured
+    let processedConfig = rawFileConfig;
+    if ((_options_defaults_pathResolution = options.defaults.pathResolution) === null || _options_defaults_pathResolution === void 0 ? void 0 : _options_defaults_pathResolution.pathFields) {
+        processedConfig = resolveConfigPaths(rawFileConfig, resolvedConfigDir, options.defaults.pathResolution.pathFields, options.defaults.pathResolution.resolvePathArray || []);
+    }
     const config = clean({
-        ...rawFileConfig,
+        ...processedConfig,
         ...{
             configDirectory: resolvedConfigDir
         }
@@ -825,7 +959,7 @@ const create$1 = (params)=>{
         log: logger.debug
     });
     const configFile = validatePath(options.defaults.configFile, resolvedConfigDir);
-    logger.debug('Attempting to load config file for cardigantime');
+    logger.verbose('Attempting to load config file for cardigantime');
     let rawFileConfig = {};
     try {
         const yamlContent = await storage.readFile(configFile, options.defaults.encoding);
@@ -833,13 +967,13 @@ const create$1 = (params)=>{
         const parsedYaml = yaml__namespace.load(yamlContent);
         if (parsedYaml !== null && typeof parsedYaml === 'object') {
             rawFileConfig = parsedYaml;
-            logger.debug('Loaded configuration file successfully');
+            logger.verbose('Loaded configuration file successfully');
         } else if (parsedYaml !== null) {
             logger.warn('Ignoring invalid configuration format. Expected an object, got ' + typeof parsedYaml);
         }
     } catch (error) {
         if (error.code === 'ENOENT' || /not found|no such file/i.test(error.message)) {
-            logger.debug('Configuration file not found. Using empty configuration.');
+            logger.verbose('Configuration file not found. Using empty configuration.');
         } else {
             // SECURITY FIX: Don't expose internal paths or detailed error information
             logger.error('Failed to load or parse configuration file: ' + (error.message || 'Unknown error'));
@@ -1152,7 +1286,8 @@ class ConfigurationError extends Error {
     checkForExtraKeys(config, fullSchema, logger);
     if (!validationResult.success) {
         const formattedError = JSON.stringify(validationResult.error.format(), null, 2);
-        logger.error('Configuration validation failed: %s', formattedError);
+        logger.error('Configuration validation failed. Check logs for details.');
+        logger.silly('Configuration validation failed: %s', formattedError);
         throw ConfigurationError.validation('Configuration validation failed. Check logs for details.', validationResult.error);
     }
     return;
@@ -1174,6 +1309,7 @@ class ConfigurationError extends Error {
  * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')
  * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)
  * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')
+ * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)
  * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])
  * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)
  * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)
@@ -1188,15 +1324,25 @@ class ConfigurationError extends Error {
  *   apiKey: z.string().min(1),
  *   timeout: z.number().default(5000),
  *   debug: z.boolean().default(false),
+ *   contextDirectories: z.array(z.string()).optional(),
  * });
  * 
  * const cardigantime = create({
  *   defaults: {
  *     configDirectory: './config',
  *     configFile: 'myapp.yaml',
+ *     // Resolve relative paths in contextDirectories relative to config file location
+ *     pathResolution: {
+ *       pathFields: ['contextDirectories'],
+ *       resolvePathArray: ['contextDirectories']
+ *     }
  *   },
  *   configShape: MyConfigSchema.shape,
  * });
+ * 
+ * // If config file is at ../config/myapp.yaml and contains:
+ * // contextDirectories: ['./context', './data']
+ * // These paths will be resolved relative to ../config/ directory
  * ```
  */ const create = (pOptions)=>{
     const defaults = {