envjanitor

Env File Linter & Validator — Scan your codebase for environment variable usage and cross-reference against your .env files.

---

The Problem

90% of "works on my machine" bugs come from environment variable mismatches between dev and prod. Developers add env vars to code, forget to add them to .env.example, or remove them from .env without checking if they're still used. This causes silent failures and deployment headaches.

The Solution

envjanitor automatically detects:

1. 🔴 MISSING — Environment variables used in code but not declared in .env / .env.example
2. 🟡 UNUSED — Variables in .env that are never referenced anywhere in the codebase
3. 🔵 TYPO — Variable names that are very similar to declared ones (Levenshtein distance ≤ 2)
4. 📊 Type Inference Hints — Infers expected types from variable names and example values

---

Quick Start

# Install
pip install envjanitor

# Scan the current directory
envjanitor scan

# Scan a specific project
envjanitor scan /path/to/project

# JSON output (CI integration)
envjanitor scan --json

# Quiet mode (issues only)
envjanitor scan --quiet

Test Drive (without installing)

cd /path/to/envjanitor
pip install -e .
envjanitor scan .

---

Features

Multi-Language Support

Language	Detected Patterns
Python	os.getenv("VAR"), os.environ["VAR"], os.environ.get("VAR"), config("VAR"), env="VAR" (pydantic)
Node.js / TypeScript	process.env.VAR, process.env["VAR"], destructuring, import.meta.env.VAR (Vite)
Rust	env!("VAR"), std::env::var("VAR"), dotenvy::var
C / C++	getenv("VAR"), secure_getenv("VAR")
Go	os.Getenv("VAR")
Ruby	ENV["VAR"], ENV.fetch("VAR")
Shell	$VAR, ${VAR}

CI Integration

envjanitor scan --json --no-exit-code > env-report.json

Exit code is 1 when any 🔴 MISSING or 🔵 TYPO issues are found (use --no-exit-code to override).

Configuration

Create .envjanitor.toml in your project root:

[envjanitor]
env_file = ".env"
env_example_file = ".env.example"
exclude_dirs = ["node_modules", ".git", "__pycache__", "vendor"]
include_patterns = ["custom_getenv('{VAR}')"]
quiet = false
json_output = false

Or use pyproject.toml:

[tool.envjanitor]
exclude_dirs = ["tests", "docs"]

CLI Options

Usage: envjanitor scan [OPTIONS] [PATH]

Arguments:
  [PATH]  Directory or file to scan (default: current working directory).

Options:
  -e, --env-file TEXT          Path to .env file
  -x, --env-example TEXT       Path to .env.example file
  -X, --exclude-dirs TEXT      Directories to exclude
  -i, --include-pattern TEXT   Custom env var patterns
  -j, --json                   JSON output
  -q, --quiet                  Issues only, no summary
  --no-exit-code               Always exit 0
  -c, --config FILE            Config file path
  --help                       Show this message and exit.

---

Development

# Clone and install in editable mode
cd envjanitor
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=envjanitor --cov-report=term-missing

Project Structure

envjanitor/
├── envjanitor/
│   ├── __init__.py       # Package metadata
│   ├── __main__.py       # python -m envjanitor support
│   ├── cli.py            # CLI entry point (Typer)
│   ├── scanner.py        # Code scanning (AST + regex)
│   ├── parser.py         # .env file parsing
│   ├── checker.py        # Cross-referencing & typo detection
│   ├── reporter.py       # Terminal (Rich) & JSON output
│   └── config.py         # Config file loading (TOML)
├── tests/
│   ├── test_parser.py
│   ├── test_scanner.py
│   └── test_checker.py
├── pyproject.toml        # PEP 621 packaging
├── README.md
└── LICENSE

---

License

MIT — see LICENSE.

Built by AFS Agentics.