configorama 0.6.7 → 0.6.9

package/src/main.js

@@ -1,7 +1,7 @@
 const os = require('os')
 const path = require('path')
 const fs = require('fs')
-/*
+/* // disable logs to find broken tests
 console.log = () => {}
 // process.exit(1)
 /** */
@@ -91,7 +91,7 @@ const logLines = '────────────────────
 let DEBUG = process.argv.includes('--debug') ? true : false
 let VERBOSE = process.argv.includes('--verbose') ? true : false
 // DEBUG = true
-
+let DEBUG_TYPE = false
 const ENABLE_FUNCTIONS = true
 
 function combineRegexes(regexes) {
@@ -104,6 +104,136 @@ function combineRegexes(regexes) {
   return new RegExp(`(${patterns.join('|')})`)
 }
 
+/**
+ * Preprocess config to fix malformed fallback references
+ * @param {Object} configObject - The parsed configuration object
+ * @param {RegExp} variableSyntax - The variable syntax regex to use
+ * @returns {Object} The preprocessed configuration object
+ */
+function preProcess(configObject, variableSyntax) {
+  // Known reference prefixes that should be wrapped in ${}
+  const refPrefixes = ['self:', 'opt:', 'env:', 'file:', 'text:', 'deep:']
+
+  /**
+   * Fix malformed fallback references in a string
+   * @param {string} str - String potentially containing variables
+   * @returns {string} String with fixed fallback references
+   */
+  function fixFallbacksInString(str) {
+    if (typeof str !== 'string') return str
+
+    let result = str
+    let changed = true
+
+    // Keep iterating until no more changes (to handle nested variables)
+    while (changed) {
+      changed = false
+
+      // Find innermost ${...} blocks (ones that don't contain other ${)
+      let i = 0
+      while (i < result.length) {
+        if (result[i] === '$' && result[i + 1] === '{') {
+          const start = i
+          let braceCount = 1
+          let j = i + 2
+
+          // Find the matching closing brace by counting { and }
+          while (j < result.length && braceCount > 0) {
+            if (result[j] === '{') {
+              braceCount++
+            } else if (result[j] === '}') {
+              braceCount--
+            }
+            j++
+          }
+
+          if (braceCount === 0) {
+            const end = j
+            const match = result.substring(start, end)
+            const content = result.substring(start + 2, end - 1)
+
+            // Only process if there's a comma (indicating fallback syntax)
+            if (content.includes(',')) {
+              // Split by comma
+              const parts = splitByComma(content, variableSyntax)
+
+              if (parts.length > 1) {
+                // Check if the first part has nested ${} - if so, skip this (process inner ones first)
+                const firstPart = parts[0]
+                if (firstPart.includes('${')) {
+                  i = start + 2 // Move past ${ to find inner variables
+                  continue
+                }
+
+                // Check each part after the first (these are fallback values)
+                const fixed = parts.map((part, index) => {
+                  if (index === 0) {
+                    return part // Keep the main reference as-is
+                  }
+
+                  const trimmed = part.trim()
+
+                  // Check if this looks like a reference but is not wrapped
+                  const looksLikeRef = refPrefixes.some(prefix => trimmed.startsWith(prefix))
+                  const alreadyWrapped = trimmed.startsWith('${') && trimmed.endsWith('}')
+
+                  if (looksLikeRef && !alreadyWrapped) {
+                    return ` \${${trimmed}}`
+                  }
+
+                  return ` ${trimmed}`
+                })
+
+                const replacement = `\${${fixed.join(',')}}`
+                if (replacement !== match) {
+                  result = result.substring(0, start) + replacement + result.substring(end)
+                  changed = true
+                  break // Restart search from beginning
+                }
+              }
+            }
+
+            i = start + 2 // Move past ${ to continue searching for nested variables
+          } else {
+            i++
+          }
+        } else {
+          i++
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Recursively traverse and fix the config object
+   */
+  function traverseAndFix(obj) {
+    if (typeof obj === 'string') {
+      return fixFallbacksInString(obj)
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map(item => traverseAndFix(item))
+    }
+
+    if (obj !== null && typeof obj === 'object') {
+      const result = {}
+      for (const key in obj) {
+        if (obj.hasOwnProperty(key)) {
+          result[key] = traverseAndFix(obj[key])
+        }
+      }
+      return result
+    }
+
+    return obj
+  }
+
+  return traverseAndFix(configObject)
+}
+
 class Configorama {
   constructor(fileOrObject, opts) {
     /* attach sig events on async calls */
@@ -124,6 +254,9 @@ class Configorama {
 
     this.foundVariables = []
 
+    // Track variable resolutions for metadata (keyed by path)
+    this.resolutionTracking = {}
+
     const defaultSyntax = '\\${((?!AWS|stageVariables)[ ~:a-zA-Z0-9=+!@#%*<>?._\'",|\\-\\/\\(\\)\\\\]+?)}'
   
     const varSyntax = options.syntax || defaultSyntax
@@ -226,8 +359,7 @@ class Configorama {
         prefix: 'file',
         match: fileRefSyntax,
         resolver: (varString, o, x, pathValue) => {
-          // console.log('pathValue getValueFromFile', pathValue)
-          return this.getValueFromFile(varString)
+          return this.getValueFromFile(varString, { context: pathValue })
         },
       },
 
@@ -237,7 +369,7 @@ class Configorama {
         prefix: 'text',
         match: textRefSyntax,
         resolver: (varString, o, x, pathValue) => {
-          return this.getValueFromFile(varString, { asRawText: true })
+          return this.getValueFromFile(varString, { asRawText: true, context: pathValue })
         },
       },
 
@@ -258,7 +390,7 @@ class Configorama {
         match: deepRefSyntax,
         resolver: (varString, o, x, pathValue) => {
           // console.log('>>>>>getValueFromDeep', varString)
-          return this.getValueFromDeep(varString)
+          return this.getValueFromDeep(varString, pathValue)
         },
       },
       // Numbers
@@ -463,7 +595,7 @@ class Configorama {
 
     // If we have a file path but no config yet, parse it now
     if (this.configFilePath && !this.config) {
-      const configObject = await parseFileContents(
+      let configObject = await parseFileContents(
         this.originalString,
         this.configFileType,
         this.configFilePath,
@@ -474,6 +606,16 @@ class Configorama {
       if (VERBOSE || showFoundVariables) {
         this.configFileContents = fs.readFileSync(this.configFilePath, 'utf8')
       }
+      /*
+      console.log('before preprocess', configObject)
+      /** */
+      /* Preprocess step here */
+      configObject = preProcess(configObject, this.variableSyntax)
+      /*
+      console.log('after preprocess', configObject)
+      /** */
+      //process.exit(1)
+
       this.config = configObject
       this.originalConfig = cloneDeep(configObject)
     }
@@ -489,106 +631,17 @@ class Configorama {
     const variablesKnownTypes = this.variablesKnownTypes
 
     if (VERBOSE || showFoundVariables) {
-      const foundVariables = []
-      const variableData = {}
-      let matchCount = 1
-      // console.log('this.originalConfig', this.originalConfig)
-      traverse(this.originalConfig).forEach(function (rawValue) {
-        if (typeof rawValue === 'string' && rawValue.match(variableSyntax)) {
-          const configValuePath = this.path.join('.')
-          if (configValuePath.endsWith('Fn::Sub')) {
-            return
-          }
-      
-          const nested = findNestedVariables(rawValue, variableSyntax, variablesKnownTypes, configValuePath)
-          /*
-          console.log('traverse nested result', nested)
-          /** */
-          
-          // console.log(`▷ Path: ${configValuePath}`)
-          // console.log('\n  Key/value:')
-          // console.log(`  ${configValuePath}: ${rawValue}`)
-          const lastItem = nested[nested.length - 1]
-          const lastKeyPath = this.path[this.path.length - 1]
-          const itemKey = (lastKeyPath.match(/[\d+]$/)) ? `${this.path[this.path.length - 2]}[${lastKeyPath}]` : lastKeyPath
-          const key = lastItem.fullMatch
-          const varData = {
-            path: configValuePath,
-            key: itemKey,
-            value: rawValue,
-            variable: lastItem.fullMatch,
-            isRequired: false,
-            defaultValue: undefined,
-            matchIndex: matchCount++,
-            // hasFallback: false,
-            resolveOrder: [],
-            resolveDetails: nested,
-          }
-          let defaultValueIsVar = false
-          function calculateResolveOrder(item) {
-            if (item && item.fallbackValues) {
-              let hasResolvedFallback
-              // console.log('item.fallbackValues', item.fallbackValues)
-              const order = ([item.valueBeforeFallback]).concat(item.fallbackValues.map((f, i) => {
-                // console.log('f', f)
-                if (f.fallbackValues) {
-                  const [nestedOrder, nestedResolvedFallback] = calculateResolveOrder(f)
-                  // console.log('nestedOrder', nestedOrder)
-                  // console.log('nestedResolvedFallback', nestedResolvedFallback)
-                  if (!hasResolvedFallback && nestedResolvedFallback) {
-                    hasResolvedFallback = nestedResolvedFallback
-                  }
-                  return nestedOrder // Return just the order part
-                }
-        
-                if (!hasResolvedFallback && f.isResolvedFallback) {
-                  hasResolvedFallback = f.stringValue
-                }
-                if (f.isResolvedFallback) {
-                  hasResolvedFallback = f.stringValue
-                }
-
-                if (!hasResolvedFallback && f.isVariable) {
-                  defaultValueIsVar = f
-                }
-                // console.log('hasResolvedFallback', hasResolvedFallback)
-                return `${f.stringValue || f.variable}${f.isResolvedFallback ? ' (Resolved default fallback)' : ''}`
-              })).flat()
-              
-              return [order, hasResolvedFallback]
-            }
-            return [[item.variable], undefined] // Return array instead of just the value
-          }
-
-          const [resolveOrder, hasResolvedFallback] = calculateResolveOrder(lastItem)
-          varData.resolveOrder = resolveOrder
-          
-          if (defaultValueIsVar) {
-            varData.defaultValueIsVar = defaultValueIsVar
-          }
-
-          // console.log('hasResolvedFallback', hasResolvedFallback)
-          if (typeof hasResolvedFallback !== 'undefined') {
-            varData.defaultValue = hasResolvedFallback
-          }
-
-          // console.log('varData.defaultValue', varData.defaultValue)
-          if (typeof varData.defaultValue === 'undefined') {
-            varData.isRequired = true
-          }
-      
-          if (varData.resolveOrder.length > 1) {
-            varData.hasFallback = true
-          }
-          //console.log('varData', varData)
-
-          variableData[key] = (variableData[key] || []).concat(varData)
-
-          foundVariables.push(rawValue)
-        }
-      })
+      // Use collectVariableMetadata to get variable info (DRY - don't duplicate logic)
+      const metadata = this.collectVariableMetadata()
+      /*
+      deepLog('metadata', metadata)
+      process.exit(1)
+      /** */
+    
+      const variableData = metadata.variables
+      const varKeys = Object.keys(variableData)
 
-      if (!foundVariables.length) {
+      if (!varKeys.length) {
         logHeader('No Variables Found in Config')
         if (this.configFilePath) {
           console.log(`File: ${this.configFilePath}`)
@@ -611,10 +664,7 @@ class Configorama {
         console.log()
       }
 
-      // make foundVariables array unique
-      const finalFoundVariables = [...new Set(foundVariables)]
-      if (finalFoundVariables.length > 0) {
-        const varKeys = Object.keys(variableData)
+      if (varKeys.length > 0) {
         const fileName = this.configFilePath ? ` in ${this.configFilePath}` : ''
 
         logHeader(`Found ${varKeys.length} Variables${fileName}`)
@@ -626,9 +676,34 @@ class Configorama {
           const longestKey = varKeys.reduce((acc, k) => {
             return Math.max(acc, k.length)
           }, 0)
+          // Count all references including nested ones within other variables
+          const countAllReferences = (targetVariable) => {
+            // Start with direct references
+            let count = variableData[targetVariable].length
+
+            // Check all other variables for nested references to this variable
+            varKeys.forEach((otherKey) => {
+              if (otherKey === targetVariable) return
+
+              variableData[otherKey].forEach((instance) => {
+                if (instance.resolveDetails) {
+                  instance.resolveDetails.forEach((detail) => {
+                    // Check if this resolveDetail references our target variable
+                    if (detail.fullMatch === targetVariable) {
+                      count++
+                    }
+                  })
+                }
+              })
+            })
+
+            return count
+          }
+
           console.log(varKeys.map((k) => {
-            const placesWord = variableData[k].length > 1 ? 'places' : 'place'
-            return `- ${k.padEnd(longestKey).padEnd(longestKey + 10)} referenced ${variableData[k].length} ${placesWord}`
+            const refCount = countAllReferences(k)
+            const placesWord = refCount > 1 ? 'places' : 'place'
+            return `- ${k.padEnd(longestKey).padEnd(longestKey + 10)} referenced ${refCount} ${placesWord}`
           }).join('\n'))
           console.log()
         }
@@ -697,7 +772,9 @@ class Configorama {
                 firstInstance.defaultValue = truncatedString
               } else {
                 deepLog('Missing default var', firstInstance)
-                throw new Error(`Variable misconfiguration at ${firstInstance.variable}\n\n"${hasDotPropOrSelf[0].variable}" resolves to undefined value.\n`)
+                throw new Error(
+                  `Variable misconfiguration at ${firstInstance.variable}\n\n"${hasDotPropOrSelf[0].variable}" resolves to undefined value.\n`
+                )
               }
             }
             //this.originalConfig[key] = undefined
@@ -802,6 +879,7 @@ class Configorama {
           return this.populateObjectImpl(this.config).finally(() => {
             // TODO populate function values here?
             // console.log('Final Config', this.config)
+            // console.log(this.deep)
             const transform = this.runFunction.bind(this)
             const varSyntax = this.variableSyntax
             const leaves = this.leaves
@@ -812,7 +890,9 @@ class Configorama {
               /* Pass through unknown variables */
               if (!configoramaOpts.allowUndefinedValues && typeof rawValue === 'undefined') {
                 const configValuePath = this.path.join('.')
+                /*
                 console.log(this.path)
+                /** */
                 const ogValue = dotProp.get(originalConfig, configValuePath)
                 const varDisplay = ogValue ? `"${ogValue}" variable` : 'variable'
 
@@ -889,6 +969,214 @@ class Configorama {
         })
     })
   }
+
+  /**
+   * Collect metadata about all variables found in the configuration
+   * @returns {object} Metadata object containing variables, fileRefs, and summary
+   */
+  collectVariableMetadata() {
+    const variableSyntax = this.variableSyntax
+    const variablesKnownTypes = this.variablesKnownTypes
+    const foundVariables = []
+    const variableData = {}
+    const fileRefs = []
+    const fileGlobPatterns = []
+    let matchCount = 1
+
+    traverse(this.originalConfig).forEach(function (rawValue) {
+      if (typeof rawValue === 'string' && rawValue.match(variableSyntax)) {
+        const configValuePath = this.path.join('.')
+        /* Skip Fn::Sub variables */
+        if (configValuePath.endsWith('Fn::Sub')) {
+          return
+        }
+
+        const nested = findNestedVariables(rawValue, variableSyntax, variablesKnownTypes, configValuePath)
+
+        const lastItem = nested[nested.length - 1]
+        const lastKeyPath = this.path[this.path.length - 1]
+        const itemKey = (lastKeyPath.match(/[\d+]$/)) ? `${this.path[this.path.length - 2]}[${lastKeyPath}]` : lastKeyPath
+        const key = lastItem.fullMatch
+        const varData = {
+          path: configValuePath,
+          key: itemKey,
+          value: rawValue,
+          variable: lastItem.fullMatch,
+          isRequired: false,
+          defaultValue: undefined,
+          matchIndex: matchCount++,
+          resolveOrder: [],
+          resolveDetails: nested,
+        }
+        let defaultValueIsVar = false
+
+        function calculateResolveOrder(item) {
+          if (item && item.fallbackValues) {
+            let hasResolvedFallback
+            const order = ([item.valueBeforeFallback]).concat(item.fallbackValues.map((f, i) => {
+              if (f.fallbackValues) {
+                const [nestedOrder, nestedResolvedFallback] = calculateResolveOrder(f)
+                if (!hasResolvedFallback && nestedResolvedFallback) {
+                  hasResolvedFallback = nestedResolvedFallback
+                }
+                return nestedOrder
+              }
+
+              if (!hasResolvedFallback && f.isResolvedFallback) {
+                hasResolvedFallback = f.stringValue
+              }
+              if (f.isResolvedFallback) {
+                hasResolvedFallback = f.stringValue
+              }
+
+              if (!hasResolvedFallback && f.isVariable) {
+                defaultValueIsVar = f
+              }
+              return `${f.stringValue || f.variable}${f.isResolvedFallback ? ' (Resolved default fallback)' : ''}`
+            })).flat()
+
+            return [order, hasResolvedFallback]
+          }
+          return [[item.variable], undefined]
+        }
+
+        const [resolveOrder, hasResolvedFallback] = calculateResolveOrder(lastItem)
+        varData.resolveOrder = resolveOrder
+
+        if (defaultValueIsVar) {
+          varData.defaultValueIsVar = defaultValueIsVar
+        }
+
+        if (typeof hasResolvedFallback !== 'undefined') {
+          varData.defaultValue = hasResolvedFallback
+        }
+
+        if (typeof varData.defaultValue === 'undefined') {
+          varData.isRequired = true
+        }
+
+        if (varData.resolveOrder.length > 1) {
+          varData.hasFallback = true
+        }
+
+        // Extract file references
+        nested.forEach((detail) => {
+          if (detail.varType && 
+             (detail.varType.startsWith('file(') || detail.varType.startsWith('text('))
+          ) {
+            const fileMatch = detail.varType.match(/^(?:file|text)\((.*?)\)/)
+            if (fileMatch && fileMatch[1]) {
+              let fileContent = fileMatch[1].trim()
+              
+              // Split by comma to separate file path from parameters/fallback values
+              const parts = splitCsv(fileContent)
+              let filePath = parts[0].trim()
+              
+              // Remove quotes if present
+              filePath = filePath.replace(/^['"]|['"]$/g, '')
+              
+              // Normalize path: ensure relative paths start with ./
+              let normalizedPath = filePath
+              if (
+                !filePath.startsWith('./') && 
+                !filePath.startsWith('../') && 
+                !filePath.startsWith('/') && 
+                !filePath.startsWith('~')
+              ) {
+                normalizedPath = './' + filePath
+              }
+
+              // file .// 
+              if (normalizedPath.startsWith('.//')) {
+                normalizedPath = normalizedPath.replace('.//', './')
+              }
+              
+              // Handle variables in file paths - just record the pattern
+              if (!fileRefs.includes(normalizedPath)) {
+                fileRefs.push(normalizedPath)
+              }
+              
+              // Check if path contains variables and create glob pattern
+              if (normalizedPath.match(variableSyntax)) {
+                // Replace variable syntax ${...} with * for glob pattern
+                const globPattern = normalizedPath.replace(variableSyntax, '*')
+                if (!fileGlobPatterns.includes(globPattern)) {
+                  fileGlobPatterns.push(globPattern)
+                }
+              }
+            }
+          }
+        })
+
+        variableData[key] = (variableData[key] || []).concat(varData)
+        foundVariables.push(rawValue)
+      }
+    })
+
+    // Make foundVariables array unique
+    const finalFoundVariables = [...new Set(foundVariables)]
+    const varKeys = Object.keys(variableData)
+
+    // Calculate summary using same logic as CLI display
+    let requiredCount = 0
+    let withDefaultsCount = 0
+    varKeys.forEach((key) => {
+      const instances = variableData[key]
+      const firstInstance = instances[0]
+
+      // Check if truly required using same logic as display code
+      let isTrulyRequired = false
+      if (typeof firstInstance.defaultValue === 'undefined') {
+        // Check for self-references that resolve to config values
+        let dotPropArr = []
+        if (firstInstance.defaultValueIsVar && (
+          firstInstance.defaultValueIsVar.varType === 'self:' ||
+          firstInstance.defaultValueIsVar.varType === 'dot.prop'
+        )) {
+          dotPropArr = [firstInstance.defaultValueIsVar]
+        }
+
+        const hasDotPropOrSelf = instances.reduce((acc, v) => {
+          const dotProp = v.resolveDetails.find((d) => d.varType === 'dot.prop')
+          if (dotProp) {
+            acc.push(dotProp)
+          }
+          if (v.resolveDetails && v.resolveDetails.length === 1 && v.resolveDetails[0].varType === 'self:') {
+            acc.push(v.resolveDetails[0])
+          }
+          return acc
+        }, dotPropArr)
+
+        if (!hasDotPropOrSelf.length) {
+          isTrulyRequired = true
+        } else {
+          // Check if the self-reference resolves to a value
+          const cleanPath = hasDotPropOrSelf[0].variable.replace('self:', '')
+          const dotPropValue = dotProp.get(this.originalConfig, cleanPath)
+          if (typeof dotPropValue === 'undefined') {
+            isTrulyRequired = true
+          }
+        }
+      }
+
+      if (isTrulyRequired) {
+        requiredCount++
+      } else {
+        withDefaultsCount++
+      }
+    })
+
+    return {
+      variables: variableData,
+      summary: {
+        totalVariables: varKeys.length,
+        requiredVariables: requiredCount,
+        variablesWithDefaults: withDefaultsCount
+      },
+      fileRefs: fileRefs,
+      fileGlobPatterns: fileGlobPatterns,
+    }
+  }
   runFunction(variableString) {
     // console.log('runFunction', variableString)
     /* If json object value return it */
@@ -918,7 +1206,6 @@ class Configorama {
       argsToPass = formatFunctionArgs(splitter)
     }
     // console.log('argsToPass runFunction', argsToPass)
-
     // TODO check for camelCase version. | toUpperCase messes with function name
     const theFunction = this.functions[functionName] || this.functions[functionName.toLowerCase()]
 
@@ -1016,6 +1303,15 @@ class Configorama {
         }
       }
       leaf.originalSource = originalValue
+
+      // Check if we have existing resolution history from previous iterations
+      const pathKey = thePath
+      if (this.resolutionTracking[pathKey] && this.resolutionTracking[pathKey].resolutionHistory) {
+        leaf.resolutionHistory = this.resolutionTracking[pathKey].resolutionHistory
+      } else {
+        leaf.resolutionHistory = []
+      }
+
       if (originalValue && isString(originalValue)) {
         const varString = cleanVariable(originalValue, this.variableSyntax, true, `getProperties ${this.callCount}`)
         if (varString.match(fileRefSyntax)) {
@@ -1027,7 +1323,6 @@ class Configorama {
     }
     return results
   }
-
   /**
    * @typedef {TerminalProperty} TerminalPropertyPopulated
    * @property {Object} populated The populated value of the value at the path
@@ -1044,11 +1339,9 @@ class Configorama {
       // Initial check if value has variable string in it
       return isString(property.value) && property.value.match(this.variableSyntax)
     })
-
     /*
     console.log(`variables at call count ${this.callCount}`, variables)
     /** */
-
     /* Exclude git messages from being processed */
     // Was failing on git msgs like "xyz cron:pattern to cron(pattern) for improved clarity"
     if (this.callCount > 1) {
@@ -1060,7 +1353,6 @@ class Configorama {
         return true
       })
     }
-
     return map(variables, (valueObject) => {
       // console.log('valueObject', valueObject)
       return this.populateValue(valueObject, false, '_populateVariables').then((populated) => {
@@ -1163,16 +1455,127 @@ class Configorama {
    */
   renderMatches(valueObject, matches, results) {
     /*
+    console.log('valueObject', valueObject)
     console.log('RENDER', matches)
     console.log('RESULTS', results)
     /** */
+
+    /* Attach data to valueObject for parent details */
+    if (matches.length === 1) {
+      valueObject.currentVarDetails = matches[0]
+      valueObject.currentVarDetails.result = results[0]
+
+      // Extract metadata from result if present
+      let actualResult = results[0]
+      let resolverType = undefined
+      if (results[0] && typeof results[0] === 'object') {
+        if (results[0].__internal_metadata) {
+          actualResult = results[0].value
+          resolverType = results[0].__resolverType
+        } else if (results[0].__internal_only_flag) {
+          // Don't extract value from __internal_only_flag objects, but grab resolverType if present
+          actualResult = results[0]
+          resolverType = results[0].__resolverType
+        }
+      }
+      // valueObject.currentVarDetails.varType = results[0].__resolverType
+
+      // Track resolution history
+      if (!valueObject.resolutionHistory) {
+        valueObject.resolutionHistory = []
+      }
+      
+      // Extract clean result to avoid circular references
+      // For __internal_only_flag objects (like deep resolver results), extract the value
+      // For real data objects (like file contents), keep them as-is
+      let cleanResult = actualResult
+      if (actualResult && typeof actualResult === 'object' && actualResult.__internal_only_flag) {
+        cleanResult = actualResult.value
+      }
+      
+      const historyEntry = {
+        match: matches[0].match,
+        variable: matches[0].variable,
+        result: cleanResult,
+        resultType: typeof cleanResult,
+        valueBeforeResolution: valueObject.value,
+      }
+      if (resolverType) {
+        historyEntry.varType = resolverType
+      }
+
+      // Check if variable has fallback values (comma-separated)
+      const variableParts = splitByComma(matches[0].variable)
+      if (variableParts.length > 1) {
+        historyEntry.hasFallback = true
+        historyEntry.valueBeforeFallback = variableParts[0]
+        historyEntry.fallbackValues = variableParts.slice(1).map((fallback) => {
+          const trimmedFallback = fallback.trim()
+          // Check if it's a variable reference
+          const isVariable = trimmedFallback.match(this.variableSyntax) || trimmedFallback.match(this.variablesKnownTypes)
+          const fallbackData = {
+            isVariable: !!isVariable,
+            fullMatch: trimmedFallback,
+            variable: trimmedFallback,
+          }
+
+          // If it's a literal string/number, parse it
+          if (!isVariable) {
+            // Check if it's a quoted string
+            if (/^["'].*["']$/.test(trimmedFallback)) {
+              fallbackData.stringValue = trimmedFallback.replace(/^["']|["']$/g, '')
+              fallbackData.isResolvedFallback = true
+            } else if (/^-?\d+(\.\d+)?$/.test(trimmedFallback)) {
+              // It's a number
+              fallbackData.numberValue = parseFloat(trimmedFallback)
+              fallbackData.isResolvedFallback = true
+            } else {
+              fallbackData.stringValue = trimmedFallback
+              fallbackData.isResolvedFallback = true
+            }
+          } else {
+            // Extract varType from variable references
+            const varTypeMatch = trimmedFallback.match(this.variablesKnownTypes)
+            if (varTypeMatch && varTypeMatch[1]) {
+              fallbackData.varType = varTypeMatch[1]
+            }
+          }
+
+          return fallbackData
+        })
+      }
+
+      // Only add to history if not a duplicate (same match + variable)
+      const isDuplicate = valueObject.resolutionHistory.some(entry => 
+        entry.match === historyEntry.match && 
+        entry.variable === historyEntry.variable
+      )
+      
+      if (!isDuplicate) {
+        valueObject.resolutionHistory.push(historyEntry)
+      }
+
+      // Save resolution history to tracking map for persistence across iterations
+      if (valueObject.path && valueObject.path.length) {
+        const pathKey = valueObject.path.join('.')
+        if (!this.resolutionTracking[pathKey]) {
+          this.resolutionTracking[pathKey] = {
+            path: pathKey,
+            originalPropertyString: valueObject.originalSource,
+            calls: []
+          }
+        }
+        this.resolutionTracking[pathKey].resolutionHistory = valueObject.resolutionHistory
+      }
+    }
+
     let result = valueObject.value
     for (let i = 0; i < matches.length; i += 1) {
       this.warnIfNotFound(matches[i].variable, results[i])
       // console.log('Render MATCHES', results[i])
       let valueToPop = results[i]
       // TODO refactor this. __internal_only_flag needed to stop clash with sync/async file resolution
-      if (results[i] && typeof results[i] === 'object' && results[i].__internal_only_flag) {
+      if (results[i] && typeof results[i] === 'object' && (results[i].__internal_only_flag || results[i].__internal_metadata)) {
         valueToPop = results[i].value
       }
       result = this.populateVariable(valueObject, matches[i].match, valueToPop)
@@ -1216,7 +1619,10 @@ class Configorama {
       .then((result) => {
         // console.log('renderMatches result', result)
         if (root && isArray(matches)) {
-          return this.populateValue({ value: result.value }, root, 'self populateValue')
+          return this.populateValue({
+            value: result.value,
+            resolutionHistory: result.resolutionHistory || valueObject.resolutionHistory || []
+          }, root, 'self populateValue')
         }
         return result
       })
@@ -1254,11 +1660,11 @@ class Configorama {
 
     const parts = splitByComma(variable, this.variableSyntax)
     if (DEBUG) {
-      console.log('parts', parts)
-      console.log('parts variable:', variable)
-      console.log('parts originalVar:', originalVar)
-      console.log('parts property:', valueObject)
-      console.log('All parts:', parts)
+      console.log('splitAndGet parts', parts)
+      console.log('splitAndGet parts variable:', variable)
+      console.log('splitAndGet parts originalVar:', originalVar)
+      console.log('splitAndGet parts current valueObject:', valueObject)
+      console.log('splitAndGet All parts:', parts)
       console.log('-----')
     }
     if (parts.length <= 1) {
@@ -1279,16 +1685,20 @@ class Configorama {
   populateVariable(valueObject, matchedString, valueToPopulate) {
     let property = valueObject.value
     // console.log('init property', property)
-    let DEBUG_TYPE = false
+
     if (DEBUG) {
       console.log('────────START populateVar──────────────')
-      console.log('populateVar: valueToPopulate', valueToPopulate)
-      console.log('populateVar: typeof valueToPopulate', typeof valueToPopulate)
-      console.log(`populateVar: path "${valueObject.path}"`)
-      console.log(`populateVar: value \`${valueObject.value}\``)
-      console.log(`populateVar: originalSource \`${valueObject.originalSource}\``)
-      console.log('populateVar: property', property)
-      console.log('populateVar: matchedString', matchedString)
+      console.log('populateVariable: valueObject', valueObject)
+      console.log('populateVariable: valueToPopulate', valueToPopulate)
+      console.log('populateVariable: typeof valueToPopulate', typeof valueToPopulate)
+      console.log(`populateVariable: path "${valueObject.path}"`)
+      console.log(`populateVariable: value \`${valueObject.value}\``)
+      console.log(`populateVariable: originalSource \`${valueObject.originalSource}\``)
+      console.log('populateVariable: property', property)
+      console.log('populateVariable: matchedString', matchedString)
+      if (valueObject.resolutionHistory && valueObject.resolutionHistory.length > 0) {
+        console.log('populateVariable: resolutionHistory', JSON.stringify(valueObject.resolutionHistory, null, 2))
+      }
     }
 
     const originalSrc = valueObject.originalSource || ''
@@ -1307,9 +1717,35 @@ class Configorama {
       if (DEBUG_TYPE) console.log('DEBUG_TYPE total replacement')
       const v = valueObject.value || ''
       property = valueToPopulate
+      // console.log('hasFilters', hasFilters)
+      // console.log('valueToPopulate', valueToPopulate)
+      /* Check resolution history for parent details */
+      if (valueObject.resolutionHistory && valueObject.resolutionHistory.length) {
+        const currentDetails = valueObject.resolutionHistory[valueObject.resolutionHistory.length - 1]
+        
+        // get 2nd to last item in resolution history
+        const parentDetails = valueObject.resolutionHistory[valueObject.resolutionHistory.length - 2]
+        /*
+        console.log('currentDetails', currentDetails)
+        console.log('parentDetails', parentDetails)
+        /** */
+
+        /* Convert a fallback number to string */
+        if (currentDetails && 
+          currentDetails.resultType === 'number' && 
+          parentDetails && parentDetails.resultType === 'string' && 
+          parentDetails.result.match(/^\d+$/) && parentDetails.varType === 'env'
+        ) {
+          if (Number(parentDetails.result) === currentDetails.result) {
+            property = String(valueToPopulate)
+          }
+        }
+
+      }
 
       /* Handle ${self:custom.ref, ''} with deep values */
       if (v.match(deepRefSyntax) && originalSrc.match(this.variableSyntax) && !v.match(/deep\:(\d*)\..*}$/)) {
+        // console.log('deep ref syntax')
         // console.log('deep var', this.deep)
         // console.log('originalSrc', originalSrc)
         // console.log('value', v)
@@ -1412,7 +1848,12 @@ class Configorama {
         missingValue = this.deep[i]
       }
 
-      const cleanVar = cleanVariable(property, this.variableSyntax, true, `populateVariable fallback ${this.callCount}`)
+      const cleanVar = cleanVariable(
+        property,
+        this.variableSyntax,
+        true,
+        `populateVariable fallback ${this.callCount}`
+      )
       const cleanVarNoFilters = cleanVar.split('|')[0]
       const splitVars = splitByComma(cleanVarNoFilters)
       const nestedVar = findNestedVariable(splitVars, valueObject.originalSource)
@@ -1427,6 +1868,7 @@ class Configorama {
           value: fallbackStr,
           path: valueObject.path,
           originalSource: valueObject.originalSource,
+          resolutionHistory: valueObject.resolutionHistory || [],
           // set __internal_only_flag to note this is object we make not a resolved value
           __internal_only_flag: true,
           caller: 'nestedVar',
@@ -1478,6 +1920,7 @@ Missing Value ${missingValue} - ${matchedString}
           value: finalProp, // prop to fix nested ¯\_(ツ)_/¯
           path: valueObject.path,
           originalSource: valueObject.originalSource,
+          resolutionHistory: valueObject.resolutionHistory || [],
           // set __internal_only_flag to note this is object we make not a resolved value
           // __internal_only_flag: true
         }
@@ -1496,13 +1939,15 @@ Missing Value ${missingValue} - ${matchedString}
         }
       }
       */
-      // Does not match file refs with nested vars + args
-      // @TODO fix this for eval refs
-      // console.log('prop', prop)
-      // console.log('func', func)
 
       if (
+        /* Not another variable reference */
+        !prop.match(this.variableSyntax)
+        &&
+        /* Not file or text refs */
         !prop.match(fileRefSyntax) 
+        && !prop.match(textRefSyntax)
+        /* Not eval refs */
         && !prop.match(getValueFromEval.match) 
         // AND is not multiline value
         && (func && prop.split('\n').length < 3)) {
@@ -1523,14 +1968,21 @@ Missing Value ${missingValue} - ${matchedString}
 
     // console.log('foundFilters', foundFilters)
 
-    /* Apply filters if found */
-    //console.log('> property', property)
-    if (
-      foundFilters.length > 0 &&
-      typeof valueToPopulate === 'string' &&
-      !valueToPopulate.match(deepRefSyntax) &&
+    let runFilters = false
+    if (typeof valueToPopulate === 'number' && foundFilters.length) {
+      runFilters = true
+    } else if (
+      typeof valueToPopulate === 'string' && 
+      !valueToPopulate.match(deepRefSyntax) && 
+      foundFilters.length && 
       !property.match(this.variableSyntax)
     ) {
+      runFilters = true
+    }
+
+    /* Apply filters if found */
+    //console.log('> property', property)
+    if (runFilters) {
       // If filter cache exists we need to remove filter that have already been run
       if (this.filterCache[valueObject.path]) {
         foundFilters = foundFilters.filter((filter) => {
@@ -1555,6 +2007,7 @@ Missing Value ${missingValue} - ${matchedString}
       value: property,
       path: valueObject.path,
       originalSource: valueObject.originalSource,
+      resolutionHistory: valueObject.resolutionHistory || [],
       __internal_only_flag: true, // set __internal_only_flag to note this is object we make not a resolved value
       caller: 'end',
       count: this.callCount,
@@ -1596,15 +2049,22 @@ Missing Value ${missingValue} - ${matchedString}
     // console.log('propertyString', typeof propertyString)
     const variableValues = variableStrings.map((variableString) => {
       // This runs on nested variable resolution
-      return this.getValueFromSource(variableString, valueObject, 'overwrite')
+      return this.getValueFromSource(variableString, valueObject, 'overwrite', valueObject.originalSource)
     })
-    
+
     // console.log('variableValues', variableValues)
     return Promise.all(variableValues).then((values) => {
       let deepPropertyStr = propertyString
       let deepProperties = 0
       // console.log('overwrite values', valuesToUse)
-      values.forEach((value, index) => {
+      // Extract actual values from metadata objects
+      const extractedValues = values.map((value) => {
+        if (value && typeof value === 'object' && (value.__internal_only_flag || value.__internal_metadata)) {
+          return value.value
+        }
+        return value
+      })
+      extractedValues.forEach((value, index) => {
         // console.log('───────────────────────────────> value', value)
         if (isString(value) && value.match(this.variableSyntax)) {
           deepProperties += 1
@@ -1620,7 +2080,7 @@ Missing Value ${missingValue} - ${matchedString}
       })
       return deepProperties > 0
         ? Promise.resolve(deepPropertyStr) // return deep variable replacement of original
-        : Promise.resolve(values.find(isValidValue)) // resolve first valid value, else undefined
+        : Promise.resolve(extractedValues.find(isValidValue)) // resolve first valid value, else undefined
     })
   }
   /**
@@ -1632,6 +2092,25 @@ Missing Value ${missingValue} - ${matchedString}
     // console.log('getValueFromSrc caller', caller)
     const propertyString = valueObject.value
     const pathValue = valueObject.path
+
+    // Track every call to getValueFromSource for metadata
+    if (pathValue && pathValue.length) {
+      const pathKey = pathValue.join('.')
+      if (!this.resolutionTracking[pathKey]) {
+        this.resolutionTracking[pathKey] = {
+          path: pathKey,
+          originalPropertyString: propertyString,
+          calls: []
+        }
+      }
+
+      this.resolutionTracking[pathKey].calls.push({
+        variableString: variableString,
+        propertyString: propertyString,
+        caller: caller
+      })
+    }
+
     // console.log('getValueFromSrc propertyString', propertyString)
     // console.log(`tracker contains ${variableString}`, this.tracker.contains(variableString))
     if (this.tracker.contains(variableString)) {
@@ -1642,11 +2121,12 @@ Missing Value ${missingValue} - ${matchedString}
     let newHasFilter
     // Else lookup value from various sources
     if (DEBUG) {
-      console.log(`>>>>> getValueFromSrc() call - ${caller}`)
-      console.log('variableString:', variableString)
-      console.log('propertyString:', propertyString)
-      console.log('pathValue:', pathValue)
-      console.log('valueObject', valueObject)
+      console.log(`>>>>> getValueFromSrc() caller - ${caller}`)
+      console.log('getValueFromSource originalVar', originalVar)
+      console.log('getValueFromSource variableString:', variableString)
+      console.log('getValueFromSource propertyString:', propertyString)
+      console.log('getValueFromSource pathValue:', valueObject.path)
+      console.log('getValueFromSource valueObject:', valueObject)
       console.log('-----')
     }
 
@@ -1674,6 +2154,8 @@ Missing Value ${missingValue} - ${matchedString}
         })
         .map((f) => {
           return trim(f)
+          // TODO refactor this. This is a temp fix for filters with nested vars.
+          .replace(/}$/, '')
         })
       // console.log('filters to run', _filter)
 
@@ -1730,6 +2212,21 @@ Missing Value ${missingValue} - ${matchedString}
         valueObject,
 
       ).then((val) => {
+        // Update the last call with the resolved value
+        if (pathValue && pathValue.length) {
+          const pathKey = pathValue.join('.')
+          if (this.resolutionTracking[pathKey] && this.resolutionTracking[pathKey].calls.length) {
+            // Find the most recent call for this variableString
+            for (let i = this.resolutionTracking[pathKey].calls.length - 1; i >= 0; i--) {
+              if (this.resolutionTracking[pathKey].calls[i].variableString === variableString) {
+                this.resolutionTracking[pathKey].calls[i].resolvedValue = val
+                this.resolutionTracking[pathKey].calls[i].resolverType = resolverType
+                break
+              }
+            }
+          }
+        }
+
         // console.log('VALUE', val)
         if (
           val === null ||
@@ -1763,7 +2260,7 @@ Missing Value ${missingValue} - ${matchedString}
           // console.log('valueCount', valueCount)
           // TODO throw on empty values?
           // No fallback value found AND this is undefined, throw error
-          const nestedVars = findNestedVariables(propertyString, this.variableSyntax)
+          const nestedVars = findNestedVariables(propertyString, this.variableSyntax, this.variablesKnownTypes)
           // console.log('nestedVars', nestedVars)
           const noNestedVars = nestedVars.length < 2
           if (valueCount.length === 1 && noNestedVars) {
@@ -1792,7 +2289,19 @@ Unable to resolve configuration variable
         if (!newHasFilter) {
           // console.log('no newHasFilter', val, valueObject)
           // console.log('> RESOLVER RETURN newValue 3', val, originalVar)
-          return Promise.resolve(val)
+          // Wrap value with resolverType metadata for resolution tracking
+          // But don't wrap if it's already an internal flag object
+          if (val && typeof val === 'object' && val.__internal_only_flag) {
+            // Attach resolverType to existing internal object
+            val.__resolverType = resolverType
+            return Promise.resolve(val)
+          }
+          return Promise.resolve({
+            value: val,
+            __resolverType: resolverType,
+            __variableString: variableString,
+            __internal_metadata: true
+          })
         }
 
         const newUse = newHasFilter.reduce((acc, currentFilter, i) => {
@@ -1805,6 +2314,8 @@ Unable to resolve configuration variable
             // args: argsToPass
           })
         }, [])
+        // console.log('pathValue', pathValue)
+        // console.log('propertyString', propertyString)
         // console.log('newUse', newUse)
 
         if (typeof val === 'string' && val.match(/deep:/)) {
@@ -1841,7 +2352,19 @@ Unable to resolve configuration variable
         }, val)
         // console.log('> RESOLVER RETURN newValue', newValue)
         // console.log('> RESOLVER RETURN newValue 5', newValue)
-        return Promise.resolve(newValue)
+        // Wrap value with resolverType metadata for resolution tracking
+        // But don't wrap if it's already an internal flag object
+        if (newValue && typeof newValue === 'object' && newValue.__internal_only_flag) {
+          // Attach resolverType to existing internal object
+          newValue.__resolverType = resolverType
+          return Promise.resolve(newValue)
+        }
+        return Promise.resolve({
+          value: newValue,
+          __resolverType: resolverType,
+          __variableString: variableString,
+          __internal_metadata: true
+        })
       })
 
       // console.log('valuePromise', valuePromise)
@@ -1851,12 +2374,20 @@ Unable to resolve configuration variable
       return this.tracker.add(variableString, valuePromise, propertyString, newHasFilter, promiseKey)
     }
 
+    // console.log('fall thru variableString', variableString)
+
     /* fall through case with self refs */
     if (variableString) {
       // console.log('before clean propertyString', propertyString, variableString)
-      const clean = cleanVariable(propertyString, this.variableSyntax, true, `getValueFromSrc self ${this.callCount}`)
+      const clean = cleanVariable(
+        propertyString, 
+        this.variableSyntax, 
+        true, 
+        `getValueFromSrc self ${this.callCount}`
+      )
       // TODO @DWELLS cleanVariable makes fallback values with spaces have no spaces
       // console.log('AFTER cleanVariable', clean)
+      // console.log(typeof clean)
       const cleanClean = clean.split('|')[0]
       // console.log('cleanCleanVariable', cleanClean)
       if (funcRegex.exec(cleanClean)) {
@@ -1865,7 +2396,8 @@ Unable to resolve configuration variable
       }
 
       const split = splitByComma(cleanClean)
-
+      // console.log('split', split)
+      // console.log('typeof split', typeof split)
       // @TODO refactor this. USE FILTER [ 'commas', 'split("-"' ] is wrong
       let fallbackValue
       if (split.length === 2 || split.length === 3) {
@@ -1874,7 +2406,9 @@ Unable to resolve configuration variable
         fallbackValue = split[0]
       }
 
+      // TODO this should be new in memory resolutionHistory probably?
       const nestedVar = findNestedVariable(split, valueObject.originalSource)
+      // console.log('nestedVar', nestedVar)
 
       if (nestedVar) {
         if (!this.opts.allowUnknownVars) {
@@ -1883,7 +2417,7 @@ Unable to resolve configuration variable
         const fallbackStr = getFallbackString(split, nestedVar)
         return this.getValueFromSource(variableString, {
           value: fallbackStr,
-        }, 'nestedVar')
+        }, 'nestedVar', originalVar)
       }
 
       // TODO verify we need this still with file(file.js, param)
@@ -1895,7 +2429,7 @@ Unable to resolve configuration variable
           // recurse on fallback and check again
           return this.getValueFromSource(`${variableString})`, {
             value: propertyString,
-          }, 'cleanClean.match(fileRefSyntax)')
+          }, 'cleanClean.match(fileRefSyntax)', originalVar)
         }
       }
       // const fallbackValue = split[1]
@@ -1907,7 +2441,10 @@ Unable to resolve configuration variable
         const valuePromise = Promise.resolve(fallbackValue)
         return this.tracker.add(fallbackValue, valuePromise, propertyString, newHasFilter)
       }
-
+      /*
+      console.log('what is fallbackValue', fallbackValue)
+      console.log('typeof fallbackValue', typeof fallbackValue)
+      /** */
       // has fallback but needs deeper lookup. Call getValueFromSrc again
       if (fallbackValue) {
         if (DEBUG) console.log('fallbackValue', fallbackValue)
@@ -1915,11 +2452,21 @@ Unable to resolve configuration variable
         // recurse on fallback and check again
         return this.getValueFromSource(
           fallbackValue,
-          {
-            value: propertyString,
-          },
+          valueObject,
+          // Object.assign({}, valueObject, { value: propertyString }),
+          // {
+          //   value: propertyString,
+          //   path: valueObject.path,
+          //   originalSource: valueObject.originalSource,
+          //   ahh:true
+          // },
           'fallbackValue',
-        )
+          originalVar,
+        ).then((res) => {
+          // console.log('res', res)
+          // console.log('typeof res', typeof res)
+          return res
+        })
       }
     }
 
@@ -1932,7 +2479,9 @@ Unable to resolve configuration variable
     ]
 
     // Default value used for self variable
-    if (propertyString.match(/,/)) {
+    // Only show this error if the variable itself (not a parent fallback) is a self-reference with a fallback
+    const isSelfReference = !variableString.match(/^(env|opt|file|text|cron|eval|git):/)
+    if (isSelfReference && variableString.match(/,/)) {
       errorMessage.push('\n Default values for self referenced values are not allowed')
       errorMessage.push(`\n Fix the ${propertyString} variable`)
     }
@@ -1940,23 +2489,30 @@ Unable to resolve configuration variable
     let allowSpecialCase = false
     /* handle special cases for cloudformation ${Sub} values */
     if (this.originalConfig && key.endsWith('Fn::Sub')) {
-      const params = this.originalConfig.Parameters || (this.originalConfig.parameters || {}).Parameters
-      const resources = this.originalConfig.Resources || (this.originalConfig.resources || {}).Resources
-      /* Cloudformation Resource References */
-      if (resources && resources[variableString]) {
-        allowSpecialCase = true
-      } else if (params && params[variableString]) {
-        allowSpecialCase = true
-      } else if (variableString === 'ApiGatewayRestApi') {
-        // Allow for "hidden" cloudformation variables, set by sls framework
-        allowSpecialCase = true
-      } else if (variableString === 'HttpApi') {
-        // Allow for "hidden" cloudformation variables, set by sls framework
+      if (this.opts.verifySubReferences) {
+        const params = this.originalConfig.Parameters || (this.originalConfig.resources || {}).Parameters
+        const resources = this.originalConfig.Resources || (this.originalConfig.resources || {}).Resources
+        /* Cloudformation Resource References */
+        if (resources && resources[variableString]) {
+          allowSpecialCase = true
+        } else if (params && params[variableString]) {
+          allowSpecialCase = true
+        } else if (variableString === 'ApiGatewayRestApi') {
+          // Allow for "hidden" cloudformation variables, set by sls framework
+          allowSpecialCase = true
+        } else if (variableString === 'HttpApi') {
+          // Allow for "hidden" cloudformation variables, set by sls framework
+          allowSpecialCase = true
+        }
+      } else {
+        // Default let any sub references pass through
         allowSpecialCase = true
       }
     }
     /* Todo handle stage variables */
 
+
+
     /* Pass through unknown variables */
     if (this.opts.allowUnknownVars || allowSpecialCase) {
       // console.log('allowUnknownVars propertyString', propertyString)
@@ -2061,7 +2617,10 @@ Unable to resolve configuration variable
     } else if (resolvedPath.match(/\.\//)) {
       // TODO test higher parent refs
       const cleanName = path.basename(resolvedPath)
-      fullFilePath = findUp.sync(cleanName, { cwd: this.configPath })
+      const findUpResult = findUp.sync(cleanName, { cwd: this.configPath })
+      if (findUpResult) {
+        fullFilePath = findUpResult
+      }
     }
 
     let fileExtension = resolvedPath.split('.')
@@ -2070,18 +2629,39 @@ Unable to resolve configuration variable
 
     // Validate file exists
     if (!fs.existsSync(fullFilePath)) {
+      const originalVar = options.context && options.context.originalSource
+
+      const findNestedResult = findNestedVariables(
+        originalVar, 
+        this.variableSyntax, 
+        this.variablesKnownTypes, 
+        options.context.path
+      )
+      // console.log('findNestedResult', findNestedResult)
+      let hasFallback = false
+      if (findNestedResult) {
+        const varDetails = findNestedResult[0]
+        // console.log('varDetails', varDetails)
+        hasFallback = varDetails.hasFallback
+      }
+
+      // check if original var has fallback value
       // console.log('NO FILE FOUND', fullFilePath)
       // console.log('variableString', variableString)
-      const errorMsg = `${logLines}
-Variable ${variableString} cannot resolve due to missing file.
+
+      if (!hasFallback) {
+        const errorMsg = makeBox({
+          title: `File Not Found in ${originalVar}`,
+          text: `Variable ${variableString} cannot resolve due to missing file.
 
 File not found ${fullFilePath}
 
 Default fallback value will be used if provided.
-${logLines}
-`
 
-      console.log(errorMsg)
+${JSON.stringify(options.context, null, 2)}`,
+    })
+        console.log(errorMsg)
+      }
       // TODO maybe reject. YAML does not allow for null/undefined values
       // return Promise.reject(new Error(errorMsg))
       return Promise.resolve(undefined)
@@ -2099,6 +2679,7 @@ ${logLines}
 
     // Process JS files
     if (fileExtension === 'js' || fileExtension === 'cjs') {
+      // Possible alt importer tool https://github.com/humanwhocodes/module-importer
       const jsFile = require(fullFilePath)
       let returnValueFunction = jsFile
       // TODO change how exported functions are referenced
@@ -2198,6 +2779,7 @@ Check if your TypeScript is returning the correct data.`
     }
 
     if (fileExtension === 'mjs' || fileExtension === 'esm') {
+      // Possible alt importer tool https://github.com/humanwhocodes/module-importer
       const { executeESMFile } = require('./parsers/esm')
       let returnValueFunction
       const variableArray = variableString.split(':')
@@ -2269,9 +2851,10 @@ Check if your ESM is returning the correct data.`
         // console.log('deep', variableString)
         // console.log('matchedFileString', matchedFileString)
         let deepProperties = variableString.replace(matchedFileString, '')
+        // TODO 2025-11-12 add file.path.support instead of just : 
         if (deepProperties.substring(0, 1) !== ':') {
           const errorMessage = `Invalid variable syntax when referencing file "${relativePath}" sub properties
-Please use ":" to reference sub properties`
+Please use ":" to reference sub properties. ${deepProperties}`
           return Promise.reject(new Error(errorMessage))
         }
         deepProperties = deepProperties.slice(1).split('.')
@@ -2298,7 +2881,7 @@ Please use ":" to reference sub properties`
         return Promise.resolve(valueToPopulate)
       }
     }
-    console.log('fall thru', valueToPopulate)
+    // console.log('fall thru', valueToPopulate)
     return Promise.resolve(valueToPopulate)
   }
   getVariableFromDeep(variableString) {
@@ -2310,15 +2893,22 @@ Please use ":" to reference sub properties`
     /** */
     return this.deep[index]
   }
-  getValueFromDeep(variableString) {
+  getValueFromDeep(variableString, pathValue) {
     const variable = this.getVariableFromDeep(variableString)
     const deepRef = variableString.replace(deepPrefixReplacePattern, '')
     /*
     console.log("GET getValueFromDeep", variableString)
-    console.log('deepRef', deepRef)
+    console.log('deepRef', (deepRef) ? deepRef : '- no deepRef')
     console.log('getValueFromDeep variable', variable)
     /** */
-    let ret = this.populateValue({ value: variable }, undefined, 'getValueFromDeep')
+    // Preserve path and originalSource information from pathValue
+    const valueObject = {
+      value: variable,
+      path: pathValue ? pathValue.path : undefined,
+      originalSource: pathValue ? pathValue.originalSource : undefined,
+      resolutionHistory: pathValue ? pathValue.resolutionHistory : []
+    }
+    let ret = this.populateValue(valueObject, undefined, 'getValueFromDeep')
     if (deepRef.length) {
       // if there is a deep reference remaining
       ret = ret.then((result) => {
@@ -2342,7 +2932,12 @@ Please use ":" to reference sub properties`
     }
     // console.log("makeDeepVariable SET INDEX", index)
     const variableContainer = variable.match(this.variableSyntax)[0]
-    const variableString = cleanVariable(variableContainer, this.variableSyntax, true, `makeDeepVariable ${this.callCount}`)
+    const variableString = cleanVariable(
+      variableContainer, 
+      this.variableSyntax, 
+      true, 
+      `makeDeepVariable ${this.callCount}`
+    )
     const deepVar = variableContainer.replace(variableString, `deep:${index}`)
     /*
     console.log('MAKE DEEP', variable, caller)