configorama 0.11.0 → 1.0.0

package/src/utils/parsing/commentAnnotations.js

@@ -0,0 +1,107 @@
+const KNOWN_TAGS = new Set([
+  'description',
+  'from',
+  'example',
+  'default',
+  'sensitive',
+  'group',
+  'deprecated',
+])
+
+function toLines(input) {
+  if (Array.isArray(input)) return input
+  if (input === undefined || input === null) return []
+  return String(input).split(/\r?\n/)
+}
+
+function firstNonEmpty(values) {
+  return (values || []).find(value => value !== undefined && value !== null && String(value).trim() !== '')
+}
+
+function uniqueNonEmpty(values) {
+  const seen = new Set()
+  const result = []
+  for (const value of values || []) {
+    if (value === undefined || value === null) continue
+    const normalized = String(value).trim()
+    if (!normalized || seen.has(normalized)) continue
+    seen.add(normalized)
+    result.push(normalized)
+  }
+  return result
+}
+
+function parseSensitive(value) {
+  if (value === undefined || value === null) return undefined
+  const normalized = String(value).trim().toLowerCase()
+  if (normalized === 'true') return true
+  if (normalized === 'false') return false
+  return undefined
+}
+
+function normalizeAnnotations(tags, plainText) {
+  const descriptionFromTag = uniqueNonEmpty(tags.description).join(' ')
+  const obtainHint = firstNonEmpty(tags.from)
+  const examples = uniqueNonEmpty(tags.example)
+  const defaultHint = firstNonEmpty(tags.default)
+  const sensitive = parseSensitive(firstNonEmpty(tags.sensitive))
+  const group = firstNonEmpty(tags.group)
+  const deprecationMessage = firstNonEmpty(tags.deprecated)
+
+  const annotations = {}
+  if (descriptionFromTag) annotations.description = descriptionFromTag
+  if (obtainHint) annotations.obtainHint = String(obtainHint).trim()
+  if (examples.length) annotations.examples = examples
+  if (defaultHint) annotations.defaultHint = String(defaultHint).trim()
+  if (sensitive !== undefined) annotations.sensitive = sensitive
+  if (group) annotations.group = String(group).trim()
+  if (deprecationMessage) annotations.deprecationMessage = String(deprecationMessage).trim()
+
+  return {
+    annotations,
+    description: annotations.description || plainText || null,
+    descriptionSource: annotations.description ? 'commentTag' : null,
+  }
+}
+
+function parseCommentAnnotations(input) {
+  const tags = {}
+  const plainLines = []
+
+  for (const line of toLines(input)) {
+    const text = String(line || '').trim()
+    if (!text) continue
+
+    const match = text.match(/^@([a-z][a-z0-9_-]*)\b([\s\S]*)$/)
+    if (!match) {
+      plainLines.push(text)
+      continue
+    }
+
+    const tagName = match[1]
+    if (!KNOWN_TAGS.has(tagName)) {
+      plainLines.push(text)
+      continue
+    }
+
+    if (!tags[tagName]) tags[tagName] = []
+    tags[tagName].push(match[2].replace(/^\s/, ''))
+  }
+
+  const plainText = plainLines.join(' ').trim() || null
+  const normalized = normalizeAnnotations(tags, plainText)
+
+  return {
+    plainText,
+    tags,
+    annotations: normalized.annotations,
+    description: normalized.description,
+    descriptionSource: normalized.descriptionSource,
+  }
+}
+
+module.exports = {
+  KNOWN_TAGS,
+  parseCommentAnnotations,
+  parseSensitive,
+}

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

