configorama 0.11.2 → 1.0.0

package/src/utils/introspection/audit.js

@@ -0,0 +1,78 @@
+const { severityForRisk } = require('./model')
+
+function sortFindings(a, b) {
+  const severityOrder = { high: 0, medium: 1, low: 2, info: 3 }
+  const severityDiff = (severityOrder[a.severity] ?? 99) - (severityOrder[b.severity] ?? 99)
+  if (severityDiff !== 0) return severityDiff
+  return String(a.id).localeCompare(String(b.id))
+}
+
+function buildAuditReport(introspection, options = {}) {
+  const findings = []
+
+  for (const node of introspection.nodes || []) {
+    if (!node.risk || node.risk === 'none') continue
+    findings.push({
+      id: node.id,
+      severity: node.severity || severityForRisk(node.risk),
+      risk: node.risk,
+      kind: node.kind,
+      variable: node.variable,
+      path: node.path,
+      relativePath: node.relativePath,
+      configPaths: node.paths || [],
+      message: messageForNode(node),
+    })
+  }
+
+  if (options.dotenv === true) {
+    findings.push({
+      id: 'dotenv:useDotenv',
+      severity: 'high',
+      risk: 'environment_mutation',
+      kind: 'source',
+      message: 'Configuration requests dotenv loading, which mutates process.env.',
+    })
+  }
+
+  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.`,
+      })
+    }
+  }
+
+  findings.sort(sortFindings)
+
+  return {
+    schemaVersion: 1,
+    safeMode: options.safeMode === true,
+    findings,
+    diagnostics: introspection.diagnostics || [],
+    summary: {
+      high: findings.filter(finding => finding.severity === 'high').length,
+      medium: findings.filter(finding => finding.severity === 'medium').length,
+      low: findings.filter(finding => finding.severity === 'low').length,
+      info: findings.filter(finding => finding.severity === 'info').length,
+      total: findings.length,
+    }
+  }
+}
+
+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.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}`
+}
+
+module.exports = {
+  buildAuditReport,
+}

package/src/utils/introspection/graph.js

@@ -0,0 +1,43 @@
+function quote(value) {
+  return JSON.stringify(String(value))
+}
+
+function toMermaid(graph) {
+  const lines = ['graph TD']
+  for (const node of graph.nodes) {
+    lines.push(`  ${sanitizeId(node.id)}[${quote(node.label || node.variable || node.relativePath || node.id).slice(1, -1)}]`)
+  }
+  for (const edge of graph.edges) {
+    lines.push(`  ${sanitizeId(edge.from)} -->|${edge.kind}| ${sanitizeId(edge.to)}`)
+  }
+  return lines.join('\n') + '\n'
+}
+
+function sanitizeId(value) {
+  return String(value).replace(/[^A-Za-z0-9_]/g, '_')
+}
+
+function toDot(graph) {
+  const lines = ['digraph configorama {']
+  for (const node of graph.nodes) {
+    lines.push(`  ${quote(node.id)} [label=${quote(node.label || node.variable || node.relativePath || node.id)}];`)
+  }
+  for (const edge of graph.edges) {
+    lines.push(`  ${quote(edge.from)} -> ${quote(edge.to)} [label=${quote(edge.kind)}];`)
+  }
+  lines.push('}')
+  return lines.join('\n') + '\n'
+}
+
+function formatGraph(graph, format = 'json') {
+  const normalized = String(format || 'json').toLowerCase()
+  if (normalized === 'mermaid' || normalized === 'mmd') return toMermaid(graph)
+  if (normalized === 'dot' || normalized === 'graphviz') return toDot(graph)
+  return JSON.stringify(graph, null, 2)
+}
+
+module.exports = {
+  formatGraph,
+  toDot,
+  toMermaid,
+}

package/src/utils/introspection/model.js

