configorama 0.6.11 → 0.6.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "configorama",
-  "version": "0.6.11",
+  "version": "0.6.12",
   "description": "Variable support for configuration files",
   "main": "src/index.js",
   "types": "index.d.ts",

package/src/main.js

@@ -2,6 +2,7 @@ const os = require('os')
 const path = require('path')
 const fs = require('fs')
 const enrichMetadata = require('./utils/enrichMetadata')
+const { normalizePath, extractFilePath, resolveInnerVariables } = require('./utils/filePathUtils')
 /* // disable logs to find broken tests
 console.log = () => {}
 // process.exit(1)
@@ -753,6 +754,9 @@ class Configorama {
       if (varKeys.length > 0) {
         const fileName = this.configFilePath ? ` in ${this.configFilePath}` : ''
 
+        // Extract base variable name from varMatch key (e.g., '${env:FOO, default}' -> 'env:FOO')
+        const getBaseVarName = (key) => key.replace(/^\$\{/, '').replace(/\}$/, '').split(',')[0].trim()
+
         logHeader(`Found ${varKeys.length} Variables${fileName}`)
 
         // deepLog('variableData', variableData)
@@ -765,9 +769,7 @@ class Configorama {
 
           // 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 varName = getBaseVarName(k)
             const uniqueVar = uniqueVariables[varName]
             const refCount = uniqueVar ? uniqueVar.occurrences.length : variableData[k].length
             const placesWord = refCount > 1 ? 'places' : 'place'
@@ -788,7 +790,7 @@ class Configorama {
           const firstInstance = variableInstances[0]
 
           // Get uniqueVariable data for description and other metadata
-          const varName = key.replace(/^\$\{/, '').replace(/\}$/, '').split(',')[0].trim()
+          const varName = getBaseVarName(key)
           const uniqueVar = uniqueVariables[varName]
 
           // Build display message from enriched metadata
@@ -807,38 +809,16 @@ class Configorama {
           }
 
           // 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`
-            }
+          if (uniqueVar && uniqueVar.types && uniqueVar.types.length > 0) {
+            const typeLabel = `${indent}${keyChalk('Type:'.padEnd(titleText.length, ' '))}`
+            varMsg += `${typeLabel} ${valueChalk(uniqueVar.types.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`
-            }
+          if (uniqueVar && uniqueVar.descriptions && uniqueVar.descriptions.length > 0) {
+            const descText = `${indent}${keyChalk('Description:'.padEnd(titleText.length, ' '))}`
+            const combinedDesc = uniqueVar.descriptions.join('. ')
+            varMsg += `${descText} ${valueChalk(combinedDesc)}\n`
           }
 
     
@@ -873,11 +853,7 @@ class Configorama {
               // 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
-
+                const pathType = occurrence && occurrence.type
                 typeText = pathType ? ` ${chalk.dim(`Type: ${pathType}`)}` : ''
                 const prefix = idx === 0 ? '' : `${indent}${pathIndent}`
                 return `${prefix}${valueChalk(`- ${v.path}`)}${typeText}`
@@ -888,12 +864,7 @@ class Configorama {
             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
-
+            const pathType = firstInstance.type
             typeText = pathType ? ` ${chalk.dim(`Type: ${pathType}`)}` : ''
           }
           varMsg += `${locationLabel} ${locationRender}`
@@ -1129,10 +1100,15 @@ class Configorama {
     const variablesKnownTypes = this.variablesKnownTypes
     const variableTypes = this.variableTypes
     const filterMatch = this.filterMatch
+    const configFilePath = this.configFilePath
+    const originalConfig = this.originalConfig
     const foundVariables = []
     const variableData = {}
     const fileRefs = []
     const fileGlobPatterns = []
+    const preResolvedPaths = new Set()
+    const byConfigPath = []
+    const referencesMap = new Map()
     let matchCount = 1
 
     traverse(this.originalConfig).forEach(function (rawValue) {
@@ -1304,46 +1280,75 @@ class Configorama {
         nested.forEach((detail) => {
           // 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()
-              
-              // 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
-              }
+            const extracted = extractFilePath(detail.variable)
+            if (extracted) {
+              const normalizedPath = normalizePath(extracted.filePath)
+              if (!normalizedPath) return
 
-              // 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)) {
+              const containsVariables = !!normalizedPath.match(variableSyntax)
+              let globPattern
+              if (containsVariables) {
                 // Replace variable syntax ${...} with * for glob pattern
-                const globPattern = normalizedPath.replace(variableSyntax, '*')
+                globPattern = normalizedPath.replace(variableSyntax, '*')
                 if (!fileGlobPatterns.includes(globPattern)) {
                   fileGlobPatterns.push(globPattern)
                 }
               }
+
+              // Try to pre-resolve inner variables from originalConfig
+              let resolvedPath = normalizedPath
+              let resolvedVarString = rawValue
+              if (containsVariables) {
+                const pathResult = resolveInnerVariables(normalizedPath, variableSyntax, originalConfig, dotProp.get)
+                const varStringResult = resolveInnerVariables(rawValue, variableSyntax, originalConfig, dotProp.get)
+
+                if (pathResult.didResolve) {
+                  resolvedPath = normalizePath(pathResult.resolved) || pathResult.resolved
+                  resolvedVarString = varStringResult.resolved
+                  preResolvedPaths.add(resolvedPath)
+                }
+              }
+
+              // Build byConfigPath entry
+              const absolutePath = configFilePath
+                ? path.resolve(path.dirname(configFilePath), resolvedPath)
+                : resolvedPath
+              const fileExists = configFilePath ? fs.existsSync(absolutePath) : false
+
+              const configPathEntry = {
+                location: configValuePath,
+                filePath: absolutePath,
+                relativePath: resolvedPath,
+                originalVariableString: rawValue,
+                resolvedVariableString: resolvedVarString,
+                containsVariables,
+                exists: fileExists,
+              }
+              if (globPattern) {
+                configPathEntry.pattern = globPattern
+              }
+              byConfigPath.push(configPathEntry)
+
+              // Build references entry (use resolvedPath as key when available)
+              const refKey = resolvedPath
+              if (!referencesMap.has(refKey)) {
+                referencesMap.set(refKey, {
+                  resolvedPath: refKey,
+                  refs: [],
+                })
+              }
+              const refEntry = referencesMap.get(refKey)
+              refEntry.refs.push({
+                location: configValuePath,
+                value: normalizedPath,
+                originalVariableString: rawValue,
+              })
             }
           }
         })
@@ -1423,12 +1428,13 @@ class Configorama {
         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,
+        // Resolved paths: static paths + pre-resolved dynamic paths
+        resolvedPaths: [
+          ...fileRefs.filter(ref => ref.indexOf('*') === -1 && !ref.match(variableSyntax)),
+          ...preResolvedPaths
+        ],
+        byConfigPath,
+        references: Array.from(referencesMap.values()),
       },
       summary: {
         totalVariables: varKeys.length,

package/src/utils/configWizard.js

@@ -223,17 +223,27 @@ function validateType(value, expectedType) {
 }
 
 /**
- * Extracts type from variable occurrences
- * @param {Array} occurrences - Variable occurrences
+ * Extracts type from variable data or occurrences
+ * @param {object} varData - Variable data with types array or occurrences
  * @returns {string|null} Expected type or null
  */