@@ -0,0 +1,123 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const fs = require('fs')
+const path = require('path')
+const { parseCommentAnnotations, parseSensitive } = require('./commentAnnotations')
+
+test('parseCommentAnnotations parses supported tags into normalized annotation fields', () => {
+  const result = parseCommentAnnotations([
+    '@description Stripe live secret key',
+    '@from Stripe dashboard > Developers > API keys',
+    '@example sk_live_...',
+    '@default Set this in CI',
+    '@sensitive true',
+    '@group Payments',
+    '@deprecated Use STRIPE_RESTRICTED_KEY instead',
+  ])
+
+  assert.equal(result.tags, {
+    description: ['Stripe live secret key'],
+    from: ['Stripe dashboard > Developers > API keys'],
+    example: ['sk_live_...'],
+    default: ['Set this in CI'],
+    sensitive: ['true'],
+    group: ['Payments'],
+    deprecated: ['Use STRIPE_RESTRICTED_KEY instead'],
+  })
+  assert.equal(result.annotations, {
+    description: 'Stripe live secret key',
+    obtainHint: 'Stripe dashboard > Developers > API keys',
+    examples: ['sk_live_...'],
+    defaultHint: 'Set this in CI',
+    sensitive: true,
+    group: 'Payments',
+    deprecationMessage: 'Use STRIPE_RESTRICTED_KEY instead',
+  })
+  assert.is(result.description, 'Stripe live secret key')
+  assert.is(result.descriptionSource, 'commentTag')
+})
+
+test('parseCommentAnnotations keeps plain text separate from tag lines', () => {
+  const result = parseCommentAnnotations([
+    'Stripe live secret key',
+    '@from Stripe dashboard > Developers > API keys',
+  ])
+
+  assert.is(result.plainText, 'Stripe live secret key')
+  assert.is(result.description, 'Stripe live secret key')
+  assert.is(result.descriptionSource, null)
+  assert.equal(result.annotations, {
+    obtainHint: 'Stripe dashboard > Developers > API keys',
+  })
+})
+
+test('parseCommentAnnotations treats unknown tag-shaped lines as plain description text', () => {
+  const result = parseCommentAnnotations([
+    '@david rotate this key after launch',
+    'ping @ops before rotating this key',
+  ])
+
+  assert.is(result.plainText, '@david rotate this key after launch ping @ops before rotating this key')
+  assert.is(result.description, '@david rotate this key after launch ping @ops before rotating this key')
+  assert.equal(result.tags, {})
+  assert.equal(result.annotations, {})
+})
+
+test('parseCommentAnnotations preserves empty tag values in raw tags and omits normalized empty fields', () => {
+  const result = parseCommentAnnotations([
+    '@from',
+    '@default ',
+    '@group Platform',
+  ])
+
+  assert.equal(result.tags, {
+    from: [''],
+    default: [''],
+    group: ['Platform'],
+  })
+  assert.equal(result.annotations, {
+    group: 'Platform',
+  })
+})
+
+test('parseCommentAnnotations joins repeated descriptions and dedupes examples', () => {
+  const result = parseCommentAnnotations([
+    '@description Stripe live',
+    '@description secret key',
+    '@example sk_live_...',
+    '@example sk_live_...',
+    '@example stripe-key',
+  ])
+
+  assert.is(result.annotations.description, 'Stripe live secret key')
+  assert.equal(result.annotations.examples, ['sk_live_...', 'stripe-key'])
+})
+
+test('parseSensitive accepts only true and false case-insensitively', () => {
+  assert.is(parseSensitive('true'), true)
+  assert.is(parseSensitive('TRUE'), true)
+  assert.is(parseSensitive('false'), false)
+  assert.is(parseSensitive('False'), false)
+  assert.is(parseSensitive('yes'), undefined)
+  assert.is(parseSensitive('1'), undefined)
+  assert.is(parseSensitive(''), undefined)
+})
+
+test('parseCommentAnnotations ignores invalid sensitive values so heuristics can apply later', () => {
+  const result = parseCommentAnnotations([
+    '@sensitive yes',
+    '@description API token',
+  ])
+
+  assert.equal(result.tags.sensitive, ['yes'])
+  assert.equal(result.annotations, {
+    description: 'API token',
+  })
+})
+
+test('comment annotation parser does not require jsdoc-parser', () => {
+  const source = fs.readFileSync(path.join(__dirname, 'commentAnnotations.js'), 'utf8')
+  assert.not.match(source, /jsdoc-parser|doxxx|jsdoctypeparser/)
+})
+
+test.run()

package/src/utils/parsing/enrichMetadata.js

@@ -3,6 +3,8 @@ const fs = require('fs')
 const path = require('path')
 const { normalizePath, extractFilePath, normalizeFileVariable, resolveInnerVariables } = require('../paths/filePathUtils')
 const { preResolveString, preResolveSingle } = require('../resolution/preResolveVariable')
