envsleuth 0.1.0__tar.gz

envsleuth-0.1.0/LICENSE

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

envsleuth-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: envsleuth
+Version: 0.1.0
+Summary: Detective for env vars in Python code. Parses your source with AST, finds every os.getenv/os.environ usage, and tells you what's missing from your .env file.
+Author: k38f
+License: MIT
+Project-URL: Homepage, https://github.com/k38f/envsleuth
+Project-URL: Repository, https://github.com/k38f/envsleuth
+Project-URL: Issues, https://github.com/k38f/envsleuth/issues
+Keywords: env,dotenv,cli,static-analysis,ast,environment-variables
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: flashbar>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+# envsleuth
+
+[![tests](https://github.com/k38f/envsleuth/actions/workflows/tests.yml/badge.svg)](https://github.com/k38f/envsleuth/actions/workflows/tests.yml)
+[![pypi](https://img.shields.io/pypi/v/envsleuth.svg)](https://pypi.org/project/envsleuth/)
+[![python](https://img.shields.io/pypi/pyversions/envsleuth.svg)](https://pypi.org/project/envsleuth/)
+[![license](https://img.shields.io/pypi/l/envsleuth.svg)](LICENSE)
+
+> 🕵️  The detective for env vars in Python code. Parses your source with AST, finds every `os.getenv()` / `os.environ[]` / `os.environ.get()`, and tells you what's missing from your `.env` file.
+
+No more shipping to prod and realising you forgot `STRIPE_API_KEY`.
+
+## Install
+
+```bash
+pip install envsleuth
+```
+
+## Usage
+
+```bash
+# scan current directory, check against ./.env
+envsleuth scan
+
+# specific directory, specific env file
+envsleuth scan --path ./src --env .env.production
+
+# CI mode — exits 1 if anything is missing
+envsleuth scan --strict
+
+# generate a .env.example from your code
+envsleuth generate
+
+# machine-readable output
+envsleuth scan --json
+```
+
+### Example output
+
+```
+Found 6 variables in code
+checking against .env
+
+⚠️  AWS_SECRET — not in .env but has default in code (probably ok)
+✅ DATABASE_URL
+✅ DEBUG
+❌ REDIS_URL — missing from .env
+     at src/app.py:7
+✅ SECRET_KEY
+❌ STRIPE_API_KEY — missing from .env
+     at src/app.py:6
+
+⚠️  1 dynamic usage (variable name computed at runtime, can't check statically)
+     src/app.py:12  →  getenv(name)
+
+ℹ  1 variable in .env not referenced in code: UNUSED_VAR
+
+3 ok  1 with default  2 missing
+```
+
+## What it detects
+
+Works with all three common patterns:
+
+```python
+import os
+
+a = os.getenv("A")              # required — must be in .env
+b = os.getenv("B", "fallback")  # has default — warned but not required
+c = os.environ["C"]             # required (would raise KeyError without)
+d = os.environ.get("D")         # required
+```
+
+Also handles aliased imports:
+
+```python
+from os import getenv, environ
+import os as sys_os
+
+a = getenv("A")
+b = environ["B"]
+c = sys_os.getenv("C")
+```
+
+Variables with names computed at runtime (e.g. `os.getenv(f"PREFIX_{x}")`) can't be checked statically — they're reported in a separate warning section so you know they exist.
+
+## `envsleuth generate`
+
+Scans your code and writes a `.env.example` with every variable found, a comment pointing at where it's used, and the default value from code if there is one:
+
+```bash
+$ envsleuth generate
+Wrote 6 variables to .env.example
+
+$ cat .env.example
+# Generated by envsleuth — edit this file before committing.
+# Each variable below is used somewhere in your code.
+
+# used at src/app.py:8
+AWS_SECRET=default-value
+
+# used at src/app.py:3
+DATABASE_URL=
+
+# used at src/app.py:5
+DEBUG=false
+...
+```
+
+Use `--force` to overwrite an existing file, `--output path/to/file` to write elsewhere.
+
+## `.envignore`
+
+Exclude variables from the "missing" check with glob patterns — one per line:
+
+```
+# .envignore
+TEST_*
+LEGACY_*
+DEBUG_TOOL
+```
+
+Great for vars that come from CI, Docker, or your shell rc files rather than the local `.env`.
+
+## CI usage
+
+GitHub Actions:
+
+```yaml
+- name: Check env vars
+  run: |
+    pip install envsleuth
+    envsleuth scan --env .env.example --strict
+```
+
+pre-commit:
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: envsleuth
+      name: envsleuth
+      entry: envsleuth scan --strict
+      language: system
+      pass_filenames: false
+```
+
+## CLI reference
+
+### `envsleuth scan`
+
+| Flag | Description |
+| --- | --- |
+| `--path`, `-p` | Directory or file to scan. Default: `.` |
+| `--env` | Path to `.env` file. Default: `./.env` |
+| `--envignore` | Path to `.envignore`. Default: `./.envignore` if present |
+| `--strict` | Exit with code 1 if vars are missing |
+| `--json` | JSON output for CI pipelines |
+| `--no-color` | Disable ANSI colors (also honours `NO_COLOR` env var) |
+| `--exclude DIR` | Extra directory name to skip. Can be repeated |
+| `--ext .EXT` | Extra file extension to scan (e.g. `.pyi`). Can be repeated |
+| `--verbose`, `-v` | Show usage locations for every variable |
+
+### `envsleuth generate`
+
+| Flag | Description |
+| --- | --- |
+| `--path`, `-p` | Directory or file to scan. Default: `.` |
+| `--output`, `-o` | Where to write. Default: `./.env.example` |
+| `--force`, `-f` | Overwrite existing output file |
+| `--exclude`, `--ext` | Same as in `scan` |
+
+## How it compares
+
+| | envsleuth | [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) | [python-decouple](https://github.com/HBNetwork/python-decouple) |
+| --- | --- | --- | --- |
+| Scans your **code** for env var usages | ✅ | ❌ | ❌ |
+| Lints the **.env file itself** | ❌ | ✅ | ❌ |
+| Runtime config reader with casting | ❌ | ❌ | ✅ |
+| Generates `.env.example` from code | ✅ | ❌ | ❌ |
+| Language | Python | Rust | Python |
+
+envsleuth is the only tool here that understands your **source code**. The others either look at your `.env` file in isolation, or read env vars at runtime.
+
+## Dependencies
+
+- [click](https://click.palletsprojects.com/) — CLI
+- [python-dotenv](https://github.com/theskumar/python-dotenv) — `.env` parsing
+- [flashbar](https://github.com/k38f/flashbar) — progress bar (a tiny zero-dep lib I wrote; envsleuth uses it when scanning 20+ files)
+
+The scanner itself uses only the Python standard library (`ast`).
+
+## License
+
+MIT

envsleuth-0.1.0/README.md

@@ -0,0 +1,195 @@
+# envsleuth
+
+[![tests](https://github.com/k38f/envsleuth/actions/workflows/tests.yml/badge.svg)](https://github.com/k38f/envsleuth/actions/workflows/tests.yml)
+[![pypi](https://img.shields.io/pypi/v/envsleuth.svg)](https://pypi.org/project/envsleuth/)
+[![python](https://img.shields.io/pypi/pyversions/envsleuth.svg)](https://pypi.org/project/envsleuth/)
+[![license](https://img.shields.io/pypi/l/envsleuth.svg)](LICENSE)
+
+> 🕵️  The detective for env vars in Python code. Parses your source with AST, finds every `os.getenv()` / `os.environ[]` / `os.environ.get()`, and tells you what's missing from your `.env` file.
+
+No more shipping to prod and realising you forgot `STRIPE_API_KEY`.
+
+## Install
+
+```bash
+pip install envsleuth
+```
+
+## Usage
+
+```bash
+# scan current directory, check against ./.env
+envsleuth scan
+
+# specific directory, specific env file
+envsleuth scan --path ./src --env .env.production
+
+# CI mode — exits 1 if anything is missing
+envsleuth scan --strict
+
+# generate a .env.example from your code
+envsleuth generate
+
+# machine-readable output
+envsleuth scan --json
+```
+
+### Example output
+
+```
+Found 6 variables in code
+checking against .env
+
+⚠️  AWS_SECRET — not in .env but has default in code (probably ok)
+✅ DATABASE_URL
+✅ DEBUG
+❌ REDIS_URL — missing from .env
+     at src/app.py:7
+✅ SECRET_KEY
+❌ STRIPE_API_KEY — missing from .env
+     at src/app.py:6
+
+⚠️  1 dynamic usage (variable name computed at runtime, can't check statically)
+     src/app.py:12  →  getenv(name)
+
+ℹ  1 variable in .env not referenced in code: UNUSED_VAR
+
+3 ok  1 with default  2 missing
+```
+
+## What it detects
+
+Works with all three common patterns:
+
+```python
+import os
+
+a = os.getenv("A")              # required — must be in .env
+b = os.getenv("B", "fallback")  # has default — warned but not required
+c = os.environ["C"]             # required (would raise KeyError without)
+d = os.environ.get("D")         # required
+```
+
+Also handles aliased imports:
+
+```python
+from os import getenv, environ
+import os as sys_os
+
+a = getenv("A")
+b = environ["B"]
+c = sys_os.getenv("C")
+```
+
+Variables with names computed at runtime (e.g. `os.getenv(f"PREFIX_{x}")`) can't be checked statically — they're reported in a separate warning section so you know they exist.
+
+## `envsleuth generate`
+
+Scans your code and writes a `.env.example` with every variable found, a comment pointing at where it's used, and the default value from code if there is one:
+
+```bash
+$ envsleuth generate
+Wrote 6 variables to .env.example
+
+$ cat .env.example
+# Generated by envsleuth — edit this file before committing.
+# Each variable below is used somewhere in your code.
+
+# used at src/app.py:8
+AWS_SECRET=default-value
+
+# used at src/app.py:3
+DATABASE_URL=
+
+# used at src/app.py:5
+DEBUG=false
+...
+```
+
+Use `--force` to overwrite an existing file, `--output path/to/file` to write elsewhere.
+
+## `.envignore`
+
+Exclude variables from the "missing" check with glob patterns — one per line:
+
+```
+# .envignore
+TEST_*
+LEGACY_*
+DEBUG_TOOL
+```
+
+Great for vars that come from CI, Docker, or your shell rc files rather than the local `.env`.
+
+## CI usage
+
+GitHub Actions:
+
+```yaml
+- name: Check env vars
+  run: |
+    pip install envsleuth
+    envsleuth scan --env .env.example --strict
+```
+
+pre-commit:
+
+```yaml
+# .pre-commit-config.yaml
+- repo: local
+  hooks:
+    - id: envsleuth
+      name: envsleuth
+      entry: envsleuth scan --strict
+      language: system
+      pass_filenames: false
+```
+
+## CLI reference
+
+### `envsleuth scan`
+
+| Flag | Description |
+| --- | --- |
+| `--path`, `-p` | Directory or file to scan. Default: `.` |
+| `--env` | Path to `.env` file. Default: `./.env` |
+| `--envignore` | Path to `.envignore`. Default: `./.envignore` if present |
+| `--strict` | Exit with code 1 if vars are missing |
+| `--json` | JSON output for CI pipelines |
+| `--no-color` | Disable ANSI colors (also honours `NO_COLOR` env var) |
+| `--exclude DIR` | Extra directory name to skip. Can be repeated |
+| `--ext .EXT` | Extra file extension to scan (e.g. `.pyi`). Can be repeated |
+| `--verbose`, `-v` | Show usage locations for every variable |
+
+### `envsleuth generate`
+
+| Flag | Description |
+| --- | --- |
+| `--path`, `-p` | Directory or file to scan. Default: `.` |
+| `--output`, `-o` | Where to write. Default: `./.env.example` |
+| `--force`, `-f` | Overwrite existing output file |
+| `--exclude`, `--ext` | Same as in `scan` |
+
+## How it compares
+
+| | envsleuth | [dotenv-linter](https://github.com/dotenv-linter/dotenv-linter) | [python-decouple](https://github.com/HBNetwork/python-decouple) |
+| --- | --- | --- | --- |
+| Scans your **code** for env var usages | ✅ | ❌ | ❌ |
+| Lints the **.env file itself** | ❌ | ✅ | ❌ |
+| Runtime config reader with casting | ❌ | ❌ | ✅ |
+| Generates `.env.example` from code | ✅ | ❌ | ❌ |
+| Language | Python | Rust | Python |
+
+envsleuth is the only tool here that understands your **source code**. The others either look at your `.env` file in isolation, or read env vars at runtime.
+
+## Dependencies
+
+- [click](https://click.palletsprojects.com/) — CLI
+- [python-dotenv](https://github.com/theskumar/python-dotenv) — `.env` parsing
+- [flashbar](https://github.com/k38f/flashbar) — progress bar (a tiny zero-dep lib I wrote; envsleuth uses it when scanning 20+ files)
+
+The scanner itself uses only the Python standard library (`ast`).
+
+## License
+
+MIT

envsleuth-0.1.0/envsleuth/__init__.py

@@ -0,0 +1,3 @@
+"""envsleuth — static analyzer for environment variables in Python projects."""
+
+__version__ = "0.1.0"

envsleuth-0.1.0/envsleuth/checker.py

@@ -0,0 +1,160 @@
+"""Compare scanned env vars against an actual .env file."""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from dotenv import dotenv_values
+
+from envsleuth.scanner import EnvUsage, ScanResult
+
+
+DEFAULT_ENV_FILE = ".env"
+DEFAULT_ENVIGNORE_FILE = ".envignore"
+
+
+@dataclass
+class VarReport:
+    """Per-variable status after comparing scan results with .env."""
+
+    name: str
+    present_in_env: bool
+    has_default_in_code: bool
+    usages: List[EnvUsage] = field(default_factory=list)
+    ignored: bool = False
+
+    @property
+    def status(self) -> str:
+        """One of: 'present', 'missing', 'default', 'ignored'."""
+        if self.ignored:
+            return "ignored"
+        if self.present_in_env:
+            return "present"
+        if self.has_default_in_code:
+            return "default"
+        return "missing"
+
+
+@dataclass
+class CheckReport:
+    """Full comparison report."""
+
+    variables: List[VarReport] = field(default_factory=list)
+    dynamic_usages: List[EnvUsage] = field(default_factory=list)
+    env_file: Optional[Path] = None
+    env_file_exists: bool = False
+    extra_in_env: List[str] = field(default_factory=list)
+    ignore_patterns: List[str] = field(default_factory=list)
+    errors: List[Tuple[Path, str]] = field(default_factory=list)
+
+    @property
+    def missing(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "missing"]
+
+    @property
+    def present(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "present"]
+
+    @property
+    def with_default(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "default"]
+
+    @property
+    def ignored(self) -> List[VarReport]:
+        return [v for v in self.variables if v.status == "ignored"]
+
+    @property
+    def has_issues(self) -> bool:
+        """True if anything requires user attention (missing vars or scan errors)."""
+        return bool(self.missing) or bool(self.errors)
+
+
+# --------------------------------------------------------------------- helpers
+
+
+def load_env_file(path: Path) -> Dict[str, Optional[str]]:
+    if not path.exists():
+        return {}
+    return dict(dotenv_values(path))
+
+
+def load_ignore_patterns(path: Path) -> List[str]:
+    """Read .envignore — one glob pattern per line. Blank lines and '#' are ignored."""
+    if not path.exists():
+        return []
+    patterns: List[str] = []
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        patterns.append(line)
+    return patterns
+
+
+def _matches_any(name: str, patterns: List[str]) -> bool:
+    return any(fnmatch.fnmatchcase(name, p) for p in patterns)
+
+
+# -------------------------------------------------------------------- main api
+
+
+def check(
+    scan: ScanResult,
+    env_path: Path,
+    ignore_patterns: Optional[List[str]] = None,
+) -> CheckReport:
+    """Compare scan results against the given .env file and return a report."""
+    patterns = ignore_patterns or []
+    env_values = load_env_file(env_path)
+    env_keys = set(env_values.keys())
+
+    by_name: Dict[str, List[EnvUsage]] = {}
+    for u in scan.usages:
+        if u.name is None:
+            continue
+        by_name.setdefault(u.name, []).append(u)
+
+    variables: List[VarReport] = []
+    for name in sorted(by_name):
+        usages = by_name[name]
+        has_default = any(u.has_default for u in usages)
+        ignored = _matches_any(name, patterns)
+        variables.append(
+            VarReport(
+                name=name,
+                present_in_env=name in env_keys,
+                has_default_in_code=has_default,
+                usages=usages,
+                ignored=ignored,
+            )
+        )
+
+    code_names = set(by_name.keys())
+    extra_in_env = sorted(env_keys - code_names)
+
+    return CheckReport(
+        variables=variables,
+        dynamic_usages=scan.dynamic_usages,
+        env_file=env_path,
+        env_file_exists=env_path.exists(),
+        extra_in_env=extra_in_env,
+        ignore_patterns=patterns,
+        errors=list(scan.errors),
+    )
+
+
+def find_nearby_env_files(root: Path) -> List[Path]:
+    """Look for .env.* files in `root` to help the user when .env is missing."""
+    if not root.is_dir():
+        return []
+    candidates: List[Path] = []
+    for p in sorted(root.iterdir()):
+        if not p.is_file():
+            continue
+        name = p.name
+        if name == ".env" or name.startswith(".env."):
+            candidates.append(p)
+    return candidates