@theunwalked/cardigantime 0.0.3 → 0.0.6

package/dist/util/hierarchical.d.ts

@@ -0,0 +1,120 @@
+import { Logger } from '../types';
+/**
+ * Represents a discovered configuration directory with its path and precedence level.
+ */
+export interface DiscoveredConfigDir {
+    /** Absolute path to the configuration directory */
+    path: string;
+    /** Distance from the starting directory (0 = closest/highest precedence) */
+    level: number;
+}
+/**
+ * Options for hierarchical configuration discovery.
+ */
+export interface HierarchicalDiscoveryOptions {
+    /** Name of the configuration directory to look for (e.g., '.kodrdriv') */
+    configDirName: string;
+    /** Name of the configuration file within each directory */
+    configFileName: string;
+    /** Maximum number of parent directories to traverse (default: 10) */
+    maxLevels?: number;
+    /** Starting directory for discovery (default: process.cwd()) */
+    startingDir?: string;
+    /** File encoding for reading configuration files */
+    encoding?: string;
+    /** Logger for debugging */
+    logger?: Logger;
+}
+/**
+ * Result of loading configurations from multiple directories.
+ */
+export interface HierarchicalConfigResult {
+    /** Merged configuration object with proper precedence */
+    config: object;
+    /** Array of directories where configuration was found */
+    discoveredDirs: DiscoveredConfigDir[];
+    /** Array of any errors encountered during loading (non-fatal) */
+    errors: string[];
+}
+/**
+ * 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 }
+ * // ]
+ * ```
+ */
+export declare function discoverConfigDirectories(options: HierarchicalDiscoveryOptions): Promise<DiscoveredConfigDir[]>;
+/**
+ * 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
+ */
+export declare function loadConfigFromDirectory(configDir: string, configFileName: string, encoding?: string, logger?: Logger): Promise<object | 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'] }
+ * ```
+ */
+export declare function deepMergeConfigs(configs: object[]): object;
+/**
+ * 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
+ * ```
+ */
+export declare function loadHierarchicalConfig(options: HierarchicalDiscoveryOptions): Promise<HierarchicalConfigResult>;

package/dist/util/hierarchical.js