-function getExpectedType(occurrences) {
-  if (!occurrences || occurrences.length === 0) return null
+function getExpectedType(varData) {
+  // Use pre-computed types if available
+  if (varData && varData.types && varData.types.length > 0) {
+    return varData.types[0]
+  }
+
+  // Fallback to checking occurrences
+  const occurrences = varData && varData.occurrences ? varData.occurrences : varData
+  if (!occurrences || !Array.isArray(occurrences) || occurrences.length === 0) return null
 
   for (const occ of occurrences) {
+    // Check pre-computed type on occurrence
+    if (occ.type) return occ.type
+
+    // Fallback to filters
     if (occ.filters && Array.isArray(occ.filters)) {
       for (const filter of occ.filters) {
-        // Check if filter starts with uppercase letter
         if (filter && typeof filter === 'string' && /^[A-Z]/.test(filter)) {
           return filter
         }
@@ -244,23 +254,28 @@ function getExpectedType(occurrences) {
 }
 
 /**
- * Extracts help text from variable occurrences
- * @param {Array} occurrences - Variable occurrences
+ * Extracts help text from variable data or occurrences
+ * @param {object} varData - Variable data with descriptions array or occurrences
  * @returns {string|null} Help text or null
  */
-function getHelpText(occurrences) {
-  if (!occurrences || occurrences.length === 0) return null
+function getHelpText(varData) {
+  // Use pre-computed descriptions if available
+  if (varData && varData.descriptions && varData.descriptions.length > 0) {
+    return varData.descriptions.join('. ')
+  }
+
+  // Fallback to checking occurrences
+  const occurrences = varData && varData.occurrences ? varData.occurrences : varData
+  if (!occurrences || !Array.isArray(occurrences) || occurrences.length === 0) return null
 
   for (const occ of occurrences) {
-    // Check for description field first (preferred)
     if (occ.description) {
       return occ.description
     }
 
-    // Fallback to checking filters array (for backwards compatibility)
+    // Fallback to checking filters array
     if (occ.filters && Array.isArray(occ.filters)) {
       for (const filter of occ.filters) {
-        // Check if filter has help() syntax
         const helpMatch = filter.match(/^help\(['"](.+)['"]\)$/)
         if (helpMatch) {
           return helpMatch[1]
@@ -290,22 +305,20 @@ function createPromptMessage(varInfo) {
     typeLabel = 'Value'
   }
 
-  // Check for type from filters
-  const expectedType = getExpectedType(occurrences)
+  // Check for type - use pre-computed if available
+  const expectedType = getExpectedType(varInfo)
 
   // Append type to label if found
   if (expectedType) {
     typeLabel = `${typeLabel}:${expectedType}`
   }
 
-  // Collect all unique descriptions from occurrences
-  const descriptions = []
-  if (occurrences && occurrences.length > 0) {
-    occurrences.forEach(occ => {
-      if (occ.description && !descriptions.includes(occ.description)) {
-        descriptions.push(occ.description)
-      }
-    })
+  // Use pre-computed descriptions if available, otherwise collect from occurrences
+  let descriptions = varInfo.descriptions || []
+  if (descriptions.length === 0 && occurrences && occurrences.length > 0) {
+    descriptions = occurrences
+      .map(occ => occ.description)
+      .filter((d, i, a) => d && a.indexOf(d) === i)
   }
 
   // Build context from all occurrences

package/src/utils/enrichMetadata.js

@@ -1,7 +1,36 @@
-const { splitCsv } = require('./splitCsv')
 const dotProp = require('dot-prop')
 const fs = require('fs')
 const path = require('path')
+const { normalizePath, extractFilePath, normalizeFileVariable, resolveInnerVariables } = require('./filePathUtils')
+
+// Type filters that indicate expected value types
+const TYPE_FILTERS = ['Boolean', 'String', 'Number', 'Array', 'Object', 'Json']
+
+/**
+ * Extract type filter from filters array
+ * @param {Array} filters - Filters array from variable instance
+ * @returns {string|undefined} Type filter if found
+ */
+function extractTypeFromFilters(filters) {
+  if (!filters || !Array.isArray(filters)) return undefined
+  return filters.find(f => TYPE_FILTERS.includes(f))
+}
+
+/**
+ * Extract description from filters array (help filter)
+ * @param {Array} filters - Filters array from variable instance
+ * @returns {string|undefined} Description if found
+ */
+function extractDescriptionFromFilters(filters) {
+  if (!filters || !Array.isArray(filters)) return undefined
+  for (const filter of filters) {
+    if (filter && typeof filter === 'string') {
+      const helpMatch = filter.match(/^help\(['"](.+)['"]\)$/)
+      if (helpMatch) return helpMatch[1]
+    }
+  }
+  return undefined
+}
 
 /**
  * Create a standardized occurrence object
@@ -29,6 +58,9 @@ function createOccurrence(instance, varMatch, options = {}) {
     }
   }
 
+  // Extract type from filters
+  const type = extractTypeFromFilters(filters)
+
   const occurrence = {
     originalString: instance.originalStringValue,
     varMatch: varMatch,
@@ -40,6 +72,10 @@ function createOccurrence(instance, varMatch, options = {}) {
     hasFallback: options.hasFallback !== undefined ? options.hasFallback : (instance.hasFallback || false),
   }
 
+  if (type) {
+    occurrence.type = type
+  }
+
   if (description) {
     occurrence.description = description
   }
@@ -51,56 +87,6 @@ function createOccurrence(instance, varMatch, options = {}) {
   return occurrence
 }
 
-/**
- * Extract file path from a file() or text() reference string
- * @param {string} propertyString - The property string containing file/text reference
- * @returns {object|null} Object with filePath, or null if no match
- */
-function extractFilePath(propertyString) {
-  const fileMatch = propertyString.match(/^\$\{(?:file|text)\((.*?)\)/)
-  if (!fileMatch || !fileMatch[1]) {
-    return null
-  }
-  
-  const fileContent = fileMatch[1].trim()
-  const parts = splitCsv(fileContent)
-  let filePath = parts[0].trim()
-  
-  // Remove quotes if present
-  filePath = filePath.replace(/^['"]|['"]$/g, '')
-  
-  return { filePath }
-}
-
-/**
- * Normalize a file path (add ./ prefix, fix .//, skip deep refs)
- * @param {string} filePath - The file path to normalize
- * @returns {string|null} Normalized path, or null if should be skipped
- */
-function normalizePath(filePath) {
-  // Skip deep references
-  if (filePath.includes('deep:')) {
-    return null
-  }
-  
-  let normalized = filePath
-  
-  // Add ./ prefix for relative paths
-  if (!filePath.startsWith('./') && 
-      !filePath.startsWith('../') && 
-      !filePath.startsWith('/') && 
-      !filePath.startsWith('~')) {
-    normalized = './' + filePath
-  }
-  
-  // Fix double slashes
-  if (normalized.startsWith('.//')) {
-    normalized = normalized.replace('.//', './')
-  }
-  
-  return normalized
-}
-
 /**
  * Enriches variable metadata with resolution tracking data.
  * @param {object} metadata - The metadata object from collectVariableMetadata.
@@ -173,6 +159,16 @@ function enrichMetadata(
           }
         }
       }
+
+      // Add type and description to individual variable instance
+      const instanceType = extractTypeFromFilters(varData.filters)
+      const instanceDescription = extractDescriptionFromFilters(varData.filters)
+      if (instanceType) {
+        varData.type = instanceType
+      }
+      if (instanceDescription) {
+        varData.description = instanceDescription
+      }
     }
   }
 
@@ -198,7 +194,8 @@ function enrichMetadata(
   }
 
   // Update fileDependencies.resolvedPaths with the resolved file refs
-  if (metadata.fileDependencies) {
+  // Only overwrite if we have enriched data, otherwise keep original from collectVariableMetadata
+  if (metadata.fileDependencies && resolvedFileRefs.length > 0) {
     metadata.fileDependencies.resolvedPaths = resolvedFileRefs
   }
 
@@ -304,10 +301,14 @@ function enrichMetadata(
     }
   }
 
-  // Update fileDependencies with the enriched data
+  // Update fileDependencies with the enriched data (only if we have data)
   if (metadata.fileDependencies) {
-    metadata.fileDependencies.byConfigPath = byConfigPath
-    metadata.fileDependencies.references = references
+    if (byConfigPath.length > 0) {
+      metadata.fileDependencies.byConfigPath = byConfigPath
+    }
+    if (references.length > 0) {
+      metadata.fileDependencies.references = references
+    }
   }
 
   // Build uniqueVariables rollup - group by base variable (without fallbacks)
@@ -338,24 +339,7 @@ function enrichMetadata(
     }
 
     // Normalize file() and text() references
-    if (baseVar.match(/^(?:file|text)\(/)) {
-      // Strip sub-key accessors like :topLevel, :nested.value, etc.
-      baseVar = baseVar.replace(/:[\w.[\]]+$/, '')
-
-      // Normalize path - remove quotes and ensure it starts with ./
-      baseVar = baseVar.replace(/^(file|text)\((.+?)\)/, (match, funcName, filePath) => {
-        // Remove surrounding quotes (single or double)
-        let cleanPath = filePath.trim().replace(/^["']|["']$/g, '')
-
-        // Use normalizePath for consistent normalization (handles ./, .// etc)
-        const normalized = normalizePath(cleanPath)
-        if (normalized) {
-          return `${funcName}(${normalized})`
-        }
-
-        return match
-      })
-    }
+    baseVar = normalizeFileVariable(baseVar)
 
     if (!uniqueVariablesMap.has(baseVar)) {
       uniqueVariablesMap.set(baseVar, {
@@ -394,17 +378,7 @@ function enrichMetadata(
             const siblingBaseVar = detail.valueBeforeFallback || detail.variable
 
             // Normalize file/text references for sibling too
-            let normalizedSiblingVar = siblingBaseVar
-            if (normalizedSiblingVar.match(/^(?:file|text)\(/)) {
-              // Strip sub-key accessor (e.g., :foo from file(./_inner.yml):foo)
-              normalizedSiblingVar = normalizedSiblingVar.replace(/:[\w.[\]]+$/, '')
-
-              normalizedSiblingVar = normalizedSiblingVar.replace(/^(file|text)\((.+?)\)/, (match, funcName, filePath) => {
-                let cleanPath = filePath.trim().replace(/^["']|["']$/g, '')
-                const normalized = normalizePath(cleanPath)
-                return normalized ? `${funcName}(${normalized})` : match
-              })
-            }
+            const normalizedSiblingVar = normalizeFileVariable(siblingBaseVar)
 
             // Create or get entry for this sibling variable
             if (!uniqueVariablesMap.has(normalizedSiblingVar)) {
@@ -512,12 +486,7 @@ function enrichMetadata(
         }
 
         // Normalize file paths after variable substitution
-        if (resolvedVariable.match(/^(?:file|text)\(/)) {
-          resolvedVariable = resolvedVariable.replace(/^(file|text)\((.+?)\)/, (match, funcName, filePath) => {
-            const normalized = normalizePath(filePath)
-            return normalized ? `${funcName}(${normalized})` : match
-          })
-        }
+        resolvedVariable = normalizeFileVariable(resolvedVariable)
 
         // Update the variable to the resolved version and update map key
         if (resolvedVariable !== baseVar) {
@@ -577,6 +546,25 @@ function enrichMetadata(
     }
   }
 
+  // Aggregate types and descriptions for each uniqueVariable
+  for (const [, entry] of uniqueVariablesMap) {
+    // Collect unique types from occurrences
+    const types = entry.occurrences
+      .map(occ => occ.type)
+      .filter((t, i, a) => t && a.indexOf(t) === i)
+    if (types.length > 0) {
+      entry.types = types
+    }
+
+    // Collect unique descriptions from occurrences
+    const descriptions = entry.occurrences
+      .map(occ => occ.description)
+      .filter((d, i, a) => d && a.indexOf(d) === i)
+    if (descriptions.length > 0) {
+      entry.descriptions = descriptions
+    }
+  }
+
   // Convert map to object for metadata
   metadata.uniqueVariables = Object.fromEntries(uniqueVariablesMap)
 

package/src/utils/filePathUtils.js

@@ -0,0 +1,135 @@
+// Utilities for parsing and normalizing file paths in variable references
+
+const { splitCsv } = require('./splitCsv')
+
+/**
+ * Normalize a file path (add ./ prefix, fix .//, skip deep refs)
+ * @param {string} filePath - The file path to normalize
+ * @returns {string|null} Normalized path, or null if should be skipped
+ */
+function normalizePath(filePath) {
+  // Skip deep references
+  if (filePath.includes('deep:')) {
+    return null
+  }
+
+  let normalized = filePath
+
+  // Add ./ prefix for relative paths
+  if (
+    !filePath.startsWith('./') &&
+    !filePath.startsWith('../') &&
+    !filePath.startsWith('/') &&
+    !filePath.startsWith('~')
+  ) {
+    normalized = './' + filePath
+  }
+
+  // Fix double slashes
+  if (normalized.startsWith('.//')) {
+    normalized = normalized.replace('.//', './')
+  }
+
+  return normalized
+}
+
+/**
+ * Extract file path from a file() or text() variable string
+ * @param {string} variableString - The variable string (with or without ${} wrapper)
+ * @returns {object|null} Object with filePath, or null if no match
+ */
+function extractFilePath(variableString) {
+  // Match both ${file(...)} and file(...) formats
+  const fileMatch = variableString.match(/^(?:\$\{)?(?:file|text)\((.*?)\)/)
+  if (!fileMatch || !fileMatch[1]) {
+    return null
+  }
+
+  const fileContent = fileMatch[1].trim()
+  const parts = splitCsv(fileContent)
+  let filePath = parts[0].trim()
+
+  // Remove quotes if present
+  filePath = filePath.replace(/^['"]|['"]$/g, '')
+
+  return { filePath }
+}
+
+/**
+ * Normalize a file() or text() variable string
+ * Strips key accessors and normalizes the path inside
+ * @param {string} variableString - e.g. "file('./config.json'):key" or "file(config.json)"
+ * @returns {string} Normalized variable string, e.g. "file(./config.json)"
+ */
+function normalizeFileVariable(variableString) {
+  if (!variableString.match(/^(?:file|text)\(/)) {
+    return variableString
+  }
+
+  // Strip sub-key accessors like :topLevel, :nested.value, etc.
+  let normalized = variableString.replace(/:[\w.[\]]+$/, '')
+
+  // Normalize the path inside
+  normalized = normalized.replace(/^(file|text)\((.+?)\)/, (match, funcName, filePath) => {
+    let cleanPath = filePath.trim().replace(/^["']|["']$/g, '')
+    const normalizedPath = normalizePath(cleanPath)
+    return normalizedPath ? `${funcName}(${normalizedPath})` : match
+  })
+
+  return normalized
+}
+
+/**
+ * Resolve inner variables in a string from config values
+ * @param {string} str - String containing variables like ${self:stage}
+ * @param {RegExp} variableSyntax - Regex to match variable syntax
+ * @param {object} config - Config object to look up values
+ * @param {function} getProp - Function to get nested property (e.g. dotProp.get)
+ * @returns {{resolved: string, didResolve: boolean}} Resolved string and whether resolution happened
+ */
+function resolveInnerVariables(str, variableSyntax, config, getProp) {
+  const varMatches = str.match(variableSyntax)
+  if (!varMatches) {
+    return { resolved: str, didResolve: false }
+  }
+
+  let canResolve = true
+  let resolved = str
+  for (const varMatch of varMatches) {
+    const innerVar = varMatch.slice(2, -1) // Remove ${ and }
+    let configPath = null
+
+    // Handle self: prefix
+    if (innerVar.startsWith('self:')) {
+      configPath = innerVar.slice(5)
+    } else if (!innerVar.includes(':')) {
+      // dot.prop style
+      configPath = innerVar
+    }
+
+    if (configPath) {
+      const configValue = getProp(config, configPath)
+      // Only use if it's a static value (not another variable)
+      if (configValue !== undefined &&
+          typeof configValue === 'string' &&
+          !configValue.match(variableSyntax)) {
+        resolved = resolved.replace(varMatch, configValue)
+      } else {
+        canResolve = false
+        break
+      }
+    } else {
+      canResolve = false
+      break
+    }
+  }
+
+  return { resolved: canResolve ? resolved : str, didResolve: canResolve }
+}
+
+module.exports = {
+  normalizePath,
+  extractFilePath,
+  normalizeFileVariable,
+  resolveInnerVariables,
+}

package/src/utils/filePathUtils.test.js

@@ -0,0 +1,214 @@
+// Tests for file path parsing and normalization utilities
+
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { normalizePath, extractFilePath, normalizeFileVariable, resolveInnerVariables } = require('./filePathUtils')
+
+// normalizePath tests
+
+test('normalizePath - returns null for deep: references', () => {
+  assert.is(normalizePath('deep:1'), null)
+  assert.is(normalizePath('some/deep:path'), null)
+})
+
+test('normalizePath - adds ./ prefix to bare paths', () => {
+  assert.is(normalizePath('config.json'), './config.json')
+  assert.is(normalizePath('path/to/file.yml'), './path/to/file.yml')
+})
+
+test('normalizePath - keeps ./ paths unchanged', () => {
+  assert.is(normalizePath('./config.json'), './config.json')
+  assert.is(normalizePath('./path/to/file.yml'), './path/to/file.yml')
+})
+
+test('normalizePath - keeps ../ paths unchanged', () => {
+  assert.is(normalizePath('../config.json'), '../config.json')
+  assert.is(normalizePath('../../path/to/file.yml'), '../../path/to/file.yml')
+})
+
+test('normalizePath - keeps absolute paths unchanged', () => {
+  assert.is(normalizePath('/etc/config.json'), '/etc/config.json')
+  assert.is(normalizePath('/home/user/file.yml'), '/home/user/file.yml')
+})
+
+test('normalizePath - keeps ~ paths unchanged', () => {
+  assert.is(normalizePath('~/config.json'), '~/config.json')
+  assert.is(normalizePath('~/.config/file.yml'), '~/.config/file.yml')
+})
+
+test('normalizePath - fixes .// to ./', () => {
+  assert.is(normalizePath('.//config.json'), './config.json')
+  assert.is(normalizePath('.//path/to/file.yml'), './path/to/file.yml')
+})
+
+// extractFilePath tests
+
+test('extractFilePath - extracts path from file(...) format', () => {
+  const result = extractFilePath('file(./config.json)')
+  assert.is(result.filePath, './config.json')
+})
+
+test('extractFilePath - extracts path from ${file(...)} format', () => {
+  const result = extractFilePath('${file(./config.json)}')
+  assert.is(result.filePath, './config.json')
+})
+
+test('extractFilePath - extracts path from text(...) format', () => {
+  const result = extractFilePath('text(./readme.txt)')
+  assert.is(result.filePath, './readme.txt')
+})
+
+test('extractFilePath - extracts path from ${text(...)} format', () => {
+  const result = extractFilePath('${text(./readme.txt)}')
+  assert.is(result.filePath, './readme.txt')
+})
+
+test('extractFilePath - handles single-quoted paths', () => {
+  const result = extractFilePath("file('./config.json')")
+  assert.is(result.filePath, './config.json')
+})
+
+test('extractFilePath - handles double-quoted paths', () => {
+  const result = extractFilePath('file("./config.json")')
+  assert.is(result.filePath, './config.json')
+})
+
+test('extractFilePath - extracts first path when fallback present', () => {
+  const result = extractFilePath("file(./env.yml, 'default')")
+  assert.is(result.filePath, './env.yml')
+})
+
+test('extractFilePath - handles path with key accessor', () => {
+  const result = extractFilePath('file(./env.yml):FOO')
+  assert.is(result.filePath, './env.yml')
+})
+
+test('extractFilePath - handles complex fallback with key accessor', () => {
+  const result = extractFilePath("file(./env.yml):SECRET, 'default-value'")
+  assert.is(result.filePath, './env.yml')
+})
+
+test('extractFilePath - returns null for non-file patterns', () => {
+  assert.is(extractFilePath('opt:stage'), null)
+  assert.is(extractFilePath('${self:provider.stage}'), null)
+  assert.is(extractFilePath('env:FOO'), null)
+})
+
+test('extractFilePath - returns null for empty input', () => {
+  assert.is(extractFilePath(''), null)
+})
+
+test('extractFilePath - handles bare filename', () => {
+  const result = extractFilePath('file(config.json)')
+  assert.is(result.filePath, 'config.json')
+})
+
+// normalizeFileVariable tests
+
+test('normalizeFileVariable - returns non-file strings unchanged', () => {
+  assert.is(normalizeFileVariable('opt:stage'), 'opt:stage')
+  assert.is(normalizeFileVariable('self:provider.stage'), 'self:provider.stage')
+})
+
+test('normalizeFileVariable - normalizes bare path in file()', () => {
+  assert.is(normalizeFileVariable('file(config.json)'), 'file(./config.json)')
+})
+
+test('normalizeFileVariable - normalizes bare path in text()', () => {
+  assert.is(normalizeFileVariable('text(readme.txt)'), 'text(./readme.txt)')
+})
+
+test('normalizeFileVariable - strips key accessor', () => {
+  assert.is(normalizeFileVariable('file(./env.yml):FOO'), 'file(./env.yml)')
+  assert.is(normalizeFileVariable('file(./config.json):nested.value'), 'file(./config.json)')
+})
+
+test('normalizeFileVariable - strips key accessor with array notation', () => {
+  assert.is(normalizeFileVariable('file(./data.json):items[0]'), 'file(./data.json)')
+})
+
+test('normalizeFileVariable - removes quotes from path', () => {
+  assert.is(normalizeFileVariable("file('./config.json')"), 'file(./config.json)')
+  assert.is(normalizeFileVariable('file("./config.json")'), 'file(./config.json)')
+})
+
+test('normalizeFileVariable - handles combined normalization', () => {
+  assert.is(normalizeFileVariable("file('config.json'):key"), 'file(./config.json)')
+})
+
+test('normalizeFileVariable - keeps ./ paths unchanged', () => {
+  assert.is(normalizeFileVariable('file(./already-normalized.yml)'), 'file(./already-normalized.yml)')
+})
+
+test('normalizeFileVariable - keeps ../ paths unchanged', () => {
+  assert.is(normalizeFileVariable('file(../parent/config.yml)'), 'file(../parent/config.yml)')
+})
+
+// resolveInnerVariables tests
+
+const variableSyntax = /\$\{([^}]+)\}/g
+const getProp = (obj, path) => path.split('.').reduce((o, k) => o && o[k], obj)
+
+test('resolveInnerVariables - returns unchanged when no variables', () => {
+  const result = resolveInnerVariables('./config.json', variableSyntax, {}, getProp)
+  assert.is(result.resolved, './config.json')
+  assert.is(result.didResolve, false)
+})
+
+test('resolveInnerVariables - resolves self: variables from config', () => {
+  const config = { stage: 'prod' }
+  const result = resolveInnerVariables('./database-${self:stage}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './database-prod.json')
+  assert.is(result.didResolve, true)
+})
+
+test('resolveInnerVariables - resolves dot.prop style variables', () => {
+  const config = { stage: 'dev' }
+  const result = resolveInnerVariables('./database-${stage}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './database-dev.json')
+  assert.is(result.didResolve, true)
+})
+
+test('resolveInnerVariables - resolves nested config paths', () => {
+  const config = { provider: { stage: 'test' } }
+  const result = resolveInnerVariables('./db-${self:provider.stage}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './db-test.json')
+  assert.is(result.didResolve, true)
+})
+
+test('resolveInnerVariables - resolves multiple variables', () => {
+  const config = { stage: 'prod', region: 'us-east-1' }
+  const result = resolveInnerVariables('./config-${self:stage}-${self:region}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './config-prod-us-east-1.json')
+  assert.is(result.didResolve, true)
+})
+
+test('resolveInnerVariables - does not resolve if config value is a variable', () => {
+  const config = { stage: '${opt:stage}' }
+  const result = resolveInnerVariables('./database-${self:stage}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './database-${self:stage}.json')
+  assert.is(result.didResolve, false)
+})
+
+test('resolveInnerVariables - does not resolve if config value is undefined', () => {
+  const config = {}
+  const result = resolveInnerVariables('./database-${self:stage}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './database-${self:stage}.json')
+  assert.is(result.didResolve, false)
+})
+
+test('resolveInnerVariables - does not resolve env: or opt: variables', () => {
+  const config = { stage: 'prod' }
+  const result = resolveInnerVariables('./database-${env:STAGE}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './database-${env:STAGE}.json')
+  assert.is(result.didResolve, false)
+})
+
+test('resolveInnerVariables - partial resolution fails completely', () => {
+  const config = { stage: 'prod' }
+  const result = resolveInnerVariables('./config-${self:stage}-${env:REGION}.json', variableSyntax, config, getProp)
+  assert.is(result.resolved, './config-${self:stage}-${env:REGION}.json')
+  assert.is(result.didResolve, false)
+})
+
+test.run()