@utilarium/cardigantime 0.0.24-dev.0

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sources":["../src/types.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { ZodObject } from \"zod\";\n\nimport { z } from \"zod\";\nimport { SecurityValidationConfig } from \"./security/types\";\n\n// Re-export MCP types for convenience\nexport type {\n    MCPConfigSource,\n    FileConfigSource,\n    ConfigSource,\n    ResolvedConfig,\n    MCPInvocationContext,\n} from \"./mcp/types\";\n\n/**\n * Available features that can be enabled in Cardigantime.\n * Currently supports:\n * - 'config': Configuration file reading and validation\n * - 'hierarchical': Hierarchical configuration discovery and layering\n */\nexport type Feature = 'config' | 'hierarchical';\n\n/**\n * Supported configuration file formats.\n * \n * - 'yaml': YAML format (.yaml, .yml)\n * - 'json': JSON format (.json)\n * - 'javascript': JavaScript module (.js, .mjs, .cjs)\n * - 'typescript': TypeScript module (.ts, .mts, .cts)\n */\nexport enum ConfigFormat {\n    YAML = 'yaml',\n    JSON = 'json',\n    JavaScript = 'javascript',\n    TypeScript = 'typescript'\n}\n\n/**\n * Interface for format-specific configuration parsers.\n * Each parser is responsible for loading and parsing configuration from a specific format.\n * \n * @template T - The type of the parsed configuration object\n */\nexport interface ConfigParser<T = unknown> {\n    /** The format this parser handles */\n    format: ConfigFormat;\n    /** File extensions this parser supports (e.g., ['.yaml', '.yml']) */\n    extensions: string[];\n    /** \n     * Parses configuration content from a file.\n     * \n     * @param content - The raw file content as a string\n     * @param filePath - The absolute path to the configuration file\n     * @returns Promise resolving to the parsed configuration object\n     * @throws {Error} When parsing fails or content is invalid\n     */\n    parse(content: string, filePath: string): Promise<T>;\n}\n\n/**\n * Metadata about where a configuration value came from.\n * Used for tracking configuration sources and debugging.\n * \n * @deprecated Use FileConfigSource from ./mcp/types instead.\n * This type is kept for backward compatibility and will be removed in a future version.\n */\nexport interface LegacyConfigSource {\n    /** The format of the configuration file */\n    format: ConfigFormat;\n    /** Absolute path to the configuration file */\n    filePath: string;\n    /** The parsed configuration content */\n    content: unknown;\n    /** Timestamp when the configuration was loaded */\n    loadedAt: Date;\n}\n\n/**\n * Defines how array fields should be merged in hierarchical configurations.\n * \n * - 'override': Higher precedence arrays completely replace lower precedence arrays (default)\n * - 'append': Higher precedence array elements are appended to lower precedence arrays\n * - 'prepend': Higher precedence array elements are prepended to lower precedence arrays\n */\nexport type ArrayOverlapMode = 'override' | 'append' | 'prepend';\n\n/**\n * Configuration for how fields should be merged in hierarchical configurations.\n * Maps field names (using dot notation) to their overlap behavior.\n * \n * @example\n * ```typescript\n * const fieldOverlaps: FieldOverlapOptions = {\n *   'features': 'append',           // features arrays will be combined by appending\n *   'api.endpoints': 'prepend',     // nested endpoint arrays will be combined by prepending\n *   'excludePatterns': 'override'   // excludePatterns arrays will replace each other (default behavior)\n * };\n * ```\n */\nexport interface FieldOverlapOptions {\n    [fieldPath: string]: ArrayOverlapMode;\n}\n\n/**\n * Configuration for resolving relative paths in configuration values.\n * Paths specified in these fields will be resolved relative to the configuration file's directory.\n */\nexport interface PathResolutionOptions {\n    /** Array of field names (using dot notation) that contain paths to be resolved */\n    pathFields?: string[];\n    /** Array of field names whose array elements should all be resolved as paths */\n    resolvePathArray?: string[];\n}\n\n/**\n * Default configuration options for Cardigantime.\n * These define the basic behavior of configuration loading.\n */\nexport interface DefaultOptions {\n    /** Directory path where configuration files are located */\n    configDirectory: string;\n    /** Name of the configuration file (e.g., 'config.yaml', 'app.yml') */\n    configFile: string;\n    /** Whether the configuration directory must exist. If true, throws error if directory doesn't exist */\n    isRequired: boolean;\n    /** File encoding for reading configuration files (e.g., 'utf8', 'ascii') */\n    encoding: string;\n    /** Configuration for resolving relative paths in configuration values */\n    pathResolution?: PathResolutionOptions;\n    /** \n     * Configuration for how array fields should be merged in hierarchical mode.\n     * Only applies when the 'hierarchical' feature is enabled.\n     * If not specified, all arrays use 'override' behavior (default).\n     */\n    fieldOverlaps?: FieldOverlapOptions;\n    /** \n     * Security validation configuration (optional, uses development profile by default).\n     * Enable security features to validate CLI arguments and config file values.\n     */\n    security?: Partial<SecurityValidationConfig>;\n    /**\n     * Optional source metadata for tracking where configuration came from.\n     * Populated automatically when configuration is loaded.\n     * \n     * @deprecated Use the new ConfigSource union type from ./mcp/types instead.\n     */\n    source?: LegacyConfigSource;\n    /**\n     * Allow executable configuration files (JavaScript/TypeScript).\n     * \n     * **SECURITY WARNING**: Executable configs run with full Node.js permissions\n     * in the same process as your application. Only enable this if you trust\n     * the configuration files being loaded.\n     * \n     * When disabled (default), JavaScript and TypeScript config files will be\n     * ignored with a warning message.\n     * \n     * @default false\n     */\n    allowExecutableConfig?: boolean;\n}\n\n/**\n * Complete options object passed to Cardigantime functions.\n * Combines defaults, features, schema shape, and logger.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Options<T extends z.ZodRawShape> {\n    /** Default configuration options */\n    defaults: DefaultOptions,\n    /** Array of enabled features */\n    features: Feature[],\n    /** Zod schema shape for validating user configuration */\n    configShape: T;\n    /** Logger instance for debugging and error reporting */\n    logger: Logger;\n}\n\n/**\n * Logger interface for Cardigantime's internal logging.\n * Compatible with popular logging libraries like Winston, Bunyan, etc.\n */\nexport interface Logger {\n    /** Debug-level logging for detailed troubleshooting information */\n    debug: (message: string, ...args: any[]) => void;\n    /** Info-level logging for general information */\n    info: (message: string, ...args: any[]) => void;\n    /** Warning-level logging for non-critical issues */\n    warn: (message: string, ...args: any[]) => void;\n    /** Error-level logging for critical problems */\n    error: (message: string, ...args: any[]) => void;\n    /** Verbose-level logging for extensive detail */\n    verbose: (message: string, ...args: any[]) => void;\n    /** Silly-level logging for maximum detail */\n    silly: (message: string, ...args: any[]) => void;\n}\n\n/**\n * Main Cardigantime interface providing configuration management functionality.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Cardigantime<T extends z.ZodRawShape> {\n    /** \n     * Adds Cardigantime's CLI options to a Commander.js command.\n     * This includes options like --config-directory for runtime config path overrides.\n     */\n    configure: (command: Command) => Promise<Command>;\n    /** Sets a custom logger for debugging and error reporting */\n    setLogger: (logger: Logger) => void;\n    /** \n     * Reads configuration from files and merges with CLI arguments.\n     * Returns a fully typed configuration object.\n     */\n    read: (args: Args) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;\n    /** \n     * Validates the merged configuration against the Zod schema.\n     * Throws ConfigurationError if validation fails.\n     */\n    validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => Promise<void>;\n    /** \n     * Generates a configuration file with default values in the specified directory.\n     * Creates the directory if it doesn't exist and writes a config file with all default values populated.\n     */\n    generateConfig: (configDirectory?: string) => Promise<void>;\n    /** \n     * Checks and displays the resolved configuration with detailed source tracking.\n     * Shows which file and hierarchical level contributed each configuration value in a git blame-like format.\n     */\n    checkConfig: (args: Args) => Promise<void>;\n}\n\n/**\n * Parsed command-line arguments object, typically from Commander.js opts().\n * Keys correspond to CLI option names with values from user input.\n */\nexport interface Args {\n    [key: string]: any;\n}\n\n/**\n * Base Zod schema for core Cardigantime configuration.\n * Contains the minimum required configuration fields.\n */\nexport const ConfigSchema = z.object({\n    /** The resolved configuration directory path */\n    configDirectory: z.string(),\n    /** Array of all directory paths that were discovered during hierarchical search */\n    discoveredConfigDirs: z.array(z.string()),\n    /** Array of directory paths that actually contained valid configuration files */\n    resolvedConfigDirs: z.array(z.string()),\n});\n\n/**\n * Base configuration type derived from the core schema.\n */\nexport type Config = z.infer<typeof ConfigSchema>;\n\n// ============================================================================\n// Configuration Discovery Types\n// ============================================================================\n\n/**\n * Defines a configuration file naming pattern.\n * Used to discover configuration files in various standard locations.\n * \n * Patterns support placeholders:\n * - `{app}` - The application name (e.g., 'protokoll', 'myapp')\n * - `{ext}` - The file extension (e.g., 'yaml', 'json', 'ts')\n * \n * @example\n * ```typescript\n * // Pattern: \"{app}.config.{ext}\" with app=\"myapp\" and ext=\"yaml\"\n * // Results in: \"myapp.config.yaml\"\n * \n * const pattern: ConfigNamingPattern = {\n *   pattern: '{app}.config.{ext}',\n *   priority: 1,\n *   hidden: false\n * };\n * ```\n */\nexport interface ConfigNamingPattern {\n    /**\n     * Pattern template with `{app}` and `{ext}` placeholders.\n     * \n     * Examples:\n     * - `\"{app}.config.{ext}\"` → `\"protokoll.config.yaml\"`\n     * - `\".{app}/config.{ext}\"` → `\".protokoll/config.yaml\"`\n     * - `\".{app}rc.{ext}\"` → `\".protokollrc.json\"`\n     * - `\".{app}rc\"` → `\".protokollrc\"` (no extension)\n     */\n    pattern: string;\n\n    /**\n     * Search priority (lower number = checked first).\n     * When multiple config files exist, lower priority patterns take precedence.\n     */\n    priority: number;\n\n    /**\n     * Whether this pattern results in a hidden file or directory.\n     * Hidden patterns start with a dot (e.g., `.myapp/`, `.myapprc`).\n     */\n    hidden: boolean;\n}\n\n/**\n * Options for configuring how configuration files are discovered.\n * \n * @example\n * ```typescript\n * const options: ConfigDiscoveryOptions = {\n *   appName: 'myapp',\n *   extensions: ['yaml', 'yml', 'json'],\n *   searchHidden: true,\n *   // Use custom patterns instead of defaults\n *   patterns: [\n *     { pattern: '{app}.config.{ext}', priority: 1, hidden: false }\n *   ]\n * };\n * ```\n */\nexport interface ConfigDiscoveryOptions {\n    /**\n     * The application name used in pattern expansion.\n     * This value replaces `{app}` placeholders in naming patterns.\n     */\n    appName: string;\n\n    /**\n     * Custom naming patterns to use for discovery.\n     * If not provided, uses the standard patterns defined in STANDARD_PATTERNS.\n     */\n    patterns?: ConfigNamingPattern[];\n\n    /**\n     * File extensions to search for.\n     * These replace the `{ext}` placeholder in patterns.\n     * If not provided, defaults to supported format extensions.\n     * \n     * @example ['yaml', 'yml', 'json', 'js', 'ts']\n     */\n    extensions?: string[];\n\n    /**\n     * Whether to search for hidden files and directories.\n     * When false, patterns with `hidden: true` are skipped.\n     * \n     * @default true\n     */\n    searchHidden?: boolean;\n\n    /**\n     * Whether to check for multiple config files and emit a warning.\n     * When enabled, discovery continues after finding the first match\n     * to detect and warn about additional config files that would be ignored.\n     * \n     * @default true\n     */\n    warnOnMultipleConfigs?: boolean;\n}\n\n/**\n * Result of discovering a configuration file.\n * Contains the file path and the pattern that matched.\n */\nexport interface DiscoveredConfig {\n    /**\n     * The resolved file path to the configuration file.\n     * Can be a file path (e.g., 'app.config.yaml') or include\n     * a directory (e.g., '.app/config.yaml').\n     */\n    path: string;\n\n    /**\n     * The absolute path to the configuration file.\n     */\n    absolutePath: string;\n\n    /**\n     * The pattern that matched this configuration file.\n     */\n    pattern: ConfigNamingPattern;\n}\n\n/**\n * Warning information when multiple config files are found.\n * This helps users identify and remove unused config files.\n */\nexport interface MultipleConfigWarning {\n    /**\n     * The configuration that will be used (highest priority).\n     */\n    used: DiscoveredConfig;\n\n    /**\n     * Configurations that were found but will be ignored.\n     */\n    ignored: DiscoveredConfig[];\n}\n\n/**\n * Full result of configuration discovery, including warnings.\n */\nexport interface DiscoveryResult {\n    /**\n     * The discovered configuration file, or null if none found.\n     */\n    config: DiscoveredConfig | null;\n\n    /**\n     * Warning about multiple config files, if any were found.\n     */\n    multipleConfigWarning?: MultipleConfigWarning;\n}\n\n// ============================================================================\n// Hierarchical Configuration Types\n// ============================================================================\n\n/**\n * Controls how hierarchical configuration lookup behaves.\n * \n * - `'enabled'` - Walk up the directory tree and merge configs (default behavior).\n *   Configurations from parent directories are merged with child configurations,\n *   with child values taking precedence.\n * \n * - `'disabled'` - Use only the config found in the starting directory.\n *   No parent directory traversal occurs. Useful for isolated projects or\n *   MCP configurations that should be self-contained.\n * \n * - `'root-only'` - Walk up to find the first config, but don't merge with others.\n *   This mode finds the \"closest\" config file without merging parent configs.\n *   Useful when you want automatic config discovery but not inheritance.\n * \n * - `'explicit'` - Only merge configs that are explicitly referenced.\n *   The base config can specify which parent configs to extend via an\n *   `extends` field. No automatic directory traversal.\n * \n * @example\n * ```typescript\n * // In a child config that wants to be isolated:\n * // protokoll.config.yaml\n * hierarchical:\n *   mode: disabled\n * \n * // This config will NOT inherit from parent directories\n * ```\n */\nexport type HierarchicalMode = 'enabled' | 'disabled' | 'root-only' | 'explicit';\n\n/**\n * Files or directories that indicate a project root.\n * When encountered during directory traversal, hierarchical lookup stops.\n * \n * @example\n * ```typescript\n * const markers: RootMarker[] = [\n *   { type: 'file', name: 'package.json' },\n *   { type: 'directory', name: '.git' },\n *   { type: 'file', name: 'pnpm-workspace.yaml' },\n * ];\n * ```\n */\nexport interface RootMarker {\n    /** Type of the marker */\n    type: 'file' | 'directory';\n    /** Name of the file or directory that indicates a root */\n    name: string;\n}\n\n/**\n * Default root markers used when none are specified.\n * These indicate common project root boundaries.\n */\nexport const DEFAULT_ROOT_MARKERS: RootMarker[] = [\n    { type: 'file', name: 'package.json' },\n    { type: 'directory', name: '.git' },\n    { type: 'file', name: 'pnpm-workspace.yaml' },\n    { type: 'file', name: 'lerna.json' },\n    { type: 'file', name: 'nx.json' },\n    { type: 'file', name: 'rush.json' },\n];\n\n/**\n * Configuration options for hierarchical config behavior.\n * Can be set in the configuration file or programmatically.\n * \n * @example\n * ```typescript\n * // Configuration file (protokoll.config.yaml):\n * hierarchical:\n *   mode: enabled\n *   maxDepth: 5\n *   stopAt:\n *     - node_modules\n *     - vendor\n *   rootMarkers:\n *     - type: file\n *       name: package.json\n * ```\n * \n * @example\n * ```typescript\n * // Programmatic configuration:\n * const options: HierarchicalOptions = {\n *   mode: 'disabled',  // No parent config merging\n * };\n * \n * // For MCP servers:\n * const mcpOptions: HierarchicalOptions = {\n *   mode: 'root-only',\n *   rootMarkers: [{ type: 'file', name: 'mcp.json' }],\n * };\n * ```\n */\nexport interface HierarchicalOptions {\n    /**\n     * The hierarchical lookup mode.\n     * Controls whether and how parent directories are searched.\n     * \n     * @default 'enabled'\n     */\n    mode?: HierarchicalMode;\n\n    /**\n     * Maximum number of parent directories to traverse.\n     * Prevents unbounded traversal in deep directory structures.\n     * \n     * @default 10\n     */\n    maxDepth?: number;\n\n    /**\n     * Directory names where traversal should stop.\n     * When a directory with one of these names is encountered as a parent,\n     * traversal stops even if no config was found.\n     * \n     * @example ['node_modules', 'vendor', '.cache']\n     */\n    stopAt?: string[];\n\n    /**\n     * Files or directories that indicate a project root.\n     * When a directory contains one of these markers, it's treated as a root\n     * and traversal stops after processing that directory.\n     * \n     * If not specified, uses DEFAULT_ROOT_MARKERS.\n     * Set to empty array to disable root marker detection.\n     */\n    rootMarkers?: RootMarker[];\n\n    /**\n     * Whether to stop at the first root marker found.\n     * When true, traversal stops immediately when a root marker is found.\n     * When false, the directory with the root marker is included but no further.\n     * \n     * @default true\n     */\n    stopAtRoot?: boolean;\n}\n\n// ============================================================================\n// Directory Traversal Security Types\n// ============================================================================\n\n/**\n * Defines security boundaries for directory traversal.\n * Used to prevent configuration lookup from accessing sensitive directories.\n * \n * @example\n * ```typescript\n * const boundaries: TraversalBoundary = {\n *   forbidden: ['/etc', '/usr', '/var'],\n *   boundaries: [process.env.HOME ?? '/home'],\n *   maxAbsoluteDepth: 20,\n *   maxRelativeDepth: 10,\n * };\n * ```\n */\nexport interface TraversalBoundary {\n    /**\n     * Directories that are never allowed to be accessed.\n     * Traversal is blocked if the path is at or within these directories.\n     * Paths can include environment variable placeholders like `$HOME`.\n     * \n     * @example ['/etc', '/usr', '/var', '/sys', '/proc', '$HOME/.ssh']\n     */\n    forbidden: string[];\n\n    /**\n     * Soft boundary directories - traversal stops at these unless explicitly allowed.\n     * These represent natural project boundaries.\n     * Paths can include environment variable placeholders like `$HOME`.\n     * \n     * @example ['$HOME', '/tmp', '/private/tmp']\n     */\n    boundaries: string[];\n\n    /**\n     * Maximum absolute depth from the filesystem root.\n     * Prevents extremely deep traversal regardless of starting point.\n     * Depth is counted as the number of path segments from root.\n     * \n     * @example 20 means paths like /a/b/c/.../t (20 levels deep) are allowed\n     * @default 20\n     */\n    maxAbsoluteDepth: number;\n\n    /**\n     * Maximum relative depth from the starting directory.\n     * Limits how far up the directory tree traversal can go.\n     * \n     * @example 10 means traversal can go up 10 directories from the start\n     * @default 10\n     */\n    maxRelativeDepth: number;\n}\n\n/**\n * Result of a traversal boundary check.\n */\nexport interface TraversalCheckResult {\n    /** Whether the path is allowed */\n    allowed: boolean;\n    \n    /** Reason for blocking (if not allowed) */\n    reason?: string;\n    \n    /** The boundary that was violated (if any) */\n    violatedBoundary?: string;\n}\n\n/**\n * Options for configuring traversal security behavior.\n */\nexport interface TraversalSecurityOptions {\n    /**\n     * Custom traversal boundaries to use instead of defaults.\n     */\n    boundaries?: Partial<TraversalBoundary>;\n\n    /**\n     * Allow traversal beyond safe boundaries.\n     * \n     * **SECURITY WARNING**: Setting this to true bypasses security checks\n     * and allows traversal into sensitive directories. Only use this in\n     * trusted scenarios where you control all configuration files.\n     * \n     * @default false\n     */\n    allowUnsafeTraversal?: boolean;\n\n    /**\n     * Whether to log warnings when boundaries are overridden.\n     * \n     * @default true\n     */\n    warnOnOverride?: boolean;\n}\n"],"names":["ConfigFormat","ConfigSchema","z","object","configDirectory","string","discoveredConfigDirs","array","resolvedConfigDirs","DEFAULT_ROOT_MARKERS","type","name"],"mappings":";;AAuBA;;;;;;;IAQO,IAAKA,YAAAA,iBAAAA,SAAAA,YAAAA,EAAAA;;;;;AAAAA,IAAAA,OAAAA,YAAAA;AAKX,CAAA,CAAA,EAAA;AA8MD;;;AAGC,IACM,MAAMC,YAAAA,GAAeC,CAAAA,CAAEC,MAAM,CAAC;qDAEjCC,eAAAA,EAAiBF,CAAAA,CAAEG,MAAM,EAAA;AACzB,wFACAC,oBAAAA,EAAsBJ,CAAAA,CAAEK,KAAK,CAACL,EAAEG,MAAM,EAAA,CAAA;AACtC,sFACAG,kBAAAA,EAAoBN,CAAAA,CAAEK,KAAK,CAACL,EAAEG,MAAM,EAAA;AACxC,CAAA;AA6NA;;;UAIaI,oBAAAA,GAAqC;AAC9C,IAAA;QAAEC,IAAAA,EAAM,MAAA;QAAQC,IAAAA,EAAM;AAAe,KAAA;AACrC,IAAA;QAAED,IAAAA,EAAM,WAAA;QAAaC,IAAAA,EAAM;AAAO,KAAA;AAClC,IAAA;QAAED,IAAAA,EAAM,MAAA;QAAQC,IAAAA,EAAM;AAAsB,KAAA;AAC5C,IAAA;QAAED,IAAAA,EAAM,MAAA;QAAQC,IAAAA,EAAM;AAAa,KAAA;AACnC,IAAA;QAAED,IAAAA,EAAM,MAAA;QAAQC,IAAAA,EAAM;AAAU,KAAA;AAChC,IAAA;QAAED,IAAAA,EAAM,MAAA;QAAQC,IAAAA,EAAM;AAAY;;;;;"}

