@theunwalked/cardigantime 0.0.9 → 0.0.10

package/dist/cardigantime.js

@@ -1,11 +1,15 @@
 import { configure } from './configure.js';
 import { DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS } from './constants.js';
-import { read } from './read.js';
+import { checkConfig, read } from './read.js';
 import { validate } from './validate.js';
+import * as yaml from 'js-yaml';
+import * as path from 'path';
+import { generateDefaultConfig } from './util/schema-defaults.js';
+import { create as create$1 } from './util/storage.js';
+import { FileSystemError } from './error/FileSystemError.js';
 export { ConfigSchema } from './types.js';
 export { ArgumentError } from './error/ArgumentError.js';
 export { ConfigurationError } from './error/ConfigurationError.js';
-export { FileSystemError } from './error/FileSystemError.js';
 
 /**
  * Creates a new Cardigantime instance for configuration management.
@@ -82,13 +86,78 @@ export { FileSystemError } from './error/FileSystemError.js';
         logger = pLogger;
         options.logger = pLogger;
     };
+    const generateConfig = async (configDirectory)=>{
+        const targetDir = configDirectory || options.defaults.configDirectory;
+        const configFile = options.defaults.configFile;
+        const encoding = options.defaults.encoding;
+        logger.verbose(`Generating configuration file in: ${targetDir}`);
+        // Create storage utility
+        const storage = create$1({
+            log: logger.debug
+        });
+        // Ensure the target directory exists
+        const dirExists = await storage.exists(targetDir);
+        if (!dirExists) {
+            logger.info(`Creating configuration directory: ${targetDir}`);
+            try {
+                await storage.createDirectory(targetDir);
+            } catch (error) {
+                throw FileSystemError.directoryCreationFailed(targetDir, error);
+            }
+        }
+        // Check if directory is writable
+        const isWritable = await storage.isDirectoryWritable(targetDir);
+        if (!isWritable) {
+            throw new FileSystemError('not_writable', 'Configuration directory is not writable', targetDir, 'directory_write');
+        }
+        // Build the full config file path
+        const configFilePath = path.join(targetDir, configFile);
+        // Generate default configuration
+        const defaultConfig = generateDefaultConfig(options.configShape);
+        // Convert to YAML with nice formatting
+        const yamlContent = yaml.dump(defaultConfig, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+            sortKeys: true
+        });
+        // Add header comment to the YAML file
+        const header = `# Configuration file generated by Cardigantime
+# This file contains default values for your application configuration.
+# Modify the values below to customize your application's behavior.
+#
+# For more information about Cardigantime configuration:
+# https://github.com/SemicolonAmbulance/cardigantime
+
+`;
+        const finalContent = header + yamlContent;
+        // Check if config file already exists
+        const configExists = await storage.exists(configFilePath);
+        if (configExists) {
+            logger.warn(`Configuration file already exists: ${configFilePath}`);
+            logger.warn('This file was not overwritten, but here is what the default configuration looks like if you want to copy it:');
+            logger.info('\n' + '='.repeat(60));
+            logger.info(finalContent.trim());
+            logger.info('='.repeat(60));
+            return;
+        }
+        // Write the configuration file
+        try {
+            await storage.writeFile(configFilePath, finalContent, encoding);
+            logger.info(`Configuration file generated successfully: ${configFilePath}`);
+        } catch (error) {
+            throw FileSystemError.operationFailed('write configuration file', configFilePath, error);
+        }
+    };
     return {
         setLogger,
         configure: (command)=>configure(command, options),
         validate: (config)=>validate(config, options),
-        read: (args)=>read(args, options)
+        read: (args)=>read(args, options),
+        generateConfig,
+        checkConfig: (args)=>checkConfig(args, options)
     };
 };
 
-export { create };
+export { FileSystemError, create };
 //# sourceMappingURL=cardigantime.js.map

package/dist/cardigantime.js.map

@@ -1 +1 @@
-{"version":3,"file":"cardigantime.js","sources":["../src/cardigantime.ts"],"sourcesContent":["import { Command } from 'commander';\nimport { Args, DefaultOptions, Feature, Cardigantime, Logger, Options } from 'types';\nimport { z, ZodObject } from 'zod';\nimport { configure } from './configure';\nimport { DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS } from './constants';\nimport { read } from './read';\nimport { ConfigSchema } from 'types';\nimport { validate } from './validate';\n\nexport * from './types';\nexport { ArgumentError, ConfigurationError, FileSystemError } from './validate';\n\n/**\n * Creates a new Cardigantime instance for configuration management.\n * \n * Cardigantime handles the complete configuration lifecycle including:\n * - Reading configuration from YAML files\n * - Validating configuration against Zod schemas\n * - Merging CLI arguments with file configuration and defaults\n * - Providing type-safe configuration objects\n * \n * @template T - The Zod schema shape type for your configuration\n * @param pOptions - Configuration options for the Cardigantime instance\n * @param pOptions.defaults - Default configuration settings\n * @param pOptions.defaults.configDirectory - Directory to search for configuration files (required)\n * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')\n * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)\n * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')\n * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)\n * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])\n * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)\n * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)\n * @returns A Cardigantime instance with methods for configure, read, validate, and setLogger\n * \n * @example\n * ```typescript\n * import { create } from '@theunwalked/cardigantime';\n * import { z } from 'zod';\n * \n * const MyConfigSchema = z.object({\n *   apiKey: z.string().min(1),\n *   timeout: z.number().default(5000),\n *   debug: z.boolean().default(false),\n *   contextDirectories: z.array(z.string()).optional(),\n * });\n * \n * const cardigantime = create({\n *   defaults: {\n *     configDirectory: './config',\n *     configFile: 'myapp.yaml',\n *     // Resolve relative paths in contextDirectories relative to config file location\n *     pathResolution: {\n *       pathFields: ['contextDirectories'],\n *       resolvePathArray: ['contextDirectories']\n *     },\n *     // Configure how array fields are merged in hierarchical mode\n *     fieldOverlaps: {\n *       'features': 'append',              // Accumulate features from all levels\n *       'excludePatterns': 'prepend'       // Higher precedence patterns come first\n *     }\n *   },\n *   configShape: MyConfigSchema.shape,\n *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery\n * });\n * \n * // If config file is at ../config/myapp.yaml and contains:\n * // contextDirectories: ['./context', './data']\n * // These paths will be resolved relative to ../config/ directory\n * ```\n */\nexport const create = <T extends z.ZodRawShape>(pOptions: {\n    defaults: Pick<DefaultOptions, 'configDirectory'> & Partial<Omit<DefaultOptions, 'configDirectory'>>,\n    features?: Feature[],\n    configShape: T, // Make configShape mandatory\n    logger?: Logger,\n}): Cardigantime<T> => {\n\n\n    const defaults: DefaultOptions = { ...DEFAULT_OPTIONS, ...pOptions.defaults } as DefaultOptions;\n    const features = pOptions.features || DEFAULT_FEATURES;\n    const configShape = pOptions.configShape;\n    let logger = pOptions.logger || DEFAULT_LOGGER;\n\n    const options: Options<T> = {\n        defaults,\n        features,\n        configShape, // Store the shape\n        logger,\n    }\n\n    const setLogger = (pLogger: Logger) => {\n        logger = pLogger;\n        options.logger = pLogger;\n    }\n\n    return {\n        setLogger,\n        configure: (command: Command) => configure(command, options),\n        validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => validate(config, options),\n        read: (args: Args) => read(args, options),\n    }\n}\n\n\n\n\n\n"],"names":["create","pOptions","defaults","DEFAULT_OPTIONS","features","DEFAULT_FEATURES","configShape","logger","DEFAULT_LOGGER","options","setLogger","pLogger","configure","command","validate","config","read","args"],"mappings":";;;;;;;;;AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0DO,MAAMA,MAAAA,GAAS,CAA0BC,QAAAA,GAAAA;AAQ5C,IAAA,MAAMC,QAAAA,GAA2B;AAAE,QAAA,GAAGC,eAAe;AAAE,QAAA,GAAGF,SAASC;AAAS,KAAA;IAC5E,MAAME,QAAAA,GAAWH,QAAAA,CAASG,QAAQ,IAAIC,gBAAAA;IACtC,MAAMC,WAAAA,GAAcL,SAASK,WAAW;IACxC,IAAIC,MAAAA,GAASN,QAAAA,CAASM,MAAM,IAAIC,cAAAA;AAEhC,IAAA,MAAMC,OAAAA,GAAsB;AACxBP,QAAAA,QAAAA;AACAE,QAAAA,QAAAA;AACAE,QAAAA,WAAAA;AACAC,QAAAA;AACJ,KAAA;AAEA,IAAA,MAAMG,YAAY,CAACC,OAAAA,GAAAA;QACfJ,MAAAA,GAASI,OAAAA;AACTF,QAAAA,OAAAA,CAAQF,MAAM,GAAGI,OAAAA;AACrB,KAAA;IAEA,OAAO;AACHD,QAAAA,SAAAA;QACAE,SAAAA,EAAW,CAACC,OAAAA,GAAqBD,SAAAA,CAAUC,OAAAA,EAASJ,OAAAA,CAAAA;QACpDK,QAAAA,EAAU,CAACC,MAAAA,GAA8DD,QAAAA,CAASC,MAAAA,EAAQN,OAAAA,CAAAA;QAC1FO,IAAAA,EAAM,CAACC,IAAAA,GAAeD,IAAAA,CAAKC,IAAAA,EAAMR,OAAAA;AACrC,KAAA;AACJ;;;;"}
+{"version":3,"file":"cardigantime.js","sources":["../src/cardigantime.ts"],"sourcesContent":["import { Command } from 'commander';\nimport { Args, DefaultOptions, Feature, Cardigantime, Logger, Options } from 'types';\nimport { z, ZodObject } from 'zod';\nimport { configure } from './configure';\nimport { DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS } from './constants';\nimport { read, checkConfig } from './read';\nimport { ConfigSchema } from 'types';\nimport { validate } from './validate';\nimport * as yaml from 'js-yaml';\nimport * as path from 'path';\nimport { generateDefaultConfig } from './util/schema-defaults';\nimport * as Storage from './util/storage';\nimport { FileSystemError } from './error/FileSystemError';\n\nexport * from './types';\nexport { ArgumentError, ConfigurationError, FileSystemError } from './validate';\n\n/**\n * Creates a new Cardigantime instance for configuration management.\n * \n * Cardigantime handles the complete configuration lifecycle including:\n * - Reading configuration from YAML files\n * - Validating configuration against Zod schemas\n * - Merging CLI arguments with file configuration and defaults\n * - Providing type-safe configuration objects\n * \n * @template T - The Zod schema shape type for your configuration\n * @param pOptions - Configuration options for the Cardigantime instance\n * @param pOptions.defaults - Default configuration settings\n * @param pOptions.defaults.configDirectory - Directory to search for configuration files (required)\n * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')\n * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)\n * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')\n * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)\n * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])\n * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)\n * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)\n * @returns A Cardigantime instance with methods for configure, read, validate, and setLogger\n * \n * @example\n * ```typescript\n * import { create } from '@theunwalked/cardigantime';\n * import { z } from 'zod';\n * \n * const MyConfigSchema = z.object({\n *   apiKey: z.string().min(1),\n *   timeout: z.number().default(5000),\n *   debug: z.boolean().default(false),\n *   contextDirectories: z.array(z.string()).optional(),\n * });\n * \n * const cardigantime = create({\n *   defaults: {\n *     configDirectory: './config',\n *     configFile: 'myapp.yaml',\n *     // Resolve relative paths in contextDirectories relative to config file location\n *     pathResolution: {\n *       pathFields: ['contextDirectories'],\n *       resolvePathArray: ['contextDirectories']\n *     },\n *     // Configure how array fields are merged in hierarchical mode\n *     fieldOverlaps: {\n *       'features': 'append',              // Accumulate features from all levels\n *       'excludePatterns': 'prepend'       // Higher precedence patterns come first\n *     }\n *   },\n *   configShape: MyConfigSchema.shape,\n *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery\n * });\n * \n * // If config file is at ../config/myapp.yaml and contains:\n * // contextDirectories: ['./context', './data']\n * // These paths will be resolved relative to ../config/ directory\n * ```\n */\nexport const create = <T extends z.ZodRawShape>(pOptions: {\n    defaults: Pick<DefaultOptions, 'configDirectory'> & Partial<Omit<DefaultOptions, 'configDirectory'>>,\n    features?: Feature[],\n    configShape: T, // Make configShape mandatory\n    logger?: Logger,\n}): Cardigantime<T> => {\n\n\n    const defaults: DefaultOptions = { ...DEFAULT_OPTIONS, ...pOptions.defaults } as DefaultOptions;\n    const features = pOptions.features || DEFAULT_FEATURES;\n    const configShape = pOptions.configShape;\n    let logger = pOptions.logger || DEFAULT_LOGGER;\n\n    const options: Options<T> = {\n        defaults,\n        features,\n        configShape, // Store the shape\n        logger,\n    }\n\n    const setLogger = (pLogger: Logger) => {\n        logger = pLogger;\n        options.logger = pLogger;\n    }\n\n    const generateConfig = async (configDirectory?: string): Promise<void> => {\n        const targetDir = configDirectory || options.defaults.configDirectory;\n        const configFile = options.defaults.configFile;\n        const encoding = options.defaults.encoding;\n\n        logger.verbose(`Generating configuration file in: ${targetDir}`);\n\n        // Create storage utility\n        const storage = Storage.create({ log: logger.debug });\n\n        // Ensure the target directory exists\n        const dirExists = await storage.exists(targetDir);\n        if (!dirExists) {\n            logger.info(`Creating configuration directory: ${targetDir}`);\n            try {\n                await storage.createDirectory(targetDir);\n            } catch (error: any) {\n                throw FileSystemError.directoryCreationFailed(targetDir, error);\n            }\n        }\n\n        // Check if directory is writable\n        const isWritable = await storage.isDirectoryWritable(targetDir);\n        if (!isWritable) {\n            throw new FileSystemError('not_writable', 'Configuration directory is not writable', targetDir, 'directory_write');\n        }\n\n        // Build the full config file path\n        const configFilePath = path.join(targetDir, configFile);\n\n        // Generate default configuration\n        const defaultConfig = generateDefaultConfig(options.configShape, targetDir);\n\n        // Convert to YAML with nice formatting\n        const yamlContent = yaml.dump(defaultConfig, {\n            indent: 2,\n            lineWidth: 120,\n            noRefs: true,\n            sortKeys: true\n        });\n\n        // Add header comment to the YAML file\n        const header = `# Configuration file generated by Cardigantime\n# This file contains default values for your application configuration.\n# Modify the values below to customize your application's behavior.\n#\n# For more information about Cardigantime configuration:\n# https://github.com/SemicolonAmbulance/cardigantime\n\n`;\n\n        const finalContent = header + yamlContent;\n\n        // Check if config file already exists\n        const configExists = await storage.exists(configFilePath);\n        if (configExists) {\n            logger.warn(`Configuration file already exists: ${configFilePath}`);\n            logger.warn('This file was not overwritten, but here is what the default configuration looks like if you want to copy it:');\n            logger.info('\\n' + '='.repeat(60));\n            logger.info(finalContent.trim());\n            logger.info('='.repeat(60));\n            return;\n        }\n\n        // Write the configuration file\n        try {\n            await storage.writeFile(configFilePath, finalContent, encoding);\n            logger.info(`Configuration file generated successfully: ${configFilePath}`);\n        } catch (error: any) {\n            throw FileSystemError.operationFailed('write configuration file', configFilePath, error);\n        }\n    };\n\n    return {\n        setLogger,\n        configure: (command: Command) => configure(command, options),\n        validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => validate(config, options),\n        read: (args: Args) => read(args, options),\n        generateConfig,\n        checkConfig: (args: Args) => checkConfig(args, options),\n    }\n}\n\n\n\n\n\n"],"names":["create","pOptions","defaults","DEFAULT_OPTIONS","features","DEFAULT_FEATURES","configShape","logger","DEFAULT_LOGGER","options","setLogger","pLogger","generateConfig","configDirectory","targetDir","configFile","encoding","verbose","storage","Storage","log","debug","dirExists","exists","info","createDirectory","error","FileSystemError","directoryCreationFailed","isWritable","isDirectoryWritable","configFilePath","path","join","defaultConfig","generateDefaultConfig","yamlContent","yaml","dump","indent","lineWidth","noRefs","sortKeys","header","finalContent","configExists","warn","repeat","trim","writeFile","operationFailed","configure","command","validate","config","read","args","checkConfig"],"mappings":"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"}

package/dist/configure.js

@@ -100,6 +100,10 @@ import { ArgumentError } from './error/ArgumentError.js';
             throw error;
         }
     }, validatedDefaultDir);