@@ -0,0 +1,150 @@
+const path = require('path')
+const { EXECUTABLE_EXTENSIONS } = require('../security/safetyPolicy')
+const { redactRequirementValue } = require('../redaction/redact')
+
+const SCHEMA_VERSION = 1
+
+function sortBy(keys) {
+  return (a, b) => {
+    for (const key of keys) {
+      const av = a[key] === undefined || a[key] === null ? '' : String(a[key])
+      const bv = b[key] === undefined || b[key] === null ? '' : String(b[key])
+      if (av < bv) return -1
+      if (av > bv) return 1
+    }
+    return 0
+  }
+}
+
+function normalizeVariableType(type) {
+  if (type === 'options' || type === 'opt') return 'option'
+  if (type === 'dot.prop') return 'dotProp'
+  if (type === 'if') return 'eval'
+  return type || 'unknown'
+}
+
+function riskForVariable(variableType, variable) {
+  const type = normalizeVariableType(variableType)
+  if (type === 'eval') return 'data_flow_expression'
+  if (type === 'git') return 'process_spawn'
+  if (type === 'file' || type === 'text') {
+    const match = String(variable || '').match(/^(?:file|text)\((.+?)\)/)
+    const ext = match ? path.extname(match[1]).toLowerCase() : ''
+    return EXECUTABLE_EXTENSIONS.has(ext) ? 'executable_code' : 'local_file_read'
+  }
+  return 'none'
+}
+
+function severityForRisk(risk) {
+  if (risk === 'executable_code' || risk === 'custom_extension' || risk === 'environment_mutation') return 'high'
+  if (risk === 'process_spawn') return 'medium'
+  if (risk === 'local_file_read' || risk === 'data_flow_expression') return 'low'
+  return 'info'
+}
+
+function buildIntrospection(enrichedMetadata = {}, options = {}) {
+  const uniqueVariables = enrichedMetadata.uniqueVariables || {}
+  const requirements = options.requirements || []
+  const requirementsByVariable = new Map(requirements.map(req => [req.variable, req]))
+  const nodes = []
+  const edges = []
+  const diagnostics = []
+
+  for (const [key, entry] of Object.entries(uniqueVariables).sort(([a], [b]) => a.localeCompare(b))) {
+    const variable = entry.variable || key
+    const variableType = normalizeVariableType(entry.variableType)
+    const requirement = requirementsByVariable.get(variable)
+    const risk = riskForVariable(variableType, variable)
+    const node = {
+      id: `variable:${variable}`,
+      kind: variableType === 'file' || variableType === 'text'
+        ? 'file'
+        : (risk === 'executable_code' ? 'executable' : 'variable'),
+      variable,
+      variableType,
+      sourceClass: entry.variableSourceType || entry.sourceClass || requirement?.sourceClass || null,
+      risk,
+      severity: severityForRisk(risk),
+      paths: [...new Set((entry.occurrences || []).map(occ => occ.path).filter(Boolean))].sort(),
+      sensitive: requirement ? requirement.sensitive === true : false,
+    }
+    if (requirement) {
+      node.required = requirement.required
+      node.default = redactRequirementValue(requirement, requirement.default)
+      node.description = requirement.description
+    }
+    nodes.push(node)
+
+    for (const configPath of node.paths) {
+      edges.push({
+        from: `configPath:${configPath}`,
+        to: node.id,
+        kind: 'uses',
+      })
+    }
+
+    for (const inner of entry.innerVariables || []) {
+      edges.push({
+        from: node.id,
+        to: `variable:${inner.variable}`,
+        kind: 'depends_on',
+      })
+    }
+
+    if ((variableType === 'file' || variableType === 'text') && String(variable).includes('${')) {
+      diagnostics.push({
+        code: 'dynamic_file_target',
+        severity: 'info',
+        variable,
+        message: 'File target contains variables; static introspection records a partial edge.',
+      })
+    }
+  }
+
+  const fileDeps = enrichedMetadata.fileDependencies || {}
+  for (const dep of fileDeps.byConfigPath || []) {
+    const id = `file:${dep.relativePath || dep.filePath}`
+    if (!nodes.some(node => node.id === id)) {
+      nodes.push({
+        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',
+      })
+    }
+    if (dep.location) {
+      edges.push({
+        from: `configPath:${dep.location}`,
+        to: id,
+        kind: 'reads',
+      })
+    }
+  }
+
+  nodes.sort(sortBy(['kind', 'id']))
+  edges.sort(sortBy(['from', 'kind', 'to']))
+  diagnostics.sort(sortBy(['code', 'variable']))
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    nodes,
+    edges,
+    diagnostics,
+    summary: {
+      nodes: nodes.length,
+      edges: edges.length,
+      diagnostics: diagnostics.length,
+    }
+  }
+}
+
+module.exports = {
+  SCHEMA_VERSION,
+  buildIntrospection,
+  normalizeVariableType,
+  riskForVariable,
+  severityForRisk,
+}