@@ -0,0 +1,257 @@
+import path__default from 'path';
+import * as yaml from 'js-yaml';
+import { create } from './storage.js';
+
+/**
+ * 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({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    const discoveredDirs = [];
+    let currentDir = path__default.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__default.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__default.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__default.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({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    const configFilePath = path__default.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.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
+    };
+}
+
+export { deepMergeConfigs, discoverConfigDirectories, loadConfigFromDirectory, loadHierarchicalConfig };
+//# sourceMappingURL=hierarchical.js.map

package/dist/util/hierarchical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hierarchical.js","sources":["../../src/util/hierarchical.ts"],"sourcesContent":["import path from 'path';\nimport * as yaml from 'js-yaml';\nimport { create as createStorage } from './storage';\nimport { Logger } from '../types';\n\n/**\n * Represents a discovered configuration directory with its path and precedence level.\n */\nexport interface DiscoveredConfigDir {\n    /** Absolute path to the configuration directory */\n    path: string;\n    /** Distance from the starting directory (0 = closest/highest precedence) */\n    level: number;\n}\n\n/**\n * Options for hierarchical configuration discovery.\n */\nexport interface HierarchicalDiscoveryOptions {\n    /** Name of the configuration directory to look for (e.g., '.kodrdriv') */\n    configDirName: string;\n    /** Name of the configuration file within each directory */\n    configFileName: string;\n    /** Maximum number of parent directories to traverse (default: 10) */\n    maxLevels?: number;\n    /** Starting directory for discovery (default: process.cwd()) */\n    startingDir?: string;\n    /** File encoding for reading configuration files */\n    encoding?: string;\n    /** Logger for debugging */\n    logger?: Logger;\n}\n\n/**\n * Result of loading configurations from multiple directories.\n */\nexport interface HierarchicalConfigResult {\n    /** Merged configuration object with proper precedence */\n    config: object;\n    /** Array of directories where configuration was found */\n    discoveredDirs: DiscoveredConfigDir[];\n    /** Array of any errors encountered during loading (non-fatal) */\n    errors: string[];\n}\n\n/**\n * Discovers configuration directories by traversing up the directory tree.\n * \n * Starting from the specified directory (or current working directory),\n * this function searches for directories with the given name, continuing\n * up the directory tree until it reaches the filesystem root or the\n * maximum number of levels.\n * \n * @param options Configuration options for discovery\n * @returns Promise resolving to array of discovered configuration directories\n * \n * @example\n * ```typescript\n * const dirs = await discoverConfigDirectories({\n *   configDirName: '.kodrdriv',\n *   configFileName: 'config.yaml',\n *   maxLevels: 5\n * });\n * // Returns: [\n * //   { path: '/project/.kodrdriv', level: 0 },\n * //   { path: '/project/parent/.kodrdriv', level: 1 }\n * // ]\n * ```\n */\nexport async function discoverConfigDirectories(\n    options: HierarchicalDiscoveryOptions\n): Promise<DiscoveredConfigDir[]> {\n    const {\n        configDirName,\n        maxLevels = 10,\n        startingDir = process.cwd(),\n        logger\n    } = options;\n\n    const storage = createStorage({ log: logger?.debug || (() => { }) });\n    const discoveredDirs: DiscoveredConfigDir[] = [];\n\n    let currentDir = path.resolve(startingDir);\n    let level = 0;\n    const visited = new Set<string>(); // Prevent infinite loops with symlinks\n\n    logger?.debug(`Starting hierarchical discovery from: ${currentDir}`);\n\n    while (level < maxLevels) {\n        // Prevent infinite loops with symlinks\n        const realPath = path.resolve(currentDir);\n        if (visited.has(realPath)) {\n            logger?.debug(`Already visited ${realPath}, stopping discovery`);\n            break;\n        }\n        visited.add(realPath);\n\n        const configDirPath = path.join(currentDir, configDirName);\n        logger?.debug(`Checking for config directory: ${configDirPath}`);\n\n        try {\n            const exists = await storage.exists(configDirPath);\n            const isReadable = exists && await storage.isDirectoryReadable(configDirPath);\n\n            if (exists && isReadable) {\n                discoveredDirs.push({\n                    path: configDirPath,\n                    level\n                });\n                logger?.debug(`Found config directory at level ${level}: ${configDirPath}`);\n            } else if (exists && !isReadable) {\n                logger?.debug(`Config directory exists but is not readable: ${configDirPath}`);\n            }\n        } catch (error: any) {\n            logger?.debug(`Error checking config directory ${configDirPath}: ${error.message}`);\n        }\n\n        // Move up one directory level\n        const parentDir = path.dirname(currentDir);\n\n        // Check if we've reached the root directory\n        if (parentDir === currentDir) {\n            logger?.debug('Reached filesystem root, stopping discovery');\n            break;\n        }\n\n        currentDir = parentDir;\n        level++;\n    }\n\n    logger?.debug(`Discovery complete. Found ${discoveredDirs.length} config directories`);\n    return discoveredDirs;\n}\n\n/**\n * Loads and parses a configuration file from a directory.\n * \n * @param configDir Path to the configuration directory\n * @param configFileName Name of the configuration file\n * @param encoding File encoding\n * @param logger Optional logger\n * @returns Promise resolving to parsed configuration object or null if not found\n */\nexport async function loadConfigFromDirectory(\n    configDir: string,\n    configFileName: string,\n    encoding: string = 'utf8',\n    logger?: Logger\n): Promise<object | null> {\n    const storage = createStorage({ log: logger?.debug || (() => { }) });\n    const configFilePath = path.join(configDir, configFileName);\n\n    try {\n        logger?.debug(`Attempting to load config file: ${configFilePath}`);\n\n        const exists = await storage.exists(configFilePath);\n        if (!exists) {\n            logger?.debug(`Config file does not exist: ${configFilePath}`);\n            return null;\n        }\n\n        const isReadable = await storage.isFileReadable(configFilePath);\n        if (!isReadable) {\n            logger?.debug(`Config file exists but is not readable: ${configFilePath}`);\n            return null;\n        }\n\n        const yamlContent = await storage.readFile(configFilePath, encoding);\n        const parsedYaml = yaml.load(yamlContent);\n\n        if (parsedYaml !== null && typeof parsedYaml === 'object') {\n            logger?.debug(`Successfully loaded config from: ${configFilePath}`);\n            return parsedYaml as object;\n        } else {\n            logger?.debug(`Config file contains invalid format: ${configFilePath}`);\n            return null;\n        }\n    } catch (error: any) {\n        logger?.debug(`Error loading config from ${configFilePath}: ${error.message}`);\n        return null;\n    }\n}\n\n/**\n * Deep merges multiple configuration objects with proper precedence.\n * \n * Objects are merged from lowest precedence to highest precedence,\n * meaning that properties in later objects override properties in earlier objects.\n * Arrays are replaced entirely (not merged).\n * \n * @param configs Array of configuration objects, ordered from lowest to highest precedence\n * @returns Merged configuration object\n * \n * @example\n * ```typescript\n * const merged = deepMergeConfigs([\n *   { api: { timeout: 5000 }, debug: true },        // Lower precedence\n *   { api: { retries: 3 }, features: ['auth'] },    // Higher precedence\n * ]);\n * // Result: { api: { timeout: 5000, retries: 3 }, debug: true, features: ['auth'] }\n * ```\n */\nexport function deepMergeConfigs(configs: object[]): object {\n    if (configs.length === 0) {\n        return {};\n    }\n\n    if (configs.length === 1) {\n        return { ...configs[0] };\n    }\n\n    return configs.reduce((merged, current) => {\n        return deepMergeTwo(merged, current);\n    }, {});\n}\n\n/**\n * Deep merges two objects with proper precedence.\n * \n * @param target Target object (lower precedence)\n * @param source Source object (higher precedence)\n * @returns Merged object\n */\nfunction deepMergeTwo(target: any, source: any): any {\n    // Handle null/undefined\n    if (source == null) return target;\n    if (target == null) return source;\n\n    // Handle non-objects (primitives, arrays, functions, etc.)\n    if (typeof source !== 'object' || typeof target !== 'object') {\n        return source; // Source takes precedence\n    }\n\n    // Handle arrays - replace entirely, don't merge\n    if (Array.isArray(source)) {\n        return [...source];\n    }\n\n    if (Array.isArray(target)) {\n        return source; // Source object replaces target array\n    }\n\n    // Deep merge objects\n    const result = { ...target };\n\n    for (const key in source) {\n        if (Object.prototype.hasOwnProperty.call(source, key)) {\n            if (Object.prototype.hasOwnProperty.call(result, key) &&\n                typeof result[key] === 'object' &&\n                typeof source[key] === 'object' &&\n                !Array.isArray(source[key]) &&\n                !Array.isArray(result[key])) {\n                // Recursively merge nested objects\n                result[key] = deepMergeTwo(result[key], source[key]);\n            } else {\n                // Replace with source value (higher precedence)\n                result[key] = source[key];\n            }\n        }\n    }\n\n    return result;\n}\n\n/**\n * Loads configurations from multiple directories and merges them with proper precedence.\n * \n * This is the main function for hierarchical configuration loading. It:\n * 1. Discovers configuration directories up the directory tree\n * 2. Loads configuration files from each discovered directory\n * 3. Merges them with proper precedence (closer directories win)\n * 4. Returns the merged configuration with metadata\n * \n * @param options Configuration options for hierarchical loading\n * @returns Promise resolving to hierarchical configuration result\n * \n * @example\n * ```typescript\n * const result = await loadHierarchicalConfig({\n *   configDirName: '.kodrdriv',\n *   configFileName: 'config.yaml',\n *   startingDir: '/project/subdir',\n *   maxLevels: 5\n * });\n * \n * // result.config contains merged configuration\n * // result.discoveredDirs shows where configs were found\n * // result.errors contains any non-fatal errors\n * ```\n */\nexport async function loadHierarchicalConfig(\n    options: HierarchicalDiscoveryOptions\n): Promise<HierarchicalConfigResult> {\n    const { configFileName, encoding = 'utf8', logger } = options;\n\n    logger?.debug('Starting hierarchical configuration loading');\n\n    // Discover all configuration directories\n    const discoveredDirs = await discoverConfigDirectories(options);\n\n    if (discoveredDirs.length === 0) {\n        logger?.debug('No configuration directories found');\n        return {\n            config: {},\n            discoveredDirs: [],\n            errors: []\n        };\n    }\n\n    // Load configurations from each directory\n    const configs: object[] = [];\n    const errors: string[] = [];\n\n    // Sort by level (highest level first = lowest precedence first)\n    const sortedDirs = [...discoveredDirs].sort((a, b) => b.level - a.level);\n\n    for (const dir of sortedDirs) {\n        try {\n            const config = await loadConfigFromDirectory(\n                dir.path,\n                configFileName,\n                encoding,\n                logger\n            );\n\n            if (config !== null) {\n                configs.push(config);\n                logger?.debug(`Loaded config from level ${dir.level}: ${dir.path}`);\n            } else {\n                logger?.debug(`No valid config found at level ${dir.level}: ${dir.path}`);\n            }\n        } catch (error: any) {\n            const errorMsg = `Failed to load config from ${dir.path}: ${error.message}`;\n            errors.push(errorMsg);\n            logger?.debug(errorMsg);\n        }\n    }\n\n    // Merge all configurations with proper precedence\n    const mergedConfig = deepMergeConfigs(configs);\n\n    logger?.debug(`Hierarchical loading complete. Merged ${configs.length} configurations`);\n\n    return {\n        config: mergedConfig,\n        discoveredDirs,\n        errors\n    };\n} "],"names":["discoverConfigDirectories","options","configDirName","maxLevels","startingDir","process","cwd","logger","storage","createStorage","log","debug","discoveredDirs","currentDir","path","resolve","level","visited","Set","realPath","has","add","configDirPath","join","exists","isReadable","isDirectoryReadable","push","error","message","parentDir","dirname","length","loadConfigFromDirectory","configDir","configFileName","encoding","configFilePath","isFileReadable","yamlContent","readFile","parsedYaml","yaml","load","deepMergeConfigs","configs","reduce","merged","current","deepMergeTwo","target","source","Array","isArray","result","key","Object","prototype","hasOwnProperty","call","loadHierarchicalConfig","config","errors","sortedDirs","sort","a","b","dir","errorMsg","mergedConfig"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theunwalked/cardigantime",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "cardigantime is a tool to help you time your cardigans.",
   "type": "module",
   "main": "./dist/cardigantime.cjs",
@@ -46,9 +46,9 @@
     "@swc/core": "^1.12.7",
     "@types/js-yaml": "^4.0.9",
     "@types/luxon": "^3.6.2",
-    "@types/node": "^24.0.7",
-    "@typescript-eslint/eslint-plugin": "^8.35.0",
-    "@typescript-eslint/parser": "^8.35.0",
+    "@types/node": "^24.0.8",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
     "@vitest/coverage-v8": "^3.2.4",
     "eslint": "^9.30.0",
     "eslint-plugin-import": "^2.32.0",
@@ -67,6 +67,11 @@
     "test": "vitest run --coverage",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "docs:dev": "cd docs && cp ../README.md public/ && pnpm install && pnpm run dev",
+    "docs:build": "cd docs && cp ../README.md public/ && pnpm install && pnpm run build",
+    "docs:preview": "cd docs && pnpm run preview",
+    "docs:test": "cd docs && pnpm install && pnpm run test",
+    "docs:coverage": "cd docs && pnpm install && pnpm run coverage"
   }
 }