Detector: Stale Env

Detector: Stale Env

Detects drift between .env.example documentation and actual environment variable usage in code.

Property	Value
Name	stale-env
Tier	DETERMINISTIC
Languages	Python, JavaScript/TypeScript
External tool	None
LLM required	No
Confidence	0.75–0.80

What it detects

Two types of env config drift:

1. Stale documentation: Variables documented in .env.example but never referenced in source code
2. Missing documentation: Variables used in code (os.environ, os.getenv, process.env) but not documented in .env.example

How it works

1. Reads .env.example, .env.sample, or .env.template
2. Extracts documented variable names
3. Scans Python source for os.environ/os.getenv patterns
4. Scans JS/TS source for process.env patterns
5. Cross-references documented vs. used variables

Common variable allowlist

~30 common system/runtime variables are automatically excluded: PATH, HOME, USER, NODE_ENV, CI, GITHUB_TOKEN, DOCKER_HOST, TZ, etc.

Severity

Type	Severity
Used but undocumented	MEDIUM
Documented but unused	LOW

Example finding

[STALE-ENV] .env.example:5 — REDIS_URL
  Documented in .env.example but never referenced in source code
  Severity: LOW, Confidence: 0.80

Best for

Web applications (Next.js, Express, Django, Flask) that use .env.example files to document required configuration. Less useful for libraries.

Known limitations

• Only detects env vars accessed via standard patterns (os.environ, process.env)
• Does not detect vars loaded by dotenv libraries indirectly
• Requires a .env.example (or .env.sample/.env.template) to exist