Metadata-Version: 2.4
Name: envcheck-sync
Version: 0.1.0
Summary: Keep your .env.example in sync with the environment variables your code actually uses.
Project-URL: Homepage, https://github.com/gazzycodes/envcheck
Project-URL: Repository, https://github.com/gazzycodes/envcheck
Project-URL: Issues, https://github.com/gazzycodes/envcheck/issues
Author: gazzycodes
License: MIT License
        
        Copyright (c) 2026 gazzycodes
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: cli,configuration,dotenv,environment-variables,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# envcheck

[![CI](https://github.com/gazzycodes/envcheck/actions/workflows/ci.yml/badge.svg)](https://github.com/gazzycodes/envcheck/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/envcheck-sync.svg)](https://pypi.org/project/envcheck-sync/)

**Keep your `.env.example` in sync with the environment variables your code actually uses.**

New teammate clones the repo, copies `.env.example`, runs the app — and it crashes on a
`KeyError` for some variable nobody documented. `envcheck` catches that *before* it happens.
It statically scans your Python (it never imports or runs your code) for `os.getenv` /
`os.environ` access, compares the result to your example env file, and reports:

- **Undocumented** vars — used in code but missing from `.env.example` (fails CI)
- **Possibly unused** vars — in `.env.example` but never read by any code

Zero runtime dependencies, Python 3.8+, CI-friendly.

## Demo

![envcheck flagging an undocumented and an unused variable](https://raw.githubusercontent.com/gazzycodes/envcheck/main/docs/demo.gif)

> The [`examples/sample`](examples/sample) project deliberately drifts from its
> `.env.example` so you can try it immediately: `envcheck examples/sample`.

## Installation

```bash
pip install envcheck-sync
```

Or run from a checkout without installing:

```bash
PYTHONPATH=src python -m envcheck path/to/project
```

## Usage

```bash
# Scan the current directory (auto-detects .env.example, .env.sample, ...)
envcheck .

# Point at a specific example file
envcheck . --env-file config/.env.template

# Machine-readable output for tooling
envcheck . --format json
```

### Example

```text
$ envcheck examples/sample
Scanned 3 env var(s) in code against examples/sample/.env.example.

Undocumented (1 variable used in code, not in the env file):
  - JWT_SECRET  (e.g. examples/sample/app.py:9)

Possibly unused (1 variable in the env file, not read by code):
  - LEGACY_FLAG
```

`envcheck` exits non-zero when undocumented variables are found, so it drops straight into
CI or a pre-commit hook (use `--no-fail` to report without failing).

## What it detects

Static, literal-key access in these forms:

- `os.getenv("X")` and `getenv("X")`
- `os.environ.get("X")` and `environ.get("X")`
- `os.environ["X"]` and `environ["X"]`
- `os.environ.setdefault("X", ...)`

Dynamic keys (e.g. `os.getenv(some_variable)`) are intentionally ignored — `envcheck` only
reports what it can prove statically, so it never produces noisy false positives.

## How it works

1. Walk the project and parse each `.py` file with the standard-library `ast` module.
2. Collect every literal-key environment-variable access, with its file and line.
3. Parse the example env file for declared variable names.
4. Diff the two sets and report the gaps.

## Development

```bash
git clone https://github.com/gazzycodes/envcheck
cd envcheck
PYTHONPATH=src python -m unittest discover -s tests -v
```

Contributions are welcome — please open an issue or PR.

## License

MIT — see [LICENSE](LICENSE).
