configorama 0.6.9 → 0.6.10

package/src/main.js

@@ -1,6 +1,7 @@
 const os = require('os')
 const path = require('path')
 const fs = require('fs')
+const enrichMetadata = require('./utils/enrichMetadata')
 /* // disable logs to find broken tests
 console.log = () => {}
 // process.exit(1)
@@ -14,6 +15,7 @@ const traverse = require('traverse')
 const dotProp = require('dot-prop')
 const chalk = require('./utils/chalk')
 const { resolveAlias } = require('./utils/resolveAlias')
+const { resolveFilePathFromMatch } = require('./utils/getFullFilePath')
 
 /* Default Value resolvers */
 const getValueFromString = require('./resolvers/valueFromString')
@@ -27,6 +29,7 @@ const createGitResolver = require('./resolvers/valueFromGit')
 const YAML = require('./parsers/yaml')
 const TOML = require('./parsers/toml')
 const INI = require('./parsers/ini')
+const JSON5 = require('./parsers/json5')
 /* functions */
 const md5Function = require('./functions/md5')
 
@@ -50,13 +53,16 @@ const { splitCsv } = require('./utils/splitCsv')
 const { replaceAll } = require('./utils/replaceAll')
 const { getTextAfterOccurrence, findNestedVariable } = require('./utils/textUtils')
 const { getFallbackString, verifyVariable } = require('./utils/variableUtils')
-const { encodeUnknown, decodeUnknown } = require('./utils/unknownValues')
+const { encodeUnknown, decodeUnknown } = require('./utils/encoders/unknown-values')
+const { decodeEncodedValue } = require('./utils/encoders')
+const { encodeJsSyntax, decodeJsSyntax, hasParenthesesPlaceholder } = require('./utils/encoders/js-fixes')
 const { mergeByKeys } = require('./utils/mergeByKeys')
 const { arrayToJsonPath } = require('./utils/arrayToJsonPath')
 const { findNestedVariables } = require('./utils/find-nested-variables')
 const { makeBox, makeStackedBoxes } = require('@davidwells/box-logger')
 const { logHeader } = require('./utils/logs')
 const { createEditorLink } = require('./utils/createEditorLink')
