Environment Variable Extraction from Source Code Prompt

This prompt is for DevOps engineers, platform teams, and SREs who need to audit a codebase and produce a machine-readable catalog of every environment variable reference. Use it when you are onboarding to a new service, preparing for a security audit, or generating configuration documentation that must stay synchronized with the actual code. The primary job-to-be-done is converting scattered process.env, os.getenv, System.getenv, or equivalent calls across multiple files into a single structured inventory that includes the variable name, file location, default value, and usage context.

The prompt assumes you can provide representative source files or code snippets. It is not a replacement for a static analysis tool but a fast, flexible way to bootstrap documentation and detect drift. You should use this prompt when you need a human-readable starting point for a configuration audit, when you suspect undocumented environment variables exist in a service you inherited, or when you are preparing a compliance artifact that requires listing every external configuration dependency. Do not use this prompt when you need guaranteed completeness for a safety-critical system—static analysis tools with AST parsing are more reliable for exhaustive extraction. Do not use it when the codebase contains obfuscated, dynamically constructed, or reflection-based variable access that a text-based LLM cannot trace.

Before running this prompt, gather representative source files that contain environment variable access patterns. If the codebase is large, sample the most configuration-heavy modules: database connectors, API clients, authentication middleware, and startup scripts. Provide enough context so the model can distinguish between environment variables and similarly named local variables or constants. After receiving the output, validate it against a known subset of variables you already expect to find. Flag any variable that appears in the catalog but not in your existing documentation as a candidate for investigation. The next section provides the exact prompt template you can adapt and run.

This prompt template scans source files for environment variable references and produces a structured catalog suitable for documentation, auditing, or drift detection. It handles common access patterns across languages—process.env, os.getenv, os.environ, System.getenv, env.—and distinguishes between direct reads, defaulted reads, and conditional checks. The output is designed to feed directly into a configuration reference pipeline or a variable audit harness.

textCopy
You are an environment variable extraction engine. Your task is to scan the provided source code files and produce a structured JSON catalog of every environment variable reference.

## INPUT
Source files with file paths and content:
[SOURCE_FILES]

## OUTPUT_SCHEMA
Return a JSON object with a single key "variables" containing an array of objects. Each object must have these fields:
- "name": string (the exact environment variable name as referenced in code)
- "file": string (relative file path where the reference appears)
- "line": number (approximate line number, or null if unavailable)
- "access_pattern": string (one of: "direct_read", "defaulted_read", "conditional_check", "boolean_flag", "coerced_read")
- "default_value": string or null (the fallback value if provided, otherwise null)
- "type_hint": string or null (inferred type from coercion or usage: "string", "number", "boolean", "list", "json", or null)
- "required": boolean (true if no default is provided and no conditional guard exists before use)
- "usage_context": string (one-sentence description of how the variable is used at this location)
- "sensitive": boolean (true if the variable name suggests secrets: contains KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL, or is used in auth context)

## CONSTRAINTS
- Include every distinct variable-file combination. If the same variable appears in multiple files, create one entry per file.
- Do not invent variables not present in the source.
- If a variable is read inside a conditional block that checks for its existence first, mark required as false.
- For access patterns: use "direct_read" for bare reads like `process.env.X`; "defaulted_read" for reads with a fallback like `process.env.X || 'default'`; "conditional_check" for `if (process.env.X)` guards; "boolean_flag" for truthiness checks used as feature flags; "coerced_read" for parseInt/JSON.parse wrapping.
- If you cannot determine a field value, use null. Do not guess.
- Sort the output array alphabetically by name, then by file path.