+    // Add the init config option
+    retCommand = retCommand.option('--init-config', 'Generate initial configuration file and exit');
+    // Add the check config option
+    retCommand = retCommand.option('--check-config', 'Display resolved configuration with source tracking and exit');
     return retCommand;
 };
 

package/dist/configure.js.map

@@ -1 +1 @@
-{"version":3,"file":"configure.js","sources":["../src/configure.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { z } from \"zod\";\nimport { ArgumentError } from \"./error/ArgumentError\";\nimport { Options } from \"./types\";\nexport { ArgumentError };\n\n/**\n * Validates a configuration directory path to ensure it's safe and valid.\n * \n * Performs security and safety checks including:\n * - Non-empty string validation\n * - Null byte injection prevention\n * - Path length validation\n * - Type checking\n * \n * @param configDirectory - The configuration directory path to validate\n * @param _testThrowNonArgumentError - Internal testing parameter to simulate non-ArgumentError exceptions\n * @returns The trimmed and validated configuration directory path\n * @throws {ArgumentError} When the directory path is invalid\n * \n * @example\n * ```typescript\n * const validDir = validateConfigDirectory('./config'); // Returns './config'\n * const invalidDir = validateConfigDirectory(''); // Throws ArgumentError\n * ```\n */\nexport function validateConfigDirectory(configDirectory: string, _testThrowNonArgumentError?: boolean): string {\n    if (_testThrowNonArgumentError) {\n        throw new Error('Test non-ArgumentError for coverage');\n    }\n\n    if (!configDirectory) {\n        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty');\n    }\n\n    if (typeof configDirectory !== 'string') {\n        throw new ArgumentError('configDirectory', 'Configuration directory must be a string');\n    }\n\n    const trimmed = configDirectory.trim();\n    if (trimmed.length === 0) {\n        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty or whitespace only');\n    }\n\n    // Check for obviously invalid paths\n    if (trimmed.includes('\\0')) {\n        throw new ArgumentError('configDirectory', 'Configuration directory contains invalid null character');\n    }\n\n    // Validate path length (reasonable limit)\n    if (trimmed.length > 1000) {\n        throw new ArgumentError('configDirectory', 'Configuration directory path is too long (max 1000 characters)');\n    }\n\n    return trimmed;\n}\n\n/**\n * Configures a Commander.js command with Cardigantime's CLI options.\n * \n * This function adds command-line options that allow users to override\n * configuration settings at runtime, such as:\n * - --config-directory: Override the default configuration directory\n * \n * The function validates both the command object and the options to ensure\n * they meet the requirements for proper integration.\n * \n * @template T - The Zod schema shape type for configuration validation\n * @param command - The Commander.js Command instance to configure\n * @param options - Cardigantime options containing defaults and schema\n * @param _testThrowNonArgumentError - Internal testing parameter\n * @returns Promise resolving to the configured Command instance\n * @throws {ArgumentError} When command or options are invalid\n * \n * @example\n * ```typescript\n * import { Command } from 'commander';\n * import { configure } from './configure';\n * \n * const program = new Command();\n * const configuredProgram = await configure(program, options);\n * \n * // Now the program accepts: --config-directory <path>\n * ```\n */\nexport const configure = async <T extends z.ZodRawShape>(\n    command: Command,\n    options: Options<T>,\n    _testThrowNonArgumentError?: boolean\n): Promise<Command> => {\n    // Validate the command object\n    if (!command) {\n        throw new ArgumentError('command', 'Command instance is required');\n    }\n\n    if (typeof command.option !== 'function') {\n        throw new ArgumentError('command', 'Command must be a valid Commander.js Command instance');\n    }\n\n    // Validate options\n    if (!options) {\n        throw new ArgumentError('options', 'Options object is required');\n    }\n\n    if (!options.defaults) {\n        throw new ArgumentError('options.defaults', 'Options must include defaults configuration');\n    }\n\n    if (!options.defaults.configDirectory) {\n        throw new ArgumentError('options.defaults.configDirectory', 'Default config directory is required');\n    }\n\n    // Validate the default config directory\n    const validatedDefaultDir = validateConfigDirectory(options.defaults.configDirectory, _testThrowNonArgumentError);\n\n    let retCommand = command;\n\n    // Add the config directory option with validation\n    retCommand = retCommand.option(\n        '-c, --config-directory <configDirectory>',\n        'Configuration directory path',\n        (value: string) => {\n            try {\n                return validateConfigDirectory(value, _testThrowNonArgumentError);\n            } catch (error) {\n                if (error instanceof ArgumentError) {\n                    // Re-throw with more specific context for CLI usage\n                    throw new ArgumentError('config-directory', `Invalid --config-directory: ${error.message}`);\n                }\n                throw error;\n            }\n        },\n        validatedDefaultDir\n    );\n\n    return retCommand;\n}\n\n\n\n\n"],"names":["validateConfigDirectory","configDirectory","_testThrowNonArgumentError","ArgumentError","trimmed","trim","length","includes","configure","command","options","option","defaults","validatedDefaultDir","retCommand","value","error","message"],"mappings":";;AAMA;;;;;;;;;;;;;;;;;;;AAmBC,IACM,SAASA,uBAAAA,CAAwBC,eAAuB,EAAEC,0BAAoC,EAAA;AAKjG,IAAA,IAAI,CAACD,eAAAA,EAAiB;QAClB,MAAM,IAAIE,cAAc,iBAAA,EAAmB,yCAAA,CAAA;AAC/C;IAEA,IAAI,OAAOF,oBAAoB,QAAA,EAAU;QACrC,MAAM,IAAIE,cAAc,iBAAA,EAAmB,0CAAA,CAAA;AAC/C;IAEA,MAAMC,OAAAA,GAAUH,gBAAgBI,IAAI,EAAA;IACpC,IAAID,OAAAA,CAAQE,MAAM,KAAK,CAAA,EAAG;QACtB,MAAM,IAAIH,cAAc,iBAAA,EAAmB,4DAAA,CAAA;AAC/C;;IAGA,IAAIC,OAAAA,CAAQG,QAAQ,CAAC,IAAA,CAAA,EAAO;QACxB,MAAM,IAAIJ,cAAc,iBAAA,EAAmB,yDAAA,CAAA;AAC/C;;IAGA,IAAIC,OAAAA,CAAQE,MAAM,GAAG,IAAA,EAAM;QACvB,MAAM,IAAIH,cAAc,iBAAA,EAAmB,gEAAA,CAAA;AAC/C;IAEA,OAAOC,OAAAA;AACX;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BC,IACM,MAAMI,SAAAA,GAAY,OACrBC,SACAC,OAAAA,EACAR,0BAAAA,GAAAA;;AAGA,IAAA,IAAI,CAACO,OAAAA,EAAS;QACV,MAAM,IAAIN,cAAc,SAAA,EAAW,8BAAA,CAAA;AACvC;AAEA,IAAA,IAAI,OAAOM,OAAAA,CAAQE,MAAM,KAAK,UAAA,EAAY;QACtC,MAAM,IAAIR,cAAc,SAAA,EAAW,uDAAA,CAAA;AACvC;;AAGA,IAAA,IAAI,CAACO,OAAAA,EAAS;QACV,MAAM,IAAIP,cAAc,SAAA,EAAW,4BAAA,CAAA;AACvC;IAEA,IAAI,CAACO,OAAAA,CAAQE,QAAQ,EAAE;QACnB,MAAM,IAAIT,cAAc,kBAAA,EAAoB,6CAAA,CAAA;AAChD;AAEA,IAAA,IAAI,CAACO,OAAAA,CAAQE,QAAQ,CAACX,eAAe,EAAE;QACnC,MAAM,IAAIE,cAAc,kCAAA,EAAoC,sCAAA,CAAA;AAChE;;AAGA,IAAA,MAAMU,sBAAsBb,uBAAAA,CAAwBU,OAAAA,CAAQE,QAAQ,CAACX,eAAiBC,CAAAA;AAEtF,IAAA,IAAIY,UAAAA,GAAaL,OAAAA;;AAGjBK,IAAAA,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,0CAAA,EACA,gCACA,CAACI,KAAAA,GAAAA;QACG,IAAI;AACA,YAAA,OAAOf,wBAAwBe,KAAAA,EAAOb,0BAAAA,CAAAA;AAC1C,SAAA,CAAE,OAAOc,KAAAA,EAAO;AACZ,YAAA,IAAIA,iBAAiBb,aAAAA,EAAe;;gBAEhC,MAAM,IAAIA,cAAc,kBAAA,EAAoB,CAAC,4BAA4B,EAAEa,KAAAA,CAAMC,OAAO,CAAA,CAAE,CAAA;AAC9F;YACA,MAAMD,KAAAA;AACV;KACJ,EACAH,mBAAAA,CAAAA;IAGJ,OAAOC,UAAAA;AACX;;;;"}
+{"version":3,"file":"configure.js","sources":["../src/configure.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { z } from \"zod\";\nimport { ArgumentError } from \"./error/ArgumentError\";\nimport { Options } from \"./types\";\nexport { ArgumentError };\n\n/**\n * Validates a configuration directory path to ensure it's safe and valid.\n * \n * Performs security and safety checks including:\n * - Non-empty string validation\n * - Null byte injection prevention\n * - Path length validation\n * - Type checking\n * \n * @param configDirectory - The configuration directory path to validate\n * @param _testThrowNonArgumentError - Internal testing parameter to simulate non-ArgumentError exceptions\n * @returns The trimmed and validated configuration directory path\n * @throws {ArgumentError} When the directory path is invalid\n * \n * @example\n * ```typescript\n * const validDir = validateConfigDirectory('./config'); // Returns './config'\n * const invalidDir = validateConfigDirectory(''); // Throws ArgumentError\n * ```\n */\nexport function validateConfigDirectory(configDirectory: string, _testThrowNonArgumentError?: boolean): string {\n    if (_testThrowNonArgumentError) {\n        throw new Error('Test non-ArgumentError for coverage');\n    }\n\n    if (!configDirectory) {\n        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty');\n    }\n\n    if (typeof configDirectory !== 'string') {\n        throw new ArgumentError('configDirectory', 'Configuration directory must be a string');\n    }\n\n    const trimmed = configDirectory.trim();\n    if (trimmed.length === 0) {\n        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty or whitespace only');\n    }\n\n    // Check for obviously invalid paths\n    if (trimmed.includes('\\0')) {\n        throw new ArgumentError('configDirectory', 'Configuration directory contains invalid null character');\n    }\n\n    // Validate path length (reasonable limit)\n    if (trimmed.length > 1000) {\n        throw new ArgumentError('configDirectory', 'Configuration directory path is too long (max 1000 characters)');\n    }\n\n    return trimmed;\n}\n\n/**\n * Configures a Commander.js command with Cardigantime's CLI options.\n * \n * This function adds command-line options that allow users to override\n * configuration settings at runtime, such as:\n * - --config-directory: Override the default configuration directory\n * \n * The function validates both the command object and the options to ensure\n * they meet the requirements for proper integration.\n * \n * @template T - The Zod schema shape type for configuration validation\n * @param command - The Commander.js Command instance to configure\n * @param options - Cardigantime options containing defaults and schema\n * @param _testThrowNonArgumentError - Internal testing parameter\n * @returns Promise resolving to the configured Command instance\n * @throws {ArgumentError} When command or options are invalid\n * \n * @example\n * ```typescript\n * import { Command } from 'commander';\n * import { configure } from './configure';\n * \n * const program = new Command();\n * const configuredProgram = await configure(program, options);\n * \n * // Now the program accepts: --config-directory <path>\n * ```\n */\nexport const configure = async <T extends z.ZodRawShape>(\n    command: Command,\n    options: Options<T>,\n    _testThrowNonArgumentError?: boolean\n): Promise<Command> => {\n    // Validate the command object\n    if (!command) {\n        throw new ArgumentError('command', 'Command instance is required');\n    }\n\n    if (typeof command.option !== 'function') {\n        throw new ArgumentError('command', 'Command must be a valid Commander.js Command instance');\n    }\n\n    // Validate options\n    if (!options) {\n        throw new ArgumentError('options', 'Options object is required');\n    }\n\n    if (!options.defaults) {\n        throw new ArgumentError('options.defaults', 'Options must include defaults configuration');\n    }\n\n    if (!options.defaults.configDirectory) {\n        throw new ArgumentError('options.defaults.configDirectory', 'Default config directory is required');\n    }\n\n    // Validate the default config directory\n    const validatedDefaultDir = validateConfigDirectory(options.defaults.configDirectory, _testThrowNonArgumentError);\n\n    let retCommand = command;\n\n    // Add the config directory option with validation\n    retCommand = retCommand.option(\n        '-c, --config-directory <configDirectory>',\n        'Configuration directory path',\n        (value: string) => {\n            try {\n                return validateConfigDirectory(value, _testThrowNonArgumentError);\n            } catch (error) {\n                if (error instanceof ArgumentError) {\n                    // Re-throw with more specific context for CLI usage\n                    throw new ArgumentError('config-directory', `Invalid --config-directory: ${error.message}`);\n                }\n                throw error;\n            }\n        },\n        validatedDefaultDir\n    );\n\n    // Add the init config option\n    retCommand = retCommand.option(\n        '--init-config',\n        'Generate initial configuration file and exit'\n    );\n\n    // Add the check config option\n    retCommand = retCommand.option(\n        '--check-config',\n        'Display resolved configuration with source tracking and exit'\n    );\n\n    return retCommand;\n}\n\n\n\n\n"],"names":["validateConfigDirectory","configDirectory","_testThrowNonArgumentError","ArgumentError","trimmed","trim","length","includes","configure","command","options","option","defaults","validatedDefaultDir","retCommand","value","error","message"],"mappings":";;AAMA;;;;;;;;;;;;;;;;;;;AAmBC,IACM,SAASA,uBAAAA,CAAwBC,eAAuB,EAAEC,0BAAoC,EAAA;AAKjG,IAAA,IAAI,CAACD,eAAAA,EAAiB;QAClB,MAAM,IAAIE,cAAc,iBAAA,EAAmB,yCAAA,CAAA;AAC/C;IAEA,IAAI,OAAOF,oBAAoB,QAAA,EAAU;QACrC,MAAM,IAAIE,cAAc,iBAAA,EAAmB,0CAAA,CAAA;AAC/C;IAEA,MAAMC,OAAAA,GAAUH,gBAAgBI,IAAI,EAAA;IACpC,IAAID,OAAAA,CAAQE,MAAM,KAAK,CAAA,EAAG;QACtB,MAAM,IAAIH,cAAc,iBAAA,EAAmB,4DAAA,CAAA;AAC/C;;IAGA,IAAIC,OAAAA,CAAQG,QAAQ,CAAC,IAAA,CAAA,EAAO;QACxB,MAAM,IAAIJ,cAAc,iBAAA,EAAmB,yDAAA,CAAA;AAC/C;;IAGA,IAAIC,OAAAA,CAAQE,MAAM,GAAG,IAAA,EAAM;QACvB,MAAM,IAAIH,cAAc,iBAAA,EAAmB,gEAAA,CAAA;AAC/C;IAEA,OAAOC,OAAAA;AACX;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BC,IACM,MAAMI,SAAAA,GAAY,OACrBC,SACAC,OAAAA,EACAR,0BAAAA,GAAAA;;AAGA,IAAA,IAAI,CAACO,OAAAA,EAAS;QACV,MAAM,IAAIN,cAAc,SAAA,EAAW,8BAAA,CAAA;AACvC;AAEA,IAAA,IAAI,OAAOM,OAAAA,CAAQE,MAAM,KAAK,UAAA,EAAY;QACtC,MAAM,IAAIR,cAAc,SAAA,EAAW,uDAAA,CAAA;AACvC;;AAGA,IAAA,IAAI,CAACO,OAAAA,EAAS;QACV,MAAM,IAAIP,cAAc,SAAA,EAAW,4BAAA,CAAA;AACvC;IAEA,IAAI,CAACO,OAAAA,CAAQE,QAAQ,EAAE;QACnB,MAAM,IAAIT,cAAc,kBAAA,EAAoB,6CAAA,CAAA;AAChD;AAEA,IAAA,IAAI,CAACO,OAAAA,CAAQE,QAAQ,CAACX,eAAe,EAAE;QACnC,MAAM,IAAIE,cAAc,kCAAA,EAAoC,sCAAA,CAAA;AAChE;;AAGA,IAAA,MAAMU,sBAAsBb,uBAAAA,CAAwBU,OAAAA,CAAQE,QAAQ,CAACX,eAAiBC,CAAAA;AAEtF,IAAA,IAAIY,UAAAA,GAAaL,OAAAA;;AAGjBK,IAAAA,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,0CAAA,EACA,gCACA,CAACI,KAAAA,GAAAA;QACG,IAAI;AACA,YAAA,OAAOf,wBAAwBe,KAAAA,EAAOb,0BAAAA,CAAAA;AAC1C,SAAA,CAAE,OAAOc,KAAAA,EAAO;AACZ,YAAA,IAAIA,iBAAiBb,aAAAA,EAAe;;gBAEhC,MAAM,IAAIA,cAAc,kBAAA,EAAoB,CAAC,4BAA4B,EAAEa,KAAAA,CAAMC,OAAO,CAAA,CAAE,CAAA;AAC9F;YACA,MAAMD,KAAAA;AACV;KACJ,EACAH,mBAAAA,CAAAA;;IAIJC,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,eAAA,EACA,8CAAA,CAAA;;IAIJG,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,gBAAA,EACA,8DAAA,CAAA;IAGJ,OAAOG,UAAAA;AACX;;;;"}

