@theunwalked/cardigantime 0.0.15 → 0.0.17

package/README.md

@@ -29,9 +29,9 @@ Cardigantime provides a complete, battle-tested solution for all of this complex
 ```bash
 npm install @theunwalked/cardigantime
 # or
-pnpm add @theunwalked/cardigantime
-# or
 yarn add @theunwalked/cardigantime
+# or
+pnpm add @theunwalked/cardigantime
 ```
 
 ## Quick Start
@@ -149,16 +149,16 @@ Comprehensive error handling with detailed, actionable error messages to help us
 
 ## Documentation
 
-📚 **[Complete Documentation](https://semicolonambulance.github.io/cardigantime/)** - Full documentation site
+📚 **[Complete Documentation](https://tobrien.github.io/cardigantime/)** - Full documentation site
 
 **Quick Links:**
-- [Getting Started Guide](https://semicolonambulance.github.io/cardigantime/#getting-started) - Detailed setup and basic concepts
-- [Core Concepts](https://semicolonambulance.github.io/cardigantime/#core-concepts) - Configuration sources, hierarchical discovery
-- [API Reference](https://semicolonambulance.github.io/cardigantime/#api-reference) - Complete API documentation
-- [Configuration Options](https://semicolonambulance.github.io/cardigantime/#configuration-options) - All available options
-- [Debugging & Analysis](https://semicolonambulance.github.io/cardigantime/#debugging-analysis) - Tools for analyzing config
-- [Advanced Usage](https://semicolonambulance.github.io/cardigantime/#advanced-usage) - Complex examples and scenarios
-- [Error Handling](https://semicolonambulance.github.io/cardigantime/#error-handling) - Comprehensive error handling guide
+- [Getting Started Guide](https://tobrien.github.io/cardigantime/#getting-started) - Detailed setup and basic concepts
+- [Core Concepts](https://tobrien.github.io/cardigantime/#core-concepts) - Configuration sources, hierarchical discovery
+- [API Reference](https://tobrien.github.io/cardigantime/#api-reference) - Complete API documentation
+- [Configuration Options](https://tobrien.github.io/cardigantime/#configuration-options) - All available options
+- [Debugging & Analysis](https://tobrien.github.io/cardigantime/#debugging-analysis) - Tools for analyzing config
+- [Advanced Usage](https://tobrien.github.io/cardigantime/#advanced-usage) - Complex examples and scenarios
+- [Error Handling](https://tobrien.github.io/cardigantime/#error-handling) - Comprehensive error handling guide
 
 ## Contributing
 

package/dist/cardigantime.cjs

@@ -30,6 +30,19 @@ const yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
 const path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 const fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 
+function _define_property$2(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
 /**
  * Error thrown when CLI arguments or function parameters are invalid.
  * 
@@ -43,20 +56,7 @@ const fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
  * // Error message: "Path cannot be empty"
  * // error.argument: "config-directory"
  * ```
- */ function _define_property$2(obj, key, value) {
-    if (key in obj) {
-        Object.defineProperty(obj, key, {
-            value: value,
-            enumerable: true,
-            configurable: true,
-            writable: true
-        });
-    } else {
-        obj[key] = value;
-    }
-    return obj;
-}
-class ArgumentError extends Error {
+ */ class ArgumentError extends Error {
     /**
      * Gets the name of the argument that caused this error.
      * 
@@ -217,9 +217,7 @@ class ArgumentError extends Error {
     silly: ()=>{}
 };
 
-/**
- * Error thrown when file system operations fail
- */ function _define_property$1(obj, key, value) {
+function _define_property$1(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -232,7 +230,9 @@ class ArgumentError extends Error {
     }
     return obj;
 }
-class FileSystemError extends Error {
+/**
+ * Error thrown when file system operations fail
+ */ class FileSystemError extends Error {
     /**
      * Creates an error for when a required directory doesn't exist
      */ static directoryNotFound(path, isRequired = false) {
@@ -973,7 +973,8 @@ const create$1 = (params)=>{
     let discoveredConfigDirs = [];
     let resolvedConfigDirs = [];
     // Check if hierarchical configuration discovery is enabled
-    if (options.features.includes('hierarchical')) {
+    // Use optional chaining for safety although options.features is defaulted
+    if (options.features && options.features.includes('hierarchical')) {
         logger.verbose('Hierarchical configuration discovery enabled');
         try {
             var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
@@ -1252,7 +1253,8 @@ const create$1 = (params)=>{
     let resolvedConfigDirs = [];
     let tracker = {};
     // Check if hierarchical configuration discovery is enabled
-    if (options.features.includes('hierarchical')) {
+    // Use optional chaining for safety although options.features is defaulted
+    if (options.features && options.features.includes('hierarchical')) {
         logger.verbose('Using hierarchical configuration discovery for source tracking');
         try {
             var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
@@ -1389,9 +1391,7 @@ const create$1 = (params)=>{
     displayConfigWithSources(finalConfig, tracker, discoveredDirs, logger);
 };
 
-/**
- * Error thrown when configuration validation fails
- */ function _define_property(obj, key, value) {
+function _define_property(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -1404,7 +1404,9 @@ const create$1 = (params)=>{
     }
     return obj;
 }
-class ConfigurationError extends Error {
+/**
+ * Error thrown when configuration validation fails
+ */ class ConfigurationError extends Error {
     /**
      * Creates a validation error for when config doesn't match the schema
      */ static validation(message, zodError, configPath) {
@@ -1444,22 +1446,22 @@ class ConfigurationError extends Error {
 
 /**
  * Recursively extracts all keys from a Zod schema in dot notation.
- * 
+ *
  * This function traverses a Zod schema structure and builds a flat list
  * of all possible keys, using dot notation for nested objects. It handles
  * optional/nullable types by unwrapping them and supports arrays by
  * introspecting their element type.
- * 
+ *
  * Special handling for:
  * - ZodOptional/ZodNullable: Unwraps to get the underlying type
  * - ZodAny/ZodRecord: Accepts any keys, returns the prefix or empty array
  * - ZodArray: Introspects the element type
  * - ZodObject: Recursively processes all shape properties
- * 
+ *
  * @param schema - The Zod schema to introspect
  * @param prefix - Internal parameter for building nested key paths
  * @returns Array of strings representing all possible keys in dot notation
- * 
+ *
  * @example
  * ```typescript
  * const schema = z.object({
@@ -1469,32 +1471,26 @@ class ConfigurationError extends Error {
  *   }),
  *   debug: z.boolean()
  * });
- * 
+ *
  * const keys = listZodKeys(schema);
  * // Returns: ['user.name', 'user.settings.theme', 'debug']
  * ```
  */ const listZodKeys = (schema, prefix = '')=>{
-    // Check if schema has unwrap method (which both ZodOptional and ZodNullable have)
-    if (schema._def && (schema._def.typeName === 'ZodOptional' || schema._def.typeName === 'ZodNullable')) {
-        // Use type assertion to handle the unwrap method
-        const unwrappable = schema;
-        return listZodKeys(unwrappable.unwrap(), prefix);
+    // Handle ZodOptional and ZodNullable - unwrap to get the underlying type
+    if (schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable) {
+        return listZodKeys(schema.unwrap(), prefix);
     }
     // Handle ZodAny and ZodRecord - these accept any keys, so don't introspect
-    if (schema._def && (schema._def.typeName === 'ZodAny' || schema._def.typeName === 'ZodRecord')) {
+    if (schema instanceof zod.z.ZodAny || schema instanceof zod.z.ZodRecord) {
         return prefix ? [
             prefix
         ] : [];
     }
-    if (schema._def && schema._def.typeName === 'ZodArray') {
-        // Use type assertion to handle the element property
-        const arraySchema = schema;
-        return listZodKeys(arraySchema.element, prefix);
+    if (schema instanceof zod.z.ZodArray) {
+        return listZodKeys(schema.element, prefix);
     }
-    if (schema._def && schema._def.typeName === 'ZodObject') {
-        // Use type assertion to handle the shape property
-        const objectSchema = schema;
-        return Object.entries(objectSchema.shape).flatMap(([key, subschema])=>{
+    if (schema instanceof zod.z.ZodObject) {
+        return Object.entries(schema.shape).flatMap(([key, subschema])=>{
             const fullKey = prefix ? `${prefix}.${key}` : key;
             const nested = listZodKeys(subschema, fullKey);
             return nested.length ? nested : fullKey;
@@ -1504,7 +1500,7 @@ class ConfigurationError extends Error {
 };
 /**
  * Type guard to check if a value is a plain object (not array, null, or other types).
- * 
+ *
  * @param value - The value to check
  * @returns True if the value is a plain object
  */ const isPlainObject = (value)=>{
@@ -1552,26 +1548,26 @@ class ConfigurationError extends Error {
 };
 /**
  * Validates that the configuration object contains only keys allowed by the schema.
- * 
+ *
  * This function prevents configuration errors by detecting typos or extra keys
  * that aren't defined in the Zod schema. It intelligently handles:
  * - ZodRecord types that accept arbitrary keys
  * - Nested objects and their key structures
  * - Arrays and their element key structures
- * 
+ *
  * The function throws a ConfigurationError if extra keys are found, providing
  * helpful information about what keys are allowed vs. what was found.
- * 
+ *
  * @param mergedSources - The merged configuration object to validate
  * @param fullSchema - The complete Zod schema including base and user schemas
  * @param logger - Logger for error reporting
  * @throws {ConfigurationError} When extra keys are found that aren't in the schema
- * 
+ *
  * @example
  * ```typescript
  * const schema = z.object({ name: z.string(), age: z.number() });
  * const config = { name: 'John', age: 30, typo: 'invalid' };
- * 
+ *
  * checkForExtraKeys(config, schema, console);
  * // Throws: ConfigurationError with details about 'typo' being an extra key
  * ```
@@ -1582,18 +1578,16 @@ class ConfigurationError extends Error {
     const recordPrefixes = new Set();
     // Find all prefixes that are ZodRecord types
     const findRecordPrefixes = (schema, prefix = '')=>{
-        if (schema._def && (schema._def.typeName === 'ZodOptional' || schema._def.typeName === 'ZodNullable')) {
-            const unwrappable = schema;
-            findRecordPrefixes(unwrappable.unwrap(), prefix);
+        if (schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable) {
+            findRecordPrefixes(schema.unwrap(), prefix);
             return;
         }
-        if (schema._def && (schema._def.typeName === 'ZodAny' || schema._def.typeName === 'ZodRecord')) {
+        if (schema instanceof zod.z.ZodAny || schema instanceof zod.z.ZodRecord) {
             if (prefix) recordPrefixes.add(prefix);
             return;
         }
-        if (schema._def && schema._def.typeName === 'ZodObject') {
-            const objectSchema = schema;
-            Object.entries(objectSchema.shape).forEach(([key, subschema])=>{
+        if (schema instanceof zod.z.ZodObject) {
+            Object.entries(schema.shape).forEach(([key, subschema])=>{
                 const fullKey = prefix ? `${prefix}.${key}` : key;
                 findRecordPrefixes(subschema, fullKey);
             });
@@ -1620,11 +1614,11 @@ class ConfigurationError extends Error {
 };
 /**
  * Validates that a configuration directory exists and is accessible.
- * 
+ *
  * This function performs file system checks to ensure the configuration
  * directory can be used. It handles the isRequired flag to determine
  * whether a missing directory should cause an error or be silently ignored.
- * 
+ *
  * @param configDirectory - Path to the configuration directory
  * @param isRequired - Whether the directory must exist
  * @param logger - Optional logger for debug information
@@ -1647,30 +1641,30 @@ class ConfigurationError extends Error {
 };
 /**
  * Validates a configuration object against the combined Zod schema.
- * 
+ *
  * This is the main validation function that:
  * 1. Validates the configuration directory (if config feature enabled)
  * 2. Combines the base ConfigSchema with user-provided schema shape
  * 3. Checks for extra keys not defined in the schema
  * 4. Validates all values against their schema definitions
  * 5. Provides detailed error reporting for validation failures
- * 
+ *
  * The validation is comprehensive and catches common configuration errors
  * including typos, missing required fields, wrong types, and invalid values.
- * 
+ *
  * @template T - The Zod schema shape type for configuration validation
  * @param config - The merged configuration object to validate
  * @param options - Cardigantime options containing schema, defaults, and logger
  * @throws {ConfigurationError} When configuration validation fails
  * @throws {FileSystemError} When configuration directory validation fails
- * 
+ *
  * @example
  * ```typescript
  * const schema = z.object({
  *   apiKey: z.string().min(1),
  *   timeout: z.number().positive(),
  * });
- * 
+ *
  * await validate(config, {
  *   configShape: schema.shape,
  *   defaults: { configDirectory: './config', isRequired: true },
@@ -1703,18 +1697,17 @@ class ConfigurationError extends Error {
 };
 
 /**
- * Extracts default values from a Zod schema recursively.
- * 
- * This function traverses a Zod schema and builds an object containing
- * all the default values defined in the schema. It handles:
- * - ZodDefault types with explicit default values
- * - ZodOptional/ZodNullable types by unwrapping them
- * - ZodObject types by recursively processing their shape
- * - ZodArray types by providing an empty array as default
- * 
+ * Extracts default values from a Zod schema recursively using Zod v4's parsing mechanisms.
+ *
+ * This function leverages Zod's own parsing behavior to extract defaults rather than
+ * accessing internal properties. It works by:
+ * 1. For ZodDefault types: parsing undefined to trigger the default
+ * 2. For ZodObject types: creating a minimal object and parsing to get all defaults
+ * 3. For wrapped types: unwrapping and recursing
+ *
  * @param schema - The Zod schema to extract defaults from
  * @returns An object containing all default values from the schema
- * 
+ *
  * @example
  * ```typescript
  * const schema = z.object({
@@ -1726,68 +1719,72 @@ class ConfigurationError extends Error {
  *     port: z.number().default(5432)
  *   })
  * });
- * 
+ *
  * const defaults = extractSchemaDefaults(schema);
  * // Returns: { name: 'app', port: 3000, debug: false, database: { host: 'localhost', port: 5432 } }
  * ```
  */ const extractSchemaDefaults = (schema)=>{
-    // Handle ZodDefault - extract the default value
-    if (schema._def && schema._def.typeName === 'ZodDefault') {
-        const defaultSchema = schema;
-        return defaultSchema._def.defaultValue();
-    }
-    // Handle ZodOptional and ZodNullable - only recurse if there's an explicit default
-    if (schema._def && (schema._def.typeName === 'ZodOptional' || schema._def.typeName === 'ZodNullable')) {
-        const unwrappable = schema;
-        const unwrapped = unwrappable.unwrap();
-        // Only provide defaults if the unwrapped schema has explicit defaults
-        // This prevents optional arrays/objects from automatically getting [] or {} defaults
-        if (unwrapped._def && unwrapped._def.typeName === 'ZodDefault') {
-            return extractSchemaDefaults(unwrapped);
+    // Handle ZodDefault - parse undefined to get the default value
+    if (schema instanceof zod.z.ZodDefault) {
+        try {
+            return schema.parse(undefined);
+        } catch  {
+            // If parsing undefined fails, return undefined
+            return undefined;
         }
-        // For optional fields without explicit defaults, return undefined
-        return undefined;
-    }
-    // Handle ZodObject - recursively process shape
-    if (schema._def && schema._def.typeName === 'ZodObject') {
-        const objectSchema = schema;
-        const result = {};
-        for (const [key, subschema] of Object.entries(objectSchema.shape)){
+    }
+    // Handle ZodOptional and ZodNullable by unwrapping
+    if (schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable) {
+        return extractSchemaDefaults(schema.unwrap());
+    }
+    // Handle ZodObject - create an object with defaults by parsing an empty object
+    if (schema instanceof zod.z.ZodObject) {
+        const defaults = {};
+        const shape = schema.shape;
+        // First, try to extract defaults from individual fields
+        for (const [key, subschema] of Object.entries(shape)){
             const defaultValue = extractSchemaDefaults(subschema);
             if (defaultValue !== undefined) {
-                result[key] = defaultValue;
+                defaults[key] = defaultValue;
             }
         }
-        return Object.keys(result).length > 0 ? result : undefined;
+        // Then parse an empty object to trigger any schema-level defaults
+        const result = schema.safeParse({});
+        if (result.success) {
+            // Merge the parsed result with our extracted defaults
+            return {
+                ...defaults,
+                ...result.data
+            };
+        }
+        return Object.keys(defaults).length > 0 ? defaults : undefined;
     }
-    // Handle ZodArray - provide empty array as default
-    if (schema._def && schema._def.typeName === 'ZodArray') {
-        const arraySchema = schema;
-        const elementDefaults = extractSchemaDefaults(arraySchema.element);
-        // Return an empty array, or an array with one example element if it has defaults
+    // Handle ZodArray - return empty array as a reasonable default
+    if (schema instanceof zod.z.ZodArray) {
+        const elementDefaults = extractSchemaDefaults(schema.element);
         return elementDefaults !== undefined ? [
             elementDefaults
         ] : [];
     }
-    // Handle ZodRecord - provide empty object as default
-    if (schema._def && schema._def.typeName === 'ZodRecord') {
+    // Handle ZodRecord - return empty object as default
+    if (schema instanceof zod.z.ZodRecord) {
         return {};
     }
-    // For other types, return undefined (no default available)
+    // No default available for other schema types
     return undefined;
 };
 /**
  * Generates a complete configuration object with all default values populated.
- * 
+ *
  * This function combines the base ConfigSchema with a user-provided schema shape
  * and extracts all available default values to create a complete configuration
  * example that can be serialized to YAML.
- * 
+ *
  * @template T - The Zod schema shape type
  * @param configShape - The user's configuration schema shape
  * @param configDirectory - The configuration directory to include in the defaults
  * @returns An object containing all default values suitable for YAML serialization
- * 
+ *
  * @example
  * ```typescript
  * const shape = z.object({
@@ -1795,7 +1792,7 @@ class ConfigurationError extends Error {
  *   timeout: z.number().default(5000).describe('Request timeout in milliseconds'),
  *   features: z.array(z.string()).default(['auth', 'logging'])
  * }).shape;
- * 
+ *
  * const config = generateDefaultConfig(shape, './config');
  * // Returns: { timeout: 5000, features: ['auth', 'logging'] }
  * // Note: apiKey is not included since it has no default
@@ -1939,7 +1936,7 @@ class ConfigurationError extends Error {
 # Modify the values below to customize your application's behavior.
 #
 # For more information about Cardigantime configuration:
-# https://github.com/SemicolonAmbulance/cardigantime
+# https://tobrien.github.io/cardigantime/
 
 `;
         const finalContent = header + yamlContent;