configorama 0.6.12 → 0.6.13

package/src/utils/paths/findLineForKey.test.js

@@ -0,0 +1,126 @@
+/**
+ * Tests for findLineForKey utility
+ */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { findLineForKey } = require('./findLineForKey')
+
+// YAML tests
+test('YAML - finds key at start of line', () => {
+  const lines = ['foo: bar', 'baz: qux']
+  assert.equal(findLineForKey('foo', lines, '.yml'), 1)
+  assert.equal(findLineForKey('baz', lines, '.yml'), 2)
+})
+
+test('YAML - finds key with indentation', () => {
+  const lines = ['root:', '  nested: value', '  other: thing']
+  assert.equal(findLineForKey('nested', lines, '.yaml'), 2)
+  assert.equal(findLineForKey('other', lines, '.yaml'), 3)
+})
+
+test('YAML - finds key with space before colon', () => {
+  const lines = ['foo : bar']
+  assert.equal(findLineForKey('foo', lines, '.yml'), 1)
+})
+
+test('YAML - returns 0 for missing key', () => {
+  const lines = ['foo: bar']
+  assert.equal(findLineForKey('missing', lines, '.yml'), 0)
+})
+
+// JSON tests
+test('JSON - finds quoted key', () => {
+  const lines = ['{', '  "foo": "bar",', '  "baz": 123', '}']
+  assert.equal(findLineForKey('foo', lines, '.json'), 2)
+  assert.equal(findLineForKey('baz', lines, '.json'), 3)
+})
+
+test('JSON - finds key with space before colon', () => {
+  const lines = ['{ "foo" : "bar" }']
+  assert.equal(findLineForKey('foo', lines, '.json'), 1)
+})
+
+test('JSON5 - works same as JSON', () => {
+  const lines = ['{', '  "foo": "bar"', '}']
+  assert.equal(findLineForKey('foo', lines, '.json5'), 2)
+})
+
+// TOML tests
+test('TOML - finds key with equals', () => {
+  const lines = ['foo = "bar"', 'baz = 123']
+  assert.equal(findLineForKey('foo', lines, '.toml'), 1)
+  assert.equal(findLineForKey('baz', lines, '.toml'), 2)
+})
+
+test('TOML - finds key without spaces around equals', () => {
+  const lines = ['foo="bar"']
+  assert.equal(findLineForKey('foo', lines, '.toml'), 1)
+})
+
+// INI tests
+test('INI - finds key with equals', () => {
+  const lines = ['[section]', 'foo = bar', 'baz = qux']
+  assert.equal(findLineForKey('foo', lines, '.ini'), 2)
+  assert.equal(findLineForKey('baz', lines, '.ini'), 3)
+})
+
+// JS/TS tests
+test('JS - finds unquoted key', () => {
+  const lines = ['module.exports = {', '  foo: "bar",', '  baz: 123', '}']
+  assert.equal(findLineForKey('foo', lines, '.js'), 2)
+  assert.equal(findLineForKey('baz', lines, '.js'), 3)
+})
+
+test('JS - finds double-quoted key', () => {
+  const lines = ['module.exports = {', '  "foo": "bar"', '}']
+  assert.equal(findLineForKey('foo', lines, '.js'), 2)
+})
+
+test('JS - finds single-quoted key', () => {
+  const lines = ["module.exports = {", "  'foo': 'bar'", "}"]
+  assert.equal(findLineForKey('foo', lines, '.js'), 2)
+})
+
+test('JS - finds backtick-quoted key', () => {
+  const lines = ['module.exports = {', '  `foo`: "bar"', '}']
+  assert.equal(findLineForKey('foo', lines, '.js'), 2)
+})
+
+test('TS - works same as JS', () => {
+  const lines = ['export default {', '  foo: "bar"', '}']
+  assert.equal(findLineForKey('foo', lines, '.ts'), 2)
+})
+
+test('MJS - works same as JS', () => {
+  const lines = ['export default {', '  foo: "bar"', '}']
+  assert.equal(findLineForKey('foo', lines, '.mjs'), 2)
+})
+
+// Edge cases
+test('returns 0 for empty lines array', () => {
+  assert.equal(findLineForKey('foo', [], '.yml'), 0)
+})
+
+test('returns 0 for null/undefined key', () => {
+  const lines = ['foo: bar']
+  assert.equal(findLineForKey(null, lines, '.yml'), 0)
+  assert.equal(findLineForKey(undefined, lines, '.yml'), 0)
+})
+
+test('returns 0 for null/undefined lines', () => {
+  assert.equal(findLineForKey('foo', null, '.yml'), 0)
+  assert.equal(findLineForKey('foo', undefined, '.yml'), 0)
+})
+
+test('escapes special regex characters in key', () => {
+  const lines = ['foo.bar: value', 'baz[0]: thing']
+  assert.equal(findLineForKey('foo.bar', lines, '.yml'), 1)
+  assert.equal(findLineForKey('baz[0]', lines, '.yml'), 2)
+})
+
+test('unknown file type falls back to YAML-style', () => {
+  const lines = ['foo: bar']
+  assert.equal(findLineForKey('foo', lines, '.unknown'), 1)
+})
+
+test.run()