package/dist/util/hierarchical.d.ts

@@ -0,0 +1,136 @@
+import { Logger, FieldOverlapOptions } 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;
+    /** Array of field names that contain paths to be resolved */
+    pathFields?: string[];
+    /** Array of field names whose array elements should all be resolved as paths */
+    resolvePathArray?: string[];
+    /** Configuration for how array fields should be merged in hierarchical mode */
+    fieldOverlaps?: FieldOverlapOptions;
+}
+/**
+ * Result of loading configurations from multiple directories.
+ */
+export interface HierarchicalConfigResult {
+    /** Merged configuration object with proper precedence */
+    config: object;
+    /** Array of directories where configuration was found */
+    discoveredDirs: DiscoveredConfigDir[];
+    /** Array of directories that actually contained valid configuration files */
+    resolvedConfigDirs: 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
+ * @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
+ */
+export declare function loadConfigFromDirectory(configDir: string, configFileName: string, encoding?: string, logger?: Logger, pathFields?: string[], resolvePathArray?: string[]): Promise<object | null>;
+/**
+ * Deep merges multiple configuration objects with proper precedence 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 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 }, features: ['auth'] },        // Lower precedence
+ *   { api: { retries: 3 }, features: ['analytics'] },      // Higher precedence
+ * ], {
+ *   'features': 'append'  // Results in features: ['auth', 'analytics']
+ * });
+ * ```
+ */
+export declare function deepMergeConfigs(configs: object[], fieldOverlaps?: FieldOverlapOptions): 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,
+ *   fieldOverlaps: {
+ *     'features': 'append',
+ *     'excludePatterns': 'prepend'
+ *   }
+ * });
+ *
+ * // result.config contains merged configuration with custom array merging
+ * // 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,436 @@
+import * as path from 'node:path';
+import * as yaml from 'js-yaml';
+import { create } from './storage.js';
+
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ */ 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 isUnsafeKey(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}
+function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    // Prevent prototype pollution via special property names
+    if (isUnsafeKey(lastKey) || keys.some(isUnsafeKey)) {
+        return;
+    }
+    const target = keys.reduce((current, key)=>{
+        // Skip if this is an unsafe key (already checked above, but defensive)
+        if (isUnsafeKey(key)) {
+            return current;
+        }
+        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.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path.resolve(configDir, pathStr);
+}
+/**
+ * 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.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.verbose(`Discovery complete. Found ${discoveredDirs.length} config directories`);
+    return discoveredDirs;
+}
+/**
+ * Tries to find a config file with alternative extensions (.yaml or .yml).
+ * 
+ * @param storage Storage instance to use for file operations
+ * @param configDir The directory containing the config file
+ * @param configFileName The base config file name (may have .yaml or .yml extension)
+ * @param logger Optional logger for debugging
+ * @returns Promise resolving to the found config file path or null if not found
+ */ async function findConfigFileWithExtension(storage, configDir, configFileName, logger) {
+    const configFilePath = path.join(configDir, configFileName);
+    // First try the exact filename as specified
+    const exists = await storage.exists(configFilePath);
+    if (exists) {
+        const isReadable = await storage.isFileReadable(configFilePath);
+        if (isReadable) {
+            return configFilePath;
+        }
+    }
+    // If the exact filename doesn't exist or isn't readable, try alternative extensions
+    // Only do this if the filename has a .yaml or .yml extension
+    const ext = path.extname(configFileName);
+    if (ext === '.yaml' || ext === '.yml') {
+        const baseName = path.basename(configFileName, ext);
+        const alternativeExt = ext === '.yaml' ? '.yml' : '.yaml';
+        const alternativePath = path.join(configDir, baseName + alternativeExt);
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Config file not found at ${configFilePath}, trying alternative: ${alternativePath}`);
+        const altExists = await storage.exists(alternativePath);
+        if (altExists) {
+            const altIsReadable = await storage.isFileReadable(alternativePath);
+            if (altIsReadable) {
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Found config file with alternative extension: ${alternativePath}`);
+                return alternativePath;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * 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
+ * @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, pathFields, resolvePathArray) {
+    const storage = create({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    try {
+        logger === null || logger === void 0 ? void 0 : logger.verbose(`Attempting to load config file: ${path.join(configDir, configFileName)}`);
+        // Try to find the config file with alternative extensions
+        const configFilePath = await findConfigFileWithExtension(storage, configDir, configFileName, logger);
+        if (!configFilePath) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file does not exist: ${path.join(configDir, configFileName)}`);
+            return null;
+        }
+        const yamlContent = await storage.readFile(configFilePath, encoding);
+        const parsedYaml = yaml.load(yamlContent);
+        if (parsedYaml !== null && typeof parsedYaml === 'object') {
+            let config = parsedYaml;
+            // Apply path resolution if configured
+            if (pathFields && pathFields.length > 0) {
+                config = resolveConfigPaths(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;
+        }
+    } catch (error) {
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Error loading config from ${path.join(configDir, configFileName)}: ${error.message}`);
+        return null;
+    }
+}
+/**
+ * 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 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 }, features: ['auth'] },        // Lower precedence
+ *   { api: { retries: 3 }, features: ['analytics'] },      // Higher precedence
+ * ], {
+ *   'features': 'append'  // Results in features: ['auth', 'analytics']
+ * });
+ * ```
+ */ function deepMergeConfigs(configs, fieldOverlaps) {
+    if (configs.length === 0) {
+        return {};
+    }
+    if (configs.length === 1) {
+        return {
+            ...configs[0]
+        };
+    }
+    return configs.reduce((merged, current)=>{
+        return deepMergeTwo(merged, current, fieldOverlaps);
+    }, {});
+}
+/**
+ * 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, fieldOverlaps, currentPath = '') {
+    // 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 with configurable overlap behavior
+    if (Array.isArray(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
+    }
+    // Deep merge objects
+    const result = {
+        ...target
+    };
+    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], fieldOverlaps, fieldPath);
+            } else {
+                // 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.
+ * 
+ * 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,
+ *   fieldOverlaps: {
+ *     'features': 'append',
+ *     'excludePatterns': 'prepend'
+ *   }
+ * });
+ * 
+ * // 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, fieldOverlaps } = 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.verbose('No configuration directories found');
+        return {
+            config: {},
+            discoveredDirs: [],
+            resolvedConfigDirs: [],
+            errors: []
+        };
+    }
+    // Load configurations from each directory
+    const configs = [];
+    const resolvedConfigDirs = [];
+    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, pathFields, resolvePathArray);
+            if (config !== null) {
+                configs.push(config);
+                resolvedConfigDirs.push(dir);
+                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 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,
+        discoveredDirs,
+        resolvedConfigDirs,
+        errors
+    };
+}
+
+export { deepMergeConfigs, discoverConfigDirectories, loadConfigFromDirectory, loadHierarchicalConfig };
+//# sourceMappingURL=hierarchical.js.map