+const { parseOneOfFilter } = require('../filters/oneOf')
+const { extractComment } = require('./extractComment')
 
 // Type filters that indicate expected value types
 const TYPE_FILTERS = ['Boolean', 'String', 'Number', 'Array', 'Object', 'Json']
@@ -61,6 +63,8 @@ function createOccurrence(instance, varMatch, options = {}) {
 
   // Extract type from filters
   const type = extractTypeFromFilters(filters)
+  const oneOfFilter = filters && filters.find(filter => typeof filter === 'string' && filter.match(/^oneOf\(/))
+  const oneOf = parseOneOfFilter(oneOfFilter)
 
   const occurrence = {
     originalString: instance.originalStringValue,
@@ -79,6 +83,11 @@ function createOccurrence(instance, varMatch, options = {}) {
 
   if (description) {
     occurrence.description = description
+    occurrence.descriptionSource = 'help'
+  }
+
+  if (oneOf && oneOf.allowedValues) {
+    occurrence.allowedValues = oneOf.allowedValues
   }
 
   if (instance.defaultValueSrc) {
@@ -133,6 +142,56 @@ async function enrichMetadata(
   // Create resolve context early for resolving descriptions
   const configDir = configPath ? path.dirname(configPath) : undefined
   const resolveContext = { config: originalConfig, variableSyntax, configDir, options }
+  const commentFileType = configPath ? path.extname(configPath) : ''
+  let commentLines = []
+  if (configPath) {
+    try {
+      commentLines = fs.readFileSync(configPath, 'utf8').split('\n')
+    } catch (error) {
+      commentLines = []
+    }
+  }
+
+  function applyCommentFallback(occurrence) {
+    if (!occurrence) return occurrence
+    const comment = extractComment(occurrence.path, commentLines, commentFileType)
+    if (comment) {
+      if (comment.description && (!occurrence.description || comment.descriptionSource === 'commentTag')) {
+        occurrence.description = comment.description
+        occurrence.descriptionSource = comment.descriptionSource
+      }
+      if (comment.obtainHint) occurrence.obtainHint = comment.obtainHint
+      if (comment.examples) occurrence.examples = comment.examples
+      if (comment.defaultHint) occurrence.defaultHint = comment.defaultHint
+      if (comment.sensitive !== undefined) {
+        occurrence.sensitive = comment.sensitive
+        occurrence.sensitiveSource = 'commentTag'
+      }
+      if (comment.group) occurrence.group = comment.group
+      if (comment.deprecationMessage) occurrence.deprecationMessage = comment.deprecationMessage
+    }
+    return occurrence
+  }
+
+  async function applyDynamicOneOfAllowedValues(occurrence) {
+    if (!occurrence || occurrence.allowedValues || !occurrence.filters) return occurrence
+    const oneOfFilter = occurrence.filters.find(filter => typeof filter === 'string' && filter.match(/^oneOf\(/))
+    if (!oneOfFilter) return occurrence
+
+    const match = oneOfFilter.match(/^oneOf\(\s*\$\{([^}]+)\}\s*\)$/)
+    if (!match) return occurrence
+
+    try {
+      const resolved = await preResolveSingle(match[1], resolveContext)
+      if (Array.isArray(resolved)) {
+        occurrence.allowedValues = resolved.map(String)
+      }
+    } catch (error) {
+      // Leave unresolved dynamic oneOf args without allowedValues; runtime will report errors.
+    }
+
+    return occurrence
+  }
 
   const varKeys = Object.keys(metadata.variables)
 
@@ -439,6 +498,8 @@ async function enrichMetadata(
     for (const instance of varInstances) {
       // Add this occurrence with its full context
       const occurrence = createOccurrence(instance, key)
+      applyCommentFallback(occurrence)
+      await applyDynamicOneOfAllowedValues(occurrence)
       entry.occurrences.push(occurrence)
 
       // Find inner variables in resolveDetails (excluding the outermost variable itself)
@@ -511,6 +572,8 @@ async function enrichMetadata(
               hasFallback: !!detail.hasFallback,
               defaultValue: siblingDefaultValue,
             })
+            applyCommentFallback(siblingOccurrence)
+            await applyDynamicOneOfAllowedValues(siblingOccurrence)
             if (siblingDefaultValueSrc) {
               siblingOccurrence.defaultValueSrc = siblingDefaultValueSrc
             }
@@ -763,4 +826,4 @@ async function enrichMetadata(
   return metadata
 }
 
-module.exports = enrichMetadata
+module.exports = enrichMetadata

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

@@ -0,0 +1,84 @@
+/* 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')
+
+function writeTempConfig(lines) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'configorama-annotations-'))
+  const configPath = path.join(dir, 'config.yml')
+  fs.writeFileSync(configPath, lines.join('\n'))
+  return { dir, configPath }
+}
+
+test('enriched metadata maps comment annotations onto occurrences', async () => {
+  const { dir, configPath } = writeTempConfig([
+    '# Stripe live secret key',
+    '# @from Stripe dashboard > Developers > API keys',
+    '# @example sk_live_...',
+    '# @default Set in CI',
+    '# @sensitive false',
+    '# @group Payments',
+    '# @deprecated Use STRIPE_RESTRICTED_KEY instead',
+    'stripeSecret: ${env:STRIPE_SECRET_KEY}',
+  ])
+
+  try {
+    const analysis = await configorama.analyze(configPath, { options: {} })
+    const occurrence = analysis.uniqueVariables['env:STRIPE_SECRET_KEY'].occurrences[0]
+
+    assert.is(occurrence.description, 'Stripe live secret key')
+    assert.is(occurrence.descriptionSource, 'leadingComment')
+    assert.is(occurrence.obtainHint, 'Stripe dashboard > Developers > API keys')
+    assert.equal(occurrence.examples, ['sk_live_...'])
+    assert.is(occurrence.defaultHint, 'Set in CI')
+    assert.is(occurrence.defaultValue, undefined)
+    assert.is(occurrence.sensitive, false)
+    assert.is(occurrence.sensitiveSource, 'commentTag')
+    assert.is(occurrence.group, 'Payments')
+    assert.is(occurrence.deprecationMessage, 'Use STRIPE_RESTRICTED_KEY instead')
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('enriched metadata lets @description override help on the same occurrence', async () => {
+  const { dir, configPath } = writeTempConfig([
+    '# Plain comment loses',
+    '# @description Comment tag wins',
+    'apiKey: ${env:CONFIGORAMA_ANNOTATED_API_KEY | help("Help loses")}',
+  ])
+
+  try {
+    const analysis = await configorama.analyze(configPath, { options: {} })
+    const occurrence = analysis.uniqueVariables['env:CONFIGORAMA_ANNOTATED_API_KEY'].occurrences[0]
+
+    assert.is(occurrence.description, 'Comment tag wins')
+    assert.is(occurrence.descriptionSource, 'commentTag')
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('enriched metadata keeps normal comment below help while preserving independent tags', async () => {
+  const { dir, configPath } = writeTempConfig([
+    '# Plain comment loses to help',
+    '# @from Dashboard > Tokens',
+    'apiToken: ${env:CONFIGORAMA_ANNOTATED_TOKEN | help("Help wins")}',
+  ])
+
+  try {
+    const analysis = await configorama.analyze(configPath, { options: {} })
+    const occurrence = analysis.uniqueVariables['env:CONFIGORAMA_ANNOTATED_TOKEN'].occurrences[0]
+
+    assert.is(occurrence.description, 'Help wins')
+    assert.is(occurrence.descriptionSource, 'help')
+    assert.is(occurrence.obtainHint, 'Dashboard > Tokens')
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test.run()

package/src/utils/parsing/extractComment.js

@@ -0,0 +1,145 @@
+const { findLineByPath, findLineForKey } = require('../paths/findLineForKey')
+const { parseCommentAnnotations } = require('./commentAnnotations')
+
+function getCommentMarkers(fileType) {
+  if (fileType === '.json') return []
+  if (fileType === '.json5' || fileType === '.jsonc') return ['//']
+  if (fileType === '.hcl') return ['//', '#']
+  if (['.yml', '.yaml', '.toml', '.ini'].includes(fileType)) return ['#']
+  return ['#', '//']
+}
+
+function isDecorationComment(text) {
+  return /^[\s\-=_*]{3,}$/.test(text)
+}
+
+function stripCommentMarker(line, marker) {
+  return line.trim().slice(marker.length).replace(/^\s?/, '')
+}
+
+function findCommentStart(line, markers) {
+  let quote = null
+  let variableDepth = 0
+
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i]
+    const prev = i > 0 ? line[i - 1] : ''
+
+    if (!quote && char === '$' && line[i + 1] === '{') {
+      variableDepth++
+      i++
+      continue
+    }
+    if (!quote && variableDepth > 0 && char === '}') {
+      variableDepth--
+      continue
+    }
+    if ((char === "'" || char === '"') && prev !== '\\') {
+      if (!quote) quote = char
+      else if (quote === char) quote = null
+      continue
+    }
+    if (quote || variableDepth > 0) continue
+
+    for (const marker of markers) {
+      if (line.slice(i, i + marker.length) === marker) {
+        return { index: i, marker }
+      }
+    }
+  }
+
+  return null
+}
+
+function getLineNumber(configPath, lines, fileType) {
+  if (['.yml', '.yaml', '.json5', '.jsonc'].includes(fileType)) {
+    const byPath = findLineByPath(configPath, lines, fileType)
+    if (byPath) return byPath
+  }
+
+  if (fileType === '.json') return 0
+  const key = String(configPath).split('.').pop()
+  return findLineForKey(key, lines, fileType)
+}
+
+function getLeadingComment(lines, lineIndex, markers) {
+  const comments = getLeadingCommentLines(lines, lineIndex, markers)
+  return comments.length ? comments.join(' ') : null
+}
+
+function getLeadingCommentLines(lines, lineIndex, markers) {
+  const comments = []
+  for (let i = lineIndex - 1; i >= 0; i--) {
+    const line = lines[i]
+    if (!line || line.trim() === '') break
+
+    const trimmed = line.trim()
+    const marker = markers.find(item => trimmed.startsWith(item))
+    if (!marker) break
+
+    const text = stripCommentMarker(trimmed, marker).trim()
+    if (text && !isDecorationComment(text)) comments.unshift(text)
+  }
+
+  return comments
+}
+
+function hasAnnotations(annotations) {
+  return annotations && Object.keys(annotations).length > 0
+}
+
+function buildCommentResult(commentLines, fallbackDescriptionSource) {
+  const parsed = parseCommentAnnotations(commentLines)
+  if (!parsed.description && !hasAnnotations(parsed.annotations)) return null
+
+  const result = {}
+  if (parsed.description) {
+    result.description = parsed.description
+    result.descriptionSource = parsed.descriptionSource || fallbackDescriptionSource
+  }
+
+  if (hasAnnotations(parsed.annotations)) {
+    result.annotations = parsed.annotations
+    for (const [key, value] of Object.entries(parsed.annotations)) {
+      if (key === 'description') continue
+      result[key] = value
+    }
+  }
+
+  return result
+}
+
+function extractComment(configPath, lines, fileType) {
+  try {
+    const markers = getCommentMarkers(fileType)
+    if (!markers.length || !configPath || !Array.isArray(lines) || !lines.length) return null
+
+    const lineNumber = getLineNumber(configPath, lines, fileType)
+    if (!lineNumber) return null
+
+    const lineIndex = lineNumber - 1
+    const line = lines[lineIndex] || ''
+    const inlineStart = findCommentStart(line, markers)
+    if (inlineStart) {
+      const text = stripCommentMarker(line.slice(inlineStart.index), inlineStart.marker).trim()
+      if (text && !isDecorationComment(text)) {
+        return buildCommentResult([text], 'comment')
+      }
+    }
+
+    const leading = getLeadingCommentLines(lines, lineIndex, markers)
+    const result = buildCommentResult(leading, 'leadingComment')
+    if (result) return result
+  } catch (error) {
+    return null
+  }
+
+  return null
+}
+
+module.exports = {
+  extractComment,
+  findCommentStart,
+  getCommentMarkers,
+  getLeadingComment,
+}