@soulbatical/tetra-dev-toolkit 1.20.25 → 1.20.26

package/lib/checks/codeQuality/env-vars-defined.js

@@ -0,0 +1,491 @@
+/**
+ * Code Quality Check: Env Vars Defined in Doppler
+ *
+ * Scans source files for process.env.X and import.meta.env.X references
+ * and verifies they are defined in the appropriate Doppler config(s).
+ *
+ * WHAT IT CATCHES:
+ *   - FAIL: process.env.X || "" (empty-string fallback) and X is missing in Doppler
+ *     → silently produces wrong API URLs, missing tokens, empty base URLs
+ *   - FAIL: process.env.X ?? "" (nullish-coalescing empty fallback) and X missing
+ *   - WARN: process.env.X || 'non-empty-default' and X missing in Doppler
+ *     → sometimes intentional, sometimes a forgotten secret
+ *   - WARN: process.env.X (no fallback) and X missing
+ *
+ * SKIP:
+ *   - NODE_ENV, PORT — always set by runtime
+ *   - Vars already validated via tetra-core createApp({ requiredEnvVars: [...] })
+ *   - If Doppler CLI is not installed or not authenticated
+ *
+ * HOW IT WORKS:
+ *   1. Reads doppler.yaml from projectRoot to discover the Doppler project name.
+ *   2. Scans TS/TSX/JS/JSX source files for env var references.
+ *   3. Maps each file path to a Doppler config (dev_backend, dev_frontend, etc.)
+ *   4. Calls `doppler secrets --json` once per config and caches results.
+ *   5. Reports missing vars with suggested fix commands.
+ *
+ * Severity: high — empty-fallback missing vars cause silent production failures
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, relative } from 'path'
+import { glob } from 'glob'
+import { execFileSync } from 'child_process'
+
+// ============================================================================
+// META
+// ============================================================================
+
+export const meta = {
+  id: 'env-vars-defined',
+  name: 'Env vars defined in Doppler',
+  category: 'codeQuality',
+  severity: 'high',
+  description: 'Verifies that env vars referenced in source files are defined in the matching Doppler config'
+}
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+const IGNORE_PATTERNS = [
+  '**/node_modules/**',
+  '**/.next/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.netlify/**',
+  '**/coverage/**',
+]
+
+/**
+ * Vars that are always present — set by runtime, Next.js, Express, or Node itself.
+ * Never flag these as missing.
+ */
+const BUILTIN_VARS = new Set([
+  'NODE_ENV',
+  'PORT',
+  'HOST',
+  'HOSTNAME',
+  'PWD',
+  'HOME',
+  'PATH',
+  'USER',
+  'SHELL',
+  'TERM',
+  'CI',
+  'TZ',
+  'LANG',
+  'npm_lifecycle_event',
+  'npm_package_version',
+  'VERCEL',
+  'VERCEL_ENV',
+  'VERCEL_URL',
+  'NEXT_RUNTIME',
+  'NEXT_PHASE',
+])
+
+// ============================================================================
+// DOPPLER CONFIG MAPPING
+// ============================================================================
+
+/**
+ * Map a source file path (relative to projectRoot) to Doppler config name(s).
+ * Returns an array because some files may be relevant to multiple configs
+ * (e.g. a shared util used by both backend and frontend).
+ *
+ * Convention:
+ *   frontend/**  → dev_frontend (+ prd_frontend if it exists)
+ *   src/app/**   → dev_frontend (Next.js app router)
+ *   backend/**   → dev_backend (+ prd_backend if it exists)
+ *   backend-mcp/**  → dev_backend
+ *   bot/**       → dev_bot
+ *   (other)      → dev_backend (safe default)
+ */
+function getConfigsForFile(relPath) {
+  const p = relPath.replace(/\\/g, '/')
+
+  if (p.startsWith('frontend/') || p.startsWith('src/app/') || p.startsWith('src/pages/')) {
+    return ['dev_frontend', 'prd_frontend']
+  }
+  if (p.startsWith('bot/')) {
+    return ['dev_bot']
+  }
+  if (p.startsWith('backend-mcp/') || p.startsWith('backend/')) {
+    return ['dev_backend', 'prd_backend']
+  }
+
+  // Top-level src/ could be Next.js root — treat as frontend
+  if (p.startsWith('src/')) {
+    return ['dev_frontend', 'prd_frontend']
+  }
+
+  // Default fallback
+  return ['dev_backend']
+}
+
+// ============================================================================
+// DOPPLER HELPERS
+// ============================================================================
+
+/**
+ * Read doppler.yaml from the project root.
+ * Returns the first `project:` value found, or null.
+ *
+ * doppler.yaml format:
+ *   setup:
+ *     - project: my-project
+ *       config: dev_backend
+ *       path: backend/
+ */
+function readDopplerProject(projectRoot) {
+  const dopplerYamlPath = join(projectRoot, 'doppler.yaml')
+  if (!existsSync(dopplerYamlPath)) return null
+
+  try {
+    const content = readFileSync(dopplerYamlPath, 'utf-8')
+    const m = content.match(/project:\s*(\S+)/)
+    return m ? m[1] : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Test whether the `doppler` CLI is installed and authenticated.
+ * Uses execFileSync with argument array — no shell injection risk.
+ * Returns { ok: boolean, reason?: string }
+ */
+function checkDopplerAuth() {
+  try {
+    execFileSync('doppler', ['--version'], { stdio: 'ignore', timeout: 5000 })
+  } catch {
+    return { ok: false, reason: 'doppler CLI not found — install it from https://docs.doppler.com/docs/install-cli' }
+  }
+
+  try {
+    execFileSync('doppler', ['me'], { stdio: 'ignore', timeout: 5000 })
+  } catch {
+    return { ok: false, reason: 'doppler CLI not authenticated — run `doppler login`' }
+  }
+
+  return { ok: true }
+}
+
+/**
+ * Fetch the set of secret names defined in a Doppler config.
+ * Returns null if the config does not exist or the call fails.
+ *
+ * Cache is per (project, config) within a single audit run.
+ * Uses execFileSync with argument array — no shell injection risk.
+ */
+const _dopplerCache = new Map()
+
+function fetchDopplerSecretNames(dopplerProject, configName) {
+  const key = `${dopplerProject}::${configName}`
+  if (_dopplerCache.has(key)) return _dopplerCache.get(key)
+
+  try {
+    const raw = execFileSync(
+      'doppler',
+      ['secrets', '--project', dopplerProject, '--config', configName, '--json'],
+      { stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }
+    )
+    const parsed = JSON.parse(raw.toString())
+    const names = new Set(Object.keys(parsed))
+    _dopplerCache.set(key, names)
+    return names
+  } catch {
+    // Config may not exist (e.g. prd_frontend in a project that only has dev_frontend)
+    _dopplerCache.set(key, null)
+    return null
+  }
+}
+
+// ============================================================================
+// SOURCE SCANNING
+// ============================================================================
+
+/**
+ * Patterns we look for in source files.
+ * Each pattern captures the variable name and optionally the fallback value.
+ *
+ * Matches:
+ *   process.env.MY_VAR
+ *   process.env.MY_VAR || ''
+ *   process.env.MY_VAR || ""
+ *   process.env.MY_VAR ?? ''
+ *   process.env.MY_VAR ?? ""
+ *   process.env.MY_VAR || 'some-default'
+ *   import.meta.env.MY_VAR
+ *   import.meta.env.MY_VAR || ''
+ */
+const ENV_RE_SOURCE = /(?:process\.env|import\.meta\.env)\.([A-Z][A-Z0-9_]*)(?:\s*(?:\|\||[?][?])\s*(['"`]([^'"`]*)['"`]))?/g
+
+function scanFile(content) {
+  const findings = []
+  const lines = content.split('\n')
+
+  for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+    const line = lines[lineIdx]
+
+    // Skip comment lines
+    if (/^\s*(\/\/|\/\*|\*)/.test(line)) continue
+
+    const lineRe = new RegExp(ENV_RE_SOURCE.source, 'g')
+    let match
+
+    while ((match = lineRe.exec(line)) !== null) {
+      const varName = match[1]
+      const hasFallback = match[2] !== undefined
+      const fallbackValue = match[3] ?? null
+      // Empty fallback: || '' or || "" or ?? '' or ?? ""
+      const isEmptyFallback = hasFallback && (fallbackValue === '' || fallbackValue === null)
+
+      findings.push({
+        varName,
+        line: lineIdx + 1,
+        hasFallback,
+        isEmptyFallback,
+        fallbackValue,
+      })
+    }
+  }
+
+  return findings
+}
+
+// ============================================================================
+// REQUIRED ENV VARS FROM TETRA-CORE createApp()
+// ============================================================================
+
+/**
+ * Scan the project for `requiredEnvVars: [...]` in createApp() calls.
+ * These are already validated at startup so we skip them in this check.
+ */
+function collectRequiredEnvVars(projectRoot) {
+  const result = new Set()
+
+  const files = glob.sync('**/*.ts', {
+    cwd: projectRoot,
+    ignore: IGNORE_PATTERNS,
+    absolute: true,
+  })
+
+  for (const absPath of files) {
+    let content
+    try { content = readFileSync(absPath, 'utf-8') } catch { continue }
+
+    // Match: requiredEnvVars: ['A', 'B', "C"]
+    const blockRe = /requiredEnvVars\s*:\s*\[([^\]]+)\]/g
+    let m
+    while ((m = blockRe.exec(content)) !== null) {
+      const inner = m[1]
+      const strRe = /['"]([A-Z][A-Z0-9_]*)['"]/g
+      let s
+      while ((s = strRe.exec(inner)) !== null) {
+        result.add(s[1])
+      }
+    }
+  }
+
+  return result
+}
+
+// ============================================================================
+// MAIN CHECK
+// ============================================================================
+
+export async function run(config, projectRoot) {
+  const result = {
+    passed: true,
+    findings: [],
+    summary: { total: 0, critical: 0, high: 0, medium: 0, low: 0 },
+    details: {
+      filesScanned: 0,
+      varsChecked: 0,
+      missingInDoppler: 0,
+      emptyFallbackMissing: 0,
+      dopplerSkipped: false,
+      dopplerProject: null,
+    }
+  }
+
+  // ── Step 1: check Doppler auth ────────────────────────────────────────────
+
+  const authCheck = checkDopplerAuth()
+  if (!authCheck.ok) {
+    result.details.dopplerSkipped = true
+    result.findings.push({
+      file: 'project',
+      line: 0,
+      severity: 'low',
+      message: `env-vars-defined check skipped: ${authCheck.reason}`,
+    })
+    result.summary.low++
+    result.summary.total++
+    return result
+  }
+
+  // ── Step 2: read Doppler project name ──────────────────────────────────────
+
+  const dopplerProject = readDopplerProject(projectRoot)
+  if (!dopplerProject) {
+    result.details.dopplerSkipped = true
+    result.findings.push({
+      file: 'doppler.yaml',
+      line: 0,
+      severity: 'low',
+      message: 'env-vars-defined check skipped: no doppler.yaml found (or no project: field)',
+    })
+    result.summary.low++
+    result.summary.total++
+    return result
+  }
+
+  result.details.dopplerProject = dopplerProject
+
+  // ── Step 3: collect vars already validated by tetra-core ──────────────────
+
+  const alreadyValidated = collectRequiredEnvVars(projectRoot)
+
+  // ── Step 4: scan source files ─────────────────────────────────────────────
+
+  const sourceFiles = glob.sync('**/*.{ts,tsx,js,jsx}', {
+    cwd: projectRoot,
+    ignore: IGNORE_PATTERNS,
+    absolute: true,
+  })
+
+  result.details.filesScanned = sourceFiles.length
+
+  // Track reported (file, varName) pairs to avoid duplicate findings for same
+  // var referenced multiple times in same file
+  const reported = new Set()
+
+  for (const absPath of sourceFiles) {
+    let content
+    try { content = readFileSync(absPath, 'utf-8') } catch { continue }
+
+    const relPath = relative(projectRoot, absPath)
+    const usages = scanFile(content)
+
+    for (const usage of usages) {
+      const { varName, line, hasFallback, isEmptyFallback, fallbackValue } = usage
+
+      // Skip builtins
+      if (BUILTIN_VARS.has(varName)) continue
+
+      // Skip vars already validated at startup by tetra-core
+      if (alreadyValidated.has(varName)) continue
+
+      result.details.varsChecked++
+
+      const configs = getConfigsForFile(relPath)
+
+      // Check each applicable config — if the var is defined in ANY of them,
+      // it's fine (e.g. prd_frontend might not exist yet)
+      let foundInAny = false
+      const checkedConfigs = []
+
+      for (const configName of configs) {
+        const secrets = fetchDopplerSecretNames(dopplerProject, configName)
+        if (secrets === null) {
+          // Config doesn't exist (e.g. prd_frontend) — skip silently
+          continue
+        }
+        checkedConfigs.push(configName)
+        if (secrets.has(varName)) {
+          foundInAny = true
+          break
+        }
+      }
+
+      // If we couldn't check any config (all returned null), skip silently
+      if (checkedConfigs.length === 0) continue
+
+      if (foundInAny) continue
+
+      // Var is missing in all checked configs
+      result.details.missingInDoppler++
+
+      const dedupeKey = `${relPath}::${varName}`
+      const firstOccurrence = !reported.has(dedupeKey)
+      reported.add(dedupeKey)
+
+      const fixConfig = checkedConfigs[0] ?? configs[0]
+      const fixCmd = `doppler secrets set ${varName}=<value> --project ${dopplerProject} --config ${fixConfig}`
+
+      if (isEmptyFallback) {
+        // FAIL — empty fallback means code will silently use "" as the value
+        result.details.emptyFallbackMissing++
+        result.passed = false
+        result.summary.high++
+        result.summary.total++
+
+        result.findings.push({
+          file: relPath,
+          line,
+          severity: 'high',
+          message: [
+            `Missing env var with empty fallback — silent failure risk:`,
+            `  File:    ${relPath}:${line}`,
+            `  Var:     ${varName}`,
+            `  Pattern: process.env.${varName} || ""  ← empty string silently used as value`,
+            `  Configs: ${checkedConfigs.join(', ')} (project: ${dopplerProject})`,
+            ``,
+            `  This is the silent-failure class: code runs without error but produces`,
+            `  wrong API URLs, empty tokens, or missing base URLs.`,
+            ``,
+            `  Fix option 1: add to Doppler:`,
+            `    ${fixCmd}`,
+            `  Fix option 2: replace with getRequiredEnv("${varName}") from @soulbatical/tetra-ui`,
+            `    → crashes loud at startup instead of silently using ""`,
+          ].join('\n'),
+          fix: fixCmd,
+        })
+      } else if (hasFallback && firstOccurrence) {
+        // WARN — non-empty fallback, possibly intentional
+        result.summary.medium++
+        result.summary.total++
+
+        result.findings.push({
+          file: relPath,
+          line,
+          severity: 'medium',
+          message: [
+            `Env var with non-empty fallback not found in Doppler (may be intentional):`,
+            `  File:    ${relPath}:${line}`,
+            `  Var:     ${varName}`,
+            `  Fallback: "${fallbackValue}"`,
+            `  Configs: ${checkedConfigs.join(', ')} (project: ${dopplerProject})`,
+            ``,
+            `  If this var must be configurable per environment, add it to Doppler:`,
+            `  ${fixCmd}`,
+          ].join('\n'),
+          fix: fixCmd,
+        })
+      } else if (!hasFallback && firstOccurrence) {
+        // WARN — no fallback, var missing
+        result.summary.medium++
+        result.summary.total++
+
+        result.findings.push({
+          file: relPath,
+          line,
+          severity: 'medium',
+          message: [
+            `Env var not found in Doppler:`,
+            `  File:    ${relPath}:${line}`,
+            `  Var:     ${varName}`,
+            `  Configs: ${checkedConfigs.join(', ')} (project: ${dopplerProject})`,
+            ``,
+            `  Fix: ${fixCmd}`,
+          ].join('\n'),
+          fix: fixCmd,
+        })
+      }
+    }
+  }
+
+  return result
+}