configorama 1.0.1 → 1.1.0

package/src/utils/introspection/audit.js

@@ -12,7 +12,7 @@ function buildAuditReport(introspection, options = {}) {
 
   for (const node of introspection.nodes || []) {
     if (!node.risk || node.risk === 'none') continue
-    findings.push({
+    const finding = {
       id: node.id,
       severity: node.severity || severityForRisk(node.risk),
       risk: node.risk,
@@ -22,7 +22,12 @@ function buildAuditReport(introspection, options = {}) {
       relativePath: node.relativePath,
       configPaths: node.paths || [],
       message: messageForNode(node),
-    })
+    }
+    if (node.sensitive === true) finding.sensitive = true
+    if (node.sensitivityReason) finding.sensitivityReason = node.sensitivityReason
+    if (node.dotenvFile !== undefined) finding.dotenvFile = node.dotenvFile
+    if (node.dotenvReadScope) finding.dotenvReadScope = node.dotenvReadScope
+    findings.push(finding)
   }
 
   if (options.dotenv === true) {
@@ -36,15 +41,11 @@ function buildAuditReport(introspection, options = {}) {
   }
 
   if (options.customResolvers && options.customResolvers.length) {
-    for (const resolver of options.customResolvers.slice().sort()) {
-      findings.push({
-        id: `customResolver:${resolver}`,
-        severity: 'high',
-        risk: 'custom_extension',
-        kind: 'source',
-        variableType: resolver,
-        message: `Custom resolver "${resolver}" can execute user-provided code.`,
-      })
+    const sorted = options.customResolvers.slice().sort((a, b) => {
+      return String(a.type || a).localeCompare(String(b.type || b))
+    })
+    for (const resolver of sorted) {
+      findings.push(customResolverFinding(resolver))
     }
   }
 
@@ -65,9 +66,45 @@ function buildAuditReport(introspection, options = {}) {
   }
 }
 
+/**
+ * Build the audit finding for one custom resolver.
+ * Resolvers that self-describe as sensitive/risky get a specific finding
+ * instead of the generic custom_extension one - never both.
+ * @param {string|{type: string, sensitive?: boolean, risk?: string, description?: string}} resolver
+ * @returns {object} Audit finding
+ */
+function customResolverFinding(resolver) {
+  const source = typeof resolver === 'string' ? { type: resolver } : resolver
+  const { type, sensitive, risk, description } = source
+
+  if (sensitive === true || risk) {
+    const finding = {
+      id: `customResolver:${type}`,
+      severity: 'high',
+      risk: risk || 'custom_extension',
+      kind: 'source',
+      variableType: type,
+      message: `Custom resolver "${type}" reads secret values.${description ? ` ${description}.` : ''}`,
+    }
+    if (sensitive === true) finding.sensitive = true
+    return finding
+  }
+
+  return {
+    id: `customResolver:${type}`,
+    severity: 'high',
+    risk: 'custom_extension',
+    kind: 'source',
+    variableType: type,
+    message: `Custom resolver "${type}" can execute user-provided code.`,
+  }
+}
+
 function messageForNode(node) {
   if (node.risk === 'executable_code') return 'Reference may execute JavaScript or TypeScript.'
   if (node.risk === 'process_spawn') return 'Reference may spawn a git process.'
+  if (node.sensitivityReason === 'dotenv_file' && node.dotenvReadScope === 'full_file') return 'Reference reads an entire dotenv file; resolved output may contain secrets.'
+  if (node.sensitivityReason === 'dotenv_file') return 'Reference reads a key from a dotenv file.'
   if (node.risk === 'local_file_read') return 'Reference reads a local file.'
   if (node.risk === 'data_flow_expression') return 'Expression can read resolved config values but is not JavaScript execution.'
   return `Risk surface: ${node.risk}`

package/src/utils/introspection/model.js

@@ -1,6 +1,7 @@
 const path = require('path')
 const { EXECUTABLE_EXTENSIONS } = require('../security/safetyPolicy')
 const { redactRequirementValue } = require('../redaction/redact')
+const { getDotenvFileRefMetadata } = require('../security/dotenvFileRefs')
 
 const SCHEMA_VERSION = 1
 
@@ -42,6 +43,25 @@ function severityForRisk(risk) {
   return 'info'
 }
 
+function severityForNode(risk, metadata) {
+  if (metadata && metadata.dotenvFile && metadata.dotenvReadScope === 'full_file') return 'medium'
+  return severityForRisk(risk)
+}
+
+function firstOccurrenceVariable(entry) {
+  const occurrence = entry && Array.isArray(entry.occurrences) ? entry.occurrences[0] : null
+  return occurrence ? (occurrence.varMatch || occurrence.originalString) : null
+}
+
+function assignSensitivity(target, metadata) {
+  if (!metadata) return target
+  if (metadata.sensitive === true) target.sensitive = true
+  if (metadata.sensitivityReason) target.sensitivityReason = metadata.sensitivityReason
+  if (metadata.dotenvFile !== undefined) target.dotenvFile = metadata.dotenvFile
+  if (metadata.dotenvReadScope) target.dotenvReadScope = metadata.dotenvReadScope
+  return target
+}
+
 function buildIntrospection(enrichedMetadata = {}, options = {}) {
   const uniqueVariables = enrichedMetadata.uniqueVariables || {}
   const requirements = options.requirements || []
@@ -55,6 +75,11 @@ function buildIntrospection(enrichedMetadata = {}, options = {}) {
     const variableType = normalizeVariableType(entry.variableType)
     const requirement = requirementsByVariable.get(variable)
     const risk = riskForVariable(variableType, variable)
+    const dotenvMetadata = getDotenvFileRefMetadata({
+      ...entry,
+      variable,
+      originalVariableString: firstOccurrenceVariable(entry),
+    })
     const node = {
       id: `variable:${variable}`,
       kind: variableType === 'file' || variableType === 'text'
@@ -64,10 +89,11 @@ function buildIntrospection(enrichedMetadata = {}, options = {}) {
       variableType,
       sourceClass: entry.variableSourceType || entry.sourceClass || requirement?.sourceClass || null,
       risk,
-      severity: severityForRisk(risk),
+      severity: severityForNode(risk, dotenvMetadata || entry),
       paths: [...new Set((entry.occurrences || []).map(occ => occ.path).filter(Boolean))].sort(),
-      sensitive: requirement ? requirement.sensitive === true : false,
+      sensitive: requirement ? requirement.sensitive === true : entry.sensitive === true,
     }
+    assignSensitivity(node, dotenvMetadata || entry)
     if (requirement) {
       node.required = requirement.required
       node.default = redactRequirementValue(requirement, requirement.default)
@@ -104,16 +130,20 @@ function buildIntrospection(enrichedMetadata = {}, options = {}) {
   const fileDeps = enrichedMetadata.fileDependencies || {}
   for (const dep of fileDeps.byConfigPath || []) {
     const id = `file:${dep.relativePath || dep.filePath}`
+    const dotenvMetadata = getDotenvFileRefMetadata(dep)
+    const risk = EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'executable_code' : 'local_file_read'
     if (!nodes.some(node => node.id === id)) {
-      nodes.push({
+      const node = {
         id,
         kind: EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'executable' : 'file',
         path: dep.filePath,
         relativePath: dep.relativePath,
         exists: dep.exists,
-        risk: EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'executable_code' : 'local_file_read',
-        severity: EXECUTABLE_EXTENSIONS.has(path.extname(dep.relativePath || dep.filePath || '').toLowerCase()) ? 'high' : 'low',
-      })
+        risk,
+        severity: severityForNode(risk, dotenvMetadata || dep),
+      }
+      assignSensitivity(node, dotenvMetadata || dep)
+      nodes.push(node)
     }
     if (dep.location) {
       edges.push({

package/src/utils/parsing/enrichMetadata.js

@@ -5,6 +5,7 @@ const { normalizePath, extractFilePath, normalizeFileVariable, resolveInnerVaria
 const { preResolveString, preResolveSingle } = require('../resolution/preResolveVariable')
 const { parseOneOfFilter } = require('../filters/oneOf')
 const { extractComment } = require('./extractComment')
+const { applyDotenvFileRefMetadata, normalizeDotenvFileVariable } = require('../security/dotenvFileRefs')
 
 // Type filters that indicate expected value types
 const TYPE_FILTERS = ['Boolean', 'String', 'Number', 'Array', 'Object', 'Json']
@@ -109,6 +110,12 @@ function getSourceForType(variableType, variableTypes) {
   return typeDef?.source
 }
 
+function sameFileRefPath(left, right) {
+  if (!left || !right) return false
+  const normalize = value => String(value).replace(/^\.\//, '')
+  return normalize(left) === normalize(right)
+}
+
 /**
  * Enriches variable metadata with resolution tracking data.
  * @param {object} metadata - The metadata object from collectVariableMetadata.
@@ -388,6 +395,7 @@ async function enrichMetadata(
             containsVariables: !!ref.hasInnerVariable,
             exists: details.exists,
           }
+          applyDotenvFileRefMetadata(confDetails, details)
           if (ref.pattern) {
             confDetails.pattern = ref.pattern
           }
@@ -478,7 +486,7 @@ async function enrichMetadata(
     }
 
     // Normalize file() and text() references
-    baseVar = normalizeFileVariable(baseVar)
+    baseVar = normalizeDotenvFileVariable(baseVar) || normalizeFileVariable(baseVar)
 
     if (!uniqueVariablesMap.has(baseVar)) {
       uniqueVariablesMap.set(baseVar, {
@@ -536,7 +544,7 @@ async function enrichMetadata(
             const siblingBaseVar = detail.valueBeforeFallback || detail.variable
 
             // Normalize file/text references for sibling too
-            const normalizedSiblingVar = normalizeFileVariable(siblingBaseVar)
+            const normalizedSiblingVar = normalizeDotenvFileVariable(siblingBaseVar) || normalizeFileVariable(siblingBaseVar)
 
             // Create or get entry for this sibling variable
             if (!uniqueVariablesMap.has(normalizedSiblingVar)) {
@@ -665,7 +673,7 @@ async function enrichMetadata(
         }
 
         // Normalize file paths after variable substitution
-        resolvedVariable = normalizeFileVariable(resolvedVariable)
+        resolvedVariable = normalizeDotenvFileVariable(resolvedVariable) || normalizeFileVariable(resolvedVariable)
 
         // Update the variable to the resolved version and update map key
         if (resolvedVariable !== baseVar) {
@@ -712,13 +720,22 @@ async function enrichMetadata(
 
         if (!hasVariables) {
           // Look up in fileRefsFound to see if file exists
-          const fileRef = fileRefsFound.find(ref => ref.relativePath === filePath)
+          const fileRef = fileRefsFound.find(ref => sameFileRefPath(ref.relativePath, filePath))
           if (fileRef) {
             entry.fileExists = fileRef.exists
+            applyDotenvFileRefMetadata(entry, {
+              ...fileRef,
+              variable: entry.variable,
+            })
           } else if (configPath) {
             const thePath = path.resolve(path.dirname(configPath), filePath)
             const fileExists = fs.existsSync(thePath)
             entry.fileExists = fileExists
+            applyDotenvFileRefMetadata(entry, {
+              filePath: thePath,
+              relativePath: filePath,
+              variable: entry.variable,
+            })
           }
         }
       }

package/src/utils/parsing/parse.js

@@ -4,8 +4,10 @@ const path = require('path')
 const YAML = require('../../parsers/yaml')
 const TOML = require('../../parsers/toml')
 const INI = require('../../parsers/ini')
+const DOTENV = require('../../parsers/dotenv')
 const JSON5 = require('../../parsers/json5')
 const HCL = require('../../parsers/hcl')
+const { isEnvFile } = require('../paths/fileType')
 const { executeTypeScriptFileSync } = require('../../parsers/typescript')
 const { executeESMFileSync } = require('../../parsers/esm')
 const cloudFormationSchema = require('./cloudformationSchema')
@@ -72,8 +74,12 @@ function detectFormat(contents) {
 function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
   let fileType = path.extname(filePath)
 
-  // Content-based detection for extensionless or unrecognized files
-  if (!fileType || !KNOWN_EXTENSIONS.has(fileType.toLowerCase())) {
+  // Dotenv files have no extension (path.extname('.env') === ''), so detect
+  // them by name before falling back to content sniffing.
+  if (isEnvFile(filePath)) {
+    fileType = '.env'
+  } else if (!fileType || !KNOWN_EXTENSIONS.has(fileType.toLowerCase())) {
+    // Content-based detection for extensionless or unrecognized files
     fileType = detectFormat(contents)
   }
 
@@ -105,6 +111,8 @@ function parseFileContents({ contents, filePath, varRegex, dynamicArgs }) {
     configObject = TOML.parse(contents)
   } else if (fileType.match(/\.(ini)/i)) {
     configObject = INI.parse(contents)
+  } else if (fileType === '.env') {
+    configObject = DOTENV.parse(contents)
   } else if (fileType.match(/\.(json|json5|jsonc)/i)) {
     configObject = JSON5.parse(contents)
   } else if (fileType.match(/\.(tf|hcl)$/i) || filePath.match(/\.tf\.json$/i)) {

package/src/utils/paths/fileType.js

@@ -0,0 +1,27 @@
+// Classifies config files by type, treating dotenv files as ".env"
+// so extension-less names like .env / .env.local / deploy.env resolve consistently
+const path = require('path')
+
+/**
+ * Whether a path is a dotenv file (.env, .env.local, deploy.env, ...).
+ * `path.extname('.env')` is '' (dotfile), so detection is by basename.
+ * @param {string} filePath - File path or name
+ * @returns {boolean} True for dotenv files
+ */
+function isEnvFile(filePath) {
+  const base = path.basename(String(filePath || ''))
+  return base === '.env' || base.startsWith('.env.') || base.endsWith('.env')
+}
+
+/**
+ * Normalized config file type: '.env' for dotenv files, else the lowercased
+ * extension.
+ * @param {string} filePath - File path or name
+ * @returns {string} File type (e.g. '.yml', '.env', '')
+ */
+function configFileType(filePath) {
+  if (isEnvFile(filePath)) return '.env'
+  return path.extname(String(filePath || '')).toLowerCase()
+}
+
+module.exports = { isEnvFile, configFileType }

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

@@ -0,0 +1,41 @@
+/* Tests for config file type classification (dotenv detection) */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { isEnvFile, configFileType } = require('./fileType')
+
+test('isEnvFile detects the env-stage-loader precedence names', () => {
+  // .env.{environment}.local, .env.{environment}, .env.local, .env
+  assert.ok(isEnvFile('.env'))
+  assert.ok(isEnvFile('.env.local'))
+  assert.ok(isEnvFile('.env.production'))
+  assert.ok(isEnvFile('.env.production.local'))
+  assert.ok(isEnvFile('/path/to/.env.staging.local'))
+  assert.ok(isEnvFile('deploy.env'))
+})
+
+test('isEnvFile rejects non-dotenv names', () => {
+  assert.is(isEnvFile('config.yml'), false)
+  assert.is(isEnvFile('env.js'), false)
+  assert.is(isEnvFile('environment.json'), false)
+  assert.is(isEnvFile('.environment'), false)
+  assert.is(isEnvFile(''), false)
+})
+
+test('configFileType returns .env for staged dotenv names', () => {
+  assert.is(configFileType('.env.production.local'), '.env')
+  assert.is(configFileType('.env.staging'), '.env')
+})
+
+test('configFileType returns .env for dotenv files', () => {
+  assert.is(configFileType('.env'), '.env')
+  assert.is(configFileType('/x/.env.local'), '.env')
+  assert.is(configFileType('deploy.env'), '.env')
+})
+
+test('configFileType returns lowercased extension otherwise', () => {
+  assert.is(configFileType('config.YML'), '.yml')
+  assert.is(configFileType('data.json'), '.json')
+  assert.is(configFileType('noext'), '')
+})
+
+test.run()

package/src/utils/paths/findLineForKey.js

@@ -31,6 +31,10 @@ function findLineForKey(keyToFind, lines, fileType) {
     if (fileType === '.ini') {
       return new RegExp(`^\\s*${escapedKey}\\s*=`).test(line)
     }
+    // dotenv: KEY= or export KEY=
+    if (fileType === '.env') {
+      return new RegExp(`^\\s*(?:export\\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)
@@ -55,13 +59,32 @@ function findLineByPath(configPath, lines, fileType) {
 
   const isYaml = fileType === '.yml' || fileType === '.yaml'
   const isJson = fileType === '.json' || fileType === '.json5' || fileType === '.jsonc'
-  if (!isYaml && !isJson) return 0
+  const isEnv = fileType === '.env'
+  if (!isYaml && !isJson && !isEnv) return 0
 
   const segments = configPath.split('.')
+  if (isEnv) return findLineByPathEnv(segments, lines)
   if (isYaml) return findLineByPathYaml(segments, lines)
   return findLineByPathJson(segments, lines)
 }
 
+/**
+ * Find a dotenv key's line. .env is flat, so the key is the first path segment.
+ * Handles leading whitespace and an optional `export ` prefix.
+ * @param {string[]} segments
+ * @param {string[]} lines
+ * @returns {number}
+ */
+function findLineByPathEnv(segments, lines) {
+  const key = segments[0]
+  const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(`^\\s*(?:export\\s+)?${escaped}\\s*=`)
+  for (let li = 0; li < lines.length; li++) {
+    if (pattern.test(lines[li])) return li + 1
+  }
+  return 0
+}
+
 /**
  * @param {string[]} segments
  * @param {string[]} lines

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

@@ -3,7 +3,7 @@
  */
 const { test } = require('uvu')
 const assert = require('uvu/assert')
-const { findLineForKey } = require('./findLineForKey')
+const { findLineForKey, findLineByPath } = require('./findLineForKey')
 
 // YAML tests
 test('YAML - finds key at start of line', () => {
@@ -123,4 +123,23 @@ test('unknown file type falls back to YAML-style', () => {
   assert.equal(findLineForKey('foo', lines, '.unknown'), 1)
 })
 
+// dotenv
+test('dotenv - finds KEY= line', () => {
+  const lines = ['API_URL=https://x', 'stage=${opt:stage}']
+  assert.equal(findLineForKey('stage', lines, '.env'), 2)
+  assert.equal(findLineForKey('API_URL', lines, '.env'), 1)
+})
+
+test('dotenv - finds export-prefixed and whitespace-padded keys', () => {
+  const lines = ['# comment', 'export TOKEN=abc', '  PADDED = x']
+  assert.equal(findLineForKey('TOKEN', lines, '.env'), 2)
+  assert.equal(findLineForKey('PADDED', lines, '.env'), 3)
+})
+
+test('findLineByPath - dotenv key lookup', () => {
+  const lines = ['A=1', 'stage=${opt:stage}', 'B=2']
+  assert.equal(findLineByPath('stage', lines, '.env'), 2)
+  assert.equal(findLineByPath('missing', lines, '.env'), 0)
+})
+
 test.run()

package/src/utils/security/dotenvFileRefs.js

@@ -0,0 +1,134 @@
+const path = require('path')
+const { normalizePath } = require('../paths/filePathUtils')
+const { splitCsv } = require('../strings/splitCsv')
+const { trimSurroundingQuotes } = require('../strings/quoteUtils')
+
+const DOTENV_SENSITIVITY_REASON = 'dotenv_file'
+
+function isDotenvFilePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return false
+  const cleanPath = filePath.trim().replace(/^["']|["']$/g, '')
+  const baseName = path.basename(cleanPath)
+  return baseName === '.env' || baseName.startsWith('.env.')
+}
+
+function hasFileAccessor(variableString) {
+  const expression = extractFileExpression(variableString)
+  if (!expression) return false
+  const suffix = String(variableString || '').slice(expression.end).trim()
+  return suffix.startsWith(':') || suffix.startsWith('.')
+}
+
+function extractFileExpression(variableString) {
+  const value = String(variableString || '')
+  const prefixMatch = /(?:^|[^\w.])((?:file|text)\()/.exec(value)
+  if (!prefixMatch) return null
+
+  const expressionStart = prefixMatch.index + prefixMatch[0].indexOf(prefixMatch[1])
+  const openParenIndex = expressionStart + prefixMatch[1].length - 1
+  let depth = 1
+  let index = openParenIndex + 1
+
+  while (index < value.length && depth > 0) {
+    if (value[index] === '(') depth++
+    else if (value[index] === ')') depth--
+    index++
+  }
+
+  if (depth !== 0) return null
+
+  const fileContent = value.substring(openParenIndex + 1, index - 1).trim()
+  if (!fileContent) return null
+
+  const parts = splitCsv(fileContent, undefined, { protectVariables: true })
+  const filePath = trimSurroundingQuotes(parts[0].trim(), false)
+
+  return {
+    filePath,
+    expression: value.slice(expressionStart, index),
+    start: expressionStart,
+    end: index,
+  }
+}
+
+function extractDotenvPath(source) {
+  const candidates = [
+    source.relativePath,
+    source.resolvedPath,
+    source.filePath,
+    source.fullFilePath,
+  ].filter(Boolean)
+
+  for (const candidate of candidates) {
+    if (isDotenvFilePath(candidate)) return candidate
+  }
+
+  const variableCandidates = [
+    source.variable,
+    source.variableString,
+    source.originalVariableString,
+    source.resolvedVariableString,
+  ].filter(Boolean)
+
+  for (const candidate of variableCandidates) {
+    const extracted = extractFileExpression(String(candidate))
+    if (extracted && isDotenvFilePath(extracted.filePath)) {
+      return extracted.filePath
+    }
+  }
+
+  return null
+}
+
+function getDotenvFileRefMetadata(source = {}) {
+  const dotenvPath = extractDotenvPath(source)
+  if (!dotenvPath) return null
+
+  const scopeSource = source.variableString ||
+    source.variable ||
+    source.originalVariableString ||
+    source.resolvedVariableString ||
+    ''
+  const accessorScope = hasFileAccessor(scopeSource) ? 'key' : null
+
+  return {
+    sensitive: true,
+    sensitivityReason: DOTENV_SENSITIVITY_REASON,
+    dotenvFile: true,
+    dotenvReadScope: accessorScope || source.dotenvReadScope || 'full_file',
+  }
+}
+
+function normalizeDotenvFileVariable(variableString) {
+  const value = String(variableString || '')
+  const expression = extractFileExpression(value)
+  if (!expression || !isDotenvFilePath(expression.filePath)) return null
+
+  const normalizedPath = normalizePath(expression.filePath) || expression.filePath
+  const normalizedExpression = expression.expression.replace(/\(([\s\S]*)\)$/, `(${normalizedPath})`)
+  const suffix = value.slice(expression.end).trim()
+  const accessor = suffix.match(/^([:.][\w.[\]-]+)/)
+
+  return accessor ? `${normalizedExpression}${accessor[1]}` : normalizedExpression
+}
+
+function isIniLikeFilePath(filePath) {
+  const ext = path.extname(String(filePath || '')).slice(1).toLowerCase()
+  return ext === 'ini' || isDotenvFilePath(filePath)
+}
+
+function applyDotenvFileRefMetadata(target, source) {
+  const metadata = getDotenvFileRefMetadata(source)
+  if (metadata) Object.assign(target, metadata)
+  return target
+}
+
+module.exports = {
+  DOTENV_SENSITIVITY_REASON,
+  applyDotenvFileRefMetadata,
+  getDotenvFileRefMetadata,
+  hasFileAccessor,
+  normalizeDotenvFileVariable,
+  isDotenvFilePath,
+  isIniLikeFilePath,
+}

package/src/utils/security/dotenvFileRefs.test.js

@@ -0,0 +1,47 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const {
+  getDotenvFileRefMetadata,
+  hasFileAccessor,
+  isDotenvFilePath,
+  normalizeDotenvFileVariable,
+} = require('./dotenvFileRefs')
+
+test('dotenv file detection matches .env and .env variants', () => {
+  assert.is(isDotenvFilePath('.env'), true)
+  assert.is(isDotenvFilePath('./.env.production'), true)
+  assert.is(isDotenvFilePath('/tmp/app/.env.local'), true)
+  assert.is(isDotenvFilePath('./env.yml'), false)
+})
+
+test('dotenv accessors are detected without assuming ${} syntax', () => {
+  assert.is(hasFileAccessor('file(.env).API_KEY'), true)
+  assert.is(hasFileAccessor('file(.env):TOKEN'), true)
+  assert.is(hasFileAccessor('${file(.env).API_KEY}'), true)
+  assert.is(hasFileAccessor('[[file(.env).API_KEY]]'), true)
+  assert.is(hasFileAccessor('file(.env)'), false)
+})
+
+test('dotenv metadata classifies full-file and key reads', () => {
+  assert.equal(getDotenvFileRefMetadata({ variable: 'file(.env)' }), {
+    sensitive: true,
+    sensitivityReason: 'dotenv_file',
+    dotenvFile: true,
+    dotenvReadScope: 'full_file',
+  })
+  assert.equal(getDotenvFileRefMetadata({ variable: '[[file(.env):TOKEN]]' }), {
+    sensitive: true,
+    sensitivityReason: 'dotenv_file',
+    dotenvFile: true,
+    dotenvReadScope: 'key',
+  })
+})
+
+test('dotenv variable normalization preserves key accessors', () => {
+  assert.is(normalizeDotenvFileVariable('file(.env)'), 'file(./.env)')
+  assert.is(normalizeDotenvFileVariable('file(.env).API_KEY'), 'file(./.env).API_KEY')
+  assert.is(normalizeDotenvFileVariable('file(.env):TOKEN'), 'file(./.env):TOKEN')
+  assert.is(normalizeDotenvFileVariable('file(config.yml):value'), null)
+})
+
+test.run()