Metadata-Version: 2.4
Name: dotguard-scan
Version: 0.1.0
Summary: Automatically generate documented .env.example files by scanning your codebase.
Author: dotguard contributors
License: MIT
Project-URL: Homepage, https://github.com/medahz/dotguard_v1
Keywords: env,dotenv,environment,variables,scanner,devtools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# dotguard 

<p align="center">
  <strong>Auto-generate documented .env.example files from your codebase.</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/pypi/v/dotguard-scan" />
  <img src="https://img.shields.io/pypi/pyversions/dotguard-scan" />
  <img src="https://img.shields.io/github/stars/medahz/dotguard_v1?style=social" />
</p>

<p align="center">
  <strong>Auto-generate documented .env.example files from your codebase.</strong>
</p>

Ever had a deploy fail because someone added `os.getenv("NEW_VAR")` but forgot `.env.example`?
dotguard fixes that - automatically.

**dotguard** scans your codebase and automatically generates a fully documented `.env.example` - grouped, commented, and ready to commit.

## Features

- ⚡ **Zero dependencies** — pure Python (installs in ~1s)
- 🌍 **Language agnostic** — Python, JS, TS, shell, YAML, TOML
- 🧠 **Smart grouping** — auto-groups variables by prefix
- 🔐 **Secret detection** — flags `_KEY`, `_SECRET`, `_PASSWORD`, `_TOKEN`
- 🤖 **CI-ready** — `--check` fails if `.env.example` is outdated

## Demo

![dotguard in action](demo.gif)

## Install

```bash
pip install dotguard-scan
```

## Usage

```bash
dotguard scan                    # scan current directory → .env.example
dotguard scan ./backend          # scan specific folder
dotguard scan --output prod.env  # custom output filename
dotguard scan --check            # CI mode: exit 1 if undocumented vars found
dotguard diff                    # compare .env vs .env.example, show missing keys
dotguard audit                   # show all vars, which files use them, flag secrets
```

## Quick Demo

```
🔍 Scanning ./myproject...

  ✔ 23 files scanned
  ✔ 11 environment variables found
  ⚠  3 secrets detected (SECRET_KEY, DB_PASSWORD, AUTH_TOKEN)
  ✔ .env.example written

  Variables by group:
  DATABASE  ████  3 vars
  SMTP      ██    2 vars
  APP       ████  4 vars
  SECRETS   ███   3 vars  ⚠
```

## Generated Output

dotguard produces a clean, grouped `.env.example` with comments showing where each variable is used:

```bash
# ─────────────────────────────────────
# SECRETS  ⚠️  Never commit real values
# ─────────────────────────────────────

# Used in: config.py:4
SECRET_KEY=your-secret-here

# Used in: auth.py:9
AUTH_TOKEN=your-secret-here


# ─────────────────────────────────────
# DATABASE
# ─────────────────────────────────────

# Used in: db.py:12, config.py:3
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Used in: cache.py:8
REDIS_HOST=localhost


# ─────────────────────────────────────
# APP
# ─────────────────────────────────────

# Used in: settings.py:3
DEBUG=true
```

## CI Integration

Add `dotguard scan --check` to your CI pipeline. It exits with code 1 if any environment variable in your code is missing from `.env.example`:

```yaml
# GitHub Actions example
- name: Check env docs
  run: dotguard scan --check
```

## Supported Patterns

| Pattern                     | Language   |
|-----------------------------|------------|
| `os.getenv("KEY")`          | Python     |
| `os.environ["KEY"]`         | Python     |
| `os.environ.get("KEY")`     | Python     |
| `process.env.KEY`           | JavaScript |
| `$KEY` / `${KEY}`           | Shell      |
| `getenv("KEY")`             | Generic    |

## License

Licensed under
[The MIT License](https://opensource.org/licenses/mit/).

## ⭐ Support & Contributing

If you find this project useful, consider:

- ⭐ Starring the repository
- 👤 Following me for more projects
- 🛠️ Contributing to improve the tool

Contributions are always welcome! Feel free to open issues or submit pull requests.
