configorama 0.11.0 → 1.0.0

package/src/display.js

@@ -5,13 +5,64 @@ const chalk = require('./utils/ui/chalk')
 const { logHeader } = require('./utils/ui/logs')
 const { makeStackedBoxes } = require('@davidwells/box-logger')
 const { findLineForKey } = require('./utils/paths/findLineForKey')
-const { createEditorLink } = require('./utils/ui/createEditorLink')
-const { isSensitiveVariable } = require('./utils/ui/configWizard')
+const { createEditorLink, toClickablePath } = require('./utils/ui/createEditorLink')
+const { isSensitiveVariable } = require('./utils/redaction/redact')
 
 const SPACING = '           '
 const TITLE_TEXT = `Variable:${SPACING}`
 const VALUE_HEX = '#899499'
 
+function uniqueCompact(values) {
+  return [...new Set((values || []).filter(value => value !== undefined && value !== null && value !== ''))]
+}
+
+function firstValue(source, field) {
+  if (!source) return undefined
+  if (source[field] !== undefined && source[field] !== null && source[field] !== '') return source[field]
+  const occurrences = Array.isArray(source.occurrences) ? source.occurrences : []
+  const occurrence = occurrences.find(occ => occ[field] !== undefined && occ[field] !== null && occ[field] !== '')
+  return occurrence ? occurrence[field] : undefined
+}
+
+function getAnnotationMetadata(source) {
+  const occurrences = Array.isArray(source?.occurrences) ? source.occurrences : []
+  return {
+    group: firstValue(source, 'group'),
+    obtainHint: firstValue(source, 'obtainHint'),
+    examples: uniqueCompact([
+      ...(Array.isArray(source?.examples) ? source.examples : []),
+      ...occurrences.flatMap(occ => Array.isArray(occ.examples) ? occ.examples : [])
+    ]),
+    defaultHint: firstValue(source, 'defaultHint'),
+    deprecationMessage: firstValue(source, 'deprecationMessage'),
+  }
+}
+
+function appendAnnotationMetadata(varMsg, source, keyChalk, valueChalk, indent = '') {
+  const metadata = getAnnotationMetadata(source)
+  const lines = []
+
+  if (metadata.group) lines.push(['Group:', metadata.group])
+  if (metadata.obtainHint) lines.push(['From:', metadata.obtainHint])
+  if (metadata.examples.length > 0) {
+    lines.push([metadata.examples.length === 1 ? 'Example:' : 'Examples:', metadata.examples.join(', ')])
+  }
+  if (metadata.defaultHint) lines.push(['Default hint:', metadata.defaultHint])
+  if (metadata.deprecationMessage) lines.push(['Deprecated:', metadata.deprecationMessage])
+
+  for (const [label, value] of lines) {
+    varMsg += `${indent}${keyChalk(label.padEnd(TITLE_TEXT.length, ' '))} ${valueChalk(value)}\n`
+  }
+
+  return varMsg
+}
+
+function isSensitiveOccurrence(varName, occurrences = []) {
+  const explicitOccurrence = occurrences.find(occ => typeof occ.sensitive === 'boolean')
+  if (explicitOccurrence) return explicitOccurrence.sensitive
+  return isSensitiveVariable(varName)
+}
+
 /**
  * Display "No Variables Found" message
  * @param {string} configFilePath
@@ -58,9 +109,13 @@ function displayVariableDetails({ varKeys, variableData, uniqueVariables, varPre
 
   const getBaseVarName = (key) => key.replace(varPrefixPattern, '').replace(varSuffixPattern, '').split(',')[0].trim()
 
-  const fileName = configFilePath ? ` in ${configFilePath}` : ''
+  logHeader(`Found ${varKeys.length} Variables`)
 
-  logHeader(`Found ${varKeys.length} Variables${fileName}`)
+  // Print the path on its own line (outside the wrapping box) so it stays clickable
+  if (configFilePath) {
+    console.log()
+    console.log(`  in ${toClickablePath(configFilePath)}`)
+  }
 
   // deepLog('variableData', variableData)
 
@@ -96,6 +151,8 @@ function displayVariableDetails({ varKeys, variableData, uniqueVariables, varPre
     // Get uniqueVariable data for description and other metadata
     const varName = getBaseVarName(key)
     const uniqueVar = uniqueVariables[varName]
+    const occurrenceMetadata = uniqueVar || { occurrences: variableInstances }
+    const isSensitive = isSensitiveOccurrence(varName, occurrenceMetadata.occurrences || variableInstances)
 
     // Build display message from enriched metadata
     let varMsg = ''
@@ -128,7 +185,7 @@ function displayVariableDetails({ varKeys, variableData, uniqueVariables, varPre
 
     // Show default value from metadata
     if (typeof firstInstance.defaultValue !== 'undefined') {
-      const defaultValueRender = firstInstance.defaultValue === '' ? '""' : firstInstance.defaultValue
+      const defaultValueRender = isSensitive ? '********' : (firstInstance.defaultValue === '' ? '""' : firstInstance.defaultValue)
       const defaultValueText = `${indent}${keyChalk('Default value:'.padEnd(TITLE_TEXT.length, ' '))}`
       varMsg += `${defaultValueText} ${valueChalk(defaultValueRender)}\n`
     }
@@ -144,6 +201,8 @@ function displayVariableDetails({ varKeys, variableData, uniqueVariables, varPre
       }
     }
 
+    varMsg = appendAnnotationMetadata(varMsg, occurrenceMetadata, keyChalk, valueChalk, indent)
+
     // Show path(s) from metadata
     const configPathLine = findLineForKey(variableInstances[0].path, lines, fileType)
     let locationRender = configPathLine
@@ -250,7 +309,7 @@ function displayUniqueVariables({ uniqueVarKeys, uniqueVariables, lines, fileTyp
 
     // Show default value only if it's a true fallback, not a pre-resolved value
     // Redact sensitive values like API keys, secrets, tokens
-    const isSensitive = isSensitiveVariable(varName)
+    const isSensitive = isSensitiveOccurrence(varName, occurrences)
     const hasActualDefault = firstOcc.hasFallback && typeof firstOcc.defaultValue !== 'undefined'
     if (hasActualDefault) {
       const defaultValueRender = isSensitive ? '********' : (firstOcc.defaultValue === '' ? '""' : firstOcc.defaultValue)
@@ -275,6 +334,8 @@ function displayUniqueVariables({ uniqueVarKeys, uniqueVariables, lines, fileTyp
       }
     }
 
+    varMsg = appendAnnotationMetadata(varMsg, uniqueVar, keyChalk, valueChalk)
+
     // Show config path(s) from occurrences
     let locationRender
     let locationLabel
@@ -403,7 +464,7 @@ function displayConfigurableVariables({ uniqueVarKeys, uniqueVariables, lines, f
       }
 
       // Show current/default value (redact sensitive values)
-      const isSensitive = isSensitiveVariable(v.varName)
+      const isSensitive = isSensitiveOccurrence(v.varName, occurrences)
       if (v.resolvedValue !== undefined) {
         const resolvedRender = isSensitive ? '********' : (v.resolvedValue === '' ? '""' : v.resolvedValue)
         varMsg += `${keyChalk('Current value:'.padEnd(TITLE_TEXT.length, ' '))} ${valueChalk(resolvedRender)}\n`
@@ -412,6 +473,8 @@ function displayConfigurableVariables({ uniqueVarKeys, uniqueVariables, lines, f
         varMsg += `${keyChalk('Default value:'.padEnd(TITLE_TEXT.length, ' '))} ${valueChalk(defaultRender)}\n`
       }
 
+      varMsg = appendAnnotationMetadata(varMsg, v, keyChalk, valueChalk)
+
       // Show config path(s)
       let locationRender
       let locationLabel

package/src/display.test.js

@@ -0,0 +1,82 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { displayConfigurableVariables } = require('./display')
+
+function captureStdout(fn) {
+  const originalLog = console.log
+  const output = []
+  console.log = (...args) => output.push(args.join(' '))
+  try {
+    fn()
+  } finally {
+    console.log = originalLog
+  }
+  return output.join('\n')
+}
+
+test('displayConfigurableVariables renders annotation metadata and sensitive overrides', () => {
+  const output = captureStdout(() => {
+    displayConfigurableVariables({
+      uniqueVarKeys: [
+        'env:CONFIGORAMA_DISPLAY_SECRET',
+        'env:CONFIGORAMA_DISPLAY_PUBLIC_KEY',
+      ],
+      uniqueVariables: {
+        'env:CONFIGORAMA_DISPLAY_SECRET': {
+          varName: 'env:CONFIGORAMA_DISPLAY_SECRET',
+          variableType: 'env',
+          variableSourceType: 'user',
+          descriptions: ['Stripe live secret key'],
+          resolvedValue: 'secret-value',
+          occurrences: [
+            {
+              path: 'secrets.stripeSecret',
+              varMatch: '${env:CONFIGORAMA_DISPLAY_SECRET}',
+              isRequired: true,
+              sensitive: true,
+              group: 'Payments',
+              obtainHint: 'Stripe dashboard > Developers > API keys',
+              examples: ['sk_live_...'],
+              defaultHint: 'Set in CI',
+              deprecationMessage: 'Use STRIPE_RESTRICTED_KEY instead',
+            }
+          ],
+        },
+        'env:CONFIGORAMA_DISPLAY_PUBLIC_KEY': {
+          varName: 'env:CONFIGORAMA_DISPLAY_PUBLIC_KEY',
+          variableType: 'env',
+          variableSourceType: 'user',
+          descriptions: ['Public publishable key'],
+          resolvedValue: 'public-value',
+          occurrences: [
+            {
+              path: 'secrets.publishableKey',
+              varMatch: '${env:CONFIGORAMA_DISPLAY_PUBLIC_KEY}',
+              isRequired: true,
+              sensitive: false,
+            }
+          ],
+        },
+      },
+      lines: [],
+      fileType: 'yaml',
+      configFilePath: '',
+    })
+  })
+
+  assert.match(output, /Group:/)
+  assert.match(output, /Payments/)
+  assert.match(output, /From:/)
+  assert.match(output, /Stripe dashboard > Developers > API keys/)
+  assert.match(output, /Example:/)
+  assert.match(output, /sk_live_\.\.\./)
+  assert.match(output, /Default hint:/)
+  assert.match(output, /Set in CI/)
+  assert.match(output, /Deprecated:/)
+  assert.match(output, /Use STRIPE_RESTRICTED_KEY instead/)
+  assert.match(output, /\*{8}/)
+  assert.not.match(output, /secret-value/)
+  assert.match(output, /public-value/)
+})
+
+test.run()

package/src/errors.js

@@ -0,0 +1,73 @@
+// Registry of stable error codes emitted on `error.code` and in `--error-format json`.
+// Single source of truth for the codes referenced by classifyErrorMessage and thrown
+// directly as ConfigoramaError; surfaced by `configorama capabilities`.
+const ERROR_CODES = [
+  { code: 'missing_env', description: 'A referenced environment variable was not set and had no fallback.' },
+  { code: 'missing_file', description: 'A referenced file could not be found on disk.' },
+  { code: 'unresolved_variable', description: 'A variable could not be resolved to a value.' },
+  { code: 'unknown_filter', description: 'A pipe filter name is not registered.' },
+  { code: 'invalid_variable_syntax', description: 'A variable reference is malformed.' },
+  { code: 'circular_dependency', description: 'Variables reference each other in a cycle.' },
+  { code: 'invalid_view', description: 'An unknown --view was passed to the inspect command.' },
+  { code: 'blocked_by_safe_mode', description: 'An executable or mutating reference was blocked by --safe.' },
+  { code: 'blocked_eval_escape', description: 'An eval/if expression attempted a prototype-chain (constructor) escape.' },
+  { code: 'file_root_forbidden', description: 'A file/text reference resolved outside an allowed --safe-root.' },
+  { code: 'unknown_command', description: 'The first argument was not a recognized command.' },
+  { code: 'no_input_file', description: 'No config file was provided on the command line.' },
+  { code: 'file_not_found', description: 'The provided config file path does not exist.' },
+  { code: 'path_not_found', description: 'A jq-style extraction path matched nothing in the resolved config.' },
+  { code: 'configorama_error', description: 'Generic, unclassified configorama error.' },
+]
+
+class ConfigoramaError extends Error {
+  constructor(code, message, details = {}) {
+    super(message)
+    this.name = 'ConfigoramaError'
+    this.code = code || 'configorama_error'
+    this.details = details
+  }
+
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.details || {},
+      }
+    }
+  }
+}
+
+function isConfigoramaError(error) {
+  return !!(error && error.name === 'ConfigoramaError' && error.code)
+}
+
+function normalizeError(error, fallbackCode = 'configorama_error') {
+  if (isConfigoramaError(error)) return error
+  const code = error && error.code ? error.code : classifyErrorMessage(error && error.message, fallbackCode)
+  return new ConfigoramaError(
+    code,
+    error && error.message ? error.message : String(error),
+    error && error.details ? error.details : {}
+  )
+}
+
+function classifyErrorMessage(message, fallbackCode = 'configorama_error') {
+  const text = String(message || '')
+  if (/Filter ".+" not found/.test(text)) return 'unknown_filter'
+  if (/Unable to resolve config variable/.test(text) && /env:/.test(text)) return 'missing_env'
+  if (/Unable to resolve config variable/.test(text)) return 'unresolved_variable'
+  if (/Blocked eval expression/.test(text)) return 'blocked_eval_escape'
+  if (/File not found|cannot resolve due to missing file/i.test(text)) return 'missing_file'
+  if (/Invalid variable reference syntax/.test(text)) return 'invalid_variable_syntax'
+  if (/Circular variable dependency/.test(text)) return 'circular_dependency'
+  return fallbackCode
+}
+
+module.exports = {
+  ERROR_CODES,
+  ConfigoramaError,
+  classifyErrorMessage,
+  isConfigoramaError,
+  normalizeError,
+}

package/src/index.js

@@ -2,6 +2,14 @@ const Configorama = require('./main')
 const parsers = require('./parsers')
 const enrichMetadata = require('./utils/parsing/enrichMetadata')
 const { buildVariableSyntax } = require('./utils/variables/variableUtils')
+const { serializeRequirements } = require('./utils/requirements/serializeRequirements')
+const { buildConfigRequirements } = require('./utils/requirements/configRequirements')
+const { buildIntrospection } = require('./utils/introspection/model')
+const { buildAuditReport } = require('./utils/introspection/audit')
+const { formatGraph } = require('./utils/introspection/graph')
+const { ConfigoramaError } = require('./errors')
+
+const INSPECT_VIEWS = ['requirements', 'audit', 'graph']
 
 /**
  * @typedef {Object} ConfigoramaSettings
@@ -127,7 +135,89 @@ module.exports.analyze = async (configPathOrObject, settings = {}) => {
     returnPreResolvedVariableDetails: true,
   })
   const options = settings.options || {}
-  return instance.init(options)
+  const analysis = await instance.init(options)
+  if (settings.instructions) {
+    return serializeRequirements(analysis, { configPathOrObject })
+  }
+  return analysis
+}
+
+module.exports.introspect = async (configPathOrObject, settings = {}) => {
+  const analysis = await module.exports.analyze(configPathOrObject, {
+    ...settings,
+    blockCustomResolvers: false,
+    blockCustomFunctions: false,
+    blockDotEnv: false,
+  })
+  const requirements = buildConfigRequirements(analysis)
+  return buildIntrospection(analysis, { requirements })
+}
+
+module.exports.audit = async (configPathOrObject, settings = {}) => {
+  const analysis = await module.exports.analyze(configPathOrObject, {
+    ...settings,
+    blockCustomResolvers: false,
+    blockCustomFunctions: false,
+    blockDotEnv: false,
+  })
+  const requirements = buildConfigRequirements(analysis)
+  const introspection = buildIntrospection(analysis, { requirements })
+  const customResolvers = Array.isArray(settings.variableSources)
+    ? settings.variableSources.map(source => source.type).filter(Boolean)
+    : []
+  const originalConfig = analysis.originalConfig || {}
+  return buildAuditReport(introspection, {
+    safeMode: settings.safeMode === true || settings.safe === true,
+    dotenv: originalConfig.useDotenv === true || originalConfig.useDotEnv === true || settings.useDotEnvFiles === true,
+    customResolvers,
+  })
+}
+
+module.exports.graph = async (configPathOrObject, settings = {}) => {
+  const graph = await module.exports.introspect(configPathOrObject, settings)
+  if (settings.formatGraph === false) return graph
+  return formatGraph(graph, settings.format || 'json')
+}
+
+/**
+ * Unified introspection entry point. Without a view it returns the full model
+ * (requirements + graph + audit). With `settings.view` it returns a single
+ * projection, identical to the focused `requirements` / `graph` / `audit` verbs.
+ * @param {string|object} configPathOrObject - Path to config file or raw config object
+ * @param {object} [settings] - Same settings as the main API, plus `view` and `format`
+ * @return {Promise<object|string>} the requested model (string for mermaid/dot graph views)
+ */
+module.exports.inspect = async (configPathOrObject, settings = {}) => {
+  const view = settings.view
+  if (view !== undefined && view !== null && view !== '' && !INSPECT_VIEWS.includes(view)) {
+    throw new ConfigoramaError('invalid_view', `Unknown inspect view "${view}". Valid views: ${INSPECT_VIEWS.join(', ')}.`)
+  }
+  if (view === 'requirements') {
+    return module.exports.analyze(configPathOrObject, { ...settings, instructions: true })
+  }
+  if (view === 'audit') {
+    return module.exports.audit(configPathOrObject, settings)
+  }
+  if (view === 'graph') {
+    return module.exports.graph(configPathOrObject, settings)
+  }
+
+  // Full model: each projection runs its own verb's code path so the unified
+  // output stays identical to `requirements`, `graph`, and `audit` run alone.
+  // (Those paths use different analyze settings, so they are not collapsible
+  // into a single shared analysis without changing their output.)
+  const [requirements, graph, audit] = await Promise.all([
+    module.exports.analyze(configPathOrObject, { ...settings, instructions: true }),
+    module.exports.graph(configPathOrObject, { ...settings, formatGraph: false }),
+    module.exports.audit(configPathOrObject, settings),
+  ])
+  return {
+    schemaVersion: 1,
+    config: typeof configPathOrObject === 'string' ? configPathOrObject : (settings.configFilePath || null),
+    requirements,
+    graph,
+    audit,
+  }
 }
 
 /**