package/src/utils/{getFullFilePath.js → paths/getFullFilePath.js}

@@ -2,28 +2,39 @@ const os = require('os')
 const fs = require('fs')
 const path = require('path')
 const findUp = require('find-up')
-const trimSurroundingQuotes = require('./trimSurroundingQuotes')
+const { trimSurroundingQuotes } = require('../strings/quoteUtils')
 const { resolveAlias } = require('./resolveAlias')
 
-module.exports = function getFullPath(fileString, cwd) {
-  const configPath = cwd || process.cwd()
-  const relativePath = fileString.replace('~', os.homedir())
-
-  let fullFilePath = (path.isAbsolute(relativePath) ? relativePath : path.join(configPath, relativePath))
+/**
+ * Core path resolution logic - resolves a file path handling absolute paths, symlinks, and findUp
+ * @param {string} pathToResolve - The path to resolve
+ * @param {string} basePath - The base directory for relative paths
+ * @returns {string} The resolved full file path
+ */
+function resolveFilePath(pathToResolve, basePath) {
+  let fullFilePath = path.isAbsolute(pathToResolve) ? pathToResolve : path.join(basePath, pathToResolve)
 
   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 (relativePath.match(/\.\//)) {
-    const cleanName = path.basename(relativePath)
-    fullFilePath = findUp.sync(cleanName, { cwd: configPath })
+  } else if (pathToResolve.match(/\.\//)) {
+    const cleanName = path.basename(pathToResolve)
+    const findUpResult = findUp.sync(cleanName, { cwd: basePath })
+    if (findUpResult) {
+      fullFilePath = findUpResult
+    }
   }
 
   return fullFilePath
 }
 
+module.exports = function getFullPath(fileString, cwd) {
+  const configPath = cwd || process.cwd()
+  const relativePath = fileString.replace('~', os.homedir())
+  return resolveFilePath(relativePath, configPath)
+}
+
 /**
  * Resolves a file path from a matched file string (e.g., from file() or text() syntax)
  * @param {string} matchedFileString - The matched file string (e.g., "file(path/to/file.js)")
@@ -38,22 +49,7 @@ function resolveFilePathFromMatch(matchedFileString, syntax, configPath) {
 
   // Resolve alias if the path contains alias syntax
   const resolvedPath = resolveAlias(relativePath, configPath)
-
-  let fullFilePath = path.isAbsolute(resolvedPath) ? resolvedPath : path.join(configPath, resolvedPath)
-
-  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: configPath })
-    if (findUpResult) {
-      fullFilePath = findUpResult
-    }
-  }
+  const fullFilePath = resolveFilePath(resolvedPath, configPath)
 
   return { fullFilePath, resolvedPath, relativePath }
 }

package/src/utils/{resolveAlias.js → paths/resolveAlias.js}

@@ -1,7 +1,7 @@
 const path = require('path')
 const fs = require('fs')
 const findUp = require('find-up')
-const JSON5 = require('../parsers/json5')
+const JSON5 = require('../../parsers/json5')
 
 const DEBUG = false
 const DEBUG_LOG = (message) => {

package/src/utils/regex/index.js

@@ -1,4 +1,26 @@
+/**
+ * Shared regex patterns and utilities
+ */
+
+const funcRegex = /(\w+)\s*\(((?:[^()]+)*)?\s*\)\s*/
+const funcStartOfLineRegex = /^(\w+)\s*\(((?:[^()]+)*)?\s*\)\s*/
+const subFunctionRegex = /(\w+):(\w+)\s*\(((?:[^()]+)*)?\s*\)\s*/
+
+/**
+ * Combine multiple regex patterns into single OR pattern
+ * @param {RegExp[]} regexes - Array of regex patterns to combine
+ * @returns {RegExp} Combined regex with OR operator
+ */
+function combineRegexes(regexes) {
+  const patterns = regexes.map(regex => regex.source).filter(Boolean)
+  return new RegExp(`(${patterns.join('|')})`)
+}
 
 module.exports = {
-  functionRegex: /(\w+)\s*\(((?:[^()]+)*)?\s*\)\s*/
+  funcRegex,
+  funcStartOfLineRegex,
+  subFunctionRegex,
+  combineRegexes,
+  // Keep old export name for backwards compat
+  functionRegex: funcRegex
 }

package/src/utils/resolution/preResolveVariable.js

@@ -0,0 +1,260 @@
+/**
+ * Pre-resolve variables that don't have dynamic dependencies.
+ * Uses existing resolvers to avoid duplicating logic.
+ */
+const fs = require('fs')
+const path = require('path')
+const dotProp = require('dot-prop')
+
+const createGitResolver = require('../../resolvers/valueFromGit')
+const { parseFileContents } = require('../../resolvers/valueFromFile')
+
+// Cache for resolved values (they don't change during execution)
+const resolverCache = {}
+
+/**
+ * Check if a string contains unresolved variable syntax
+ * @param {string} str - String to check
+ * @param {RegExp} variableSyntax - Variable syntax regex
+ * @returns {boolean}
+ */
+function hasUnresolvedVars(str, variableSyntax) {
+  if (typeof str !== 'string') return false
+  if (!variableSyntax) {
+    // Fallback to basic pattern if no syntax provided
+    return /\$\{[^}]+\}/.test(str)
+  }
+  // Create a new regex from the source to avoid stateful lastIndex issues
+  const regex = new RegExp(variableSyntax.source, variableSyntax.flags.replace('g', ''))
+  return regex.test(str)
+}
+
+/**
+ * Pre-resolve a single variable reference
+ * @param {string} varString - Variable string like "self:path.to.value" or "env:VAR_NAME"
+ * @param {object} context - Resolution context
+ * @param {object} context.config - Original config object
+ * @param {string} context.configDir - Config file directory
+ * @param {RegExp} context.variableSyntax - Variable syntax regex
+ * @returns {Promise<*>} Resolved value or undefined if can't pre-resolve
+ */
+async function preResolveSingle(varString, context) {
+  const { config = {}, configDir, variableSyntax } = context
+
+  // self: reference
+  if (varString.startsWith('self:')) {
+    const path = varString.slice(5).trim()
+    if (hasUnresolvedVars(path, variableSyntax)) return undefined
+    const value = dotProp.get(config, path)
+    // Only return if the value itself doesn't contain variables
+    if (value !== undefined && !hasUnresolvedVars(JSON.stringify(value), variableSyntax)) {
+      return value
+    }
+    return undefined
+  }
+
+  // env: reference
+  if (varString.startsWith('env:')) {
+    const envVar = varString.slice(4).trim()
+    if (hasUnresolvedVars(envVar, variableSyntax)) return undefined
+    return process.env[envVar]
+  }
+
+  // git: reference - use existing resolver
+  if (varString.startsWith('git:')) {
+    const gitVar = varString.slice(4).trim()
+    if (hasUnresolvedVars(gitVar, variableSyntax)) return undefined
+
+    const cacheKey = `git:${configDir || '.'}:${gitVar}`
+    if (resolverCache[cacheKey] !== undefined) {
+      return resolverCache[cacheKey]
+    }
+
+    try {
+      const gitResolver = createGitResolver(configDir)
+      const value = await gitResolver.resolver(`git:${gitVar}`)
+      resolverCache[cacheKey] = value
+      return value
+    } catch (e) {
+      resolverCache[cacheKey] = undefined
+      return undefined
+    }
+  }
+
+  // opt: reference - CLI options
+  if (varString.startsWith('opt:')) {
+    const optName = varString.slice(4).trim()
+    if (hasUnresolvedVars(optName, variableSyntax)) return undefined
+    const { options = {} } = context
+    return options[optName]
+  }
+
+  // file() reference - read file contents
+  const fileMatch = varString.match(/^file\((.+?)\)(?::(.+))?$/)
+  if (fileMatch) {
+    const filePath = fileMatch[1].trim()
+    const subPath = fileMatch[2] ? fileMatch[2].trim() : null
+
+    if (hasUnresolvedVars(filePath, variableSyntax)) return undefined
+
+    const cacheKey = `file:${configDir || '.'}:${filePath}`
+    if (resolverCache[cacheKey] !== undefined) {
+      const cached = resolverCache[cacheKey]
+      if (subPath && cached && typeof cached === 'object') {
+        return dotProp.get(cached, subPath)
+      }
+      return cached
+    }
+
+    try {
+      const resolvedPath = path.resolve(configDir || '.', filePath)
+      if (!fs.existsSync(resolvedPath)) {
+        resolverCache[cacheKey] = undefined
+        return undefined
+      }
+
+      const content = fs.readFileSync(resolvedPath, 'utf8')
+      const parsed = parseFileContents(content, resolvedPath)
+
+      resolverCache[cacheKey] = parsed
+
+      if (subPath && parsed && typeof parsed === 'object') {
+        return dotProp.get(parsed, subPath)
+      }
+      return parsed
+    } catch (e) {
+      resolverCache[cacheKey] = undefined
+      return undefined
+    }
+  }
+
+  // Simple config reference (no prefix, just a path like "foo.bar")
+  // Only if it looks like a valid path (alphanumeric, dots, underscores)
+  if (/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(varString)) {
+    const value = dotProp.get(config, varString)
+    if (value !== undefined && !hasUnresolvedVars(JSON.stringify(value), variableSyntax)) {
+      return value
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Pre-resolve variable references in a string
+ * Replaces ${varRef} patterns with resolved values where possible
+ * @param {string} str - String containing variable references
+ * @param {object} context - Resolution context
+ * @param {object} context.config - Original config object
+ * @param {string} context.configDir - Config file directory
+ * @param {RegExp} context.variableSyntax - Variable syntax regex
+ * @param {object} [options] - Options
+ * @param {boolean} [options.formatArrays=true] - Join arrays with ", "
+ * @returns {Promise<string>} String with pre-resolved variables
+ */
+async function preResolveString(str, context, options = {}) {
+  if (typeof str !== 'string') return str
+
+  const { formatArrays = true } = options
+  const { variableSyntax } = context
+
+  // Use provided syntax or fallback to basic pattern
+  const varPattern = variableSyntax ? new RegExp(variableSyntax.source, 'g') : /\$\{([^{}]+)\}/g
+
+  // Collect all matches first since we need async resolution
+  const matches = []
+  let match
+  while ((match = varPattern.exec(str)) !== null) {
+    matches.push({ match: match[0], index: match.index })
+  }
+
+  if (matches.length === 0) return str
+
+  // Resolve all matches
+  const resolutions = await Promise.all(matches.map(async ({ match: matchStr }) => {
+    // Extract content between ${ and }
+    const varContent = matchStr.slice(2, -1)
+
+    // Skip if the content itself has ${} (nested variable)
+    if (hasUnresolvedVars(varContent, variableSyntax)) {
+      return matchStr
+    }
+
+    // Handle fallback syntax: ${var, fallback1, fallback2}
+    // Try each in order until one resolves
+    const parts = varContent.split(',').map(p => p.trim())
+
+    for (const part of parts) {
+      // Skip quoted literals for now (they're fallbacks, not resolvable)
+      if (/^['"].*['"]$/.test(part)) {
+        // Return the literal without quotes
+        return part.slice(1, -1)
+      }
+
+      // Skip numeric literals
+      if (/^\d+(\.\d+)?$/.test(part)) {
+        return part
+      }
+
+      const resolved = await preResolveSingle(part, context)
+      if (resolved !== undefined) {
+        // Format the value
+        if (Array.isArray(resolved) && formatArrays) {
+          return resolved.join(', ')
+        }
+        if (typeof resolved === 'object') {
+          return JSON.stringify(resolved)
+        }
+        return String(resolved)
+      }
+    }
+
+    // Couldn't resolve any part, return original
+    return matchStr
+  }))
+
+  // Replace matches with resolved values (in reverse order to preserve indices)
+  let result = str
+  for (let i = matches.length - 1; i >= 0; i--) {
+    const { match: matchStr, index } = matches[i]
+    result = result.slice(0, index) + resolutions[i] + result.slice(index + matchStr.length)
+  }
+
+  return result
+}
+
+/**
+ * Pre-resolve variables in an object recursively
+ * @param {*} obj - Object to process
+ * @param {object} context - Resolution context
+ * @param {object} [options] - Options passed to preResolveString
+ * @returns {Promise<*>} Object with pre-resolved variables
+ */
+async function preResolveObject(obj, context, options = {}) {
+  if (typeof obj === 'string') {
+    return preResolveString(obj, context, options)
+  }
+
+  if (Array.isArray(obj)) {
+    return Promise.all(obj.map(item => preResolveObject(item, context, options)))
+  }
+
+  if (obj !== null && typeof obj === 'object') {
+    const result = {}
+    const entries = Object.keys(obj)
+    const values = await Promise.all(entries.map(key => preResolveObject(obj[key], context, options)))
+    entries.forEach((key, i) => {
+      result[key] = values[i]
+    })
+    return result
+  }
+
+  return obj
+}
+
+module.exports = {
+  preResolveSingle,
+  preResolveString,
+  preResolveObject,
+  hasUnresolvedVars
+}

package/src/utils/resolution/preResolveVariable.test.js

@@ -0,0 +1,98 @@
+/**
+ * Tests for preResolveVariable utility
+ */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { preResolveSingle, preResolveString, hasUnresolvedVars } = require('./preResolveVariable')
+
+// Default variable syntax (matches configorama default)
+const variableSyntax = /\$\{([\s\S]+?)\}/g
+
+// Test hasUnresolvedVars
+test('hasUnresolvedVars - detects variable syntax', () => {
+  assert.is(hasUnresolvedVars('${foo}', variableSyntax), true)
+  assert.is(hasUnresolvedVars('${self:bar}', variableSyntax), true)
+  assert.is(hasUnresolvedVars('hello ${world}', variableSyntax), true)
+  assert.is(hasUnresolvedVars('no variables here', variableSyntax), false)
+  assert.is(hasUnresolvedVars('', variableSyntax), false)
+  assert.is(hasUnresolvedVars(null, variableSyntax), false)
+  assert.is(hasUnresolvedVars(123, variableSyntax), false)
+})
+
+// Test preResolveSingle with config refs
+test('preResolveSingle - resolves simple config path', async () => {
+  const config = { foo: 'bar', nested: { value: 42 } }
+  const ctx = { config, variableSyntax }
+  assert.is(await preResolveSingle('foo', ctx), 'bar')
+  assert.is(await preResolveSingle('nested.value', ctx), 42)
+  assert.is(await preResolveSingle('notfound', ctx), undefined)
+})
+
+test('preResolveSingle - resolves self: refs', async () => {
+  const config = { appName: 'MyApp', settings: { port: 3000 } }
+  const ctx = { config, variableSyntax }
+  assert.is(await preResolveSingle('self:appName', ctx), 'MyApp')
+  assert.is(await preResolveSingle('self:settings.port', ctx), 3000)
+  assert.is(await preResolveSingle('self:missing', ctx), undefined)
+})
+
+test('preResolveSingle - resolves env: refs', async () => {
+  process.env.TEST_PRE_RESOLVE = 'testvalue'
+  const ctx = { config: {}, variableSyntax }
+  assert.is(await preResolveSingle('env:TEST_PRE_RESOLVE', ctx), 'testvalue')
+  assert.is(await preResolveSingle('env:DEFINITELY_NOT_SET_12345', ctx), undefined)
+  delete process.env.TEST_PRE_RESOLVE
+})
+
+test('preResolveSingle - skips values with unresolved vars', async () => {
+  const config = { dynamic: '${other}' }
+  const ctx = { config, variableSyntax }
+  assert.is(await preResolveSingle('dynamic', ctx), undefined)
+  assert.is(await preResolveSingle('self:dynamic', ctx), undefined)
+})
+
+// Test preResolveString
+test('preResolveString - resolves variables in string', async () => {
+  const config = { name: 'World', count: 5 }
+  const ctx = { config, variableSyntax }
+  const result = await preResolveString('Hello ${name}, count: ${count}', ctx)
+  assert.is(result, 'Hello World, count: 5')
+})
+
+test('preResolveString - formats arrays as comma-separated', async () => {
+  const config = { items: ['a', 'b', 'c'] }
+  const ctx = { config, variableSyntax }
+  const result = await preResolveString('Items: ${items}', ctx)
+  assert.is(result, 'Items: a, b, c')
+})
+
+test('preResolveString - handles fallback values', async () => {
+  const config = { existing: 'found' }
+  const ctx = { config, variableSyntax }
+  assert.is(await preResolveString('${existing, "default"}', ctx), 'found')
+  assert.is(await preResolveString('${missing, "default"}', ctx), 'default')
+  assert.is(await preResolveString('${missing, 42}', ctx), '42')
+})
+
+test('preResolveString - leaves unresolvable vars unchanged', async () => {
+  const ctx = { config: {}, variableSyntax }
+  const result = await preResolveString('Value: ${unknown}', ctx)
+  assert.is(result, 'Value: ${unknown}')
+})
+
+test('preResolveString - handles env: in strings', async () => {
+  process.env.TEST_STRING_RESOLVE = 'envval'
+  const ctx = { config: {}, variableSyntax }
+  const result = await preResolveString('Env: ${env:TEST_STRING_RESOLVE}', ctx)
+  assert.is(result, 'Env: envval')
+  delete process.env.TEST_STRING_RESOLVE
+})
+
+test('preResolveString - handles self: in strings', async () => {
+  const config = { version: '1.0.0' }
+  const ctx = { config, variableSyntax }
+  const result = await preResolveString('Version: ${self:version}', ctx)
+  assert.is(result, 'Version: 1.0.0')
+})
+
+test.run()

package/src/utils/strings/bracketMatcher.js

@@ -0,0 +1,86 @@
+/**
+ * Finds all outermost matching brace pairs in a string
+ * @param {string} text - The text to search
+ * @param {string} openChar - The opening character (default: '{')
+ * @param {string} closeChar - The closing character (default: '}')
+ * @param {string} prefix - Optional prefix before opening char (e.g., '$' for '${')
+ * @returns {Array<string>} Array of matched substrings including delimiters
+ */
+function findOutermostBraces(text, openChar = '{', closeChar = '}', prefix = '') {
+  const matches = []
+  let i = 0
+  const openPattern = prefix + openChar
+
+  while (i < text.length) {
+    // Check if we have a match at this position
+    const checkLen = openPattern.length
+    if (text.substring(i, i + checkLen) === openPattern) {
+      let depth = 1
+      let start = i
+      i += checkLen
+
+      while (i < text.length && depth > 0) {
+        if (text[i] === openChar) {
+          depth++
+        } else if (text[i] === closeChar) {
+          depth--
+        }
+        i++
+      }
+
+      if (depth === 0) {
+        matches.push(text.substring(start, i))
+      }
+    } else {
+      i++
+    }
+  }
+
+  return matches
+}
+
+/**
+ * Alternative implementation for finding outermost braces using depth tracking
+ * Optimized for simple bracket matching without prefix
+ * @param {string} text - The text to search
+ * @param {string} openChar - The opening character
+ * @param {string} closeChar - The closing character
+ * @returns {Array<string>} Array of matched substrings including delimiters
+ */
+function findOutermostBracesDepthFirst(text, openChar = '{', closeChar = '}') {
+  const results = []
+  let depth = 0
+  let startIndex = -1
+
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === openChar) {
+      if (depth === 0) {
+        startIndex = i
+      }
+      depth++
+    } else if (text[i] === closeChar) {
+      depth--
+      if (depth === 0 && startIndex !== -1) {
+        results.push(text.substring(startIndex, i + 1))
+        startIndex = -1
+      }
+    }
+  }
+
+  return results
+}
+
+/**
+ * Finds outermost variables with ${} syntax
+ * @param {string} text - The text to search
+ * @returns {Array<string>} Array of matched variables including ${}
+ */
+function findOutermostVariables(text) {
+  return findOutermostBraces(text, '{', '}', '$')
+}
+
+module.exports = {
+  findOutermostBraces,
+  findOutermostBracesDepthFirst,
+  findOutermostVariables
+}