package/dist/read.d.ts

@@ -31,3 +31,26 @@ import { Args, ConfigSchema, Options } from './types';
  * ```
  */
 export declare const read: <T extends z.ZodRawShape>(args: Args, options: Options<T>) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;
+/**
+ * Checks and displays the resolved configuration with detailed source tracking.
+ *
+ * This function provides a git blame-like view of configuration resolution,
+ * showing which file and hierarchical level contributed each configuration value.
+ *
+ * @template T - The Zod schema shape type for configuration validation
+ * @param args - Parsed command-line arguments
+ * @param options - Cardigantime options with defaults, schema, and logger
+ * @returns Promise that resolves when the configuration check is complete
+ *
+ * @example
+ * ```typescript
+ * await checkConfig(cliArgs, {
+ *   defaults: { configDirectory: './config', configFile: 'app.yaml' },
+ *   configShape: MySchema.shape,
+ *   logger: console,
+ *   features: ['config', 'hierarchical']
+ * });
+ * // Outputs detailed configuration source analysis
+ * ```
+ */
+export declare const checkConfig: <T extends z.ZodRawShape>(args: Args, options: Options<T>) => Promise<void>;

package/dist/read.js

@@ -255,6 +255,263 @@ import { loadHierarchicalConfig } from './util/hierarchical.js';
     }
     return rawFileConfig;
 }
+/**
+ * Recursively tracks the source of configuration values from hierarchical loading.
+ * 
+ * @param config - The configuration object to track
+ * @param sourcePath - Path to the configuration file
+ * @param level - Hierarchical level
+ * @param prefix - Current object path prefix for nested values
+ * @param tracker - The tracker object to populate
+ */ function trackConfigSources(config, sourcePath, level, prefix = '', tracker = {}) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        // For primitives and arrays, track the entire value
+        tracker[prefix] = {
+            value: config,
+            sourcePath,
+            level,
+            sourceLabel: `Level ${level}: ${path.basename(path.dirname(sourcePath))}`
+        };
+        return tracker;
+    }
+    // For objects, recursively track each property
+    for (const [key, value] of Object.entries(config)){
+        const fieldPath = prefix ? `${prefix}.${key}` : key;
+        trackConfigSources(value, sourcePath, level, fieldPath, tracker);
+    }
+    return tracker;
+}
+/**
+ * Merges multiple configuration source trackers with proper precedence.
+ * Lower level numbers have higher precedence.
+ * 
+ * @param trackers - Array of trackers from different config sources
+ * @returns Merged tracker with proper precedence
+ */ function mergeConfigTrackers(trackers) {
+    const merged = {};
+    for (const tracker of trackers){
+        for (const [key, info] of Object.entries(tracker)){
+            // Only update if we don't have this key yet, or if this source has higher precedence (lower level)
+            if (!merged[key] || info.level < merged[key].level) {
+                merged[key] = info;
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Formats a configuration value for display, handling different types appropriately.
+ * 
+ * @param value - The configuration value to format
+ * @returns Formatted string representation
+ */ function formatConfigValue(value) {
+    if (value === null) return 'null';
+    if (value === undefined) return 'undefined';
+    if (typeof value === 'string') return `"${value}"`;
+    if (typeof value === 'boolean') return value.toString();
+    if (typeof value === 'number') return value.toString();
+    if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        if (value.length <= 3) {
+            return `[${value.map(formatConfigValue).join(', ')}]`;
+        }
+        return `[${value.slice(0, 2).map(formatConfigValue).join(', ')}, ... (${value.length} items)]`;
+    }
+    if (typeof value === 'object') {
+        const keys = Object.keys(value);
+        if (keys.length === 0) return '{}';
+        if (keys.length <= 2) {
+            return `{${keys.slice(0, 2).join(', ')}}`;
+        }
+        return `{${keys.slice(0, 2).join(', ')}, ... (${keys.length} keys)}`;
+    }
+    return String(value);
+}
+/**
+ * Displays configuration with source tracking in a git blame-like format.
+ * 
+ * @param config - The resolved configuration object
+ * @param tracker - Configuration source tracker
+ * @param discoveredDirs - Array of discovered configuration directories
+ * @param logger - Logger instance for output
+ */ function displayConfigWithSources(config, tracker, discoveredDirs, logger) {
+    logger.info('\n' + '='.repeat(80));
+    logger.info('CONFIGURATION SOURCE ANALYSIS');
+    logger.info('='.repeat(80));
+    // Display discovered configuration hierarchy
+    logger.info('\nDISCOVERED CONFIGURATION HIERARCHY:');
+    if (discoveredDirs.length === 0) {
+        logger.info('  No configuration directories found in hierarchy');
+    } else {
+        discoveredDirs.sort((a, b)=>a.level - b.level) // Sort by precedence (lower level = higher precedence)
+        .forEach((dir)=>{
+            const precedence = dir.level === 0 ? '(highest precedence)' : dir.level === Math.max(...discoveredDirs.map((d)=>d.level)) ? '(lowest precedence)' : '';
+            logger.info(`  Level ${dir.level}: ${dir.path} ${precedence}`);
+        });
+    }
+    // Display resolved configuration with sources
+    logger.info('\nRESOLVED CONFIGURATION WITH SOURCES:');
+    logger.info('Format: [Source] key: value\n');
+    const sortedKeys = Object.keys(tracker).sort();
+    const maxKeyLength = Math.max(...sortedKeys.map((k)=>k.length), 20);
+    const maxSourceLength = Math.max(...Object.values(tracker).map((info)=>info.sourceLabel.length), 25);
+    for (const key of sortedKeys){
+        const info = tracker[key];
+        const paddedKey = key.padEnd(maxKeyLength);
+        const paddedSource = info.sourceLabel.padEnd(maxSourceLength);
+        const formattedValue = formatConfigValue(info.value);
+        logger.info(`[${paddedSource}] ${paddedKey}: ${formattedValue}`);
+    }
+    // Display summary
+    logger.info('\n' + '-'.repeat(80));
+    logger.info('SUMMARY:');
+    logger.info(`  Total configuration keys: ${Object.keys(tracker).length}`);
+    logger.info(`  Configuration sources: ${discoveredDirs.length}`);
+    // Count values by source
+    const sourceCount = {};
+    for (const info of Object.values(tracker)){
+        sourceCount[info.sourceLabel] = (sourceCount[info.sourceLabel] || 0) + 1;
+    }
+    logger.info('  Values by source:');
+    for (const [source, count] of Object.entries(sourceCount)){
+        logger.info(`    ${source}: ${count} value(s)`);
+    }
+    logger.info('='.repeat(80));
+}
+/**
+ * Checks and displays the resolved configuration with detailed source tracking.
+ * 
+ * This function provides a git blame-like view of configuration resolution,
+ * showing which file and hierarchical level contributed each configuration value.
+ * 
+ * @template T - The Zod schema shape type for configuration validation
+ * @param args - Parsed command-line arguments
+ * @param options - Cardigantime options with defaults, schema, and logger
+ * @returns Promise that resolves when the configuration check is complete
+ * 
+ * @example
+ * ```typescript
+ * await checkConfig(cliArgs, {
+ *   defaults: { configDirectory: './config', configFile: 'app.yaml' },
+ *   configShape: MySchema.shape,
+ *   logger: console,
+ *   features: ['config', 'hierarchical']
+ * });
+ * // Outputs detailed configuration source analysis
+ * ```
+ */ const checkConfig = async (args, options)=>{
+    var _options_defaults, _options_defaults_pathResolution;
+    const logger = options.logger;
+    logger.info('Starting configuration check...');
+    const rawConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
+    if (!rawConfigDir) {
+        throw new Error('Configuration directory must be specified');
+    }
+    const resolvedConfigDir = validateConfigDirectory(rawConfigDir);
+    logger.verbose(`Resolved config directory: ${resolvedConfigDir}`);
+    let rawFileConfig = {};
+    let discoveredDirs = [];
+    let tracker = {};
+    // Check if hierarchical configuration discovery is enabled
+    if (options.features.includes('hierarchical')) {
+        logger.verbose('Using hierarchical configuration discovery for source tracking');
+        try {
+            var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
+            // Extract the config directory name from the path for hierarchical discovery
+            const configDirName = path.basename(resolvedConfigDir);
+            const startingDir = path.dirname(resolvedConfigDir);
+            logger.debug(`Using hierarchical discovery: configDirName=${configDirName}, startingDir=${startingDir}`);
+            const hierarchicalResult = await loadHierarchicalConfig({
+                configDirName,
+                configFileName: options.defaults.configFile,
+                startingDir,
+                encoding: options.defaults.encoding,
+                logger,
+                pathFields: (_options_defaults_pathResolution1 = options.defaults.pathResolution) === null || _options_defaults_pathResolution1 === void 0 ? void 0 : _options_defaults_pathResolution1.pathFields,
+                resolvePathArray: (_options_defaults_pathResolution2 = options.defaults.pathResolution) === null || _options_defaults_pathResolution2 === void 0 ? void 0 : _options_defaults_pathResolution2.resolvePathArray,
+                fieldOverlaps: options.defaults.fieldOverlaps
+            });
+            rawFileConfig = hierarchicalResult.config;
+            discoveredDirs = hierarchicalResult.discoveredDirs;
+            // Build detailed source tracking by re-loading each config individually
+            const trackers = [];
+            // Sort by level (highest level first = lowest precedence first) to match merge order
+            const sortedDirs = [
+                ...discoveredDirs
+            ].sort((a, b)=>b.level - a.level);
+            for (const dir of sortedDirs){
+                const storage = create({
+                    log: logger.debug
+                });
+                const configFilePath = path.join(dir.path, options.defaults.configFile);
+                try {
+                    const exists = await storage.exists(configFilePath);
+                    if (!exists) continue;
+                    const isReadable = await storage.isFileReadable(configFilePath);
+                    if (!isReadable) continue;
+                    const yamlContent = await storage.readFile(configFilePath, options.defaults.encoding);
+                    const parsedYaml = yaml.load(yamlContent);
+                    if (parsedYaml !== null && typeof parsedYaml === 'object') {
+                        const levelTracker = trackConfigSources(parsedYaml, configFilePath, dir.level);
+                        trackers.push(levelTracker);
+                    }
+                } catch (error) {
+                    logger.debug(`Error loading config for source tracking from ${configFilePath}: ${error.message}`);
+                }
+            }
+            // Merge trackers with proper precedence
+            tracker = mergeConfigTrackers(trackers);
+            if (hierarchicalResult.errors.length > 0) {
+                logger.warn('Configuration loading warnings:');
+                hierarchicalResult.errors.forEach((error)=>logger.warn(`  ${error}`));
+            }
+        } catch (error) {
+            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));
+            logger.verbose('Falling back to single directory configuration loading');
+            // Fall back to single directory mode for source tracking
+            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+            const configFilePath = path.join(resolvedConfigDir, options.defaults.configFile);
+            tracker = trackConfigSources(rawFileConfig, configFilePath, 0);
+            discoveredDirs = [
+                {
+                    path: resolvedConfigDir,
+                    level: 0
+                }
+            ];
+        }
+    } else {
+        // Use traditional single directory configuration loading
+        logger.verbose('Using single directory configuration loading for source tracking');
+        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+        const configFilePath = path.join(resolvedConfigDir, options.defaults.configFile);
+        tracker = trackConfigSources(rawFileConfig, configFilePath, 0);
+        discoveredDirs = [
+            {
+                path: resolvedConfigDir,
+                level: 0
+            }
+        ];
+    }
+    // Apply path resolution if configured (this doesn't change source tracking)
+    let processedConfig = rawFileConfig;
+    if ((_options_defaults_pathResolution = options.defaults.pathResolution) === null || _options_defaults_pathResolution === void 0 ? void 0 : _options_defaults_pathResolution.pathFields) {
+        processedConfig = resolveConfigPaths(rawFileConfig, resolvedConfigDir, options.defaults.pathResolution.pathFields, options.defaults.pathResolution.resolvePathArray || []);
+    }
+    // Build final configuration including built-in values
+    const finalConfig = clean({
+        ...processedConfig,
+        configDirectory: resolvedConfigDir
+    });
+    // Add built-in configuration to tracker
+    tracker['configDirectory'] = {
+        value: resolvedConfigDir,
+        sourcePath: 'built-in',
+        level: -1,
+        sourceLabel: 'Built-in (runtime)'
+    };
+    // Display the configuration with source information
+    displayConfigWithSources(finalConfig, tracker, discoveredDirs, logger);
+};
 
-export { read };
+export { checkConfig, read };
 //# sourceMappingURL=read.js.map