package/src/utils/introspection/model.test.js

@@ -0,0 +1,93 @@
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+const { buildIntrospection, riskForVariable } = require('./model')
+const { buildAuditReport } = require('./audit')
+const { formatGraph } = require('./graph')
+
+test('riskForVariable classifies eval as data-flow and js file refs as executable', () => {
+  assert.is(riskForVariable('eval', 'eval(1 + 1)'), 'data_flow_expression')
+  assert.is(riskForVariable('if', 'if(true)'), 'data_flow_expression')
+  assert.is(riskForVariable('file', 'file(./config.js)'), 'executable_code')
+  assert.is(riskForVariable('file', 'file(./config.yml)'), 'local_file_read')
+})
+
+test('buildIntrospection creates deterministic nodes edges and dynamic diagnostics', () => {
+  const graph = buildIntrospection({
+    uniqueVariables: {
+      'file(./${opt:stage}.yml)': {
+        variable: 'file(./${opt:stage}.yml)',
+        variableType: 'file',
+        variableSourceType: 'config',
+        occurrences: [{ path: 'database' }],
+        innerVariables: [{ variable: 'opt:stage', variableType: 'options' }]
+      },
+      'opt:stage': {
+        variable: 'opt:stage',
+        variableType: 'options',
+        variableSourceType: 'user',
+        occurrences: [{ path: 'stage' }]
+      }
+    },
+    fileDependencies: {
+      byConfigPath: []
+    }
+  }, {
+    requirements: [{ variable: 'opt:stage', sensitive: false, required: true, default: null }]
+  })
+
+  assert.is(graph.schemaVersion, 1)
+  assert.ok(graph.nodes.some(node => node.id === 'variable:file(./${opt:stage}.yml)'))
+  assert.ok(graph.edges.some(edge => edge.kind === 'depends_on'))
+  assert.is(graph.diagnostics[0].code, 'dynamic_file_target')
+})
+
+test('buildIntrospection redacts sensitive requirement defaults', () => {
+  const graph = buildIntrospection({
+    uniqueVariables: {
+      'env:API_KEY': {
+        variable: 'env:API_KEY',
+        variableType: 'env',
+        variableSourceType: 'user',
+        occurrences: [{ path: 'apiKey' }]
+      }
+    },
+    fileDependencies: { byConfigPath: [] }
+  }, {
+    requirements: [{
+      variable: 'env:API_KEY',
+      sensitive: true,
+      required: false,
+      default: 'secret-value',
+      description: 'API key'
+    }]
+  })
+
+  const node = graph.nodes.find(item => item.variable === 'env:API_KEY')
+  assert.is(node.sensitive, true)
+  assert.is(node.default, '********')
+})
+
+test('audit report sorts executable findings before lower severity surfaces', () => {
+  const report = buildAuditReport({
+    nodes: [
+      { id: 'variable:eval(1)', risk: 'data_flow_expression', severity: 'low', kind: 'variable' },
+      { id: 'variable:file(./x.js)', risk: 'executable_code', severity: 'high', kind: 'executable' }
+    ],
+    diagnostics: []
+  })
+
+  assert.is(report.summary.total, 2)
+  assert.is(report.findings[0].severity, 'high')
+})
+
+test('formatGraph emits mermaid and dot formats', () => {
+  const graph = {
+    nodes: [{ id: 'configPath:stage', label: 'stage' }, { id: 'variable:opt:stage', variable: 'opt:stage' }],
+    edges: [{ from: 'configPath:stage', to: 'variable:opt:stage', kind: 'uses' }]
+  }
+
+  assert.match(formatGraph(graph, 'mermaid'), /graph TD/)
+  assert.match(formatGraph(graph, 'dot'), /digraph configorama/)
+})
+
+test.run()

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()