env-auditor 0.2.0__tar.gz

env_auditor-0.2.0/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+.venv/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment files
+.env
+.env.local
+.env.production
+.env.staging
+config.ini

env_auditor-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SemTiOne
+
+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.

env_auditor-0.2.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: env-auditor
+Version: 0.2.0
+Summary: Audit environment variable consistency across a codebase.
+Project-URL: Homepage, https://github.com/SemTiOne/env-auditor
+Project-URL: Issues, https://github.com/SemTiOne/env-auditor/issues
+License: MIT License
+        
+        Copyright (c) 2026 SemTiOne
+        
+        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: audit,cli,devtools,dotenv,env
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# env-auditor
+
+[![CI](https://github.com/SemTiOne/env-auditor/actions/workflows/ci.yml/badge.svg)](https://github.com/SemTiOne/env-auditor/actions)
+[![PyPI](https://img.shields.io/pypi/v/env-auditor.svg)](https://pypi.org/project/env-auditor/)
+[![Python](https://img.shields.io/pypi/pyversions/env-auditor.svg)](https://pypi.org/project/env-auditor/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Audit environment variable consistency across your codebase.** Finds vars used in code but missing from `.env.example`, stale vars nobody references anymore, and required vars with no default value — in any language.
+
+```
+$ env-auditor .
+
+env-auditor — environment variable audit
+──────────────────────────────────────────
+
+✗  3 undocumented variables (in code, missing from .env.example)
+   DATABASE_URL          src/db/connection.py:14
+   STRIPE_WEBHOOK_SECRET src/payments/webhook.py:8, src/payments/webhook.py:31
+   REDIS_URL             src/cache.py:22
+
+⚠  2 stale variables (in .env.example, not found in code)
+   OLD_PAYMENT_KEY
+   DEPRECATED_FEATURE_FLAG
+
+○  2 variables with no default value (empty in .env.example)
+   SECRET_KEY
+   JWT_SECRET
+
+⚡  1 dynamic reference (runtime key construction — cannot audit statically)
+   src/config/loader.py:45  →  process.env[configKey]
+
+──────────────────────────────────────────
+Result: FAIL  (exit code 1)
+```
+
+## Why
+
+Your `.env.example` is a contract. It tells new contributors what the app needs to run. Over time that contract drifts: someone adds `process.env.NEW_KEY` to the source and forgets to document it, or removes a feature but leaves the stale key rotting in `.env.example`. `env-auditor` catches both automatically, in CI, before it becomes someone else's debugging session.
+
+## Installation
+
+```bash
+pip install env-auditor
+```
+
+Requires Python 3.10+. **Zero runtime dependencies** — pure stdlib.
+
+## Usage
+
+```bash
+# Audit current directory against .env.example (default)
+env-auditor
+
+# Audit a specific project
+env-auditor /path/to/project
+
+# Use a different env file
+env-auditor --env .env.production
+
+# Multiple env files (keys merged — union)
+env-auditor --env .env.example --env .env.staging
+
+# Strict mode: fail on stale vars too
+env-auditor --strict
+
+# JSON output for tooling / dashboards
+env-auditor --format json | jq .undocumented
+
+# Suppress specific sections
+env-auditor --ignore-stale --ignore-missing
+
+# Exclude extra directories
+env-auditor --exclude vendor --exclude third_party
+```
+
+## Config file
+
+Commit a `.env-auditorrc` at your project root to persist settings for your whole team:
+
+```toml
+# .env-auditorrc
+env_files = [".env.example", ".env.staging"]
+exclude_dirs = ["vendor", "third_party"]
+ignore_stale = false
+strict = true
+ignore_keys = ["CI", "HOME", "USER"]
+required_keys = ["DATABASE_URL", "SECRET_KEY"]
+```
+
+Or add it to `pyproject.toml` under `[tool.env-auditor]`:
+
+```toml
+[tool.env-auditor]
+env_files = [".env.example"]
+strict = true
+ignore_keys = ["CI"]
+```
+
+CLI flags always override config file values.
+
+`ignore_keys` excludes specific variable names from every category (undocumented, stale, missing values, required). `required_keys` is the inverse: names that must appear in at least one env file, always reported as a failure if absent, whether or not they're referenced in code (useful for infra-only vars like `DATABASE_URL` that no source file ever touches directly).
+
+## Supported languages
+
+| Language | Detected patterns |
+|---|---|
+| JavaScript / TypeScript | `process.env.VAR`, `process.env['VAR']`, `process.env["VAR"]` |
+| Python | `os.environ['VAR']`, `os.environ.get('VAR')`, `os.getenv('VAR')` |
+| Go | `os.Getenv("VAR")`, `os.LookupEnv("VAR")` |
+| Shell | `$VAR`, `${VAR}` (`.sh`, `.bash`, `.zsh` only) |
+| Docker | `ENV VAR`, `ARG VAR` in Dockerfiles |
+| Ruby | `ENV['VAR']`, `ENV["VAR"]`, `ENV.fetch('VAR')` |
+
+Dynamic references like `process.env[someVariable]` are flagged separately — they can't be statically audited.
+
+## CLI reference
+
+| Flag | Description | Default |
+|---|---|---|
+| `PATH` | Root directory to scan | `.` |
+| `--env FILE` | Env file(s) as source of truth. Repeatable. | `.env.example` |
+| `--config FILE` | Path to config file | auto-discover `.env-auditorrc` |
+| `--ignore-stale` | Suppress stale variable report | off |
+| `--ignore-missing` | Suppress empty-value report | off |
+| `--format [text\|json]` | Output format | `text` |
+| `--no-color` | Disable ANSI colors | off |
+| `--exclude DIR` | Extra directories to skip. Repeatable. | — |
+| `--strict` | Exit 1 on stale vars too | off |
+| `--version` | Show version and exit | — |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean |
+| `1` | Undocumented vars found, stale vars with `--strict`, or missing `required_keys` |
+| `2` | Tool error — bad args, missing files, etc. |
+
+## CI integration
+
+Block deploys when env vars drift:
+
+```yaml
+# .github/workflows/deploy.yml
+jobs:
+  env-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install env-auditor
+      - run: env-auditor --strict
+```
+
+Save the report as a CI artifact:
+
+```yaml
+- run: env-auditor --format json > env-auditor-report.json || true
+- uses: actions/upload-artifact@v4
+  with:
+    name: env-auditor-report
+    path: env-auditor-report.json
+```
+
+For monorepos, run per-service:
+
+```yaml
+- run: env-auditor services/api --env services/api/.env.example
+- run: env-auditor services/worker --env services/worker/.env.example
+```
+
+## Security
+
+- Symlinks are never followed
+- Files over 1 MB are skipped (with a warning)
+- Lines over 2000 characters are skipped (ReDoS protection)
+- `--exclude` paths are validated to be within the scan root — path traversal rejected
+- Actual `.env` values are never stored, logged, or printed — only key names
+- No network calls, no telemetry, entirely local
+
+## Development
+
+```bash
+git clone https://github.com/SemTiOne/env-auditor
+cd env-auditor
+pip install -e .
+pip install pytest pytest-cov
+pytest --cov=env_auditor --cov-report=term-missing
+```
+
+## License
+
+MIT

env_auditor-0.2.0/README.md

@@ -0,0 +1,194 @@
+# env-auditor
+
+[![CI](https://github.com/SemTiOne/env-auditor/actions/workflows/ci.yml/badge.svg)](https://github.com/SemTiOne/env-auditor/actions)
+[![PyPI](https://img.shields.io/pypi/v/env-auditor.svg)](https://pypi.org/project/env-auditor/)
+[![Python](https://img.shields.io/pypi/pyversions/env-auditor.svg)](https://pypi.org/project/env-auditor/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Audit environment variable consistency across your codebase.** Finds vars used in code but missing from `.env.example`, stale vars nobody references anymore, and required vars with no default value — in any language.
+
+```
+$ env-auditor .
+
+env-auditor — environment variable audit
+──────────────────────────────────────────
+
+✗  3 undocumented variables (in code, missing from .env.example)
+   DATABASE_URL          src/db/connection.py:14
+   STRIPE_WEBHOOK_SECRET src/payments/webhook.py:8, src/payments/webhook.py:31
+   REDIS_URL             src/cache.py:22
+
+⚠  2 stale variables (in .env.example, not found in code)
+   OLD_PAYMENT_KEY
+   DEPRECATED_FEATURE_FLAG
+
+○  2 variables with no default value (empty in .env.example)
+   SECRET_KEY
+   JWT_SECRET
+
+⚡  1 dynamic reference (runtime key construction — cannot audit statically)
+   src/config/loader.py:45  →  process.env[configKey]
+
+──────────────────────────────────────────
+Result: FAIL  (exit code 1)
+```
+
+## Why
+
+Your `.env.example` is a contract. It tells new contributors what the app needs to run. Over time that contract drifts: someone adds `process.env.NEW_KEY` to the source and forgets to document it, or removes a feature but leaves the stale key rotting in `.env.example`. `env-auditor` catches both automatically, in CI, before it becomes someone else's debugging session.
+
+## Installation
+
+```bash
+pip install env-auditor
+```
+
+Requires Python 3.10+. **Zero runtime dependencies** — pure stdlib.
+
+## Usage
+
+```bash
+# Audit current directory against .env.example (default)
+env-auditor
+
+# Audit a specific project
+env-auditor /path/to/project
+
+# Use a different env file
+env-auditor --env .env.production
+
+# Multiple env files (keys merged — union)
+env-auditor --env .env.example --env .env.staging
+
+# Strict mode: fail on stale vars too
+env-auditor --strict
+
+# JSON output for tooling / dashboards
+env-auditor --format json | jq .undocumented
+
+# Suppress specific sections
+env-auditor --ignore-stale --ignore-missing
+
+# Exclude extra directories
+env-auditor --exclude vendor --exclude third_party
+```
+
+## Config file
+
+Commit a `.env-auditorrc` at your project root to persist settings for your whole team:
+
+```toml
+# .env-auditorrc
+env_files = [".env.example", ".env.staging"]
+exclude_dirs = ["vendor", "third_party"]
+ignore_stale = false
+strict = true
+ignore_keys = ["CI", "HOME", "USER"]
+required_keys = ["DATABASE_URL", "SECRET_KEY"]
+```
+
+Or add it to `pyproject.toml` under `[tool.env-auditor]`:
+
+```toml
+[tool.env-auditor]
+env_files = [".env.example"]
+strict = true
+ignore_keys = ["CI"]
+```
+
+CLI flags always override config file values.
+
+`ignore_keys` excludes specific variable names from every category (undocumented, stale, missing values, required). `required_keys` is the inverse: names that must appear in at least one env file, always reported as a failure if absent, whether or not they're referenced in code (useful for infra-only vars like `DATABASE_URL` that no source file ever touches directly).
+
+## Supported languages
+
+| Language | Detected patterns |
+|---|---|
+| JavaScript / TypeScript | `process.env.VAR`, `process.env['VAR']`, `process.env["VAR"]` |
+| Python | `os.environ['VAR']`, `os.environ.get('VAR')`, `os.getenv('VAR')` |
+| Go | `os.Getenv("VAR")`, `os.LookupEnv("VAR")` |
+| Shell | `$VAR`, `${VAR}` (`.sh`, `.bash`, `.zsh` only) |
+| Docker | `ENV VAR`, `ARG VAR` in Dockerfiles |
+| Ruby | `ENV['VAR']`, `ENV["VAR"]`, `ENV.fetch('VAR')` |
+
+Dynamic references like `process.env[someVariable]` are flagged separately — they can't be statically audited.
+
+## CLI reference
+
+| Flag | Description | Default |
+|---|---|---|
+| `PATH` | Root directory to scan | `.` |
+| `--env FILE` | Env file(s) as source of truth. Repeatable. | `.env.example` |
+| `--config FILE` | Path to config file | auto-discover `.env-auditorrc` |
+| `--ignore-stale` | Suppress stale variable report | off |
+| `--ignore-missing` | Suppress empty-value report | off |
+| `--format [text\|json]` | Output format | `text` |
+| `--no-color` | Disable ANSI colors | off |
+| `--exclude DIR` | Extra directories to skip. Repeatable. | — |
+| `--strict` | Exit 1 on stale vars too | off |
+| `--version` | Show version and exit | — |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean |
+| `1` | Undocumented vars found, stale vars with `--strict`, or missing `required_keys` |
+| `2` | Tool error — bad args, missing files, etc. |
+
+## CI integration
+
+Block deploys when env vars drift:
+
+```yaml
+# .github/workflows/deploy.yml
+jobs:
+  env-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install env-auditor
+      - run: env-auditor --strict
+```
+
+Save the report as a CI artifact:
+
+```yaml
+- run: env-auditor --format json > env-auditor-report.json || true
+- uses: actions/upload-artifact@v4
+  with:
+    name: env-auditor-report
+    path: env-auditor-report.json
+```
+
+For monorepos, run per-service:
+
+```yaml
+- run: env-auditor services/api --env services/api/.env.example
+- run: env-auditor services/worker --env services/worker/.env.example
+```
+
+## Security
+
+- Symlinks are never followed
+- Files over 1 MB are skipped (with a warning)
+- Lines over 2000 characters are skipped (ReDoS protection)
+- `--exclude` paths are validated to be within the scan root — path traversal rejected
+- Actual `.env` values are never stored, logged, or printed — only key names
+- No network calls, no telemetry, entirely local
+
+## Development
+
+```bash
+git clone https://github.com/SemTiOne/env-auditor
+cd env-auditor
+pip install -e .
+pip install pytest pytest-cov
+pytest --cov=env_auditor --cov-report=term-missing
+```
+
+## License
+
+MIT

env_auditor-0.2.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "env-auditor"
+version = "0.2.0"
+description = "Audit environment variable consistency across a codebase."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+keywords = ["cli", "env", "dotenv", "devtools", "audit"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Utilities",
+]
+
+# No runtime dependencies — stdlib only.
+dependencies = []
+
+[project.scripts]
+env-auditor = "env_auditor.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/SemTiOne/env-auditor"
+Issues = "https://github.com/SemTiOne/env-auditor/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/env_auditor"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/",
+  "tests/",
+  "README.md",
+  "pyproject.toml",
+]
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Dev / test dependencies
+# ──────────────────────────────────────────────────────────────────────────────
+
+[tool.hatch.envs.default]
+dependencies = [
+  "pytest>=7.4",
+  "pytest-cov>=4.1",
+]
+
+[tool.hatch.envs.default.scripts]
+test = "pytest --cov=env_auditor --cov-report=term-missing {args}"
+test-ci = "pytest --cov=env_auditor --cov-report=term-missing --cov-fail-under=85 {args}"
+
+# ──────────────────────────────────────────────────────────────────────────────
+# pytest configuration
+# ──────────────────────────────────────────────────────────────────────────────
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Coverage configuration
+# ──────────────────────────────────────────────────────────────────────────────
+
+[tool.coverage.run]
+source = ["env_auditor"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "if TYPE_CHECKING:",
+  "if __name__ == .__main__.:",
+  "raise NotImplementedError",
+]
+show_missing = true

env_auditor-0.2.0/src/env_auditor/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__: str = version("env-auditor")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0-dev"
+
+__all__ = ["__version__"]

env_auditor-0.2.0/src/env_auditor/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from env_auditor.cli import main
+
+if __name__ == "__main__":
+    main()