configorama 0.6.18 → 0.7.0

package/src/parsers/typescript.js

@@ -2,10 +2,10 @@ const path = require('path')
 const fs = require('fs')
 
 /**
- * Execute TypeScript file and return its export
+ * Load TypeScript file and return its export (without executing)
  * @param {string} filePath - Full path to the TypeScript file
- * @param {Object} opts - Additional options including dynamicArgs
- * @returns {Promise<*>} The result of executing the TypeScript file
+ * @param {Object} opts - Additional options (unused, kept for API compat)
+ * @returns {Promise<*>} The exported module from the TypeScript file
  */
 async function executeTypeScriptFile(filePath, opts = {}) {
   // Check if tsx is available first (preferred)
@@ -34,6 +34,7 @@ async function executeTypeScriptFile(filePath, opts = {}) {
   let tsFile
   if (useTsx) {
     // Use tsx for modern, fast TypeScript execution
+    // @ts-ignore - tsx doesn't have type declarations
     const { register } = require('tsx/cjs/api')
     const restore = register()
     try {
@@ -46,6 +47,7 @@ async function executeTypeScriptFile(filePath, opts = {}) {
   } else {
     // Fallback to ts-node
     try {
+      // @ts-ignore - ts-node is optional peer dependency
       require('ts-node/register')
       tsFile = require(filePath)
     } catch (err) {
@@ -53,34 +55,19 @@ async function executeTypeScriptFile(filePath, opts = {}) {
     }
   }
 
-  if (typeof tsFile !== 'function') {
-    return tsFile
-  } else {
-    let tsArgs = opts.dynamicArgs || {}
-    if (tsArgs && typeof tsArgs === 'function') {
-      tsArgs = tsArgs()
-    }
-    
-    try {
-      const result = tsFile(tsArgs)
-      
-      // Handle promises
-      if (result && typeof result.then === 'function') {
-        return await result
-      }
-      
-      return result
-    } catch (err) {
-      throw new Error(`Error executing TypeScript function: ${err.message}`)
-    }
+  // Handle ES module default exports
+  if (tsFile && typeof tsFile === 'object' && 'default' in tsFile) {
+    tsFile = tsFile.default
   }
+
+  return tsFile
 }
 
 /**
- * Synchronous TypeScript file execution (using tsx with sync API)
+ * Load TypeScript file synchronously and return its export
  * @param {string} filePath - Full path to the TypeScript file
- * @param {Object} opts - Additional options including dynamicArgs
- * @returns {*} The result of executing the TypeScript file
+ * @param {Object} opts - Additional options (unused, kept for API compat)
+ * @returns {*} The exported module from the TypeScript file
  */
 function executeTypeScriptFileSync(filePath, opts = {}) {
   // Check if tsx is available first (preferred)
@@ -109,6 +96,7 @@ function executeTypeScriptFileSync(filePath, opts = {}) {
   let tsFile
   if (useTsx) {
     // Use tsx for modern, fast TypeScript execution
+    // @ts-ignore - tsx doesn't have type declarations
     const { register } = require('tsx/cjs/api')
     const restore = register()
     try {
@@ -121,6 +109,7 @@ function executeTypeScriptFileSync(filePath, opts = {}) {
   } else {
     // Fallback to ts-node
     try {
+      // @ts-ignore - ts-node is optional peer dependency
       require('ts-node/register')
       tsFile = require(filePath)
     } catch (err) {
@@ -128,24 +117,12 @@ function executeTypeScriptFileSync(filePath, opts = {}) {
     }
   }
 
-  if (typeof tsFile !== 'function') {
-    return tsFile
-  } else {
-    let tsArgs = opts.dynamicArgs || {}
-    if (tsArgs && typeof tsArgs === 'function') {
-      tsArgs = tsArgs()
-    }
-    
-    try {
-      const result = tsFile(tsArgs)
-      
-      // Note: For sync execution, we don't await promises
-      // If the function returns a promise, it will be resolved by the calling code
-      return result
-    } catch (err) {
-      throw new Error(`Error executing TypeScript function: ${err.message}`)
-    }
+  // Handle ES module default exports
+  if (tsFile && typeof tsFile === 'object' && 'default' in tsFile) {
+    tsFile = tsFile.default
   }
+
+  return tsFile
 }
 
 module.exports = {

package/src/parsers/yaml.js

@@ -3,7 +3,12 @@ const TOML = require('./toml')
 const JSON = require('./json5')
 const { findOutermostVariables, findOutermostBracesDepthFirst } = require('../utils/strings/bracketMatcher')
 
-// Loader for custom CF syntax
+/**
+ * Loader for custom CF syntax
+ * @param {string|Buffer} contents - YAML content to load
+ * @param {Object} [options] - YAML load options
+ * @returns {{data: Object|null, error: Error|null}} Parsed data and error if any
+ */
 function load(contents, options) {
   let data
   let error
@@ -15,6 +20,12 @@ function load(contents, options) {
   return { data, error }
 }
 
+/**
+ * Parse YAML content into JavaScript object
+ * @param {string} ymlContents - YAML string to parse
+ * @returns {Object} Parsed YAML object
+ * @throws {Error} If YAML parsing fails
+ */
 function parse(ymlContents) {
   // Get document, or throw exception on error
   let ymlObject = {}
@@ -26,6 +37,12 @@ function parse(ymlContents) {
   return ymlObject
 }
 
+/**
+ * Convert JavaScript object to YAML string
+ * @param {Object} object - Object to convert to YAML
+ * @returns {string} YAML string representation
+ * @throws {Error} If conversion fails
+ */
 function dump(object) {
   let yml
   try {
@@ -38,6 +55,12 @@ function dump(object) {
   return yml
 }
 
+/**
+ * Convert YAML content to TOML format
+ * @param {string} ymlContents - YAML string to convert
+ * @returns {string} TOML string representation
+ * @throws {Error} If conversion fails
+ */
 function toToml(ymlContents) {
   let toml
   try {
@@ -48,6 +71,12 @@ function toToml(ymlContents) {
   return toml
 }
 
+/**
+ * Convert YAML content to JSON format
+ * @param {string} ymlContents - YAML string to convert
+ * @returns {string} JSON string representation
+ * @throws {Error} If conversion fails
+ */
 function toJson(ymlContents) {
   let json
   try {
@@ -61,12 +90,16 @@ function toJson(ymlContents) {
 // Alias for backward compatibility
 const matchOutermostBraces = findOutermostBracesDepthFirst
 
-
 // https://regex101.com/r/XIltbc/1
 const KEY_OBJECT = /^[ \t]*[^":\s]*:\s+\{/gm
 
 const INNER_ARRAY = /\[(?:[^\[\]])*\]/g
 
+/**
+ * Pre-process YAML string to handle nested variables and CloudFormation syntax
+ * @param {string} [ymlStr=''] - YAML string to pre-process
+ * @returns {string} Pre-processed YAML string
+ */
 function preProcess(ymlStr = '') {
   /*
   return ymlStr

package/src/resolvers/valueFromFile.js

@@ -7,7 +7,7 @@ const { splitCsv } = require('../utils/strings/splitCsv')
 const { resolveFilePathFromMatch, resolveFilePath } = require('../utils/paths/getFullFilePath')
 const { findNestedVariables } = require('../utils/variables/findNestedVariables')
 const { makeBox } = require('@davidwells/box-logger')
-const { encodeJsSyntax } = require('../utils/encoders/js-fixes')
+const { encodeJsSyntax, decodeJsonInVariable, hasEncodedJson } = require('../utils/encoders/js-fixes')
 
 /* File Parsers */
 const YAML = require('../parsers/yaml')
@@ -15,6 +15,29 @@ const TOML = require('../parsers/toml')
 const INI = require('../parsers/ini')
 const JSON5 = require('../parsers/json5')
 
+/**
+ * Recursively clean encoded JSON from an object
+ * @param {*} obj - Object to clean
+ * @returns {*} Cleaned object
+ */
+function cleanEncodedJson(obj) {
+  if (!obj) return obj
+  if (typeof obj === 'string') {
+    return decodeJsonInVariable(obj)
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(cleanEncodedJson)
+  }
+  if (typeof obj === 'object') {
+    const cleaned = {}
+    for (const key of Object.keys(obj)) {
+      cleaned[key] = cleanEncodedJson(obj[key])
+    }
+    return cleaned
+  }
+  return obj
+}
+
 /**
  * Parse file contents based on file extension
  * @param {string} content - Raw file contents
@@ -86,6 +109,17 @@ async function getValueFromFile(ctx, variableString, options) {
       matchedFileString = argsFound[0]
       argsToPass = argsFound.filter((arg, i) => {
         return i !== 0
+      }).map((arg) => {
+        // Decode base64-encoded JSON objects passed as args
+        if (hasEncodedJson(arg)) {
+          const decoded = decodeJsonInVariable(arg)
+          try {
+            return JSON.parse(decoded)
+          } catch (e) {
+            return decoded
+          }
+        }
+        return arg
       })
     }
   }
@@ -137,9 +171,8 @@ async function getValueFromFile(ctx, variableString, options) {
 
   ctx.fileRefsFound.push(fileRefEntry)
 
-  let fileExtension = resolvedPath.split('.')
-
-  fileExtension = fileExtension[fileExtension.length - 1].toLowerCase()
+  const fileExtParts = resolvedPath.split('.')
+  const fileExtension = fileExtParts[fileExtParts.length - 1].toLowerCase()
 
   // Validate file exists
   if (!exists) {
@@ -168,14 +201,14 @@ async function getValueFromFile(ctx, variableString, options) {
       const errorMsg = makeBox({
         title: `File Not Found in ${originalVar}`,
         minWidth: '100%',
-        text: `Variable ${variableString} cannot resolve due to missing file.
+        content: `Variable ${variableString} cannot resolve due to missing file.
 
 File not found ${fullFilePath}
 
 Default fallback value will be used if provided.
 
 ${JSON.stringify(options.context, null, 2)}`,
-  })
+      })
       console.log(errorMsg)
     }
     // TODO maybe reject. YAML does not allow for null/undefined values
@@ -197,11 +230,17 @@ ${JSON.stringify(options.context, null, 2)}`,
     return Promise.resolve(valueToPopulate)
   }
 
+  // Clean encoded JSON from currentConfig for cleaner context
+  const cleanedCurrentConfig = cleanEncodedJson(ctx.config)
+
   // Build context for executable files
   const valueForFunction = {
+    options: ctx.opts.options || {},
     originalConfig: ctx.originalConfig,
-    config: ctx.config,
-    opts: ctx.opts,
+    currentConfig: cleanedCurrentConfig,
+    argsToPass,
+    // maybe helper fns
+    // maybe the lib instance itself for nested lookups
   }
 
   // Process JS files
@@ -230,8 +269,14 @@ ${JSON.stringify(options.context, null, 2)}`,
     try {
       const tsFile = await executeTypeScriptFile(fullFilePath, { dynamicArgs: () => argsToPass })
       let returnValueFunction = tsFile.config || tsFile.default || tsFile
-      if (moduleName) {
+      // For default export functions with :property syntax, keep the function and use deep properties
+      // For named exports (non-function module), look up the named export
+      let includeFirstProperty = false
+      if (moduleName && typeof returnValueFunction !== 'function') {
         returnValueFunction = tsFile[moduleName]
+      } else if (moduleName && typeof returnValueFunction === 'function') {
+        // Default export function with property access - include first property in path
+        includeFirstProperty = true
       }
 
       return processExecutableFile({
@@ -243,7 +288,8 @@ ${JSON.stringify(options.context, null, 2)}`,
         matchedFileString,
         relativePath,
         fileType: 'TypeScript',
-        getDeeperValue: ctx.getDeeperValue
+        getDeeperValue: ctx.getDeeperValue,
+        includeFirstProperty
       })
     } catch (err) {
       return Promise.reject(new Error(`Error processing TypeScript file: ${err.message}`))
@@ -257,8 +303,14 @@ ${JSON.stringify(options.context, null, 2)}`,
     try {
       const esmFile = await executeESMFile(fullFilePath, { dynamicArgs: () => argsToPass })
       let returnValueFunction = esmFile.config || esmFile.default || esmFile
-      if (moduleName) {
+      // For default export functions with :property syntax, keep the function and use deep properties
+      // For named exports (non-function module), look up the named export
+      let includeFirstProperty = false
+      if (moduleName && typeof returnValueFunction !== 'function') {
         returnValueFunction = esmFile[moduleName]
+      } else if (moduleName && typeof returnValueFunction === 'function') {
+        // Default export function with property access - include first property in path
+        includeFirstProperty = true
       }
 
       return processExecutableFile({
@@ -270,7 +322,8 @@ ${JSON.stringify(options.context, null, 2)}`,
         matchedFileString,
         relativePath,
         fileType: 'ESM',
-        getDeeperValue: ctx.getDeeperValue
+        getDeeperValue: ctx.getDeeperValue,
+        includeFirstProperty
       })
     } catch (err) {
       return Promise.reject(new Error(`Error processing ESM file: ${err.message}`))
@@ -295,15 +348,15 @@ ${JSON.stringify(options.context, null, 2)}`,
       }
       // console.log('deep', variableString)
       // console.log('matchedFileString', matchedFileString)
-      let deepProperties = variableString.replace(matchedFileString, '')
+      const deepPropertiesStr = variableString.replace(matchedFileString, '')
       // Support both : and . as the separator for sub properties
-      const firstChar = deepProperties.substring(0, 1)
+      const firstChar = deepPropertiesStr.substring(0, 1)
       if (firstChar !== ':' && firstChar !== '.') {
         const errorMessage = `Invalid variable syntax when referencing file "${relativePath}" sub properties
-Please use ":" or "." to reference sub properties. ${deepProperties}`
+Please use ":" or "." to reference sub properties. ${deepPropertiesStr}`
         return Promise.reject(new Error(errorMessage))
       }
-      deepProperties = deepProperties.slice(1).split('.')
+      const deepProperties = deepPropertiesStr.slice(1).split('.')
       return ctx.getDeeperValue(deepProperties, valueToPopulate)
     }
 
@@ -360,13 +413,21 @@ function parseModuleReference(variableString, matchedFileString) {
  * Extracts deep properties from variable string after file match
  * @param {string} variableString - The full variable string
  * @param {string} matchedFileString - The matched file path portion
+ * @param {boolean} [includeFirstProperty=false] - Include first property (for default exports)
  * @returns {string[]} Array of property keys to traverse
  */
-function extractDeepProperties(variableString, matchedFileString) {
-  let deepProperties = variableString.replace(matchedFileString, '')
-  deepProperties = deepProperties.slice(1).split('.')
-  deepProperties.splice(0, 1)
-  return deepProperties.map((prop) => trim(prop))
+function extractDeepProperties(variableString, matchedFileString, includeFirstProperty = false) {
+  const deepPropertiesStr = variableString.replace(matchedFileString, '')
+  if (!deepPropertiesStr || deepPropertiesStr === '') {
+    return []
+  }
+  const deepProperties = deepPropertiesStr.slice(1).split('.')
+  // For named exports, skip first property (it's the module name)
+  // For default exports, keep all properties
+  if (!includeFirstProperty) {
+    deepProperties.splice(0, 1)
+  }
+  return deepProperties.map((prop) => trim(prop)).filter(Boolean)
 }
 
 /**
@@ -381,6 +442,7 @@ function extractDeepProperties(variableString, matchedFileString) {
  * @param {string} params.relativePath - Relative file path for errors
  * @param {string} params.fileType - Type of file (javascript/TypeScript/ESM)
  * @param {Function} params.getDeeperValue - Function to resolve nested values
+ * @param {boolean} [params.includeFirstProperty=false] - Include first property in path (for default exports)
  * @returns {Promise<any>}
  */
 async function processExecutableFile({
@@ -392,7 +454,8 @@ async function processExecutableFile({
   matchedFileString,
   relativePath,
   fileType,
-  getDeeperValue
+  getDeeperValue,
+  includeFirstProperty = false
 }) {
   if (typeof returnValueFunction !== 'function') {
     const errorMessage = `Invalid variable syntax when referencing file "${relativePath}".
@@ -400,10 +463,10 @@ Check if your ${fileType} is exporting a function that returns a value.`
     return Promise.reject(new Error(errorMessage))
   }
 
-  const valueToPopulate = returnValueFunction.call(fileModule, valueForFunction, ...argsToPass)
+  const valueToPopulate = returnValueFunction.call(fileModule, ...argsToPass, valueForFunction)
 
   return Promise.resolve(valueToPopulate).then((valueToPopulateResolved) => {
-    const deepProperties = extractDeepProperties(variableString, matchedFileString)
+    const deepProperties = extractDeepProperties(variableString, matchedFileString, includeFirstProperty)
     return getDeeperValue(deepProperties, valueToPopulateResolved).then((deepValueToPopulateResolved) => {
       if (typeof deepValueToPopulateResolved === 'undefined') {
         const errorMessage = `Invalid variable syntax when referencing file "${relativePath}".

package/src/resolvers/valueFromGit.js

@@ -10,13 +10,19 @@ const { findProjectRoot } = require('../utils/paths/findProjectRoot')
 const GIT_PREFIX = 'git'
 const gitVariableSyntax = RegExp(/^git:/g)
 
+/**
+ * Execute a shell command
+ * @param {string} cmd - Command to execute
+ * @param {import('child_process').ExecOptions} [options] - Exec options
+ * @returns {Promise<string>}
+ */
 async function _exec(cmd, options = { timeout: 1000 }) {
   return new Promise((resolve, reject) => {
     childProcess.exec(cmd, options, (err, stdout) => {
       if (err) {
         return reject(err)
       }
-      return resolve(stdout.trim())
+      return resolve(String(stdout).trim())
     })
   })
 }
@@ -213,8 +219,10 @@ const cache = new Map()
 
 /**
  * Gets the last Git commit timestamp for a file
- * @param {string} file - Path to the file to check
- * @returns {Promise<Date|undefined>} The commit timestamp or undefined if not in Git
+ * @param {string} _file - Path to the file to check
+ * @param {string} cwd - Working directory
+ * @param {boolean} [throwOnMissing] - Whether to throw on missing file
+ * @returns {Promise<string|undefined>} The commit timestamp ISO string or undefined if not in Git
  */
 async function getGitTimestamp(_file, cwd, throwOnMissing = true) {
   // Validate file path to prevent command injection

package/src/utils/encoders/js-fixes.js

@@ -1,6 +1,9 @@
 const PAREN_OPEN_PLACEHOLDER = '__PH_PAREN_OPEN__'
 const OPEN_PAREN_PLACEHOLDER_PATTERN = /__PH_PAREN_OPEN__/g
 
+const JSON_ENCODED_PREFIX = '__JSON_B64__'
+const JSON_ENCODED_PATTERN = /__JSON_B64__([A-Za-z0-9+/=]+)__/g
+
 function encodeJsSyntax(value = '') {
   return value.replace(/\(/g, PAREN_OPEN_PLACEHOLDER)
 }
@@ -14,9 +17,50 @@ function hasParenthesesPlaceholder(value = '') {
   return OPEN_PAREN_PLACEHOLDER_PATTERN.test(value)
 }
 
+/**
+ * Encode a JSON object to base64 for safe embedding in variable strings
+ * @param {object} obj - Object to encode
+ * @returns {string} Encoded string like __JSON_B64__eyJmb28iOiJiYXIifQ==__
+ */
+function encodeJsonForVariable(obj) {
+  const jsonStr = JSON.stringify(obj)
+  const b64 = Buffer.from(jsonStr).toString('base64')
+  return `${JSON_ENCODED_PREFIX}${b64}__`
+}
+
+/**
+ * Decode base64-encoded JSON from variable strings
+ * @param {string} value - String potentially containing encoded JSON
+ * @returns {string} String with encoded JSON decoded back to JSON strings
+ */
+function decodeJsonInVariable(value) {
+  if (!value || typeof value !== 'string') return value
+  return value.replace(JSON_ENCODED_PATTERN, (match, b64) => {
+    try {
+      const jsonStr = Buffer.from(b64, 'base64').toString('utf8')
+      return jsonStr
+    } catch (e) {
+      return match
+    }
+  })
+}
+
+/**
+ * Check if string contains encoded JSON
+ * @param {string} value - String to check
+ * @returns {boolean}
+ */
+function hasEncodedJson(value) {
+  if (!value || typeof value !== 'string') return false
+  return value.includes(JSON_ENCODED_PREFIX)
+}
+
 module.exports = {
   OPEN_PAREN_PLACEHOLDER_PATTERN,
   hasParenthesesPlaceholder,
   encodeJsSyntax,
   decodeJsSyntax,
+  encodeJsonForVariable,
+  decodeJsonInVariable,
+  hasEncodedJson,
 }

package/src/utils/parsing/mergeByKeys.js

@@ -3,9 +3,10 @@
  */
 function mergeByKeys(data, path, keysToMerge) {
   if (!data) return {}
-  
-  const items = path.split('.').reduce((obj, key) => obj?.[key], data)
-  if (!Array.isArray(items)) return {}
+
+  // Handle empty path - operate on root data
+  const items = path ? path.split('.').reduce((obj, key) => obj?.[key], data) : data
+  if (!Array.isArray(items)) return data
   
   const result = {}
   const mergeAll = !keysToMerge || !Array.isArray(keysToMerge) || keysToMerge.length === 0

package/src/utils/parsing/parse.js

@@ -31,12 +31,12 @@ function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
 
   if (fileType.match(/\.(yml|yaml)/i)) {
     try {
-      const ymlText = YAML.preProcess(contents, regex)
+      const ymlText = YAML.preProcess(contents)
       configObject = YAML.parse(ymlText)
     } catch (err) {
       // Attempt to fix cloudformation refs
       if (err.message.match(/YAMLException/)) {
-        const ymlText = YAML.preProcess(contents, regex)
+        const ymlText = YAML.preProcess(contents)
         const result = YAML.load(ymlText, {
           filename: filePath,
           schema: cloudFormationSchema.schema,
@@ -82,6 +82,8 @@ function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
         configObject = (typeof configObject.config === 'function') ? configObject.config(jsArgs) : configObject.config
       } else if (configObject.default) {
         configObject = (typeof configObject.default === 'function') ? configObject.default(jsArgs) : configObject.default
+      } else if (typeof configObject === 'function') {
+        configObject = configObject(jsArgs)
       }
       // console.log('parseFileContents configObject', configObject)
     } catch (err) {