## EXAMPLES
Input:
```javascript
// config.js
const PORT = process.env.PORT || '3000';
const DB_URL = process.env.DATABASE_URL;
if (process.env.ENABLE_FEATURE_X) { ... }

Output:

jsonCopy
{
  "variables": [
    {
      "name": "DATABASE_URL",
      "file": "config.js",
      "line": 3,
      "access_pattern": "direct_read",
      "default_value": null,
      "type_hint": "string",
      "required": true,
      "usage_context": "Database connection string used to establish backend connectivity",
      "sensitive": true
    },
    {
      "name": "ENABLE_FEATURE_X",
      "file": "config.js",
      "line": 4,
      "access_pattern": "boolean_flag",
      "default_value": null,
      "type_hint": "boolean",
      "required": false,
      "usage_context": "Feature flag controlling experimental feature X activation",
      "sensitive": false
    },
    {
      "name": "PORT",
      "file": "config.js",
      "line": 2,
      "access_pattern": "defaulted_read",
      "default_value": "3000",
      "type_hint": "number",
      "required": false,
      "usage_context": "Network port the server binds to for incoming HTTP requests",
      "sensitive": false
    }
  ]
}

RISK_LEVEL

Low. Output is derived from static analysis of provided source files. No destructive actions. Human review recommended before publishing as documentation.

Now process the provided source files and return only the JSON output with no additional commentary.

To adapt this template, replace [SOURCE_FILES] with your actual source content—typically a concatenation of file paths and their contents, formatted as ### FILE: path/to/file.ext followed by the code block. For large codebases, run the prompt per directory or module to stay within context limits, then merge the results. If your codebase uses custom config wrappers or indirect variable access (e.g., a getConfig('key') helper), add an example of that pattern to the [EXAMPLES] section so the model recognizes it. The sensitive field uses a heuristic based on variable naming—adjust the keyword list in [CONSTRAINTS] to match your organization's secret naming conventions.

Before wiring this into a documentation pipeline, validate the output against a known-good reference. Common failure modes include: missing variables accessed through dynamic string construction (e.g., process.env['PREFIX_' + name]), false positives from commented-out code, and incorrect required classification when guard clauses span multiple files. Run the prompt against a small, well-understood module first and compare the extracted catalog to your manual inventory. If the type_hint field matters for downstream tooling, add a post-processing step that cross-references against a schema registry or config validation layer rather than relying solely on the model's inference.

This prompt is designed to be called programmatically from a script, Makefile target, or CI/CD pipeline step rather than run interactively. The core workflow is: gather source files, assemble the prompt, call the LLM, validate the response, and store the result as a build artifact. A typical invocation script first collects all files matching a pattern (*.py, *.js, *.go, *.ts) and concatenates them with file path headers so the model can attribute each variable reference to its source location. The concatenated source block is injected into the [SOURCE_CODE] placeholder. If your codebase exceeds the model's context window, split by directory or service and run the prompt multiple times, then merge the resulting JSON arrays.

When calling the LLM, set response_format to json_object (OpenAI) or use the equivalent structured output mode for your model provider to guarantee valid JSON. After receiving the response, validate the JSON against the output contract before accepting it. The expected schema is an array of objects, each containing variable_name (string), file_path (string), line_number (number), default_value (string or null), is_required (boolean), usage_context (string), and sensitive_classification (string enum: secret, sensitive, public). Reject any response missing required fields or containing malformed entries. If validation fails, retry once with a repair prompt that includes the validation error message and the original response. If the second attempt also fails, fail the pipeline step and alert a human.

Store the validated JSON as a build artifact (e.g., env-vars-audit.json) committed to the repository or uploaded to your artifact store. For ongoing audits, diff the generated JSON against the previous run's artifact to detect newly added variables, removed variables, or changed defaults. Flag any variable where is_required changed from false to true for immediate human review, as this may indicate a breaking deployment change. Variables classified as secret should trigger a secondary check: scan the source file to confirm the value is not hardcoded. If a hardcoded secret is detected, block the pipeline and escalate.

Do not run this prompt on files containing hardcoded secrets without first redacting them. Use a pre-processing step (e.g., detect-secrets, trufflehog, or a regex-based scrubber) to mask known secret patterns before the source code reaches the LLM. The model should see REDACTED in place of actual credentials. This prevents accidental exfiltration and keeps secrets out of LLM provider logs. For high-security environments, consider running this prompt against a local model or a private deployment where data never leaves your network boundary.