configorama 0.11.0 → 1.0.0

package/src/utils/parsing/extractComment.test.js

@@ -0,0 +1,182 @@
+/* eslint-disable no-template-curly-in-string */
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const configorama = require('../../index')
+const { extractComment, findCommentStart, getCommentMarkers } = require('./extractComment')
+
+test('extractComment reads trailing inline YAML comments', () => {
+  const lines = ['apiKey: ${env:API_KEY} # API key from dashboard']
+  assert.equal(extractComment('apiKey', lines, '.yml'), {
+    description: 'API key from dashboard',
+    descriptionSource: 'comment',
+  })
+})
+
+test('extractComment reads leading block comments and drops decoration', () => {
+  const lines = [
+    '# --------',
+    '# Database host',
+    '# Used by app startup',
+    'host: ${env:DB_HOST}',
+  ]
+  assert.equal(extractComment('host', lines, '.yaml'), {
+    description: 'Database host Used by app startup',
+    descriptionSource: 'leadingComment',
+  })
+})
+
+test('extractComment ignores comment markers inside variables and quotes', () => {
+  const lines = ['apiKey: ${env:API_KEY, "abc#123"} # Real comment']
+  const start = findCommentStart(lines[0], getCommentMarkers('.yml'))
+  assert.is(lines[0].slice(start.index), '# Real comment')
+})
+
+test('extractComment uses path-aware lookup for nested duplicate YAML keys', () => {
+  const lines = [
+    'first:',
+    '  apiKey: ${env:FIRST_KEY} # First key',
+    'second:',
+    '  apiKey: ${env:SECOND_KEY} # Second key',
+  ]
+  assert.equal(extractComment('second.apiKey', lines, '.yml'), {
+    description: 'Second key',
+    descriptionSource: 'comment',
+  })
+})
+
+test('extractComment skips JSON comments and handles failures without throwing', () => {
+  assert.is(extractComment('apiKey', ['"apiKey": "${env:API_KEY}" // ignored'], '.json'), null)
+  assert.is(extractComment(null, null, '.yml'), null)
+})
+
+test('extractComment handles JSON5 line comments', () => {
+  const lines = [
+    '{',
+    '  "apiKey": "${env:API_KEY}" // API key',
+    '}',
+  ]
+  assert.equal(extractComment('apiKey', lines, '.json5'), {
+    description: 'API key',
+    descriptionSource: 'comment',
+  })
+})
+
+test('extractComment parses leading YAML annotation tags', () => {
+  const lines = [
+    '# Stripe live secret key',
+    '# @from Stripe dashboard > Developers > API keys',
+    '# @sensitive true',
+    'stripeSecret: ${env:STRIPE_SECRET_KEY}',
+  ]
+  assert.equal(extractComment('stripeSecret', lines, '.yml'), {
+    description: 'Stripe live secret key',
+    descriptionSource: 'leadingComment',
+    annotations: {
+      obtainHint: 'Stripe dashboard > Developers > API keys',
+      sensitive: true,
+    },
+    obtainHint: 'Stripe dashboard > Developers > API keys',
+    sensitive: true,
+  })
+})
+
+test('extractComment lets explicit @description override plain comment text', () => {
+  const lines = [
+    '# Plain comment loses to explicit description',
+    '# @description Stripe live secret key',
+    'stripeSecret: ${env:STRIPE_SECRET_KEY}',
+  ]
+  assert.equal(extractComment('stripeSecret', lines, '.yaml'), {
+    description: 'Stripe live secret key',
+    descriptionSource: 'commentTag',
+    annotations: {
+      description: 'Stripe live secret key',
+    },
+  })
+})
+
+test('extractComment parses inline tags without requiring a description', () => {
+  const lines = [
+    'stripeSecret: ${env:STRIPE_SECRET_KEY} # @from Stripe dashboard > Developers > API keys',
+  ]
+  assert.equal(extractComment('stripeSecret', lines, '.yaml'), {
+    annotations: {
+      obtainHint: 'Stripe dashboard > Developers > API keys',
+    },
+    obtainHint: 'Stripe dashboard > Developers > API keys',
+  })
+})
+
+test('extractComment parses JSONC and HCL annotation comments', () => {
+  const jsoncLines = [
+    '{',
+    '  // @group Payments',
+    '  "stripeSecret": "${env:STRIPE_SECRET_KEY}"',
+    '}',
+  ]
+  assert.equal(extractComment('stripeSecret', jsoncLines, '.jsonc'), {
+    annotations: {
+      group: 'Payments',
+    },
+    group: 'Payments',
+  })
+
+  const hclLines = [
+    '// Stripe live secret key',
+    '// @from Stripe dashboard > Developers > API keys',
+    'stripe_secret = "${env:STRIPE_SECRET_KEY}"',
+  ]
+  assert.equal(extractComment('stripe_secret', hclLines, '.hcl'), {
+    description: 'Stripe live secret key',
+    descriptionSource: 'leadingComment',
+    annotations: {
+      obtainHint: 'Stripe dashboard > Developers > API keys',
+    },
+    obtainHint: 'Stripe dashboard > Developers > API keys',
+  })
+})
+
+test('extractComment keeps unknown tag-shaped comments as plain description', () => {
+  const lines = [
+    '# @david rotate this key after launch',
+    'stripeSecret: ${env:STRIPE_SECRET_KEY}',
+  ]
+  assert.equal(extractComment('stripeSecret', lines, '.yaml'), {
+    description: '@david rotate this key after launch',
+    descriptionSource: 'leadingComment',
+  })
+})
+
+test('requirements model uses comments when help is absent and keeps help precedence', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'configorama-comments-'))
+  const configPath = path.join(dir, 'config.yml')
+  fs.writeFileSync(configPath, [
+    '# API key from dashboard',
+    'apiKey: ${env:CONFIGORAMA_COMMENT_API_KEY}',
+    'withHelp: ${env:CONFIGORAMA_COMMENT_HELP | help("Help wins")} # Comment loses',
+    'nested:',
+    '  apiKey: ${env:CONFIGORAMA_COMMENT_NESTED} # Nested key',
+  ].join('\n'))
+
+  try {
+    const result = await configorama.analyze(configPath, {
+      instructions: true,
+      options: {}
+    })
+    const byVariable = Object.fromEntries(result.requirements.map(req => [req.variable, req]))
+
+    assert.is(byVariable['env:CONFIGORAMA_COMMENT_API_KEY'].description, 'API key from dashboard')
+    assert.is(byVariable['env:CONFIGORAMA_COMMENT_API_KEY'].descriptionSource, 'leadingComment')
+    assert.is(byVariable['env:CONFIGORAMA_COMMENT_HELP'].description, 'Help wins')
+    assert.is(byVariable['env:CONFIGORAMA_COMMENT_HELP'].descriptionSource, 'help')
+    assert.is(byVariable['env:CONFIGORAMA_COMMENT_NESTED'].description, 'Nested key')
+    assert.is(byVariable['env:CONFIGORAMA_COMMENT_NESTED'].descriptionSource, 'comment')
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test.run()

package/src/utils/parsing/preProcess.js

@@ -26,7 +26,8 @@ function preProcess(configObject, variableSyntax, variableTypes, options = {}) {
   // Extract reference prefixes from variable types, or use defaults
   const refPrefixes = variableTypes && variableTypes.length > 0
     ? variableTypes
-        .map(v => (v.prefix || v.type) + ':')
+        .flatMap(v => v.prefixes || [v.prefix || v.type])
+        .map(prefix => prefix + ':')
         .filter(p => p !== 'dot.prop:' && p !== 'string:' && p !== 'number:')
     : ['self:', 'opt:', 'env:', 'file:', 'text:', 'deep:']
 

package/src/utils/paths/findLineForKey.js

@@ -19,8 +19,8 @@ function findLineForKey(keyToFind, lines, fileType) {
     if (fileType === '.yml' || fileType === '.yaml') {
       return new RegExp(`^\\s*${escapedKey}\\s*:`).test(line)
     }
-    // TOML: key = or key=
-    if (fileType === '.toml') {
+    // TOML/HCL: key = or key=
+    if (fileType === '.toml' || fileType === '.hcl') {
       return new RegExp(`^\\s*${escapedKey}\\s*=`).test(line)
     }
     // JSON: "key": or "key" :

package/src/utils/paths/ignorePaths.js

@@ -1,5 +1,6 @@
 const DEFAULT_IGNORE_PATHS = [
   '**.Fn::Sub',
+  '**.Fn::Sub.0',
   '**.Properties.Code.ZipFile',
   '**.Properties.FunctionCode',
   '**.Properties.UserData',
@@ -29,17 +30,29 @@ function patternToSegments(pattern) {
 }
 
 function matchSegments(patternSegments, pathSegments) {
-  if (!patternSegments.length) return pathSegments.length === 0
+  return matchFrom(patternSegments, 0, pathSegments, 0)
+}
 
-  const [head, ...tail] = patternSegments
-  if (head === '**') {
-    if (matchSegments(tail, pathSegments)) return true
-    return pathSegments.length > 0 && matchSegments(patternSegments, pathSegments.slice(1))
+// Index-based glob match: '**' spans zero-or-more segments (with backtracking),
+// '*' matches one segment, anything else matches literally. Avoids per-call array
+// allocation (no destructuring/slice) that dominated resolution hot paths.
+function matchFrom(pattern, pi, path, si) {
+  while (pi < pattern.length) {
+    const head = pattern[pi]
+    if (head === '**') {
+      // '**' consumes zero segments here...
+      if (matchFrom(pattern, pi + 1, path, si)) return true
+      // ...or one more path segment, still anchored on '**'
+      if (si >= path.length) return false
+      si++
+      continue
+    }
+    if (si >= path.length) return false
+    if (head !== '*' && head !== path[si]) return false
+    pi++
+    si++
   }
-
-  if (!pathSegments.length) return false
-  if (head !== '*' && head !== pathSegments[0]) return false
-  return matchSegments(tail, pathSegments.slice(1))
+  return si === path.length
 }
 
 function normalizeIgnorePaths(options = {}) {

package/src/utils/redaction/redact.js

@@ -0,0 +1,78 @@
+const dotProp = require('dot-prop')
+
+const REDACTED_VALUE = '********'
+
+const DEFAULT_SENSITIVE_PATTERNS = [
+  /secret/i,
+  /password/i,
+  /token/i,
+  /key/i,
+  /credential/i,
+  /auth/i,
+  /private[-_]?key/i,
+  /client[-_]?secret/i,
+]
+
+function cloneJson(value) {
+  if (value === undefined) return undefined
+  return JSON.parse(JSON.stringify(value))
+}
+
+function toRegex(pattern) {
+  if (pattern instanceof RegExp) return pattern
+  return new RegExp(String(pattern), 'i')
+}
+
+function getSensitivePatterns(options = {}) {
+  const customPatterns = (options.patterns || options.sensitivePatterns || []).map(toRegex)
+  return DEFAULT_SENSITIVE_PATTERNS.concat(customPatterns)
+}
+
+function isSensitiveName(name, options = {}) {
+  if (!name) return false
+  const value = String(name)
+  return getSensitivePatterns(options).some(pattern => pattern.test(value))
+}
+
+function getSensitiveOverride(entries = []) {
+  const entry = entries.find(item => item && typeof item.value === 'boolean')
+  if (!entry) return null
+  return entry.value
+}
+
+function isSensitiveVariable(name, options = {}) {
+  const override = getSensitiveOverride(options.sensitiveEntries || [])
+  if (override !== null) return override
+  return isSensitiveName(name, options) || isSensitiveName(options.path, options)
+}
+
+function redactValue(value) {
+  if (value === undefined) return undefined
+  return REDACTED_VALUE
+}
+
+function redactObjectByPaths(value, paths = []) {
+  const redacted = cloneJson(value)
+  for (const configPath of paths || []) {
+    if (configPath && dotProp.has(redacted, configPath)) {
+      dotProp.set(redacted, configPath, REDACTED_VALUE)
+    }
+  }
+  return redacted
+}
+
+function redactRequirementValue(requirement, value) {
+  return requirement && requirement.sensitive === true ? REDACTED_VALUE : value
+}
+
+module.exports = {
+  DEFAULT_SENSITIVE_PATTERNS,
+  REDACTED_VALUE,
+  cloneJson,
+  getSensitivePatterns,
+  isSensitiveName,
+  isSensitiveVariable,
+  redactObjectByPaths,
+  redactRequirementValue,
+  redactValue,
+}

package/src/utils/redaction/redact.test.js

@@ -0,0 +1,38 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const {
+  isSensitiveVariable,
+  redactObjectByPaths,
+  REDACTED_VALUE,
+} = require('./redact')
+
+test('isSensitiveVariable detects common secret names', () => {
+  assert.is(isSensitiveVariable('API_KEY'), true)
+  assert.is(isSensitiveVariable('clientSecret'), true)
+  assert.is(isSensitiveVariable('private_key'), true)
+  assert.is(isSensitiveVariable('region'), false)
+})
+
+test('isSensitiveVariable honors annotation overrides', () => {
+  assert.is(isSensitiveVariable('API_KEY', {
+    sensitiveEntries: [{ value: false, path: 'apiKey' }]
+  }), false)
+
+  assert.is(isSensitiveVariable('region', {
+    sensitiveEntries: [{ value: true, path: 'region' }]
+  }), true)
+})
+
+test('redactObjectByPaths redacts nested config paths', () => {
+  const redacted = redactObjectByPaths({
+    service: 'demo',
+    secrets: {
+      apiKey: 'secret-value'
+    }
+  }, ['secrets.apiKey'])
+
+  assert.is(redacted.service, 'demo')
+  assert.is(redacted.secrets.apiKey, REDACTED_VALUE)
+})
+
+test.run()

package/src/utils/redaction/setupRedaction.js

@@ -0,0 +1,47 @@
+const dotProp = require('dot-prop')
+const { REDACTED_VALUE, cloneJson } = require('./redact')
+
+function inputSectionForRequirement(requirement) {
+  if (!requirement) return null
+  if (requirement.variableType === 'option') return 'options'
+  if (requirement.variableType === 'env') return 'env'
+  if (requirement.variableType === 'self') return 'self'
+  if (requirement.variableType === 'dotProp') return 'dotProp'
+  return null
+}
+
+function redactUserInputsByRequirements(userInputs, requirements) {
+  const redacted = cloneJson(userInputs || {})
+
+  for (const requirement of requirements || []) {
+    if (!requirement || requirement.sensitive !== true) continue
+    const section = inputSectionForRequirement(requirement)
+    if (!section || !redacted[section]) continue
+    if (Object.prototype.hasOwnProperty.call(redacted[section], requirement.name)) {
+      redacted[section][requirement.name] = REDACTED_VALUE
+    }
+  }
+
+  return redacted
+}
+
+function redactConfigByRequirements(config, requirements) {
+  const redacted = cloneJson(config)
+
+  for (const requirement of requirements || []) {
+    if (!requirement || requirement.sensitive !== true) continue
+    for (const configPath of requirement.paths || []) {
+      if (configPath && dotProp.has(redacted, configPath)) {
+        dotProp.set(redacted, configPath, REDACTED_VALUE)
+      }
+    }
+  }
+
+  return redacted
+}
+
+module.exports = {
+  REDACTED_VALUE,
+  redactConfigByRequirements,
+  redactUserInputsByRequirements,
+}

package/src/utils/redaction/setupRedaction.test.js

@@ -0,0 +1,68 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const {
+  REDACTED_VALUE,
+  redactConfigByRequirements,
+  redactUserInputsByRequirements,
+} = require('./setupRedaction')
+
+const requirements = [
+  {
+    name: 'API_KEY',
+    variableType: 'env',
+    sensitive: true,
+    paths: ['secrets.apiKey'],
+  },
+  {
+    name: 'PUBLIC_KEY',
+    variableType: 'env',
+    sensitive: false,
+    paths: ['secrets.publicKey'],
+  },
+  {
+    name: 'stage',
+    variableType: 'option',
+    sensitive: false,
+    paths: ['stage'],
+  },
+]
+
+test('redactUserInputsByRequirements redacts only sensitive setup values', () => {
+  const inputs = {
+    options: { stage: 'prod' },
+    env: {
+      API_KEY: 'secret-value',
+      PUBLIC_KEY: 'public-value',
+    }
+  }
+
+  assert.equal(redactUserInputsByRequirements(inputs, requirements), {
+    options: { stage: 'prod' },
+    env: {
+      API_KEY: REDACTED_VALUE,
+      PUBLIC_KEY: 'public-value',
+    }
+  })
+  assert.is(inputs.env.API_KEY, 'secret-value')
+})
+
+test('redactConfigByRequirements redacts only sensitive resolved config paths', () => {
+  const config = {
+    stage: 'prod',
+    secrets: {
+      apiKey: 'secret-value',
+      publicKey: 'public-value',
+    }
+  }
+
+  assert.equal(redactConfigByRequirements(config, requirements), {
+    stage: 'prod',
+    secrets: {
+      apiKey: REDACTED_VALUE,
+      publicKey: 'public-value',
+    }
+  })
+  assert.is(config.secrets.apiKey, 'secret-value')
+})
+
+test.run()