+const { runConfigWizard } = require('./utils/configWizard')
 /**
  * Maintainer's notes:
  *
@@ -90,6 +96,7 @@ const logLines = '────────────────────
 
 let DEBUG = process.argv.includes('--debug') ? true : false
 let VERBOSE = process.argv.includes('--verbose') ? true : false
+let SETUP_MODE = process.argv.includes('--setup') ? true : false
 // DEBUG = true
 let DEBUG_TYPE = false
 const ENABLE_FUNCTIONS = true
@@ -123,6 +130,7 @@ function preProcess(configObject, variableSyntax) {
     if (typeof str !== 'string') return str
 
     let result = str
+    // result = result.replace(/\$\{self:/g, '${')
     let changed = true
 
     // Keep iterating until no more changes (to handle nested variables)
@@ -248,11 +256,18 @@ class Configorama {
       allowUnknownVars: false,
       // Allow undefined to be an end result.
       allowUndefinedValues: false,
+      // Allow unknown file refs to pass through without throwing errors
+      allowUnknownFileRefs: false,
+      // Return metadata
+      returnMetadata: false,
+      // Return preResolvedVariableDetails
+      returnPreResolvedVariableDetails: false,
     }, options)
 
     this.filterCache = {}
 
     this.foundVariables = []
+    this.fileRefsFound = []
 
     // Track variable resolutions for metadata (keyed by path)
     this.resolutionTracking = {}
@@ -343,6 +358,8 @@ class Configorama {
       {
         type: 'self',
         prefix: 'self',
+        syntax: '${self:pathToKeyInConfig}',
+        description: `Resolves values from the current config object. Supports sub-properties via :key lookup.`,
         match: selfRefSyntax,
         resolver: (varString, o, x, pathValue) => {
           return this.getValueFromSelf(varString, o, x, pathValue)
@@ -357,6 +374,8 @@ class Configorama {
       {
         type: 'file',
         prefix: 'file',
+        syntax: '${file(pathToFile.json)}',
+        description: `Resolves values from files. Supports sub-properties via :key lookup.`,
         match: fileRefSyntax,
         resolver: (varString, o, x, pathValue) => {
           return this.getValueFromFile(varString, { context: pathValue })
@@ -387,6 +406,7 @@ class Configorama {
       /* Resolve deep references */
       {
         type: 'deep',
+        internal: true,
         match: deepRefSyntax,
         resolver: (varString, o, x, pathValue) => {
           // console.log('>>>>>getValueFromDeep', varString)
@@ -399,23 +419,23 @@ class Configorama {
 
     /* Nicer self: references. Match key in object */
     const fallThroughSelfMatcher = {
-      type: 'fallthrough',
+      type: 'dot.prop',
       match: (varString, fullObject, valueObject) => {
         /*
-        console.log('fallthrough varString', varString)
-        console.log('fallthrough valueObject', valueObject)
+        console.log('fallThroughSelfMatcher varString', varString)
+        console.log('fallThroughSelfMatcher valueObject', valueObject)
         console.log('fullObject', fullObject)
         /** */
         /* its file ref so we need to shift lookup for self in nested files */
         if (valueObject.isFileRef) {
           const exists = dotProp.get(fullObject, varString)
-          // console.log('fallthrough exists', exists)
+          // console.log('fallThroughSelfMatcher exists', exists)
           if (!exists) {
             // @ Todo make recursive
             const deepProperties = [valueObject.path[0]].concat(varString)
             const dotPropPath = deepProperties.join('.')
             const deeperExists = dotProp.get(fullObject, dotPropPath)
-            // console.log('fallthrough deeper', deeperExists)
+            // console.log('fallThroughSelfMatcher deeper', deeperExists)
             return deeperExists
           }
         }
@@ -426,10 +446,10 @@ class Configorama {
       },
       resolver: (varString, options, config, pathValue) => {
         /*
-        console.log('fallthrough resolver', varString)
-        console.log('fallthrough options', options)
-        console.log('fallthrough config', config)
-        console.log('fallthrough pathValue', pathValue)
+        console.log('fallThroughSelfMatcher resolver', varString)
+        console.log('fallThroughSelfMatcher options', options)
+        console.log('fallThroughSelfMatcher config', config)
+        console.log('fallThroughSelfMatcher pathValue', pathValue)
         /** */
         return this.getValueFromSelf(varString, options, config, pathValue)
       },
@@ -437,6 +457,19 @@ class Configorama {
 
     /* Apply user defined variable sources */
     if (options.variableSources) {
+      
+      // ensure each variable source has a type
+      options.variableSources.forEach((v) => {
+        if (!v.type) {
+          console.log('Variable', v)
+          throw new Error('Variable source must have a type')
+        }
+        if (!v.match || !v.resolver) {
+          console.log('Variable', v)
+          throw new Error('Variable source must have a match and resolver functions')
+        }
+      })
+
       this.variableTypes = this.variableTypes.concat(options.variableSources)
     }
 
@@ -482,7 +515,7 @@ class Configorama {
       toKebabCase: (val) => {
         return kebabCase(val)
       },
-      /* Type filters */
+      /* Type filters for coercion */
       toNumber: (val, from) => {
         const newVal = Number(val)
         return newVal
@@ -497,7 +530,37 @@ class Configorama {
         return JSON.stringify(val)
       },
       toObject: (val) => {
-        return JSON.parse(val)
+        return JSON5.parse(val)
+      },
+      /* Type validation filters */
+      Number: (value) => {
+        const n = Number(value)
+        if (isNaN(n)) throw new Error(`Configorama Error: Expected Number, got "${value}"`)
+        return n
+      },
+      Boolean: (value) => {
+        if (typeof value === 'boolean') return value
+        const v = String(value).toLowerCase()
+        if (['true', '1', 'yes', 'on'].includes(v)) return true
+        if (['false', '0', 'no', 'off'].includes(v)) return false
+        throw new Error(`Configorama Error: Expected Boolean, got "${value}"`)
+      },
+      String: (value) => {
+        if (value === undefined || value === null || value === 'null') return ''
+        return String(value)
+      },
+      Json: (value) => {
+        try {
+          return typeof value === 'string' ? JSON.parse(value) : value
+        } catch (e) {
+          throw new Error(`Configorama Error: Invalid JSON in variable`)
+        }
+      },
+      /* Help filter - identity function that preserves value but provides metadata for wizard */
+      help: (value, helpText) => {
+        // Identity function - returns value unchanged
+        // The helpText argument is extracted during metadata collection for the wizard
+        return value
       },
     }
 
@@ -507,7 +570,9 @@ class Configorama {
     }
 
     // (\|\s*(toUpperCase|toLowerCase|toCamelCase|toKebabCase|capitalize)\s*)+$
-    this.filterMatch = new RegExp(`(\\|\\s*(${Object.keys(this.filters).join('|')})\\s*)+}?$`)
+    // Updated to support function-style filters like help('text') with nested parens
+    // Use a more permissive pattern that matches anything between parens including nested parens
+    this.filterMatch = new RegExp(`(\\|\\s*(${Object.keys(this.filters).join('|')})(?:\\s*\\([^)]*(?:\\([^)]*\\))?[^)]*\\))?\\s*)+}?$`)
     // console.log('this.filterMatch', this.filterMatch)
 
     this.functions = {
@@ -603,7 +668,7 @@ class Configorama {
         this.opts
       )
       this.configFileContents = ''
-      if (VERBOSE || showFoundVariables) {
+      if (VERBOSE || showFoundVariables || this.opts.returnPreResolvedVariableDetails) {
         this.configFileContents = fs.readFileSync(this.configFilePath, 'utf8')
       }
       /*
@@ -630,16 +695,37 @@ class Configorama {
     const variableSyntax = this.variableSyntax
     const variablesKnownTypes = this.variablesKnownTypes
 
-    if (VERBOSE || showFoundVariables) {
+    if (VERBOSE || showFoundVariables || this.opts.returnPreResolvedVariableDetails) {
       // Use collectVariableMetadata to get variable info (DRY - don't duplicate logic)
       const metadata = this.collectVariableMetadata()
-      /*
-      deepLog('metadata', metadata)
-      process.exit(1)
-      /** */
-    
+
+      const enrich = enrichMetadata(
+        metadata,
+        this.resolutionTracking,
+        this.variableSyntax,
+        this.fileRefsFound,
+        this.originalConfig,
+        this.configFilePath,
+        Object.keys(this.filters)
+      )
+
+      if (showFoundVariables) {
+        /*
+        deepLog('metadata', metadata)
+        fs.writeFileSync(`metadata-${path.basename(this.configFilePath)}.json`, JSON.stringify(metadata, null, 2))
+        deepLog('enrich', enrich)
+        // process.exit(1)
+        /** */
+      }
+
       const variableData = metadata.variables
+      const uniqueVariables = metadata.uniqueVariables
       const varKeys = Object.keys(variableData)
+      const uniqueVarKeys = Object.keys(uniqueVariables)
+
+      // if (this.opts.returnPreResolvedVariableDetails) {
+      //   return metadata
+      // }
 
       if (!varKeys.length) {
         logHeader('No Variables Found in Config')
@@ -651,9 +737,9 @@ class Configorama {
 
         const varTypes = Object.keys(this.variableTypes)
         if (varTypes.length) {
-          const exclude = ['fallthrough', 'deep']
+          const exclude = ['dot.prop', 'deep']
           console.log('\nAllowed variable types:')
-          varTypes.filter((v) => v.type !== 'fallthrough').forEach((v) => {
+          varTypes.filter((v) => v.type !== 'dot.prop').forEach((v) => {
             const vData = this.variableTypes[v]
             if (exclude.includes(vData.type)) {
               return
@@ -676,166 +762,231 @@ 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 refCount = countAllReferences(k)
+          // Use uniqueVariables for simpler reference counting
+          const referenceData = varKeys.map((k) => {
+            // Map from varMatch (e.g., '${env:API_KEY}') to variable name (e.g., 'env:API_KEY')
+            // Extract the variable name from the key by removing ${ and }
+            const varName = k.replace(/^\$\{/, '').replace(/\}$/, '').split(',')[0].trim()
+            const uniqueVar = uniqueVariables[varName]
+            const refCount = uniqueVar ? uniqueVar.occurrences.length : variableData[k].length
             const placesWord = refCount > 1 ? 'places' : 'place'
             return `- ${k.padEnd(longestKey).padEnd(longestKey + 10)} referenced ${refCount} ${placesWord}`
-          }).join('\n'))
-          console.log()
+          }).join('\n')
+
+          console.log(`${referenceData}\n`)
         }
 
         logHeader('Variable Details')
 
-        const lines = this.configFileContents.split('\n')
-        // console.log('lines', lines)
-    
+        const lines = this.configFileContents ? this.configFileContents.split('\n') : []
+
         const indent = ''
         const boxes = varKeys.map((key, i) => {
           const variableInstances = variableData[key]
           // console.log('variableInstances', variableInstances)
-      
           const firstInstance = variableInstances[0]
 
-          let requiredText = ''
-          let defaultValueSrc = ''
-          if (typeof firstInstance.defaultValue === 'undefined') {
-            // console.log('no default value', firstInstance)
-
-            let dotPropArr = []
-            if (firstInstance.defaultValueIsVar && (
-              firstInstance.defaultValueIsVar.varType === 'self:' ||
-              firstInstance.defaultValueIsVar.varType === 'dot.prop'
-            )) {
-              dotPropArr = [firstInstance.defaultValueIsVar]
-            }
-            /* Check if the fallback variable is a self reference */
-            const hasDotPropOrSelf = variableInstances.reduce((acc, v) => {
-              const dotProp = v.resolveDetails.find((d) => {
-                // console.log('d', d)
-                return d.varType === 'dot.prop'
-              })
-              if (dotProp) {
-                acc.push(dotProp)
-              }
-              if (v.resolveDetails && v.resolveDetails.length === 1 && v.resolveDetails[0].varType === 'self:') {
-                // console.log('dot.prop', v.resolveDetails)
-                acc.push(v.resolveDetails[0])
-              }
-              return acc
-            }, dotPropArr)
-            // console.log('hasDotPropOrSelf', hasDotPropOrSelf)
-            
-            if (!hasDotPropOrSelf.length) {
-              const debug = (false) ? JSON.stringify(firstInstance, null, 2) : ''
-              requiredText = `[Required Variable] ${debug}`
-            } else {
-              const fallBackValues = variableInstances.filter((v) => v.resolveDetails.find((d) => d.hasFallback)).map((v) => v.resolveDetails)
-              // console.log('fallBackValues', fallBackValues)
-              if (fallBackValues.length) {
-                // console.log('fallBackValues.resolveDetails', fallBackValues)
-              }
+          // Get uniqueVariable data for description and other metadata
+          const varName = key.replace(/^\$\{/, '').replace(/\}$/, '').split(',')[0].trim()
+          const uniqueVar = uniqueVariables[varName]
 
-              const cleanPath = hasDotPropOrSelf[0].variable.replace('self:', '')
-              defaultValueSrc = cleanPath
-              // Find the dot prop value in the original config
-              const dotPropValue = dotProp.get(this.originalConfig, cleanPath)
-              // console.log('dotPropValue', dotPropValue)
-              if (typeof dotPropValue !== 'undefined') {
-                requiredText = ''
-                const niceString = typeof dotPropValue === 'object' ? JSON.stringify(dotPropValue) : dotPropValue
-                // truncate niceString to 100 characters
-                const truncatedString = niceString.length > 100 ? niceString.substring(0, 90) + '...' : niceString
-                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`
-                )
-              }
-            }
-            //this.originalConfig[key] = undefined
-          }
+          // Build display message from enriched metadata
           const spacing = '           '
           const titleText = `Variable:${spacing}`
-          const reqText = (requiredText) ? `${chalk.red.bold(requiredText)}\n` : ''
-          let varMsg = `${reqText}`
-          const VALUE_HEX = '#899499' // '#708090'
+          const VALUE_HEX = '#899499'
           const keyChalk = chalk.whiteBright
           const valueChalk = chalk.hex(VALUE_HEX)
 
+          let varMsg = ''
+          let requiredMessage = ''
+
+          // Show required status from metadata
+          if (firstInstance.isRequired) {
+            requiredMessage = `${chalk.red.bold('[Required]')}`
+          }
+
+          // Show type filter if present (Boolean, String, Number, etc.)
+          if (uniqueVar && uniqueVar.occurrences.length > 0) {
+            const typeFilters = ['Boolean', 'String', 'Number', 'Array', 'Object']
+            const foundTypes = new Set()
+
+            uniqueVar.occurrences.forEach(occ => {
+              if (occ.filters && Array.isArray(occ.filters)) {
+                occ.filters.forEach(filter => {
+                  if (typeFilters.includes(filter)) {
+                    foundTypes.add(filter)
+                  }
+                })
+              }
+            })
+
+            if (foundTypes.size > 0) {
+              const typeText = `${indent}${keyChalk('Type:'.padEnd(titleText.length, ' '))}`
+              varMsg += `${typeText} ${valueChalk(Array.from(foundTypes).join(', '))}\n`
+            }
+          }
+
+          // Show description from uniqueVariables if available
+          if (uniqueVar && uniqueVar.occurrences.length > 0) {
+            // Collect unique descriptions from all occurrences
+            const descriptions = uniqueVar.occurrences
+              .map(occ => occ.description)
+              .filter((desc, index, self) => desc && self.indexOf(desc) === index)
+
+            if (descriptions.length > 0) {
+              const descText = `${indent}${keyChalk('Description:'.padEnd(titleText.length, ' '))}`
+              const combinedDesc = descriptions.join('. ')
+              varMsg += `${descText} ${valueChalk(combinedDesc)}\n`
+            }
+          }
+
+    
+
+          // Show default value from metadata
           if (typeof firstInstance.defaultValue !== 'undefined') {
-            // console.log('firstInstance.defaultValue', firstInstance.defaultValue)
             const defaultValueRender = firstInstance.defaultValue === '' ? '""' : firstInstance.defaultValue
-            const defaultValueText = `${indent}${keyChalk(`Default value:`.padEnd(titleText.length, ' '))}`
-            // ensure padding is even 
-            varMsg += `${defaultValueText} ${valueChalk(defaultValueRender)}`
+            const defaultValueText = `${indent}${keyChalk('Default value:'.padEnd(titleText.length, ' '))}`
+            varMsg += `${defaultValueText} ${valueChalk(defaultValueRender)}\n`
           }
 
-          if (defaultValueSrc) {
-            varMsg += `\n${indent}${keyChalk('Default value path:'.padEnd(titleText.length, ' '))} `
-            varMsg += `${valueChalk(defaultValueSrc)}`
+          // Show default value source path from metadata
+          if (firstInstance.defaultValueSrc) {
+            varMsg += `${indent}${keyChalk('Default value path:'.padEnd(titleText.length, ' '))} `
+            varMsg += `${valueChalk(firstInstance.defaultValueSrc)}\n`
           }
 
+          // Show resolve order from metadata
           if (firstInstance.resolveOrder.length > 1) {
-            varMsg += `\n${indent}${keyChalk('Resolve Order:'.padEnd(titleText.length, ' '))}`
+            varMsg += `${indent}${keyChalk('Resolve Order:'.padEnd(titleText.length, ' '))}`
             const resolveOrder = firstInstance.resolveOrder.join(', ')
-            varMsg += ` ${valueChalk(resolveOrder)}`
+            varMsg += ` ${valueChalk(resolveOrder)}\n`
           }
 
+          // Show path(s) from metadata
           let locationRender = valueChalk(variableInstances[0].path)
-  
-          let locationLabel = `${indent}${keyChalk('Path:'.padEnd(titleText.length, ' '))}`
+          let locationLabel = `${indent}${keyChalk('Config Path:'.padEnd(titleText.length, ' '))}`
+          let typeText = ''
           if (variableInstances.length > 1) {
-            locationRender = `\n${variableInstances.map((v) => valueChalk(`${indent}- ${v.path}`)).join('\n')}`
-            const locationLabelText = `${indent}${keyChalk('Paths:')}`
-            locationLabel = locationLabelText
+            const pathIndent = ' '.repeat(titleText.length + 1)
+            const pathItems = variableInstances.map((v, idx) => {
+              // Show type filter per path if different
+              if (uniqueVar && uniqueVar.occurrences.length > 1) {
+                const occurrence = uniqueVar.occurrences.find(occ => occ.path === v.path)
+                const typeFilters = ['Boolean', 'String', 'Number', 'Array', 'Object']
+                const pathType = occurrence && occurrence.filters
+                  ? occurrence.filters.find(f => typeFilters.includes(f))
+                  : null
+
+                typeText = pathType ? ` ${chalk.dim(`Type: ${pathType}`)}` : ''
+                const prefix = idx === 0 ? '' : `${indent}${pathIndent}`
+                return `${prefix}${valueChalk(`- ${v.path}`)}${typeText}`
+              }
+              const prefix = idx === 0 ? '' : `${indent}${pathIndent}`
+              return `${prefix}${valueChalk(`- ${v.path}`)}${typeText}`
+            })
+            locationRender = pathItems.join('\n')
+            locationLabel = `${indent}${keyChalk('Config Paths:'.padEnd(titleText.length, ' '))}`
+          } else {
+            // look for type filter in the first instance
+            const typeFilters = ['Boolean', 'String', 'Number', 'Array', 'Object']
+            const pathType = firstInstance.filters
+              ? firstInstance.filters.find(f => typeFilters.includes(f))
+              : null
+
+            typeText = pathType ? ` ${chalk.dim(`Type: ${pathType}`)}` : ''
           }
+          varMsg += `${locationLabel} ${locationRender}`
+
+          // Find line number in config file based on format (YAML, TOML, JSON, INI)
+          const configKey = firstInstance.key
+          const line = lines.findIndex((line) => {
+            const fileType = this.configFileType
+            const escapedKey = configKey.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+            // YAML: key: or key :
+            if (fileType === '.yml' || fileType === '.yaml') {
+              return new RegExp(`^\\s*${escapedKey}\\s*:`).test(line)
+            }
+            // TOML: key = or key=
+            if (fileType === '.toml') {
+              return new RegExp(`^\\s*${escapedKey}\\s*=`).test(line)
+            }
+            // JSON: "key": or "key" :
+            if (fileType === '.json' || fileType === '.json5') {
+              return new RegExp(`"${escapedKey}"\\s*:`).test(line)
+            }
+            // INI: key = or key=
+            if (fileType === '.ini') {
+              return new RegExp(`^\\s*${escapedKey}\\s*=`).test(line)
+            }
+            // JS/TS/ESM: key: or "key": or 'key': or `key`: or [`key`]:
+            if (['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(fileType)) {
+              return new RegExp(`(?:${escapedKey}|"${escapedKey}"|'${escapedKey}'|\`${escapedKey}\`|\\[\`${escapedKey}\`\\])\\s*:`).test(line)
+            }
+            // Default fallback: try YAML-style
+            return line.includes(`${configKey}:`)
+          })
+          const lineNumber = line !== -1 ? line + 1 : 0
 
-          varMsg += `\n${locationLabel} ${locationRender}`
 
-          // find the match in our lines
-          const line = lines.findIndex((line) => line.includes(key))
-          const lineNumber = line + 1
-    
-          // console.log(` ${chalk.bold(key)}`)
           return {
-            text: varMsg,
+            content: {
+              left: varMsg,
+              backgroundColor: 'red',
+              width: '100%',
+            },
             title: {
-              left: `▶ ${lineNumber ? createEditorLink(this.configFilePath, lineNumber, 1, key) : key}`,
-              right: lineNumber ? createEditorLink(this.configFilePath, lineNumber, 1, `Line: ${lineNumber}`, 'gray') : '',
+              left: `▷ ${lineNumber ? createEditorLink(this.configFilePath, lineNumber, 1, key) : key}`,
+              right: lineNumber ? createEditorLink(this.configFilePath, lineNumber, 1, `${requiredMessage} ${lineNumber ? `Line: ${lineNumber.toString().padEnd(2, ' ')}` : ''}`, 'gray') : '',
+              center: typeText,
+              paddingBottom: 1,
+              paddingTop: (i === 0) ? 1 : 0,
+              truncate: true,
             },
+            width: '100%',
           }
         })
 
         console.log(makeStackedBoxes(boxes, {
+          borderText: 'Variable Details. Click on titles to open in editor.',
           borderColor: 'gray',
-          minWidth: 120,
+          minWidth: '96%',
           borderStyle: 'bold',
+          disableTitleSeparator: true,
         }))
+        // process.exit(1)
+      }
+
+
+      // WALK through CLI prompt if --setup flag is set
+      if (SETUP_MODE) {
+        logHeader('Setup Mode')
+        // deepLog('enrich', enrich)
+        const userInputs = await runConfigWizard(enrich, this.originalConfig, this.configFilePath)
+
+        console.log('\n')
+        logHeader('User Inputs Summary')
+        console.log(JSON.stringify(userInputs, null, 2))
+
+        // TODO set values
+
+        // Apply user inputs to options and environment
+        if (userInputs.options) {
+          Object.assign(this.opts, userInputs.options)
+        }
+        if (userInputs.env) {
+          Object.assign(process.env, userInputs.env)
+        }
+        // Note: self references are in the config, so no need to apply them
+
+        console.log()
+        logHeader('Resolving Configuration')
+        console.log()
+
+        // process.exit(1)
+
+        // Continue with normal resolution flow using the new values
+        // Don't exit - let it fall through to resolve the config
       }
     
       /* Exit early if list or info flag is set */
@@ -931,9 +1082,8 @@ class Configorama {
                 }
 
                 /* fix for file(JS-ref.js, raw) to keep parens and inline code */
-                const OPEN_PAREN_PLACEHOLDER_PATTERN = /__PH_PAREN_OPEN__/g
-                if (rawValue.match(OPEN_PAREN_PLACEHOLDER_PATTERN)) {
-                  rawValue = rawValue.replace(OPEN_PAREN_PLACEHOLDER_PATTERN, '(')
+                if (hasParenthesesPlaceholder(rawValue)) {
+                  rawValue = decodeJsSyntax(rawValue)
                   this.update(rawValue)
                 }
 
@@ -977,6 +1127,8 @@ class Configorama {
   collectVariableMetadata() {
     const variableSyntax = this.variableSyntax
     const variablesKnownTypes = this.variablesKnownTypes
+    const variableTypes = this.variableTypes
+    const filterMatch = this.filterMatch
     const foundVariables = []
     const variableData = {}
     const fileRefs = []
@@ -991,29 +1143,117 @@ class Configorama {
           return
         }
 
-        const nested = findNestedVariables(rawValue, variableSyntax, variablesKnownTypes, configValuePath)
+        const nested = findNestedVariables(
+          rawValue, 
+          variableSyntax, 
+          variablesKnownTypes, 
+          configValuePath, 
+          variableTypes
+        )
 
         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
+
+        // Extract filters from varMatch
+        const originalSrc = lastItem.varMatch || ''
+        const hasFilters = filterMatch && originalSrc.match(filterMatch)
+        let foundFilters = []
+        let keyWithoutFilters = originalSrc
+
+        if (hasFilters) {
+          // Extract filter names from the match (e.g., "| String}" -> ["String"])
+          const filterPart = hasFilters[0].replace(/}?$/, '') // Remove trailing }
+          foundFilters = filterPart
+            .split('|')
+            .map((filter) => filter.trim())
+            .filter(Boolean)
+
+          // Remove filters from the key (replace "| String}" with "}")
+          // Also clean up any trailing whitespace before the closing brace
+          keyWithoutFilters = originalSrc.replace(filterMatch, '}').replace(/\s+}$/, '}')
+        }
+
+        const key = keyWithoutFilters
+
+        // Strip filters from resolveDetails
+        const cleanedResolveDetails = nested.map(detail => {
+          const cleaned = { ...detail }
+          if (cleaned.varMatch && filterMatch) {
+            const match = cleaned.varMatch.match(filterMatch)
+            if (match) {
+              cleaned.varMatch = cleaned.varMatch.replace(filterMatch, '').replace(/\s+$/, '') + '}'
+            }
+          }
+          if (cleaned.variable && filterMatch) {
+            const match = cleaned.variable.match(filterMatch)
+            if (match) {
+              cleaned.variable = cleaned.variable.replace(filterMatch, '').replace(/\s+$/, '')
+            }
+          }
+          if (cleaned.varString && filterMatch) {
+            const match = cleaned.varString.match(filterMatch)
+            if (match) {
+              cleaned.varString = cleaned.varString.replace(filterMatch, '').trim()
+            }
+          }
+          // Also clean fallbackValues if present
+          if (cleaned.fallbackValues && Array.isArray(cleaned.fallbackValues)) {
+            cleaned.fallbackValues = cleaned.fallbackValues.map(fb => {
+              const cleanedFb = { ...fb }
+              if (cleanedFb.varMatch && filterMatch) {
+                const match = cleanedFb.varMatch.match(filterMatch)
+                if (match) {
+                  cleanedFb.varMatch = cleanedFb.varMatch.replace(filterMatch, '').trim()
+                }
+              }
+              if (cleanedFb.variable && filterMatch) {
+                const match = cleanedFb.variable.match(filterMatch)
+                if (match) {
+                  cleanedFb.variable = cleanedFb.variable.replace(filterMatch, '').trim()
+                }
+              }
+              if (cleanedFb.stringValue && filterMatch) {
+                const match = cleanedFb.stringValue.match(filterMatch)
+                if (match) {
+                  cleanedFb.stringValue = cleanedFb.stringValue.replace(filterMatch, '').trim()
+                }
+              }
+              return cleanedFb
+            })
+          }
+          return cleaned
+        })
+
         const varData = {
           path: configValuePath,
           key: itemKey,
-          value: rawValue,
-          variable: lastItem.fullMatch,
+          originalStringValue: rawValue,
+          variable: keyWithoutFilters,
+          variableWithFilters: originalSrc,
           isRequired: false,
           defaultValue: undefined,
           matchIndex: matchCount++,
           resolveOrder: [],
-          resolveDetails: nested,
+          resolveDetails: cleanedResolveDetails,
+          ...(foundFilters.length > 0 && { filters: foundFilters }),
         }
         let defaultValueIsVar = false
 
         function calculateResolveOrder(item) {
+          // Helper to strip filters from variable strings
+          const stripFilters = (str) => {
+            if (!str || !filterMatch) return str
+            const match = str.match(filterMatch)
+            if (match) {
+              return str.replace(filterMatch, '').trim()
+            }
+            return str
+          }
+
           if (item && item.fallbackValues) {
             let hasResolvedFallback
-            const order = ([item.valueBeforeFallback]).concat(item.fallbackValues.map((f, i) => {
+            const order = ([stripFilters(item.valueBeforeFallback)]).concat(item.fallbackValues.map((f, i) => {
               if (f.fallbackValues) {
                 const [nestedOrder, nestedResolvedFallback] = calculateResolveOrder(f)
                 if (!hasResolvedFallback && nestedResolvedFallback) {
@@ -1023,21 +1263,22 @@ class Configorama {
               }
 
               if (!hasResolvedFallback && f.isResolvedFallback) {
-                hasResolvedFallback = f.stringValue
+                hasResolvedFallback = stripFilters(f.stringValue)
               }
               if (f.isResolvedFallback) {
-                hasResolvedFallback = f.stringValue
+                hasResolvedFallback = stripFilters(f.stringValue)
               }
 
               if (!hasResolvedFallback && f.isVariable) {
                 defaultValueIsVar = f
               }
-              return `${f.stringValue || f.variable}${f.isResolvedFallback ? ' (Resolved default fallback)' : ''}`
+              const valueStr = stripFilters(f.stringValue || f.variable)
+              return `${valueStr}${f.isResolvedFallback ? ' (default)' : ''}`
             })).flat()
 
             return [order, hasResolvedFallback]
           }
-          return [[item.variable], undefined]
+          return [[stripFilters(item.variable)], undefined]
         }
 
         const [resolveOrder, hasResolvedFallback] = calculateResolveOrder(lastItem)
@@ -1061,10 +1302,9 @@ class Configorama {
 
         // Extract file references
         nested.forEach((detail) => {
-          if (detail.varType && 
-             (detail.varType.startsWith('file(') || detail.varType.startsWith('text('))
-          ) {
-            const fileMatch = detail.varType.match(/^(?:file|text)\((.*?)\)/)
+          // console.log('detail', detail)
+          if (detail.variableType && (detail.variableType === 'file' || detail.variableType === 'text')) {
+            const fileMatch = detail.variable.match(/^(?:file|text)\((.*?)\)/)
             if (fileMatch && fileMatch[1]) {
               let fileContent = fileMatch[1].trim()
               
@@ -1130,19 +1370,19 @@ class Configorama {
         // Check for self-references that resolve to config values
         let dotPropArr = []
         if (firstInstance.defaultValueIsVar && (
-          firstInstance.defaultValueIsVar.varType === 'self:' ||
-          firstInstance.defaultValueIsVar.varType === 'dot.prop'
+          firstInstance.defaultValueIsVar.variableType === 'self:' ||
+          firstInstance.defaultValueIsVar.variableType === '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])
+          // Only check the outermost variable (last in resolveDetails)
+          if (v.resolveDetails && v.resolveDetails.length > 0) {
+            const outermostDetail = v.resolveDetails[v.resolveDetails.length - 1]
+            if (outermostDetail.variableType === 'dot.prop' || outermostDetail.variableType === 'self') {
+              acc.push(outermostDetail)
+            }
           }
           return acc
         }, dotPropArr)
@@ -1155,10 +1395,20 @@ class Configorama {
           const dotPropValue = dotProp.get(this.originalConfig, cleanPath)
           if (typeof dotPropValue === 'undefined') {
             isTrulyRequired = true
+          } else {
+            // Enrich with default value from self-reference
+            firstInstance.defaultValueSrc = cleanPath
+            const niceString = typeof dotPropValue === 'object' ? JSON.stringify(dotPropValue) : dotPropValue
+            const truncatedString = niceString.length > 100 ? niceString.substring(0, 90) + '...' : niceString
+            firstInstance.defaultValue = truncatedString
+            firstInstance.isRequired = false
           }
         }
       }
 
+      // Update isRequired based on computed isTrulyRequired
+      firstInstance.isRequired = isTrulyRequired
+
       if (isTrulyRequired) {
         requiredCount++
       } else {
@@ -1168,13 +1418,23 @@ class Configorama {
 
     return {
       variables: variableData,
+      uniqueVariables: {},
+      fileDependencies: {
+        globPatterns: fileGlobPatterns,
+        // all: fileRefs,
+        dynamicPaths: fileRefs.filter(ref => ref.indexOf('*') !== -1 || ref.match(variableSyntax)),
+        // resolve files are those that are paths with no * and no inner variables
+        resolvedPaths: fileRefs.filter(ref => ref.indexOf('*') === -1 && !ref.match(variableSyntax)),
+        // Set in enrichMetadata
+        byConfigPath: undefined,
+        // Set in enrichMetadata
+        references: undefined,
+      },
       summary: {
         totalVariables: varKeys.length,
         requiredVariables: requiredCount,
         variablesWithDefaults: withDefaultsCount
       },
-      fileRefs: fileRefs,
-      fileGlobPatterns: fileGlobPatterns,
     }
   }
   runFunction(variableString) {
@@ -1198,6 +1458,7 @@ class Configorama {
     let argsToPass
     if (rawArgs && rawArgs.match(/^{([^}]+)}$/)) {
       // console.log('OBJECT', hasFunc[2])
+      // TODO use JSON5
       argsToPass = [JSON.parse(rawArgs)]
     } else {
       // TODO fix how commas + spaces are ned
@@ -1464,48 +1725,79 @@ class Configorama {
     if (matches.length === 1) {
       valueObject.currentVarDetails = matches[0]
       valueObject.currentVarDetails.result = results[0]
+    }
+
+    // Initialize resolution history if needed
+    if (!valueObject.resolutionHistory) {
+      valueObject.resolutionHistory = []
+    }
+
+    let result = valueObject.value
+    for (let i = 0; i < matches.length; i += 1) {
+      this.warnIfNotFound(matches[i].variable, results[i])
 
       // Extract metadata from result if present
-      let actualResult = results[0]
+      let actualResult = results[i]
       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
+      if (results[i] && typeof results[i] === 'object') {
+        if (results[i].__internal_metadata) {
+          actualResult = results[i].value
+          resolverType = results[i].__resolverType
+        } else if (results[i].__internal_only_flag) {
+          actualResult = results[i]
+          resolverType = results[i].__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,
+
+      let valueBeforeResolution = result
+
+      if (typeof valueBeforeResolution === 'object' && valueBeforeResolution.__internal_only_flag) {
+        valueBeforeResolution = valueBeforeResolution.value
+      }
+
+      const finalResult = decodeEncodedValue(cleanResult)
+
+      // Track this resolution step in history
+      const historyEntry = {}
+
+      historyEntry.match = matches[i].match
+      historyEntry.variable = matches[i].variable
+      if (historyEntry.resultType === 'string' && historyEntry.result.match(/^>passthrough\[/)) {
+        historyEntry.variableType = 'encodedUnknown'
       }
       if (resolverType) {
-        historyEntry.varType = resolverType
+        historyEntry.variableType = resolverType
+      }
+      historyEntry.result = finalResult
+
+      const isDeepResult = typeof finalResult === 'string' && finalResult.match(/^\$\{deep:\d+\}$/)
+
+      if (isDeepResult) {
+        historyEntry.resultAfterDeep = 'TBD'
       }
 
+      historyEntry.resultType = typeof finalResult
+      historyEntry.valueBeforeResolution = valueBeforeResolution
+      historyEntry.from = 'renderMatches'
+      if (isDeepResult) {
+        historyEntry.resultIsDeep = true
+      }
+
+      if (finalResult !== cleanResult) {
+        historyEntry.resultEncoded = cleanResult
+      }
+    
+
+    
+
       // Check if variable has fallback values (comma-separated)
-      const variableParts = splitByComma(matches[0].variable)
+      const variableParts = splitByComma(matches[i].variable)
       if (variableParts.length > 1) {
         historyEntry.hasFallback = true
         historyEntry.valueBeforeFallback = variableParts[0]
@@ -1534,10 +1826,10 @@ class Configorama {
               fallbackData.isResolvedFallback = true
             }
           } else {
-            // Extract varType from variable references
+            // Extract variableType from variable references
             const varTypeMatch = trimmedFallback.match(this.variablesKnownTypes)
             if (varTypeMatch && varTypeMatch[1]) {
-              fallbackData.varType = varTypeMatch[1]
+              fallbackData.variableType = varTypeMatch[1]
             }
           }
 
@@ -1546,33 +1838,16 @@ class Configorama {
       }
 
       // Only add to history if not a duplicate (same match + variable)
-      const isDuplicate = valueObject.resolutionHistory.some(entry => 
-        entry.match === historyEntry.match && 
+      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])
+      // Process the match
       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 || results[i].__internal_metadata)) {
@@ -1586,6 +1861,21 @@ class Configorama {
       console.log(this.deep)
       /** */
     }
+
+    // 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,
+          resolvedPropertyValue: undefined,
+          calls: []
+        }
+      }
+      this.resolutionTracking[pathKey].resolutionHistory = valueObject.resolutionHistory
+    }
+
     return result
   }
   /**
@@ -1734,7 +2024,7 @@ class Configorama {
         if (currentDetails && 
           currentDetails.resultType === 'number' && 
           parentDetails && parentDetails.resultType === 'string' && 
-          parentDetails.result.match(/^\d+$/) && parentDetails.varType === 'env'
+          parentDetails.result.match(/^\d+$/) && parentDetails.variableType === 'env'
         ) {
           if (Number(parentDetails.result) === currentDetails.result) {
             property = String(valueToPopulate)
@@ -1990,7 +2280,23 @@ Missing Value ${missingValue} - ${matchedString}
         })
       }
       property = foundFilters.reduce((acc, filter) => {
-        const newVal = this.filters[filter](acc, 'from populateVariable')
+        // Check if filter has function-style arguments
+        const funcMatch = filter.match(/^(\w+)\((.*)\)$/)
+        let filterName = filter
+        let filterArgs = []
+
+        if (funcMatch) {
+          filterName = funcMatch[1]
+          const rawArgs = funcMatch[2]
+          if (rawArgs) {
+            const splitter = splitCsv(rawArgs, ', ')
+            filterArgs = formatFunctionArgs(splitter)
+          }
+        }
+
+        const newVal = filterArgs.length > 0
+          ? this.filters[filterName](acc, ...filterArgs, 'from populateVariable')
+          : this.filters[filterName](acc, 'from populateVariable')
         // console.log('PROPERTY', newVal)
         return newVal
       }, property)
@@ -2100,10 +2406,27 @@ Missing Value ${missingValue} - ${matchedString}
         this.resolutionTracking[pathKey] = {
           path: pathKey,
           originalPropertyString: propertyString,
+          resolvedPropertyValue: undefined,
           calls: []
         }
       }
 
+      // this.resolutionTracking[pathKey].resolutionHistory = this.resolutionTracking[pathKey].resolutionHistory || []
+
+      // const isDuplicate = this.resolutionTracking[pathKey].resolutionHistory.some(entry => 
+      //   entry.variableString === variableString
+      // )
+
+      // if (!isDuplicate) {
+      //   this.resolutionTracking[pathKey].resolutionHistory.push({
+      //     variableString: variableString,
+      //     propertyString: propertyString,
+      //     caller: caller,
+      //     lol: 'what'
+      //   })
+      // }
+
+
       this.resolutionTracking[pathKey].calls.push({
         variableString: variableString,
         propertyString: propertyString,
@@ -2210,7 +2533,6 @@ Missing Value ${missingValue} - ${matchedString}
         this.options,
         this.config,
         valueObject,
-
       ).then((val) => {
         // Update the last call with the resolved value
         if (pathValue && pathValue.length) {
@@ -2219,7 +2541,8 @@ Missing Value ${missingValue} - ${matchedString}
             // 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
+                const v = (typeof val === 'object' && val.__internal_only_flag) ? val.value : val
+                this.resolutionTracking[pathKey].calls[i].resolvedValue = v
                 this.resolutionTracking[pathKey].calls[i].resolverType = resolverType
                 break
               }
@@ -2260,17 +2583,22 @@ 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, this.variablesKnownTypes)
+          const nestedVars = findNestedVariables(propertyString, this.variableSyntax, this.variablesKnownTypes, undefined, this.variableTypes)
           // console.log('nestedVars', nestedVars)
           const noNestedVars = nestedVars.length < 2
+
+          if (this.opts.allowUnknownFileRefs && variableString.match(fileRefSyntax)) {
+            // Encode the unknown file variable to pass through resolution
+            return Promise.resolve(encodeUnknown(propertyString))
+          }
+
           if (valueCount.length === 1 && noNestedVars) {
-            const configFilePath = (this.configFilePath) ? ` in ${this.configFilePath}` : ''
-            throw new Error(`
-Unable to resolve configuration variable
+            const configFilePathMsg = (this.configFilePath) ? `\nIn file ${this.configFilePath} ` : ''
+            const fromLine = (propertyString !== valueObject.originalSource) ? `\n  From   "${valueObject.originalSource}"\n` : ''
+
 
-  Value  "${propertyString}" 
-  From   "${valueObject.originalSource}" 
-  At location ${valueObject.path ? `"${arrayToJsonPath(valueObject.path)}"` : 'na'}${configFilePath}
+
+            throw new Error(`Unable to resolve config variable "${propertyString}".\n${configFilePathMsg}at location ${valueObject.path ? `"${arrayToJsonPath(valueObject.path)}"` : 'n/a'}${fromLine}
 \nFix this reference, your inputs and/or provide a valid fallback value.
 \nExample of setting a fallback value: \${${variableString}, "fallbackValue"\}\n`)
           }
@@ -2305,13 +2633,28 @@ Unable to resolve configuration variable
         }
 
         const newUse = newHasFilter.reduce((acc, currentFilter, i) => {
-          if (!this.filters[currentFilter]) {
-            throw new Error(`Filter "${currentFilter}" not found`)
+          // Check if filter has function-style arguments: filterName(arg1, arg2)
+          const funcMatch = currentFilter.match(/^(\w+)\((.*)\)$/)
+          let filterName = currentFilter
+          let filterArgs = null
+
+          if (funcMatch) {
+            filterName = funcMatch[1]
+            const rawArgs = funcMatch[2]
+            // Parse arguments using the same logic as functions
+            if (rawArgs) {
+              const splitter = splitCsv(rawArgs, ', ')
+              filterArgs = formatFunctionArgs(splitter)
+            }
+          }
+
+          if (!this.filters[filterName]) {
+            throw new Error(`Filter "${filterName}" not found`)
           }
           return acc.concat({
-            filter: this.filters[currentFilter],
-            filterName: currentFilter,
-            // args: argsToPass
+            filter: this.filters[filterName],
+            filterName: filterName,
+            args: filterArgs
           })
         }, [])
         // console.log('pathValue', pathValue)
@@ -2573,7 +2916,7 @@ Unable to resolve configuration variable
     // console.log('matchedFileString', matchedFileString)
 
     // Get function input params if any supplied https://regex101.com/r/qlNFVm/1
-  // var funcParamsRegex = /(\w+)\s*\(((?:[^()]+)*)?\s*\)\s*/g
+    // var funcParamsRegex = /(\w+)\s*\(((?:[^()]+)*)?\s*\)\s*/g
     var funcParamsRegex = /(\w+)\s*\(((?:[^()]+)*)?\s*\)/g
     // tighter (?<![.\w-])\b(\w+)\s*\(((?:[^()]+)*)?\s*\)\s*
     var hasParams = funcParamsRegex.exec(matchedFileString)
@@ -2597,45 +2940,37 @@ Unable to resolve configuration variable
     }
     // console.log('argsToPass', argsToPass)
 
-    const relativePath = trimSurroundingQuotes(
-      matchedFileString.replace(syntax, (match, varName) => varName.trim()).replace('~', os.homedir()),
-    )
-
-    // Resolve alias if the path contains alias syntax
-    const resolvedPath = resolveAlias(relativePath, this.configPath)
-    // console.log('resolvedPath', resolvedPath)
+    const fileDetails = resolveFilePathFromMatch(matchedFileString, syntax, this.configPath)
+    // console.log('fileDetails', fileDetails)
 
-    let fullFilePath = path.isAbsolute(resolvedPath) ? resolvedPath : path.join(this.configPath, resolvedPath)
+    const { fullFilePath, resolvedPath, relativePath } = fileDetails
 
-    // console.log('fullFilePath', fullFilePath)
+    const exists = fs.existsSync(fullFilePath)
 
-    if (fs.existsSync(fullFilePath)) {
-      // Get real path to handle potential symlinks (but don't fatal error)
-      fullFilePath = fs.realpathSync(fullFilePath)
-
-      // Only match files that are relative
-    } else if (resolvedPath.match(/\.\//)) {
-      // TODO test higher parent refs
-      const cleanName = path.basename(resolvedPath)
-      const findUpResult = findUp.sync(cleanName, { cwd: this.configPath })
-      if (findUpResult) {
-        fullFilePath = findUpResult
-      }
-    }
+    this.fileRefsFound.push({
+      // location: options.context.path.join('.'),
+      filePath: fullFilePath,
+      relativePath,
+      resolvedVariableString: options.context.value,
+      originalVariableString: options.context.originalSource,
+      containsVariables: options.context.value !== options.context.originalSource,
+      exists,
+    })
 
     let fileExtension = resolvedPath.split('.')
 
     fileExtension = fileExtension[fileExtension.length - 1]
 
     // Validate file exists
-    if (!fs.existsSync(fullFilePath)) {
+    if (!exists) {
       const originalVar = options.context && options.context.originalSource
 
       const findNestedResult = findNestedVariables(
-        originalVar, 
-        this.variableSyntax, 
-        this.variablesKnownTypes, 
-        options.context.path
+        originalVar,
+        this.variableSyntax,
+        this.variablesKnownTypes,
+        options.context.path,
+        this.variableTypes
       )
       // console.log('findNestedResult', findNestedResult)
       let hasFallback = false
@@ -2649,9 +2984,10 @@ Unable to resolve configuration variable
       // console.log('NO FILE FOUND', fullFilePath)
       // console.log('variableString', variableString)
 
-      if (!hasFallback) {
+      if (!hasFallback && !this.opts.allowUnknownFileRefs) {
         const errorMsg = makeBox({
           title: `File Not Found in ${originalVar}`,
+          minWidth: '100%',
           text: `Variable ${variableString} cannot resolve due to missing file.
 
 File not found ${fullFilePath}
@@ -2667,13 +3003,19 @@ ${JSON.stringify(options.context, null, 2)}`,
       return Promise.resolve(undefined)
     }
 
+  
+
     let valueToPopulate
 
     const variableFileContents = fs.readFileSync(fullFilePath, 'utf-8')
 
     /* handle case for referencing raw JS files to inline them */
-    if (argsToPass.length && (argsToPass && argsToPass[0]  && argsToPass[0].toLowerCase() === 'raw') || opts.asRawText) {
-      valueToPopulate = variableFileContents.replace(/\(/g, '__PH_PAREN_OPEN__')
+    if (argsToPass.length 
+      && (argsToPass && argsToPass[0] && argsToPass[0].toLowerCase() === 'raw') 
+      || opts.asRawText
+    ) {
+      // Encode foo() to foo__PH_PAREN_OPEN__) to avoid function collisions
+      valueToPopulate = encodeJsSyntax(variableFileContents)
       return Promise.resolve(valueToPopulate)
     }
 
@@ -3020,25 +3362,25 @@ Please use ":" to reference sub properties. ${deepProperties}`
   }
 
   warnIfNotFound(variableString, valueToPopulate) {
-    let varType
+    let variableTypeText
     if (variableString.match(envRefSyntax)) {
-      varType = 'environment variable'
+      variableTypeText = 'environment variable'
     } else if (variableString.match(optRefSyntax)) {
-      varType = 'option'
+      variableTypeText = 'option'
     } else if (variableString.match(selfRefSyntax)) {
-      varType = 'config attribute'
+      variableTypeText = 'config attribute'
     } else if (variableString.match(fileRefSyntax)) {
-      varType = 'file'
+      variableTypeText = 'file'
     } else if (variableString.match(deepRefSyntax)) {
-      varType = 'deep'
+      variableTypeText = 'deep'
     } else if (variableString.match(textRefSyntax)) {
-      varType = 'text'
+      variableTypeText = 'text'
     }
     if (!isValidValue(valueToPopulate)) {
       // console.log("MISSING", variableString)
       // console.log(this.deep)
       // console.log(valueToPopulate)
-      const notFoundMsg = `No ${varType} found to satisfy the '\${${variableString}}' variable. Attempting fallback value`
+      const notFoundMsg = `No ${variableTypeText} found to satisfy the '\${${variableString}}' variable. Attempting fallback value`
       if (DEBUG) {
         console.log(notFoundMsg)
       }